diff --git a/.changeset/pass-through-add-mcp-setup.md b/.changeset/pass-through-add-mcp-setup.md
new file mode 100644
index 00000000..c9f11155
--- /dev/null
+++ b/.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.
diff --git a/.changeset/tidy-code-mode-token-burden.md b/.changeset/tidy-code-mode-token-burden.md
new file mode 100644
index 00000000..5ce32ac0
--- /dev/null
+++ b/.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.
diff --git a/CONTEXT.md b/CONTEXT.md
index 7518e71b..23925365 100644
--- a/CONTEXT.md
+++ b/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
diff --git a/PRODUCT.md b/PRODUCT.md
index 59663aad..26f4caaa 100644
--- a/PRODUCT.md
+++ b/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
diff --git a/README.md b/README.md
index 2828293d..15d94bd7 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,8 @@
Caplets
- Give your agent capabilities, not giant tool walls.
- Caplets wraps MCP servers, APIs, and commands behind focused capability cards.
+ Give your coding agent the whole stack.
+ The capability layer for coding agents.
@@ -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.` 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.`
+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 ` 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:
diff --git a/STRATEGY.md b/STRATEGY.md
index 44807c72..a94275eb 100644
--- a/STRATEGY.md
+++ b/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.
diff --git a/apps/catalog/src/pages/caplets/[entryKey].astro b/apps/catalog/src/pages/caplets/[entryKey].astro
index acc0b804..7688b333 100644
--- a/apps/catalog/src/pages/caplets/[entryKey].astro
+++ b/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;
---
-
- {entry ? `${entry.name} - Caplets Catalog` : "Caplet unavailable"}
-
+ {pageTitle} — Caplets Catalog
+
+
+
+
+
+
+
+
+
diff --git a/apps/catalog/src/pages/index.astro b/apps/catalog/src/pages/index.astro
index 4a4b6c4e..fcac7432 100644
--- a/apps/catalog/src/pages/index.astro
+++ b/apps/catalog/src/pages/index.astro
@@ -17,10 +17,23 @@ const entries = await listCatalogEntries(getCatalogEnv());
- Caplets Catalog
+ Shared Caplets — Caplets Catalog
+
+
+
+
+
+
+
@@ -29,10 +42,17 @@ const entries = await listCatalogEntries(getCatalogEnv());
Skip to results
-
- Not security-reviewed.
- Inspect Caplets before installing.
+
+
The capability layer for coding agents
+
Find a capability. Make it yours.
+
+ Search reusable Caplet definitions and operating guidance. The catalog is one distribution channel—not the boundary of what Caplets can connect.
+
+
diff --git a/apps/catalog/src/styles/catalog.css b/apps/catalog/src/styles/catalog.css
index 6a2b32e8..a309f8e4 100644
--- a/apps/catalog/src/styles/catalog.css
+++ b/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;
diff --git a/apps/docs/src/content/docs/agent-integrations.mdx b/apps/docs/src/content/docs/agent-integrations.mdx
index 64a57ca6..e761dcd2 100644
--- a/apps/docs/src/content/docs/agent-integrations.mdx
+++ b/apps/docs/src/content/docs/agent-integrations.mdx
@@ -1,6 +1,6 @@
---
title: Agent Integrations
-description: Use Caplets with Codex, Claude, OpenCode, and Pi.
+description: Use Caplets with add-mcp clients, OpenCode, and Pi.
---
Caplets works with Codex, Claude, OpenCode, Pi, and other MCP clients. Code Mode is the
@@ -103,12 +103,16 @@ CAPLETS_MODE=remote CAPLETS_REMOTE_URL=https://caplets.example.com pi
## Other MCP clients
-Use the `add-mcp` client catalog through Caplets setup:
+Pass any stdio-capable client ID from the `add-mcp` catalog directly to Caplets setup:
```sh
-caplets setup mcp-client --client
+caplets setup
```
+Run `caplets setup` without an ID to see detected clients first and all supported clients after
+them. Use the arrow keys to move, Space to select each integration, and Enter to run setup once.
+OpenCode and Pi are special cases: their IDs install the native Caplets integrations.
+
If you write config manually, keep the agent as a thin daemon client:
```json
diff --git a/apps/docs/src/content/docs/index.mdx b/apps/docs/src/content/docs/index.mdx
index 2e973900..f24a4dc7 100644
--- a/apps/docs/src/content/docs/index.mdx
+++ b/apps/docs/src/content/docs/index.mdx
@@ -1,14 +1,18 @@
---
title: Caplets
-description: Give coding agents Code Mode capabilities without a giant tool wall.
+description: Give your coding agent the whole stack through reusable, controlled Caplets.
---
-Caplets wraps MCP servers, APIs, and commands into focused capabilities for coding agents.
-Code Mode is the default surface: each configured backend becomes a typed caplets.<id>
-handle that an agent can inspect, search, call, filter, and summarize in one workflow.
+Caplets is the capability layer for coding agents. Turn MCP servers, OpenAPI and Google
+Discovery APIs, GraphQL endpoints, simple HTTP actions, and curated CLI commands into
+reusable Caplets your agent can use across the work surrounding your code.
-Use Caplets with Codex, Claude, OpenCode, Pi, or any MCP client that can launch a local
-stdio server.
+Your Whole Stack is the set of capabilities you intentionally expose through Caplets—not
+blanket access to every system or credential. Caplet definitions can be reused across
+Codex, Claude, OpenCode, Pi, and supported MCP clients while each host independently
+supplies and authorizes access.
+
+Code Mode is the default surface: each configured Caplet becomes a typed `caplets.` handle that an agent can inspect, search, call, filter, and summarize in one workflow. Direct and progressive exposure remain available for clients and tasks that need them.
> **Required upgrade migration:** If this host ran `caplets@0.25.x` or earlier, do not
> start `caplets@0.26.0` or later until you complete the
diff --git a/apps/docs/src/content/docs/install.mdx b/apps/docs/src/content/docs/install.mdx
index abdfa2bd..c18a99f3 100644
--- a/apps/docs/src/content/docs/install.mdx
+++ b/apps/docs/src/content/docs/install.mdx
@@ -134,7 +134,7 @@ and configures `caplets attach ` after the daemon is healthy.
explicit client target, run:
```sh
-caplets setup mcp-client --client codex
+caplets setup codex
```
If you need to write a config by hand, keep it daemon-backed and secret-free:
diff --git a/apps/docs/src/content/docs/reference/code-mode-api.mdx b/apps/docs/src/content/docs/reference/code-mode-api.mdx
index a67cbf34..c2a24739 100644
--- a/apps/docs/src/content/docs/reference/code-mode-api.mdx
+++ b/apps/docs/src/content/docs/reference/code-mode-api.mdx
@@ -133,13 +133,18 @@ interface CapletHandle {
inspect(): Promise>;
/** Check backend readiness/auth; expected unavailable states return ok:false. */
check(): Promise>;
- /** List tool summaries for the discovery pass; may be empty. */
+ /** List compact tool summaries; safe callTemplate hints can be used later in this program. */
tools(input?: PageInput): Promise>;
- /** Search tool summaries for the discovery pass; may be empty. */
+ /** Search compact summaries; continue from a safe callTemplate before returning when no schema details are needed. */
searchTools(query: string, input?: PageInput): Promise>;
/** Get schema, callSignature, types, examples; prefer outputSchema/outputTypeScript over observed hints. */
describeTool(name: string): Promise>;
- /** Call one tool; expected failures return ok:false. Filter bulky data in script before returning. */
+ /** After searchTools, pass its callTemplate here with placeholder overrides in the same program. */
+ callTool(
+ template: ToolCallTemplate,
+ overrides?: Record,
+ ): Promise>;
+ /** Call one exact tool name; expected failures return ok:false. Filter bulky data before returning. */
callTool(name: string, args?: unknown): Promise>;
/** List readable resources for the discovery pass; many backends expose none. */
resources(input?: PageInput): Promise>;
@@ -217,6 +222,13 @@ type ToolSummary = {
readOnlyHint?: boolean;
/** True when the tool declares that it may perform destructive writes. */
destructiveHint?: boolean;
+ /** Required and accepted argument names, when the downstream schema declares them. */
+ requiredArgs?: string[];
+ acceptedArgs?: string[];
+ /** Safe placeholders for simple calls; replace placeholders before calling. */
+ argsTemplate?: Record;
+ /** A simple call skeleton emitted only when required arguments can be represented safely. */
+ callTemplate?: ToolCallTemplate;
};
```
diff --git a/apps/landing/src/components/landing/Activation.astro b/apps/landing/src/components/landing/Activation.astro
index 7392baf3..6a9713af 100644
--- a/apps/landing/src/components/landing/Activation.astro
+++ b/apps/landing/src/components/landing/Activation.astro
@@ -1,5 +1,7 @@
---
import ArrowUpRight from "@tabler/icons/outline/arrow-up-right.svg";
+import Check from "@tabler/icons/outline/check.svg";
+import Copy from "@tabler/icons/outline/copy.svg";
import Terminal from "@tabler/icons/outline/terminal-2.svg";
import { Badge } from "@/components/starwind/badge";
@@ -7,93 +9,102 @@ import { Button } from "@/components/starwind/button";
import { Card, CardContent } from "@/components/starwind/card";
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/starwind/tabs";
-import { exampleCaplets } from "../../data/landing";
+import {
+ agentSetupPrompt,
+ firstCaplet,
+ manualSetupCommand,
+ manualSetupCommands,
+} from "../../data/landing";
+
+const setupOptions = [
+ {
+ label: "Manual",
+ copyLabel: "manual setup commands",
+ copyValue: manualSetupCommand,
+ copyAttribution: true,
+ lines: [manualSetupCommands.install, manualSetupCommands.setup],
+ },
+ {
+ label: "Agent",
+ copyLabel: "agent setup prompt",
+ copyValue: agentSetupPrompt,
+ copyAttribution: false,
+ lines: ["Read bootstrap skill", "detect -> ask -> plan -> approve"],
+ },
+] as const;
---
-
-
-
First Caplet
-
- Start where auth cannot get in the way.
+
+
+
+ Get one real result.
- Copy setup from the hero, then add OSV first because it needs no auth. Bring in GitHub or Sourcegraph after the discovery path feels right.
+ Set up Caplets and run OSV. No authentication required.
Give your agent capabilities, not giant tool walls.
+
Give your coding agent the whole stack.
- Install the CLI, wire up your agent, browse the catalog, or read the benchmark method behind the launch claim.
+ Connect your first capability, reuse a shared Caplet, or inspect the benchmark behind the smaller tool surface.