refactor: reposition Caplets around whole-stack agent capabilities

.changeset/pass-through-add-mcp-setup.md

@@ -0,0 +1,5 @@
+---
+"@caplets/core": patch
+---
+
+Accept every stdio-capable add-mcp client ID directly in `caplets setup`, with one keyboard multi-select pass for interactive setup, while keeping OpenCode and Pi on their native integration paths.

.changeset/tidy-code-mode-token-burden.md

@@ -0,0 +1,5 @@
+---
+"@caplets/core": patch
+---
+
+Reduce Code Mode token overhead with actionable discovery call templates, compact generated guidance, and model-facing successful envelopes that preserve session, recovery, logging, diagnostics, and full error details.

CONTEXT.md

@@ -1,9 +1,41 @@
 # Caplets
 
-Caplets is a capability gateway for coding agents. This glossary names the product concepts used when describing Caplet configuration and runtime behavior.
+Caplets is a capability layer for coding agents. This glossary names the product concepts used when describing Caplet configuration and runtime behavior.
 
 ## Language
 
+**Caplet**:
+A reusable capability surface for coding agents that exposes intentionally selected backend functionality. A Caplet can be kept local, reused across supported agent environments, or shared without transferring credentials.
+_Avoid_: Connector, integration listing, tool bundle
+
+**Capability Layer**:
+The product category for Caplets: a shared intermediary that turns heterogeneous backends into intentionally exposed, reusable capabilities for coding agents.
+_Avoid_: Agent integration platform, tool aggregator, capability marketplace
+
+**Whole Stack**:
+The set of backend capabilities a user intentionally makes available to a coding agent through Caplets. It describes potential breadth across the agent's work, not unrestricted authority or the current contents of the Prebuilt Caplets Catalog.
+_Avoid_: Unrestricted agent access, every credential by default, prebuilt catalog coverage
+
+**Capability Sharing**:
+The transfer of a reusable Caplet definition and its operating guidance without transferring credentials or authenticated authority. Each receiving user or host supplies and authorizes its own access.
+_Avoid_: Credential sharing, connection cloning, inherited authority
+
+**Capability Composition**:
+An agent's task-specific selection and combination of Caplets across backend systems. The agent determines the path from the current task rather than following a predefined human-authored automation.
+_Avoid_: Workflow builder, fixed integration pipeline, automation recipe
+
+**Agent Portability**:
+The ability to reuse the same Caplet definitions across supported coding-agent environments without redefining their backend capabilities. Agent-specific surfaces may differ, and credentials remain independently authorized.
+_Avoid_: Identical client experience, automatic credential portability, universal client parity
+
+**First Caplet Execution**:
+The first successful backend operation executed through a configured Caplet. It proves that the initial capability works, but it is not Caplet Activation.
+_Avoid_: Caplet Activation, install conversion, setup completion
+
+**Caplet Activation**:
+A completed First Caplet Execution followed by connecting a capability from the user's own stack. A website interaction, catalog view, installation, setup completion, or first execution alone is not activation.
+_Avoid_: First Caplet Execution, install conversion, setup completion, first page view
+
 **Code Mode**:
 A Caplets exposure surface where configured backends appear as typed handles inside a bounded script workflow.
 _Avoid_: JavaScript shell, Node REPL, sandbox boundary

PRODUCT.md

@@ -6,11 +6,19 @@ product
 
 ## Users
 
-Caplets serves developers working with coding agents and tool ecosystems. The primary audience is split between agent power users who run many MCP servers, APIs, and local tools, and tool builders who package focused capability domains for agents or teams. Users are usually in a technical workflow: configuring integrations, inspecting available capabilities, debugging setup, or helping an agent choose the right tool without flooding context.
+Caplets primarily serves agent power users who want their coding agent to work across the systems surrounding the repository. Teams are the expansion audience: they standardize and distribute approved Caplets. Tool builders and community authors are the ecosystem audience: they package reusable capability definitions for others. Users are usually connecting backends, authorizing access, reusing Caplets across supported agents, or inspecting exactly what a capability exposes.
 
 ## Product Purpose
 
-Caplets turns sprawling tool stacks into focused capability cards for coding agents. It exists to reduce context bloat, improve tool discovery, preserve downstream capability fidelity, and make heterogeneous backends feel like one coherent progressive-disclosure interface. Success looks like agents choosing the right capability quickly, users trusting what is exposed and hidden, and builders being able to package tools without writing bespoke agent integration code.
+Caplets is the capability layer for coding agents. It turns heterogeneous MCP servers, APIs, and commands into intentionally exposed, reusable Caplets that agents can select and combine for the task at hand. Success means an agent can carry work across the user's authorized stack, the same Caplet definitions can be reused without transferring credentials, and Code Mode keeps the resulting decision surface focused without reducing backend fidelity.
+
+## Positioning
+
+**Category:** The capability layer for coding agents.
+
+**Promise:** Give your coding agent the whole stack.
+
+**Meaning:** Whole Stack is the set of backend capabilities a user intentionally exposes through Caplets—not blanket authority, inherited credentials, or the current contents of the public catalog. Connection breadth is the primary proof; agent portability and capability sharing are the supporting promises; Code Mode efficiency and benchmarked token reduction are technical evidence.
 
 ## Brand Personality
 

README.md

@@ -4,8 +4,8 @@
   <h1>Caplets</h1>
 
   <p>
-    <strong>Give your agent capabilities, not giant tool walls.</strong><br />
-    Caplets wraps MCP servers, APIs, and commands behind focused capability cards.
+    <strong>Give your coding agent the whole stack.</strong><br />
+    The capability layer for coding agents.
   </p>
 
   <p>
@@ -25,20 +25,26 @@
 
 ---
 
-Caplets gives coding agents a Code Mode surface for MCP servers, APIs, and commands. Instead
-of exposing every downstream operation as a giant tool list, each backend becomes a typed
-`caplets.<id>` handle the agent can inspect, search, call, filter, join, and summarize inside
-one compact workflow.
+Caplets turns MCP servers, APIs, and commands into reusable capabilities your coding agent
+can use from issue to production. You choose what each agent can access. A Caplet definition
+can stay local, work across supported agent environments, or be shared without transferring
+credentials or authenticated authority.
 
-Progressive discovery is still available when you want visible wrapper tools, but Code Mode is
-the default exposure for configured backends.
+Code Mode is the default exposure: each configured backend becomes a typed `caplets.<id>`
+handle the agent can inspect, search, call, filter, join, and summarize inside one compact
+workflow. Progressive and direct exposure remain available when a client or task needs them.
 
 Caplets can wrap:
 
 - MCP servers
-- OpenAPI, GraphQL, and simple HTTP APIs
+- OpenAPI APIs
+- Google Discovery APIs
+- GraphQL and simple HTTP APIs
 - Curated repository CLI commands
-- Shared Caplet files from this repo's `caplets/` catalog
+- Shared Caplet Files from the public catalog or another source
+
+The catalog is a discovery and distribution channel, not the boundary of what Caplets can
+connect. Each receiving host supplies and authorizes its own access.
 
 ## Quick Start
 
@@ -164,11 +170,11 @@ configures the selected agent as a thin attach/native client. This avoids relyin
 each MCP client to inherit the same shell environment as your terminal; backend
 execution happens in the Caplets daemon instead.
 
-| Agent                                     | Recommended local setup                                                                                                     |
-| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| Codex, Claude Code, and other MCP clients | `caplets setup` or `caplets setup mcp-client --client codex` for an explicit add-mcp client target                          |
-| OpenCode                                  | `caplets setup opencode` or [`@caplets/opencode`](https://github.com/spiritledsoftware/caplets/tree/main/packages/opencode) |
-| Pi                                        | `caplets setup pi` or [`@caplets/pi`](https://github.com/spiritledsoftware/caplets/tree/main/packages/pi)                   |
+| Agent           | Recommended local setup                                                                                                     |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Add-mcp clients | `caplets setup` or `caplets setup <client-id>` for an explicit client target                                                |
+| OpenCode        | `caplets setup opencode` or [`@caplets/opencode`](https://github.com/spiritledsoftware/caplets/tree/main/packages/opencode) |
+| Pi              | `caplets setup pi` or [`@caplets/pi`](https://github.com/spiritledsoftware/caplets/tree/main/packages/pi)                   |
 
 For MCP clients, setup uses the `add-mcp` client catalog under the hood and writes a
 Caplets server command shaped like this:

STRATEGY.md

@@ -1,24 +1,27 @@
 ---
 name: Caplets
-last_updated: 2026-06-17
+last_updated: 2026-07-26
 ---
 
 # Caplets Strategy
 
 ## Target problem
 
-Coding agents get slower, more expensive, and less reliable when real backend surfaces are exposed as flat tool lists: large MCP/API setups flood context with hundreds of operations, create duplicate generic names, and force repeated model/tool round trips for discovery, schema inspection, execution, and synthesis. The hard part is preserving exact backend power, auth state, schemas, resources, prompts, results, and errors across local, remote, Cloud, and native agent setups without making the agent reason over the whole tool wall up front.
+Coding agents stop where the repository ends. Users become the human integration layer: they carry issue context into the agent, inspect dashboards themselves, trigger operations, and update external systems after the code changes. Connecting more systems can then overwhelm the agent with flat tool lists, giant schemas, repeated auth setup, and extra model/tool round trips. The hard part is giving an agent broad, reusable capability access while preserving exact backend semantics and deliberate user control.
 
 ## Our approach
 
-Caplets wins by being a Code Mode-first capability layer for coding agents, not a general tool catalog. It turns heterogeneous backends into typed, scoped handles so agents can discover, inspect, execute, filter, and summarize with a small decision surface, while preserving exact backend semantics and keeping auth, direct I/O, and project-local context behind Caplet-controlled boundaries.
+Caplets wins by being the capability layer for coding agents. It turns heterogeneous MCP servers, APIs, commands, and shared Caplet Files into intentionally exposed, reusable capabilities that an agent can select and combine for the current task. Code Mode is the default mechanism for keeping that Whole Stack focused: typed, scoped handles preserve backend fidelity while auth, direct I/O, and project-local context remain behind Caplet-controlled boundaries.
 
 ## Who it's for
 
-**Primary:** Agent power-users/builders - They're hiring Caplets to turn sprawling MCP/API/CLI surfaces into typed capabilities their coding agents can inspect, call, filter, and synthesize without a giant tool wall.
+**Primary:** Individual agent power users who want their coding agent to work across the systems surrounding the repository. **Expansion:** Teams that standardize and distribute approved Caplets. **Ecosystem:** Tool builders and community authors who publish reusable capability definitions.
 
 ## Key metrics
 
+- **First Caplet execution** - The first successful backend operation executed through a configured Caplet. Landing clicks, catalog views, installation, and setup completion are funnel diagnostics, not execution.
+- **Caplet Activation** - A first successful Caplet execution followed by connecting a capability from the user's own stack. Activation and retention cohorts use this complete milestone.
+- **Whole Stack retention** - Repeat successful Caplet executions across backend families after Caplet Activation, indicating that users expanded into personally relevant work.
 - **Initial tool surface compression** - Reduction in initially visible tools, serialized payload bytes, approximate context tokens, and duplicate top-level names versus direct flat MCP; measured by `pnpm benchmark:check`.
 - **Code Mode workflow efficiency** - Reduction in model/tool round trips, external calls, and payload tokens while preserving required evidence fields; measured by deterministic Code Mode benchmark fixtures.
 - **Live task parity at lower token cost** - Live eval pass rate must match baselines before claiming token efficiency, then compare request+output tokens and tool-surface tokens.
@@ -62,6 +65,12 @@ _Why it serves the approach:_ Caplets asks users to trust a smaller visible surf
 
 ## Marketing
 
-**One-liner:** Give your agent capabilities, not giant tool walls.
+**Category:** The capability layer for coding agents.
 
-**Key message:** Caplets turns MCP servers, APIs, and commands into focused capability handles for compact coding-agent workflows. The proof point is not just that Caplets connects to more backends; it is that agents can complete real multi-step backend work with a smaller decision surface, fewer round trips, and claims that are checked against reproducible benchmarks.
+**One-liner / headline:** Give your coding agent the whole stack.
+
+**Profile description:** Turn MCP servers, APIs, and commands into reusable Caplets your coding agent can use across the work. You control access.
+
+**Key message:** Caplets connects coding agents to intentionally exposed capabilities across the user's stack. A Caplet is reusable across supported agent environments and can be shared without transferring credentials. Agents compose Caplets for the task instead of requiring a fixed automation workflow. Code Mode tool-surface compression, fewer round trips, and benchmarked token reduction are technical proof—not the primary promise.
+
+**Launch sequence:** Whole Stack promise → “MCP. APIs. Commands. All of it.” → human integration-layer problem → capability composition → agent portability → “Share capabilities, not secrets.” → issue-to-production example → Code Mode evidence → first Caplet activation.

apps/catalog/src/pages/caplets/[entryKey].astro

@@ -15,20 +15,33 @@ const entry = entryKey ? await getCatalogEntry(entryKey, getCatalogEnv()) : unde
 if (!entry) {
   Astro.response.status = 404;
 }
+const pageTitle = entry ? `${entry.name} — Shared Caplet` : "Caplet unavailable";
+const pageDescription = entry
+  ? `${entry.description} Inspect this shared Caplet before installing, then authorize access on your host.`
+  : "This shared Caplet is unavailable or no longer indexed.";
+if (!Astro.site) {
+  throw new Error("Catalog site URL is not configured.");
+}
+const canonicalUrl = new URL(
+  entry ? `/caplets/${encodeURIComponent(entry.entryKey)}/` : "/caplets/",
+  Astro.site,
+).href;
 ---
-
 <!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>{entry ? `${entry.name} - Caplets Catalog` : "Caplet unavailable"}</title>
-    <meta
-      name="description"
-      content={entry
-        ? entry.description
-        : "This catalog entry is unavailable, suppressed, or no longer indexed."}
-    />
+    <title>{pageTitle} — Caplets Catalog</title>
+    <link rel="canonical" href={canonicalUrl} />
+    <meta name="description" content={pageDescription} />
+    <meta property="og:title" content={`${pageTitle} — Caplets Catalog`} />
+    <meta property="og:description" content={pageDescription} />
+    <meta property="og:type" content="website" />
+    <meta property="og:url" content={canonicalUrl} />
+    <meta name="twitter:card" content="summary" />
+    <meta name="twitter:title" content={`${pageTitle} — Caplets Catalog`} />
+    <meta name="twitter:description" content={pageDescription} />
     <ThemeInit />
     <link rel="icon" type="image/png" href="/icon.png" />
   </head>

apps/catalog/src/pages/index.astro

@@ -17,10 +17,23 @@ const entries = await listCatalogEntries(getCatalogEnv());
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Caplets Catalog</title>
+    <title>Shared Caplets — Caplets Catalog</title>
     <meta
       name="description"
-      content="Search official and community Caplets, inspect source content, and copy supported install commands."
+      content="Find reusable Caplet definitions for coding agents. Inspect every source before installing, then authorize access on your own host."
+    />
+    <meta property="og:title" content="Shared Caplets — Caplets Catalog" />
+    <meta
+      property="og:description"
+      content="Find reusable Caplet definitions for coding agents. Share capabilities without sharing credentials."
+    />
+    <meta property="og:type" content="website" />
+    <meta property="og:url" content="https://catalog.caplets.dev/" />
+    <meta name="twitter:card" content="summary" />
+    <meta name="twitter:title" content="Shared Caplets — Caplets Catalog" />
+    <meta
+      name="twitter:description"
+      content="Find reusable Caplet definitions for coding agents. Share capabilities without sharing credentials."
     />
     <ThemeInit />
     <link rel="icon" type="image/png" href="/icon.png" />
@@ -29,10 +42,17 @@ const entries = await listCatalogEntries(getCatalogEnv());
     <a class="skip-link" href="#catalog-results">Skip to results</a>
     <CatalogHeader search={{ count: entries.length, value: Astro.url.searchParams.get("q") ?? "" }} />
     <main class="mx-auto w-[min(1180px,calc(100vw_-_2rem))] py-4 max-sm:w-[min(1180px,calc(100vw_-_1.25rem))] max-sm:py-3">
-      <section class="catalog-intro" role="note">
-        <strong>Not security-reviewed.</strong>
-        <span>Inspect Caplets before installing.</span>
+      <section class="catalog-positioning" aria-labelledby="catalog-title">
+        <p>The capability layer for coding agents</p>
+        <h1 id="catalog-title">Find a capability. Make it yours.</h1>
+        <span>
+          Search reusable Caplet definitions and operating guidance. The catalog is one distribution channel—not the boundary of what Caplets can connect.
+        </span>
       </section>
+      <aside class="catalog-intro" role="note">
+        <strong>Not security-reviewed.</strong>
+        <span>Inspect every Caplet before installing. Credentials and access never transfer with a shared Caplet.</span>
+      </aside>
       <div id="catalog-results">
         <SearchShell entries={entries} />
       </div>

apps/catalog/src/styles/catalog.css

@@ -75,6 +75,36 @@
   padding: 0.875rem;
 }
 
+.catalog-positioning {
+  display: grid;
+  max-width: 52rem;
+  gap: 0.65rem;
+  margin: 1.5rem 0 1.25rem;
+}
+
+.catalog-positioning p {
+  color: var(--accent);
+  font-size: 0.875rem;
+  font-weight: 650;
+}
+
+.catalog-positioning h1 {
+  color: var(--foreground);
+  font-size: 2rem;
+  font-weight: 650;
+  line-height: 1.15;
+  letter-spacing: -0.03em;
+  text-wrap: balance;
+}
+
+.catalog-positioning span {
+  max-width: 68ch;
+  color: var(--muted-foreground);
+  font-size: 1rem;
+  line-height: 1.65;
+  text-wrap: pretty;
+}
+
 .catalog-intro {
   display: flex;
   flex-wrap: wrap;