diff --git a/.changeset/bright-walls-refresh.md b/.changeset/bright-walls-refresh.md
new file mode 100644
index 00000000..03a40b0c
--- /dev/null
+++ b/.changeset/bright-walls-refresh.md
@@ -0,0 +1,8 @@
+---
+"@caplets/core": patch
+"@caplets/opencode": patch
+"@caplets/pi": patch
+"caplets": patch
+---
+
+Refresh expired downstream OAuth/OIDC tokens before calling MCP, OpenAPI, GraphQL, and HTTP backends, persisting rotated credentials when providers return them.
diff --git a/.codex/config.toml b/.codex/config.toml
new file mode 100644
index 00000000..a3721b56
--- /dev/null
+++ b/.codex/config.toml
@@ -0,0 +1,7 @@
+[mcp_servers.caplets-local]
+command = "node"
+args = ["./packages/cli/dist/index.js", "serve", "--transport", "stdio"]
+env_vars = ["GH_TOKEN"]
+
+[mcp_servers.caplets-local.env]
+CAPLETS_MODE = "local"
diff --git a/AGENTS.md b/AGENTS.md
index 4ae49cf3..ecdca696 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,13 +13,13 @@
 ## Package Map
 
 - `packages/core` is the runtime/library source: config parsing, schema generation, MCP/OpenAPI/GraphQL/HTTP/CLI backends, native service exports.
-- `packages/cli` publishes the `caplets` binary and delegates almost all behavior to `@caplets/core`; `serve`/no arg starts the stdio MCP server.
+- `packages/cli` publishes the `caplets` binary and delegates almost all behavior to `@caplets/core`; `caplets serve` starts the MCP server, while no args print help.
 - `packages/opencode` and `packages/pi` are native agent integrations that wrap `@caplets/core/native`; keep integration-specific schema/adapter code there.
 - `packages/benchmarks` owns deterministic and opt-in live coding-agent benchmarks; deterministic benchmark docs are generated from `pnpm benchmark`.
 
 ## Generated And Checked Files
 
-- Put design specs in `docs/specs/`, implementation plans in `docs/plans/`, and product requirements documents in `docs/product/`; do not use `docs/superpowers/` in this repo.
+- Source code is the source of truth. Keep long-lived product docs in `docs/product/`, architecture docs in `docs/`, and ADRs in `docs/adr/`. Avoid committing short-lived implementation plans or design specs unless explicitly requested; if they are needed, put them in `docs/plans/` or `docs/specs/` and delete or repurpose them once they are superseded. Do not use `docs/superpowers/` in this repo.
 - Config schema source of truth is Zod in `packages/core/src/config.ts`; update `schemas/caplets-config.schema.json` with `pnpm schema:generate` and verify with `pnpm schema:check`.
 - Code Mode runtime API declaration source of truth is `packages/core/src/code-mode/runtime-api.d.ts`; update `packages/core/src/code-mode/runtime-api.generated.ts` with `pnpm code-mode:generate-api` and verify with `pnpm code-mode:check-api`.
 - `pnpm benchmark` updates `docs/benchmarks/coding-agent.md`; `pnpm benchmark:check` fails if the committed report is stale.
@@ -28,7 +28,7 @@
 ## Config And Runtime Gotchas
 
 - Default user config path is resolved by core; tests commonly override with `CAPLETS_CONFIG`.
-- Project config lives at `.caplets/config.json` and executable project config is intentionally restricted unless `CAPLETS_TRUST_PROJECT_CAPLETS` is enabled.
+- Project config lives at `.caplets/config.json`; project Markdown Caplet files load by default, while executable backend maps in project config are intentionally rejected.
 - Runtime config reload keeps the last known-good config on parse/validation errors; do not change this behavior without updating reload tests.
 - Caplet tool names come from configured server IDs and expose progressive discovery operations (`get_caplet`, `list_tools`/`search_tools`, `get_tool`, `call_tool`) rather than flattening downstream tools.
 
diff --git a/README.md b/README.md
index 2bc1c8a3..304eb475 100644
--- a/README.md
+++ b/README.md
@@ -1,61 +1,57 @@
 <div align="center">
-  <img src="docs/assets/caplets-icon.png" alt="Caplets logo" width="140" height="140" />
+  <img src="docs/assets/caplets-icon.png" alt="Caplets logo" width="120" height="120" />
 
   <h1>Caplets</h1>
 
   <p>
-    <strong>Give your agent capabilities, not tools.</strong><br />
-    Turn MCP servers, APIs, and commands into focused agent capabilities.
+    <strong>Give your agent capabilities, not giant tool walls.</strong><br />
+    Caplets wraps MCP servers, APIs, and commands behind focused capability cards.
   </p>
 
   <p>
     <a href="https://www.npmjs.com/package/caplets"><img alt="npm" src="https://img.shields.io/npm/v/caplets?style=flat-square&color=E0582F" /></a>
     <a href="https://github.com/spiritledsoftware/caplets/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/spiritledsoftware/caplets/ci.yml?branch=main&style=flat-square&label=ci&color=E0582F" /></a>
     <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-F6E8C8?style=flat-square&labelColor=1F2018" /></a>
-    <img alt="Node 24+" src="https://img.shields.io/badge/node-%3E%3D24-F6E8C8?style=flat-square&labelColor=1F2018" />
   </p>
 
   <p>
     <a href="https://caplets.dev"><strong>caplets.dev</strong></a>
   </p>
-
-  <p>
-    <code>MCP</code> · <code>OpenAPI</code> · <code>GraphQL</code> · <code>HTTP</code> · <code>CLI</code>
-  </p>
 </div>
 
 ---
 
-Caplets turns MCP servers, APIs, and commands into focused agent capabilities: one card first, searchable tools next, inspectable schemas before calls, and preserved results after.
+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.
 
-Stop dumping every operation into context up front. Caplets wraps each tool source as a capability an agent can discover, inspect, call, and recover from one step at a time. Instead of exposing a giant flat wall of operations, Caplets shows a compact capability card with source, status, and next actions. The agent chooses a domain first, then uses scoped operations like `search_tools`, `describe_tool`, and `call_tool` only when it needs more detail.
+Progressive discovery is still available when you want visible wrapper tools, but Code Mode is
+the default exposure for configured backends.
 
-For MCP-backed Caplets, the scoped operation set also includes resource discovery and reading, prompt listing and rendering, resource-template discovery, and completion for prompt or template arguments. Non-MCP backends expose focused tool and action operations.
+Caplets can wrap:
 
-## Try the aha moment
+- MCP servers
+- OpenAPI, GraphQL, and simple HTTP APIs
+- Curated repository CLI commands
+- Shared Caplet files from this repo's `caplets/` catalog
 
-Install Caplets, add Context7, and watch your agent see one capability before it searches downstream tools.
+## Quick Start
+
+Install the CLI and wire it into your agent:
 
 ```sh
 npm install -g caplets
-caplets init
-caplets add mcp context7 --command npx --arg -y --arg @upstash/context7-mcp
-caplets serve
+caplets setup
 ```
 
-In the deterministic benchmark, 106 flat tools became 3 top-level capabilities with an 87.9% smaller initial payload. Your agent starts with `context7`, then drills in through `inspect`, `search_tools`, `describe_tool`, and `call_tool` only when needed.
-
-## Quick Start
-
-Caplets requires Node.js 24 or newer.
+Install a no-auth example Caplet and try it from your agent:
 
 ```sh
-npm install -g caplets
-caplets init
-caplets serve
+caplets install spiritledsoftware/caplets osv
 ```
 
-Connect Caplets to any MCP client:
+Or add Caplets manually to any MCP client:
 
 ```json
 {
@@ -68,86 +64,53 @@ Connect Caplets to any MCP client:
 }
 ```
 
-Ask your agent to use Caplets. It will see a compact capability list first, then inspect only the backend it needs.
+## Use Caplets
 
-Add capabilities from existing systems when you are ready to give agents a focused tool surface:
+Add your own capability sources:
 
 ```sh
-# Wrap an MCP server
 caplets add mcp docs --command npx --arg -y --arg @upstash/context7-mcp
-
-# Convert useful repository commands into curated tools
+caplets add openapi users --spec ./openapi.json --base-url https://api.example.com
+caplets add graphql catalog --endpoint-url https://api.example.com/graphql --schema ./schema.graphql
+caplets add http status-api --base-url https://api.example.com --action get_status:GET:/status/{service}
 caplets add cli repo-tools --repo . --include git,gh,package
-
-# Install ready-made Caplets from a repository
-caplets install spiritledsoftware/caplets github linear context7
 ```
 
-Configured Caplets can be invoked directly from the CLI for agent-friendly scripts and smoke tests:
+Inspect and call them from the CLI:
 
 ```sh
-caplets inspect context7
-caplets list-tools context7
-caplets get-tool context7 resolve-library-id
-caplets call-tool context7 resolve-library-id --args '{"libraryName":"react"}'
-caplets call-tool context7 resolve-library-id --args '{"libraryName":"react"}' --field result.id --format json
-caplets list-resources docs
-caplets read-resource docs file:///repo/README.md
-caplets list-prompts linear
-caplets get-prompt linear review_issue --args '{"issueId":"CAP-123"}'
-caplets complete docs --resource-template 'file:///repo/{path}' --argument path --value src/
+caplets list
+caplets inspect osv
+caplets search-tools osv vulnerability
+caplets get-tool osv query_package_version
+caplets call-tool osv query_package_version --args '{"name":"react","ecosystem":"npm","version":"18.2.0"}'
 ```
 
-The older qualified form, such as `caplets call-tool context7.resolve-library-id` or `caplets get-prompt linear.review_issue`, remains supported for scripts and existing usage.
-
-Direct CLI operation commands print Markdown summaries by default. Add `--format plain` for plain text or `--format json` for machine-readable JSON (`md` is accepted as an alias for `markdown`). If a downstream tool returns `isError: true`, Caplets still exits with status code 1.
+MCP-backed Caplets also support resources, resource templates, prompts, and argument
+completion. Direct CLI commands print Markdown by default; pass `--format json` for
+machine-readable output. In agent sessions, Code Mode keeps the same operations behind typed
+handles so discovery, execution, filtering, and synthesis can happen in one call.
 
-### Shell completions
+## Agent Surfaces
 
-The npm package ships shell completion generators for Bash, Zsh, Fish, PowerShell, and cmd. Installation is explicit: `npm install -g caplets` does not modify shell startup files or system completion directories.
-
-```sh
-# Bash
-mkdir -p ~/.local/share/bash-completion/completions
-caplets completion bash > ~/.local/share/bash-completion/completions/caplets
+Caplets works as a regular MCP server through `caplets serve`. By default, that server exposes
+Code Mode for the configured backends. Caplets also has native integrations for agents that can
+load packages directly:
 
-# Zsh
-mkdir -p ~/.zsh/completions
-caplets completion zsh > ~/.zsh/completions/_caplets
-# Ensure ~/.zsh/completions is on fpath before compinit, then reload your shell:
-# echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
-# echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
+| Agent                                     | Setup                                                                                           |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Codex, Claude Code, and other MCP clients | `caplets setup` or `caplets serve`                                                              |
+| OpenCode                                  | [`@caplets/opencode`](https://github.com/spiritledsoftware/caplets/tree/main/packages/opencode) |
+| Pi                                        | [`@caplets/pi`](https://github.com/spiritledsoftware/caplets/tree/main/packages/pi)             |
 
-# Fish
-mkdir -p ~/.config/fish/completions
-caplets completion fish > ~/.config/fish/completions/caplets.fish
+`caplets setup` uses each harness's MCP configuration command:
 
-# PowerShell
-caplets completion powershell | Out-String | Invoke-Expression
-
-# cmd.exe
-caplets completion cmd > %USERPROFILE%\caplets-completion.cmd
-%USERPROFILE%\caplets-completion.cmd
+```sh
+codex mcp add caplets -- caplets serve
+claude mcp add --transport stdio --scope user caplets -- caplets serve
 ```
 
-Completions include command names, options, common enum values, configured Caplet IDs, and cache-backed downstream names for split targets such as `caplets call-tool repo <TAB>` and qualified targets such as `caplets call-tool repo.<TAB>`. Downstream discovery is bounded by the `completion` config timeouts and a platform-native cache directory. Generated shell scripts suppress completion stderr; run the underlying CLI command directly when debugging completion behavior.
-
-Backends that require OAuth or token auth may need `caplets auth login <server>` before live downstream completions can return richer results. Completion never starts interactive login flows.
-
-## Agent Integrations
-
-Use Caplets as a normal MCP server everywhere, or install a native agent integration when
-your coding agent supports one.
-
-| Agent          | Install                                                        | What It Provides                                                |
-| -------------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
-| Any MCP client | Add `caplets serve` or `caplets attach` manually in MCP config | Universal Code Mode gateway; progressive exposure is opt-in     |
-| Claude Code    | Add `caplets serve` or `caplets attach` manually in MCP config | Local or remote/Cloud Code Mode gateway                         |
-| Codex          | Add `caplets serve` or `caplets attach` manually in MCP config | Local or remote/Cloud Code Mode gateway                         |
-| OpenCode       | Install [`@caplets/opencode`](packages/opencode/README.md)     | Native `caplets__<id>` tools and prompt guidance hooks          |
-| Pi             | Install [`@caplets/pi`](packages/pi/README.md)                 | Native `caplets__<id>` tools with Pi prompt snippets/guidelines |
-
-Codex local MCP config (`~/.codex/config.toml`):
+Equivalent local Codex config:
 
 ```toml
 [mcp_servers.caplets]
@@ -155,20 +118,7 @@ command = "caplets"
 args = ["serve"]
 ```
 
-Claude Code or generic JSON MCP config:
-
-```json
-{
-  "mcpServers": {
-    "caplets": {
-      "command": "caplets",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-Codex remote or Cloud MCP config (`~/.codex/config.toml`):
+For a remote or Cloud-backed MCP server, point the client at `caplets attach` instead:
 
 ```toml
 [mcp_servers.caplets]
@@ -176,8 +126,6 @@ command = "caplets"
 args = ["attach"]
 ```
 
-Claude Code or generic JSON remote or Cloud MCP config:
-
 ```json
 {
   "mcpServers": {
@@ -189,1112 +137,78 @@ Claude Code or generic JSON remote or Cloud MCP config:
 }
 ```
 
-For Caplets Cloud, authenticate once and set the remote selection environment for the agent:
-
-```sh
-caplets cloud auth login
-export CAPLETS_MODE=cloud
-export CAPLETS_REMOTE_URL=https://cloud.caplets.dev
-```
+Native integrations expose `caplets__code_mode` for multi-step TypeScript workflows over
+generated `caplets.<id>` handles. Progressive exposure adds `caplets__<id>` tools; direct
+exposure adds operation-level tools such as `caplets__<id>__<operation>`.
 
-For a self-hosted remote:
+Remote mode is available with `caplets attach`, self-hosted HTTP service settings, or
+Caplets Cloud auth:
 
 ```sh
 export CAPLETS_MODE=remote
 export CAPLETS_REMOTE_URL=https://caplets.example.com/caplets
 export CAPLETS_REMOTE_TOKEN=...
-```
-
-## Core Alchemy
-
-Core Alchemy deploys the public landing page from `apps/landing`. It does not deploy the private Cloud Worker or Cloud dashboard; those belong to the nested Cloud repository.
-
-### Remote Caplets service
-
-OpenCode and Pi can use native `caplets__<id>` tools backed by a remote Caplets HTTP service. Codex, Claude Code, and any MCP client can connect to the same remote MCP endpoint directly.
-
-Hosted Caplets Cloud uses browser-mediated Cloud Auth:
-
-```sh
-caplets cloud auth login --workspace personal
-caplets cloud auth status
-caplets cloud auth workspaces
-caplets cloud auth switch team
-caplets cloud auth logout
-```
-
-Cloud Auth stores one Selected Workspace locally. `caplets attach --workspace <workspace>` must match that saved workspace; switch explicitly before attaching another hosted workspace. Self-hosted remotes continue to use `CAPLETS_REMOTE_URL`, `CAPLETS_REMOTE_TOKEN`, or Basic Auth credentials.
-
-Access tokens are short-lived. The CLI refreshes expired hosted credentials before attach, persists the rotated refresh token returned by Cloud, and treats revoked refresh credentials as a fresh-login requirement. `caplets cloud auth logout` clears local credentials; Cloud logout revokes the refresh credential family so rotated refresh tokens stop working together.
 
-Use `caplets attach --once` for a finite Project Binding smoke test, or `caplets attach` to run a remote-backed MCP server over stdio or HTTP with Project Binding and local overlay.
-
-Start a local HTTP service. `--path` is the service base path; Caplets mounts MCP,
-control, and health endpoints underneath it:
-
-```sh
-CAPLETS_SERVER_URL=http://127.0.0.1:5387/caplets \
-CAPLETS_SERVER_PASSWORD=... \
-caplets serve --transport http
-```
-
-With `CAPLETS_SERVER_URL=http://127.0.0.1:5387/caplets`, the derived endpoints are:
-
-- MCP: `http://127.0.0.1:5387/caplets/mcp`
-- Control: `http://127.0.0.1:5387/caplets/control`
-- Health: `http://127.0.0.1:5387/caplets/healthz`
-
-`caplets serve --transport http` serves plain HTTP. For non-loopback or network access, expose it only through HTTPS/TLS (for example, a reverse proxy or secure tunnel) and enable Basic Auth; Basic Auth over plain HTTP exposes credentials. Keep credentials out of plugin manifests.
-
-#### Docker Compose self-hosting
-
-This repository includes a source-build Docker image and Compose service for running the HTTP service from the checked-out source tree:
-
-```sh
-CAPLETS_SERVER_PASSWORD=change-me docker compose up --build
-```
-
-By default, Compose publishes the service on loopback only:
-
-- Base URL: `http://127.0.0.1:5387`
-- MCP endpoint: `http://127.0.0.1:5387/mcp`
-- Control endpoint: `http://127.0.0.1:5387/control`
-- Health endpoint: `http://127.0.0.1:5387/healthz`
-
-The service stores Caplets config and auth state in a Docker named volume mounted at `/data`. To use a host-visible bind mount instead, replace this Compose volume entry:
-
-```yaml
-volumes:
-  - caplets-data:/data
-```
-
-with:
-
-```yaml
-volumes:
-  - ./data:/data
-```
-
-To expose the service to a LAN interface or reverse proxy, set an explicit bind address and public base URL:
-
-```sh
-CAPLETS_BIND_ADDRESS=0.0.0.0 \
-CAPLETS_SERVER_URL=https://caplets.example.com \
-CAPLETS_SERVER_PASSWORD=change-me \
-docker compose up --build
-```
-
-Only expose Caplets beyond loopback through HTTPS/TLS and Basic Auth. `CAPLETS_SERVER_PASSWORD` protects both the MCP and control endpoints; downstream provider tokens and auth files remain server-owned inside the mounted `/data` location.
-
-Native integrations and remote-capable CLI commands read remote client settings from environment variables:
-
-```sh
-CAPLETS_MODE=remote \
-CAPLETS_SERVER_URL=https://caplets.example.com/caplets \
-CAPLETS_SERVER_USER=caplets \
-CAPLETS_SERVER_PASSWORD=... \
-opencode
+caplets cloud auth login
+CAPLETS_MODE=cloud CAPLETS_REMOTE_URL=https://cloud.caplets.dev opencode
 ```
 
-For MCP-backed Codex or Claude Code configs, point the agent's MCP server entry at the derived `/mcp` URL using that agent's supported HTTP MCP configuration. If Basic Auth is needed, use the agent's secure secret or environment interpolation mechanism rather than hardcoding credentials.
-
-In `CAPLETS_MODE=remote`, read and execute commands use a merged Caplets view. Remote server rows load first, user-global local Caplets overlay them, and project-local Caplets have the highest priority. A local Caplet with the same ID shadows the remote one, runs locally, and prints a warning such as `Warning: project Caplet shared shadows remote Caplet`; remote-only IDs continue through remote control.
-
-Local overlays in remote mode are best-effort. Invalid local config sources warn and are ignored while remaining valid layers still load; invalid Caplet files warn and are skipped individually. For sibling file layouts, `foo/CAPLET.md` wins over `foo.md` and warns that `foo.md` was shadowed; if the winning `CAPLET.md` is invalid, that local ID is skipped instead of falling back to `foo.md`.
-
-Mutating commands do not automatically write to the server just because remote mode is active. `caplets init`, `caplets add ...`, and `caplets install ...` write project-local by default, `--project` is the explicit project-local target, `--global` writes user-global local files, and `--remote` sends the mutation to the remote Caplets server. Target flags are mutually exclusive.
-
-## Convert Existing Tooling
-
-Caplets is designed to convert what you already use into agent-friendly capability domains.
-
-| Existing source          | Command                                                                                                          |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| Local MCP server         | `caplets add mcp local-tools --command node --arg ./server.mjs`                                                  |
-| Remote MCP server        | `caplets add mcp remote-tools --url https://mcp.example.com/mcp --transport http --token-env MCP_TOKEN`          |
-| OpenAPI service          | `caplets add openapi users --spec ./openapi.json --base-url https://api.example.com --token-env USERS_API_TOKEN` |
-| GraphQL endpoint         | `caplets add graphql catalog --endpoint-url https://api.example.com/graphql --schema ./schema.graphql`           |
-| Simple HTTP API          | `caplets add http status-api --base-url https://api.example.com --action get_status:GET:/status/{service}`       |
-| Repository CLI workflows | `caplets add cli repo-tools --repo . --include git,gh,package`                                                   |
-| Shared Caplet catalog    | `caplets install spiritledsoftware/caplets github linear context7`                                               |
-
-Generated Caplet files are written to `./.caplets` by default so teams can review,
-version, and customize them with the project.
-
-## Why It Matters
-
-Flat tool lists make agents guess before they understand. If every downstream server exposes every operation up front, the model starts with a noisy list, duplicate tool names, and a larger context surface before it knows which capability matters.
-
-Caplets turns that flat wall into a staged path:
-
-1. **Choose** a capability, such as `GitHub`.
-2. **Inspect** matching operations with `search_tools` or `tools`.
-3. **Resolve** the exact schema with `describe_tool`.
-4. **Invoke** with `call_tool` while preserving downstream content, structured data, and error state.
-
-A backend enters agent context as a focused card with source, status, and next actions, not a wall of operations.
-
 ## Benchmark
 
-Caplets reduces the tool surface an agent has to carry while preserving access to the
-same downstream operations.
-
-In Caplets' deterministic coding-agent benchmark, the same seven mock MCP servers are
-exposed two ways: direct flat MCP aggregation versus Caplets progressive disclosure.
-
-| Initial Agent Surface     |   Direct Flat MCP |      Caplets |     Reduction |
-| ------------------------- | ----------------: | -----------: | ------------: |
-| Visible tools             |               215 |            7 |   96.7% fewer |
-| Serialized MCP payload    |      63,250 bytes | 12,720 bytes | 79.9% smaller |
-| Approx. context surface   |     15,813 tokens | 3,180 tokens |  12,633 fewer |
-| Top-level name collisions | 3 duplicate names |            0 |    eliminated |
-
-Caplets does not remove access to downstream tools. It places them behind scoped
-discovery operations, so the agent sees less up front while retaining access to the same
-capabilities when needed.
-
-In a live Pi eval on a real-world large MCP stack, Caplets Code Mode completed the same
-10/10 tasks as direct MCP and Executor while using far fewer total tokens. The stack used
-GitHub, Context7, DeepWiki, Git, filesystem, Playwright, ast-grep, language-server, and
-web-search MCP servers. The run used `openai-codex/gpt-5.5` as both the main model and
-judge model, with 2 runs per task per mode.
-
-| Mode                            | Tasks Passed | Avg request + output tokens | Avg provider tokens |
-| ------------------------------- | -----------: | --------------------------: | ------------------: |
-| Caplets Code Mode               |        10/10 |                     236,803 |             126,877 |
-| Caplets progressive + Code Mode |        10/10 |                     422,861 |             264,624 |
-| Caplets progressive             |        10/10 |                     461,171 |             294,217 |
-| Executor MCP                    |        10/10 |                     675,842 |             369,992 |
-| Direct vanilla MCP              |        10/10 |                     846,048 |             544,121 |
-
-Against the same pass-rate baseline, Caplets Code Mode used 72.0% fewer request+output
-tokens than direct vanilla MCP and 65.0% fewer than Executor MCP. Caplets progressive
-disclosure also beat direct vanilla MCP by 45.5% and Executor MCP by 31.8% on
-request+output tokens.
-
-Live results depend on local agent CLIs, credentials, model/provider behavior, and the
-date of the run. The deterministic surface benchmark remains the reproducible,
-credential-free claim; the live eval demonstrates the same trend in a realistic large
-MCP harness.
-
-See [`docs/benchmarks/coding-agent.md`](docs/benchmarks/coding-agent.md) for methodology,
-limitations, and reproduction commands.
-
-```sh
-pnpm benchmark
-pnpm benchmark:check
-pnpm build
-CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:pi-eval -- --task-suite mcp-real-world-large --mode caplets-code-mode,caplets-progressive,vanilla-mcp,executor-mcp --model openai-codex/gpt-5.5 --runs 2
-```
-
-## Design Model
-
-Caplets combines two ideas that work well separately but leave a gap together: agent skills and MCP servers.
-
-Agent skills are great at progressive disclosure. They show an agent a compact capability card first, then let it read deeper instructions only when that skill is relevant. MCP servers are great at live tool execution, but most clients expose their tools as one flat list up front. That means a powerful MCP setup can flood the agent with every tool from every server before it knows which capability area matters.
-
-Caplets borrows the skill-shaped discovery model and applies it to MCP, OpenAPI, GraphQL, HTTP, and CLI backends. Each backend becomes a skill-like capability card first; its actual operations stay hidden until the agent chooses that capability and asks to search, list, inspect, or call them.
-
-A capability is safe for agents when it reveals itself in stages:
-
-- **Discoverable as one capability:** source, status, auth posture, and next actions are visible before any downstream tool list enters context.
-- **Inspectable before invocation:** agents search inside the selected capability, then inspect exact tool schemas before any call is made.
-- **Lossless after the call:** Caplets preserves structured content, resource links, images, and downstream error state instead of flattening results away.
-
-## Trust Before Invocation
-
-Caplets keeps trust mechanics visible before an agent calls a backend.
-
-| Mechanic | Example                            | Why it matters                                                                  |
-| -------- | ---------------------------------- | ------------------------------------------------------------------------------- |
-| Source   | `.caplets/config.json`             | Users can see where the capability came from before trusting it.                |
-| Auth     | `GITHUB_TOKEN: redacted`           | Secrets stay hidden while auth state remains inspectable.                       |
-| Timeout  | `30s boundary`                     | Slow or stuck backends fail visibly instead of disappearing into agent context. |
-| Error    | `safe message + raw detail scoped` | Recovery information stays useful without leaking sensitive configuration.      |
-
-If a backend fails, Caplets keeps the error scoped to the capability, preserves useful recovery detail, and redacts sensitive configuration before it reaches the agent.
-
-## Capabilities
-
-- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, explicit HTTP API action definitions, and curated CLI tool definitions from user and project config sources.
-- Registers one generated MCP tool for each enabled MCP server, OpenAPI endpoint, GraphQL endpoint, HTTP API, or CLI tools backend.
-- Uses the configured server ID as the generated tool name.
-- Uses the configured `name` and `description` as the capability card shown to agents.
-- Starts downstream MCP servers and loads OpenAPI specs lazily when an operation needs them.
-- Supports stdio, Streamable HTTP, and legacy HTTP+SSE downstream servers.
-- Lets agents `tools`, `search_tools`, `describe_tool`, and `call_tool` within one selected Caplet namespace.
-- Converts OpenAPI operations into MCP-style tool metadata and executes HTTP calls directly.
-- Converts configured GraphQL operations into MCP-style tool metadata, and can auto-generate GraphQL tools from schema root query and mutation fields.
-- Converts explicitly configured HTTP actions into MCP-style tool metadata and executes HTTP calls directly.
-- Converts explicitly configured CLI actions into MCP-style tool metadata and executes commands directly without a shell.
-- Preserves downstream tool results instead of rewriting them into a custom format.
-- Redacts secrets from structured errors.
-- Supports static remote auth and OAuth token storage for remote servers.
-
-## Configure
-
-Create a starter project config at `./.caplets/config.json`:
-
-```sh
-caplets init
-```
-
-To create a starter user config instead, pass `--global`. The user config path is
-`${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms and
-`%APPDATA%\caplets\config.json` on Windows:
-
-```sh
-caplets init --global
-```
-
-The generated config includes a disabled example server. Replace it with the MCP servers
-you want Caplets to expose:
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplets-config.schema.json",
-  "version": 1,
-  "defaultSearchLimit": 20,
-  "maxSearchLimit": 50,
-  "completion": {
-    "discoveryTimeoutMs": 750,
-    "overallTimeoutMs": 1500,
-    "cacheTtlMs": 300000,
-    "negativeCacheTtlMs": 30000
-  },
-  "mcpServers": {
-    "filesystem": {
-      "name": "Project Files",
-      "description": "Read, search, and edit local project files.",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/you/code"],
-      "cwd": "/home/you/code",
-      "startupTimeoutMs": 10000,
-      "callTimeoutMs": 60000,
-      "toolCacheTtlMs": 30000
-    },
-    "docs": {
-      "name": "Hosted Docs",
-      "description": "Search hosted product and API documentation.",
-      "transport": "http",
-      "url": "https://mcp.example.com/mcp",
-      "auth": {
-        "type": "bearer",
-        "token": "$env:DOCS_MCP_TOKEN"
-      }
-    }
-  },
-  "openapiEndpoints": {
-    "users": {
-      "name": "Users API",
-      "description": "Manage users through the internal HTTP API.",
-      "specPath": "./openapi.json",
-      "baseUrl": "https://api.example.com",
-      "auth": {
-        "type": "bearer",
-        "token": "$env:USERS_API_TOKEN"
-      }
-    }
-  },
-  "graphqlEndpoints": {
-    "catalog": {
-      "name": "Catalog GraphQL",
-      "description": "Query and update catalog records through GraphQL.",
-      "endpointUrl": "https://api.example.com/graphql",
-      "introspection": true,
-      "auth": {
-        "type": "oidc",
-        "issuer": "https://login.example.com"
-      }
-    }
-  },
-  "httpApis": {
-    "status": {
-      "name": "Status API",
-      "description": "Read deployment status from a simple HTTP API.",
-      "baseUrl": "https://api.example.com",
-      "auth": { "type": "none" },
-      "actions": {
-        "get_status": {
-          "method": "GET",
-          "path": "/status/{service}",
-          "description": "Fetch status for one service.",
-          "inputSchema": {
-            "type": "object",
-            "properties": { "service": { "type": "string" } },
-            "required": ["service"]
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-The user config path can be overridden with `CAPLETS_CONFIG`; the project config path can be
-overridden with `CAPLETS_PROJECT_CONFIG`:
-
-```sh
-CAPLETS_PROJECT_CONFIG=/path/to/project/.caplets/config.json caplets init
-CAPLETS_CONFIG=/path/to/user/config.json caplets init --global
-CAPLETS_CONFIG=/path/to/config.json caplets serve
-```
-
-Inspect the installed CLI version and resolved config locations:
-
-```sh
-caplets --version
-caplets config path
-caplets config paths
-caplets config paths --json
-```
-
-Caplets validates config files at startup and hot reloads config changes while `caplets serve`
-is running. Invalid edits are ignored until fixed, so the MCP server keeps serving the last
-known-good config instead of dropping every tool because of a transient JSON or validation error.
-
-The optional `$schema` field points editors at the generated JSON Schema in
-[`schemas/caplets-config.schema.json`](schemas/caplets-config.schema.json). CI verifies that
-the committed schema stays in sync with the Zod config validator.
-
-### Caplet Files
-
-For richer skill-like cards, add Markdown Caplet files beside `config.json`. Every Caplet
-file must include exactly one executable backend: `mcpServer`, `openapiEndpoint`,
-`graphqlEndpoint`, `httpApi`, `cliTools`, or `capletSet`;
-serverless Caplets are intentionally out of scope.
-
-Top-level files derive the Caplet ID from the filename:
-
-```md
----
-$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
-name: GitHub
-description: Interact with GitHub repositories, issues, and pull requests.
-tags:
-  - code
-  - review
-mcpServer:
-  transport: http
-  url: https://api.githubcopilot.com/mcp
-  auth:
-    type: bearer
-    token: $env:GH_TOKEN
----
-
-# GitHub
-
-Use this Caplet for repository, issue, pull request, and code review workflows.
-```
-
-OpenAPI-backed Caplet files use `openapiEndpoint`:
-
-```md
----
-name: Users API
-description: Manage users through the internal HTTP API.
-openapiEndpoint:
-  specPath: ./openapi.json
-  baseUrl: https://api.example.com
-  auth:
-    type: bearer
-    token: $env:USERS_API_TOKEN
----
-
-# Users API
-```
-
-GraphQL-backed Caplet files use `graphqlEndpoint`:
-
-```md
----
-name: Catalog GraphQL
-description: Query and update catalog records through GraphQL.
-graphqlEndpoint:
-  endpointUrl: https://api.example.com/graphql
-  schemaPath: ./schema.graphql
-  auth:
-    type: oidc
-    issuer: https://login.example.com
----
-
-# Catalog GraphQL
-```
-
-HTTP action Caplet files use `httpApi`:
-
-```md
----
-name: Status API
-description: Read deployment status from a simple HTTP API.
-httpApi:
-  baseUrl: https://api.example.com
-  auth:
-    type: none
-  actions:
-    get_status:
-      method: GET
-      path: /status/{service}
-      description: Fetch status for one service.
-      inputSchema:
-        type: object
-        properties:
-          service:
-            type: string
-        required: [service]
----
-
-# Status API
-```
-
-CLI-backed Caplet files use `cliTools`:
-
-```md
----
-name: Repository CLI
-description: Run curated repository workflows through local CLI commands.
-cliTools:
-  cwd: /home/you/project
-  actions:
-    git_status:
-      description: Show concise Git working tree status.
-      command: git
-      args: ["status", "--short"]
-      annotations:
-        readOnlyHint: true
----
-
-# Repository CLI
-```
-
-Top-level files derive their Caplet ID from the filename. Directory-style Caplets use
-`linear/CAPLET.md`, which is exposed as `linear`; sibling files can be referenced with
-normal Markdown links from `CAPLET.md`.
-
-This repository includes polished working examples under [`caplets/`](caplets/):
-
-- `github`: GitHub's hosted MCP endpoint, using `GH_TOKEN`.
-- `linear`: Linear's hosted OAuth MCP endpoint.
-- `context7`: Context7 documentation lookup through `@upstash/context7-mcp`.
-- `repo-cli`: Read-oriented repository CLI workflows through `git` and package scripts.
-- `ast-grep`: Structural code search, scan, rewrite, rule testing, and scaffolding through the `ast-grep` CLI.
-- `osv`: OSV.dev vulnerability lookups through explicit read-only HTTP actions.
-- `npm`: npm registry operations through npm's published OpenAPI spec URL.
-- `pypi`: PyPI project metadata, release metadata, and Simple API JSON through a curated OpenAPI spec.
-- `deepwiki`: Repository-focused documentation and architecture context through DeepWiki MCP.
-- `sourcegraph`: Cross-repository code search and navigation through Sourcegraph MCP.
-- `playwright`: Headless browser automation for frontend inspection and testing through Playwright MCP.
-- `lsp`: Language Server Protocol-backed code intelligence through `language-server-mcp`.
-- `coding-agent-toolkit`: A CapletSet that bundles high-value coding-agent examples; source children are symlinks to canonical top-level examples and installed copies are materialized as self-contained files/directories.
-
-GraphQL is intentionally skipped in this showcase batch so the examples can focus on HTTP,
-OpenAPI, MCP, CLI, and CapletSet coverage without duplicating GitHub or GitLab surfaces.
-
-Install every example from a repo's `caplets/` directory into the current project's
-`./.caplets` directory:
-
-```sh
-caplets install spiritledsoftware/caplets
-```
-
-Install one or more individual Caplets by ID:
-
-```sh
-caplets install spiritledsoftware/caplets github
-caplets install spiritledsoftware/caplets github linear
-```
-
-`caplets install` accepts a GitHub `owner/repo` shorthand, a Git URL, or a local repository path.
-By default it writes to `./.caplets`, creating that directory when needed. Pass `-g` or
-`--global` to write to your user Caplets root instead, which is
-`${XDG_CONFIG_HOME:-~/.config}/caplets` on Unix-like platforms, `%APPDATA%\caplets` on Windows,
-or the parent directory of `CAPLETS_CONFIG` when that environment variable is set. Existing
-Caplets are not overwritten unless `--force` is passed.
-
-On Unix-like platforms, relative `XDG_CONFIG_HOME` and `XDG_STATE_HOME` values are ignored.
-
-Caplets loads user Caplet files from the user Caplets root and project Caplet files from the
-current working directory's `./.caplets` directory. Later sources override earlier ones in this
-order: user `config.json`, user Caplet files, project `config.json`, and project Caplet files.
-That means a project-local Caplet can intentionally replace a user-level Caplet with the same ID.
-Use `caplets list` to see each Caplet's winning source; when a project Caplet shadows a user-level
-Caplet, the list output includes a warning naming the shadowed path.
-
-`caplets init` refuses to overwrite an existing project config. To intentionally replace the file:
-
-```sh
-caplets init --force
-```
-
-Use `caplets init --global --force` to replace the user config instead.
-
-### Caplet IDs
-
-Each key under `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, `httpApis`, `cliTools`, or `capletSets` is the
-stable Caplet ID. It becomes the generated MCP tool name exactly, so keep it short and specific:
-
-```json
-{
-  "mcpServers": {
-    "linear": {
-      "name": "Linear",
-      "description": "Read and update Linear issues and projects.",
-      "command": "npx",
-      "args": ["-y", "linear-mcp-server"]
-    }
-  }
-}
-```
-
-Caplet IDs must match `^[a-zA-Z0-9_-]{1,64}$` and must be unique across `mcpServers`,
-`openapiEndpoints`, `graphqlEndpoints`, `httpApis`, `cliTools`, and `capletSets`. Spaces, dots, slashes, colons, and Unicode IDs are rejected.
-
-### Stdio Servers
-
-Use `command` for a local stdio MCP server. `args`, `env`, and `cwd` are optional.
-
-```json
-{
-  "name": "Local Tools",
-  "description": "Run local development tools through stdio.",
-  "command": "node",
-  "args": ["./server.mjs"],
-  "env": {
-    "API_TOKEN": "${API_TOKEN}"
-  },
-  "cwd": "/home/you/project"
-}
-```
-
-### Remote Servers
-
-Use `transport` and `url` for remote MCP servers.
-
-```json
-{
-  "name": "Remote Docs",
-  "description": "Search documentation from a remote MCP server.",
-  "transport": "http",
-  "url": "https://mcp.example.com/mcp",
-  "auth": {
-    "type": "headers",
-    "headers": {
-      "x-api-key": "$env:REMOTE_DOCS_API_KEY"
-    }
-  }
-}
-```
-
-`transport` can be `http` for MCP Streamable HTTP or `sse` for legacy HTTP+SSE. Remote
-URLs must use `https://`, except loopback development URLs such as `http://localhost`.
-
-### OpenAPI Endpoints
-
-Use `openapiEndpoints` for native HTTP APIs described by OpenAPI 3 specs. Each entry
-points at one spec through either `specPath` or `specUrl`, and may override the request
-base URL with `baseUrl`.
-
-```json
-{
-  "name": "Users API",
-  "description": "Manage users through the internal HTTP API.",
-  "specPath": "./openapi.json",
-  "baseUrl": "https://api.example.com",
-  "auth": { "type": "none" }
-}
-```
-
-OpenAPI auth is explicit and supports:
-
-- `{"type": "none"}`
-- `{"type": "bearer", "token": "$env:TOKEN"}`
-- `{"type": "headers", "headers": {"x-api-key": "$env:API_KEY"}}`
-- `{"type": "oauth2", ...}`
-- `{"type": "oidc", ...}`
-
-OpenAPI `call_tool.args` uses grouped HTTP inputs:
-
-```json
-{
-  "operation": "call_tool",
-  "tool": "GET /users/{id}",
-  "arguments": {
-    "path": { "id": "42" },
-    "query": { "active": true },
-    "body": { "name": "Ada" }
-  }
-}
-```
-
-Every OpenAPI endpoint can set:
-
-- `requestTimeoutMs`: timeout for HTTP calls. Defaults to `60000`.
-- `operationCacheTtlMs`: how long OpenAPI operation metadata stays fresh. Defaults to `30000`; `0` refreshes every time.
-- `disabled`: omit the endpoint from Caplets discovery. Defaults to `false`.
-
-### GraphQL Endpoints
-
-Use `graphqlEndpoints` for native GraphQL APIs. Each entry points at a GraphQL HTTP
-endpoint and exactly one schema source: `schemaPath`, `schemaUrl`, or `introspection: true`.
-
-```json
-{
-  "name": "Catalog GraphQL",
-  "description": "Query and update catalog records through GraphQL.",
-  "endpointUrl": "https://api.example.com/graphql",
-  "schemaPath": "./schema.graphql",
-  "auth": { "type": "oidc", "issuer": "https://login.example.com" },
-  "operations": {
-    "product": {
-      "document": "query Product($id: ID!) { product(id: $id) { id name } }",
-      "operationName": "Product",
-      "description": "Fetch a product by ID."
-    }
-  }
-}
-```
-
-When `operations` is omitted or empty, Caplets auto-generates tools from schema root
-fields: `query_<field>` and `mutation_<field>`. Generated tools use bounded scalar
-selection sets and pass `call_tool.args` directly as GraphQL variables/root-field
-arguments.
-
-Every GraphQL endpoint can set:
-
-- `requestTimeoutMs`: timeout for HTTP calls. Defaults to `60000`.
-- `operationCacheTtlMs`: how long GraphQL operation metadata stays fresh. Defaults to `30000`; `0` refreshes every time.
-- `selectionDepth`: maximum depth for generated selection sets. Defaults to `2`; maximum `5`.
-- `disabled`: omit the endpoint from Caplets discovery. Defaults to `false`.
-
-### HTTP APIs
-
-Use `httpApis` for simple HTTP APIs that do not have an OpenAPI spec. Each action is an
-explicitly configured tool; Caplets does not discover routes, import curl commands, or execute
-shell snippets.
-
-```json
-{
-  "name": "Status API",
-  "description": "Read and update deployment status through HTTP actions.",
-  "baseUrl": "https://api.example.com",
-  "auth": { "type": "bearer", "token": "$env:STATUS_API_TOKEN" },
-  "maxResponseBytes": 1000000,
-  "actions": {
-    "get_status": {
-      "method": "GET",
-      "path": "/status/{service}",
-      "description": "Fetch status for one service.",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "service": { "type": "string" },
-          "verbose": { "type": "boolean" }
-        },
-        "required": ["service"]
-      },
-      "query": { "verbose": "$input.verbose" }
-    },
-    "set_status": {
-      "method": "POST",
-      "path": "/status/{service}",
-      "jsonBody": { "state": "$input.state", "note": "$input.note" }
-    }
-  }
-}
-```
-
-HTTP API actions support `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. `baseUrl` must be HTTPS
-except loopback URLs, must not include credentials, query, or fragment, and action `path` values
-must start with `/` and be URL paths that cannot change origin or escape the base URL path.
-
-Action mappings can set `query`, `headers`, and `jsonBody`. `query` and `headers` must resolve
-to object maps whose values are strings, numbers, or booleans. `jsonBody` may use literals,
-nested arrays/objects, `$input.field` references, or `$input` for the whole argument object.
-Path placeholders such as `{service}` are read directly from `call_tool.args` and URL-encoded.
-Configured action headers cannot set managed headers such as `authorization`, `host`,
-`content-length`, `connection`, or `content-type`; JSON bodies set `content-type` automatically.
-
-HTTP API auth supports `none`, `bearer`, `headers`, `oauth2`, and `oidc`, matching OpenAPI and
-GraphQL. Responses are returned as structured content with `status`, `statusText`, safe headers,
-parsed `body` when present, and `elapsedMs`; non-2xx responses set `isError`, redirects are rejected,
-timeouts are enforced, response bodies are capped by `maxResponseBytes` (default `1000000`), and
-errors redact secrets.
-
-### CLI Tools
-
-Use `cliTools` for curated local command-line workflows. Each action is an explicitly configured
-tool; Caplets does not expose arbitrary shell access and always spawns `command` plus `args`
-without shell interpolation.
-
-```json
-{
-  "name": "Repository CLI",
-  "description": "Run curated repository workflows through local CLI commands.",
-  "cwd": "/home/you/project",
-  "timeoutMs": 60000,
-  "maxOutputBytes": 1000000,
-  "actions": {
-    "git_status": {
-      "description": "Show concise Git working tree status.",
-      "command": "git",
-      "args": ["status", "--short"],
-      "annotations": { "readOnlyHint": true }
-    },
-    "run_tests": {
-      "description": "Run the package test script.",
-      "command": "pnpm",
-      "args": ["run", "test"],
-      "timeoutMs": 120000,
-      "annotations": { "readOnlyHint": true }
-    }
-  }
-}
-```
-
-CLI actions can set `inputSchema`, `outputSchema`, `env`, action-level `cwd`, `timeoutMs`,
-`maxOutputBytes`, `output: {"type":"json"}`, and MCP annotations. `$input.field` references are
-supported inside `args`, `env`, and `cwd` strings. Caplets performs basic required-field and
-primitive-type validation before spawning. Results are returned as structured content with
-`exitCode`, `stdout`, `stderr`, and `elapsedMs`; non-zero exits set `isError`.
-
-Generate and add a CLI Caplet manifest from a repository:
-
-```sh
-caplets add cli repo-tools --repo . --include git,gh,package
-```
-
-`caplets add` writes generated Markdown Caplet files to `./.caplets/<id>.md` by default.
-Pass `-g` or `--global` to write to the user Caplets root, `--print` to review the generated
-manifest without writing, `--output <path>` for an explicit destination, or `--force` to overwrite
-an existing destination file.
-
-### Caplet Sets
-
-Use `capletSets` to expose another Caplets collection as nested Caplets. Each child Caplet appears
-as one downstream tool and supports the full Caplets operation set: `inspect`, `check`,
-`tools`, `search_tools`, `describe_tool`, and `call_tool`.
-
-```json
-{
-  "capletSets": {
-    "team": {
-      "name": "Team Caplets",
-      "description": "Use the team's shared Caplets collection.",
-      "configPath": "./team-caplets/config.json",
-      "capletsRoot": "./team-caplets/caplets"
-    }
-  }
-}
-```
-
-`configPath` and `capletsRoot` are independently optional, but at least one is required. Child
-collections are isolated from the parent collection; they use their own config and Caplet files,
-with their own `defaultSearchLimit` and `maxSearchLimit` when set on the `capletSets` entry.
-Recursive nesting is supported, and repeated source paths are rejected as cycles.
-
-Markdown Caplet files use `capletSet` frontmatter:
-
-```yaml
----
-name: Team Caplets
-description: Use the team's shared Caplets collection.
-capletSet:
-  configPath: ./team-caplets/config.json
-  capletsRoot: ./team-caplets/caplets
----
-```
-
-Add MCP, OpenAPI, GraphQL, and HTTP API Caplets with the same destination options:
-
-```sh
-caplets add mcp local-tools --command node --arg ./server.mjs
-caplets add mcp remote-tools --url https://mcp.example.com/mcp --transport http --token-env MCP_TOKEN
-caplets add openapi users --spec ./openapi.json --base-url https://api.example.com --token-env USERS_API_TOKEN
-caplets add graphql catalog --endpoint-url https://api.example.com/graphql --schema ./schema.graphql
-caplets add graphql catalog-live --endpoint-url https://api.example.com/graphql --introspection
-caplets add http status-api --base-url https://api.example.com --action get_status:GET:/status/{service}
-```
-
-For `caplets add mcp`, use `--command` with repeated `--arg`, optional `--cwd`, and repeated
-`--env KEY=VALUE` for stdio servers, or `--url` with `--transport http|sse` for remote servers.
-For HTTP authentication, pass `--token-env <ENV>` so generated manifests reference `$env:ENV`
-instead of embedding raw bearer tokens.
-
-### Authentication
-
-Remote servers can use:
-
-- `{"type": "none"}`
-- `{"type": "bearer", "token": "$env:TOKEN"}`
-- `{"type": "headers", "headers": {"x-api-key": "$env:API_KEY"}}`
-- `{"type": "oauth2", ...}`
-- `{"type": "oidc", ...}`
+The deterministic benchmark compares flat MCP exposure with Caplets over the same mock
+servers:
 
-For OAuth/OIDC-backed MCP, OpenAPI, GraphQL, and HTTP API Caplets, authenticate once with:
+| Initial surface         |    Direct MCP |      Caplets |     Reduction |
+| ----------------------- | ------------: | -----------: | ------------: |
+| Visible tools           |           215 |            7 |   96.7% fewer |
+| Serialized payload      |  63,250 bytes | 12,720 bytes | 79.9% smaller |
+| Approx. context surface | 15,813 tokens | 3,180 tokens |  12,633 fewer |
 
-```sh
-caplets auth login <server>
-```
-
-For headless terminals:
-
-```sh
-caplets auth login <server> --no-open
-```
-
-In local mode, OAuth/OIDC tokens are stored under
-`${XDG_STATE_HOME:-~/.local/state}/caplets/auth/<server>.json` on Unix-like platforms and
-`%LOCALAPPDATA%\caplets\auth\<server>.json` on Windows. Token files use owner-only file
-permissions where the platform supports them. In `CAPLETS_MODE=remote`, `caplets auth list` shows
-local and remote auth targets with a `source` field. `caplets auth login <server>` and
-`caplets auth logout <server>` use the matching scope when it is unambiguous; if the same ID exists
-in multiple scopes, pass `--project`, `--global`, or `--remote`. Remote OAuth/OIDC credentials are
-stored server-side and are not returned to the local client. Caplets supports well-known OAuth/OIDC
-discovery and dynamic client registration when advertised. When a token expires, run
-`caplets auth login <server>` again.
+The landing-page live Pi eval reports Caplets Code Mode passing the same 10/10 real-world
+large MCP tasks as direct MCP and Executor.sh while using 72.0% fewer request + output
+tokens than direct vanilla MCP. Live runs are model- and environment-dependent; the
+deterministic benchmark is the reproducible claim.
 
-Auth target flags are mutually exclusive. `caplets auth list --project`,
-`caplets auth list --global`, and `caplets auth list --remote` filter the listing to one scope.
+See [docs/benchmarks/coding-agent.md](https://github.com/spiritledsoftware/caplets/blob/main/docs/benchmarks/coding-agent.md) for methodology and reproduction commands.
 
-To inspect or remove stored OAuth credentials:
+## Repository
 
-```sh
-caplets auth list
-caplets auth logout <server>
-```
-
-To list configured Caplets without starting downstream backends:
+This monorepo uses pnpm. Published packages support Node.js `>=22`; repo verification uses
+the root toolchain, which requires Node.js `>=24`.
 
 ```sh
-caplets list
-caplets list --all
-caplets list --json
-```
-
-Human output includes a `source` column. JSON output includes each Caplet's `source`, `path`, and
-`shadows` metadata. If a project source overrides a user source, human output prints a warning such
-as `Warning: project Caplet GitHub shadows global Caplet at /path/to/github.md`.
-
-For safety, `caplets add` and `caplets install` reject symlinked output paths and symlinked parent
-directories instead of following them.
-
-### Optional Server Settings
-
-Every server can set:
-
-- `startupTimeoutMs`: timeout for starting or checking the downstream server. Defaults to `10000`.
-- `callTimeoutMs`: timeout for downstream tool calls. Defaults to `60000`.
-- `toolCacheTtlMs`: how long downstream tool metadata stays fresh. Defaults to `30000`; `0` refreshes every time.
-- `disabled`: omit the server from Caplets discovery. Defaults to `false`.
-
-## Add Caplets To An MCP Client
-
-Configure your MCP client to run Caplets as a stdio server:
-
-```json
-{
-  "mcpServers": {
-    "caplets": {
-      "command": "caplets",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-If your client starts the configured command directly, `caplets` without arguments also
-starts the MCP server. `serve` is explicit and recommended for clarity.
-
-`caplets serve` watches the effective user config, project config, user Caplet files, and
-project Caplet files. Adding, editing, disabling, or removing a Caplet updates the
-top-level MCP tool list without restarting Caplets. When an MCP-backed Caplet changes or is
-removed, Caplets closes only that affected downstream connection; unrelated Caplets and
-their downstream connections keep running.
-
-## Quick Integration Setup
-
-Run the interactive setup flow to choose one or more agent integrations:
-
-```bash
-caplets setup
-```
-
-For scripted setup, pass the integration explicitly:
-
-```bash
-caplets setup codex
-caplets setup claude-code
-caplets setup opencode
-caplets setup pi
-caplets setup mcp-client --output ./caplets.mcp.json
-```
-
-Preview the actions before changing anything:
-
-```bash
-caplets setup codex --dry-run
-```
-
-For native integrations that should connect to a remote Caplets HTTP service:
-
-```bash
-caplets setup codex --remote-url https://caplets.example.com/caplets
-caplets setup claude-code --remote-url https://caplets.example.com/caplets
-caplets setup opencode --remote-url https://caplets.example.com/caplets
-```
-
-For Codex and Claude Code, `caplets setup` uses each harness's MCP configuration command:
-`codex mcp add caplets -- caplets serve` and
-`claude mcp add --transport stdio --scope user caplets -- caplets serve`. Generic MCP
-clients still require an explicit `--output` path because their config locations are not
-standardized. The setup command does not store secrets or start `caplets serve`.
-
-## Additional Native Integrations
-
-OpenCode and Pi support true native tool registration. Those integrations expose one
-prefixed tool per configured Caplet, such as `caplets__github`, while reusing the same
-Caplets config and backend runtime.
-
-- [`@caplets/opencode`](packages/opencode/README.md): OpenCode plugin that injects prompt guidance through plugin hooks instead of editing `opencode.json`.
-- [`@caplets/pi`](packages/pi/README.md): Pi extension installable with `pi install npm:@caplets/pi`, with guidance provided through Pi tool prompt snippets and guidelines.
-
-Native integrations hot reload config and Caplet file edits through the same runtime used by
-`caplets serve`. Existing native tools execute against the latest valid config without host
-restart. Pi also refreshes newly added Caplet tools at runtime and deactivates removed Caplet
-tools when Pi's active-tool APIs are available. OpenCode's current plugin API snapshots the
-tool inventory at plugin load, so adding, removing, or renaming OpenCode native tools still
-requires restarting OpenCode; already-registered tools execute against live Caplets state, and
-prompt guidance is rebuilt from current Caplets state for those initially registered tools only.
-Newly added OpenCode tools are not advertised until restart.
-
-## How Agents Use It
-
-Caplets initially exposes one MCP tool per enabled Caplet. If the config has `filesystem`,
-`docs`, and `users`, the client sees three top-level tools: `filesystem`, `docs`, and
-`users`.
-
-Each generated Caplet tool accepts an `operation`:
-
-```json
-{
-  "operation": "tools"
-}
-```
-
-Search within a selected server:
-
-```json
-{
-  "operation": "search_tools",
-  "query": "read file",
-  "limit": 10
-}
-```
-
-Inspect one exact downstream tool:
-
-```json
-{
-  "operation": "describe_tool",
-  "tool": "read_file"
-}
-```
-
-Call one exact downstream tool:
-
-```json
-{
-  "operation": "call_tool",
-  "tool": "read_file",
-  "arguments": {
-    "path": "/home/you/code/project/README.md"
-  }
-}
-```
-
-Available operations:
-
-- `inspect`: return the configured capability card without starting the downstream server.
-- `check`: verify the selected backend, whether MCP, OpenAPI, GraphQL, HTTP, CLI, or nested Caplets.
-- `tools`: return compact downstream tool metadata.
-- `search_tools`: search downstream tool names and descriptions within this Caplet.
-- `describe_tool`: return full metadata for one exact downstream tool.
-- `call_tool`: invoke one exact downstream tool with JSON object arguments.
-
-Requests are strict: operation-specific extra fields are rejected, and `call_tool` requires
-`arguments` to be a JSON object.
-
-Discovery operations (`inspect`, `check`, `tools`, `search_tools`, and
-`describe_tool`) return wrapper-generated results whose `structuredContent.caplets` field
-identifies the Caplet with `id`, plus backend, operation, status, and elapsed time when
-available. Discovery result objects and compact tool entries also use `id` for the
-configured Caplet identity. Compact `tools` and `search_tools` entries may include
-input/output schema hashes; treat those
-hashes as reuse hints for a schema you have already inspected, not as a replacement for
-`describe_tool` when arguments, output, or semantics are unclear.
-
-Direct `call_tool` preserves the downstream tool result shape instead of wrapping it in
-`structuredContent.result`. When the result can carry MCP metadata, Caplets adds
-`_meta.caplets` with the same call context and status. It may also include artifact metadata
-for paths mentioned by downstream content, such as screenshots, snapshots, logs, downloads,
-or other saved files. Artifact `displayPath` values are either absolute local paths or
-relative to the downstream MCP server process, not necessarily relative to the current
-project or Caplets process.
-
-Code Mode is the default exposure because it keeps discovery, filtering, execution, and
-summary work inside one compact tool call. To expose the older progressive wrapper tools,
-set `options.exposure` to `progressive` or `progressive_and_code_mode`.
-
-## Development
-
-```sh
-pnpm install
-pnpm dev
+pnpm install --frozen-lockfile
+pnpm verify
 ```
 
-Useful commands:
+Useful focused checks:
 
 ```sh
-pnpm build
-pnpm test
-pnpm typecheck
-pnpm lint
 pnpm format:check
-pnpm schema:generate
-pnpm schema:check
-pnpm verify
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm benchmark:check
+pnpm build
 ```
 
-`pnpm dev` rebuilds Caplets source changes and restarts the local stdio MCP server from
-`dist/index.js`. Use it for local development, not as the command configured in an MCP
-client, because build logs are written to stdout. Runtime config hot reload is built into
-normal `caplets serve` and does not require `pnpm dev`.
-
-## Product Notes
+Package map:
 
-The product requirements document lives at
-[`docs/product/caplets-progressive-mcp-disclosure-prd.md`](docs/product/caplets-progressive-mcp-disclosure-prd.md).
-It describes the progressive MCP disclosure model, configuration rules, MVP tool surface,
-security expectations, and non-goals.
+- `packages/core` - runtime, config, Code Mode, backends, MCP server, remote attach
+- `packages/cli` - published `caplets` binary
+- `packages/opencode` - native OpenCode plugin
+- `packages/pi` - native Pi extension
+- `packages/benchmarks` - deterministic and opt-in live benchmarks
+- `apps/landing` - public site at `caplets.dev`
 
-Caplets intentionally does not provide a hosted service, GUI, cross-server flattened tool
-search, automatic MCP client config import, or namespaced flattened tool IDs such as
-`server.tool`.
-
-Progressive disclosure is context management, not a security boundary. Caplets reduces the
-tool surface shown to the agent up front, but downstream MCP servers remain responsible for
-their own tool behavior and any client-side confirmations.
-
-## Release Flow
-
-User-facing changes should include a changeset:
-
-```sh
-pnpm changeset
-```
+Long-lived docs:
 
-Merging changesets to `main` lets the release workflow open a version PR. Merging that
-version PR publishes the package to npm through trusted publishing.
+- [Code Mode PRD](https://github.com/spiritledsoftware/caplets/blob/main/docs/product/caplets-code-mode-prd.md)
+- [Architecture](https://github.com/spiritledsoftware/caplets/blob/main/docs/architecture.md)
+- [ADR 0001: Code Mode default exposure](https://github.com/spiritledsoftware/caplets/blob/main/docs/adr/0001-code-mode-default-exposure.md)
+- [Benchmark methodology](https://github.com/spiritledsoftware/caplets/blob/main/docs/benchmarks/coding-agent.md)
+- [Native integrations](https://github.com/spiritledsoftware/caplets/blob/main/docs/native-integrations.md)
+- [Project Binding](https://github.com/spiritledsoftware/caplets/blob/main/docs/project-binding.md)
 
 ## License
 
diff --git a/docs/adr/0001-code-mode-default-exposure.md b/docs/adr/0001-code-mode-default-exposure.md
new file mode 100644
index 00000000..04e481b9
--- /dev/null
+++ b/docs/adr/0001-code-mode-default-exposure.md
@@ -0,0 +1,37 @@
+# ADR 0001: Make Code Mode The Default Backend Exposure
+
+## Status
+
+Accepted
+
+## Context
+
+Early Caplets work centered on progressive disclosure: show one capability card first, then let the agent inspect and call downstream operations through scoped wrapper tools. That model reduced flat tool-list bloat, but larger workflows still required repeated model/tool round trips for discovery, schema inspection, execution, filtering, and synthesis.
+
+The current implementation supports multiple exposure modes and defaults global config to `code_mode`. The landing page, benchmark report, native integrations, and runtime code all treat Code Mode as the main path for agents using configured backends.
+
+Source code remains the source of truth for behavior. This ADR records the decision and rationale, not a substitute for `packages/core` or generated schemas.
+
+## Decision
+
+Code Mode is the default backend exposure for Caplets.
+
+Configured backends should enter the primary agent surface as generated `caplets.<id>` handles inside a Code Mode TypeScript script. Agents should perform discovery, exact schema inspection, tool calls, filtering, joins, and compact synthesis inside that script.
+
+Progressive wrapper tools remain supported through the `progressive` and `progressive_and_code_mode` exposure modes. Direct MCP exposure remains supported through `direct` and `direct_and_code_mode` when the downstream surface should be registered directly.
+
+## Consequences
+
+- Product docs should describe Caplets as Code Mode first, not only as a progressive disclosure gateway.
+- Progressive disclosure remains an implementation and compatibility model, but not the primary product frame.
+- Benchmarks should report Code Mode separately from progressive modes.
+- Agent guidance should prefer compact one-pass Code Mode scripts for multi-step work.
+- Long-lived docs should preserve progressive exposure details as an alternate mode, not as the main PRD.
+
+## Evidence
+
+- `packages/core/src/config.ts` defaults `options.exposure` to `code_mode`.
+- `packages/core/src/serve/session.ts` registers a `code_mode` MCP tool when Code Mode Caplets are callable.
+- `packages/core/src/native/tools.ts` defines `caplets__code_mode` for native integrations.
+- `docs/benchmarks/coding-agent.md` records deterministic Code Mode workflow results and live benchmark guidance.
+- `apps/landing/src/pages/index.astro` presents Code Mode as the primary evaluated mode.
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 00000000..e3bd3f0b
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,120 @@
+# Caplets Architecture
+
+Caplets is a Code Mode and capability gateway for coding agents. It turns configured backends into Caplet handles, optional progressive wrapper tools, and optional direct MCP surfaces.
+
+Source code is authoritative. This document summarizes the architecture, but implementation details in `packages/core`, generated schemas, tests, and package entrypoints win when docs drift.
+
+## Runtime Layers
+
+### Configuration And Caplet Sources
+
+The core config loader accepts user config, project config, and Markdown Caplet files. The schema source of truth is Zod in `packages/core/src/config.ts`, with generated JSON Schemas in `schemas/`.
+
+Supported backend families are:
+
+- `mcpServers`
+- `openapiEndpoints`
+- `graphqlEndpoints`
+- `httpApis`
+- `cliTools`
+- `capletSets`
+
+Project sources override user/global sources. Source-aware inspection reports where each Caplet came from and warns when one Caplet shadows another.
+
+### Engine
+
+`packages/core/src/engine.ts` owns the active config, backend managers, config reload behavior, and execution dispatch. Reload keeps the last known-good config if parsing or validation fails.
+
+Backend managers provide a common shape for listing tools, searching tools, describing exact tools, calling tools, and checking readiness. MCP-backed Caplets additionally support resources, resource templates, prompts, and completion.
+
+### Exposure Policy
+
+`packages/core/src/exposure/policy.ts` resolves one exposure value into three booleans:
+
+- `codeMode`
+- `progressive`
+- `direct`
+
+The global default is `code_mode`. Per-Caplet config may choose `direct`, `progressive`, `code_mode`, `direct_and_code_mode`, or `progressive_and_code_mode`.
+
+### MCP Server
+
+`packages/core/src/serve/session.ts` registers the user-facing MCP surface.
+
+- Code Mode exposure registers one `code_mode` tool that runs TypeScript against generated `caplets.<id>` handles.
+- Progressive exposure registers one wrapper tool per Caplet.
+- Direct exposure registers discovered downstream MCP tools, resources, resource templates, and prompts.
+
+The HTTP server in `packages/core/src/serve/http.ts` exposes MCP, control, and health endpoints for self-hosting and remote clients. Stdio remains the local MCP transport for ordinary client config.
+
+### Code Mode
+
+Code Mode is implemented under `packages/core/src/code-mode/`.
+
+The runtime generates TypeScript declarations from the current callable Caplets, statically checks the submitted script, runs it in the sandbox, bridges handle methods back to the native service, stores logs when configured, and returns JSON-serializable results with diagnostics.
+
+The intended agent pattern is one compact script:
+
+1. choose handles
+2. inspect or check only when useful
+3. search for candidate operations
+4. describe exact operations when schemas are needed
+5. call tools
+6. filter, join, and summarize inside the script
+7. return compact decision-ready evidence
+
+### Native Service
+
+`packages/core/src/native/service.ts` powers OpenCode and Pi. It uses the same engine and exposure policy as MCP serving, then exposes native tools with agent-specific prompt guidance.
+
+`caplets__code_mode` is the native Code Mode entrypoint. `caplets__<id>` tools exist for progressive exposure. Direct native exposure registers operation-level tools named `caplets__<id>__<operation>`.
+
+### Remote Control
+
+Remote control under `packages/core/src/remote-control/` lets CLI and native integrations operate against a self-hosted or Cloud Caplets service. Remote mode uses server-owned config, auth, and execution, with local/project overlays where supported.
+
+### Project Binding
+
+Project Binding under `packages/core/src/project-binding/` connects a local project root to a remote runtime. The foreground attach loop owns session state, heartbeat, reconnect behavior, sync preflight, and terminal recovery commands.
+
+`docs/project-binding.md` is the living operational contract for Project Binding.
+
+## Backend Contracts
+
+### MCP
+
+MCP-backed Caplets preserve downstream tool results and expose resources, templates, prompts, and completion when the downstream server supports them. Direct exposure can register those downstream surfaces directly.
+
+### OpenAPI, GraphQL, And HTTP
+
+OpenAPI, GraphQL, and HTTP backends expose explicit operation/action tools. They do not synthesize MCP resources or prompts. HTTP-like backends enforce safe URL handling, bounded response bodies, timeouts, and redacted errors.
+
+### CLI Tools
+
+CLI-backed Caplets expose curated actions only. Actions spawn declared commands and args without shell interpolation. Inputs are validated before spawn, and outputs are bounded.
+
+### Caplet Sets
+
+Caplet sets expose another Caplets collection as a nested backend. This lets a team or repository share a Caplet catalog without flattening every child backend into the parent config.
+
+## Auth And Secrets
+
+Auth supports none, bearer, headers, OAuth2, and OIDC where the backend family supports them. OAuth/OIDC state is stored outside config. Errors and diagnostics redact configured secrets.
+
+Cloud Auth stores hosted credentials and a selected workspace. `caplets attach` refreshes expired hosted credentials before creating Binding Sessions and fails closed when refresh credentials are revoked.
+
+## Distribution And Deployment
+
+The public CLI package is `caplets`. The native packages are `@caplets/opencode` and `@caplets/pi`.
+
+The repo includes a source-build `Dockerfile` and `docker-compose.yml` for self-hosting the HTTP service. Release workflows publish npm packages and can publish the service image.
+
+## Benchmark Architecture
+
+`packages/benchmarks` owns deterministic and opt-in live benchmarks.
+
+- Deterministic benchmarks are stable, credential-free, and committed through `docs/benchmarks/coding-agent.md`.
+- Live benchmarks require local agents, credentials, selected models, and explicit `CAPLETS_BENCH_LIVE=1`.
+- Pi eval modes include Code Mode, progressive Code Mode, direct Code Mode, vanilla MCP, and Executor MCP competitors.
+
+Benchmark output is product evidence, not runtime configuration truth. Runtime truth lives in `packages/core`.
diff --git a/docs/plans/2026-05-12-cli-inspection-polish.md b/docs/plans/2026-05-12-cli-inspection-polish.md
deleted file mode 100644
index 851ac039..00000000
--- a/docs/plans/2026-05-12-cli-inspection-polish.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Caplets CLI Inspection Polish
-
-## Summary
-
-Add a small read-only inspection suite to the existing Commander-based CLI:
-
-- `caplets --version` prints the package version from `package.json`.
-- `caplets list` lists enabled configured Caplets by default.
-- `caplets list --all` includes disabled entries.
-- `caplets list --json` emits stable machine-readable JSON.
-- `caplets config path` prints the effective user config path, honoring `CAPLETS_CONFIG`.
-- `caplets config paths` prints user config, project config, Caplets roots, auth directory, and trust/env state.
-
-No runtime MCP server behavior changes.
-
-## Key Changes
-
-- Update `src/cli.ts` to import `package.json` version and register Commander version support.
-- Add a `list` command that loads config through existing `loadConfig(envConfigPath())`, builds a `ServerRegistry`, and prints:
-  - text columns: `server`, `backend`, `status`, `name`
-  - JSON array objects: `{ server, backend, name, description, disabled, status }`
-- Add `config` subcommands:
-  - `config path`: prints only `resolveConfigPath(envConfigPath())`
-  - `config paths`: prints resolved user config path, project config path, user root, project root, auth dir, whether `CAPLETS_CONFIG` is set, and whether `CAPLETS_TRUST_PROJECT_CAPLETS` is enabled
-  - `--json` on `config paths` for scriptable output
-- Keep existing `init` and `auth` behavior unchanged.
-- Keep disabled Caplets excluded from `caplets list` unless `--all` is passed.
-
-## Interfaces
-
-Public CLI additions:
-
-```sh
-caplets --version
-caplets list
-caplets list --all
-caplets list --json
-caplets config path
-caplets config paths
-caplets config paths --json
-```
-
-Recommended text output shapes:
-
-```txt
-server  backend  status       name
-docs    mcp      not_started  Hosted Docs
-users   openapi  not_started  Users API
-```
-
-```txt
-userConfig: /home/you/.caplets/config.json
-projectConfig: /repo/.caplets/config.json
-userRoot: /home/you/.caplets
-projectRoot: /repo/.caplets
-authDir: /home/you/.caplets/auth
-envConfig: unset
-projectCapletsTrusted: false
-```
-
-## Test Plan
-
-Add focused tests in `test/cli.test.ts`:
-
-- `runCli(["--version"])` prints `package.json` version and does not throw.
-- `runCli(["list"])` prints only enabled MCP/OpenAPI/GraphQL Caplets.
-- `runCli(["list", "--all"])` includes disabled Caplets with `disabled` status.
-- `runCli(["list", "--json"])` emits parseable JSON and redacts/no-ops on auth secrets.
-- `runCli(["config", "path"])` honors `CAPLETS_CONFIG`.
-- `runCli(["config", "paths", "--json"])` returns stable resolved paths and env/trust flags.
-- Unsupported options still raise `REQUEST_INVALID`.
-
-Run:
-
-```sh
-pnpm format:check
-pnpm lint
-pnpm typecheck
-pnpm test
-pnpm build
-```
-
-## Assumptions
-
-- "Servers" means all configured Caplet backends: MCP servers, OpenAPI endpoints, and GraphQL endpoints.
-- Human-readable text is the default; `--json` is the stable automation contract.
-- The inspection commands must be read-only and must not start downstream servers, load remote specs, or validate live OAuth.
-- `caplets serve` remains handled by `src/index.ts` as the MCP server entrypoint.
diff --git a/docs/plans/2026-05-12-graphql-backend.md b/docs/plans/2026-05-12-graphql-backend.md
deleted file mode 100644
index c44b44ac..00000000
--- a/docs/plans/2026-05-12-graphql-backend.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# GraphQL Backend Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a native GraphQL backend to Caplets, with OAuth/OIDC discovery support shared by GraphQL and OpenAPI.
-
-**Architecture:** Caplets gains a third backend family, `graphql`, alongside MCP and OpenAPI. GraphQL endpoints expose the same Caplet wrapper operations and use either configured GraphQL documents or generated tools from schema root fields. Auth is generalized so `caplets auth login/list/logout` works for OAuth/OIDC MCP, OpenAPI, and GraphQL Caplets.
-
-**Tech Stack:** TypeScript ESM, Node.js 22+, `@modelcontextprotocol/sdk`, GraphQL.js, Zod, Vitest, rolldown, oxfmt, oxlint.
-
----
-
-## Task 1: Add GraphQL Config And Caplet File Support
-
-**Files:**
-
-- Modify: `package.json`
-- Modify: `src/config.ts`
-- Modify: `src/caplet-files.ts`
-- Modify: `src/registry.ts`
-- Modify: `scripts/generate-config-schema.ts`
-- Modify: `schemas/caplets-config.schema.json`
-- Modify: `schemas/caplet.schema.json`
-- Test: `test/config.test.ts`
-- Test: `test/registry.test.ts`
-
-- [x] Add `graphql` as a runtime dependency.
-- [x] Add top-level `graphqlEndpoints` config keyed by Caplet ID.
-- [x] Add Markdown frontmatter key `graphqlEndpoint`.
-- [x] Validate exactly one GraphQL schema source: `schemaPath`, `schemaUrl`, or `introspection: true`.
-- [x] Add optional `operations` map, where each operation has exactly one of `document` or `documentPath`, plus optional `operationName` and `description`.
-- [x] Support GraphQL auth types `none`, `bearer`, `headers`, `oauth2`, and `oidc`.
-- [x] Extend OpenAPI auth to support `oauth2` and `oidc`.
-- [x] Reject duplicate Caplet IDs across `mcpServers`, `openapiEndpoints`, and `graphqlEndpoints`.
-- [x] Reject untrusted project `graphqlEndpoints`, matching OpenAPI project-config safety.
-- [x] Update safe `get_caplet` detail and capability descriptions for GraphQL.
-- [x] Regenerate committed JSON schemas.
-
-## Task 2: Generalize OAuth/OIDC Auth
-
-**Files:**
-
-- Modify: `src/auth.ts`
-- Modify: `src/cli.ts`
-- Modify: `src/downstream.ts`
-- Modify: `src/openapi.ts`
-- Test: `test/auth.test.ts`
-- Test: `test/cli.test.ts`
-- Test: `test/openapi.test.ts`
-
-- [x] Add shared auth target typing for MCP remote servers, OpenAPI endpoints, and GraphQL endpoints.
-- [x] Keep existing MCP SDK OAuth flow for MCP remote servers.
-- [x] Add generic authorization-code-with-PKCE OAuth/OIDC flow for OpenAPI and GraphQL.
-- [x] Support OAuth Protected Resource Metadata discovery (`/.well-known/oauth-protected-resource`).
-- [x] Support OAuth Authorization Server Metadata discovery (`/.well-known/oauth-authorization-server`).
-- [x] Support OIDC discovery fallback (`/.well-known/openid-configuration`).
-- [x] Support dynamic client registration when `registration_endpoint` is advertised and no `clientId` is configured.
-- [x] For `auth.type: "oidc"`, include `openid` and default scopes to `openid profile email` unless scopes are configured.
-- [x] Store access tokens, refresh tokens, optional ID tokens, expiry, scope, issuer, subject, discovered metadata, and dynamic client info in token bundles.
-- [x] Ensure `caplets auth login/list/logout <caplet>` finds OAuth/OIDC MCP, OpenAPI, and GraphQL Caplets without printing secrets.
-- [x] Apply OAuth/OIDC access tokens to OpenAPI requests and remote spec loading.
-
-## Task 3: Implement GraphQL Manager
-
-**Files:**
-
-- Create: `src/graphql.ts`
-- Modify: `src/tools.ts`
-- Modify: `src/index.ts`
-- Test: `test/graphql.test.ts`
-- Test: `test/tools.test.ts`
-
-- [x] Load schemas from SDL files, introspection JSON files, remote schema files, or endpoint introspection.
-- [x] Validate configured GraphQL documents using GraphQL.js `parse` and `validate`.
-- [x] Convert configured operations into MCP-style tool metadata.
-- [x] When `operations` is omitted or empty, auto-generate tools from root `Query` and `Mutation` fields.
-- [x] Name auto-generated tools `query_<field>` and `mutation_<field>`.
-- [x] Generate bounded scalar-leaf selection sets with `__typename`, skipping nested fields that require arguments.
-- [x] Use default selection depth `2`; reject values above `5`.
-- [x] Convert GraphQL variables and auto-generated root field arguments into JSON Schema input schemas.
-- [x] Execute GraphQL calls with POST `{ query, variables, operationName }`.
-- [x] Return structured HTTP/GraphQL responses and mark `isError` for non-2xx HTTP responses or GraphQL `errors`.
-- [x] Add read-only annotations for query tools and destructive annotations for mutation tools.
-- [x] Enforce HTTPS except loopback, redirect rejection, request timeouts, response-size limits, and redacted auth failures.
-
-## Task 4: Documentation And Verification
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `docs/product/caplets-progressive-mcp-disclosure-prd.md`
-- Modify: `docs/plans/2026-05-12-graphql-backend.md`
-
-- [x] Document `graphqlEndpoints` JSON config and `graphqlEndpoint` Caplet files.
-- [x] Document configured-operation and auto-generated GraphQL modes.
-- [x] Document OAuth/OIDC discovery and `caplets auth` support across backends.
-- [x] Run `pnpm install`.
-- [x] Run `pnpm schema:generate`.
-- [x] Run `pnpm verify`.
-
-## Assumptions
-
-- Auto-generation includes queries and mutations by default when no operations are configured.
-- Auto-generated tools use generated selection sets only; callers do not pass custom `selectionSet` in v1.
-- Configured GraphQL `call_tool.arguments` is the variables object directly.
-- Auto-generated GraphQL `call_tool.arguments` is the root field arguments object directly.
-- GraphQL subscriptions are out of scope for v1.
-- `oidc` means browser authorization-code flow with PKCE plus OIDC discovery and ID token storage.
-- Caplets stores OIDC ID tokens for identity/status, but downstream OpenAPI/GraphQL calls use access tokens by default.
diff --git a/docs/plans/2026-05-12-hot-reload.md b/docs/plans/2026-05-12-hot-reload.md
deleted file mode 100644
index 971117b6..00000000
--- a/docs/plans/2026-05-12-hot-reload.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# Hot Reload Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make normal `caplets serve` reload config and Caplet file changes without restarting the Caplets MCP process.
-
-**Architecture:** Introduce an in-process runtime controller that owns the MCP server, registered top-level tool handles, the current registry, backend managers, and filesystem watchers. Reloads parse the effective config exactly as startup does, update registered MCP tools through `RegisteredTool` handles, invalidate only affected backend caches, and keep the last known-good config active when a reload fails.
-
-**Tech Stack:** TypeScript, Node.js `fs.watch`, `@modelcontextprotocol/sdk` `McpServer.registerTool`, Vitest.
-
----
-
-## Task 1: Runtime Controller
-
-**Files:**
-
-- Create: `src/runtime.ts`
-- Modify: `src/index.ts`
-- Test: `test/runtime.test.ts`
-
-- [ ] Add `CapletsRuntime` that creates `McpServer`, `ServerRegistry`, `DownstreamManager`, `OpenApiManager`, and `GraphQLManager`.
-- [ ] Track registered top-level Caplet tools in a `Map<string, RegisteredTool>`.
-- [ ] Register initial enabled Caplets during startup.
-- [ ] Keep `src/index.ts` as a small CLI/server entrypoint.
-
-## Task 2: Reload Reconciliation
-
-**Files:**
-
-- Modify: `src/runtime.ts`
-- Modify: `src/downstream.ts`
-- Modify: `src/openapi.ts`
-- Modify: `src/graphql.ts`
-- Test: `test/runtime.test.ts`, `test/downstream.test.ts`, `test/openapi.test.ts`, `test/graphql.test.ts`
-
-- [ ] On reload, call existing `loadConfig()` with the same resolved paths used at startup.
-- [ ] Add new Caplets with `registerTool`.
-- [ ] Update existing Caplets with `RegisteredTool.update`.
-- [ ] Remove missing or disabled Caplets with `RegisteredTool.remove`.
-- [ ] Add `DownstreamManager.closeServer(serverId)`.
-- [ ] Add `OpenApiManager.invalidate(serverId)` and `GraphQLManager.invalidate(serverId)`.
-- [ ] Invalidate or close only backends whose normalized config changed.
-- [ ] Keep serving the previous registry and tools if reload parsing or validation fails.
-
-## Task 3: Filesystem Watching
-
-**Files:**
-
-- Modify: `src/runtime.ts`
-- Test: `test/runtime.test.ts`
-
-- [ ] Watch the effective user config file, project config file, user Caplets root, and trusted project Caplets root.
-- [ ] Use dependency-free `fs.watch` with a 250 ms debounce.
-- [ ] Watch directories so new, renamed, and deleted Markdown Caplet files are detected.
-- [ ] Recreate watchers after every successful reload because roots can change with `CAPLETS_CONFIG`.
-- [ ] Close all watchers during runtime shutdown.
-
-## Task 4: Documentation
-
-**Files:**
-
-- Modify: `README.md`
-
-- [ ] Document that `caplets serve` hot reloads config and Caplet file changes by default.
-- [ ] Document last known-good behavior for invalid edits.
-- [ ] Document that changed or removed MCP-backed Caplets close only their affected downstream connection.
-- [ ] Keep `pnpm dev` documented as source rebuild/restart tooling, separate from runtime config hot reload.
-
-## Task 5: Verification
-
-**Files:**
-
-- Modify tests as needed.
-
-- [ ] Run targeted tests for runtime reload and manager invalidation.
-- [ ] Run `pnpm format:check`.
-- [ ] Run `pnpm lint`.
-- [ ] Run `pnpm typecheck`.
-- [ ] Run `pnpm schema:check`.
-- [ ] Run `pnpm test`.
-- [ ] Run `pnpm build`.
diff --git a/docs/plans/2026-05-12-mcp-backed-caplet-files.md b/docs/plans/2026-05-12-mcp-backed-caplet-files.md
deleted file mode 100644
index be75b815..00000000
--- a/docs/plans/2026-05-12-mcp-backed-caplet-files.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# MCP-Backed Caplet Files Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
-
-**Goal:** Add skill-like Markdown Caplet files while keeping every Caplet backed by exactly one MCP server.
-
-**Architecture:** Caplets remain executable MCP capability wrappers, not standalone skills. Existing `config.json` entries are normalized into Caplets, and Markdown files add richer capability cards with required `mcpServer` frontmatter. Runtime operations become Caplet-first: `get_caplet` and `check_mcp_server` replace `get_server` and `check_server`.
-
-**Tech Stack:** TypeScript ESM, Node.js 22+, `@modelcontextprotocol/sdk`, Zod, `vfile-matter`, Vitest, rolldown, oxfmt, oxlint.
-
----
-
-## Task 1: Add Caplet File Loading
-
-**Files:**
-
-- Modify: `package.json`
-- Modify: `src/config.ts`
-- Create: `src/caplet-files.ts`
-- Test: `test/config.test.ts`
-
-- [x] Add the `vfile-matter` runtime dependency.
-- [x] Create a Caplet frontmatter schema that requires fenced YAML frontmatter with `name`, `description`, and `mcpServer`.
-- [x] Discover top-level `*.md` files and one-level `*/CAPLET.md` files under both the user Caplets directory and project `.caplets` directory.
-- [x] Derive IDs from paths: `github.md` -> `github`, `linear/CAPLET.md` -> `linear`.
-- [x] Reject duplicate Caplet IDs within the same root.
-- [x] Normalize Caplet files into the existing `mcpServers` map shape, with `name` and `description` outside `mcpServer`.
-- [x] Merge source precedence as user config, user Caplet files, project config, trusted project Caplet files.
-- [x] Preserve Markdown body and `tags` on normalized Caplet config.
-- [x] Add tests for loading top-level and directory Caplets, project override precedence, same-ID config override, missing `mcpServer`, and duplicate IDs.
-
-## Task 2: Rename Runtime Operations To Caplet-First Language
-
-**Files:**
-
-- Modify: `src/tools.ts`
-- Modify: `src/registry.ts`
-- Modify: `src/index.ts`
-- Test: `test/tools.test.ts`
-- Test: `test/registry.test.ts`
-- Test: `test/benchmark.test.ts`
-
-- [x] Rename operation `get_server` to `get_caplet`.
-- [x] Rename operation `check_server` to `check_mcp_server`.
-- [x] Do not keep compatibility aliases for old operation names.
-- [x] Update request validation, operation descriptions, examples, errors, and tests.
-- [x] Return full Caplet detail from `get_caplet`, including `caplet`, `name`, `description`, optional `tags`, optional `body`, and safe `mcpServer` metadata. Do not expose local source paths.
-- [x] Ensure `get_caplet` does not start or probe the downstream MCP server.
-- [x] Keep `list_tools`, `search_tools`, `get_tool`, and `call_tool` behavior unchanged.
-
-## Task 3: Add Caplet Schema Generation
-
-**Files:**
-
-- Modify: `src/config.ts`
-- Modify: `scripts/generate-config-schema.ts`
-- Create: `schemas/caplet.schema.json`
-- Test: `test/config.test.ts`
-
-- [x] Export a generated JSON Schema for Caplet frontmatter.
-- [x] Update schema generation/checking to maintain both `schemas/caplets-config.schema.json` and `schemas/caplet.schema.json`.
-- [x] Add a drift test for the committed Caplet schema.
-- [x] Run schema generation after implementation.
-
-## Task 4: Update CLI Starters And Documentation
-
-**Files:**
-
-- Modify: `src/cli.ts`
-- Modify: `README.md`
-- Modify: `docs/product/caplets-progressive-mcp-disclosure-prd.md`
-- Test: `test/cli.test.ts`
-
-- [x] Keep `caplets init` writing the existing plain `config.json` starter.
-- [x] Add README documentation for Markdown Caplet files and directory Caplets.
-- [x] Document that every Caplet file must include `mcpServer`; serverless Caplets are out of scope.
-- [x] Update documented operations to `get_caplet` and `check_mcp_server`.
-- [x] Ensure CLI tests still validate starter config behavior.
-
-## Task 5: Verification And Final Review
-
-**Files:**
-
-- All touched files.
-
-- [x] Run `pnpm install` if the lockfile needs the new `vfile-matter` dependency.
-- [x] Run `pnpm format:check`.
-- [x] Run `pnpm lint`.
-- [x] Run `pnpm typecheck`.
-- [x] Run `pnpm schema:check`.
-- [x] Run `pnpm test`.
-- [x] Run `pnpm build`.
-- [x] Perform a final review for secret leakage in `get_caplet` safe backend metadata.
diff --git a/docs/plans/2026-05-13-http-actions-backend.md b/docs/plans/2026-05-13-http-actions-backend.md
deleted file mode 100644
index 69bdff2c..00000000
--- a/docs/plans/2026-05-13-http-actions-backend.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# HTTP Actions Backend Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a native HTTP actions backend for non-OpenAPI APIs, where each Caplet exposes explicitly configured HTTP actions as discoverable tools.
-
-**Architecture:** Caplets gains a fourth backend family, `http`, alongside MCP, OpenAPI, and GraphQL. HTTP action Caplets define a `baseUrl`, auth, timeout/output limits, and a map of named actions. Each action becomes one MCP-style tool. Calls build an HTTP request from structured argument mappings, execute it directly, and return structured status, headers, body, and timing data.
-
-**Tech Stack:** TypeScript ESM, Node.js 22+, `@modelcontextprotocol/sdk`, Zod, Vitest, rolldown, oxfmt, oxlint.
-
----
-
-## Task 1: Add HTTP Actions Config And Caplet File Support
-
-**Files:**
-
-- Modify: `src/config.ts`
-- Modify: `src/caplet-files.ts`
-- Modify: `scripts/generate-config-schema.ts` if needed
-- Modify: `schemas/caplets-config.schema.json`
-- Modify: `schemas/caplet.schema.json`
-- Test: `test/config.test.ts`
-
-- [x] Add `HttpApiConfig` and `HttpActionConfig` types.
-- [x] Add top-level `httpApis` config keyed by Caplet ID.
-- [x] Add Markdown frontmatter key `httpApi`.
-- [x] Keep v1 explicit-config-only: no discovery, imports, or manifests.
-- [x] Require `baseUrl`, `auth`, and at least one action.
-- [x] Support auth types `none`, `bearer`, `headers`, `oauth2`, and `oidc`, matching OpenAPI/GraphQL.
-- [x] Validate HTTPS except loopback for `baseUrl`.
-- [x] Reject duplicate Caplet IDs across `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, and `httpApis`.
-- [x] Reject untrusted project `httpApis`, matching OpenAPI/GraphQL project-config safety.
-- [x] Normalize relative Caplet/config local paths only where needed; HTTP paths are URL paths, not filesystem paths.
-- [x] Regenerate committed JSON schemas.
-
-## Task 2: Implement HTTP Actions Manager
-
-**Files:**
-
-- Create: `src/http-actions.ts`
-- Modify: `src/tools.ts`
-- Modify: `src/registry.ts`
-- Modify: `src/runtime.ts`
-- Test: `test/http-actions.test.ts`
-- Test: `test/tools.test.ts`
-- Test: `test/registry.test.ts`
-- Test: `test/runtime.test.ts`
-
-- [x] Create `HttpActionManager` with `checkApi`, `listTools`, `getTool`, `callTool`, `compact`, `search`, and `invalidate` methods.
-- [x] Convert configured actions into MCP-style tools using each action's `inputSchema`.
-- [x] Support HTTP methods `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
-- [x] Build URLs from `baseUrl` plus action `path`, preserving origin and rejecting origin changes.
-- [x] Resolve `{field}` path placeholders from `call_tool.arguments` and URL-encode values.
-- [x] Support `query`, `headers`, and `jsonBody` mappings.
-- [x] Support mapping values as literals, nested arrays/objects, `$input.field` references, and `$input` for the full argument object.
-- [x] Reject forbidden request headers such as `authorization`, `host`, `content-length`, `connection`, and `content-type` when user-configured headers would conflict with managed headers.
-- [x] Apply static bearer/header auth and generic OAuth/OIDC headers.
-- [x] Reject redirects.
-- [x] Enforce request timeouts and maximum response byte limits.
-- [x] Return structured `{ status, statusText, headers, body, elapsedMs }` responses and mark `isError` for non-2xx status.
-- [x] Redact secrets from errors.
-- [x] Route `backend: "http"` through generated Caplet operations.
-- [x] Add safe registry detail for HTTP APIs without exposing `baseUrl`, auth, or sensitive mappings.
-- [x] Include HTTP APIs in runtime registration, reload comparison, and cache invalidation.
-
-## Task 3: Documentation And Verification
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `docs/product/caplets-progressive-mcp-disclosure-prd.md`
-- Modify: `docs/plans/2026-05-13-http-actions-backend.md`
-
-- [x] Document `httpApis` JSON config and `httpApi` Caplet files.
-- [x] Document explicit action configuration, request mappings, auth support, and safety constraints.
-- [x] Document response shape and error behavior.
-- [x] Run `pnpm schema:generate`.
-- [x] Run `pnpm format:check`.
-- [x] Run `pnpm lint`.
-- [x] Run `pnpm typecheck`.
-- [x] Run `pnpm schema:check`.
-- [x] Run `pnpm test`.
-- [x] Run `pnpm build`.
-
-## Assumptions
-
-- The top-level config key is `httpApis` and Caplet file key is `httpApi`.
-- Runtime backend discriminator is `backend: "http"`.
-- `check_backend` validates configured actions and returns a tool count without making network calls.
-- v1 does not support action discovery, imports, manifests, raw shell/curl execution, form bodies, file upload, streaming, cookies, or custom redirect following.
-- `inputSchema` defaults to `{ "type": "object", "additionalProperties": true }` when omitted.
-- JSON request bodies set `content-type: application/json` automatically when `jsonBody` is configured.
-- HTTP response parsing matches OpenAPI behavior: JSON content is parsed as JSON; other content is text.
diff --git a/docs/plans/2026-05-13-xdg-cross-platform-paths.md b/docs/plans/2026-05-13-xdg-cross-platform-paths.md
deleted file mode 100644
index 3c14c2fe..00000000
--- a/docs/plans/2026-05-13-xdg-cross-platform-paths.md
+++ /dev/null
@@ -1,202 +0,0 @@
-# XDG and Cross-Platform Paths Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Move Caplets user config to XDG/standard platform config locations and OAuth state to XDG/standard platform state locations.
-
-**Architecture:** Centralize all default user paths in `src/config/paths.ts`, then consume those shared defaults from config loading, CLI inspection, installation, runtime, and auth storage. Project-local `./.caplets` behavior stays unchanged because it is project state, not user state. `CAPLETS_CONFIG` remains the explicit config override, and internal/test `authDir` overrides remain supported.
-
-**Tech Stack:** Node.js 22, TypeScript, Vitest, Commander, Caplets existing config/auth modules.
-
----
-
-## Target Paths
-
-| Platform         | Config                                              | State/Auth                                                     |
-| ---------------- | --------------------------------------------------- | -------------------------------------------------------------- |
-| Linux/macOS/Unix | `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` | `${XDG_STATE_HOME:-~/.local/state}/caplets/auth/<server>.json` |
-| Windows          | `%APPDATA%\\caplets\\config.json`                   | `%LOCALAPPDATA%\\caplets\\auth\\<server>.json`                 |
-| Override         | `CAPLETS_CONFIG=/custom/config.json` wins           | Existing `authDir` option wins                                 |
-
-XDG environment variables must be absolute. Relative `XDG_CONFIG_HOME` and `XDG_STATE_HOME` values are ignored.
-
-## File Structure
-
-- Modify: `src/config/paths.ts` - own all platform-specific default path resolution.
-- Modify: `src/auth/store.ts` - use the shared default auth directory instead of hard-coding `~/.caplets/auth`.
-- Modify: `src/cli/inspection.ts` - expose the split config and state roots in `caplets config paths`.
-- Modify: `test/config.test.ts` or create `test/config-paths.test.ts` - cover path helper behavior.
-- Modify: `test/cli.test.ts` - update path inspection expectations.
-- Modify: `README.md` - document XDG and Windows paths.
-- Modify: `docs/product/caplets-progressive-mcp-disclosure-prd.md` - update product/default path references.
-- Create: `.changeset/<name>.md` - note the pre-1.0 default location change.
-
-### Task 1: Platform-Aware Path Helpers
-
-**Files:**
-
-- Modify: `src/config/paths.ts`
-- Test: `test/config-paths.test.ts`
-
-- [ ] **Step 1: Write path helper tests**
-
-Add tests that call injectable helper functions with explicit environment, home, and platform inputs. Cover Unix defaults, Unix XDG overrides, ignored relative XDG overrides, Windows environment defaults, and Windows homedir fallbacks.
-
-- [ ] **Step 2: Run path helper tests to verify they fail**
-
-Run: `pnpm vitest run test/config-paths.test.ts`
-
-Expected: FAIL because the injectable helpers do not exist yet.
-
-- [ ] **Step 3: Implement path helpers**
-
-In `src/config/paths.ts`, add exported helpers equivalent to:
-
-```ts
-type Platform = NodeJS.Platform;
-type PathEnv = NodeJS.ProcessEnv;
-
-export function defaultConfigBaseDir(
-  env: PathEnv = process.env,
-  home = homedir(),
-  platform: Platform = process.platform,
-): string {
-  if (platform === "win32") {
-    return env.APPDATA && isAbsolute(env.APPDATA) ? env.APPDATA : join(home, "AppData", "Roaming");
-  }
-  return env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME)
-    ? env.XDG_CONFIG_HOME
-    : join(home, ".config");
-}
-
-export function defaultStateBaseDir(
-  env: PathEnv = process.env,
-  home = homedir(),
-  platform: Platform = process.platform,
-): string {
-  if (platform === "win32") {
-    return env.LOCALAPPDATA && isAbsolute(env.LOCALAPPDATA)
-      ? env.LOCALAPPDATA
-      : join(home, "AppData", "Local");
-  }
-  return env.XDG_STATE_HOME && isAbsolute(env.XDG_STATE_HOME)
-    ? env.XDG_STATE_HOME
-    : join(home, ".local", "state");
-}
-
-export function defaultConfigPath(...): string {
-  return join(defaultConfigBaseDir(...), "caplets", "config.json");
-}
-
-export function defaultAuthDir(...): string {
-  return join(defaultStateBaseDir(...), "caplets", "auth");
-}
-```
-
-Keep exported `DEFAULT_CONFIG_PATH` and `DEFAULT_AUTH_DIR`, but define them from the new functions.
-
-- [ ] **Step 4: Run path helper tests to verify they pass**
-
-Run: `pnpm vitest run test/config-paths.test.ts`
-
-Expected: PASS.
-
-### Task 2: Auth Store Uses State Directory
-
-**Files:**
-
-- Modify: `src/auth/store.ts`
-- Test: `test/auth.test.ts`
-
-- [ ] **Step 1: Write or update auth default tests**
-
-Add coverage proving `authStorePath("remote")` resolves under the shared default auth dir. Keep traversal rejection coverage intact.
-
-- [ ] **Step 2: Run auth tests to verify they fail before implementation**
-
-Run: `pnpm vitest run test/auth.test.ts`
-
-Expected: FAIL if the test expects the new default while the auth store still hard-codes `~/.caplets/auth`.
-
-- [ ] **Step 3: Update auth store default**
-
-Import `DEFAULT_AUTH_DIR` from `../config/paths.js`, remove direct `homedir()` usage, and use `DEFAULT_AUTH_DIR` in `authStorePath` and `listTokenBundles` defaults.
-
-- [ ] **Step 4: Run auth tests to verify they pass**
-
-Run: `pnpm vitest run test/auth.test.ts`
-
-Expected: PASS.
-
-### Task 3: CLI Path Inspection
-
-**Files:**
-
-- Modify: `src/cli/inspection.ts`
-- Modify: `test/cli.test.ts`
-
-- [ ] **Step 1: Update CLI path inspection tests**
-
-Update `caplets config paths --json` expectations to include `stateRoot`, and verify `authDir` can still be overridden by the internal test `authDir` option.
-
-- [ ] **Step 2: Run CLI tests to verify they fail before implementation**
-
-Run: `pnpm vitest run test/cli.test.ts`
-
-Expected: FAIL because `stateRoot` is not present yet.
-
-- [ ] **Step 3: Update inspection output**
-
-Import `defaultStateBaseDir` if needed, add `stateRoot: dirname(authDir ?? DEFAULT_AUTH_DIR)` or equivalent root reporting, and update human `formatConfigPaths` output.
-
-- [ ] **Step 4: Run CLI tests to verify they pass**
-
-Run: `pnpm vitest run test/cli.test.ts`
-
-Expected: PASS.
-
-### Task 4: Documentation and Changeset
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `docs/product/caplets-progressive-mcp-disclosure-prd.md`
-- Create: `.changeset/<name>.md`
-
-- [ ] **Step 1: Update README paths**
-
-Replace default user config references with `~/.config/caplets/config.json`, auth state references with `~/.local/state/caplets/auth/<server>.json`, and include Windows `%APPDATA%\\caplets\\config.json` and `%LOCALAPPDATA%\\caplets\\auth` equivalents.
-
-- [ ] **Step 2: Update PRD path references**
-
-Update all user-level path references from `~/.caplets` to the new split config/state locations. Keep project `./.caplets` references unchanged.
-
-- [ ] **Step 3: Add changeset**
-
-Create a minor changeset explaining that default config and OAuth token state locations now follow XDG and Windows platform conventions.
-
-- [ ] **Step 4: Check docs for stale user path references**
-
-Run a content search for `~/.caplets` and `.caplets/auth` and update stale default-user references only. Existing historical plans may remain unchanged if they describe already-completed old work.
-
-### Task 5: Full Verification and Review
-
-**Files:**
-
-- Verify all modified files.
-
-- [ ] **Step 1: Run targeted tests**
-
-Run: `pnpm vitest run test/config-paths.test.ts test/config.test.ts test/cli.test.ts test/auth.test.ts`
-
-Expected: PASS.
-
-- [ ] **Step 2: Run full verification**
-
-Run: `pnpm verify`
-
-Expected: PASS.
-
-- [ ] **Step 3: Review changed diff**
-
-Inspect the final diff for accidental compatibility fallback to `~/.caplets`, stale docs, or unrelated changes.
diff --git a/docs/plans/2026-05-14-cli-tools-backend.md b/docs/plans/2026-05-14-cli-tools-backend.md
deleted file mode 100644
index 64470402..00000000
--- a/docs/plans/2026-05-14-cli-tools-backend.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# CLI Tools Backend For Caplets
-
-## Summary
-
-Add a fifth backend, `cliTools`, that exposes curated command-line workflows as typed Caplets tools. Runtime execution is deterministic and shell-free: Caplets maps declared JSON inputs into `spawn(command, args)` calls, returns bounded structured results, and never exposes arbitrary bash.
-
-Also add `caplets author cli` to generate reviewable CLI Caplet manifests from repo/package metadata and curated templates for `git`, `gh`, and the detected package manager. Generation prints to stdout by default.
-
-## Key Changes
-
-- Add `cliTools` to config and Caplet frontmatter alongside `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, and `httpApis`.
-- Use an `actions` map shape, mirroring `httpApis.actions`:
-  - action key is the downstream tool name.
-  - each action supports `description`, `inputSchema`, optional `outputSchema`, `command`, `args`, `env`, `cwd`, `timeoutMs`, `maxOutputBytes`, `output`, and MCP annotations.
-- Execute with `spawn(command, args)` only; no shell mode in v1.
-- Support `$input.foo` interpolation inside argv/env/cwd strings.
-- Apply basic runtime input validation for required fields and primitive JSON Schema types before spawning.
-- Default limits: `timeoutMs: 60000`, `maxOutputBytes: 1000000`, configurable at Caplet and action level.
-- Return CLI results as structured content:
-  - `{ exitCode, stdout, stderr, elapsedMs }`
-  - `isError: true` for non-zero exits.
-  - optional stdout JSON parsing when `output.type: "json"` is declared.
-- `check_backend` validates manifest shape, cwd/env resolution, command availability, and tool count without running configured actions.
-- `list_tools`, `search_tools`, `get_tool`, `call_tool`, and field selection should work consistently with existing backends.
-- Load user-root CLI Caplets normally; load project `.caplets` CLI Caplets only under the existing `CAPLETS_TRUST_PROJECT_CAPLETS` gate.
-
-## Authoring UX
-
-- Add `caplets author cli <id>` with scriptable flags:
-  - `--repo <path>` to inspect a repository.
-  - `--include git,gh,package` to choose generators/templates.
-  - `--command <name>` for single-CLI generation.
-  - `--output -` by default, with explicit file output supported.
-- Heuristic generator only in v1; no OpenAI/API/agent dependency.
-- Repo workflow generation should inspect package scripts and lockfiles, then generate safe tools such as test, lint, typecheck, build, repo status, changed files, and PR status when applicable.
-- Single-CLI templates should cover `git`, `gh`, and detected package manager commands.
-- Generated manifests must be explicit Markdown Caplet files with `cliTools`, not hidden runtime state.
-
-## Docs And Examples
-
-- Update README config docs, Caplet file docs, generated schemas, and backend operation docs.
-- Add real bundled CLI examples under `caplets/`, focused on repo maintenance and GitHub workflows.
-- Examples should be safe/read-oriented by default; mutating actions must carry clear annotations such as `readOnlyHint: false` and `destructiveHint` where appropriate.
-
-## Test Plan
-
-- Config tests for `cliTools`, duplicate IDs across all five backend maps, Caplet frontmatter loading, project trust behavior, defaults, limits, and invalid command/action shapes.
-- CLI manager tests for list/search/get/call, input interpolation, basic validation, JSON output parsing, non-zero exit handling, timeout handling, output byte limits, command-not-found errors, cwd/env behavior, and secret redaction.
-- Runtime/registry tests for `cliTools` registration, `check_backend`, reload invalidation, and `caplets list`.
-- Authoring tests for stdout output, explicit output path, package-script detection, `git`/`gh` templates, package manager detection, and generated Caplet validation.
-- Schema check, typecheck, focused tests, full `pnpm verify`.
-
-## Assumptions
-
-- V1 intentionally excludes shell snippets, conditional argv construction, full JSON Schema validation, LLM-assisted generation, and automatic installation into the user Caplets root.
-- Complex workflows should be modeled as package scripts or wrapper executables, then called through typed `cliTools` actions.
-- Caplets surfaces risk annotations but does not block declared mutating tools at runtime; client approval remains outside Caplets.
diff --git a/docs/plans/2026-05-14-coding-agent-benchmarks.md b/docs/plans/2026-05-14-coding-agent-benchmarks.md
deleted file mode 100644
index fa41e689..00000000
--- a/docs/plans/2026-05-14-coding-agent-benchmarks.md
+++ /dev/null
@@ -1,366 +0,0 @@
-# Coding Agent Benchmarks Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use `subagent-driven-development` or `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add reproducible deterministic and opt-in live coding-agent benchmarks comparing Caplets against non-Caplets MCP exposure so README claims have measurable evidence.
-
-**Architecture:** Build a benchmark fixture suite with synthetic coding-agent tasks, mock MCP servers, deterministic context-surface analysis, and live agent runners. Pi is the primary live runner, with OpenCode supported through the same adapter interface when available.
-
-**Tech Stack:** Node 22+, Vitest, MCP SDK, existing Caplets CLI/runtime, Pi CLI, OpenCode CLI, JSON/Markdown reports.
-
----
-
-## Architectural Decisions
-
-- Benchmark both **direct/flat MCP** and **Pi proxy baseline** against **Caplets progressive disclosure**.
-- Keep deterministic benchmarks in normal CI because they are fast, stable, and credential-free.
-- Keep live LLM agent benchmarks opt-in via `pnpm benchmark:live` because they require installed agents, credentials, and model-dependent behavior.
-- Use local mock MCP servers so benchmark tasks are reproducible and do not depend on GitHub, Linear, docs sites, or network APIs.
-- Score live runs by observable task success, not subjective transcript quality.
-- Produce machine-readable JSON reports plus Markdown summaries consumed by README.
-- Design runner adapters for `pi` and `opencode`; make Pi the default live target.
-
----
-
-## Proposed Files
-
-- Create `benchmarks/fixtures/coding-agent-workspace/`: small repo fixture copied into temp dirs for each run.
-- Create `benchmarks/fixtures/mcp-server.mjs`: deterministic mock MCP server exposing many realistic coding tools.
-- Create `benchmarks/fixtures/tasks.json`: benchmark tasks, expected file changes, validation commands, and required MCP facts.
-- Create `benchmarks/lib/surface.mjs`: direct vs Caplets tool payload metrics.
-- Create `benchmarks/lib/live-agent.mjs`: shared live runner types and process helpers.
-- Create `benchmarks/lib/pi-runner.mjs`: Pi live runner.
-- Create `benchmarks/lib/opencode-runner.mjs`: OpenCode live runner.
-- Create `benchmarks/lib/scoring.mjs`: validation, transcript, and metric scoring.
-- Create `benchmarks/run-deterministic.mjs`: deterministic report generator/checker.
-- Create `benchmarks/run-live.mjs`: opt-in live benchmark matrix runner.
-- Create `docs/benchmarks/coding-agent.md`: committed benchmark report.
-- Modify `README.md`: add benchmark/value section.
-- Modify `package.json`: add benchmark scripts.
-- Modify `.gitignore`: ignore local live benchmark output.
-- Modify or replace `test/benchmark.test.ts`: assert deterministic benchmark invariants and report freshness.
-
----
-
-## Benchmark Matrix
-
-| Mode          | Agent    | MCP Exposure           | Purpose                        |
-| ------------- | -------- | ---------------------- | ------------------------------ |
-| deterministic | none     | direct flat vs Caplets | CI-safe context/value proof    |
-| live          | Pi       | direct flat            | Classic tool-flooding baseline |
-| live          | Pi       | Pi MCP adapter proxy   | Harder competitor baseline     |
-| live          | Pi       | Caplets                | Primary Caplets result         |
-| live          | OpenCode | direct flat            | Optional second agent baseline |
-| live          | OpenCode | Caplets                | Optional second agent result   |
-
----
-
-## Metrics
-
-Deterministic metrics:
-
-- Initial tool count.
-- Initial serialized MCP `tools/list` byte size.
-- Approximate token count using `Math.ceil(bytes / 4)`.
-- Duplicate tool-name collisions in direct flat mode.
-- Candidate tools visible before task-specific discovery.
-- Expected discovery path length.
-
-Live metrics:
-
-- Task pass rate.
-- Validation command result.
-- Wall-clock duration.
-- Agent process exit code.
-- Tool-call count where available from JSON logs.
-- Transcript byte size.
-- Approximate input/output token proxy where native usage is unavailable.
-- Whether the agent selected the correct MCP capability/tool.
-- Number of failed/irrelevant MCP calls.
-
----
-
-## Task 1: Benchmark Fixture Design
-
-**Files:**
-
-- Create `benchmarks/fixtures/tasks.json`
-- Create `benchmarks/fixtures/coding-agent-workspace/package.json`
-- Create `benchmarks/fixtures/coding-agent-workspace/src/discount.js`
-- Create `benchmarks/fixtures/coding-agent-workspace/test/discount.test.js`
-- Create `benchmarks/fixtures/coding-agent-workspace/src/retry.js`
-- Create `benchmarks/fixtures/coding-agent-workspace/test/retry.test.js`
-
-- [ ] Add a small fixture repo with failing tests.
-- [ ] Add tasks that require facts available only through MCP tools.
-- [ ] Ensure each task has a deterministic validation command.
-- [ ] Keep fixture code JavaScript to avoid adding build dependencies.
-
-Example task shape:
-
-```json
-[
-  {
-    "id": "discount-policy",
-    "prompt": "Fix the discount calculation. Use the available MCP tools to inspect the current product policy before editing files. Do not hard-code test-only behavior.",
-    "validationCommand": "node --test test/discount.test.js",
-    "expectedFiles": ["src/discount.js"],
-    "requiredFact": "Premium customers receive 15% off only when the cart total is at least 100."
-  },
-  {
-    "id": "retry-policy",
-    "prompt": "Fix retry scheduling. Use the available MCP tools to inspect the retry policy before editing files.",
-    "validationCommand": "node --test test/retry.test.js",
-    "expectedFiles": ["src/retry.js"],
-    "requiredFact": "Retry delays are 100ms, 250ms, and 500ms for attempts 1 through 3."
-  }
-]
-```
-
----
-
-## Task 2: Mock MCP Server
-
-**Files:**
-
-- Create `benchmarks/fixtures/mcp-server.mjs`
-
-- [ ] Implement one configurable mock MCP server.
-- [ ] Expose realistic tool domains like `policy_search`, `policy_get`, `ticket_get`, `api_schema_get`, plus many irrelevant tools.
-- [ ] Support `--server policy`, `--server tickets`, and `--server api` modes.
-- [ ] Return deterministic structured content.
-- [ ] Include duplicate downstream tool names across servers to demonstrate collision avoidance.
-
-Representative tools:
-
-- `search`
-- `get`
-- `list_recent_changes`
-- `read_policy`
-- `lookup_schema`
-- `get_ticket`
-- `search_tickets`
-- 30 to 50 distractor tools across domains.
-
----
-
-## Task 3: Deterministic Surface Benchmark
-
-**Files:**
-
-- Create `benchmarks/lib/surface.mjs`
-- Create `benchmarks/run-deterministic.mjs`
-- Modify `test/benchmark.test.ts`
-
-- [ ] Build direct flat tool payload from mock server metadata.
-- [ ] Build Caplets top-level payload using existing `ServerRegistry` and `capabilityDescription`.
-- [ ] Compute byte and approximate token reductions.
-- [ ] Count duplicate direct tool names.
-- [ ] Assert Caplets reduces initial surface by at least the current PRD threshold: `>= 70%`.
-- [ ] Assert Caplets has zero flattened downstream tool-name collisions at top level.
-- [ ] Generate `docs/benchmarks/coding-agent.md`.
-
-Expected script:
-
-```json
-{
-  "scripts": {
-    "benchmark": "node benchmarks/run-deterministic.mjs",
-    "benchmark:check": "node benchmarks/run-deterministic.mjs --check"
-  }
-}
-```
-
----
-
-## Task 4: Live Runner Abstraction
-
-**Files:**
-
-- Create `benchmarks/lib/live-agent.mjs`
-- Create `benchmarks/lib/scoring.mjs`
-
-- [ ] Define a shared runner contract.
-- [ ] Add process execution helper using `child_process.spawn`.
-- [ ] Capture stdout, stderr, exit code, duration, and JSON events when available.
-- [ ] Add timeout handling that kills only the child process group.
-- [ ] Add validation scoring by running each task's validation command in the temp workspace.
-- [ ] Never include live benchmark execution in `pnpm verify`.
-
----
-
-## Task 5: Pi Runner
-
-**Files:**
-
-- Create `benchmarks/lib/pi-runner.mjs`
-- Create `benchmarks/live-config/pi/`
-
-- [ ] Detect `pi` CLI availability.
-- [ ] Run Pi in print/JSON mode.
-- [ ] Use isolated `PI_CODING_AGENT_DIR` per benchmark run.
-- [ ] Generate project-local MCP config for each mode: direct flat MCP, Pi MCP adapter proxy, and Caplets.
-- [ ] Require explicit env var for live runs, e.g. `CAPLETS_BENCH_LIVE=1`.
-- [ ] Record Pi version, model, and command line.
-
-Expected invocation pattern:
-
-```sh
-CAPLETS_BENCH_LIVE=1 pnpm benchmark:live -- --agent pi --model provider/model
-```
-
----
-
-## Task 6: OpenCode Runner
-
-**Files:**
-
-- Create `benchmarks/lib/opencode-runner.mjs`
-
-- [ ] Detect `opencode` CLI availability.
-- [ ] Run `opencode run --format json --model <model> --dir <workspace> <prompt>`.
-- [ ] Use isolated config/env paths where OpenCode supports them.
-- [ ] Generate MCP config for direct and Caplets modes.
-- [ ] Record OpenCode version, model, and command line.
-- [ ] Treat OpenCode as optional in the first live report if Pi is the selected primary agent.
-
-Expected invocation pattern:
-
-```sh
-CAPLETS_BENCH_LIVE=1 pnpm benchmark:live -- --agent opencode --model openai/gpt-5.5
-```
-
----
-
-## Task 7: Caplets Benchmark Mode Config
-
-**Files:**
-
-- Create `benchmarks/lib/config.mjs`
-- Use existing built `dist/index.js` or package command after `pnpm build`
-
-- [ ] Generate a temp Caplets config pointing at benchmark MCP fixture servers.
-- [ ] Start Caplets through MCP stdio from the agent config.
-- [ ] Ensure Caplets receives mock servers as downstream `mcpServers`.
-- [ ] Keep Caplets config isolated from the user's real config via `CAPLETS_CONFIG`.
-- [ ] Add cleanup for temp dirs and spawned processes.
-
----
-
-## Task 8: Live Benchmark Orchestrator
-
-**Files:**
-
-- Create `benchmarks/run-live.mjs`
-- Modify `package.json`
-
-- [ ] Parse CLI args: `--agent`, `--mode`, `--model`, `--tasks`, `--runs`, `--timeout-ms`.
-- [ ] Refuse to run unless `CAPLETS_BENCH_LIVE=1`.
-- [ ] Copy fixture workspace to a fresh temp dir per task/run/mode.
-- [ ] Run matrix: `direct-flat`, `pi-proxy` for Pi only, and `caplets`.
-- [ ] Score each run.
-- [ ] Write JSON to `benchmark-results/live/<timestamp>.json`.
-- [ ] Write Markdown summary to `benchmark-results/live/<timestamp>.md`.
-
-Expected scripts:
-
-```json
-{
-  "scripts": {
-    "benchmark:live": "node benchmarks/run-live.mjs",
-    "benchmark:live:pi": "node benchmarks/run-live.mjs --agent pi",
-    "benchmark:live:opencode": "node benchmarks/run-live.mjs --agent opencode"
-  }
-}
-```
-
----
-
-## Task 9: Reports And README
-
-**Files:**
-
-- Create `docs/benchmarks/coding-agent.md`
-- Modify `README.md`
-
-- [ ] Add a README section after the product/value description.
-- [ ] Include deterministic benchmark headline numbers.
-- [ ] Link to full benchmark report.
-- [ ] Explain live benchmarks are opt-in and model-dependent.
-- [ ] Document exact commands to reproduce.
-
-README section should be factual, not hype:
-
-```md
-## Benchmarks
-
-Caplets includes reproducible coding-agent benchmarks that compare direct MCP exposure with Caplets progressive disclosure.
-
-In the deterministic benchmark fixture, Caplets reduces the initial MCP tool surface by at least 70% versus direct flat aggregation while preserving access to every downstream tool through scoped discovery and `call_tool`.
-
-See [`docs/benchmarks/coding-agent.md`](docs/benchmarks/coding-agent.md) for methodology, fixture details, and live Pi/OpenCode benchmark instructions.
-```
-
----
-
-## Task 10: CI And Freshness Checks
-
-**Files:**
-
-- Modify `package.json`
-- Modify `.github/workflows/ci.yml` only if adding a separate benchmark check is preferable
-- Modify `test/benchmark.test.ts`
-
-- [ ] Add `pnpm benchmark:check`.
-- [ ] Include deterministic benchmark freshness either in `pnpm test` or `pnpm verify`.
-- [ ] Do not include `benchmark:live` in CI.
-- [ ] Ensure `pnpm verify` remains credential-free and deterministic.
-
-Recommended package script change:
-
-```json
-{
-  "scripts": {
-    "benchmark": "node benchmarks/run-deterministic.mjs",
-    "benchmark:check": "node benchmarks/run-deterministic.mjs --check",
-    "benchmark:live": "node benchmarks/run-live.mjs",
-    "verify": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm schema:check && pnpm test && pnpm benchmark:check && pnpm build"
-  }
-}
-```
-
----
-
-## Task 11: Validation
-
-- [ ] Run `pnpm format:check`.
-- [ ] Run `pnpm lint`.
-- [ ] Run `pnpm typecheck`.
-- [ ] Run `pnpm test`.
-- [ ] Run `pnpm benchmark`.
-- [ ] Run `pnpm benchmark:check`.
-- [ ] Run `pnpm verify`.
-
-Optional live validation:
-
-```sh
-CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:pi -- --model <provider/model> --runs 1
-CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:opencode -- --model openai/gpt-5.5 --runs 1
-```
-
-Expected:
-
-- Deterministic benchmark passes in CI.
-- Live benchmark writes local reports under `benchmark-results/live/`.
-- README links to committed deterministic report.
-- Live benchmark failures are reported as benchmark results, not test-suite failures.
-
----
-
-## Risks
-
-- Pi CLI behavior may change; isolate Pi-specific behavior behind `pi-runner.mjs`.
-- OpenCode MCP config isolation may need follow-up once exact config paths are verified.
-- Live LLM results will vary by model and date; reports must include full run metadata.
-- Comparing against `pi-mcp-adapter` is useful but could blur the value claim because it already solves some context-pressure problems. Keeping direct-flat and proxy baselines separate avoids that.
-- Tool-call counts may not be available uniformly; scoring must tolerate missing telemetry and still validate task success.
diff --git a/docs/plans/2026-05-14-output-field-selection.md b/docs/plans/2026-05-14-output-field-selection.md
deleted file mode 100644
index b71b1f9a..00000000
--- a/docs/plans/2026-05-14-output-field-selection.md
+++ /dev/null
@@ -1,262 +0,0 @@
-# Output Field Selection Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use `subagent-driven-development` or `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add `call_tool.fields` projection for MCP, OpenAPI, and HTTP tools only when the backend tool exposes an output schema.
-
-**Architecture:** Keep field selection as a wrapper-layer post-call projection over `structuredContent`. Each backend exposes `outputSchema` metadata through normal `list_tools`/`get_tool` discovery. `call_tool.fields` is accepted by the static wrapper schema, but is only valid at runtime for non-GraphQL tools with output schemas.
-
-**Tech Stack:** TypeScript, Zod, `@modelcontextprotocol/sdk`, Vitest, JSON Schema-style tool metadata.
-
----
-
-## Decisions Locked
-
-- `fields` is a top-level `call_tool` wrapper field, not part of downstream `arguments`.
-- `fields` paths target `structuredContent`.
-- HTTP/OpenAPI payload fields require explicit `body.` paths because those backends wrap responses in `{ status, statusText, headers, body }`.
-- MCP paths target the downstream MCP `structuredContent` directly.
-- GraphQL is excluded because GraphQL already has native selection sets.
-- Missing output schema is a hard `REQUEST_INVALID` error, not a no-op.
-- `list_tools`/`search_tools` compact output should include `hasOutputSchema`.
-- `get_tool` should expose actual `outputSchema` where available.
-- Projection should update both `structuredContent` and text `content` when the original result has JSON text generated from structured content.
-
----
-
-## Files To Modify
-
-- `src/tools.ts`: parse `fields`, validate operation-specific fields, route projection after backend calls.
-- `src/downstream.ts`: expose `hasOutputSchema` in compact MCP tool metadata.
-- `src/openapi.ts`: extract response schemas, attach `outputSchema`, include `hasOutputSchema`.
-- `src/http-actions.ts`: add configured `outputSchema` support, attach it to tools, include `hasOutputSchema`.
-- `src/config.ts`: add `outputSchema` to HTTP action config validation/type.
-- `schemas/caplets-config.schema.json`: regenerate after config schema changes.
-- `src/field-selection.ts`: implement schema-aware field path validation and projection.
-- `test/field-selection.test.ts`: direct projection utility coverage.
-- `test/tools.test.ts`: wrapper validation, projection routing, GraphQL rejection.
-- `test/downstream.test.ts`: MCP fixture output schema discovery and filtering.
-- `test/openapi.test.ts`: OpenAPI response schema extraction and filtering.
-- `test/http-actions.test.ts`: HTTP configured output schema and filtering.
-- `test/config.test.ts`: HTTP `outputSchema` config validation.
-- `test/fixtures/stdio-server.mjs`: add `outputSchema` to `echo`.
-
----
-
-## Public Request Shape
-
-```json
-{
-  "operation": "call_tool",
-  "tool": "read_items",
-  "arguments": { "limit": 10 },
-  "fields": ["body.items.title", "body.items.url"]
-}
-```
-
-For MCP:
-
-```json
-{
-  "operation": "call_tool",
-  "tool": "search",
-  "arguments": { "query": "mcp" },
-  "fields": ["items.title", "items.url"]
-}
-```
-
-Invalid for GraphQL:
-
-```json
-{
-  "operation": "call_tool",
-  "tool": "query_user",
-  "arguments": { "id": "42" },
-  "fields": ["body.data.user.name"]
-}
-```
-
-Expected error:
-
-```json
-{
-  "code": "REQUEST_INVALID",
-  "message": "call_tool.fields is not supported for GraphQL-backed Caplets; select fields in the GraphQL operation document instead"
-}
-```
-
----
-
-## Task 1: Add Field Selection Request Validation
-
-**Files:**
-
-- Modify: `src/tools.ts`
-- Test: `test/tools.test.ts`
-
-- [x] Add `fields` to `generatedToolInputSchema` as `z.array(z.string().min(1)).min(1).optional()`.
-- [x] Update the description to say `fields` is only valid for `call_tool` after `get_tool` shows an `outputSchema`.
-- [x] Change `validateOperationRequest` for `call_tool` from `allowed(["tool", "arguments"])` to `allowed(["tool", "arguments", "fields"])`.
-- [x] Reject empty arrays and non-string path values through Zod.
-- [x] Return `fields` in the required request type only when present.
-- [x] Add tests that `call_tool` accepts `fields: ["body.name"]`, rejects `fields` for non-`call_tool` operations, rejects `fields: []`, and treats `arguments.fields` as downstream input.
-- [x] Run `pnpm test test/tools.test.ts` and confirm the new tests pass.
-
----
-
-## Task 2: Implement Schema-Aware Projection Utility
-
-**Files:**
-
-- Create: `src/field-selection.ts`
-- Test: `test/field-selection.test.ts`
-
-- [x] Write tests for object projection, array item projection, unknown schema paths, missing output schema, missing runtime values, and multiple nested selections.
-- [x] Implement `projectStructuredContent(value, outputSchema, fields)`.
-- [x] Validate paths against JSON Schema object `properties` and array `items`.
-- [x] Omit selected runtime values that are absent.
-- [x] Throw `CapletsError` with `REQUEST_INVALID` for missing schemas, non-object runtime content, or schema-disallowed fields.
-- [x] Run `pnpm test test/field-selection.test.ts` and confirm it passes.
-
----
-
-## Task 3: Expose Output Schema Metadata In Compact Tools
-
-**Files:**
-
-- Modify: `src/downstream.ts`
-- Modify: `src/openapi.ts`
-- Modify: `src/http-actions.ts`
-- Test: `test/tools.test.ts`
-
-- [x] Extend `CompactTool` with `hasOutputSchema: boolean`.
-- [x] Update MCP, OpenAPI, GraphQL, and HTTP `compact()` implementations to return `hasOutputSchema: Boolean(tool.outputSchema)`.
-- [x] Update compact tool test expectations.
-- [x] Run `pnpm test test/tools.test.ts`.
-
----
-
-## Task 4: Add MCP Projection
-
-**Files:**
-
-- Modify: `src/tools.ts`
-- Modify: `test/fixtures/stdio-server.mjs`
-- Test: `test/downstream.test.ts`
-- Test: `test/tools.test.ts`
-
-- [x] Add `outputSchema: z.object({ message: z.string() }).strict()` to the `echo` fixture tool.
-- [x] In `handleServerTool`, when `parsed.fields` exists, reject GraphQL, fetch the selected tool metadata, require `tool.outputSchema`, call the backend, and project the result.
-- [x] Add `projectCallToolResult()` in `src/tools.ts` or use a helper from `src/field-selection.ts`.
-- [x] Preserve `isError` and other result properties.
-- [x] Replace returned `content` with projected pretty JSON text.
-- [x] Test MCP `echo` with `fields: ["message"]`.
-- [x] Test missing output schema plus `fields` fails with `REQUEST_INVALID` before full output is returned.
-- [x] Run `pnpm test test/downstream.test.ts test/tools.test.ts`.
-
----
-
-## Task 5: Add OpenAPI Output Schema Extraction
-
-**Files:**
-
-- Modify: `src/openapi.ts`
-- Test: `test/openapi.test.ts`
-
-- [x] Extend `OpenApiOperation` with `outputSchema?: Record<string, unknown>`.
-- [x] Extract the first `2xx` JSON response schema from OpenAPI operations.
-- [x] Wrap the response body schema in the structured envelope schema for `{ status, statusText, headers, body }`.
-- [x] Attach `outputSchema` in `toTool()` when available.
-- [x] Test `get_tool` includes `outputSchema` for JSON response schema operations.
-- [x] Test compact output says `hasOutputSchema: true`.
-- [x] Test `call_tool.fields: ["body.name"]` returns only `{ body: { name: "Ada" } }`.
-- [x] Test fields on an operation without response schema throws `REQUEST_INVALID`.
-- [x] Run `pnpm test test/openapi.test.ts test/tools.test.ts`.
-
----
-
-## Task 6: Add HTTP Action Output Schema Config
-
-**Files:**
-
-- Modify: `src/config.ts`
-- Modify: `src/http-actions.ts`
-- Test: `test/config.test.ts`
-- Test: `test/http-actions.test.ts`
-- Regenerate: `schemas/caplets-config.schema.json`
-
-- [x] Add `outputSchema?: Record<string, unknown>` to `HttpActionConfig`.
-- [x] Add `outputSchema` to `httpActionSchema` with description `JSON Schema for structuredContent returned by this action.`
-- [x] Attach configured `outputSchema` in HTTP `toTool()` when available.
-- [x] Add config parsing tests for HTTP action output schemas.
-- [x] Add HTTP action tests for `get_tool`, compact metadata, and `call_tool.fields`.
-- [x] Run `pnpm schema:generate`.
-- [x] Run `pnpm test test/config.test.ts test/http-actions.test.ts`.
-
----
-
-## Task 7: Add Shared Result Projection In Wrapper
-
-**Files:**
-
-- Modify: `src/tools.ts`
-- Modify: `src/field-selection.ts`
-- Test: `test/tools.test.ts`
-
-- [x] Ensure result projection is centralized and shared by MCP, OpenAPI, and HTTP.
-- [x] Ensure `fields` omitted keeps existing pass-through behavior unchanged.
-- [x] Ensure GraphQL with `fields` fails with the planned error.
-- [x] Ensure projection never mutates the original result.
-- [x] Run `pnpm test test/tools.test.ts`.
-
----
-
-## Task 8: Update Agent-Facing Descriptions
-
-**Files:**
-
-- Modify: `src/tools.ts`
-- Modify: `src/registry.ts`
-- Test: `test/tools.test.ts`
-- Test: `test/registry.test.ts`
-
-- [x] Update `fields` schema description.
-- [x] Keep `arguments` warning about downstream inputs only inside `arguments`.
-- [x] Update `capabilityDescription` to mention optional `fields` only after `get_tool` confirms `outputSchema` for a non-GraphQL tool.
-- [x] Run `pnpm test test/tools.test.ts test/registry.test.ts`.
-
----
-
-## Task 9: Verification
-
-**Files:**
-
-- All modified files
-
-- [x] Run `pnpm test test/field-selection.test.ts test/tools.test.ts test/downstream.test.ts test/openapi.test.ts test/http-actions.test.ts test/config.test.ts`.
-- [x] Run `pnpm verify`.
-- [x] Fix any failures without weakening the feature contract.
-- [x] Confirm `git status --short` only contains intended files.
-
----
-
-## Risks And Guardrails
-
-- Static wrapper input schema cannot truly hide `fields` per downstream tool. Runtime validation and discovery metadata are the correct enforcement points.
-- OpenAPI response schema extraction should stay minimal: JSON `2xx` only, no content negotiation beyond `application/json`.
-- GraphQL should remain rejected for `fields` to avoid competing with GraphQL selection sets.
-- Do not support JSONPath, wildcards, computed selectors, array indexes, or aliases in the first implementation.
-- Do not silently no-op when schema is absent because that can leak full responses.
-
----
-
-## Acceptance Criteria
-
-- `list_tools` and `search_tools` show `hasOutputSchema`.
-- `get_tool` shows `outputSchema` for MCP tools that expose it.
-- `get_tool` shows synthesized `outputSchema` for OpenAPI operations with JSON response schemas.
-- `get_tool` shows configured `outputSchema` for HTTP actions.
-- `call_tool.fields` filters `structuredContent` and text content for MCP, OpenAPI, and HTTP.
-- `call_tool.fields` fails with `REQUEST_INVALID` for GraphQL.
-- `call_tool.fields` fails with `REQUEST_INVALID` when no output schema exists.
-- Existing `call_tool` behavior is unchanged when `fields` is omitted.
diff --git a/docs/plans/2026-05-14-project-first-caplets-add.md b/docs/plans/2026-05-14-project-first-caplets-add.md
deleted file mode 100644
index 1e3871ca..00000000
--- a/docs/plans/2026-05-14-project-first-caplets-add.md
+++ /dev/null
@@ -1,194 +0,0 @@
-# Project-First Caplets Add Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make project-local Caplets the default workflow by removing the project trust gate, making `add` and `install` write to `./.caplets` by default, and exposing source/shadowing information clearly.
-
-**Architecture:** Treat project `.caplets` as first-class project configuration loaded from the current working directory only. Project sources override global/user sources, but `caplets list` exposes source and shadowing information so users can see when project-local capabilities replace global ones. Keep generated Caplets as Markdown files and route all new scaffolding through `caplets add`.
-
-**Tech Stack:** TypeScript, Commander, Zod, Markdown Caplet files, Vitest, Node.js fs/path APIs.
-
----
-
-## Decisions Locked
-
-- Project Caplets load by default; remove `CAPLETS_TRUST_PROJECT_CAPLETS`.
-- Project scope is current working directory only; do not walk parents or Git roots in v1.
-- Project sources override global/user sources when IDs collide.
-- `caplets list` shows source by default and warns when a Caplet shadows another source.
-- `caplets add` and `caplets install` are project-first by default.
-- `-g, --global` writes to the user Caplets root.
-- `caplets add` replaces the public `caplets author cli` flow; keep `author cli` only as a temporary deprecated alias if compatibility is low-cost.
-- Generated Caplets are Markdown files, not direct edits to `config.json`.
-
----
-
-## Files To Modify
-
-- `src/config/paths.ts`: remove project trust env constant and make project path helpers unconditional.
-- `src/config.ts`: always load project Caplet files; add source/shadow metadata loader while keeping `loadConfig()` compatibility.
-- `src/caplet-files.ts`: expose text validation for generated Caplet manifests if needed.
-- `src/runtime.ts`: always watch project `.caplets`; remove trust checks from watched paths.
-- `src/cli.ts`: add `add` commands, update `install` with `-g/--global`, keep/deprecate `author cli` if practical.
-- `src/cli/install.ts`: support project-first destination selection.
-- `src/cli/inspection.ts`: include source metadata and shadow warnings.
-- `src/cli/author.ts` and/or new `src/cli/add.ts`: generate Caplet Markdown for CLI, MCP, OpenAPI, GraphQL, and HTTP.
-- `test/config-paths.test.ts`: update removed trust behavior.
-- `test/config.test.ts`: project loading, project override, and source/shadow metadata tests.
-- `test/runtime.test.ts`: watcher behavior without trust gate.
-- `test/cli.test.ts`: list source/warnings, install destination, add command wiring.
-- `test/author-cli.test.ts` or new `test/add.test.ts`: add command generation and validation tests.
-- `README.md`: document project-first add/install, removed trust gate, and source/shadowing behavior.
-
----
-
-## Task 1: Remove Project Trust Gate
-
-**Files:**
-
-- Modify: `src/config/paths.ts`
-- Modify: `src/config.ts`
-- Modify: `src/runtime.ts`
-- Test: `test/config-paths.test.ts`
-- Test: `test/config.test.ts`
-- Test: `test/runtime.test.ts`
-
-- [ ] Remove `TRUST_PROJECT_CAPLETS_ENV` exports and all `isTrustedEnvEnabled()` usage related to project Caplet loading.
-- [ ] Make `loadConfig(configPath, projectConfigPath)` always load project Markdown Caplet files from `resolveProjectCapletsRoot()`.
-- [ ] Keep project config loading from `./.caplets/config.json` unchanged.
-- [ ] Update runtime watcher setup so project `.caplets` is always included in watched paths.
-- [ ] Remove tests that assert project Markdown files are ignored without env trust.
-- [ ] Add tests that project Markdown files load without setting any environment variable.
-- [ ] Run `pnpm test test/config-paths.test.ts test/config.test.ts test/runtime.test.ts`.
-
----
-
-## Task 2: Add Source And Shadow Metadata
-
-**Files:**
-
-- Modify: `src/config.ts`
-- Modify: `src/caplet-files.ts` if source paths need to be returned from file discovery.
-- Test: `test/config.test.ts`
-
-- [ ] Add source metadata types: `global-config`, `global-file`, `project-config`, and `project-file`.
-- [ ] Add a loader such as `loadConfigWithSources()` that returns `{ config, sources, shadows }`.
-- [ ] Keep `loadConfig()` as a wrapper returning only `config` so runtime behavior remains compatible.
-- [ ] Track the winning source kind and path for each final Caplet ID.
-- [ ] Track shadowed entries when a later source overrides an earlier source.
-- [ ] Preserve the existing source precedence order: global config, global files, project config, project files.
-- [ ] Add tests proving project files override global files.
-- [ ] Add tests proving `sources` points at the winning project path and `shadows` includes the global path.
-- [ ] Run `pnpm test test/config.test.ts`.
-
----
-
-## Task 3: Update `caplets list` Source UX
-
-**Files:**
-
-- Modify: `src/cli/inspection.ts`
-- Modify: `src/cli.ts`
-- Test: `test/cli.test.ts`
-
-- [ ] Change `caplets list` to use `loadConfigWithSources()`.
-- [ ] Add a `source` column to human table output.
-- [ ] Append short warning lines for shadowed Caplets, for example: `Warning: project Caplet GitHub shadows global Caplet at /path/to/github.md`.
-- [ ] Add `source`, `path`, and `shadows` fields to `caplets list --json` output.
-- [ ] Keep disabled filtering behavior unchanged.
-- [ ] Add tests for human source output.
-- [ ] Add tests for JSON source/shadow output.
-- [ ] Run `pnpm test test/cli.test.ts`.
-
----
-
-## Task 4: Make `caplets install` Project-First
-
-**Files:**
-
-- Modify: `src/cli.ts`
-- Modify: `src/cli/install.ts`
-- Test: `test/cli.test.ts`
-
-- [ ] Add `-g, --global` to `caplets install`.
-- [ ] Make default destination `resolveProjectCapletsRoot()`.
-- [ ] Use `resolveCapletsRoot(resolveConfigPath(envConfigPath()))` only when `--global` is passed.
-- [ ] Preserve `--force` behavior.
-- [ ] Ensure project `.caplets` is created when missing.
-- [ ] Update install output text only if needed to make project/global destination clear.
-- [ ] Add tests that default install writes under `./.caplets`.
-- [ ] Add tests that `--global` writes under the user Caplets root.
-- [ ] Run `pnpm test test/cli.test.ts`.
-
----
-
-## Task 5: Add `caplets add cli`
-
-**Files:**
-
-- Modify: `src/cli.ts`
-- Modify: `src/cli/author.ts` or create `src/cli/add.ts`
-- Test: `test/author-cli.test.ts`
-- Test: `test/cli.test.ts`
-
-- [ ] Add public command `caplets add cli <id>` using the existing CLI Caplet generator.
-- [ ] Make default output project `.caplets/<id>.md`.
-- [ ] Add `-g, --global` for user root output.
-- [ ] Add `--print` for stdout-only review.
-- [ ] Add `--output <path>` for explicit file output.
-- [ ] Add `--force` to overwrite existing destination files.
-- [ ] Validate generated Caplet text before writing.
-- [ ] Keep `caplets author cli` as a deprecated alias that prints a warning to stderr, unless keeping it creates excessive complexity.
-- [ ] Add tests for default project write, global write, print mode, output mode, and overwrite protection.
-- [ ] Run `pnpm test test/author-cli.test.ts test/cli.test.ts`.
-
----
-
-## Task 6: Extend `caplets add` For MCP, OpenAPI, GraphQL, And HTTP
-
-**Files:**
-
-- Modify: `src/cli.ts`
-- Modify: `src/cli/author.ts` or create focused modules under `src/cli/add/`
-- Test: `test/author-cli.test.ts` or `test/add.test.ts`
-- Test: `test/cli.test.ts`
-
-- [ ] Add `caplets add mcp <id>` supporting stdio via `--command`, repeated `--arg`, optional `--cwd`, optional `--env KEY=VALUE`, and remote via `--url --transport http|sse`.
-- [ ] Add `caplets add openapi <id>` supporting `--spec <path-or-url>`, optional `--base-url`, and auth flags.
-- [ ] Add `caplets add graphql <id>` supporting `--endpoint-url` and exactly one of `--schema <path-or-url>` or `--introspection`.
-- [ ] Add `caplets add http <id>` supporting `--base-url` and repeated `--action <name:METHOD:/path>`.
-- [ ] Share destination behavior with `add cli`: project default, `--global`, `--print`, `--output`, `--force`.
-- [ ] Never embed raw bearer tokens; render `$env:ENV_NAME` from a `--token-env <ENV>` option.
-- [ ] Validate generated Caplet text before printing or writing.
-- [ ] Add tests for valid generation for each backend.
-- [ ] Add tests for invalid connection shape, invalid action syntax, invalid schema/introspection combination, and overwrite protection.
-- [ ] Run `pnpm test test/author-cli.test.ts test/cli.test.ts` or the new focused test file.
-
----
-
-## Task 7: Documentation And Verification
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: tests as needed.
-
-- [ ] Replace `caplets author cli` documentation with `caplets add cli`.
-- [ ] Document `caplets add mcp`, `add openapi`, `add graphql`, and `add http`.
-- [ ] Document that `caplets add` and `caplets install` write to `./.caplets` by default.
-- [ ] Document `-g, --global` for user-level writes.
-- [ ] Remove `CAPLETS_TRUST_PROJECT_CAPLETS` documentation.
-- [ ] Document project override precedence and `caplets list` shadow warnings.
-- [ ] Run targeted tests for changed areas.
-- [ ] Run full verification: `pnpm format:check && pnpm lint && pnpm typecheck && pnpm schema:check && pnpm test && pnpm build`.
-
----
-
-## Out Of Scope
-
-- Parent-directory or Git-root `.caplets` discovery.
-- Remote marketplace search.
-- AI-assisted generation.
-- Live backend checks during `caplets add`.
-- Direct edits to `config.json` from `caplets add`.
-- Removing `caplets install` repo support.
diff --git a/docs/plans/2026-05-15-native-agent-caplet-extensions.md b/docs/plans/2026-05-15-native-agent-caplet-extensions.md
deleted file mode 100644
index 7e8dee44..00000000
--- a/docs/plans/2026-05-15-native-agent-caplet-extensions.md
+++ /dev/null
@@ -1,807 +0,0 @@
-# Native Agent Caplet Extensions Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add native OpenCode and Pi Caplets extensions that expose Caplets as native agent tools with prompt guidance, without requiring agents to access Caplets through MCP.
-
-**Architecture:** Factor the existing Caplets operation runtime into a reusable in-process service, then publish two separate workspace packages: `@caplets/opencode` and `@caplets/pi`. Each adapter snapshots configured Caplets at extension/plugin load, registers one prefixed native tool per Caplet (`caplets_<id>`), executes through the shared service, and injects system/prompt guidance through native prompt hooks rather than editing user config.
-
-**Tech Stack:** TypeScript ESM, Node.js 22+, pnpm workspace, rolldown, Vitest, Zod, TypeBox for Pi schemas, `@opencode-ai/plugin`, `@earendil-works/pi-coding-agent`, existing Caplets backend managers.
-
----
-
-## Decisions From Architecture Grill
-
-- Native adapters register **one native tool per Caplet**, not one generic dispatch tool.
-- Native adapters use a **shared in-process runtime library**, not a child `caplets` CLI process.
-- OpenCode and Pi adapters are **separate npm packages** in the same repo workspace.
-- Package names use the `@caplets/*` scope for non-CLI packages: `@caplets/opencode` and `@caplets/pi`.
-- Native tool names are **prefixed** as `caplets_<capletId>` to avoid overriding built-in agent tools.
-- Tool registration is **snapshot-at-load** for v1. New/removed Caplets require reloading the agent/plugin.
-- Prompt guidance uses **existing Caplet metadata plus shared system guidance**. Do not add new Caplet frontmatter fields in v1.
-- OpenCode prompt guidance must use plugin hooks. Do not edit user `opencode.json`.
-- Pi prompt guidance should use `promptSnippet` and `promptGuidelines` on registered tools.
-
----
-
-## Current Code Context
-
-- `packages/core/src/tools.ts` already owns the Caplets operation contract: `get_caplet`, `check_backend`, `list_tools`, `search_tools`, `get_tool`, and `call_tool`.
-- `packages/core/src/tools.ts` already delegates execution to `DownstreamManager`, `OpenApiManager`, `GraphQLManager`, `HttpActionManager`, and `CliToolsManager`.
-- `packages/core/src/runtime.ts` couples that operation handling to MCP registration through `McpServer.registerTool`.
-- `packages/core/src/registry.ts` already exposes safe Caplet summaries/details and `capabilityDescription`.
-- `packages/core/src/generated-tool-input-schema.mjs` already defines the operation schema and user-facing field descriptions.
-- `packages/benchmarks/lib/opencode-runner.mjs` and `packages/benchmarks/lib/pi-runner.mjs` only exercise MCP modes today.
-
-The smallest correct change is to extract the non-MCP execution path into a native service and make MCP runtime plus native adapters consume the same operation handler.
-
----
-
-## Target File Structure
-
-### Core Package
-
-- Modify: `packages/core/package.json`
-  - Add workspace-aware scripts.
-  - Add package exports for `caplets/native`.
-  - Keep the existing `caplets` CLI bin unchanged.
-- Create: `pnpm-workspace.yaml`
-  - Include `.` and `packages/*`.
-- Modify: `packages/core/rolldown.config.ts`
-  - Build both `packages/core/src/index.ts` and `packages/core/src/native.ts` as ESM outputs.
-- Create: `packages/core/src/native.ts`
-  - Public native service export surface for adapter packages.
-- Create: `packages/core/src/native/service.ts`
-  - Shared in-process Caplets service that owns registry/managers and calls `handleServerTool`.
-- Create: `packages/core/src/native/tools.ts`
-  - Native tool naming, prompt text, schema shape, and result formatting helpers.
-- Test: `packages/core/test/native.test.ts`
-  - Core native service behavior independent from OpenCode/Pi.
-
-### OpenCode Adapter Package
-
-- Create: `packages/opencode/package.json`
-- Create: `packages/opencode/rolldown.config.ts`
-- Create: `packages/opencode/tsconfig.json`
-- Create: `packages/opencode/src/index.ts`
-  - OpenCode plugin entrypoint.
-- Create: `packages/opencode/src/schema.ts`
-  - Zod/OpenCode tool schema adapter.
-- Create: `packages/opencode/README.md`
-  - Installation and config-free plugin usage.
-- Test: `packages/opencode/test/opencode.test.ts`
-
-### Pi Adapter Package
-
-- Create: `packages/pi/package.json`
-- Create: `packages/pi/rolldown.config.ts`
-- Create: `packages/pi/tsconfig.json`
-- Create: `packages/pi/src/index.ts`
-  - Pi extension entrypoint.
-- Create: `packages/pi/src/schema.ts`
-  - TypeBox schema adapter.
-- Create: `packages/pi/README.md`
-  - Installation and extension usage.
-- Test: `packages/pi/test/pi.test.ts`
-
-### Documentation And Benchmarks
-
-- Modify: `README.md`
-  - Add native adapter section after MCP install/config docs.
-- Modify: `docs/benchmarks/coding-agent.md`
-  - Document that existing benchmark is MCP-mode only until native benchmark modes are added.
-- Modify: `packages/benchmarks/lib/opencode-runner.mjs`
-  - Add `native-caplets` mode in a later task after adapter package exists.
-- Modify: `packages/benchmarks/lib/pi-runner.mjs`
-  - Add `native-caplets` mode in a later task after adapter package exists.
-- Modify: `packages/benchmarks/test/benchmark.test.ts`
-  - Assert native benchmark config generation shape.
-
----
-
-## Public Native API
-
-Add this API as `caplets/native` from the root `caplets` package.
-
-```ts
-export type NativeCapletsServiceOptions = {
-  configPath?: string;
-  projectConfigPath?: string;
-  authDir?: string;
-};
-
-export type NativeCapletTool = {
-  caplet: string;
-  toolName: string;
-  title: string;
-  description: string;
-  promptGuidance: string[];
-};
-
-export type NativeCapletsService = {
-  listTools(): NativeCapletTool[];
-  execute(capletId: string, request: unknown): Promise<unknown>;
-  close(): Promise<void>;
-};
-
-export function createNativeCapletsService(
-  options?: NativeCapletsServiceOptions,
-): NativeCapletsService;
-
-export function nativeCapletToolName(capletId: string): string;
-
-export function nativeCapletsSystemGuidance(toolNames: string[]): string;
-```
-
-Service behavior:
-
-- Load Caplets config once at construction using existing `loadConfig` path rules.
-- Snapshot enabled Caplets for `listTools()`.
-- Use `ServerRegistry` plus existing backend managers exactly like MCP runtime.
-- Reuse `handleServerTool()` for operation validation/execution.
-- Return the same structured values and errors the MCP runtime returns, but adapters can format for their host tool APIs.
-- Close downstream MCP processes via `DownstreamManager.close()` when the adapter process/session shuts down.
-- Do not start or probe backends during `listTools()`.
-- Do not expose local source paths, env values, tokens, headers, raw command args beyond existing safe `get_caplet` metadata.
-
-Native tool naming:
-
-```ts
-export function nativeCapletToolName(capletId: string): string {
-  return `caplets_${capletId.replace(/-/g, "_")}`;
-}
-```
-
-This keeps current Caplet IDs unchanged internally while avoiding OpenCode/Pi tool-name collisions. Because existing `SERVER_ID_PATTERN` allows hyphens, the native name normalizes `-` to `_` for broader agent tool compatibility.
-
----
-
-## Prompt Guidance Contract
-
-The adapters should inject one shared system guidance block and per-tool descriptions.
-
-Shared guidance:
-
-```md
-## Caplets Native Tools
-
-Caplets tools are native wrappers around configured Caplet backends. Each tool is named `caplets_<id>` and represents one capability domain.
-
-Recommended flow:
-
-1. Call the relevant `caplets_<id>` tool with `operation: "get_caplet"` to read the full Caplet card.
-2. Call `check_backend` only when availability is uncertain.
-3. Use `search_tools` or `list_tools` to discover the selected Caplet's downstream operations.
-4. Use `get_tool` before `call_tool` when argument or output schema is unclear.
-5. For `call_tool`, put downstream inputs only inside the top-level `arguments` object.
-6. Do not invent downstream tool names; execute only exact names returned by `list_tools`, `search_tools`, or `get_tool`.
-```
-
-Per-tool prompt guidance:
-
-- Start from existing `capabilityDescription(caplet)`.
-- Replace examples of direct tool names with the native prefixed name where needed.
-- Preserve Caplet `name`, `description`, `tags`, and Markdown body behavior.
-- Do not add new Caplet schema fields for prompt guidance in v1.
-
-OpenCode guidance:
-
-- Register native tools through the plugin `tool` map.
-- Inject shared system guidance through OpenCode's `experimental.chat.system.transform` hook.
-- Do not edit `opencode.json`, agent prompts, or user config files.
-
-Pi guidance:
-
-- Register tools with `promptSnippet` and `promptGuidelines`.
-- Every `promptGuidelines` bullet must explicitly name the tool, e.g. `Use caplets_github ...`, because Pi appends bullets flat to its Guidelines section.
-
----
-
-## Task 1: Workspace And Build Layout
-
-**Files:**
-
-- Create: `pnpm-workspace.yaml`
-- Modify: `package.json`
-- Modify: `rolldown.config.ts`
-
-- [ ] Create `pnpm-workspace.yaml`.
-
-```yaml
-packages:
-  - "."
-  - "packages/*"
-```
-
-- [ ] Update root `package.json` scripts.
-
-Expected script shape:
-
-```json
-{
-  "scripts": {
-    "build": "pnpm build:core && pnpm --filter @caplets/opencode build && pnpm --filter @caplets/pi build",
-    "build:core": "rolldown -c",
-    "build:watch": "rolldown -c --watch",
-    "prepack": "pnpm build:core",
-    "verify": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm schema:check && pnpm test && pnpm benchmark:check && pnpm build"
-  }
-}
-```
-
-Keep existing scripts not shown here unchanged.
-
-- [ ] Add root package export for native API.
-
-Expected export shape:
-
-```json
-{
-  "exports": {
-    ".": "./dist/index.js",
-    "./native": "./dist/native.js"
-  }
-}
-```
-
-- [ ] Update `packages/core/rolldown.config.ts` to emit both CLI and native entrypoints.
-
-Expected config shape:
-
-```ts
-import { defineConfig } from "rolldown";
-
-export default defineConfig({
-  input: {
-    index: "src/index.ts",
-    native: "src/native.ts",
-  },
-  output: {
-    dir: "./dist",
-    format: "esm",
-    banner: (chunk) => (chunk.name === "index" ? "#!/usr/bin/env node" : ""),
-  },
-  platform: "node",
-});
-```
-
-- [ ] Run `pnpm build:core`.
-
-Expected: build succeeds and emits `dist/index.js` plus `dist/native.js`.
-
----
-
-## Task 2: Native Service Core
-
-**Files:**
-
-- Create: `packages/core/src/native.ts`
-- Create: `packages/core/src/native/service.ts`
-- Create: `packages/core/src/native/tools.ts`
-- Test: `packages/core/test/native.test.ts`
-
-- [ ] Write failing tests for native tool listing and prefixed naming in `packages/core/test/native.test.ts`.
-
-Test coverage:
-
-- `createNativeCapletsService({ configPath })` reads an existing Caplets config.
-- `listTools()` returns enabled Caplets only.
-- Native tool names are `caplets_<id>` and convert hyphens to underscores.
-- Tool descriptions include the existing Caplet capability card.
-- `listTools()` does not start downstream MCP servers.
-
-- [ ] Write failing tests for native execution.
-
-Test coverage:
-
-- `execute("alpha", { operation: "get_caplet" })` returns the same safe detail shape as `ServerRegistry.detail()`.
-- `execute("alpha", { operation: "search_tools", query: "x" })` delegates to the same backend manager path used by MCP runtime.
-- Invalid operation returns the same structured error result shape as MCP runtime.
-- `close()` closes downstream processes without throwing when nothing has started.
-
-- [ ] Implement `packages/core/src/native/tools.ts`.
-
-Implementation responsibilities:
-
-- `nativeCapletToolName(capletId)`.
-- `nativeCapletsSystemGuidance(toolNames)`.
-- `nativeCapletPromptGuidance(toolName, caplet)`.
-- `nativeCapletToolDescription(caplet)` using existing `capabilityDescription(caplet)`.
-
-- [ ] Implement `packages/core/src/native/service.ts`.
-
-Implementation responsibilities:
-
-- Instantiate `ServerRegistry`, `DownstreamManager`, `OpenApiManager`, `GraphQLManager`, `HttpActionManager`, and `CliToolsManager` exactly once.
-- Expose `listTools()`, `execute(capletId, request)`, and `close()`.
-- Call `handleServerTool()` for execution.
-- Catch errors and return `errorResult(error)` for adapter consistency.
-- Keep service construction free of MCP SDK server registration.
-
-- [ ] Implement `packages/core/src/native.ts` as the public export barrel.
-
-Expected exports:
-
-```ts
-export {
-  createNativeCapletsService,
-  type NativeCapletsService,
-  type NativeCapletsServiceOptions,
-  type NativeCapletTool,
-} from "./native/service";
-export { nativeCapletToolName, nativeCapletsSystemGuidance } from "./native/tools";
-export { generatedToolInputSchema } from "./tools";
-export { generatedToolInputJsonSchema } from "./generated-tool-input-schema.mjs";
-```
-
-- [ ] Run `pnpm --filter @caplets/core test -- test/native.test.ts`.
-
-Expected: native service tests pass.
-
-- [ ] Run `pnpm typecheck`.
-
-Expected: no TypeScript errors.
-
----
-
-## Task 3: OpenCode Adapter Package
-
-**Files:**
-
-- Create: `packages/opencode/package.json`
-- Create: `packages/opencode/rolldown.config.ts`
-- Create: `packages/opencode/tsconfig.json`
-- Create: `packages/opencode/src/schema.ts`
-- Create: `packages/opencode/src/index.ts`
-- Create: `packages/opencode/README.md`
-- Test: `packages/opencode/test/opencode.test.ts`
-
-- [ ] Create `packages/opencode/package.json`.
-
-Expected shape:
-
-```json
-{
-  "name": "@caplets/opencode",
-  "version": "0.0.0",
-  "description": "Native OpenCode plugin for Caplets.",
-  "type": "module",
-  "main": "dist/index.js",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "files": ["dist", "README.md"],
-  "scripts": {
-    "build": "rolldown -c"
-  },
-  "dependencies": {
-    "caplets": "workspace:*",
-    "@opencode-ai/plugin": "^0.0.0"
-  },
-  "peerDependencies": {
-    "@opencode-ai/plugin": ">=0"
-  }
-}
-```
-
-During implementation, replace `^0.0.0` with the current compatible `@opencode-ai/plugin` version resolved by `pnpm add -F @caplets/opencode @opencode-ai/plugin`.
-
-- [ ] Create package build config mirroring the root ESM Node build without a shebang.
-
-- [ ] Implement `packages/opencode/src/schema.ts`.
-
-Implementation responsibilities:
-
-- Convert the existing generated operation schema into OpenCode `tool.schema` fields.
-- Keep `operation` enum values identical to `operations` in `packages/core/src/generated-tool-input-schema.mjs`.
-- Keep `arguments` as a JSON object for `call_tool` only.
-- Keep optional `fields` as string array.
-
-- [ ] Implement `packages/opencode/src/index.ts` OpenCode plugin.
-
-Behavior:
-
-- Export a default OpenCode plugin function.
-- Create one native service at plugin load.
-- Build a tool record from `service.listTools()`.
-- Each key is the native prefixed `toolName`.
-- Each tool executes `service.execute(capletId, args)` and returns text suitable for OpenCode.
-- Add an `experimental.chat.system.transform` hook that pushes `nativeCapletsSystemGuidance(toolNames)` into `output.system`.
-- Do not write files or mutate OpenCode config.
-
-- [ ] Write `packages/opencode/test/opencode.test.ts`.
-
-Test coverage:
-
-- Plugin returns one OpenCode tool per enabled Caplet.
-- Tool keys are prefixed and hyphen-normalized.
-- Tool descriptions include Caplet name and operation guidance.
-- Tool execution delegates to `service.execute()` with the original Caplet ID.
-- The system transform hook appends Caplets guidance and names registered native tools.
-
-- [ ] Add README usage docs.
-
-Required documentation:
-
-- Install package.
-- Register plugin using OpenCode's plugin mechanism.
-- State that no MCP server is required for this mode.
-- State that the plugin does not edit `opencode.json`.
-- Show the `caplets_<id>` naming convention.
-
-- [ ] Run `pnpm --filter @caplets/opencode build`.
-
-Expected: adapter package builds successfully.
-
-- [ ] Run `pnpm test -- packages/opencode/test/opencode.test.ts`.
-
-Expected: OpenCode adapter tests pass.
-
----
-
-## Task 4: Pi Adapter Package
-
-**Files:**
-
-- Create: `packages/pi/package.json`
-- Create: `packages/pi/rolldown.config.ts`
-- Create: `packages/pi/tsconfig.json`
-- Create: `packages/pi/src/schema.ts`
-- Create: `packages/pi/src/index.ts`
-- Create: `packages/pi/README.md`
-- Test: `packages/pi/test/pi.test.ts`
-
-- [ ] Create `packages/pi/package.json`.
-
-Expected shape:
-
-```json
-{
-  "name": "@caplets/pi",
-  "version": "0.0.0",
-  "description": "Native Pi extension for Caplets.",
-  "type": "module",
-  "main": "dist/index.js",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "files": ["dist", "README.md"],
-  "scripts": {
-    "build": "rolldown -c"
-  },
-  "dependencies": {
-    "caplets": "workspace:*",
-    "typebox": "^1.0.0",
-    "@earendil-works/pi-coding-agent": "^0.0.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0"
-  }
-}
-```
-
-During implementation, replace placeholder versions with the current compatible versions resolved through package installation.
-
-- [ ] Implement `packages/pi/src/schema.ts`.
-
-Implementation responsibilities:
-
-- Build a TypeBox schema matching the Caplets operation request shape.
-- Use string literal union for `operation`.
-- Keep optional fields aligned with `generatedToolInputDescriptions`.
-- Preserve strict object behavior where Pi supports it.
-
-- [ ] Implement `packages/pi/src/index.ts` Pi extension.
-
-Behavior:
-
-- Export Pi's default extension function.
-- Create one native service at extension load.
-- Register one Pi tool per `service.listTools()` entry.
-- Use `name: tool.toolName`, `label: tool.title`, `description: tool.description`.
-- Set `promptSnippet` to a one-line Caplets capability summary.
-- Set `promptGuidelines` to bullets that explicitly name the tool.
-- `execute()` calls `service.execute(capletId, params)`.
-- Return Pi-compatible `{ content, details }`, with `details.result` carrying structured result data when available.
-- Attach a best-effort process shutdown handler that calls `service.close()` once.
-
-- [ ] Write `packages/pi/test/pi.test.ts`.
-
-Test coverage:
-
-- Extension registers one tool per enabled Caplet.
-- Tool names are prefixed and hyphen-normalized.
-- `promptGuidelines` explicitly include each native tool name.
-- Execution delegates to `service.execute()` with original Caplet ID.
-- Returned result includes LLM-readable text and details.
-
-- [ ] Add README usage docs.
-
-Required documentation:
-
-- Install package.
-- Register or load extension using Pi's extension mechanism.
-- State that no MCP server is required for this mode.
-- Show `caplets_<id>` naming.
-- Explain that new Caplets require `/reload` or restarting Pi for v1.
-
-- [ ] Run `pnpm --filter @caplets/pi build`.
-
-Expected: adapter package builds successfully.
-
-- [ ] Run `pnpm test -- packages/pi/test/pi.test.ts`.
-
-Expected: Pi adapter tests pass.
-
----
-
-## Task 5: Root Tests And Type Safety
-
-**Files:**
-
-- Modify: `packages/core/test/tools.test.ts` if schema expectations need native export coverage.
-- Modify: `packages/core/test/registry.test.ts` only if prompt helper behavior moves.
-- Modify: `packages/core/test/runtime.test.ts` only if refactoring changes MCP runtime construction.
-
-- [ ] Add tests proving existing MCP runtime behavior is unchanged.
-
-Coverage:
-
-- `CapletsRuntime.registeredToolIds()` still returns raw Caplet IDs, not prefixed native names.
-- MCP generated tool descriptions still use existing `capabilityDescription()` output.
-- MCP operation validation remains strict.
-
-- [ ] Add tests proving native naming does not leak into MCP mode.
-
-Expected:
-
-- MCP tool name remains `github`.
-- Native tool name is `caplets_github`.
-
-- [ ] Run focused tests.
-
-Commands:
-
-```sh
-pnpm --filter @caplets/core test -- test/native.test.ts test/runtime.test.ts test/tools.test.ts
-pnpm test -- packages/opencode/test/opencode.test.ts packages/pi/test/pi.test.ts
-```
-
-Expected: all focused tests pass.
-
----
-
-## Task 6: Native Benchmark Modes
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/opencode-runner.mjs`
-- Modify: `packages/benchmarks/lib/pi-runner.mjs`
-- Modify: `packages/benchmarks/live-config/opencode/README.md`
-- Modify: `packages/benchmarks/live-config/pi/README.md`
-- Modify: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Add OpenCode `native-caplets` mode.
-
-Expected behavior:
-
-- Existing `direct-flat` and `caplets` modes remain unchanged.
-- `native-caplets` config loads `@caplets/opencode` as a plugin instead of registering the Caplets MCP server.
-- The generated Caplets config file is still written for the native service to read.
-- The runner sets `CAPLETS_CONFIG` to the generated config path.
-- The runner does not expose mock servers directly through MCP in native mode.
-
-- [ ] Add Pi `native-caplets` mode.
-
-Expected behavior:
-
-- Existing `direct-flat`, `pi-proxy`, and `caplets` modes remain unchanged.
-- `native-caplets` config loads `@caplets/pi` as an extension instead of registering the Caplets MCP server.
-- The generated Caplets config file is still written for the native service to read.
-- The runner sets `CAPLETS_CONFIG` to the generated config path.
-
-- [ ] Update benchmark tests.
-
-Coverage:
-
-- `OPENCODE_CONFIG_MODES` includes `native-caplets`.
-- `PI_CONFIG_MODES` includes `native-caplets`.
-- Native configs do not include a Caplets MCP server entry.
-- Native configs preserve generated Caplets config support files.
-
-- [ ] Update live benchmark docs.
-
-Docs must state:
-
-- `caplets` mode means Caplets over MCP.
-- `native-caplets` mode means native adapter package.
-- Live native modes require the adapter package to be built.
-
-- [ ] Run benchmark tests.
-
-Command:
-
-```sh
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts
-```
-
-Expected: benchmark config tests pass.
-
----
-
-## Task 7: Documentation And Install UX
-
-**Files:**
-
-- Modify: `README.md`
-- Create or modify: `docs/native-adapters.md`
-- Modify: `package.json`
-
-- [ ] Add README native adapter section.
-
-Required content:
-
-- Explain the three exposure modes: direct downstream MCP, Caplets MCP gateway, native Caplets adapter.
-- Explain why native adapters exist: lower adapter overhead, native prompt hooks, no MCP server process for Caplets itself.
-- State that downstream MCP backends may still be used by Caplets internally; “native” means the agent-to-Caplets boundary is native.
-- Show native tool naming: `caplets_<id>`.
-- State that v1 snapshots Caplets at plugin/extension load.
-
-- [ ] Add `docs/native-adapters.md`.
-
-Required sections:
-
-- Architecture diagram in text form.
-- OpenCode install/use.
-- Pi install/use.
-- Security model.
-- Prompt guidance behavior.
-- Troubleshooting.
-
-- [ ] Add package release notes.
-
-If this repo uses Changesets at implementation time, add a changeset that describes:
-
-- `caplets`: adds native runtime export.
-- `@caplets/opencode`: initial native OpenCode adapter.
-- `@caplets/pi`: initial native Pi adapter.
-
-- [ ] Run docs-related checks.
-
-Command:
-
-```sh
-pnpm format:check
-```
-
-Expected: markdown formatting passes.
-
----
-
-## Task 8: Full Verification
-
-**Files:**
-
-- All touched files.
-
-- [ ] Install dependencies after adding workspace packages.
-
-Command:
-
-```sh
-pnpm install
-```
-
-Expected: lockfile updates only for intentional workspace/package dependencies.
-
-- [ ] Run formatting.
-
-Command:
-
-```sh
-pnpm format:check
-```
-
-Expected: pass.
-
-- [ ] Run lint.
-
-Command:
-
-```sh
-pnpm lint
-```
-
-Expected: pass.
-
-- [ ] Run typecheck.
-
-Command:
-
-```sh
-pnpm typecheck
-```
-
-Expected: pass across root and packages.
-
-- [ ] Run schema drift check.
-
-Command:
-
-```sh
-pnpm schema:check
-```
-
-Expected: pass. No Caplet schema changes should be needed for this feature.
-
-- [ ] Run tests.
-
-Command:
-
-```sh
-pnpm test
-```
-
-Expected: pass.
-
-- [ ] Run deterministic benchmark check.
-
-Command:
-
-```sh
-pnpm benchmark:check
-```
-
-Expected: pass.
-
-- [ ] Run full build.
-
-Command:
-
-```sh
-pnpm build
-```
-
-Expected: root package plus both native adapter packages build successfully.
-
-- [ ] Run full verification.
-
-Command:
-
-```sh
-pnpm verify
-```
-
-Expected: pass.
-
----
-
-## Security And Safety Requirements
-
-- Native adapters must not expose secrets in tool descriptions, system guidance, errors, or details.
-- Native adapters must not write or modify user OpenCode/Pi config.
-- Native adapters must preserve existing Caplets trust rules for project `.caplets` files.
-- Native adapters must preserve existing OAuth/auth store behavior.
-- OpenCode native tools must not override built-in tools because names are prefixed.
-- Pi guidelines must explicitly name each tool to avoid ambiguous prompt bullets.
-- Adapter package tests must include a secret-looking config value and assert it is absent from tool descriptions and `get_caplet` detail.
-
----
-
-## Residual Risks
-
-- OpenCode prompt hook APIs are experimental. The implementation must pin tests to the actual installed `@opencode-ai/plugin` types and fail fast if `experimental.chat.system.transform` changes.
-- Pi extension APIs may differ by installed version. Keep the Pi adapter package peer range explicit once the implementation resolves the current package version.
-- Snapshot-at-load means users must reload to see newly added Caplets. This is deliberate for v1 and must be documented clearly.
-- Native adapters reduce the agent-to-Caplets MCP boundary, but MCP-backed Caplets still start downstream MCP servers internally when selected.
-
----
-
-## Completion Criteria
-
-- `caplets/native` exports a stable in-process service used by both adapters.
-- `@caplets/opencode` builds and registers prefixed native Caplet tools plus system prompt guidance through hooks.
-- `@caplets/pi` builds and registers prefixed native Caplet tools plus Pi prompt snippets/guidelines.
-- Existing MCP behavior remains unchanged.
-- Docs clearly distinguish MCP gateway mode from native adapter mode.
-- `pnpm verify` passes.
diff --git a/docs/plans/2026-05-15-native-hot-reload.md b/docs/plans/2026-05-15-native-hot-reload.md
deleted file mode 100644
index cdd9501f..00000000
--- a/docs/plans/2026-05-15-native-hot-reload.md
+++ /dev/null
@@ -1,1569 +0,0 @@
-# Native Hot Reload Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add hot-reload support to native Caplets integrations so native tool execution uses the latest config, Pi can refresh its per-tool surface at runtime, and OpenCode gets the strongest behavior its current plugin API supports.
-
-**Architecture:** Extract the existing MCP runtime reload/watch/backend-invalidation machinery into a shared core engine that owns config state, filesystem watchers, backend managers, reload serialization, and last-known-good behavior. Rebuild the MCP `CapletsRuntime` and native `DefaultNativeCapletsService` on top of that engine; Pi subscribes to native tool-change events and syncs registered/active tools, while OpenCode keeps static tool inventory but reads live service state for execution and system guidance.
-
-**Tech Stack:** TypeScript, Node.js `fs.watch`, Vitest, `@modelcontextprotocol/sdk` `RegisteredTool`, OpenCode `@opencode-ai/plugin`, Pi extension APIs `registerTool`, `getActiveTools`, and `setActiveTools`.
-
----
-
-## Architecture Decisions From Grill Session
-
-- OpenCode strategy: support hot-reload for existing registered tools only, with room to expand if OpenCode adds a runtime plugin-tool registry later.
-- Pi removal strategy: deactivate stale Caplets with `setActiveTools()` when hard `unregisterTool()` is unavailable.
-- Core strategy: do not duplicate `CapletsRuntime` reload logic in native service; extract a shared engine and reuse it.
-- Compatibility strategy: keep the current `NativeCapletsService` methods and add new methods, rather than changing adapter call sites to a completely different object.
-
-## Current State
-
-- `packages/core/src/runtime.ts` already supports config and Caplet file watching, debounced reloads, pending reload coalescing, last-known-good config on validation failure, selective backend invalidation, MCP tool add/update/remove, and watcher refresh.
-- `packages/core/src/native/service.ts` loads config once in the constructor and never reloads.
-- `packages/opencode/src/index.ts` calls `service.listTools()` once while constructing the plugin `Hooks.tool` map.
-- `packages/pi/src/index.ts` calls `service.listTools()` once and calls `pi.registerTool()` once per Caplet.
-- Pi docs say `pi.registerTool()` works after startup and new tools refresh immediately in-session. Pi docs also expose `getActiveTools()` and `setActiveTools(names)` for dynamic activation.
-- OpenCode plugin types expose `Hooks.tool` as a static object and do not expose `registerTool`, `unregisterTool`, `updateToolDefinition`, or `refreshTools`. Upstream OpenCode issue `anomalyco/opencode#25531` requests this capability.
-
-## File Structure
-
-- Create `packages/core/src/engine.ts`: shared reloadable Caplets engine; owns config paths, registry, managers, watchers, reload lifecycle, listeners, and execution.
-- Modify `packages/core/src/runtime.ts`: remove duplicated reload/watch/backend-manager ownership and delegate to `CapletsEngine`; keep MCP-specific tool registration/reconciliation here.
-- Modify `packages/core/src/native/service.ts`: wrap `CapletsEngine`, expose `reload()`, `onToolsChanged()`, and live `listTools()`.
-- Modify `packages/core/src/native.ts`: export new native listener/event types if they are public.
-- Create `packages/core/test/engine.test.ts`: shared engine reload behavior tests moved from runtime-native overlap.
-- Modify `packages/core/test/runtime.test.ts`: keep MCP tool reconciliation tests; remove direct private `reloadOnce` spy and rely on engine tests for reload coalescing.
-- Modify `packages/core/test/native.test.ts`: add native service reload, watcher, invalid config, and tool-change listener tests.
-- Modify `packages/pi/src/index.ts`: register initial tools, subscribe to service tool changes, register new/updated tools, and preserve non-Caplets active tools while deactivating stale Caplet tools.
-- Modify `packages/pi/test/pi.test.ts`: add dynamic registration and active-tool preservation tests.
-- Modify `packages/opencode/src/index.ts`: keep static `Hooks.tool` inventory, but compute system guidance from `service.listTools()` each transform call so existing-tool metadata stays fresh.
-- Modify `packages/opencode/test/opencode.test.ts`: assert system guidance reflects current service state after list changes.
-- Modify `README.md`, `packages/pi/README.md`, and `packages/opencode/README.md`: document host-specific hot-reload behavior.
-- Modify `.changeset/native-agent-integrations.md`: extend the existing unreleased native integrations changeset to mention native hot-reload.
-
----
-
-### Task 1: Extract Shared Reloadable Engine
-
-**Files:**
-
-- Create: `packages/core/src/engine.ts`
-- Test: `packages/core/test/engine.test.ts`
-- Modify later: `packages/core/src/runtime.ts`
-
-- [ ] **Step 1: Write failing shared engine tests**
-
-Create `packages/core/test/engine.test.ts` with these tests. This intentionally mirrors the proven behavior currently covered indirectly through `CapletsRuntime`, but targets the shared engine directly.
-
-```ts
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { CapletsEngine } from "../src/engine";
-
-describe("CapletsEngine", () => {
-  const dirs: string[] = [];
-
-  afterEach(() => {
-    for (const dir of dirs.splice(0)) {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("adds, updates, and removes enabled Caplets across successful reloads", async () => {
-    const { dir, configPath, projectConfigPath } = tempConfig({
-      mcpServers: {
-        alpha: {
-          name: "Alpha",
-          description: "Search alpha project documents.",
-          command: process.execPath,
-        },
-        beta: {
-          name: "Beta",
-          description: "Search beta project documents.",
-          command: process.execPath,
-          disabled: true,
-        },
-      },
-    });
-    dirs.push(dir);
-    const engine = new CapletsEngine({ configPath, projectConfigPath, watch: false });
-    const events: Array<{ previous: string[]; next: string[]; invalidated: boolean }> = [];
-    engine.onReload(({ previous, next, invalidated }) => {
-      events.push({
-        previous: Object.keys(previous.mcpServers).sort(),
-        next: Object.keys(next.mcpServers).sort(),
-        invalidated,
-      });
-    });
-
-    expect(engine.enabledServers().map((caplet) => caplet.server)).toEqual(["alpha"]);
-
-    writeConfig(configPath, {
-      mcpServers: {
-        alpha: {
-          name: "Alpha Reloaded",
-          description: "Search alpha project documents after reload.",
-          command: process.execPath,
-        },
-        gamma: {
-          name: "Gamma",
-          description: "Search gamma project documents.",
-          command: process.execPath,
-        },
-      },
-    });
-
-    await expect(engine.reload()).resolves.toBe(true);
-    expect(
-      engine
-        .enabledServers()
-        .map((caplet) => caplet.server)
-        .sort(),
-    ).toEqual(["alpha", "gamma"]);
-    expect(engine.enabledServers().find((caplet) => caplet.server === "alpha")?.name).toBe(
-      "Alpha Reloaded",
-    );
-    expect(events).toHaveLength(1);
-    expect(events[0]).toEqual({
-      previous: ["alpha", "beta"],
-      next: ["alpha", "gamma"],
-      invalidated: true,
-    });
-
-    writeConfig(configPath, {
-      mcpServers: {
-        gamma: {
-          name: "Gamma",
-          description: "Search gamma project documents.",
-          command: process.execPath,
-        },
-      },
-    });
-
-    await expect(engine.reload()).resolves.toBe(true);
-    expect(engine.enabledServers().map((caplet) => caplet.server)).toEqual(["gamma"]);
-
-    await engine.close();
-  });
-
-  it("keeps last known-good config when reload validation fails", async () => {
-    const { dir, configPath, projectConfigPath } = tempConfig({
-      mcpServers: {
-        alpha: {
-          name: "Alpha",
-          description: "Search alpha project documents.",
-          command: process.execPath,
-        },
-      },
-    });
-    dirs.push(dir);
-    const errors: string[] = [];
-    const engine = new CapletsEngine({
-      configPath,
-      projectConfigPath,
-      watch: false,
-      writeErr: (value) => errors.push(value),
-    });
-    const listener = vi.fn();
-    engine.onReload(listener);
-
-    writeFileSync(configPath, "{ invalid json");
-
-    await expect(engine.reload()).resolves.toBe(false);
-    expect(engine.enabledServers().map((caplet) => caplet.server)).toEqual(["alpha"]);
-    expect(listener).not.toHaveBeenCalled();
-    expect(errors.join("")).toContain("Caplets config reload failed");
-
-    await engine.close();
-  });
-
-  it("runs a follow-up reload when another reload is requested mid-flight", async () => {
-    const { dir, configPath, projectConfigPath } = tempConfig({
-      mcpServers: {
-        alpha: {
-          name: "Alpha",
-          description: "Search alpha project documents.",
-          command: process.execPath,
-        },
-      },
-    });
-    dirs.push(dir);
-    const engine = new CapletsEngine({ configPath, projectConfigPath, watch: false });
-    let calls = 0;
-
-    (engine as unknown as { reloadOnce: () => Promise<boolean> }).reloadOnce = vi.fn(async () => {
-      calls += 1;
-      if (calls === 1) {
-        void engine.reload();
-      }
-      return true;
-    });
-
-    await engine.reload();
-    expect(calls).toBe(2);
-
-    await engine.close();
-  });
-
-  it("watches config and Caplet paths when watch is enabled", async () => {
-    const { dir, configPath, projectConfigPath } = tempConfig({
-      mcpServers: {
-        alpha: {
-          name: "Alpha",
-          description: "Search alpha project documents.",
-          command: process.execPath,
-        },
-      },
-    });
-    dirs.push(dir);
-    const engine = new CapletsEngine({ configPath, projectConfigPath, watchDebounceMs: 10 });
-    let reloads = 0;
-    (engine as unknown as { reload: () => Promise<boolean> }).reload = vi.fn(async () => {
-      reloads += 1;
-      return true;
-    });
-
-    writeConfig(configPath, {
-      mcpServers: {
-        beta: {
-          name: "Beta",
-          description: "Search beta project documents.",
-          command: process.execPath,
-        },
-      },
-    });
-
-    await eventually(() => expect(reloads).toBeGreaterThan(0));
-    await engine.close();
-  });
-
-  function tempConfig(config: unknown): {
-    dir: string;
-    configPath: string;
-    projectConfigPath: string;
-  } {
-    const dir = mkdtempSync(join(tmpdir(), "caplets-engine-"));
-    const userRoot = join(dir, "user");
-    const projectRoot = join(dir, "project", ".caplets");
-    mkdirSync(userRoot, { recursive: true });
-    mkdirSync(projectRoot, { recursive: true });
-    const configPath = join(userRoot, "config.json");
-    const projectConfigPath = join(projectRoot, "config.json");
-    writeConfig(configPath, config);
-    return { dir, configPath, projectConfigPath };
-  }
-});
-
-function writeConfig(path: string, config: unknown): void {
-  writeFileSync(path, JSON.stringify(config));
-}
-
-async function eventually(assertion: () => void): Promise<void> {
-  const deadline = Date.now() + 1_000;
-  let lastError: unknown;
-  while (Date.now() < deadline) {
-    try {
-      assertion();
-      return;
-    } catch (error) {
-      lastError = error;
-      await new Promise((resolve) => setTimeout(resolve, 20));
-    }
-  }
-  try {
-    assertion();
-  } catch {
-    throw lastError;
-  }
-}
-```
-
-- [ ] **Step 2: Run engine test to verify it fails**
-
-Run: `pnpm --filter @caplets/core test -- test/engine.test.ts`
-
-Expected: FAIL because `../src/engine.js` does not exist.
-
-- [ ] **Step 3: Create the shared engine**
-
-Create `packages/core/src/engine.ts`. Move the reload, watcher, config path, backend manager, and helper logic from `packages/core/src/runtime.ts` into this file. The public surface must match this shape:
-
-```ts
-import { existsSync, readdirSync, statSync, watch, type FSWatcher } from "node:fs";
-import { dirname, parse } from "node:path";
-import { CliToolsManager } from "./cli-tools";
-import {
-  type CapletConfig,
-  type CapletsConfig,
-  loadConfig,
-  resolveCapletsRoot,
-  resolveConfigPath,
-  resolveProjectConfigPath,
-} from "./config";
-import { DownstreamManager } from "./downstream";
-import { errorResult, toSafeError } from "./errors";
-import { GraphQLManager } from "./graphql";
-import { HttpActionManager } from "./http-actions";
-import { OpenApiManager } from "./openapi";
-import { ServerRegistry } from "./registry";
-import { handleServerTool } from "./tools";
-
-export type CapletsEngineOptions = {
-  configPath?: string;
-  projectConfigPath?: string;
-  authDir?: string;
-  watchDebounceMs?: number;
-  watch?: boolean;
-  writeErr?: (value: string) => void;
-};
-
-export type CapletsEngineReloadEvent = {
-  previous: CapletsConfig;
-  next: CapletsConfig;
-  invalidated: boolean;
-};
-
-type RuntimePaths = {
-  configPath: string;
-  projectConfigPath: string;
-};
-
-type WatchedPath = {
-  path: string;
-  reason: "config" | "caplets";
-};
-
-export class CapletsEngine {
-  private registry: ServerRegistry;
-  private readonly downstream: DownstreamManager;
-  private readonly openapi: OpenApiManager;
-  private readonly graphql: GraphQLManager;
-  private readonly http: HttpActionManager;
-  private readonly cli: CliToolsManager;
-  private readonly paths: RuntimePaths;
-  private readonly watchDebounceMs: number;
-  private readonly watchEnabled: boolean;
-  private readonly writeErr: (value: string) => void;
-  private readonly reloadListeners = new Set<(event: CapletsEngineReloadEvent) => void>();
-  private watchers: FSWatcher[] = [];
-  private reloadTimer: NodeJS.Timeout | undefined;
-  private watcherRefreshTimer: NodeJS.Timeout | undefined;
-  private reloading: Promise<boolean> | undefined;
-  private pendingReload = false;
-  private closed = false;
-
-  constructor(options: CapletsEngineOptions = {}) {
-    this.paths = {
-      configPath: resolveConfigPath(options.configPath),
-      projectConfigPath: options.projectConfigPath ?? resolveProjectConfigPath(),
-    };
-    const config = loadConfig(this.paths.configPath, this.paths.projectConfigPath);
-    this.registry = new ServerRegistry(config);
-    this.downstream = new DownstreamManager(this.registry, selectAuthOptions(options.authDir));
-    this.openapi = new OpenApiManager(this.registry, selectAuthOptions(options.authDir));
-    this.graphql = new GraphQLManager(this.registry, selectAuthOptions(options.authDir));
-    this.http = new HttpActionManager(this.registry, selectAuthOptions(options.authDir));
-    this.cli = new CliToolsManager(this.registry);
-    this.watchDebounceMs = options.watchDebounceMs ?? 250;
-    this.watchEnabled = options.watch ?? true;
-    this.writeErr = options.writeErr ?? ((value: string) => process.stderr.write(value));
-    if (this.watchEnabled) {
-      this.resetWatchers();
-    }
-  }
-
-  currentConfig(): CapletsConfig {
-    return this.registry.config;
-  }
-
-  enabledServers(): CapletConfig[] {
-    return nextEnabledServers(this.registry.config);
-  }
-
-  watchedPaths(): string[] {
-    return [...new Set(watchedPaths(this.paths).map((entry) => entry.path))].sort();
-  }
-
-  onReload(listener: (event: CapletsEngineReloadEvent) => void): () => void {
-    this.reloadListeners.add(listener);
-    return () => {
-      this.reloadListeners.delete(listener);
-    };
-  }
-
-  scheduleReload(): void {
-    if (this.closed) return;
-    if (this.reloadTimer) clearTimeout(this.reloadTimer);
-    this.reloadTimer = setTimeout(() => {
-      this.reloadTimer = undefined;
-      void this.reload();
-    }, this.watchDebounceMs);
-  }
-
-  async reload(): Promise<boolean> {
-    if (this.closed) return false;
-    if (this.reloading) {
-      this.pendingReload = true;
-      return await this.reloading;
-    }
-    this.reloading = this.reloadUntilSettled().finally(() => {
-      this.reloading = undefined;
-    });
-    return await this.reloading;
-  }
-
-  async execute(serverId: string, request: unknown): Promise<unknown> {
-    try {
-      const caplet = this.registry.require(serverId);
-      return await handleServerTool(
-        caplet,
-        request,
-        this.registry,
-        this.downstream,
-        this.openapi,
-        this.graphql,
-        this.http,
-        this.cli,
-      );
-    } catch (error) {
-      return errorResult(error);
-    }
-  }
-
-  async close(): Promise<void> {
-    this.closed = true;
-    try {
-      if (this.reloadTimer) {
-        clearTimeout(this.reloadTimer);
-        this.reloadTimer = undefined;
-      }
-      if (this.watcherRefreshTimer) {
-        clearTimeout(this.watcherRefreshTimer);
-        this.watcherRefreshTimer = undefined;
-      }
-      if (this.reloading) {
-        await this.reloading;
-      }
-    } finally {
-      this.closeWatchers();
-      await this.downstream.close();
-      this.reloadListeners.clear();
-    }
-  }
-
-  private async reloadOnce(): Promise<boolean> {
-    if (this.closed) return false;
-    let nextConfig: CapletsConfig;
-    try {
-      nextConfig = loadConfig(this.paths.configPath, this.paths.projectConfigPath);
-    } catch (error) {
-      this.writeErr(`Caplets config reload failed; keeping last known-good config.\n`);
-      this.writeErr(`${JSON.stringify(toSafeError(error, "CONFIG_INVALID"), null, 2)}\n`);
-      return false;
-    }
-
-    if (this.closed) return false;
-    const previousConfig = this.registry.config;
-    const nextRegistry = new ServerRegistry(nextConfig);
-    this.registry = nextRegistry;
-    this.downstream.updateRegistry(nextRegistry);
-    this.openapi.updateRegistry(nextRegistry);
-    this.graphql.updateRegistry(nextRegistry);
-    this.http.updateRegistry(nextRegistry);
-    this.cli.updateRegistry(nextRegistry);
-
-    let invalidated = true;
-    try {
-      await this.invalidateChangedBackends(previousConfig, nextConfig);
-    } catch (error) {
-      invalidated = false;
-      this.writeErr(`Caplets backend invalidation failed; continuing reload.\n`);
-      this.writeErr(`${JSON.stringify(toSafeError(error, "INTERNAL_ERROR"), null, 2)}\n`);
-    }
-    if (this.closed) return false;
-    if (this.watchEnabled) {
-      this.resetWatchers();
-    }
-    this.emitReload({ previous: previousConfig, next: nextConfig, invalidated });
-    return invalidated;
-  }
-
-  private async reloadUntilSettled(): Promise<boolean> {
-    let succeeded = true;
-    do {
-      this.pendingReload = false;
-      try {
-        succeeded = (await this.reloadOnce()) && succeeded;
-      } catch (err) {
-        this.writeErr(`Caplets reload failed.\n`);
-        this.writeErr(`${JSON.stringify(toSafeError(err, "INTERNAL_ERROR"), null, 2)}\n`);
-        succeeded = false;
-      }
-    } while (this.pendingReload && !this.closed);
-    return succeeded && !this.closed;
-  }
-
-  private emitReload(event: CapletsEngineReloadEvent): void {
-    for (const listener of this.reloadListeners) {
-      listener(event);
-    }
-  }
-
-  private async invalidateChangedBackends(
-    previous: CapletsConfig,
-    next: CapletsConfig,
-  ): Promise<void> {
-    const previousCaplets = new Map(allCaplets(previous).map((server) => [server.server, server]));
-    const nextCaplets = new Map(allCaplets(next).map((server) => [server.server, server]));
-    const changedIds = new Set([...previousCaplets.keys(), ...nextCaplets.keys()]);
-
-    for (const serverId of changedIds) {
-      const before = previousCaplets.get(serverId);
-      const after = nextCaplets.get(serverId);
-      const changed = serializeCaplet(before) !== serializeCaplet(after);
-      if (!changed) continue;
-      if (before?.backend === "mcp") await this.downstream.closeServer(serverId);
-      if (before?.backend === "openapi" || after?.backend === "openapi" || !after)
-        this.openapi.invalidate(serverId);
-      if (before?.backend === "graphql" || after?.backend === "graphql" || !after)
-        this.graphql.invalidate(serverId);
-      if (before?.backend === "http" || after?.backend === "http" || !after)
-        this.http.invalidate(serverId);
-      if (before?.backend === "cli" || after?.backend === "cli" || !after)
-        this.cli.invalidate(serverId);
-    }
-  }
-
-  private resetWatchers(): void {
-    this.closeWatchers();
-    const watched = new Set<string>();
-    for (const entry of watchedPaths(this.paths)) {
-      const watchPath = existsSync(entry.path) ? entry.path : nearestExistingParent(entry.path);
-      const watchKey = `${entry.reason}:${watchPath}`;
-      if (!watchPath || watched.has(watchKey)) continue;
-      watched.add(watchKey);
-      try {
-        this.watchers.push(...this.watchEntry(entry, watchPath));
-      } catch (error) {
-        this.writeErr(`Caplets could not watch ${entry.reason} path ${entry.path}.\n`);
-        this.writeErr(`${JSON.stringify(toSafeError(error, "SERVER_UNAVAILABLE"), null, 2)}\n`);
-      }
-    }
-  }
-
-  private closeWatchers(): void {
-    for (const watcher of this.watchers) watcher.close();
-    this.watchers = [];
-  }
-
-  private watchEntry(entry: WatchedPath, watchPath: string): FSWatcher[] {
-    if (entry.reason === "caplets" && existsSync(entry.path) && isDirectory(watchPath)) {
-      return this.watchDirectoryTree(watchPath);
-    }
-    return [
-      watch(watchPath, { persistent: true }, (eventType) => {
-        this.scheduleReload();
-        if (eventType === "rename" && entry.reason === "caplets" && existsSync(entry.path)) {
-          this.scheduleWatcherRefresh();
-        }
-      }),
-    ];
-  }
-
-  private watchDirectoryTree(root: string): FSWatcher[] {
-    const watchers: FSWatcher[] = [];
-    const directories = discoverDirectories(root);
-    for (const directory of directories) {
-      try {
-        watchers.push(
-          watch(directory, { persistent: true }, (eventType) => {
-            this.scheduleReload();
-            if (eventType === "rename") this.scheduleWatcherRefresh();
-          }),
-        );
-      } catch (error) {
-        for (const watcher of watchers) watcher.close();
-        throw error;
-      }
-    }
-    return watchers;
-  }
-
-  private scheduleWatcherRefresh(): void {
-    if (this.closed) return;
-    if (this.watcherRefreshTimer) clearTimeout(this.watcherRefreshTimer);
-    this.watcherRefreshTimer = setTimeout(() => {
-      this.watcherRefreshTimer = undefined;
-      if (!this.closed) this.resetWatchers();
-    }, this.watchDebounceMs);
-  }
-}
-
-function selectAuthOptions(authDir: string | undefined): { authDir?: string } {
-  return authDir ? { authDir } : {};
-}
-
-function watchedPaths(paths: RuntimePaths): WatchedPath[] {
-  return uniqueWatchedPaths([
-    { path: dirname(paths.configPath), reason: "config" },
-    { path: dirname(paths.projectConfigPath), reason: "config" },
-    { path: resolveCapletsRoot(paths.configPath), reason: "caplets" },
-    { path: dirname(paths.projectConfigPath), reason: "caplets" },
-  ]);
-}
-
-function uniqueWatchedPaths(entries: WatchedPath[]): WatchedPath[] {
-  const seen = new Set<string>();
-  const unique: WatchedPath[] = [];
-  for (const entry of entries) {
-    const key = `${entry.reason}:${entry.path}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    unique.push(entry);
-  }
-  return unique;
-}
-
-function allCaplets(config: CapletsConfig): CapletConfig[] {
-  return [
-    ...Object.values(config.mcpServers),
-    ...Object.values(config.openapiEndpoints),
-    ...Object.values(config.graphqlEndpoints),
-    ...Object.values(config.httpApis),
-    ...Object.values(config.cliTools),
-  ];
-}
-
-function nextEnabledServers(config: CapletsConfig): CapletConfig[] {
-  return allCaplets(config).filter((server) => !server.disabled);
-}
-
-function serializeCaplet(caplet: CapletConfig | undefined): string {
-  return JSON.stringify(caplet ?? null);
-}
-
-function nearestExistingParent(path: string): string | undefined {
-  let candidate = dirname(path);
-  const root = parse(candidate).root;
-  while (candidate && candidate !== root) {
-    if (existsSync(candidate)) return candidate;
-    candidate = dirname(candidate);
-  }
-  return existsSync(root) ? root : undefined;
-}
-
-function discoverDirectories(root: string): string[] {
-  if (!isDirectory(root)) return [];
-  const directories = [root];
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
-    if (entry.isDirectory()) directories.push(...discoverDirectories(`${root}/${entry.name}`));
-  }
-  return directories;
-}
-
-function isDirectory(path: string): boolean {
-  try {
-    return statSync(path).isDirectory();
-  } catch {
-    return false;
-  }
-}
-```
-
-- [ ] **Step 4: Run engine tests**
-
-Run: `pnpm --filter @caplets/core test -- test/engine.test.ts`
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```sh
-git add packages/core/src/engine.ts packages/core/test/engine.test.ts
-git commit -m "refactor(core): extract reloadable Caplets engine"
-```
-
----
-
-### Task 2: Rebuild MCP Runtime On The Shared Engine
-
-**Files:**
-
-- Modify: `packages/core/src/runtime.ts`
-- Test: `packages/core/test/runtime.test.ts`
-
-- [ ] **Step 1: Update runtime tests for the engine split**
-
-Keep the MCP-specific tests in `packages/core/test/runtime.test.ts`: initial tool registration, raw MCP names with prefixed native names, add/update/remove reconciliation, invalid config retaining old MCP tools, backend invalidation failure behavior, watched path exposure, and watcher scheduling.
-
-Delete or move the test named `runs a follow-up reload when another reload is requested mid-flight`; that behavior is now covered in `packages/core/test/engine.test.ts`.
-
-Run: `pnpm --filter @caplets/core test -- test/runtime.test.ts`
-
-Expected: FAIL while `CapletsRuntime` still owns duplicated logic and/or the private `reloadOnce` test no longer applies.
-
-- [ ] **Step 2: Replace runtime state ownership with `CapletsEngine`**
-
-In `packages/core/src/runtime.ts`, remove imports that are now engine-owned: `existsSync`, `readdirSync`, `statSync`, `watch`, `dirname`, `parse`, `loadConfig`, `resolveCapletsRoot`, `resolveConfigPath`, `resolveProjectConfigPath`, `CliToolsManager`, `DownstreamManager`, `errorResult`, `toSafeError`, `GraphQLManager`, `HttpActionManager`, `OpenApiManager`, `ServerRegistry`, and `handleServerTool`.
-
-Add these imports:
-
-```ts
-import type { CapletConfig, CapletsConfig } from "./config";
-import { CapletsEngine } from "./engine";
-```
-
-Change the class fields to this shape:
-
-```ts
-export class CapletsRuntime {
-  readonly server: ToolServer;
-  private readonly engine: CapletsEngine;
-  private readonly tools = new Map<string, RegisteredTool>();
-  private readonly unsubscribeReload: () => void;
-  private closed = false;
-```
-
-Change the constructor to instantiate the engine and reconcile initial tools:
-
-```ts
-  constructor(options: CapletsRuntimeOptions = {}) {
-    this.engine = new CapletsEngine(options);
-    this.server =
-      options.server ??
-      new McpServer({
-        name: "caplets",
-        version: packageJsonVersion,
-      });
-    this.reconcileTools(undefined, this.engine.currentConfig());
-    this.unsubscribeReload = this.engine.onReload(({ previous, next }) => {
-      this.reconcileTools(previous, next);
-    });
-  }
-```
-
-Replace reload/watch/current-config methods with delegates:
-
-```ts
-  scheduleReload(): void {
-    this.engine.scheduleReload();
-  }
-
-  async reload(): Promise<boolean> {
-    return await this.engine.reload();
-  }
-
-  async close(): Promise<void> {
-    if (this.closed) return;
-    this.closed = true;
-    this.unsubscribeReload();
-    try {
-      await this.engine.close();
-    } finally {
-      await this.server.close();
-    }
-  }
-
-  currentConfig(): CapletsConfig {
-    return this.engine.currentConfig();
-  }
-
-  watchedPaths(): string[] {
-    return this.engine.watchedPaths();
-  }
-```
-
-Replace `handleTool` with a delegate:
-
-```ts
-  private async handleTool(serverId: string, request: unknown): Promise<any> {
-    return await this.engine.execute(serverId, request);
-  }
-```
-
-Keep `reconcileTools`, `registerCapletTool`, `nextEnabledServers`, `capletById`, and `serializeCaplet` in `runtime.ts` because they are MCP tool-registration concerns.
-
-- [ ] **Step 3: Remove duplicated runtime helper code**
-
-Delete these from `packages/core/src/runtime.ts` after the engine delegate is in place:
-
-```ts
-type RuntimePaths = { configPath: string; projectConfigPath: string };
-type WatchedPath = { path: string; reason: "config" | "caplets" };
-selectAuthOptions;
-watchedPaths;
-uniqueWatchedPaths;
-allCaplets;
-nearestExistingParent;
-discoverDirectories;
-isDirectory;
-```
-
-Keep `nextEnabledServers`, `capletById`, and `serializeCaplet` if they are still used by MCP reconciliation.
-
-- [ ] **Step 4: Run runtime tests**
-
-Run: `pnpm --filter @caplets/core test -- test/runtime.test.ts`
-
-Expected: PASS.
-
-- [ ] **Step 5: Run focused core tests**
-
-Run: `pnpm --filter @caplets/core test -- test/engine.test.ts test/runtime.test.ts`
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```sh
-git add packages/core/src/runtime.ts packages/core/test/runtime.test.ts
-git commit -m "refactor(core): reuse engine in MCP runtime"
-```
-
----
-
-### Task 3: Make Native Service Reloadable
-
-**Files:**
-
-- Modify: `packages/core/src/native/service.ts`
-- Modify: `packages/core/src/native.ts`
-- Test: `packages/core/test/native.test.ts`
-
-- [ ] **Step 1: Write failing native reload tests**
-
-Append these tests to `packages/core/test/native.test.ts` before the `tempConfig` helper:
-
-```ts
-it("reloads native tool metadata after config changes", async () => {
-  const { dir, configPath, projectConfigPath } = tempConfig({
-    mcpServers: {
-      alpha: {
-        name: "Alpha",
-        description: "Search alpha project documents.",
-        command: process.execPath,
-      },
-    },
-  });
-  dirs.push(dir);
-  const service = createNativeCapletsService({ configPath, projectConfigPath, watch: false });
-
-  try {
-    expect(service.listTools().map((tool) => tool.caplet)).toEqual(["alpha"]);
-    writeFileSync(
-      configPath,
-      JSON.stringify({
-        mcpServers: {
-          beta: {
-            name: "Beta",
-            description: "Search beta project documents.",
-            command: process.execPath,
-          },
-        },
-      }),
-    );
-
-    await expect(service.reload()).resolves.toBe(true);
-    expect(service.listTools()).toEqual([
-      expect.objectContaining({ caplet: "beta", toolName: "caplets_beta", title: "Beta" }),
-    ]);
-  } finally {
-    await service.close();
-  }
-});
-
-it("notifies native tool listeners on successful reload only", async () => {
-  const { dir, configPath, projectConfigPath } = tempConfig({
-    mcpServers: {
-      alpha: {
-        name: "Alpha",
-        description: "Search alpha project documents.",
-        command: process.execPath,
-      },
-    },
-  });
-  dirs.push(dir);
-  const service = createNativeCapletsService({ configPath, projectConfigPath, watch: false });
-  const events: string[][] = [];
-  const unsubscribe = service.onToolsChanged((tools) => {
-    events.push(tools.map((tool) => tool.caplet));
-  });
-
-  try {
-    writeFileSync(configPath, "{ invalid json");
-    await expect(service.reload()).resolves.toBe(false);
-    expect(events).toEqual([]);
-
-    writeFileSync(
-      configPath,
-      JSON.stringify({
-        mcpServers: {
-          gamma: {
-            name: "Gamma",
-            description: "Search gamma project documents.",
-            command: process.execPath,
-          },
-        },
-      }),
-    );
-    await expect(service.reload()).resolves.toBe(true);
-    expect(events).toEqual([["gamma"]]);
-
-    unsubscribe();
-    writeFileSync(
-      configPath,
-      JSON.stringify({
-        mcpServers: {
-          delta: {
-            name: "Delta",
-            description: "Search delta project documents.",
-            command: process.execPath,
-          },
-        },
-      }),
-    );
-    await expect(service.reload()).resolves.toBe(true);
-    expect(events).toEqual([["gamma"]]);
-  } finally {
-    await service.close();
-  }
-});
-```
-
-Update the import from `node:fs` at the top of `native.test.ts` to keep `writeFileSync` available; it already is available today.
-
-- [ ] **Step 2: Run native tests to verify they fail**
-
-Run: `pnpm --filter @caplets/core test -- test/native.test.ts`
-
-Expected: FAIL because `watch`, `reload`, and `onToolsChanged` are not in `NativeCapletsServiceOptions` / `NativeCapletsService` yet.
-
-- [ ] **Step 3: Extend native service types**
-
-In `packages/core/src/native/service.ts`, replace the type block with:
-
-```ts
-export type NativeCapletsServiceOptions = {
-  configPath?: string;
-  projectConfigPath?: string;
-  authDir?: string;
-  watchDebounceMs?: number;
-  watch?: boolean;
-  writeErr?: (value: string) => void;
-};
-
-export type NativeCapletTool = {
-  caplet: string;
-  toolName: string;
-  title: string;
-  description: string;
-  promptGuidance: string[];
-};
-
-export type NativeCapletsToolsChangedListener = (tools: NativeCapletTool[]) => void;
-
-export type NativeCapletsService = {
-  listTools(): NativeCapletTool[];
-  execute(capletId: string, request: unknown): Promise<unknown>;
-  reload(): Promise<boolean>;
-  onToolsChanged(listener: NativeCapletsToolsChangedListener): () => void;
-  close(): Promise<void>;
-};
-```
-
-- [ ] **Step 4: Replace native service internals with `CapletsEngine`**
-
-In `packages/core/src/native/service.ts`, remove direct manager/config imports and add:
-
-```ts
-import { CapletsEngine } from "../engine";
-```
-
-Replace `DefaultNativeCapletsService` with:
-
-```ts
-class DefaultNativeCapletsService implements NativeCapletsService {
-  private readonly engine: CapletsEngine;
-
-  constructor(options: NativeCapletsServiceOptions) {
-    this.engine = new CapletsEngine(options);
-  }
-
-  listTools(): NativeCapletTool[] {
-    return this.engine.enabledServers().map((caplet) => {
-      const toolName = nativeCapletToolName(caplet.server);
-      return {
-        caplet: caplet.server,
-        toolName,
-        title: caplet.name,
-        description: nativeCapletToolDescription(toolName, caplet),
-        promptGuidance: nativeCapletPromptGuidance(toolName, caplet),
-      };
-    });
-  }
-
-  async execute(capletId: string, request: unknown): Promise<unknown> {
-    return await this.engine.execute(capletId, request);
-  }
-
-  async reload(): Promise<boolean> {
-    return await this.engine.reload();
-  }
-
-  onToolsChanged(listener: NativeCapletsToolsChangedListener): () => void {
-    return this.engine.onReload(() => listener(this.listTools()));
-  }
-
-  async close(): Promise<void> {
-    await this.engine.close();
-  }
-}
-```
-
-- [ ] **Step 5: Export listener type**
-
-In `packages/core/src/native.ts`, update the export block:
-
-```ts
-export {
-  createNativeCapletsService,
-  type NativeCapletTool,
-  type NativeCapletsService,
-  type NativeCapletsServiceOptions,
-  type NativeCapletsToolsChangedListener,
-} from "./native/service";
-```
-
-- [ ] **Step 6: Run native tests**
-
-Run: `pnpm --filter @caplets/core test -- test/native.test.ts`
-
-Expected: PASS.
-
-- [ ] **Step 7: Run core focused tests**
-
-Run: `pnpm --filter @caplets/core test -- test/engine.test.ts test/runtime.test.ts test/native.test.ts`
-
-Expected: PASS.
-
-- [ ] **Step 8: Commit**
-
-```sh
-git add packages/core/src/native.ts packages/core/src/native/service.ts packages/core/test/native.test.ts
-git commit -m "feat(core): hot reload native Caplets service"
-```
-
----
-
-### Task 4: Sync Pi Native Tools At Runtime
-
-**Files:**
-
-- Modify: `packages/pi/src/index.ts`
-- Test: `packages/pi/test/pi.test.ts`
-
-- [ ] **Step 1: Extend Pi test API types**
-
-In `packages/pi/test/pi.test.ts`, add this helper type near `RegisteredTool`:
-
-```ts
-type MockPiApi = {
-  registerTool: Mock<(definition: unknown) => void>;
-  getActiveTools: Mock<() => Array<{ name: string }>>;
-  setActiveTools: Mock<(names: string[]) => void>;
-};
-```
-
-Add this helper near `mockService`:
-
-```ts
-function mockPiApi(activeTools: string[] = []): { api: MockPiApi; registered: RegisteredTool[] } {
-  const registered: RegisteredTool[] = [];
-  const api: MockPiApi = {
-    registerTool: vi.fn((definition) => registered.push(definition as RegisteredTool)),
-    getActiveTools: vi.fn(() => activeTools.map((name) => ({ name }))),
-    setActiveTools: vi.fn(),
-  };
-  return { api, registered };
-}
-```
-
-Update `mockService` so tests can trigger listeners:
-
-```ts
-type MockService = NativeCapletsService & {
-  listTools: Mock<() => NativeCapletTool[]>;
-  execute: Mock<NativeCapletsService["execute"]>;
-  reload: Mock<NativeCapletsService["reload"]>;
-  onToolsChanged: Mock<NativeCapletsService["onToolsChanged"]>;
-  close: Mock<NativeCapletsService["close"]>;
-  setTools(tools: NativeCapletTool[]): void;
-  emitToolsChanged(): void;
-};
-
-function mockService(tools: NativeCapletTool[]): MockService {
-  let currentTools = tools;
-  const listeners = new Set<(tools: NativeCapletTool[]) => void>();
-  return {
-    listTools: vi.fn<() => NativeCapletTool[]>(() => currentTools),
-    execute: vi.fn(async () => ({ ok: true })),
-    reload: vi.fn(async () => true),
-    onToolsChanged: vi.fn((listener) => {
-      listeners.add(listener);
-      return () => listeners.delete(listener);
-    }),
-    close: vi.fn(async () => {}),
-    setTools(nextTools) {
-      currentTools = nextTools;
-    },
-    emitToolsChanged() {
-      for (const listener of listeners) listener(currentTools);
-    },
-  };
-}
-```
-
-- [ ] **Step 2: Add failing Pi dynamic sync tests**
-
-Append these tests to `packages/pi/test/pi.test.ts`:
-
-```ts
-it("registers newly added tools when the native service changes", () => {
-  const service = mockService([
-    {
-      caplet: "git-hub",
-      toolName: "caplets_git_hub",
-      title: "GitHub",
-      description: "GitHub Caplet",
-      promptGuidance: ["Use caplets_git_hub for GitHub."],
-    },
-  ]);
-  const { api, registered } = mockPiApi(["read", "caplets_git_hub"]);
-
-  capletsPiExtension(api, { service });
-  service.setTools([
-    {
-      caplet: "git-hub",
-      toolName: "caplets_git_hub",
-      title: "GitHub",
-      description: "GitHub Caplet",
-      promptGuidance: ["Use caplets_git_hub for GitHub."],
-    },
-    {
-      caplet: "linear",
-      toolName: "caplets_linear",
-      title: "Linear",
-      description: "Linear Caplet",
-      promptGuidance: ["Use caplets_linear for Linear."],
-    },
-  ]);
-  service.emitToolsChanged();
-
-  expect(registered.map((tool) => tool.name)).toEqual(["caplets_git_hub", "caplets_linear"]);
-  expect(api.setActiveTools).toHaveBeenLastCalledWith([
-    "read",
-    "caplets_git_hub",
-    "caplets_linear",
-  ]);
-});
-
-it("deactivates stale Caplets while preserving non-Caplets active tools", () => {
-  const service = mockService([
-    {
-      caplet: "git-hub",
-      toolName: "caplets_git_hub",
-      title: "GitHub",
-      description: "GitHub Caplet",
-      promptGuidance: ["Use caplets_git_hub for GitHub."],
-    },
-    {
-      caplet: "linear",
-      toolName: "caplets_linear",
-      title: "Linear",
-      description: "Linear Caplet",
-      promptGuidance: ["Use caplets_linear for Linear."],
-    },
-  ]);
-  const { api } = mockPiApi(["read", "bash", "caplets_git_hub", "caplets_linear"]);
-
-  capletsPiExtension(api, { service });
-  service.setTools([
-    {
-      caplet: "linear",
-      toolName: "caplets_linear",
-      title: "Linear",
-      description: "Linear Caplet",
-      promptGuidance: ["Use caplets_linear for Linear."],
-    },
-  ]);
-  service.emitToolsChanged();
-
-  expect(api.setActiveTools).toHaveBeenLastCalledWith(["read", "bash", "caplets_linear"]);
-});
-
-it("works when Pi active-tool APIs are unavailable", () => {
-  const service = mockService([]);
-  const registered: RegisteredTool[] = [];
-
-  capletsPiExtension(
-    { registerTool: (definition) => registered.push(definition as RegisteredTool) },
-    { service },
-  );
-
-  service.setTools([
-    {
-      caplet: "linear",
-      toolName: "caplets_linear",
-      title: "Linear",
-      description: "Linear Caplet",
-      promptGuidance: ["Use caplets_linear for Linear."],
-    },
-  ]);
-  service.emitToolsChanged();
-
-  expect(registered.map((tool) => tool.name)).toEqual(["caplets_linear"]);
-});
-```
-
-- [ ] **Step 3: Run Pi tests to verify they fail**
-
-Run: `pnpm --filter @caplets/pi test`
-
-Expected: FAIL because the adapter does not subscribe to `onToolsChanged` and does not call active-tool APIs.
-
-- [ ] **Step 4: Extend Pi adapter API type**
-
-In `packages/pi/src/index.ts`, change `PiExtensionApi` to:
-
-```ts
-export type PiExtensionApi = {
-  registerTool(definition: unknown): void;
-  getActiveTools?(): Array<{ name: string }>;
-  setActiveTools?(names: string[]): void;
-};
-```
-
-- [ ] **Step 5: Add Pi sync helpers**
-
-In `packages/pi/src/index.ts`, replace the loop in `capletsPiExtension` with a `syncTools` helper. Use this exact structure so active non-Caplets tools are preserved:
-
-```ts
-export default function capletsPiExtension(pi: PiExtensionApi, options: CapletsPiOptions = {}) {
-  const service = options.service ?? createNativeCapletsService();
-  if (!options.service) {
-    registerNativeCapletsProcessCleanup(service);
-  }
-
-  const registeredCapletTools = new Set<string>();
-  let knownCapletTools = new Set<string>();
-
-  const syncTools = (caplets = service.listTools()) => {
-    const nextCapletTools = new Set(caplets.map((caplet) => caplet.toolName));
-    for (const caplet of caplets) {
-      if (registeredCapletTools.has(caplet.toolName)) {
-        continue;
-      }
-      registeredCapletTools.add(caplet.toolName);
-      pi.registerTool(createPiTool(service, caplet));
-    }
-
-    if (pi.getActiveTools && pi.setActiveTools) {
-      const activeNonCaplets = pi
-        .getActiveTools()
-        .map((tool) => tool.name)
-        .filter((name) => !knownCapletTools.has(name));
-      pi.setActiveTools([...activeNonCaplets, ...nextCapletTools]);
-    }
-
-    knownCapletTools = nextCapletTools;
-  };
-
-  syncTools();
-  service.onToolsChanged(syncTools);
-}
-```
-
-Add this helper below `capletsPiExtension`:
-
-```ts
-function createPiTool(service: NativeCapletsService, caplet: NativeCapletTool): unknown {
-  return {
-    name: caplet.toolName,
-    label: caplet.title,
-    description: caplet.description,
-    promptSnippet: `Use ${caplet.toolName} for the ${caplet.title} Caplet capability domain.`,
-    promptGuidelines: caplet.promptGuidance,
-    parameters: capletsPiParameters(),
-    async execute(_toolCallId: string, params: unknown) {
-      const result = await service.execute(caplet.caplet, params);
-      const serialized = serializeResult(result);
-      return {
-        content: [{ type: "text", text: serialized.text }],
-        details: serialized.serializationError
-          ? { result, serializationError: serialized.serializationError }
-          : { result },
-      };
-    },
-  };
-}
-```
-
-Update the import from `@caplets/core/native` to include `type NativeCapletTool`.
-
-- [ ] **Step 6: Run Pi tests**
-
-Run: `pnpm --filter @caplets/pi test`
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit**
-
-```sh
-git add packages/pi/src/index.ts packages/pi/test/pi.test.ts
-git commit -m "feat(pi): sync native Caplet tools on reload"
-```
-
----
-
-### Task 5: Refresh OpenCode Guidance For Existing Tools
-
-**Files:**
-
-- Modify: `packages/opencode/src/index.ts`
-- Test: `packages/opencode/test/opencode.test.ts`
-
-- [ ] **Step 1: Add failing OpenCode guidance test**
-
-Append this test to `packages/opencode/test/opencode.test.ts`:
-
-```ts
-it("refreshes system guidance from the current native tool list", async () => {
-  const { createCapletsOpenCodeHooks } = await import("../src/index");
-  let tools = [
-    {
-      caplet: "git-hub",
-      toolName: "caplets_git_hub",
-      title: "GitHub",
-      description: "GitHub\n\nUse this Caplet.",
-      promptGuidance: ["Use caplets_git_hub for GitHub."],
-    },
-  ];
-  const service = {
-    listTools: () => tools,
-    execute: vi.fn(async () => ({ ok: true })),
-    reload: vi.fn(async () => true),
-    onToolsChanged: vi.fn(() => () => {}),
-    close: vi.fn(async () => {}),
-  };
-
-  const hooks = await createCapletsOpenCodeHooks(service);
-  tools = [
-    {
-      caplet: "linear",
-      toolName: "caplets_linear",
-      title: "Linear",
-      description: "Linear\n\nUse this Caplet.",
-      promptGuidance: ["Use caplets_linear for Linear."],
-    },
-  ];
-
-  const output = { system: [] as string[] };
-  await hooks["experimental.chat.system.transform"]?.({} as never, output);
-
-  expect(output.system.join("\n")).toContain("caplets_linear");
-  expect(output.system.join("\n")).not.toContain("caplets_git_hub");
-});
-```
-
-- [ ] **Step 2: Run OpenCode tests to verify failure**
-
-Run: `pnpm --filter @caplets/opencode test`
-
-Expected: FAIL because `toolNames` are snapshotted before the hook is returned.
-
-- [ ] **Step 3: Compute guidance at transform time**
-
-In `packages/opencode/src/index.ts`, keep `capletTools` for static `Hooks.tool`, but remove the top-level `toolNames` constant. Change the transform hook to:
-
-```ts
-    "experimental.chat.system.transform": async (_input, output) => {
-      output.system.push(
-        nativeCapletsSystemGuidance(service.listTools().map((caplet) => caplet.toolName)),
-      );
-    },
-```
-
-Do not dynamically add/remove OpenCode plugin tools in this task; the current OpenCode API does not support runtime plugin-tool inventory mutation.
-
-- [ ] **Step 4: Run OpenCode tests**
-
-Run: `pnpm --filter @caplets/opencode test`
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```sh
-git add packages/opencode/src/index.ts packages/opencode/test/opencode.test.ts
-git commit -m "feat(opencode): refresh native guidance from live service"
-```
-
----
-
-### Task 6: Document Host-Specific Hot Reload Behavior
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `packages/pi/README.md`
-- Modify: `packages/opencode/README.md`
-- Modify: `.changeset/native-agent-integrations.md`
-
-- [ ] **Step 1: Update root README native section**
-
-In `README.md`, replace lines 718-719 text with:
-
-```md
-Native integrations hot reload config and Caplet file edits through the same runtime used by
-`caplets serve`. Existing native tools execute against the latest valid config without host
-restart. Pi also refreshes newly added Caplet tools at runtime and deactivates removed Caplet
-tools when Pi's active-tool APIs are available. OpenCode's current plugin API snapshots the
-tool inventory at plugin load, so adding, removing, or renaming OpenCode native tools still
-requires restarting OpenCode; already-registered tools and injected guidance use live Caplets
-state.
-```
-
-- [ ] **Step 2: Update Pi README**
-
-In `packages/pi/README.md`, replace the final paragraph with:
-
-```md
-The extension hot reloads Caplets config and Caplet file edits. Existing tools execute against
-the latest valid backend config. Newly added Caplets are registered in the current Pi session;
-removed or disabled Caplets are deactivated with Pi's active-tool APIs when available. If Pi is
-running without `getActiveTools()` / `setActiveTools()`, stale tools may remain registered until
-Pi reloads extensions or restarts, but calls to removed Caplets return Caplets' normal structured
-"server not found" error.
-```
-
-- [ ] **Step 3: Update OpenCode README**
-
-In `packages/opencode/README.md`, replace the final paragraph with:
-
-```md
-The plugin hot reloads Caplets config and Caplet file edits for already-registered tools, so
-existing native tools execute against the latest valid backend config and prompt guidance is
-rebuilt from current Caplets state. OpenCode's current plugin API snapshots `Hooks.tool` at
-plugin load, so adding, removing, or renaming native tools still requires restarting OpenCode.
-```
-
-- [ ] **Step 4: Update existing changeset**
-
-Append this sentence to `.changeset/native-agent-integrations.md`:
-
-```md
-Native integrations now share the hot-reload runtime so existing native tools execute against
-the latest valid Caplets config; Pi can register newly added Caplet tools and deactivate stale
-ones at runtime when its active-tool APIs are available.
-```
-
-- [ ] **Step 5: Run docs formatting check**
-
-Run: `pnpm format:check`
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```sh
-git add README.md packages/pi/README.md packages/opencode/README.md .changeset/native-agent-integrations.md
-git commit -m "docs: describe native hot reload behavior"
-```
-
----
-
-### Task 7: Full Verification And Cleanup
-
-**Files:**
-
-- Verify all changed files.
-
-- [ ] **Step 1: Run package-focused tests**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/engine.test.ts test/runtime.test.ts test/native.test.ts
-pnpm --filter @caplets/pi test
-pnpm --filter @caplets/opencode test
-```
-
-Expected: all commands PASS.
-
-- [ ] **Step 2: Run typecheck**
-
-Run: `pnpm typecheck`
-
-Expected: PASS.
-
-- [ ] **Step 3: Run lint and format checks**
-
-Run:
-
-```sh
-pnpm format:check
-pnpm lint
-```
-
-Expected: both PASS.
-
-- [ ] **Step 4: Run full verification gate**
-
-Run: `pnpm verify`
-
-Expected: PASS, including `format:check`, `lint`, `typecheck`, `schema:check`, `test`, `benchmark:check`, and `build`.
-
-- [ ] **Step 5: Inspect final diff**
-
-Run:
-
-```sh
-git status --short
-git diff --stat HEAD
-git diff HEAD -- packages/core/src/engine.ts packages/core/src/runtime.ts packages/core/src/native/service.ts packages/pi/src/index.ts packages/opencode/src/index.ts
-```
-
-Expected: only planned files changed; no generated schema or benchmark docs changed unless `pnpm verify` explicitly updated them.
-
-- [ ] **Step 6: Final commit if previous task commits were skipped**
-
-If implementing as one commit instead of per-task commits, run:
-
-```sh
-git add packages/core/src/engine.ts packages/core/src/runtime.ts packages/core/src/native.ts packages/core/src/native/service.ts packages/core/test/engine.test.ts packages/core/test/runtime.test.ts packages/core/test/native.test.ts packages/pi/src/index.ts packages/pi/test/pi.test.ts packages/opencode/src/index.ts packages/opencode/test/opencode.test.ts README.md packages/pi/README.md packages/opencode/README.md .changeset/native-agent-integrations.md
-git commit -m "feat: hot reload native Caplets integrations"
-```
-
-Expected: commit succeeds without pre-commit failures.
-
----
-
-## Residual Risks
-
-- Pi `setActiveTools()` replaces the entire active tool list. The plan preserves all currently active non-Caplets tools and swaps only the Caplets-owned subset, but it cannot reactivate a non-Caplets tool that another extension intentionally deactivated before Caplets observes the active set.
-- Pi may treat duplicate `registerTool()` calls as collisions rather than updates. The plan avoids re-registering known tool names. If metadata changes for an existing Pi tool and Pi has no update API, the execution backend still updates, but the displayed label/description may remain as originally registered until Pi reloads extensions.
-- OpenCode cannot add/remove plugin tools at runtime with the current API. This plan documents that limitation and keeps the implementation ready to expand if OpenCode adds a runtime plugin-tool registry.
-- `fs.watch` behavior varies by platform. This plan preserves the existing `caplets serve` watcher strategy rather than changing watcher primitives.
-
-## Completion Criteria
-
-- `CapletsEngine` owns one copy of reload/watch/backend lifecycle behavior.
-- `CapletsRuntime` still passes all existing MCP hot-reload tests through the shared engine.
-- `createNativeCapletsService()` supports `reload()` and `onToolsChanged()` and hot reloads config state.
-- Pi registers newly added Caplets after native reload and deactivates stale Caplet tools without disabling active non-Caplets tools.
-- OpenCode existing native tools execute against live service state and system guidance is rebuilt from current service tools.
-- README/package docs explain exact host-specific behavior.
-- `pnpm verify` passes.
diff --git a/docs/plans/2026-05-19-caplets-interface-ux.md b/docs/plans/2026-05-19-caplets-interface-ux.md
deleted file mode 100644
index 1a8924e1..00000000
--- a/docs/plans/2026-05-19-caplets-interface-ux.md
+++ /dev/null
@@ -1,297 +0,0 @@
-# Caplets Interface UX Improvements Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use `subagent-driven-development` or `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Improve the Caplets agent interface with only low-risk, feasible changes that preserve the current wrapper protocol.
-
-**Architecture:** Keep `get_caplet`/`list_tools`/`get_tool`/`call_tool` unchanged. Add clearer Caplet identity in wrapper text and metadata, extract local artifact hints from downstream browser output, add schema fingerprints to compact tool metadata, and polish Pi rendering so large Caplet results stay readable.
-
-**Tech Stack:** TypeScript, Zod, MCP `CallToolResult`, Vitest, native Caplets service, Pi native-tool integration.
-
----
-
-## Why This Plan Exists
-
-After using both the Browser and Stealth Browser Caplets against `http://localhost:4199`, the interface worked, but these practical pain points stood out:
-
-- Browser and Stealth Browser expose identical downstream tool names, so results should identify the active Caplet more clearly.
-- Screenshot responses report relative paths such as `./browser-caplet-localhost-4199.png` without enough artifact-context metadata.
-- Two Caplets can expose identical downstream schemas, but agents have no lightweight way to recognize that known schemas match.
-- Current discovery results use generic text like `Result available in structuredContent.result.`.
-- The Pi wrapper serializes the whole result JSON in expanded mode, which is noisy for large snapshots and screenshots.
-- The generated prompt guidance is correct but over-cautious; it nudges agents to rediscover familiar tools every time.
-
----
-
-## Explicitly Out Of Scope
-
-These ideas are feasible in theory but are not included because they add protocol complexity or compatibility risk:
-
-- Fast-path `call_tool` requests without `operation`.
-- A batched browser `run_flow` operation.
-- Wrapping direct `call_tool` results in a new `structuredContent.result` envelope.
-- Guaranteed absolute screenshot paths when the downstream MCP browser server only reports relative paths.
-- Flattening downstream browser tools into separate native tools.
-
----
-
-## Decisions Locked
-
-- Keep existing operation names, request shapes, and behavior backward compatible.
-- Do not require agents to change existing Caplets calls.
-- Preserve direct `call_tool` pass-through shape: keep downstream `content`, `structuredContent`, `isError`, and `_meta` intact.
-- Add Caplets metadata to direct `call_tool` results only under `_meta.caplets`.
-- Add richer metadata to wrapper-generated discovery results under `structuredContent.caplets` while keeping `structuredContent.result` unchanged.
-- Expose artifact paths as hints with explicit path-resolution status when absolute paths cannot be guaranteed.
-- Treat schema fingerprints as hints for reuse, not as a replacement for `get_tool` when semantics are unclear.
-
----
-
-## Files To Modify
-
-- `packages/core/src/tools.ts`: annotate wrapper results, add artifact extraction, and improve wrapper text.
-- `packages/core/src/downstream.ts`: add schema fingerprints to MCP compact metadata.
-- `packages/core/src/openapi.ts`: add schema fingerprints to OpenAPI compact metadata.
-- `packages/core/src/http-actions.ts`: add schema fingerprints to HTTP compact metadata.
-- `packages/core/src/cli-tools.ts`: add schema fingerprints to CLI compact metadata.
-- `packages/core/src/caplet-sets.ts`: add schema fingerprints to Caplet-set compact metadata.
-- `packages/core/src/graphql.ts`: add schema fingerprints to GraphQL compact metadata.
-- `packages/core/src/native/tools.ts`: update native system guidance and prompt guidance.
-- `packages/pi/src/index.ts`: render concise Caplet summaries and artifact hints.
-- `packages/core/test/tools.test.ts`: wrapper text, metadata, and artifact tests.
-- Backend tests under `packages/core/test/`: compact metadata fingerprint tests.
-- `packages/core/test/native.test.ts`: guidance tests.
-- `packages/pi/test/pi.test.ts`: renderer tests.
-- `README.md`: document the metadata, artifact, and schema-fingerprint improvements.
-
----
-
-## Public Result Shape Additions
-
-### Discovery operation metadata
-
-Discovery operations keep the existing `structuredContent.result` shape and add Caplets metadata beside it:
-
-```json
-{
-  "content": [
-    {
-      "type": "text",
-      "text": "Browser list_tools result available in structuredContent.result."
-    }
-  ],
-  "structuredContent": {
-    "caplets": {
-      "id": "browser",
-      "name": "Browser",
-      "backend": "mcp",
-      "operation": "list_tools",
-      "status": "ok"
-    },
-    "result": {
-      "id": "browser",
-      "tools": []
-    }
-  }
-}
-```
-
-### Direct `call_tool` metadata
-
-Direct downstream results are not enveloped. Caplets metadata is attached under `_meta.caplets`:
-
-```json
-{
-  "content": [{ "type": "text", "text": "...downstream output..." }],
-  "structuredContent": { "ok": true },
-  "_meta": {
-    "caplets": {
-      "id": "browser",
-      "name": "Browser",
-      "backend": "mcp",
-      "operation": "call_tool",
-      "tool": "browser_take_screenshot",
-      "status": "ok",
-      "artifacts": [
-        {
-          "kind": "screenshot",
-          "displayPath": "./browser-caplet-localhost-4199.png",
-          "pathResolution": "relative-to-mcp-server"
-        }
-      ]
-    }
-  }
-}
-```
-
-### Compact schema fingerprints
-
-Compact tool metadata gains stable schema hashes:
-
-```json
-{
-  "id": "browser",
-  "tool": "browser_navigate",
-  "description": "Navigate to a URL",
-  "hasInputSchema": true,
-  "hasOutputSchema": false,
-  "inputSchemaHash": "sha256:...",
-  "outputSchemaHash": null
-}
-```
-
----
-
-## Task 1: Add Shared Caplet Metadata Helpers
-
-**Files:**
-
-- Modify: `packages/core/src/tools.ts`
-- Test: `packages/core/test/tools.test.ts`
-
-- [ ] Add a `CapletResultMetadata` type with `caplet`, `name`, `backend`, `operation`, optional `tool`, `status`, optional `elapsedMs`, and optional `artifacts`.
-- [ ] Add `metadataFor(server, operation, tool, startedAt)` to build metadata consistently.
-- [ ] Add `jsonResult(value, metadata)` support while preserving the existing `structuredContent.result` field.
-- [ ] Add `annotateCallToolResult(result, metadata)` that preserves downstream `content`, `structuredContent`, `isError`, and existing `_meta` fields.
-- [ ] Ensure `annotateCallToolResult()` merges with an existing `_meta` object instead of replacing it.
-- [ ] Add tests proving `get_caplet`, `list_tools`, and `get_tool` include `structuredContent.caplets` and keep `structuredContent.result` unchanged.
-- [ ] Add tests proving direct `call_tool` results keep their original shape and receive `_meta.caplets`.
-- [ ] Add tests proving downstream `_meta` values are preserved.
-- [ ] Add tests proving `isError: true` downstream results are annotated but otherwise unchanged.
-- [ ] Run `pnpm --filter @caplets/core test -- test/tools.test.ts`.
-
----
-
-## Task 2: Improve Human-Readable Result Headers
-
-**Files:**
-
-- Modify: `packages/core/src/tools.ts`
-- Modify: `packages/pi/src/index.ts`
-- Test: `packages/core/test/tools.test.ts`
-- Test: `packages/pi/test/pi.test.ts`
-
-- [ ] Change discovery-operation text from `Result available in structuredContent.result.` to a Caplet-specific sentence such as `Browser list_tools result available in structuredContent.result.`.
-- [ ] Keep discovery text short and do not inline large structured payloads.
-- [ ] Update Pi `renderCall()` if needed so operation and downstream tool names remain visible for identical tool names across Caplets.
-- [ ] Update Pi collapsed `renderResult()` to prefer `_meta.caplets` or `structuredContent.caplets` and render `✓ Browser call_tool browser_click complete` when metadata exists.
-- [ ] Update Pi expanded `renderResult()` to show a concise metadata header before output.
-- [ ] Add tests for Browser and Stealth Browser style names proving identical downstream tool names are disambiguated by Caplet title.
-- [ ] Run `pnpm --filter @caplets/core test -- test/tools.test.ts` and `pnpm --filter @caplets/pi test`.
-
----
-
-## Task 3: Add Artifact Metadata Extraction
-
-**Files:**
-
-- Modify: `packages/core/src/tools.ts`
-- Test: `packages/core/test/tools.test.ts`
-
-- [ ] Add an artifact extractor that scans downstream text content for local Markdown links emitted by MCP browser tools, for example `[Screenshot of viewport](./file.png)`.
-- [ ] Ignore `http:`, `https:`, `mailto:`, and fragment-only links.
-- [ ] Classify common artifacts by filename and surrounding text: `screenshot`, `snapshot`, `console-log`, `network-log`, and fallback `file`.
-- [ ] Return artifact objects with `kind`, `displayPath`, and `pathResolution`.
-- [ ] Use `pathResolution: "relative-to-mcp-server"` for relative paths unless core can reliably resolve the downstream output directory.
-- [ ] Use `pathResolution: "absolute"` only for absolute local paths that already appear in downstream output.
-- [ ] Attach extracted artifacts to `_meta.caplets.artifacts` on direct `call_tool` results.
-- [ ] Add tests for screenshot links, snapshot links, console-log links, multiple artifacts, no artifacts, and external links.
-- [ ] Run `pnpm --filter @caplets/core test -- test/tools.test.ts`.
-
----
-
-## Task 4: Add Schema Fingerprints To Compact Tool Metadata
-
-**Files:**
-
-- Modify: `packages/core/src/downstream.ts`
-- Modify: `packages/core/src/openapi.ts`
-- Modify: `packages/core/src/http-actions.ts`
-- Modify: `packages/core/src/cli-tools.ts`
-- Modify: `packages/core/src/caplet-sets.ts`
-- Modify: `packages/core/src/graphql.ts`
-- Test: backend-specific test files under `packages/core/test/`
-
-- [ ] Add a small stable JSON hashing utility for schema-like values using deterministic key ordering and SHA-256.
-- [ ] Extend every backend compact tool shape with `inputSchemaHash` and `outputSchemaHash`.
-- [ ] Return `null` for a missing schema so compact output has a stable shape.
-- [ ] Keep full schemas available only through `get_tool`.
-- [ ] Add tests proving two identical schemas produce identical hashes.
-- [ ] Add tests proving object key order differences do not change hashes.
-- [ ] Update existing compact metadata test expectations for all backend managers touched.
-- [ ] Run focused backend tests, then `pnpm typecheck`.
-
----
-
-## Task 5: Update Native Agent Guidance
-
-**Files:**
-
-- Modify: `packages/core/src/native/tools.ts`
-- Test: `packages/core/test/native.test.ts`
-
-- [ ] Update `nativeCapletsSystemGuidance()` so the recommended flow says `get_caplet` and `get_tool` are for unfamiliar or schema-unclear tools, not mandatory for every repeat use.
-- [ ] Add guidance that schema hashes from `list_tools` can identify matching schemas across Caplets when the exact hash is already understood.
-- [ ] Keep the warning that downstream inputs must stay inside `arguments`.
-- [ ] Keep the warning that agents must not invent downstream tool names.
-- [ ] Update `nativeCapletPromptGuidance()` to be less repetitive while preserving the safe discovery path.
-- [ ] Add tests for revised guidance text.
-- [ ] Run `pnpm --filter @caplets/core test -- test/native.test.ts`.
-
----
-
-## Task 6: Polish Pi Rendering For Large Caplet Results
-
-**Files:**
-
-- Modify: `packages/pi/src/index.ts`
-- Test: `packages/pi/test/pi.test.ts`
-
-- [ ] Add a helper that extracts Caplets metadata from either `details.result._meta.caplets` or `details.result.structuredContent.caplets`.
-- [ ] Update collapsed rendering to use metadata when present and keep the output one line.
-- [ ] Update expanded rendering to show metadata, artifact lines, and then a concise output preview.
-- [ ] Keep the full raw result available in `details.result` for inspection.
-- [ ] Avoid dumping huge snapshot text before the useful summary.
-- [ ] Add tests where result content contains a large snapshot to ensure collapsed output remains concise.
-- [ ] Add tests where screenshot metadata renders a clear artifact line.
-- [ ] Run `pnpm --filter @caplets/pi test`.
-
----
-
-## Task 7: Documentation
-
-**Files:**
-
-- Modify: `README.md`
-
-- [ ] Document that discovery results now include `structuredContent.caplets` metadata.
-- [ ] Document that direct `call_tool` results keep their downstream shape and include `_meta.caplets` when possible.
-- [ ] Document artifact metadata and path-resolution caveats.
-- [ ] Document schema hashes as reuse hints, not as a replacement for `get_tool` when semantics are unclear.
-- [ ] Document that the explicit progressive-discovery flow remains the safest first-use path.
-- [ ] Run `pnpm format:check`.
-
----
-
-## Task 8: Full Verification
-
-**Files:**
-
-- No direct source changes unless failures reveal missing updates.
-
-- [ ] Run `pnpm format:check`.
-- [ ] Run `pnpm lint`.
-- [ ] Run `pnpm typecheck`.
-- [ ] Run `pnpm test`.
-- [ ] Run `pnpm build`.
-- [ ] If schema generation changed checked files, run `pnpm schema:generate` and then `pnpm schema:check`.
-- [ ] If benchmark docs are stale, run `pnpm benchmark` and then `pnpm benchmark:check`.
-- [ ] Run `pnpm verify` before merging.
-
----
-
-## Rollout Notes
-
-- If adding `_meta.caplets` to direct `call_tool` results causes compatibility issues, keep metadata only for wrapper-generated operations and Pi rendering can fall back to call arguments.
-- If artifact extraction produces false positives, restrict it to MCP Caplets whose downstream tool names start with `browser_`.
-- If schema hashing changes compact output too much for snapshots/tests, ship hashes behind one shared compact helper and update all backend expectations together.
diff --git a/docs/plans/2026-05-19-http-mcp-serving.md b/docs/plans/2026-05-19-http-mcp-serving.md
deleted file mode 100644
index aec6c292..00000000
--- a/docs/plans/2026-05-19-http-mcp-serving.md
+++ /dev/null
@@ -1,1648 +0,0 @@
-# HTTP MCP Serving Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add opt-in Hono-based Streamable HTTP MCP serving to `caplets serve` with optional Basic Auth, while making no-arg `caplets` show help.
-
-**Architecture:** Refactor MCP tool registration/reload reconciliation into a reusable `CapletsMcpSession` that shares one `CapletsEngine` across stdio and HTTP sessions. Stdio creates one session and connects it to `StdioServerTransport`; HTTP creates a Hono app, routes each `Mcp-Session-Id` to a per-session `@hono/mcp` `StreamableHTTPTransport`, and keeps all sessions backed by the same engine.
-
-**Tech Stack:** TypeScript, Commander, Vitest, MCP SDK, Hono, `@hono/node-server`, `@hono/mcp`, pnpm.
-
----
-
-## File structure
-
-- Modify `packages/core/package.json` to add direct Hono dependencies.
-- Create `packages/core/src/serve/session.ts` for reusable MCP server/session registration and reload reconciliation.
-- Modify `packages/core/src/runtime.ts` so `CapletsRuntime` delegates to `CapletsMcpSession` and preserves its public API.
-- Create `packages/core/src/serve/options.ts` for serve option normalization, validation, auth resolution, path normalization, and loopback detection.
-- Create `packages/core/src/serve/stdio.ts` for stdio serve orchestration.
-- Create `packages/core/src/serve/http.ts` for Hono routes, Basic Auth middleware, MCP session map, DNS rebinding transport options, startup logs, and shutdown cleanup.
-- Create `packages/core/src/serve/index.ts` to expose `serveCaplets`, `serveStdio`, `serveHttp`, and option types.
-- Modify `packages/core/src/cli.ts` to add `serve`, no-arg help, and a test-injectable serve runner.
-- Modify `packages/cli/src/index.ts` to always delegate to `runCli`.
-- Add `packages/core/test/serve-options.test.ts` for option validation and auth resolution.
-- Add `packages/core/test/serve-session.test.ts` for shared session tool reconciliation.
-- Add `packages/core/test/serve-http.test.ts` for Hono route/auth/session behavior.
-- Modify `packages/core/test/cli.test.ts` for no-arg help and `serve` command parsing through injected runner.
-- Keep `packages/core/test/runtime.test.ts` passing as compatibility coverage.
-
----
-
-### Task 1: Add Hono dependencies
-
-**Files:**
-
-- Modify: `packages/core/package.json`
-- Modify: `pnpm-lock.yaml`
-
-- [ ] **Step 1: Add dependencies with pnpm**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core add @hono/mcp@^0.3.0 @hono/node-server@^1.19.9 hono@^4.11.5
-```
-
-Expected: `packages/core/package.json` contains the three new dependencies and `pnpm-lock.yaml` is updated.
-
-- [ ] **Step 2: Verify package manifest**
-
-Check `packages/core/package.json` contains this dependency block shape:
-
-```json
-{
-  "dependencies": {
-    "@apidevtools/swagger-parser": "^12.1.0",
-    "@hono/mcp": "^0.3.0",
-    "@hono/node-server": "^1.19.9",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "commander": "^14.0.3",
-    "graphql": "^16.14.0",
-    "hono": "^4.11.5",
-    "vfile": "^6.0.3",
-    "vfile-matter": "^5.0.1",
-    "zod": "^4.4.3"
-  }
-}
-```
-
-The exact order may be adjusted by the package manager, but all three Hono dependencies must be direct dependencies.
-
-- [ ] **Step 3: Commit dependency change**
-
-Run:
-
-```bash
-git add packages/core/package.json pnpm-lock.yaml
-git commit -m "chore(core): add Hono MCP dependencies"
-```
-
----
-
-### Task 2: Extract reusable MCP session wrapper
-
-**Files:**
-
-- Create: `packages/core/src/serve/session.ts`
-- Modify: `packages/core/src/runtime.ts`
-- Test: `packages/core/test/serve-session.test.ts`
-- Existing test: `packages/core/test/runtime.test.ts`
-
-- [ ] **Step 1: Write failing session tests**
-
-Create `packages/core/test/serve-session.test.ts`:
-
-```ts
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { CapletsEngine } from "../src/engine";
-import { CapletsMcpSession } from "../src/serve/session";
-
-const dirs: string[] = [];
-
-afterEach(() => {
-  for (const dir of dirs.splice(0)) {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-describe("CapletsMcpSession", () => {
-  it("registers enabled Caplets from a shared engine", async () => {
-    const { dir, configPath, projectConfigPath } = tempConfig({
-      mcpServers: {
-        alpha: { name: "Alpha", description: "Search alpha.", command: "node" },
-        beta: { name: "Beta", description: "Search beta.", command: "node", disabled: true },
-      },
-    });
-    dirs.push(dir);
-    const engine = new CapletsEngine({ configPath, projectConfigPath, watch: false });
-    const server = mockServer();
-    const session = new CapletsMcpSession(engine, { server });
-
-    expect(session.registeredToolIds()).toEqual(["alpha"]);
-    expect(server.registerTool).toHaveBeenCalledTimes(1);
-
-    await session.close();
-    await engine.close();
-  });
-
-  it("reconciles tools when the shared engine reloads", async () => {
-    const { dir, configPath, projectConfigPath } = tempConfig({
-      mcpServers: {
-        alpha: { name: "Alpha", description: "Search alpha.", command: "node" },
-      },
-    });
-    dirs.push(dir);
-    const engine = new CapletsEngine({ configPath, projectConfigPath, watch: false });
-    const server = mockServer();
-    const session = new CapletsMcpSession(engine, { server });
-    const alpha = server.registered.get("alpha")!;
-
-    writeConfig(configPath, {
-      httpApis: {
-        gamma: {
-          name: "Gamma HTTP",
-          description: "Call gamma over HTTP.",
-          baseUrl: "http://127.0.0.1:1",
-          auth: { type: "none" },
-          actions: { search: { method: "GET", path: "/search" } },
-        },
-      },
-    });
-    await engine.reload();
-
-    expect(alpha.remove).toHaveBeenCalledTimes(1);
-    expect(session.registeredToolIds()).toEqual(["gamma"]);
-    expect(server.registered.get("gamma")).toBeDefined();
-
-    await session.close();
-    await engine.close();
-  });
-});
-
-function tempConfig(config: unknown): {
-  dir: string;
-  configPath: string;
-  projectConfigPath: string;
-} {
-  const dir = mkdtempSync(join(tmpdir(), "caplets-session-"));
-  const userRoot = join(dir, "user");
-  const projectRoot = join(dir, "project", ".caplets");
-  mkdirSync(userRoot, { recursive: true });
-  mkdirSync(projectRoot, { recursive: true });
-  const configPath = join(userRoot, "config.json");
-  const projectConfigPath = join(projectRoot, "config.json");
-  writeConfig(configPath, config);
-  return { dir, configPath, projectConfigPath };
-}
-
-function writeConfig(path: string, config: unknown): void {
-  writeFileSync(path, JSON.stringify(config));
-}
-
-function mockServer() {
-  const registered = new Map<string, RegisteredTool>();
-  return {
-    registered,
-    registerTool: vi.fn((name: string) => {
-      const tool = {
-        update: vi.fn(),
-        remove: vi.fn(() => registered.delete(name)),
-        enable: vi.fn(),
-        disable: vi.fn(),
-        enabled: true,
-        handler: vi.fn(),
-      } as unknown as RegisteredTool;
-      registered.set(name, tool);
-      return tool;
-    }),
-    connect: vi.fn(async () => {}),
-    close: vi.fn(async () => {}),
-  };
-}
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/serve-session.test.ts
-```
-
-Expected: FAIL because `../src/serve/session` does not exist.
-
-- [ ] **Step 3: Implement `CapletsMcpSession`**
-
-Create `packages/core/src/serve/session.ts`:
-
-```ts
-import { McpServer, type RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp";
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport";
-import { version as packageJsonVersion } from "../../../package.json";
-import type { CapletConfig, CapletsConfig } from "../config";
-import { CapletsEngine } from "../engine";
-import { capabilityDescription } from "../registry";
-import { generatedToolInputSchema } from "../tools";
-
-export type ToolServer = Pick<McpServer, "registerTool" | "connect" | "close">;
-
-export type CapletsMcpSessionOptions = {
-  server?: ToolServer;
-};
-
-export class CapletsMcpSession {
-  readonly server: ToolServer;
-  private readonly tools = new Map<string, RegisteredTool>();
-  private readonly unsubscribeReload: () => void;
-  private closed = false;
-
-  constructor(
-    private readonly engine: CapletsEngine,
-    options: CapletsMcpSessionOptions = {},
-  ) {
-    this.server =
-      options.server ??
-      new McpServer({
-        name: "caplets",
-        version: packageJsonVersion,
-      });
-    this.unsubscribeReload = this.engine.onReload(({ previous, next }) =>
-      this.reconcileTools(previous, next),
-    );
-    this.reconcileTools(undefined, this.engine.currentConfig());
-  }
-
-  async connect(transport: Transport): Promise<void> {
-    await this.server.connect(transport);
-  }
-
-  registeredToolIds(): string[] {
-    return [...this.tools.keys()].sort();
-  }
-
-  async close(): Promise<void> {
-    if (this.closed) {
-      return;
-    }
-    this.closed = true;
-    this.unsubscribeReload();
-    this.tools.clear();
-    await this.server.close();
-  }
-
-  private reconcileTools(previous: CapletsConfig | undefined, next: CapletsConfig): void {
-    const enabled = new Map(nextEnabledServers(next).map((server) => [server.server, server]));
-
-    for (const [serverId, tool] of this.tools) {
-      const caplet = enabled.get(serverId);
-      if (!caplet) {
-        tool.remove();
-        this.tools.delete(serverId);
-        continue;
-      }
-
-      const previousCaplet = previous ? capletById(previous, serverId) : undefined;
-      if (!previousCaplet || serializeCaplet(previousCaplet) !== serializeCaplet(caplet)) {
-        tool.update({
-          title: caplet.name,
-          description: capabilityDescription(caplet),
-          callback: async (request) => this.handleTool(serverId, request),
-          enabled: true,
-        });
-      }
-    }
-
-    for (const caplet of enabled.values()) {
-      if (this.tools.has(caplet.server)) {
-        continue;
-      }
-      this.tools.set(caplet.server, this.registerCapletTool(caplet));
-    }
-  }
-
-  private registerCapletTool(caplet: CapletConfig): RegisteredTool {
-    return this.server.registerTool(
-      caplet.server,
-      {
-        title: caplet.name,
-        description: capabilityDescription(caplet),
-        inputSchema: generatedToolInputSchema,
-      },
-      async (request) => this.handleTool(caplet.server, request),
-    );
-  }
-
-  private async handleTool(serverId: string, request: unknown): Promise<any> {
-    return await this.engine.execute(serverId, request);
-  }
-}
-
-function nextEnabledServers(config: CapletsConfig): CapletConfig[] {
-  return [
-    ...Object.values(config.mcpServers),
-    ...Object.values(config.openapiEndpoints),
-    ...Object.values(config.graphqlEndpoints),
-    ...Object.values(config.httpApis),
-    ...Object.values(config.cliTools),
-    ...Object.values(config.capletSets),
-  ].filter((server) => !server.disabled);
-}
-
-function capletById(config: CapletsConfig, serverId: string): CapletConfig | undefined {
-  return (
-    config.mcpServers[serverId] ??
-    config.openapiEndpoints[serverId] ??
-    config.graphqlEndpoints[serverId] ??
-    config.httpApis[serverId] ??
-    config.cliTools[serverId] ??
-    config.capletSets[serverId]
-  );
-}
-
-function serializeCaplet(caplet: CapletConfig | undefined): string {
-  return JSON.stringify(caplet ?? null);
-}
-```
-
-- [ ] **Step 4: Refactor `CapletsRuntime` to delegate to the session wrapper**
-
-Replace `packages/core/src/runtime.ts` with:
-
-```ts
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport";
-import { type CapletsConfig } from "./config";
-import { CapletsEngine, type CapletsEngineOptions } from "./engine";
-import { CapletsMcpSession, type ToolServer } from "./serve/session";
-
-type CapletsRuntimeOptions = {
-  configPath?: string;
-  projectConfigPath?: string;
-  authDir?: string;
-  watchDebounceMs?: number;
-  server?: ToolServer;
-  writeErr?: (value: string) => void;
-};
-
-export class CapletsRuntime {
-  readonly server: ToolServer;
-  private readonly engine: CapletsEngine;
-  private readonly session: CapletsMcpSession;
-
-  constructor(options: CapletsRuntimeOptions = {}) {
-    this.engine = new CapletsEngine(engineOptions(options));
-    this.session = new CapletsMcpSession(this.engine, selectSessionOptions(options));
-    this.server = this.session.server;
-  }
-
-  async connect(transport: Transport): Promise<void> {
-    await this.session.connect(transport);
-  }
-
-  scheduleReload(): void {
-    this.engine.scheduleReload();
-  }
-
-  async reload(): Promise<boolean> {
-    return await this.engine.reload();
-  }
-
-  async close(): Promise<void> {
-    try {
-      await this.session.close();
-    } finally {
-      await this.engine.close();
-    }
-  }
-
-  currentConfig(): CapletsConfig {
-    return this.engine.currentConfig();
-  }
-
-  registeredToolIds(): string[] {
-    return this.session.registeredToolIds();
-  }
-
-  watchedPaths(): string[] {
-    return this.engine.watchedPaths();
-  }
-}
-
-function selectSessionOptions(options: CapletsRuntimeOptions): { server?: ToolServer } {
-  return options.server === undefined ? {} : { server: options.server };
-}
-
-function engineOptions(options: CapletsRuntimeOptions): CapletsEngineOptions {
-  const engineOptions: CapletsEngineOptions = {};
-  if (options.configPath !== undefined) {
-    engineOptions.configPath = options.configPath;
-  }
-  if (options.projectConfigPath !== undefined) {
-    engineOptions.projectConfigPath = options.projectConfigPath;
-  }
-  if (options.authDir !== undefined) {
-    engineOptions.authDir = options.authDir;
-  }
-  if (options.watchDebounceMs !== undefined) {
-    engineOptions.watchDebounceMs = options.watchDebounceMs;
-  }
-  if (options.writeErr !== undefined) {
-    engineOptions.writeErr = options.writeErr;
-  }
-  return engineOptions;
-}
-```
-
-- [ ] **Step 5: Run session and runtime tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/serve-session.test.ts test/runtime.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit session refactor**
-
-Run:
-
-```bash
-git add packages/core/src/serve/session.ts packages/core/src/runtime.ts packages/core/test/serve-session.test.ts
-git commit -m "refactor(core): share MCP session registration"
-```
-
----
-
-### Task 3: Add serve option normalization
-
-**Files:**
-
-- Create: `packages/core/src/serve/options.ts`
-- Test: `packages/core/test/serve-options.test.ts`
-
-- [ ] **Step 1: Write failing option tests**
-
-Create `packages/core/test/serve-options.test.ts`:
-
-```ts
-import { describe, expect, it } from "vitest";
-import { resolveServeOptions } from "../src/serve/options";
-
-describe("resolveServeOptions", () => {
-  it("defaults serve to stdio", () => {
-    expect(resolveServeOptions({}, {})).toEqual({ transport: "stdio" });
-  });
-
-  it("defaults HTTP serving to localhost port 5387 and /mcp", () => {
-    expect(resolveServeOptions({ transport: "http" }, {})).toMatchObject({
-      transport: "http",
-      host: "127.0.0.1",
-      port: 5387,
-      path: "/mcp",
-      auth: { enabled: false, user: "caplets" },
-    });
-  });
-
-  it("normalizes trailing slashes in HTTP path", () => {
-    expect(resolveServeOptions({ transport: "http", path: "/custom/" }, {})).toMatchObject({
-      transport: "http",
-      path: "/custom",
-    });
-  });
-
-  it("resolves Basic Auth from password with default user", () => {
-    const testPassword = ["test", "password"].join("-");
-
-    expect(resolveServeOptions({ transport: "http", password: testPassword }, {})).toMatchObject({
-      transport: "http",
-      auth: { enabled: true, user: "caplets", password: testPassword },
-    });
-  });
-
-  it("resolves Basic Auth from env and lets flags win", () => {
-    const envPassword = ["test", "env", "password"].join("-");
-
-    expect(
-      resolveServeOptions(
-        { transport: "http", user: "cli-user" },
-        { CAPLETS_SERVER_USER: "env-user", CAPLETS_SERVER_PASSWORD: envPassword },
-      ),
-    ).toMatchObject({
-      transport: "http",
-      auth: { enabled: true, user: "cli-user", password: envPassword },
-    });
-  });
-
-  it("rejects explicit user without password", () => {
-    expect(() => resolveServeOptions({ transport: "http", user: "alice" }, {})).toThrow(
-      /requires a password/u,
-    );
-  });
-
-  it("rejects HTTP-only options for stdio", () => {
-    expect(() => resolveServeOptions({ transport: "stdio", host: "127.0.0.1" }, {})).toThrow(
-      /only valid with --transport http/u,
-    );
-  });
-
-  it("rejects invalid port and path", () => {
-    expect(() => resolveServeOptions({ transport: "http", port: "0" }, {})).toThrow(
-      /valid TCP port/u,
-    );
-    expect(() => resolveServeOptions({ transport: "http", path: "mcp" }, {})).toThrow(
-      /must start with/u,
-    );
-    expect(() => resolveServeOptions({ transport: "http", path: "/mcp?x=1" }, {})).toThrow(
-      /query string/u,
-    );
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/serve-options.test.ts
-```
-
-Expected: FAIL because `../src/serve/options` does not exist.
-
-- [ ] **Step 3: Implement `serve/options.ts`**
-
-Create `packages/core/src/serve/options.ts`:
-
-```ts
-import { CapletsError } from "../errors";
-
-export type ServeTransport = "stdio" | "http";
-
-export type RawServeOptions = {
-  transport?: string;
-  host?: string;
-  port?: string | number;
-  path?: string;
-  user?: string;
-  password?: string;
-};
-
-export type StdioServeOptions = {
-  transport: "stdio";
-};
-
-export type HttpServeOptions = {
-  transport: "http";
-  host: string;
-  port: number;
-  path: string;
-  auth: HttpBasicAuthOptions;
-  warnUnauthenticatedNetwork: boolean;
-  loopback: boolean;
-};
-
-export type HttpBasicAuthOptions =
-  | { enabled: false; user: string }
-  | { enabled: true; user: string; password: string };
-
-export type ServeOptions = StdioServeOptions | HttpServeOptions;
-
-export type ServeEnv = Partial<Record<"CAPLETS_SERVER_USER" | "CAPLETS_SERVER_PASSWORD", string>>;
-
-const HTTP_ONLY_OPTIONS = ["host", "port", "path", "user", "password"] as const;
-
-export function resolveServeOptions(
-  raw: RawServeOptions,
-  env: ServeEnv = process.env,
-): ServeOptions {
-  const transport = parseTransport(raw.transport ?? "stdio");
-  if (transport === "stdio") {
-    const invalid = HTTP_ONLY_OPTIONS.filter((key) => raw[key] !== undefined);
-    if (invalid.length > 0) {
-      throw new CapletsError(
-        "REQUEST_INVALID",
-        `${invalid.map((key) => `--${key}`).join(", ")} ${invalid.length === 1 ? "is" : "are"} only valid with --transport http`,
-      );
-    }
-    return { transport };
-  }
-
-  const host = nonEmpty(raw.host, "--host") ?? "127.0.0.1";
-  const port = parsePort(raw.port ?? 5387);
-  const path = normalizeHttpPath(raw.path ?? "/mcp");
-  const userWasExplicit = raw.user !== undefined || hasEnv(env.CAPLETS_SERVER_USER);
-  const user =
-    nonEmpty(raw.user, "--user") ??
-    nonEmpty(env.CAPLETS_SERVER_USER, "CAPLETS_SERVER_USER") ??
-    "caplets";
-  const password =
-    nonEmpty(raw.password, "--password") ??
-    nonEmpty(env.CAPLETS_SERVER_PASSWORD, "CAPLETS_SERVER_PASSWORD");
-
-  if (userWasExplicit && password === undefined) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "HTTP Basic Auth requires a password; pass --password or set CAPLETS_SERVER_PASSWORD.",
-    );
-  }
-
-  const loopback = isLoopbackHost(host);
-  return {
-    transport,
-    host,
-    port,
-    path,
-    auth: password === undefined ? { enabled: false, user } : { enabled: true, user, password },
-    warnUnauthenticatedNetwork: !loopback && password === undefined,
-    loopback,
-  };
-}
-
-export function isLoopbackHost(host: string): boolean {
-  const normalized = host.toLocaleLowerCase();
-  return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
-}
-
-function parseTransport(value: string): ServeTransport {
-  if (value === "stdio" || value === "http") {
-    return value;
-  }
-  throw new CapletsError(
-    "REQUEST_INVALID",
-    `Expected --transport to be stdio or http, got ${value}`,
-  );
-}
-
-function parsePort(value: string | number): number {
-  const parsed = typeof value === "number" ? value : Number(value);
-  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      `Expected --port to be a valid TCP port, got ${value}`,
-    );
-  }
-  return parsed;
-}
-
-function normalizeHttpPath(value: string): string {
-  if (!value.startsWith("/")) {
-    throw new CapletsError("REQUEST_INVALID", "HTTP --path must start with /");
-  }
-  if (value.includes("?") || value.includes("#")) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "HTTP --path must not include a query string or fragment",
-    );
-  }
-  return value === "/" ? value : value.replace(/\/+$/u, "");
-}
-
-function nonEmpty(value: string | undefined, label: string): string | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    throw new CapletsError("REQUEST_INVALID", `${label} must not be empty`);
-  }
-  return trimmed;
-}
-
-function hasEnv(value: string | undefined): boolean {
-  return value !== undefined && value.trim() !== "";
-}
-```
-
-- [ ] **Step 4: Run option tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/serve-options.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit option normalization**
-
-Run:
-
-```bash
-git add packages/core/src/serve/options.ts packages/core/test/serve-options.test.ts
-git commit -m "feat(core): validate serve transport options"
-```
-
----
-
-### Task 4: Add stdio serve helper
-
-**Files:**
-
-- Create: `packages/core/src/serve/stdio.ts`
-- Create: `packages/core/src/serve/index.ts`
-- Test indirectly through later CLI tests
-
-- [ ] **Step 1: Implement stdio helper**
-
-Create `packages/core/src/serve/stdio.ts`:
-
-```ts
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
-import { CapletsEngine, type CapletsEngineOptions } from "../engine";
-import { CapletsMcpSession } from "./session";
-
-export type ServeStdioOptions = CapletsEngineOptions & {
-  signalHandling?: boolean;
-};
-
-export async function serveStdio(options: ServeStdioOptions = {}): Promise<void> {
-  const engine = new CapletsEngine(options);
-  const session = new CapletsMcpSession(engine);
-  let closing = false;
-
-  const close = async () => {
-    if (closing) {
-      return;
-    }
-    closing = true;
-    try {
-      await session.close();
-    } finally {
-      await engine.close();
-    }
-  };
-
-  if (options.signalHandling !== false) {
-    process.once("SIGINT", () => void close().finally(() => process.exit(130)));
-    process.once("SIGTERM", () => void close().finally(() => process.exit(143)));
-  }
-
-  await session.connect(new StdioServerTransport());
-}
-```
-
-Create `packages/core/src/serve/index.ts`:
-
-```ts
-import type { CapletsEngineOptions } from "../engine";
-import { resolveServeOptions, type RawServeOptions, type ServeOptions } from "./options";
-import { serveHttp } from "./http";
-import { serveStdio } from "./stdio";
-
-export { resolveServeOptions } from "./options";
-export type { HttpServeOptions, RawServeOptions, ServeOptions, StdioServeOptions } from "./options";
-export { serveHttp } from "./http";
-export { serveStdio } from "./stdio";
-
-export type ServeCapletsOptions = {
-  raw: RawServeOptions;
-  engine?: CapletsEngineOptions;
-  env?: NodeJS.ProcessEnv;
-  writeErr?: (value: string) => void;
-};
-
-export async function serveCaplets(options: ServeCapletsOptions): Promise<void> {
-  const resolved = resolveServeOptions(options.raw, options.env ?? process.env);
-  await serveResolvedCaplets(resolved, options.engine, options.writeErr);
-}
-
-export async function serveResolvedCaplets(
-  resolved: ServeOptions,
-  engineOptions: CapletsEngineOptions = {},
-  writeErr?: (value: string) => void,
-): Promise<void> {
-  if (resolved.transport === "stdio") {
-    await serveStdio({ ...engineOptions, ...(writeErr ? { writeErr } : {}) });
-    return;
-  }
-  await serveHttp(resolved, { ...engineOptions, ...(writeErr ? { writeErr } : {}) }, writeErr);
-}
-```
-
-This references `serveHttp` before it exists. The repository will not compile until Task 5 creates `packages/core/src/serve/http.ts`.
-
-- [ ] **Step 2: Do not commit yet**
-
-Do not commit this task independently because `serve/index.ts` imports `serveHttp`, which is created in the next task. Commit Task 4 and Task 5 together after tests pass.
-
----
-
-### Task 5: Add Hono HTTP serving
-
-**Files:**
-
-- Create: `packages/core/src/serve/http.ts`
-- Complete: `packages/core/src/serve/index.ts`
-- Test: `packages/core/test/serve-http.test.ts`
-
-- [ ] **Step 1: Write failing HTTP route/auth tests**
-
-Create `packages/core/test/serve-http.test.ts`:
-
-```ts
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { CapletsEngine } from "../src/engine";
-import { createHttpServeApp } from "../src/serve/http";
-import type { HttpServeOptions } from "../src/serve/options";
-
-const dirs: string[] = [];
-
-afterEach(() => {
-  for (const dir of dirs.splice(0)) {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-describe("createHttpServeApp", () => {
-  it("serves root info and health without auth", async () => {
-    const { engine } = testEngine();
-    const app = createHttpServeApp(httpOptions(), engine, { writeErr: () => {} });
-
-    const root = await app.request("http://127.0.0.1:5387/");
-    expect(root.status).toBe(200);
-    await expect(root.json()).resolves.toMatchObject({
-      name: "caplets",
-      transport: "http",
-      mcp: "/mcp",
-      health: "/healthz",
-      auth: { type: "basic", enabled: false },
-    });
-
-    const health = await app.request("http://127.0.0.1:5387/healthz");
-    expect(health.status).toBe(200);
-    await expect(health.json()).resolves.toEqual({
-      status: "ok",
-      transport: "http",
-      mcpPath: "/mcp",
-    });
-
-    await engine.close();
-  });
-
-  it("requires Basic Auth on MCP path when password is configured", async () => {
-    const { engine } = testEngine();
-    const testPassword = ["test", "password"].join("-");
-    const app = createHttpServeApp(
-      httpOptions({ auth: { enabled: true, user: "caplets", password: testPassword } }),
-      engine,
-      { writeErr: () => {} },
-    );
-
-    const missing = await app.request("http://127.0.0.1:5387/mcp", { method: "POST" });
-    expect(missing.status).toBe(401);
-    expect(missing.headers.get("www-authenticate")).toContain("Basic");
-
-    const wrong = await app.request("http://127.0.0.1:5387/mcp", {
-      method: "POST",
-      headers: {
-        authorization: `Basic ${Buffer.from(`caplets:not-the-${testPassword}`).toString("base64")}`,
-      },
-    });
-    expect(wrong.status).toBe(401);
-
-    await engine.close();
-  });
-
-  it("returns 404 for nested MCP paths", async () => {
-    const { engine } = testEngine();
-    const app = createHttpServeApp(httpOptions(), engine, { writeErr: () => {} });
-
-    const response = await app.request("http://127.0.0.1:5387/mcp/extra");
-    expect(response.status).toBe(404);
-
-    await engine.close();
-  });
-});
-
-function httpOptions(overrides: Partial<HttpServeOptions> = {}): HttpServeOptions {
-  return {
-    transport: "http",
-    host: "127.0.0.1",
-    port: 5387,
-    path: "/mcp",
-    auth: { enabled: false, user: "caplets" },
-    warnUnauthenticatedNetwork: false,
-    loopback: true,
-    ...overrides,
-  };
-}
-
-function testEngine(): { engine: CapletsEngine } {
-  const dir = mkdtempSync(join(tmpdir(), "caplets-http-"));
-  dirs.push(dir);
-  const userRoot = join(dir, "user");
-  const projectRoot = join(dir, "project", ".caplets");
-  mkdirSync(userRoot, { recursive: true });
-  mkdirSync(projectRoot, { recursive: true });
-  const configPath = join(userRoot, "config.json");
-  const projectConfigPath = join(projectRoot, "config.json");
-  writeFileSync(
-    configPath,
-    JSON.stringify({
-      httpApis: {
-        status: {
-          name: "Status",
-          description: "Status API.",
-          baseUrl: "http://127.0.0.1:1",
-          auth: { type: "none" },
-          actions: { check: { method: "GET", path: "/check" } },
-        },
-      },
-    }),
-  );
-  return { engine: new CapletsEngine({ configPath, projectConfigPath, watch: false }) };
-}
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/serve-http.test.ts
-```
-
-Expected: FAIL because `../src/serve/http` does not exist.
-
-- [ ] **Step 3: Implement Hono HTTP serving**
-
-Create `packages/core/src/serve/http.ts`:
-
-```ts
-import { randomUUID, timingSafeEqual } from "node:crypto";
-import type { ServerType } from "@hono/node-server";
-import { serve } from "@hono/node-server";
-import { StreamableHTTPTransport } from "@hono/mcp";
-import { Hono } from "hono";
-import type { Context, MiddlewareHandler } from "hono";
-import type { CapletsEngineOptions } from "../engine";
-import { CapletsEngine } from "../engine";
-import type { HttpBasicAuthOptions, HttpServeOptions } from "./options";
-import { CapletsMcpSession } from "./session";
-
-type HttpServeIo = {
-  writeErr?: (value: string) => void;
-};
-
-type HttpSession = {
-  server: CapletsMcpSession;
-  transport: StreamableHTTPTransport;
-};
-
-export function createHttpServeApp(
-  options: HttpServeOptions,
-  engine: CapletsEngine,
-  io: HttpServeIo = {},
-): Hono {
-  const app = new Hono();
-  const sessions = new Map<string, HttpSession>();
-
-  app.get("/", (c) =>
-    c.json({
-      name: "caplets",
-      transport: "http",
-      mcp: options.path,
-      health: "/healthz",
-      auth: { type: "basic", enabled: options.auth.enabled },
-    }),
-  );
-
-  app.get("/healthz", (c) =>
-    c.json({
-      status: "ok",
-      transport: "http",
-      mcpPath: options.path,
-    }),
-  );
-
-  app.all(options.path, basicAuth(options.auth), async (c) => {
-    const sessionId = c.req.header("mcp-session-id");
-    if (sessionId) {
-      const existing = sessions.get(sessionId);
-      if (!existing) {
-        return c.json(
-          {
-            jsonrpc: "2.0",
-            error: { code: -32001, message: "Session not found" },
-            id: null,
-          },
-          404,
-        );
-      }
-      return existing.transport.handleRequest(c);
-    }
-
-    if (c.req.method !== "POST") {
-      return c.json(
-        {
-          jsonrpc: "2.0",
-          error: { code: -32000, message: "Bad Request: Mcp-Session-Id header is required" },
-          id: null,
-        },
-        400,
-      );
-    }
-
-    const nextSessionId = randomUUID();
-    const session = await createHttpSession(
-      engine,
-      nextSessionId,
-      options,
-      async (closedSessionId) => {
-        const closed = sessions.get(closedSessionId);
-        sessions.delete(closedSessionId);
-        if (closed) {
-          await closed.server.close();
-        }
-      },
-    );
-    sessions.set(nextSessionId, session);
-    return session.transport.handleRequest(c);
-  });
-
-  app.notFound((c) => c.json({ error: "not_found" }, 404));
-
-  Object.defineProperty(app, "__capletsClose", {
-    value: async () => {
-      await Promise.allSettled(
-        [...sessions.values()].map(async (session) => {
-          await session.server.close();
-        }),
-      );
-      sessions.clear();
-    },
-  });
-
-  if (options.warnUnauthenticatedNetwork) {
-    (io.writeErr ?? process.stderr.write.bind(process.stderr))(
-      `Warning: Caplets MCP HTTP server is listening on ${options.host} without authentication.\n`,
-    );
-  }
-
-  return app;
-}
-
-export async function serveHttp(
-  options: HttpServeOptions,
-  engineOptions: CapletsEngineOptions = {},
-  writeErr: (value: string) => void = (value) => process.stderr.write(value),
-): Promise<void> {
-  const engine = new CapletsEngine(engineOptions);
-  const app = createHttpServeApp(options, engine, { writeErr });
-  const server = serve({ fetch: app.fetch, hostname: options.host, port: options.port }, () => {
-    writeErr(
-      `Caplets MCP HTTP server listening on http://${formatHost(options.host)}:${options.port}${options.path}\n`,
-    );
-    writeErr(`Health check: http://${formatHost(options.host)}:${options.port}/healthz\n`);
-    writeErr(
-      `Basic Auth: ${options.auth.enabled ? `enabled (user: ${options.auth.user})` : "disabled"}\n`,
-    );
-  });
-
-  installHttpSignalHandlers(server, app, engine, writeErr);
-}
-
-async function createHttpSession(
-  engine: CapletsEngine,
-  sessionId: string,
-  options: HttpServeOptions,
-  onClose: (sessionId: string) => Promise<void>,
-): Promise<HttpSession> {
-  const transport = new StreamableHTTPTransport({
-    sessionIdGenerator: () => sessionId,
-    onsessionclosed: onClose,
-    ...(options.loopback ? dnsRebindingOptions(options) : {}),
-  });
-  const server = new CapletsMcpSession(engine);
-  await server.connect(transport);
-  return { server, transport };
-}
-
-function basicAuth(auth: HttpBasicAuthOptions): MiddlewareHandler {
-  return async (c, next) => {
-    if (!auth.enabled) {
-      await next();
-      return;
-    }
-    const header = c.req.header("authorization") ?? "";
-    const credentials = parseBasicAuth(header);
-    if (
-      !credentials ||
-      !safeEqual(credentials.user, auth.user) ||
-      !safeEqual(credentials.password, auth.password)
-    ) {
-      c.header("www-authenticate", 'Basic realm="caplets"');
-      return c.text("Unauthorized", 401);
-    }
-    await next();
-  };
-}
-
-function parseBasicAuth(header: string): { user: string; password: string } | undefined {
-  const [scheme, encoded] = header.split(" ");
-  if (scheme?.toLocaleLowerCase() !== "basic" || !encoded) {
-    return undefined;
-  }
-  const decoded = Buffer.from(encoded, "base64").toString("utf8");
-  const separator = decoded.indexOf(":");
-  if (separator < 0) {
-    return undefined;
-  }
-  return { user: decoded.slice(0, separator), password: decoded.slice(separator + 1) };
-}
-
-function safeEqual(left: string, right: string): boolean {
-  const leftBuffer = Buffer.from(left);
-  const rightBuffer = Buffer.from(right);
-  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
-}
-
-function dnsRebindingOptions(options: HttpServeOptions): {
-  enableDnsRebindingProtection: true;
-  allowedHosts: string[];
-  allowedOrigins: string[];
-} {
-  const hostForHeader = options.host === "::1" ? "[::1]" : options.host;
-  return {
-    enableDnsRebindingProtection: true,
-    allowedHosts: [
-      options.host,
-      hostForHeader,
-      `${hostForHeader}:${options.port}`,
-      `localhost:${options.port}`,
-    ],
-    allowedOrigins: [`http://${hostForHeader}:${options.port}`, `http://localhost:${options.port}`],
-  };
-}
-
-function installHttpSignalHandlers(
-  server: ServerType,
-  app: Hono,
-  engine: CapletsEngine,
-  writeErr: (value: string) => void,
-): void {
-  const close = async () => {
-    await new Promise<void>((resolve) => server.close(() => resolve()));
-    await (app as unknown as { __capletsClose?: () => Promise<void> }).__capletsClose?.();
-    await engine.close();
-  };
-  process.once(
-    "SIGINT",
-    () =>
-      void close()
-        .catch((error) => writeErr(`${String(error)}\n`))
-        .finally(() => process.exit(130)),
-  );
-  process.once(
-    "SIGTERM",
-    () =>
-      void close()
-        .catch((error) => writeErr(`${String(error)}\n`))
-        .finally(() => process.exit(143)),
-  );
-}
-
-function formatHost(host: string): string {
-  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
-}
-```
-
-- [ ] **Step 4: Fix import/type issues from actual Hono versions**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core typecheck
-```
-
-Expected first run may FAIL on exact exported type names from `@hono/node-server` or `@hono/mcp`. If it fails:
-
-- If `ServerType` is type-only-exported from `@hono/node-server/dist/types`, replace `import type { ServerType } from "@hono/node-server";` with `import type { ServerType } from "@hono/node-server/dist/types";` only if the package export permits it.
-- If `StreamableHTTPTransport` option type rejects `allowedOrigins`, keep only `enableDnsRebindingProtection` and `allowedHosts`.
-- If `Hono` generic typing rejects the synthetic `__capletsClose` property, replace the property attachment with a helper return type in this file:
-
-```ts
-type CapletsHttpApp = Hono & { closeCapletsSessions: () => Promise<void> };
-```
-
-Then return that from `createHttpServeApp` and call `app.closeCapletsSessions()` in `serveHttp`.
-
-- [ ] **Step 5: Run HTTP tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/serve-http.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit stdio/http serve helpers**
-
-Run:
-
-```bash
-git add packages/core/src/serve/index.ts packages/core/src/serve/stdio.ts packages/core/src/serve/http.ts packages/core/test/serve-http.test.ts
-git commit -m "feat(core): serve MCP over Hono HTTP"
-```
-
----
-
-### Task 6: Wire `serve` into the core CLI
-
-**Files:**
-
-- Modify: `packages/core/src/cli.ts`
-- Modify: `packages/core/src/index.ts`
-- Test: `packages/core/test/cli.test.ts`
-
-- [ ] **Step 1: Add failing CLI tests**
-
-Append tests near the existing CLI help/version tests in `packages/core/test/cli.test.ts`:
-
-```ts
-it("prints top-level help for no arguments", async () => {
-  const out: string[] = [];
-
-  await runCli([], {
-    writeOut: (value) => out.push(value),
-    writeErr: (value) => out.push(value),
-  });
-
-  expect(out.join("")).toContain("Usage: caplets");
-  expect(out.join("")).toContain("Commands:");
-  expect(out.join("")).toContain("serve");
-});
-
-it("resolves serve defaults to stdio", async () => {
-  const served: unknown[] = [];
-
-  await runCli(["serve"], {
-    writeOut: () => {},
-    serve: async (options) => {
-      served.push(options);
-    },
-  });
-
-  expect(served).toEqual([{ transport: "stdio" }]);
-});
-
-it("resolves HTTP serve defaults", async () => {
-  const served: unknown[] = [];
-
-  await runCli(["serve", "--transport", "http"], {
-    writeOut: () => {},
-    serve: async (options) => {
-      served.push(options);
-    },
-  });
-
-  expect(served).toEqual([
-    expect.objectContaining({
-      transport: "http",
-      host: "127.0.0.1",
-      port: 5387,
-      path: "/mcp",
-      auth: { enabled: false, user: "caplets" },
-    }),
-  ]);
-});
-
-it("rejects HTTP-only serve options with stdio", async () => {
-  await expect(
-    runCli(["serve", "--transport", "stdio", "--port", "5387"], { writeErr: () => {} }),
-  ).rejects.toThrow(expect.objectContaining({ code: "REQUEST_INVALID" }) as CapletsError);
-});
-```
-
-Also update the local `CliIO` TypeScript expectations by importing the real type only if needed. The test uses `serve` before the type exists, so it should fail initially.
-
-- [ ] **Step 2: Run CLI tests to verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/cli.test.ts --runInBand
-```
-
-Expected: FAIL because `CliIO` does not accept `serve`, no-arg behavior is not implemented, and the `serve` command does not exist in Commander.
-
-- [ ] **Step 3: Modify CLI imports and `CliIO`**
-
-In `packages/core/src/cli.ts`, add imports:
-
-```ts
-import { resolveServeOptions, type ServeOptions } from "./serve";
-import { serveResolvedCaplets } from "./serve";
-```
-
-Update `CliIO`:
-
-```ts
-type CliIO = {
-  writeOut?: (value: string) => void;
-  writeErr?: (value: string) => void;
-  authDir?: string;
-  version?: string;
-  setExitCode?: (code: number) => void;
-  serve?: (options: ServeOptions) => Promise<void>;
-};
-```
-
-- [ ] **Step 4: Add no-arg help behavior**
-
-In `runCli`, before `program.parseAsync`, add:
-
-```ts
-if (args.length === 0) {
-  program.outputHelp();
-  return;
-}
-```
-
-The resulting function body should start like:
-
-```ts
-export async function runCli(args: string[], io: CliIO = {}): Promise<void> {
-  const program = createProgram(io);
-  try {
-    if (args.length === 0) {
-      program.outputHelp();
-      return;
-    }
-    await program.parseAsync(["node", "caplets", ...args]);
-  } catch (error) {
-    // existing error handling stays unchanged
-  }
-}
-```
-
-- [ ] **Step 5: Add `serve` command to `createProgram`**
-
-After the main `program` setup and before `init`, add:
-
-```ts
-program
-  .command("serve")
-  .description("Serve configured Caplets as an MCP server.")
-  .option("--transport <transport>", "server transport: stdio or http")
-  .option("--host <host>", "HTTP bind host")
-  .option("--port <port>", "HTTP bind port")
-  .option("--path <path>", "HTTP MCP endpoint path")
-  .option("--user <user>", "HTTP Basic Auth username")
-  .option("--password <password>", "HTTP Basic Auth password")
-  .action(
-    async (options: {
-      transport?: string;
-      host?: string;
-      port?: string;
-      path?: string;
-      user?: string;
-      password?: string;
-    }) => {
-      const resolved = resolveServeOptions(options);
-      const runner =
-        io.serve ??
-        ((serveOptions: ServeOptions) =>
-          serveResolvedCaplets(
-            serveOptions,
-            {
-              ...(envConfigPath() ? { configPath: envConfigPath() } : {}),
-              ...(io.authDir ? { authDir: io.authDir } : {}),
-            },
-            writeErr,
-          ));
-      await runner(resolved);
-    },
-  );
-```
-
-- [ ] **Step 6: Export serve helpers from core index**
-
-In `packages/core/src/index.ts`, add:
-
-```ts
-export { serveCaplets, serveHttp, serveResolvedCaplets, serveStdio } from "./serve";
-export type { HttpServeOptions, RawServeOptions, ServeOptions, StdioServeOptions } from "./serve";
-```
-
-- [ ] **Step 7: Run focused CLI tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/cli.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 8: Commit CLI wiring**
-
-Run:
-
-```bash
-git add packages/core/src/cli.ts packages/core/src/index.ts packages/core/test/cli.test.ts
-git commit -m "feat(core): add serve command options"
-```
-
----
-
-### Task 7: Simplify CLI binary entrypoint
-
-**Files:**
-
-- Modify: `packages/cli/src/index.ts`
-- Test: covered by package build/typecheck
-
-- [ ] **Step 1: Replace special-case entrypoint**
-
-Replace `packages/cli/src/index.ts` with:
-
-```ts
-import { runCli } from "@caplets/core";
-import { version as packageVersion } from "../package.json";
-
-async function main() {
-  await runCli(process.argv.slice(2), { version: packageVersion });
-}
-
-main().catch((error) => {
-  console.error(error);
-  process.exit(1);
-});
-```
-
-- [ ] **Step 2: Run CLI package typecheck/build**
-
-Run:
-
-```bash
-pnpm --filter caplets typecheck
-pnpm --filter caplets build
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Commit entrypoint simplification**
-
-Run:
-
-```bash
-git add packages/cli/src/index.ts
-git commit -m "refactor(cli): delegate serve command to core"
-```
-
----
-
-### Task 8: Add MCP HTTP integration coverage
-
-**Files:**
-
-- Modify: `packages/core/test/serve-http.test.ts`
-
-- [ ] **Step 1: Add initialize/list-tools integration test**
-
-Append this test to `packages/core/test/serve-http.test.ts`:
-
-```ts
-it("initializes an MCP HTTP session and lists Caplet tools", async () => {
-  const { engine } = testEngine();
-  const app = createHttpServeApp(httpOptions(), engine, { writeErr: () => {} });
-
-  const init = await app.request("http://127.0.0.1:5387/mcp", {
-    method: "POST",
-    headers: {
-      accept: "application/json, text/event-stream",
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({
-      jsonrpc: "2.0",
-      id: 1,
-      method: "initialize",
-      params: {
-        protocolVersion: "2025-03-26",
-        capabilities: {},
-        clientInfo: { name: "test", version: "1.0.0" },
-      },
-    }),
-  });
-
-  expect(init.status).toBe(200);
-  const sessionId = init.headers.get("mcp-session-id");
-  expect(sessionId).toBeTruthy();
-
-  await app.request("http://127.0.0.1:5387/mcp", {
-    method: "POST",
-    headers: {
-      accept: "application/json, text/event-stream",
-      "content-type": "application/json",
-      "mcp-session-id": sessionId!,
-    },
-    body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
-  });
-
-  const tools = await app.request("http://127.0.0.1:5387/mcp", {
-    method: "POST",
-    headers: {
-      accept: "application/json, text/event-stream",
-      "content-type": "application/json",
-      "mcp-session-id": sessionId!,
-    },
-    body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }),
-  });
-
-  expect(tools.status).toBe(200);
-  const body = await tools.text();
-  expect(body).toContain("status");
-
-  const deleted = await app.request("http://127.0.0.1:5387/mcp", {
-    method: "DELETE",
-    headers: { "mcp-session-id": sessionId! },
-  });
-  expect(deleted.status).toBe(200);
-
-  await engine.close();
-});
-```
-
-If `@hono/mcp` returns SSE frames for `tools/list`, asserting `body` contains `status` is sufficient. If it returns pure JSON, the same assertion still passes.
-
-- [ ] **Step 2: Run HTTP tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/serve-http.test.ts
-```
-
-Expected: PASS. If the DELETE request requires `mcp-protocol-version`, add header:
-
-```ts
-"mcp-protocol-version": "2025-03-26"
-```
-
-and rerun.
-
-- [ ] **Step 3: Commit HTTP integration test**
-
-Run:
-
-```bash
-git add packages/core/test/serve-http.test.ts
-git commit -m "test(core): cover HTTP MCP sessions"
-```
-
----
-
-### Task 9: Run focused and full verification
-
-**Files:**
-
-- No source files unless verification reveals issues.
-
-- [ ] **Step 1: Run focused tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/serve-options.test.ts test/serve-session.test.ts test/serve-http.test.ts test/runtime.test.ts test/cli.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 2: Run typecheck**
-
-Run:
-
-```bash
-pnpm typecheck
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Run all tests**
-
-Run:
-
-```bash
-pnpm test
-```
-
-Expected: PASS.
-
-- [ ] **Step 4: Run full gate**
-
-Run:
-
-```bash
-pnpm verify
-```
-
-Expected: PASS through format, lint, typecheck, schema check, tests, benchmark check, and build.
-
-- [ ] **Step 5: Commit any verification fixes**
-
-If verification required fixes, commit them:
-
-```bash
-git add <fixed-files>
-git commit -m "fix(core): polish HTTP serve implementation"
-```
-
-If no fixes were needed, do not create an empty commit.
-
----
-
-## Self-review notes
-
-- Spec coverage: CLI behavior is covered by Tasks 3, 6, and 7. Hono HTTP behavior, Basic Auth, root/health endpoints, DNS rebinding options, session routing, startup logs, and shutdown are covered by Tasks 5 and 8. Runtime architecture is covered by Task 2. Verification is covered by Task 9.
-- Red-flag scan: no incomplete sections are intentionally left. The only conditional instructions are concrete version/type compatibility branches for real package typings.
-- Type consistency: `ServeOptions`, `HttpServeOptions`, `CapletsMcpSession`, and `ToolServer` are introduced before later tasks consume them.
diff --git a/docs/plans/2026-05-19-remote-native-integrations.md b/docs/plans/2026-05-19-remote-native-integrations.md
deleted file mode 100644
index 9804e9ed..00000000
--- a/docs/plans/2026-05-19-remote-native-integrations.md
+++ /dev/null
@@ -1,1438 +0,0 @@
-# Remote Native Integrations Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Let OpenCode, Pi, Codex, and Claude Code connect to a remote `caplets serve --transport http` service while preserving existing local defaults.
-
-**Architecture:** Add remote-aware native service option resolution in `@caplets/core/native`, then implement a `RemoteNativeCapletsService` backed by MCP SDK `Client` + `StreamableHTTPClientTransport`. OpenCode and Pi continue using `createNativeCapletsService()` but pass host-specific config into it; Codex/Claude remain MCP-backed and get documented remote HTTP config examples.
-
-**Tech Stack:** TypeScript, Vitest, MCP SDK Streamable HTTP client, existing Caplets native service interfaces, OpenCode plugin API, Pi extension API, pnpm.
-
----
-
-## File structure
-
-- Create `packages/core/src/native/options.ts` for env/config resolution, mode selection, remote URL validation, and Basic Auth header creation.
-- Create `packages/core/src/native/remote.ts` for remote MCP client wrapper and `RemoteNativeCapletsService`.
-- Modify `packages/core/src/native/service.ts` to delegate to local or remote implementation.
-- Modify `packages/core/src/native/tools.ts` only if remote tool guidance needs a helper; otherwise keep existing local helpers unchanged.
-- Modify `packages/core/src/native.ts` to export new option types needed by integrations.
-- Add `packages/core/test/native-options.test.ts`.
-- Add `packages/core/test/native-remote.test.ts`.
-- Modify `packages/core/test/process-cleanup.test.ts` only if `NativeCapletsService` type changes.
-- Modify `packages/opencode/src/index.ts` to accept second-argument config and pass it into `createNativeCapletsService()`.
-- Add `packages/opencode/src/config.ts` for OpenCode config normalization if the logic is more than one small helper.
-- Modify `packages/opencode/test/opencode.test.ts` to verify second-argument config propagation.
-- Modify `packages/opencode/README.md` with env and plugin-config remote examples.
-- Modify `packages/pi/src/index.ts` to accept args/native options while preserving the `{ service }` test seam.
-- Modify `packages/pi/test/pi.test.ts` to verify Pi args propagation.
-- Modify `packages/pi/README.md` with `~/.pi/agent/settings.json` package args examples and note to use the active Pi settings path if different.
-- Modify `README.md` and `plugins/caplets/skills/caplets/SKILL.md` with remote service guidance for Codex/Claude.
-- Modify `packages/core/test/agent-plugins.test.ts` if docs/plugin artifact assertions need remote examples.
-- Add a changeset for `@caplets/core`, `@caplets/opencode`, `@caplets/pi`, and `caplets`.
-
----
-
-### Task 1: Add native service option resolution
-
-**Files:**
-
-- Create: `packages/core/src/native/options.ts`
-- Modify: `packages/core/src/native.ts`
-- Test: `packages/core/test/native-options.test.ts`
-
-- [ ] **Step 1: Write failing option-resolution tests**
-
-Create `packages/core/test/native-options.test.ts`:
-
-```ts
-import { describe, expect, it } from "vitest";
-import { CapletsError } from "../src/errors";
-import { resolveNativeCapletsServiceOptions } from "../src/native/options";
-
-describe("resolveNativeCapletsServiceOptions", () => {
-  it("defaults to local mode without remote configuration", () => {
-    expect(resolveNativeCapletsServiceOptions({}, {})).toEqual({
-      mode: "local",
-    });
-  });
-
-  it("uses remote mode in auto when a remote URL is configured", () => {
-    expect(
-      resolveNativeCapletsServiceOptions({}, { CAPLETS_REMOTE_URL: "http://127.0.0.1:5387/mcp" }),
-    ).toMatchObject({
-      mode: "remote",
-      remote: {
-        url: new URL("http://127.0.0.1:5387/mcp"),
-        auth: { enabled: false, user: "caplets" },
-        pollIntervalMs: 30_000,
-      },
-    });
-  });
-
-  it("lets explicit local mode ignore remote env vars", () => {
-    expect(
-      resolveNativeCapletsServiceOptions(
-        { mode: "local" },
-        { CAPLETS_REMOTE_URL: "http://127.0.0.1:5387/mcp" },
-      ),
-    ).toEqual({ mode: "local" });
-  });
-
-  it("requires a URL in explicit remote mode", () => {
-    expect(() => resolveNativeCapletsServiceOptions({ mode: "remote" }, {})).toThrow(
-      expect.objectContaining({ code: "REQUEST_INVALID" }) as CapletsError,
-    );
-  });
-
-  it("rejects non-loopback http URLs", () => {
-    expect(() =>
-      resolveNativeCapletsServiceOptions({ remote: { url: "http://caplets.example.com/mcp" } }, {}),
-    ).toThrow(/https/u);
-  });
-
-  it("lets config override env vars", () => {
-    const configPassword = ["config", "password"].join("-");
-    expect(
-      resolveNativeCapletsServiceOptions(
-        {
-          remote: {
-            url: "https://configured.example.com/mcp",
-            user: "configured",
-            password: configPassword,
-          },
-        },
-        {
-          CAPLETS_REMOTE_URL: "https://env.example.com/mcp",
-          CAPLETS_REMOTE_USER: "env-user",
-          CAPLETS_REMOTE_PASSWORD: ["env", "password"].join("-"),
-        },
-      ),
-    ).toMatchObject({
-      mode: "remote",
-      remote: {
-        url: new URL("https://configured.example.com/mcp"),
-        auth: { enabled: true, user: "configured", password: configPassword },
-      },
-    });
-  });
-
-  it("defaults Basic Auth user when password exists", () => {
-    const password = ["remote", "password"].join("-");
-    expect(
-      resolveNativeCapletsServiceOptions(
-        { remote: { url: "https://caplets.example.com/mcp", password } },
-        {},
-      ),
-    ).toMatchObject({
-      remote: { auth: { enabled: true, user: "caplets", password } },
-    });
-  });
-
-  it("rejects user without password", () => {
-    expect(() =>
-      resolveNativeCapletsServiceOptions(
-        { remote: { url: "https://caplets.example.com/mcp", user: "caplets" } },
-        {},
-      ),
-    ).toThrow(/requires a password/u);
-  });
-
-  it("builds request headers without logging credentials", () => {
-    const password = ["remote", "password"].join("-");
-    const resolved = resolveNativeCapletsServiceOptions(
-      {
-        remote: {
-          url: "https://caplets.example.com/mcp",
-          user: "caplets",
-          password,
-        },
-      },
-      {},
-    );
-    expect(resolved.mode).toBe("remote");
-    expect(resolved.mode === "remote" ? resolved.remote.requestInit.headers : undefined).toEqual({
-      Authorization: `Basic ${Buffer.from(`caplets:${password}`).toString("base64")}`,
-    });
-  });
-});
-```
-
-- [ ] **Step 2: Run option tests to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/native-options.test.ts
-```
-
-Expected: FAIL with module-not-found for `../src/native/options`.
-
-- [ ] **Step 3: Implement native option resolution**
-
-Create `packages/core/src/native/options.ts`:
-
-```ts
-import { CapletsError } from "../errors";
-
-export type NativeCapletsMode = "auto" | "local" | "remote";
-
-export type NativeRemoteCapletsOptions = {
-  url?: string;
-  user?: string;
-  password?: string;
-  pollIntervalMs?: number;
-  fetch?: typeof fetch;
-};
-
-export type NativeCapletsServiceResolutionInput = {
-  mode?: NativeCapletsMode;
-  remote?: NativeRemoteCapletsOptions;
-};
-
-export type NativeCapletsEnv = Partial<
-  Record<
-    | "CAPLETS_NATIVE_MODE"
-    | "CAPLETS_REMOTE_URL"
-    | "CAPLETS_REMOTE_USER"
-    | "CAPLETS_REMOTE_PASSWORD",
-    string
-  >
->;
-
-export type NativeRemoteAuthOptions =
-  | { enabled: false; user: string }
-  | { enabled: true; user: string; password: string };
-
-export type ResolvedNativeCapletsServiceOptions =
-  | { mode: "local" }
-  | {
-      mode: "remote";
-      remote: {
-        url: URL;
-        auth: NativeRemoteAuthOptions;
-        pollIntervalMs: number;
-        requestInit: RequestInit;
-        fetch?: typeof fetch;
-      };
-    };
-
-const DEFAULT_REMOTE_USER = "caplets";
-const DEFAULT_POLL_INTERVAL_MS = 30_000;
-
-export function resolveNativeCapletsServiceOptions(
-  input: NativeCapletsServiceResolutionInput = {},
-  env: NativeCapletsEnv = process.env,
-): ResolvedNativeCapletsServiceOptions {
-  const mode = parseMode(input.mode ?? env.CAPLETS_NATIVE_MODE ?? "auto");
-  if (mode === "local") {
-    return { mode: "local" };
-  }
-
-  const rawUrl =
-    nonEmpty(input.remote?.url, "remote.url") ??
-    nonEmpty(env.CAPLETS_REMOTE_URL, "CAPLETS_REMOTE_URL");
-  if (mode === "remote" && rawUrl === undefined) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "CAPLETS_NATIVE_MODE=remote requires CAPLETS_REMOTE_URL or remote.url.",
-    );
-  }
-  if (rawUrl === undefined) {
-    return { mode: "local" };
-  }
-
-  const url = parseRemoteUrl(rawUrl);
-  const userWasExplicit = input.remote?.user !== undefined || hasEnv(env.CAPLETS_REMOTE_USER);
-  const user =
-    nonEmpty(input.remote?.user, "remote.user") ??
-    nonEmpty(env.CAPLETS_REMOTE_USER, "CAPLETS_REMOTE_USER") ??
-    DEFAULT_REMOTE_USER;
-  const password =
-    nonEmpty(input.remote?.password, "remote.password") ??
-    nonEmpty(env.CAPLETS_REMOTE_PASSWORD, "CAPLETS_REMOTE_PASSWORD");
-
-  if (userWasExplicit && password === undefined) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "Remote Caplets Basic Auth requires a password; set CAPLETS_REMOTE_PASSWORD or remote.password.",
-    );
-  }
-
-  const auth: NativeRemoteAuthOptions =
-    password === undefined ? { enabled: false, user } : { enabled: true, user, password };
-  const requestInit: RequestInit = auth.enabled
-    ? { headers: { Authorization: basicAuthHeader(auth.user, auth.password) } }
-    : {};
-
-  return {
-    mode: "remote",
-    remote: {
-      url,
-      auth,
-      pollIntervalMs: parsePollInterval(input.remote?.pollIntervalMs),
-      requestInit,
-      ...(input.remote?.fetch ? { fetch: input.remote.fetch } : {}),
-    },
-  };
-}
-
-function parseMode(value: string): NativeCapletsMode {
-  if (value === "auto" || value === "local" || value === "remote") {
-    return value;
-  }
-  throw new CapletsError(
-    "REQUEST_INVALID",
-    `Expected CAPLETS_NATIVE_MODE to be auto, local, or remote, got ${value}`,
-  );
-}
-
-function parseRemoteUrl(value: string): URL {
-  let url: URL;
-  try {
-    url = new URL(value);
-  } catch {
-    throw new CapletsError("REQUEST_INVALID", `Invalid remote Caplets URL: ${value}`);
-  }
-  if (url.protocol === "https:") {
-    return url;
-  }
-  if (url.protocol === "http:" && isLoopbackHost(url.hostname)) {
-    return url;
-  }
-  throw new CapletsError(
-    "REQUEST_INVALID",
-    "Remote Caplets URL must use https except loopback development URLs.",
-  );
-}
-
-function isLoopbackHost(host: string): boolean {
-  return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
-}
-
-function parsePollInterval(value: number | undefined): number {
-  if (value === undefined) {
-    return DEFAULT_POLL_INTERVAL_MS;
-  }
-  if (!Number.isInteger(value) || value < 1_000) {
-    throw new CapletsError("REQUEST_INVALID", "remote.pollIntervalMs must be an integer >= 1000.");
-  }
-  return value;
-}
-
-function basicAuthHeader(user: string, password: string): string {
-  return `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
-}
-
-function nonEmpty(value: string | undefined, label: string): string | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    throw new CapletsError("REQUEST_INVALID", `${label} must not be empty`);
-  }
-  return trimmed;
-}
-
-function hasEnv(value: string | undefined): boolean {
-  return value !== undefined && value.trim() !== "";
-}
-```
-
-- [ ] **Step 4: Export option types from native entrypoint**
-
-Modify `packages/core/src/native.ts` to add:
-
-```ts
-export {
-  resolveNativeCapletsServiceOptions,
-  type NativeCapletsMode,
-  type NativeRemoteCapletsOptions,
-  type ResolvedNativeCapletsServiceOptions,
-} from "./native/options";
-```
-
-- [ ] **Step 5: Run option tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/native-options.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit native option resolution**
-
-Run:
-
-```bash
-git add packages/core/src/native/options.ts packages/core/src/native.ts packages/core/test/native-options.test.ts
-git commit -m "feat(core): resolve remote native service options"
-```
-
----
-
-### Task 2: Add remote native service implementation
-
-**Files:**
-
-- Create: `packages/core/src/native/remote.ts`
-- Modify: `packages/core/src/native/service.ts`
-- Test: `packages/core/test/native-remote.test.ts`
-
-- [ ] **Step 1: Write failing remote-service tests**
-
-Create `packages/core/test/native-remote.test.ts`:
-
-```ts
-import { EventEmitter } from "node:events";
-import { describe, expect, it, vi } from "vitest";
-import { CapletsError } from "../src/errors";
-import { RemoteNativeCapletsService, type RemoteCapletsClient } from "../src/native/remote";
-import { createNativeCapletsService } from "../src/native/service";
-
-describe("RemoteNativeCapletsService", () => {
-  it("maps remote MCP tools to native Caplets tools", async () => {
-    const client = fakeRemoteClient({
-      tools: [
-        {
-          name: "git-hub",
-          title: "GitHub",
-          description: "GitHub progressive tools.",
-          inputSchema: { type: "object" },
-        },
-      ],
-    });
-    const service = new RemoteNativeCapletsService({
-      clientFactory: async () => client,
-      pollIntervalMs: 10_000,
-    });
-
-    await service.reload();
-
-    expect(service.listTools()).toEqual([
-      expect.objectContaining({
-        caplet: "git-hub",
-        toolName: "caplets_git_hub",
-        title: "GitHub",
-      }),
-    ]);
-    expect(service.listTools()[0]?.description).toContain("GitHub progressive tools.");
-    expect(service.listTools()[0]?.promptGuidance[0]).toContain("remote Caplets service");
-
-    await service.close();
-  });
-
-  it("calls remote tools by Caplet ID", async () => {
-    const client = fakeRemoteClient({
-      tools: [{ name: "linear", inputSchema: { type: "object" } }],
-    });
-    const service = new RemoteNativeCapletsService({
-      clientFactory: async () => client,
-      pollIntervalMs: 10_000,
-    });
-
-    const result = await service.execute("linear", { operation: "get_caplet" });
-
-    expect(client.callTool).toHaveBeenCalledWith("linear", {
-      operation: "get_caplet",
-    });
-    expect(result).toEqual({ content: [{ type: "text", text: "ok" }] });
-
-    await service.close();
-  });
-
-  it("notifies listeners on tool-list-change notifications", async () => {
-    const client = fakeRemoteClient({
-      tools: [{ name: "alpha", inputSchema: { type: "object" } }],
-    });
-    const service = new RemoteNativeCapletsService({
-      clientFactory: async () => client,
-      pollIntervalMs: 10_000,
-    });
-    const changes: string[][] = [];
-    service.onToolsChanged((tools) => changes.push(tools.map((tool) => tool.caplet)));
-
-    await service.reload();
-    client.setTools([{ name: "beta", title: "Beta", inputSchema: { type: "object" } }]);
-    await client.emitToolsChanged();
-
-    expect(changes).toEqual([["alpha"], ["beta"]]);
-    await service.close();
-  });
-
-  it("keeps last known-good tools when refresh fails", async () => {
-    const errors: string[] = [];
-    const client = fakeRemoteClient({
-      tools: [{ name: "alpha", inputSchema: { type: "object" } }],
-    });
-    const service = new RemoteNativeCapletsService({
-      clientFactory: async () => client,
-      pollIntervalMs: 10_000,
-      writeErr: (value) => errors.push(value),
-    });
-
-    await service.reload();
-    client.failListTools = true;
-    const reloaded = await service.reload();
-
-    expect(reloaded).toBe(false);
-    expect(service.listTools().map((tool) => tool.caplet)).toEqual(["alpha"]);
-    expect(errors.join("")).toContain("keeping last known-good remote tools");
-    await service.close();
-  });
-
-  it("closes the client and stops future notifications", async () => {
-    const client = fakeRemoteClient({
-      tools: [{ name: "alpha", inputSchema: { type: "object" } }],
-    });
-    const service = new RemoteNativeCapletsService({
-      clientFactory: async () => client,
-      pollIntervalMs: 10_000,
-    });
-    const listener = vi.fn();
-    service.onToolsChanged(listener);
-
-    await service.reload();
-    await service.close();
-    client.setTools([{ name: "beta", inputSchema: { type: "object" } }]);
-    await client.emitToolsChanged();
-
-    expect(client.close).toHaveBeenCalled();
-    expect(listener).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe("createNativeCapletsService remote mode", () => {
-  it("returns a remote service when remote mode resolves", async () => {
-    const service = createNativeCapletsService({
-      mode: "remote",
-      remote: { url: "http://127.0.0.1:5387/mcp" },
-      remoteClientFactory: async () => fakeRemoteClient({ tools: [] }),
-    });
-
-    await expect(service.reload()).resolves.toBe(true);
-    await service.close();
-  });
-
-  it("fails fast for invalid remote configuration", () => {
-    expect(() => createNativeCapletsService({ mode: "remote" })).toThrow(
-      expect.objectContaining({ code: "REQUEST_INVALID" }) as CapletsError,
-    );
-  });
-});
-
-type FakeRemoteTool = {
-  name: string;
-  title?: string;
-  description?: string;
-  inputSchema: { type: "object" };
-};
-
-function fakeRemoteClient(initial: { tools: FakeRemoteTool[] }): RemoteCapletsClient & {
-  failListTools: boolean;
-  setTools(tools: FakeRemoteTool[]): void;
-  emitToolsChanged(): Promise<void>;
-  callTool: ReturnType<typeof vi.fn>;
-  close: ReturnType<typeof vi.fn>;
-} {
-  const events = new EventEmitter();
-  let tools = initial.tools;
-  return {
-    failListTools: false,
-    setTools(next) {
-      tools = next;
-    },
-    async emitToolsChanged() {
-      events.emit("toolsChanged");
-      await Promise.resolve();
-    },
-    async listTools() {
-      if (this.failListTools) {
-        throw new Error("list failed");
-      }
-      return tools;
-    },
-    callTool: vi.fn(async () => ({ content: [{ type: "text", text: "ok" }] })),
-    onToolsChanged(listener) {
-      events.on("toolsChanged", listener);
-      return () => events.off("toolsChanged", listener);
-    },
-    close: vi.fn(async () => {}),
-  };
-}
-```
-
-- [ ] **Step 2: Run remote tests to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/native-remote.test.ts
-```
-
-Expected: FAIL because `../src/native/remote` does not exist and `remoteClientFactory` is not accepted.
-
-- [ ] **Step 3: Implement remote service**
-
-Create `packages/core/src/native/remote.ts`:
-
-```ts
-import { Client } from "@modelcontextprotocol/sdk/client/index";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp";
-import { version as packageJsonVersion } from "../../package.json";
-import { CapletsError } from "../errors";
-import type {
-  NativeCapletTool,
-  NativeCapletsService,
-  NativeCapletsToolsChangedListener,
-} from "./service";
-import { nativeCapletToolName } from "./tools";
-
-type RemoteTool = {
-  name: string;
-  title?: string;
-  description?: string;
-  inputSchema: { type: "object" };
-};
-
-export type RemoteCapletsClient = {
-  listTools(): Promise<RemoteTool[]>;
-  callTool(name: string, arguments_: unknown): Promise<unknown>;
-  onToolsChanged(listener: () => void | Promise<void>): () => void;
-  close(): Promise<void>;
-};
-
-export type RemoteCapletsClientFactory = () => Promise<RemoteCapletsClient>;
-
-export type RemoteNativeCapletsServiceOptions = {
-  clientFactory: RemoteCapletsClientFactory;
-  pollIntervalMs: number;
-  writeErr?: (value: string) => void;
-};
-
-export class RemoteNativeCapletsService implements NativeCapletsService {
-  private client: RemoteCapletsClient | undefined;
-  private tools: NativeCapletTool[] = [];
-  private readonly listeners = new Set<NativeCapletsToolsChangedListener>();
-  private unsubscribeToolsChanged: (() => void) | undefined;
-  private poll: NodeJS.Timeout | undefined;
-  private closed = false;
-
-  constructor(private readonly options: RemoteNativeCapletsServiceOptions) {}
-
-  listTools(): NativeCapletTool[] {
-    return this.tools;
-  }
-
-  async execute(capletId: string, request: unknown): Promise<unknown> {
-    const client = await this.ensureClient();
-    try {
-      return await client.callTool(capletId, request);
-    } catch (error) {
-      throw classifyRemoteError(error, `Remote Caplets tool ${capletId} failed`);
-    }
-  }
-
-  async reload(): Promise<boolean> {
-    try {
-      const client = await this.ensureClient();
-      const next = mapRemoteTools(await client.listTools());
-      const changed = toolSignature(next) !== toolSignature(this.tools);
-      this.tools = next;
-      if (changed) {
-        this.emitToolsChanged();
-      }
-      return true;
-    } catch (error) {
-      this.writeErr(
-        `Remote Caplets refresh failed; keeping last known-good remote tools: ${safeMessage(error)}\n`,
-      );
-      return false;
-    }
-  }
-
-  onToolsChanged(listener: NativeCapletsToolsChangedListener): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
-  }
-
-  async close(): Promise<void> {
-    if (this.closed) {
-      return;
-    }
-    this.closed = true;
-    if (this.poll) {
-      clearInterval(this.poll);
-      this.poll = undefined;
-    }
-    this.unsubscribeToolsChanged?.();
-    this.unsubscribeToolsChanged = undefined;
-    await this.client?.close();
-    this.client = undefined;
-    this.listeners.clear();
-  }
-
-  private async ensureClient(): Promise<RemoteCapletsClient> {
-    if (this.closed) {
-      throw new CapletsError("SERVER_UNAVAILABLE", "Remote Caplets service is closed.");
-    }
-    if (this.client) {
-      return this.client;
-    }
-    const client = await this.options.clientFactory();
-    this.client = client;
-    this.unsubscribeToolsChanged = client.onToolsChanged(() => void this.reload());
-    this.startPolling();
-    return client;
-  }
-
-  private startPolling(): void {
-    if (this.poll) {
-      return;
-    }
-    this.poll = setInterval(() => void this.reload(), this.options.pollIntervalMs);
-    this.poll.unref?.();
-  }
-
-  private emitToolsChanged(): void {
-    const snapshot = this.listTools();
-    for (const listener of this.listeners) {
-      listener(snapshot);
-    }
-  }
-
-  private writeErr(value: string): void {
-    (this.options.writeErr ?? process.stderr.write.bind(process.stderr))(value);
-  }
-}
-
-export function createSdkRemoteCapletsClient(options: {
-  url: URL;
-  requestInit: RequestInit;
-  fetch?: typeof fetch;
-}): RemoteCapletsClientFactory {
-  return async () => {
-    const transport = new StreamableHTTPClientTransport(options.url, {
-      requestInit: options.requestInit,
-      ...(options.fetch ? { fetch: options.fetch } : {}),
-    });
-    const client = new Client(
-      { name: "caplets-native", version: packageJsonVersion },
-      {
-        capabilities: {},
-      },
-    );
-    await client.connect(transport);
-    return {
-      async listTools() {
-        const result = await client.listTools();
-        return result.tools;
-      },
-      async callTool(name, arguments_) {
-        return await client.callTool({
-          name,
-          arguments: arguments_ as Record<string, unknown>,
-        });
-      },
-      onToolsChanged(listener) {
-        client.setNotificationHandler(
-          { method: "notifications/tools/list_changed" } as never,
-          () => {
-            void listener();
-          },
-        );
-        return () =>
-          client.removeNotificationHandler({
-            method: "notifications/tools/list_changed",
-          } as never);
-      },
-      async close() {
-        await transport.terminateSession().catch(() => undefined);
-        await client.close();
-      },
-    };
-  };
-}
-
-function mapRemoteTools(tools: RemoteTool[]): NativeCapletTool[] {
-  return tools
-    .map((tool) => {
-      const toolName = nativeCapletToolName(tool.name);
-      const title = tool.title ?? tool.name;
-      return {
-        caplet: tool.name,
-        toolName,
-        title,
-        description: [
-          tool.description ?? `Remote Caplets capability domain ${title}.`,
-          "",
-          `Native tool name: ${toolName}`,
-          `Remote Caplet ID: ${tool.name}`,
-        ].join("\n"),
-        promptGuidance: [
-          `Use ${toolName} for the ${title} remote Caplets service capability domain.`,
-        ],
-      };
-    })
-    .sort((left, right) => left.caplet.localeCompare(right.caplet));
-}
-
-function toolSignature(tools: NativeCapletTool[]): string {
-  return JSON.stringify(tools);
-}
-
-function safeMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function classifyRemoteError(error: unknown, fallbackMessage: string): Error {
-  const message = safeMessage(error);
-  if (/401|403|unauthorized|forbidden/i.test(message)) {
-    return new CapletsError(
-      "AUTH_FAILED",
-      "Remote Caplets authentication failed. Check CAPLETS_REMOTE_USER and CAPLETS_REMOTE_PASSWORD.",
-    );
-  }
-  return error instanceof Error ? error : new CapletsError("SERVER_UNAVAILABLE", fallbackMessage);
-}
-```
-
-If TypeScript rejects `setNotificationHandler` object literals, use the SDK's exported notification schema type for tool-list changes or fall back to client options `listChanged.tools.onChanged` during `new Client(...)`. Keep the public `RemoteCapletsClient` interface unchanged so tests stay stable.
-
-- [ ] **Step 4: Wire service factory**
-
-Modify `packages/core/src/native/service.ts`:
-
-- Add imports:
-
-```ts
-import {
-  resolveNativeCapletsServiceOptions,
-  type NativeCapletsServiceResolutionInput,
-} from "./options";
-import {
-  createSdkRemoteCapletsClient,
-  RemoteNativeCapletsService,
-  type RemoteCapletsClientFactory,
-} from "./remote";
-```
-
-- Extend `NativeCapletsServiceOptions`:
-
-```ts
-export type NativeCapletsServiceOptions = NativeCapletsServiceResolutionInput & {
-  configPath?: string;
-  projectConfigPath?: string;
-  authDir?: string;
-  watchDebounceMs?: number;
-  watch?: boolean;
-  writeErr?: (value: string) => void;
-  remoteClientFactory?: RemoteCapletsClientFactory;
-};
-```
-
-- Replace `createNativeCapletsService` with:
-
-```ts
-export function createNativeCapletsService(
-  options: NativeCapletsServiceOptions = {},
-): NativeCapletsService {
-  const resolved = resolveNativeCapletsServiceOptions(options);
-  if (resolved.mode === "remote") {
-    return new RemoteNativeCapletsService({
-      clientFactory:
-        options.remoteClientFactory ??
-        createSdkRemoteCapletsClient({
-          url: resolved.remote.url,
-          requestInit: resolved.remote.requestInit,
-          ...(resolved.remote.fetch ? { fetch: resolved.remote.fetch } : {}),
-        }),
-      pollIntervalMs: resolved.remote.pollIntervalMs,
-      ...(options.writeErr ? { writeErr: options.writeErr } : {}),
-    });
-  }
-  return new DefaultNativeCapletsService(localEngineOptions(options));
-}
-```
-
-- Add helper:
-
-```ts
-function localEngineOptions(
-  options: NativeCapletsServiceOptions,
-): ConstructorParameters<typeof CapletsEngine>[0] {
-  const engineOptions: ConstructorParameters<typeof CapletsEngine>[0] = {};
-  if (options.configPath !== undefined) engineOptions.configPath = options.configPath;
-  if (options.projectConfigPath !== undefined)
-    engineOptions.projectConfigPath = options.projectConfigPath;
-  if (options.authDir !== undefined) engineOptions.authDir = options.authDir;
-  if (options.watchDebounceMs !== undefined)
-    engineOptions.watchDebounceMs = options.watchDebounceMs;
-  if (options.watch !== undefined) engineOptions.watch = options.watch;
-  if (options.writeErr !== undefined) engineOptions.writeErr = options.writeErr;
-  return engineOptions;
-}
-```
-
-- [ ] **Step 5: Export remote types from native entrypoint**
-
-Modify `packages/core/src/native.ts` to add:
-
-```ts
-export {
-  RemoteNativeCapletsService,
-  createSdkRemoteCapletsClient,
-  type RemoteCapletsClient,
-  type RemoteCapletsClientFactory,
-} from "./native/remote";
-```
-
-- [ ] **Step 6: Run remote tests and typecheck**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/native-remote.test.ts test/native-options.test.ts test/process-cleanup.test.ts
-pnpm --filter @caplets/core typecheck
-```
-
-Expected: PASS. If SDK notification typing requires a different handler shape, fix `createSdkRemoteCapletsClient` without changing tests.
-
-- [ ] **Step 7: Commit remote native service**
-
-Run:
-
-```bash
-git add packages/core/src/native/remote.ts packages/core/src/native/service.ts packages/core/src/native.ts packages/core/test/native-remote.test.ts
-git commit -m "feat(core): add remote native Caplets service"
-```
-
----
-
-### Task 3: Add OpenCode second-argument config
-
-**Files:**
-
-- Modify: `packages/opencode/src/index.ts`
-- Test: `packages/opencode/test/opencode.test.ts`
-- Docs: `packages/opencode/README.md`
-
-- [ ] **Step 1: Write failing OpenCode config propagation test**
-
-Append this test to `packages/opencode/test/opencode.test.ts`:
-
-```ts
-it("passes second-argument config into the native service", async () => {
-  vi.resetModules();
-  const nativeMocks = vi.hoisted(() => ({
-    createNativeCapletsService: vi.fn(() => ({
-      listTools: () => [],
-      execute: vi.fn(async () => ({})),
-      reload: vi.fn(async () => true),
-      onToolsChanged: vi.fn(() => () => {}),
-      close: vi.fn(async () => {}),
-    })),
-    registerNativeCapletsProcessCleanup: vi.fn(),
-  }));
-  vi.doMock("@caplets/core/native", () => nativeMocks);
-  const plugin = (await import("../src/index")).default;
-
-  await plugin(
-    {} as never,
-    {
-      mode: "remote",
-      remote: {
-        url: "https://caplets.example.com/mcp",
-        user: "caplets",
-        pollIntervalMs: 5_000,
-      },
-    } as never,
-  );
-
-  expect(nativeMocks.createNativeCapletsService).toHaveBeenCalledWith({
-    mode: "remote",
-    remote: {
-      url: "https://caplets.example.com/mcp",
-      user: "caplets",
-      pollIntervalMs: 5_000,
-    },
-  });
-});
-```
-
-If this conflicts with the existing top-level `vi.mock("@caplets/core/native")`, instead add a new isolated test file `packages/opencode/test/opencode-config.test.ts` that mocks before importing `../src/index.js`.
-
-- [ ] **Step 2: Run OpenCode test to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: FAIL because plugin ignores the second argument.
-
-- [ ] **Step 3: Update OpenCode plugin signature**
-
-Modify `packages/opencode/src/index.ts`:
-
-```ts
-import { type Plugin, type PluginInput } from "@opencode-ai/plugin";
-import {
-  createNativeCapletsService,
-  registerNativeCapletsProcessCleanup,
-  type NativeCapletsServiceOptions,
-} from "@caplets/core/native";
-import { createCapletsOpenCodeHooks } from "./hooks";
-
-export type CapletsOpenCodeConfig = Pick<NativeCapletsServiceOptions, "mode" | "remote">;
-
-const plugin: Plugin = async (_ctx: PluginInput, config?: CapletsOpenCodeConfig) => {
-  const service = createNativeCapletsService(normalizeOpenCodeConfig(config));
-  registerNativeCapletsProcessCleanup(service);
-  return createCapletsOpenCodeHooks(service);
-};
-
-function normalizeOpenCodeConfig(config: CapletsOpenCodeConfig | undefined): CapletsOpenCodeConfig {
-  if (!config) {
-    return {};
-  }
-  return {
-    ...(config.mode ? { mode: config.mode } : {}),
-    ...(config.remote ? { remote: config.remote } : {}),
-  };
-}
-
-export default plugin;
-```
-
-If `Plugin` type does not allow the second argument, define the implementation separately and cast at export:
-
-```ts
-const plugin = (async (_ctx: PluginInput, config?: CapletsOpenCodeConfig) => { ... }) as Plugin;
-```
-
-- [ ] **Step 4: Document OpenCode remote config**
-
-Append to `packages/opencode/README.md`:
-
-````md
-## Remote Caplets service
-
-By default the plugin reads local Caplets config. To use a remote `caplets serve --transport http` service, set environment variables:
-
-```sh
-CAPLETS_REMOTE_URL=http://127.0.0.1:5387/mcp opencode
-```
-````
-
-For authenticated remote services, keep the password in the environment:
-
-```sh
-CAPLETS_REMOTE_URL=https://caplets.example.com/mcp \
-CAPLETS_REMOTE_USER=caplets \
-CAPLETS_REMOTE_PASSWORD=... \
-opencode
-```
-
-OpenCode plugin config can also pass non-secret settings as the plugin factory's second argument:
-
-```ts
-export default {
-  plugin: [
-    [
-      "@caplets/opencode",
-      {
-        mode: "remote",
-        remote: {
-          url: "https://caplets.example.com/mcp",
-          user: "caplets",
-        },
-      },
-    ],
-  ],
-};
-```
-
-Plugin config overrides environment variables. Prefer `CAPLETS_REMOTE_PASSWORD` for the Basic Auth password unless your OpenCode setup provides secure secret storage.
-
-````md
-- [ ] **Step 5: Run OpenCode tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-pnpm --filter @caplets/opencode typecheck
-```
-````
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit OpenCode config support**
-
-Run:
-
-```bash
-git add packages/opencode/src/index.ts packages/opencode/test/opencode.test.ts packages/opencode/README.md
-git commit -m "feat(opencode): accept remote Caplets config"
-```
-
----
-
-### Task 4: Add Pi args/native option support
-
-**Files:**
-
-- Modify: `packages/pi/src/index.ts`
-- Test: `packages/pi/test/pi.test.ts`
-- Docs: `packages/pi/README.md`
-
-- [ ] **Step 1: Write failing Pi args propagation test**
-
-Add this test near the existing service-creation tests in `packages/pi/test/pi.test.ts`:
-
-```ts
-it("passes Pi args into the native service", () => {
-  const service = mockService([]);
-  nativeMocks.createNativeCapletsService.mockReturnValueOnce(service);
-  const pi = mockPiApi();
-
-  capletsPiExtension(pi, {
-    args: {
-      mode: "remote",
-      remote: {
-        url: "https://caplets.example.com/mcp",
-        user: "caplets",
-        pollIntervalMs: 5_000,
-      },
-    },
-  });
-
-  expect(nativeMocks.createNativeCapletsService).toHaveBeenCalledWith({
-    mode: "remote",
-    remote: {
-      url: "https://caplets.example.com/mcp",
-      user: "caplets",
-      pollIntervalMs: 5_000,
-    },
-  });
-});
-```
-
-If the existing `CapletsPiOptions` type rejects `args`, the test should fail at typecheck until implementation.
-
-- [ ] **Step 2: Run Pi test to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-```
-
-Expected: FAIL because `args` is not part of `CapletsPiOptions` and service creation ignores it.
-
-- [ ] **Step 3: Update Pi option types and service creation**
-
-Modify `packages/pi/src/index.ts` imports:
-
-```ts
-import {
-  createNativeCapletsService,
-  registerNativeCapletsProcessCleanup,
-  type NativeCapletTool,
-  type NativeCapletsService,
-  type NativeCapletsServiceOptions,
-} from "@caplets/core/native";
-```
-
-Replace `CapletsPiOptions` with:
-
-```ts
-export type CapletsPiOptions = {
-  service?: NativeCapletsService;
-  native?: Pick<NativeCapletsServiceOptions, "mode" | "remote">;
-  args?: Pick<NativeCapletsServiceOptions, "mode" | "remote">;
-};
-```
-
-Replace service creation with:
-
-```ts
-const ownsService = !options.service;
-const serviceOptions = options.native ?? options.args ?? {};
-const service = options.service ?? createNativeCapletsService(serviceOptions);
-```
-
-Do not change behavior when `service` is injected; tests and advanced users rely on that seam.
-
-- [ ] **Step 4: Document Pi settings args**
-
-Append to `packages/pi/README.md`:
-
-````md
-## Remote Caplets service
-
-By default the extension reads local Caplets config. To use a remote `caplets serve --transport http` service, set environment variables:
-
-```sh
-CAPLETS_REMOTE_URL=http://127.0.0.1:5387/mcp pi
-```
-````
-
-For authenticated remote services, keep the password in the environment:
-
-```sh
-CAPLETS_REMOTE_URL=https://caplets.example.com/mcp \
-CAPLETS_REMOTE_USER=caplets \
-CAPLETS_REMOTE_PASSWORD=... \
-pi
-```
-
-You can also pass non-secret remote settings through Pi package args in your Pi user settings file. Current Pi docs use `~/.pi/agent/settings.json`; use your runtime's active settings path if it differs:
-
-```json
-{
-  "packages": [
-    {
-      "source": "npm:@caplets/pi",
-      "args": {
-        "mode": "remote",
-        "remote": {
-          "url": "https://caplets.example.com/mcp",
-          "user": "caplets"
-        }
-      }
-    }
-  ]
-}
-```
-
-Package args override environment variables. Prefer `CAPLETS_REMOTE_PASSWORD` for the Basic Auth password unless your Pi setup provides secure secret storage.
-
-````md
-- [ ] **Step 5: Run Pi tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-pnpm --filter @caplets/pi typecheck
-```
-````
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit Pi args support**
-
-Run:
-
-```bash
-git add packages/pi/src/index.ts packages/pi/test/pi.test.ts packages/pi/README.md
-git commit -m "feat(pi): accept remote Caplets args"
-```
-
----
-
-### Task 5: Document Codex and Claude remote MCP configuration
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `plugins/caplets/skills/caplets/SKILL.md`
-- Modify: `packages/core/test/agent-plugins.test.ts` if needed
-
-- [ ] **Step 1: Add failing docs assertion if appropriate**
-
-If `packages/core/test/agent-plugins.test.ts` already checks README/plugin guidance, add a test asserting the root README includes `CAPLETS_REMOTE_URL` and `caplets serve --transport http`. Use this pattern:
-
-```ts
-it("documents remote Caplets service configuration for MCP-backed plugins", () => {
-  const readme = readFileSync(path.join(repoRoot, "README.md"), "utf8");
-  expect(readme).toContain("CAPLETS_REMOTE_URL");
-  expect(readme).toContain("caplets serve --transport http");
-  expect(readme).toContain("https://caplets.example.com/mcp");
-});
-```
-
-If that test file is not a good fit, skip this test and rely on docs review plus `pnpm test`.
-
-- [ ] **Step 2: Update root README Agent Plugins section**
-
-In `README.md`, after the existing paragraph ending with “install the Caplets CLI globally first,” add:
-
-````md
-### Remote Caplets service
-
-OpenCode and Pi can use native `caplets_<id>` tools backed by a remote Caplets HTTP service. Codex, Claude Code, and any MCP client can connect to the same remote MCP endpoint directly.
-
-Start the remote service:
-
-```sh
-caplets serve --transport http --host 127.0.0.1 --port 5387 --path /mcp
-```
-````
-
-For authenticated network use, configure Basic Auth on the server and keep credentials out of plugin manifests:
-
-```sh
-CAPLETS_SERVER_PASSWORD=... caplets serve --transport http --host 0.0.0.0
-```
-
-Native integrations read remote client settings from environment variables:
-
-```sh
-CAPLETS_REMOTE_URL=https://caplets.example.com/mcp \
-CAPLETS_REMOTE_USER=caplets \
-CAPLETS_REMOTE_PASSWORD=... \
-opencode
-```
-
-For MCP-backed Codex or Claude Code configs, point the agent's MCP server entry at the remote URL using that agent's supported HTTP MCP configuration. If Basic Auth is needed, use the agent's secure secret or environment interpolation mechanism rather than hardcoding credentials.
-
-````md
-- [ ] **Step 3: Update Caplets skill guidance**
-
-In `plugins/caplets/skills/caplets/SKILL.md`, add one bullet under “Guidance”:
-
-```md
-- When Caplets is configured as a remote MCP HTTP service, treat connection/auth failures as remote-service issues and ask the user to verify `CAPLETS_REMOTE_URL`, Basic Auth credentials, and that `caplets serve --transport http` is running.
-```
-````
-
-- [ ] **Step 4: Run docs/plugin tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/agent-plugins.test.ts
-pnpm format:check
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit remote MCP documentation**
-
-Run:
-
-```bash
-git add README.md plugins/caplets/skills/caplets/SKILL.md packages/core/test/agent-plugins.test.ts
-git commit -m "docs: document remote Caplets service connections"
-```
-
-If `agent-plugins.test.ts` was not modified, omit it from `git add`.
-
----
-
-### Task 6: Add changeset
-
-**Files:**
-
-- Create: `.changeset/<generated-name>.md`
-
-- [ ] **Step 1: Create changeset file**
-
-Create a changeset such as `.changeset/remote-native-caplets.md`:
-
-```md
----
-"@caplets/core": minor
-"@caplets/opencode": minor
-"@caplets/pi": minor
-"caplets": patch
----
-
-Add remote Caplets service support for native integrations, including remote-backed OpenCode and Pi native tools plus documentation for MCP-backed Codex and Claude Code remote connections.
-```
-
-- [ ] **Step 2: Check changeset status**
-
-Run:
-
-```bash
-pnpm changeset status --since=origin/main
-```
-
-Expected: output includes minor bumps for `@caplets/core`, `@caplets/opencode`, and `@caplets/pi`. `caplets` may appear as patch or as an internal dependent bump depending on Changesets dependency analysis.
-
-- [ ] **Step 3: Commit changeset**
-
-Run:
-
-```bash
-git add .changeset/remote-native-caplets.md
-git commit -m "chore: add changeset for remote native integrations"
-```
-
----
-
-### Task 7: Full verification
-
-**Files:**
-
-- No source files unless verification reveals issues.
-
-- [ ] **Step 1: Run focused tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/native-options.test.ts test/native-remote.test.ts test/process-cleanup.test.ts test/agent-plugins.test.ts
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 2: Run typecheck**
-
-Run:
-
-```bash
-pnpm typecheck
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Run all tests**
-
-Run:
-
-```bash
-pnpm test
-```
-
-Expected: PASS.
-
-- [ ] **Step 4: Run full gate**
-
-Run:
-
-```bash
-pnpm verify
-```
-
-Expected: PASS through format, lint, typecheck, schema check, tests, benchmark check, and build.
-
-- [ ] **Step 5: Commit verification fixes if any**
-
-If verification required source changes, review the working tree and stage only the files changed by those fixes:
-
-```bash
-git status --short
-git add packages/core/src/native/options.ts packages/core/src/native/remote.ts packages/core/src/native/service.ts packages/core/src/native.ts packages/opencode/src/index.ts packages/pi/src/index.ts README.md packages/opencode/README.md packages/pi/README.md plugins/caplets/skills/caplets/SKILL.md
-git commit -m "fix: polish remote native integration support"
-```
-
-If some listed files were not changed, `git add` will still succeed for tracked files. If verification fixes touched tests or a changeset, add those concrete changed paths too after checking `git status --short`. If no fixes were needed, do not create an empty commit.
-
----
-
-## Self-review notes
-
-- Spec coverage: Tasks 1 and 2 cover core remote option resolution, Basic Auth, URL validation, remote MCP client use, refresh notifications, polling fallback, last known-good behavior, and cleanup. Tasks 3 and 4 cover OpenCode second-argument config and Pi settings/package args. Task 5 covers Codex/Claude MCP-backed remote guidance. Task 6 covers release metadata. Task 7 covers verification.
-- Red-flag scan: no incomplete implementation steps are intentionally left. Conditional notes are limited to concrete SDK/host typing compatibility paths with stable public interfaces preserved.
-- Type consistency: `NativeCapletsServiceOptions`, `NativeRemoteCapletsOptions`, `RemoteCapletsClient`, `RemoteCapletsClientFactory`, and `RemoteNativeCapletsService` names are introduced before later tasks consume them.
diff --git a/docs/plans/2026-05-19-token-efficiency.md b/docs/plans/2026-05-19-token-efficiency.md
deleted file mode 100644
index e912bd33..00000000
--- a/docs/plans/2026-05-19-token-efficiency.md
+++ /dev/null
@@ -1,1541 +0,0 @@
-# Token-Efficient Caplets Interface Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development (recommended) or executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Reduce redundant token output across Caplets discovery, invocation, native Pi/OpenCode adapters, and benchmarks while preserving machine-readable results and compatibility with MCP-shaped tool responses.
-
-**Architecture:** Centralize result serialization decisions in small core helpers, then update each backend and adapter to avoid echoing the same payload in both human text and structured data. Keep detailed structured objects available in `structuredContent`/adapter `details`, but make visible `content` concise, purposeful, and bounded by default. Add tests that assert redundant JSON payloads are not emitted and benchmarks that measure runtime/discovery result surfaces, not only initial tool metadata.
-
-**Tech Stack:** TypeScript, MCP SDK `CallToolResult`, Zod, Vitest, pnpm, existing Caplets core/pi/opencode packages.
-
----
-
-## Scope And Constraints
-
-- Do not remove `structuredContent`; agents and adapters rely on it for reliable machine-readable data.
-- Keep MCP result shape valid by continuing to return a `content` array, but make it empty or minimal for structured-only operations where tests confirm the SDK accepts it.
-- Preserve full downstream text content for MCP-backed `call_tool` unless a new explicit compacting layer applies at the Pi/OpenCode adapter boundary.
-- Avoid changing external downstream tool behavior. Caplets should not silently mutate downstream MCP `content`, except where Caplets itself generated redundant JSON text for HTTP/OpenAPI/GraphQL/CLI/field-selection/error results.
-- Keep CLI default human summaries useful; JSON mode can remain complete because users explicitly request machine output from the CLI.
-- Use `pnpm` only.
-
-## File Structure
-
-- Modify `packages/core/src/tools.ts`
-  - Replace `jsonResult()` placeholder text with compact structured-only content.
-  - Replace field-selection text duplication with a compact summary.
-  - Keep metadata extraction and annotation behavior intact.
-- Create `packages/core/src/result-content.ts`
-  - Own shared helpers for compact MCP content blocks: structured-only notices, compact JSON summaries, and bounded text previews.
-- Modify `packages/core/src/errors.ts`
-  - Use compact error text while keeping `structuredContent.error` complete.
-- Modify `packages/core/src/http-actions.ts`
-  - Return compact generated text for HTTP action results instead of pretty-printing the full structured object.
-- Modify `packages/core/src/openapi.ts`
-  - Return compact generated text for OpenAPI action results instead of pretty-printing the full structured object.
-- Modify `packages/core/src/graphql.ts`
-  - Return compact generated text for GraphQL action results instead of pretty-printing the full structured object.
-- Modify `packages/core/src/cli-tools.ts`
-  - Return compact generated text for CLI action results instead of pretty-printing stdout/stderr structured object.
-- Modify `packages/core/src/capability-description.ts`
-  - Split long repeated workflow guidance from per-tool capability description.
-- Modify `packages/core/src/native/tools.ts`
-  - Move repeated workflow guidance into one global system guidance block and make per-tool prompt guidance one line.
-- Modify `packages/core/src/runtime.ts`
-  - Use concise per-tool MCP descriptions and rely on generated input schema for operation details.
-- Modify `packages/core/src/generated-tool-input-schema.ts`
-  - Shorten schema field descriptions while retaining critical constraints.
-- Modify `packages/core/src/downstream.ts`, `packages/core/src/http-actions.ts`, `packages/core/src/openapi.ts`, `packages/core/src/graphql.ts`, `packages/core/src/cli-tools.ts`, `packages/core/src/caplet-sets.ts`
-  - Make `compact()` truly compact by default and reserve verbose annotations/schema hashes for `get_tool` or a new optional discovery verbosity flag.
-- Modify `packages/core/src/registry.ts`
-  - Reduce `get_caplet` detail duplication and do not include full Markdown body by default.
-- Modify `packages/pi/src/index.ts`
-  - Stop serializing the full result into visible tool `content`; store it in `details.result` and produce a short preview string.
-- Modify `packages/opencode/src/hooks.ts`
-  - Return short human text for structured Caplets results; stringify full result only when no structured summary is available.
-- Modify tests:
-  - `packages/core/test/tools.test.ts`
-  - `packages/core/test/http-actions.test.ts`
-  - `packages/core/test/openapi.test.ts`
-  - `packages/core/test/graphql.test.ts`
-  - `packages/core/test/cli-tools.test.ts`
-  - `packages/core/test/registry.test.ts`
-  - `packages/core/test/downstream.test.ts`
-  - `packages/pi/test/pi.test.ts`
-  - `packages/opencode/test/opencode.test.ts`
-- Modify benchmarks:
-  - `packages/benchmarks/lib/surface.ts`
-  - `packages/benchmarks/test/benchmark.test.ts`
-  - `docs/benchmarks/coding-agent.md` via `pnpm benchmark`
-
----
-
-### Task 1: Add Shared Compact Result Content Helpers
-
-**Files:**
-
-- Create: `packages/core/src/result-content.ts`
-- Test: `packages/core/test/tools.test.ts`
-
-- [ ] **Step 1: Create failing tests for compact structured-only results**
-
-Add these test cases to `packages/core/test/tools.test.ts` near the existing `jsonResult` tests:
-
-```ts
-it("returns structured-only discovery results without duplicating the payload as text", () => {
-  const result = jsonResult({
-    server: "browser",
-    tools: [{ tool: "browser_click" }],
-  });
-
-  expect(result.content).toEqual([]);
-  expect(result.structuredContent).toEqual({
-    result: { server: "browser", tools: [{ tool: "browser_click" }] },
-  });
-  expect(JSON.stringify(result.content)).not.toContain("browser_click");
-});
-
-it("returns metadata in structured discovery results without human placeholder text", async () => {
-  const registry = registryForBrowserAndStealth();
-  const result = await handleServerTool(
-    registry.require("browser"),
-    { operation: "list_tools" },
-    registry,
-    mockDownstream([{ name: "browser_click", inputSchema: { type: "object" } }]),
-  );
-
-  expect(result.content).toEqual([]);
-  expect(result.structuredContent?.caplets).toMatchObject({
-    caplet: "browser",
-    name: "Browser",
-    operation: "list_tools",
-  });
-  expect(result.structuredContent?.result).toMatchObject({
-    server: "browser",
-    tools: [{ tool: "browser_click" }],
-  });
-});
-```
-
-If helper names in the current test file differ, reuse the existing local registry/downstream setup already used by nearby tests instead of creating new fixtures.
-
-- [ ] **Step 2: Run the focused test and verify it fails**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: FAIL because `jsonResult()` currently returns a text content block containing `result available in structuredContent.result`.
-
-- [ ] **Step 3: Create `packages/core/src/result-content.ts`**
-
-Write this file:
-
-```ts
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types";
-
-export type TextContentBlock = { type: "text"; text: string };
-
-export function structuredOnlyContent(): [] {
-  return [];
-}
-
-export function textContent(text: string): TextContentBlock[] {
-  return text ? [{ type: "text", text }] : [];
-}
-
-export function compactJsonText(value: unknown, maxLength = 600): string {
-  return compactText(JSON.stringify(value), maxLength);
-}
-
-export function compactText(value: string, maxLength = 600): string {
-  const collapsed = value.replace(/\s+/gu, " ").trim();
-  return collapsed.length > maxLength
-    ? `${collapsed.slice(0, maxLength - 1).trimEnd()}…`
-    : collapsed;
-}
-
-export function resultKeys(value: unknown): string {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return "scalar result";
-  }
-  const keys = Object.keys(value).filter((key) => key !== "elapsedMs");
-  return keys.length > 0 ? `structured keys: ${keys.join(", ")}` : "empty structured result";
-}
-
-export function statusSummary(value: unknown): string {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return compactJsonText(value);
-  }
-  const record = value as Record<string, unknown>;
-  const status = typeof record.status === "number" ? `status ${record.status}` : undefined;
-  const statusText =
-    typeof record.statusText === "string" && record.statusText ? record.statusText : undefined;
-  const exitCode = typeof record.exitCode === "number" ? `exit ${record.exitCode}` : undefined;
-  const body = "body" in record ? "body" : undefined;
-  const json = "json" in record ? "json" : undefined;
-  const stdout = typeof record.stdout === "string" && record.stdout ? "stdout" : undefined;
-  const stderr = typeof record.stderr === "string" && record.stderr ? "stderr" : undefined;
-  return (
-    [status, statusText, exitCode, body, json, stdout, stderr]
-      .filter((part): part is string => Boolean(part))
-      .join("; ") || resultKeys(record)
-  );
-}
-
-export function compactStructuredContent(value: unknown): TextContentBlock[] {
-  return textContent(statusSummary(value));
-}
-
-export function compactCallToolResultContent(result: CallToolResult): TextContentBlock[] {
-  if (result.isError === true) {
-    return textContent("downstream tool returned an error");
-  }
-  return compactStructuredContent(result.structuredContent);
-}
-```
-
-- [ ] **Step 4: Update `jsonResult()` to use structured-only content**
-
-In `packages/core/src/tools.ts`, import the helper:
-
-```ts
-import { structuredOnlyContent } from "./result-content";
-```
-
-Replace `jsonResult()` with:
-
-```ts
-export function jsonResult(value: unknown, metadata?: CapletResultMetadata): CallToolResult {
-  return {
-    content: structuredOnlyContent(),
-    structuredContent: {
-      ...(metadata === undefined ? {} : { caplets: metadata }),
-      result: value as Record<string, unknown>,
-    },
-  };
-}
-```
-
-- [ ] **Step 5: Run focused tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: PASS for the new tests, with failures only where old tests still expect placeholder text.
-
-- [ ] **Step 6: Update old placeholder expectations**
-
-In `packages/core/test/tools.test.ts`, replace expectations like:
-
-```ts
-expect(result.content).toEqual([
-  { type: "text", text: "Result available in structuredContent.result." },
-]);
-```
-
-with:
-
-```ts
-expect(result.content).toEqual([]);
-```
-
-For Caplet-specific list tests, replace expectations like:
-
-```ts
-expect(browser.content).toEqual([
-  {
-    type: "text",
-    text: "Browser list_tools result available in structuredContent.result.",
-  },
-]);
-```
-
-with:
-
-```ts
-expect(browser.content).toEqual([]);
-```
-
-- [ ] **Step 7: Run focused tests again**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: PASS.
-
----
-
-### Task 2: Remove Generated JSON Text Duplication From Non-MCP Backends
-
-**Files:**
-
-- Modify: `packages/core/src/http-actions.ts`
-- Modify: `packages/core/src/openapi.ts`
-- Modify: `packages/core/src/graphql.ts`
-- Modify: `packages/core/src/cli-tools.ts`
-- Test: `packages/core/test/http-actions.test.ts`
-- Test: `packages/core/test/openapi.test.ts`
-- Test: `packages/core/test/graphql.test.ts`
-- Test: `packages/core/test/cli-tools.test.ts`
-
-- [ ] **Step 1: Add focused assertions that generated text is compact**
-
-In each backend test file, update one successful call assertion to check that `content[0].text` is not the full pretty JSON.
-
-For HTTP/OpenAPI/GraphQL tests, use this pattern:
-
-```ts
-expect(result.structuredContent).toMatchObject({
-  status: 200,
-  body: { ok: true },
-});
-expect(result.content).toEqual([{ type: "text", text: "status 200; OK; body" }]);
-expect(result.content[0]?.text).not.toContain('"body"');
-```
-
-For CLI tests, use this pattern:
-
-```ts
-expect(result.structuredContent).toMatchObject({
-  exitCode: 0,
-  stdout: "hello\n",
-});
-expect(result.content).toEqual([{ type: "text", text: "exit 0; stdout" }]);
-expect(result.content[0]?.text).not.toContain('"stdout"');
-```
-
-Use the actual status text in existing test responses. If the test server returns an empty status text, expect `status 200; body` instead.
-
-- [ ] **Step 2: Run backend focused tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/http-actions.test.ts test/openapi.test.ts test/graphql.test.ts test/cli-tools.test.ts
-```
-
-Expected: FAIL because these backends currently set `content[0].text` to `JSON.stringify(structured, null, 2)`.
-
-- [ ] **Step 3: Update backend imports**
-
-Add this import to each modified backend file:
-
-```ts
-import { compactStructuredContent } from "./result-content";
-```
-
-- [ ] **Step 4: Replace duplicated JSON content in HTTP actions**
-
-In `packages/core/src/http-actions.ts`, replace:
-
-```ts
-return {
-  content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
-  structuredContent: parsed,
-  isError: !response.ok,
-};
-```
-
-with:
-
-```ts
-return {
-  content: compactStructuredContent(parsed),
-  structuredContent: parsed,
-  isError: !response.ok,
-};
-```
-
-- [ ] **Step 5: Replace duplicated JSON content in OpenAPI**
-
-In `packages/core/src/openapi.ts`, replace:
-
-```ts
-return {
-  content: [
-    {
-      type: "text",
-      text: JSON.stringify(parsed, null, 2),
-    },
-  ],
-  structuredContent: parsed as Record<string, unknown>,
-  isError: response.ok ? false : true,
-};
-```
-
-with:
-
-```ts
-return {
-  content: compactStructuredContent(parsed),
-  structuredContent: parsed as Record<string, unknown>,
-  isError: response.ok ? false : true,
-};
-```
-
-- [ ] **Step 6: Replace duplicated JSON content in GraphQL**
-
-In `packages/core/src/graphql.ts`, replace:
-
-```ts
-return {
-  content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-  structuredContent: result,
-  isError:
-    !response.ok ||
-    Boolean(body && typeof body === "object" && "errors" in body && (body as any).errors),
-};
-```
-
-with:
-
-```ts
-return {
-  content: compactStructuredContent(result),
-  structuredContent: result,
-  isError:
-    !response.ok ||
-    Boolean(body && typeof body === "object" && "errors" in body && (body as any).errors),
-};
-```
-
-- [ ] **Step 7: Replace duplicated JSON content in CLI tools**
-
-In `packages/core/src/cli-tools.ts`, replace:
-
-```ts
-return {
-  content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
-  structuredContent: structured,
-  isError: result.exitCode !== 0,
-};
-```
-
-with:
-
-```ts
-return {
-  content: compactStructuredContent(structured),
-  structuredContent: structured,
-  isError: result.exitCode !== 0,
-};
-```
-
-- [ ] **Step 8: Run backend focused tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/http-actions.test.ts test/openapi.test.ts test/graphql.test.ts test/cli-tools.test.ts
-```
-
-Expected: PASS after updating exact expected compact strings.
-
----
-
-### Task 3: Make Field Selection And Error Results Compact
-
-**Files:**
-
-- Modify: `packages/core/src/tools.ts`
-- Modify: `packages/core/src/errors.ts`
-- Test: `packages/core/test/tools.test.ts`
-- Test: `packages/core/test/redaction.test.ts`
-
-- [ ] **Step 1: Add failing tests for projected content**
-
-In `packages/core/test/tools.test.ts`, update field-selection tests that currently expect pretty JSON text. Replace assertions like:
-
-```ts
-expect(result.content).toEqual([{ type: "text", text: '{\n  "message": "ok"\n}' }]);
-```
-
-with:
-
-```ts
-expect(result.content).toEqual([{ type: "text", text: "structured keys: message" }]);
-expect(result.structuredContent).toEqual({ message: "ok" });
-```
-
-For nested body projection, use:
-
-```ts
-expect(result.content).toEqual([{ type: "text", text: "structured keys: body" }]);
-expect(result.structuredContent).toEqual({ body: { name: "Ada" } });
-```
-
-- [ ] **Step 2: Add failing test for compact error content**
-
-In `packages/core/test/tools.test.ts`, add:
-
-```ts
-it("returns compact error text while preserving structured error details", () => {
-  const result = errorResult(new CapletsError("REQUEST_INVALID", "Bad input", { field: "query" }));
-
-  expect(result.content).toEqual([{ type: "text", text: "REQUEST_INVALID: Bad input" }]);
-  expect(result.structuredContent).toEqual({
-    error: {
-      code: "REQUEST_INVALID",
-      message: "Bad input",
-      details: { field: "query" },
-    },
-  });
-});
-```
-
-Import `CapletsError` and `errorResult` if the file does not already import them.
-
-- [ ] **Step 3: Run focused tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts test/redaction.test.ts
-```
-
-Expected: FAIL because projected and error content currently contains full JSON text.
-
-- [ ] **Step 4: Update `projectCallToolResult()`**
-
-In `packages/core/src/tools.ts`, import:
-
-```ts
-import { compactStructuredContent, structuredOnlyContent } from "./result-content";
-```
-
-If `structuredOnlyContent` is already imported from Task 1, add only `compactStructuredContent`.
-
-Replace this block in `projectCallToolResult()`:
-
-```ts
-return {
-  ...result,
-  content: [
-    {
-      type: "text",
-      text: JSON.stringify(projected, null, 2),
-    },
-  ],
-  structuredContent: projected,
-} as T & CallToolResult;
-```
-
-with:
-
-```ts
-return {
-  ...result,
-  content: compactStructuredContent(projected),
-  structuredContent: projected,
-} as T & CallToolResult;
-```
-
-- [ ] **Step 5: Update `errorResult()`**
-
-In `packages/core/src/errors.ts`, replace:
-
-```ts
-export function errorResult(error: unknown, fallback?: CapletsErrorCode) {
-  return {
-    isError: true,
-    content: [
-      {
-        type: "text" as const,
-        text: JSON.stringify(toSafeError(error, fallback), null, 2),
-      },
-    ],
-    structuredContent: {
-      error: toSafeError(error, fallback),
-    },
-  };
-}
-```
-
-with:
-
-```ts
-export function errorResult(error: unknown, fallback?: CapletsErrorCode) {
-  const safe = toSafeError(error, fallback);
-  return {
-    isError: true,
-    content: [
-      {
-        type: "text" as const,
-        text: `${safe.code}: ${safe.message}`,
-      },
-    ],
-    structuredContent: {
-      error: safe,
-    },
-  };
-}
-```
-
-- [ ] **Step 6: Run focused tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts test/redaction.test.ts
-```
-
-Expected: PASS after updating old JSON-text expectations.
-
----
-
-### Task 4: Reduce Repeated Tool Description And Prompt Guidance
-
-**Files:**
-
-- Modify: `packages/core/src/capability-description.ts`
-- Modify: `packages/core/src/native/tools.ts`
-- Modify: `packages/core/src/runtime.ts`
-- Test: `packages/core/test/registry.test.ts`
-- Test: `packages/core/test/runtime.test.ts`
-- Test: `packages/pi/test/pi.test.ts`
-- Test: `packages/opencode/test/opencode.test.ts`
-
-- [ ] **Step 1: Add target tests for shorter descriptions**
-
-In `packages/core/test/registry.test.ts`, replace assertions that require full repeated workflow text with:
-
-```ts
-expect(description).toContain("Enabled Caplet");
-expect(description).toContain("Use get_caplet for details when needed.");
-expect(description).not.toContain("Recommended flow:");
-expect(description).not.toContain("After get_tool shows outputSchema");
-```
-
-In Pi/OpenCode tests that inspect descriptions, add:
-
-```ts
-expect(registered[0]?.description.length).toBeLessThan(350);
-expect(registered[0]?.description).not.toContain("Recommended flow:");
-```
-
-- [ ] **Step 2: Run focused tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/registry.test.ts test/runtime.test.ts
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: FAIL because descriptions currently include the repeated progressive-discovery workflow.
-
-- [ ] **Step 3: Replace `capabilityDescription()` with a concise per-tool description**
-
-In `packages/core/src/capability-description.ts`, replace the current function with:
-
-```ts
-import type { CapletConfig } from "./config";
-
-export function capabilityDescription(server: CapletConfig): string {
-  return [
-    `${server.name} Caplet.`,
-    server.description,
-    "Use get_caplet for details when needed; use search_tools or list_tools to discover downstream operations.",
-  ]
-    .filter(Boolean)
-    .join(" ");
-}
-```
-
-- [ ] **Step 4: Centralize the long workflow in global native guidance only**
-
-In `packages/core/src/native/tools.ts`, replace `nativeCapletPromptGuidance()` with:
-
-```ts
-export function nativeCapletPromptGuidance(toolName: string, caplet: CapletConfig): string[] {
-  return [`Use ${toolName} for the ${caplet.name} Caplet capability domain.`];
-}
-```
-
-Keep `nativeCapletsSystemGuidance()` as the single location for the detailed workflow, but shorten it by replacing the current numbered list with:
-
-```ts
-return [
-  "## Caplets Native Tools",
-  "",
-  "Caplets tools expose configured capability domains through progressive discovery.",
-  "",
-  "Available Caplets native tools:",
-  tools,
-  "",
-  "Flow: get_caplet when the domain is unfamiliar; search_tools or list_tools to find exact downstream names; get_tool only when schemas are unclear; call_tool with downstream inputs inside arguments.",
-  "Use fields on call_tool when a non-GraphQL downstream outputSchema allows selecting only needed structured paths.",
-].join("\n");
-```
-
-- [ ] **Step 5: Keep runtime descriptions concise**
-
-No separate implementation is needed in `packages/core/src/runtime.ts` if it imports `capabilityDescription()`. Verify registered tool descriptions become concise through existing calls at `registerCapletTool()` and `tool.update()`.
-
-- [ ] **Step 6: Update tests that expected old prose**
-
-Update any failing assertions that contain exact old workflow strings. Use concise expectations:
-
-```ts
-expect(description).toContain("Use get_caplet for details when needed");
-expect(description).not.toContain("Recommended flow:");
-```
-
-- [ ] **Step 7: Run focused tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/registry.test.ts test/runtime.test.ts
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: PASS.
-
----
-
-### Task 5: Shorten Generated Input Schema Descriptions
-
-**Files:**
-
-- Modify: `packages/core/src/generated-tool-input-schema.ts`
-- Test: `packages/core/test/tools.test.ts`
-- Test: `packages/pi/test/pi.test.ts`
-- Test: `packages/opencode/test/opencode.test.ts`
-
-- [ ] **Step 1: Add schema-size regression test**
-
-In `packages/core/test/tools.test.ts`, add:
-
-```ts
-it("keeps generated Caplets wrapper input schema descriptions compact", () => {
-  const schema = generatedToolInputJsonSchema();
-  const serialized = JSON.stringify(schema);
-  const descriptionBytes = Object.values(schema.properties).reduce(
-    (total, property) =>
-      total +
-      Buffer.byteLength(typeof property.description === "string" ? property.description : ""),
-    0,
-  );
-
-  expect(Buffer.byteLength(serialized)).toBeLessThan(1200);
-  expect(descriptionBytes).toBeLessThan(700);
-});
-```
-
-Import `generatedToolInputJsonSchema` if needed.
-
-- [ ] **Step 2: Run focused tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: FAIL because current schema descriptions are about 1.3 KB by themselves.
-
-- [ ] **Step 3: Replace verbose generated descriptions**
-
-In `packages/core/src/generated-tool-input-schema.ts`, replace `generatedToolInputDescriptions` with:
-
-```ts
-export const generatedToolInputDescriptions = {
-  operation:
-    "Wrapper operation: get_caplet, check_backend, list_tools, search_tools, get_tool, or call_tool.",
-  query: "Required for search_tools only.",
-  limit: "Optional search_tools result limit.",
-  tool: "Exact downstream tool name for get_tool or call_tool.",
-  arguments: "Required JSON object for call_tool downstream inputs.",
-  fields: "Optional call_tool structured output paths when outputSchema allows it.",
-} as const;
-```
-
-- [ ] **Step 4: Update tests with old exact description expectations**
-
-Replace expectations containing the old examples with compact expectations:
-
-```ts
-expect(schema.properties.operation.description).toContain("Wrapper operation");
-expect(schema.properties.arguments.description).toContain("downstream inputs");
-```
-
-- [ ] **Step 5: Run adapter tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: PASS.
-
----
-
-### Task 6: Make `list_tools` Compact By Default
-
-**Files:**
-
-- Modify: `packages/core/src/downstream.ts`
-- Modify: `packages/core/src/http-actions.ts`
-- Modify: `packages/core/src/openapi.ts`
-- Modify: `packages/core/src/graphql.ts`
-- Modify: `packages/core/src/cli-tools.ts`
-- Modify: `packages/core/src/caplet-sets.ts`
-- Test: `packages/core/test/downstream.test.ts`
-- Test: `packages/core/test/tools.test.ts`
-- Test: backend tests listed in Task 2
-
-- [ ] **Step 1: Add compact-list assertions**
-
-In `packages/core/test/downstream.test.ts`, update compact tool expectations to:
-
-```ts
-expect(first).toEqual({
-  server: "alpha",
-  tool: "example_tool",
-  description: "Example tool description.",
-  hasInputSchema: true,
-  hasOutputSchema: false,
-});
-expect(first).not.toHaveProperty("annotations");
-expect(first).not.toHaveProperty("inputSchemaHash");
-expect(first).not.toHaveProperty("outputSchemaHash");
-```
-
-In `packages/core/test/tools.test.ts`, update list-tools expected output similarly.
-
-- [ ] **Step 2: Run focused tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/downstream.test.ts test/tools.test.ts
-```
-
-Expected: FAIL because compact tools currently include annotations and schema hashes.
-
-- [ ] **Step 3: Update `CompactTool` type**
-
-In `packages/core/src/downstream.ts`, replace:
-
-```ts
-export type CompactTool = {
-  server: string;
-  tool: string;
-  description?: string;
-  annotations?: unknown;
-  hasInputSchema: boolean;
-  hasOutputSchema: boolean;
-  inputSchemaHash: string | null;
-  outputSchemaHash: string | null;
-};
-```
-
-with:
-
-```ts
-export type CompactTool = {
-  server: string;
-  tool: string;
-  description?: string;
-  hasInputSchema: boolean;
-  hasOutputSchema: boolean;
-};
-```
-
-- [ ] **Step 4: Replace all compact implementations**
-
-In each manager `compact()` method, replace the return object with this shape:
-
-```ts
-return {
-  server: server.server,
-  tool: tool.name,
-  ...(tool.description ? { description: tool.description } : {}),
-  hasInputSchema: Boolean(tool.inputSchema),
-  hasOutputSchema: Boolean(tool.outputSchema),
-};
-```
-
-Use the local config variable name in each file:
-
-- `server.server` in `DownstreamManager`
-- `endpoint.server` in `OpenApiManager` and `GraphQLManager`
-- `api.server` in `HttpActionManager`
-- `config.server` in `CliToolsManager` and `CapletSetManager`
-
-- [ ] **Step 5: Remove now-unused `schemaHash` imports**
-
-Remove `import { schemaHash } from "./schema-hash";` from files where it only supported compact list hashes.
-
-- [ ] **Step 6: Run focused tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/downstream.test.ts test/tools.test.ts test/http-actions.test.ts test/openapi.test.ts test/graphql.test.ts test/cli-tools.test.ts test/caplet-sets.test.ts
-```
-
-Expected: PASS after updating expected compact tool objects.
-
----
-
-### Task 7: Reduce `get_caplet` Detail Duplication
-
-**Files:**
-
-- Modify: `packages/core/src/registry.ts`
-- Test: `packages/core/test/registry.test.ts`
-- Test: `packages/core/test/tools.test.ts`
-
-- [ ] **Step 1: Add concise `get_caplet` tests**
-
-In `packages/core/test/registry.test.ts`, add or update assertions:
-
-```ts
-const detail = registry.detail(config.mcpServers.enabled!);
-expect(detail).toMatchObject({
-  caplet: "enabled",
-  name: "Enabled",
-  description: "Enabled Caplet description.",
-  backend: {
-    type: "mcp",
-    transport: "stdio",
-    disabled: false,
-  },
-});
-expect(detail).not.toHaveProperty("mcpServer");
-expect(detail).not.toHaveProperty("body");
-```
-
-If an existing fixture expects a body, assert that `body` is not included by default.
-
-- [ ] **Step 2: Run focused tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/registry.test.ts test/tools.test.ts
-```
-
-Expected: FAIL because MCP detail currently duplicates backend data in `mcpServer`, and Markdown body may be included.
-
-- [ ] **Step 3: Remove `mcpServer` from the public detail type**
-
-In `packages/core/src/registry.ts`, remove the `mcpServer?: { ... }` field from `CapletServerDetail`.
-
-- [ ] **Step 4: Remove default body and MCP duplication from `detail()`**
-
-Replace the `detail()` return object with:
-
-```ts
-return {
-  caplet: server.server,
-  name: server.name,
-  description: server.description,
-  ...(server.tags ? { tags: server.tags } : {}),
-  backend,
-};
-```
-
-- [ ] **Step 5: Run focused tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/registry.test.ts test/tools.test.ts
-```
-
-Expected: PASS after updating any expected snapshots or objects.
-
----
-
-### Task 8: Make Pi Adapter Visible Content Concise
-
-**Files:**
-
-- Modify: `packages/pi/src/index.ts`
-- Test: `packages/pi/test/pi.test.ts`
-
-- [ ] **Step 1: Add Pi adapter tests for concise visible content**
-
-In `packages/pi/test/pi.test.ts`, add:
-
-```ts
-it("stores full Caplets result in details while returning compact visible content", async () => {
-  const service = mockService([
-    {
-      caplet: "context7",
-      toolName: "caplets_context7",
-      title: "Context7",
-      description: "Context7 Caplet",
-      promptGuidance: ["Use caplets_context7 for Context7."],
-    },
-  ]);
-  const fullResult = {
-    content: [{ type: "text", text: "very long docs" }],
-    structuredContent: { result: { tools: [{ tool: "resolve-library-id" }] } },
-  };
-  service.execute.mockResolvedValueOnce(fullResult);
-  const registered: RegisteredTool[] = [];
-
-  capletsPiExtension(
-    {
-      registerTool: (definition) => registered.push(definition as unknown as RegisteredTool),
-    },
-    { service },
-  );
-
-  const result = await registered[0]?.execute("call-1", {
-    operation: "list_tools",
-  });
-
-  expect(result?.content[0]?.text).toBe("structured keys: result");
-  expect(result?.content[0]?.text).not.toContain("resolve-library-id");
-  expect(result?.details).toEqual({ result: fullResult });
-});
-```
-
-- [ ] **Step 2: Run Pi tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-```
-
-Expected: FAIL because `execute()` currently serializes the entire result into visible content.
-
-- [ ] **Step 3: Add local compact serializer in Pi adapter**
-
-In `packages/pi/src/index.ts`, replace `serializeResult()` with:
-
-```ts
-function serializeResult(result: unknown): {
-  text: string;
-  serializationError?: string;
-} {
-  try {
-    return { text: compactResultText(result) };
-  } catch (error) {
-    const serializationError = error instanceof Error ? error.message : String(error);
-    return {
-      text: `[Serialization error: ${serializationError}]`,
-      serializationError,
-    };
-  }
-}
-
-function compactResultText(result: unknown): string {
-  if (!result || typeof result !== "object" || Array.isArray(result)) {
-    return String(result ?? "null");
-  }
-  const structured = objectProperty(result, "structuredContent");
-  if (structured) {
-    const keys = Object.keys(structured).filter((key) => key !== "caplets");
-    return keys.length ? `structured keys: ${keys.join(", ")}` : "structured result";
-  }
-  const content = arrayProperty(result, "content")
-    .filter((item) => stringProperty(item, "type") === "text")
-    .map((item) => stringProperty(item, "text"))
-    .filter((text): text is string => Boolean(text));
-  if (content.length > 0) {
-    return content.join("\n").replace(/\s+/gu, " ").trim().slice(0, 600);
-  }
-  return "Caplets result";
-}
-```
-
-Keep the existing `details: { result }` behavior unchanged.
-
-- [ ] **Step 4: Update old Pi tests that expected full JSON content**
-
-Replace assertions that expect serialized JSON in `result.content[0].text` with concise text expectations. For `undefined`, keep:
-
-```ts
-expect(result?.content[0]?.text).toBe("null");
-```
-
-For structured results, use:
-
-```ts
-expect(result?.content[0]?.text).toContain("structured keys:");
-expect(result?.details.result).toEqual(fullResult);
-```
-
-- [ ] **Step 5: Run Pi tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-```
-
-Expected: PASS.
-
----
-
-### Task 9: Make OpenCode Adapter Visible Content Concise
-
-**Files:**
-
-- Modify: `packages/opencode/src/hooks.ts`
-- Test: `packages/opencode/test/opencode.test.ts`
-
-- [ ] **Step 1: Add OpenCode concise output test**
-
-In `packages/opencode/test/opencode.test.ts`, add:
-
-```ts
-it("returns compact text for structured Caplets results", async () => {
-  const service = mockService([
-    {
-      caplet: "linear",
-      toolName: "caplets_linear",
-      title: "Linear",
-      description: "Linear Caplet",
-      promptGuidance: ["Use caplets_linear for Linear."],
-    },
-  ]);
-  service.execute.mockResolvedValueOnce({
-    content: [{ type: "text", text: "large downstream result" }],
-    structuredContent: { result: { issues: [{ id: "LIN-1" }] } },
-  });
-
-  const hooks = await createCapletsOpenCodeHooks(service);
-  const output = await hooks.tool.caplets_linear.execute({
-    operation: "list_tools",
-  });
-
-  expect(output).toBe("structured keys: result");
-  expect(output).not.toContain("LIN-1");
-});
-```
-
-Use the exact mock helper names already present in the file.
-
-- [ ] **Step 2: Run OpenCode tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: FAIL because OpenCode currently returns full pretty JSON for non-string results.
-
-- [ ] **Step 3: Add compact result helper in OpenCode hooks**
-
-In `packages/opencode/src/hooks.ts`, replace the `execute` body with:
-
-```ts
-async execute(args) {
-  const result = await service.execute(caplet.caplet, args);
-  return compactOpenCodeResult(result);
-},
-```
-
-Add this helper below `createCapletsOpenCodeHooks()`:
-
-```ts
-function compactOpenCodeResult(result: unknown): string {
-  if (typeof result === "string") return result;
-  if (!result || typeof result !== "object" || Array.isArray(result)) {
-    return String(result ?? "null");
-  }
-  const structured = (result as Record<string, unknown>).structuredContent;
-  if (structured && typeof structured === "object" && !Array.isArray(structured)) {
-    const keys = Object.keys(structured).filter((key) => key !== "caplets");
-    return keys.length ? `structured keys: ${keys.join(", ")}` : "structured result";
-  }
-  const content = (result as Record<string, unknown>).content;
-  if (Array.isArray(content)) {
-    const text = content
-      .filter((item): item is { type: string; text: string } =>
-        Boolean(
-          item &&
-          typeof item === "object" &&
-          !Array.isArray(item) &&
-          (item as any).type === "text" &&
-          typeof (item as any).text === "string",
-        ),
-      )
-      .map((item) => item.text)
-      .join("\n")
-      .replace(/\s+/gu, " ")
-      .trim();
-    if (text) return text.length > 600 ? `${text.slice(0, 599).trimEnd()}…` : text;
-  }
-  return "Caplets result";
-}
-```
-
-- [ ] **Step 4: Run OpenCode tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: PASS.
-
----
-
-### Task 10: Add Bounded Output Options For Generated HTTP And CLI Backends
-
-**Files:**
-
-- Modify: `packages/core/src/config.ts`
-- Modify: `packages/core/src/http-actions.ts`
-- Modify: `packages/core/src/openapi.ts`
-- Modify: `packages/core/src/graphql.ts`
-- Modify: `packages/core/src/cli-tools.ts`
-- Test: `packages/core/test/config.test.ts`
-- Test: `packages/core/test/http-actions.test.ts`
-- Test: `packages/core/test/openapi.test.ts`
-- Test: `packages/core/test/graphql.test.ts`
-- Test: `packages/core/test/cli-tools.test.ts`
-- Generated: `schemas/caplets-config.schema.json`
-
-- [ ] **Step 1: Add config tests for smaller defaults**
-
-In `packages/core/test/config.test.ts`, update default expectations:
-
-```ts
-expect(config.httpApis.api?.maxResponseBytes).toBe(200_000);
-expect(config.cliTools.repo?.maxOutputBytes).toBe(200_000);
-```
-
-Add a test that explicit large values still work:
-
-```ts
-it("allows explicit larger response and CLI output byte limits", () => {
-  const config = loadConfigFromObject({
-    version: 1,
-    httpApis: {
-      api: {
-        name: "API",
-        description: "HTTP API description.",
-        baseUrl: "https://example.com",
-        auth: { type: "none" },
-        maxResponseBytes: 1_000_000,
-        actions: {
-          ping: { method: "GET", path: "/ping" },
-        },
-      },
-    },
-    cliTools: {
-      repo: {
-        name: "Repo",
-        description: "Repository CLI description.",
-        maxOutputBytes: 1_000_000,
-        actions: {
-          status: { command: "git", args: ["status"] },
-        },
-      },
-    },
-  });
-
-  expect(config.httpApis.api?.maxResponseBytes).toBe(1_000_000);
-  expect(config.cliTools.repo?.maxOutputBytes).toBe(1_000_000);
-});
-```
-
-Use the existing config test helper names in the file.
-
-- [ ] **Step 2: Run config tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/config.test.ts
-```
-
-Expected: FAIL because defaults are currently 1 MB.
-
-- [ ] **Step 3: Lower default byte limits in config**
-
-In `packages/core/src/config.ts`, replace both `.default(1_000_000)` for HTTP `maxResponseBytes` and CLI `maxOutputBytes` with:
-
-```ts
-.default(200_000)
-```
-
-- [ ] **Step 4: Add truncation marker to generated compact content**
-
-In `packages/core/src/result-content.ts`, add:
-
-```ts
-export function byteLimitHint(maxBytes: number): string {
-  return `response body limit ${maxBytes} bytes`;
-}
-```
-
-Do not add this hint to every successful response. Use it only in errors or summaries when a limit was hit. Existing `readLimitedText()` already throws when the limit is exceeded, so no backend code change is needed beyond defaults unless tests require exact error messages.
-
-- [ ] **Step 5: Regenerate schema**
-
-Run:
-
-```bash
-pnpm schema:generate
-```
-
-Expected: `schemas/caplets-config.schema.json` updates default values for HTTP and CLI byte limits.
-
-- [ ] **Step 6: Run focused backend/config tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/config.test.ts test/http-actions.test.ts test/openapi.test.ts test/graphql.test.ts test/cli-tools.test.ts
-pnpm schema:check
-```
-
-Expected: PASS.
-
----
-
-### Task 11: Expand Benchmarks To Cover Runtime Result Surfaces
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/surface.ts`
-- Modify: `packages/benchmarks/test/benchmark.test.ts`
-- Generated: `docs/benchmarks/coding-agent.md`
-
-- [ ] **Step 1: Add benchmark expectations for runtime duplication**
-
-In `packages/benchmarks/test/benchmark.test.ts`, add assertions after the existing surface benchmark checks:
-
-```ts
-expect(result.runtime).toMatchObject({
-  duplicatedStructuredContentBytes: expect.any(Number),
-  compactStructuredContentBytes: expect.any(Number),
-});
-expect(result.runtime.compactStructuredContentBytes).toBeLessThan(
-  result.runtime.duplicatedStructuredContentBytes,
-);
-expect(result.runtime.compactReduction).toBeGreaterThan(0.5);
-```
-
-- [ ] **Step 2: Run benchmark tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts
-```
-
-Expected: FAIL because `runtime` benchmark data does not exist.
-
-- [ ] **Step 3: Add runtime surface stats**
-
-In `packages/benchmarks/lib/surface.ts`, add this function near `surfaceStats()`:
-
-```ts
-function runtimeResultStats() {
-  const structured = {
-    status: 200,
-    statusText: "OK",
-    headers: { "content-type": "application/json" },
-    body: {
-      items: Array.from({ length: 20 }, (_, index) => ({
-        id: `item-${index}`,
-        title: `Example item ${index}`,
-        description:
-          "Representative downstream payload content used for token surface measurement.",
-      })),
-    },
-    elapsedMs: 42,
-  };
-  const duplicated = {
-    content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
-    structuredContent: structured,
-  };
-  const compact = {
-    content: [{ type: "text", text: "status 200; OK; body" }],
-    structuredContent: structured,
-  };
-  const duplicatedBytes = Buffer.byteLength(JSON.stringify(duplicated), "utf8");
-  const compactBytes = Buffer.byteLength(JSON.stringify(compact), "utf8");
-  return {
-    duplicatedStructuredContentBytes: duplicatedBytes,
-    compactStructuredContentBytes: compactBytes,
-    compactReduction: 1 - compactBytes / duplicatedBytes,
-    compactReductionPercent: percent(1 - compactBytes / duplicatedBytes),
-  };
-}
-```
-
-In `computeSurfaceBenchmark()`, add:
-
-```ts
-const runtime = runtimeResultStats();
-```
-
-and include it in the returned object:
-
-```ts
-runtime,
-```
-
-- [ ] **Step 4: Update markdown report**
-
-In `renderMarkdownReport()`, add this section after the deterministic initial payload results:
-
-```md
-## Runtime Result Duplication Check
-
-Generated structured backend results previously duplicated the same payload as both text content and structured content. The compact representation reduces the representative runtime result from ${result.runtime.duplicatedStructuredContentBytes} bytes to ${result.runtime.compactStructuredContentBytes} bytes, ${result.runtime.compactReductionPercent} fewer.
-```
-
-- [ ] **Step 5: Run benchmark generation**
-
-Run:
-
-```bash
-pnpm benchmark
-pnpm benchmark:check
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts
-```
-
-Expected: PASS and `docs/benchmarks/coding-agent.md` updated.
-
----
-
-### Task 12: Full Verification And Cleanup
-
-**Files:**
-
-- All modified files from Tasks 1-11
-
-- [ ] **Step 1: Run LSP diagnostics before the full build**
-
-Run via the harness diagnostic tool on:
-
-```text
-packages/core/src
-packages/pi/src
-packages/opencode/src
-packages/benchmarks/lib
-```
-
-Expected: no TypeScript errors.
-
-- [ ] **Step 2: Run format check**
-
-Run:
-
-```bash
-pnpm format:check
-```
-
-Expected: PASS. If it fails, run `pnpm format`, inspect changes, then re-run `pnpm format:check`.
-
-- [ ] **Step 3: Run lint**
-
-Run:
-
-```bash
-pnpm lint
-```
-
-Expected: PASS.
-
-- [ ] **Step 4: Run typecheck**
-
-Run:
-
-```bash
-pnpm typecheck
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Run schema check**
-
-Run:
-
-```bash
-pnpm schema:check
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Run all tests**
-
-Run:
-
-```bash
-pnpm test
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Run benchmark check**
-
-Run:
-
-```bash
-pnpm benchmark:check
-```
-
-Expected: PASS.
-
-- [ ] **Step 8: Run build**
-
-Run:
-
-```bash
-pnpm build
-```
-
-Expected: PASS.
-
-- [ ] **Step 9: Run full verify gate**
-
-Run:
-
-```bash
-pnpm verify
-```
-
-Expected: PASS.
-
----
-
-## Self-Review
-
-**Spec coverage:**
-
-- Discovery `content` plus `structuredContent` waste is covered by Tasks 1 and 3.
-- HTTP/OpenAPI/GraphQL/CLI generated result duplication is covered by Task 2.
-- Pi adapter full-result serialization is covered by Task 8.
-- OpenCode adapter full-result serialization is covered by Task 9.
-- Repeated caplet workflow instructions and prompt guidance are covered by Task 4.
-- Verbose generated input schema descriptions are covered by Task 5.
-- Large `list_tools` compact payloads are covered by Task 6.
-- `get_caplet` body and MCP backend duplication are covered by Task 7.
-- Large generated output defaults are covered by Task 10.
-- Benchmark blind spot is covered by Task 11.
-- Full verification is covered by Task 12.
-
-**Placeholder scan:** This plan contains no `TBD`, no `TODO`, and no steps that defer implementation decisions without concrete commands or code.
-
-**Type consistency:** New helper names are consistent across tasks: `structuredOnlyContent`, `compactStructuredContent`, `compactText`, `compactJsonText`, `statusSummary`, and `resultKeys`. The plan uses existing result fields `content`, `structuredContent`, `isError`, and `_meta.caplets` without renaming them.
diff --git a/docs/plans/2026-05-20-remote-cli-control.md b/docs/plans/2026-05-20-remote-cli-control.md
deleted file mode 100644
index d3184491..00000000
--- a/docs/plans/2026-05-20-remote-cli-control.md
+++ /dev/null
@@ -1,2582 +0,0 @@
-# Remote CLI Control Service Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make the `caplets` CLI, OpenCode integration, and Pi integration use a unified `CAPLETS_MODE` / `CAPLETS_SERVER_*` interface so CLI commands can operate against a remote `caplets serve --transport http` service through an authenticated structured control endpoint.
-
-**Architecture:** Introduce shared server-mode and base-URL resolution, change HTTP serving so `--path` is the service base path, add a `/control` API beside `/mcp`, then route remote-capable CLI commands through a typed remote control client. The server owns config, Caplet files, installed Caplets, and downstream auth; local clients format output and never receive secrets.
-
-**Tech Stack:** TypeScript, Vitest, Hono, @hono/mcp Streamable HTTP transport, MCP SDK auth helpers, existing CapletsEngine, pnpm.
-
----
-
-## File structure
-
-- Create `packages/core/src/server/options.ts` for unified `CAPLETS_MODE`, `CAPLETS_SERVER_URL`, `CAPLETS_SERVER_USER`, and `CAPLETS_SERVER_PASSWORD` parsing.
-- Create `packages/core/src/remote-control/types.ts` for request/response envelopes, command names, and result payload types.
-- Create `packages/core/src/remote-control/client.ts` for the local CLI remote control client.
-- Create `packages/core/src/remote-control/dispatch.ts` for server-side command dispatch that reuses existing internal functions.
-- Create `packages/core/src/remote-control/auth-flow.ts` for remote auth login flow storage and callback completion.
-- Modify `packages/core/src/serve/options.ts` so HTTP `--path` is a service base path and `CAPLETS_SERVER_URL` supplies HTTP serve defaults.
-- Modify `packages/core/src/serve/http.ts` to mount `{base}/healthz`, `{base}/mcp`, `{base}/control`, and `{base}/control/auth/callback/:flowId`.
-- Modify `packages/core/src/serve/index.ts` only if new HTTP app dependencies need wiring.
-- Modify `packages/core/src/native/options.ts` so native service resolution uses `CAPLETS_MODE` and `CAPLETS_SERVER_URL` as the target model.
-- Modify `packages/opencode/src/index.ts` and `packages/pi/src/index.ts` to expose the unified option naming while preserving explicit host config seams.
-- Modify `packages/core/src/cli.ts` to route remote-capable commands through `RemoteControlClient` when mode resolution selects remote.
-- Modify `packages/core/src/cli/auth.ts` to expose structured auth helpers used by both local CLI and remote-control dispatch.
-- Modify `packages/core/src/cli/inspection.ts` only if exported result types are needed by remote-control response typing.
-- Modify `README.md`, `packages/cli/README.md`, `packages/opencode/README.md`, and `packages/pi/README.md` for the unified environment and base-path model.
-- Add `packages/core/test/server-options.test.ts`.
-- Add `packages/core/test/remote-control-client.test.ts`.
-- Add `packages/core/test/remote-control-dispatch.test.ts`.
-- Add `packages/core/test/cli-remote.test.ts`.
-- Modify `packages/core/test/serve-options.test.ts`.
-- Modify `packages/core/test/serve-http.test.ts`.
-- Modify `packages/core/test/native-options.test.ts`.
-- Modify `packages/opencode/test/opencode.test.ts`.
-- Modify `packages/pi/test/pi.test.ts`.
-- Add a changeset under `.changeset/` for `@caplets/core`, `caplets`, `@caplets/opencode`, and `@caplets/pi`.
-
----
-
-## Task 1: Add unified server option resolution
-
-**Files:**
-
-- Create: `packages/core/src/server/options.ts`
-- Test: `packages/core/test/server-options.test.ts`
-
-- [ ] **Step 1: Write failing server option tests**
-
-Create `packages/core/test/server-options.test.ts`:
-
-```ts
-import { Buffer } from "node:buffer";
-import { describe, expect, it } from "vitest";
-import type { CapletsError } from "../src/errors";
-import {
-  controlUrlForBase,
-  healthUrlForBase,
-  mcpUrlForBase,
-  resolveCapletsMode,
-  resolveCapletsServer,
-} from "../src/server/options";
-
-describe("server option resolution", () => {
-  it("defaults to local mode without a server URL", () => {
-    expect(resolveCapletsMode({}, {})).toEqual({ mode: "local" });
-  });
-
-  it("uses remote mode in auto when CAPLETS_SERVER_URL is set", () => {
-    expect(resolveCapletsMode({}, { CAPLETS_SERVER_URL: "http://127.0.0.1:5387/caplets" })).toEqual(
-      { mode: "remote" },
-    );
-  });
-
-  it("lets explicit local mode ignore server settings", () => {
-    expect(
-      resolveCapletsMode({}, { CAPLETS_MODE: "local", CAPLETS_SERVER_URL: "https://example.com" }),
-    ).toEqual({ mode: "local" });
-  });
-
-  it("requires CAPLETS_SERVER_URL in forced remote mode", () => {
-    expect(() => resolveCapletsMode({}, { CAPLETS_MODE: "remote" })).toThrow(
-      expect.objectContaining({ code: "REQUEST_INVALID" }) as CapletsError,
-    );
-  });
-
-  it("rejects invalid CAPLETS_MODE values", () => {
-    expect(() => resolveCapletsMode({}, { CAPLETS_MODE: "cloud" })).toThrow(
-      /auto, local, or remote/u,
-    );
-  });
-
-  it("normalizes a base URL and derives service endpoints", () => {
-    const resolved = resolveCapletsServer(
-      {},
-      {
-        CAPLETS_SERVER_URL: "https://example.com/caplets/",
-        CAPLETS_SERVER_USER: "admin",
-        CAPLETS_SERVER_PASSWORD: ["fixture", "password"].join("-"),
-      },
-    );
-
-    expect(resolved).toMatchObject({
-      baseUrl: new URL("https://example.com/caplets"),
-      auth: {
-        enabled: true,
-        user: "admin",
-        password: ["fixture", "password"].join("-"),
-      },
-    });
-    expect(mcpUrlForBase(resolved.baseUrl).toString()).toBe("https://example.com/caplets/mcp");
-    expect(controlUrlForBase(resolved.baseUrl).toString()).toBe(
-      "https://example.com/caplets/control",
-    );
-    expect(healthUrlForBase(resolved.baseUrl).toString()).toBe(
-      "https://example.com/caplets/healthz",
-    );
-    expect(resolved.requestInit.headers).toEqual({
-      Authorization: `Basic ${Buffer.from(`admin:${["fixture", "password"].join("-")}`).toString("base64")}`,
-    });
-  });
-
-  it("derives endpoints from a root service base URL", () => {
-    const base = new URL("http://127.0.0.1:5387");
-
-    expect(mcpUrlForBase(base).toString()).toBe("http://127.0.0.1:5387/mcp");
-    expect(controlUrlForBase(base).toString()).toBe("http://127.0.0.1:5387/control");
-    expect(healthUrlForBase(base).toString()).toBe("http://127.0.0.1:5387/healthz");
-  });
-
-  it("rejects non-loopback http server URLs", () => {
-    expect(() =>
-      resolveCapletsServer({}, { CAPLETS_SERVER_URL: "http://caplets.example.com" }),
-    ).toThrow(/https/u);
-  });
-
-  it("rejects username, password, query, or fragment in server URLs", () => {
-    for (const url of [
-      "https://user:pass@example.com/caplets",
-      "https://example.com/caplets?token=secret",
-      "https://example.com/caplets#fragment",
-    ]) {
-      expect(() => resolveCapletsServer({}, { CAPLETS_SERVER_URL: url })).toThrow(
-        expect.objectContaining({ code: "REQUEST_INVALID" }) as CapletsError,
-      );
-    }
-  });
-
-  it("requires a password when user is explicit", () => {
-    expect(() =>
-      resolveCapletsServer(
-        {},
-        {
-          CAPLETS_SERVER_URL: "https://example.com",
-          CAPLETS_SERVER_USER: "caplets",
-        },
-      ),
-    ).toThrow(/requires a password/u);
-  });
-});
-```
-
-- [ ] **Step 2: Run server option tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/server-options.test.ts
-```
-
-Expected: FAIL with module-not-found for `../src/server/options`.
-
-- [ ] **Step 3: Implement shared server option resolution**
-
-Create `packages/core/src/server/options.ts`:
-
-```ts
-import { Buffer } from "node:buffer";
-import { CapletsError } from "../errors";
-
-export type CapletsMode = "auto" | "local" | "remote";
-
-export type CapletsServerEnv = Partial<
-  Record<
-    "CAPLETS_MODE" | "CAPLETS_SERVER_URL" | "CAPLETS_SERVER_USER" | "CAPLETS_SERVER_PASSWORD",
-    string
-  >
->;
-
-export type CapletsModeInput = {
-  mode?: CapletsMode | undefined;
-  serverUrl?: string | undefined;
-};
-
-export type CapletsServerInput = {
-  url?: string | undefined;
-  user?: string | undefined;
-  password?: string | undefined;
-  fetch?: typeof fetch | undefined;
-};
-
-export type CapletsServerAuth =
-  | { enabled: false; user: string }
-  | { enabled: true; user: string; password: string };
-
-export type ResolvedCapletsServer = {
-  baseUrl: URL;
-  auth: CapletsServerAuth;
-  requestInit: RequestInit;
-  fetch?: typeof fetch;
-};
-
-const DEFAULT_SERVER_USER = "caplets";
-
-export function resolveCapletsMode(
-  input: CapletsModeInput = {},
-  env: CapletsServerEnv = process.env,
-): { mode: "local" } | { mode: "remote" } {
-  const mode = parseMode(input.mode ?? env.CAPLETS_MODE ?? "auto");
-  if (mode === "local") return { mode: "local" };
-
-  const rawUrl =
-    nonEmpty(input.serverUrl, "serverUrl") ??
-    nonEmpty(env.CAPLETS_SERVER_URL, "CAPLETS_SERVER_URL");
-  if (mode === "remote" && rawUrl === undefined) {
-    throw new CapletsError("REQUEST_INVALID", "CAPLETS_MODE=remote requires CAPLETS_SERVER_URL.");
-  }
-  return rawUrl === undefined ? { mode: "local" } : { mode: "remote" };
-}
-
-export function resolveCapletsServer(
-  input: CapletsServerInput = {},
-  env: CapletsServerEnv = process.env,
-): ResolvedCapletsServer {
-  const rawUrl =
-    nonEmpty(input.url, "server.url") ?? nonEmpty(env.CAPLETS_SERVER_URL, "CAPLETS_SERVER_URL");
-  if (rawUrl === undefined) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "CAPLETS_SERVER_URL is required for remote Caplets mode.",
-    );
-  }
-
-  const baseUrl = parseServerBaseUrl(rawUrl);
-  const userWasExplicit = input.user !== undefined || hasEnv(env.CAPLETS_SERVER_USER);
-  const user =
-    nonEmpty(input.user, "server.user") ??
-    nonEmpty(env.CAPLETS_SERVER_USER, "CAPLETS_SERVER_USER") ??
-    DEFAULT_SERVER_USER;
-  const password =
-    nonEmpty(input.password, "server.password") ??
-    nonEmpty(env.CAPLETS_SERVER_PASSWORD, "CAPLETS_SERVER_PASSWORD");
-
-  if (userWasExplicit && password === undefined) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "Remote Caplets Basic Auth requires a password; set CAPLETS_SERVER_PASSWORD or server.password.",
-    );
-  }
-
-  const auth: CapletsServerAuth =
-    password === undefined ? { enabled: false, user } : { enabled: true, user, password };
-  const requestInit: RequestInit = auth.enabled
-    ? { headers: { Authorization: basicAuthHeader(auth.user, auth.password) } }
-    : {};
-
-  return {
-    baseUrl,
-    auth,
-    requestInit,
-    ...(input.fetch ? { fetch: input.fetch } : {}),
-  };
-}
-
-export function mcpUrlForBase(baseUrl: URL): URL {
-  return appendBasePath(baseUrl, "mcp");
-}
-
-export function controlUrlForBase(baseUrl: URL): URL {
-  return appendBasePath(baseUrl, "control");
-}
-
-export function healthUrlForBase(baseUrl: URL): URL {
-  return appendBasePath(baseUrl, "healthz");
-}
-
-export function appendBasePath(baseUrl: URL, child: string): URL {
-  const url = new URL(baseUrl.toString());
-  const basePath = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/u, "");
-  url.pathname = `${basePath}/${child}`;
-  return url;
-}
-
-export function parseServerBaseUrl(value: string): URL {
-  let url: URL;
-  try {
-    url = new URL(value);
-  } catch {
-    throw new CapletsError("REQUEST_INVALID", "Invalid CAPLETS_SERVER_URL.");
-  }
-  if (url.username !== "" || url.password !== "") {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "CAPLETS_SERVER_URL must not include username or password; use CAPLETS_SERVER_USER/CAPLETS_SERVER_PASSWORD instead.",
-    );
-  }
-  if (url.search !== "" || url.hash !== "") {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "CAPLETS_SERVER_URL must not include query or fragment.",
-    );
-  }
-  if (url.protocol === "https:") {
-    return normalizeBaseUrlPath(url);
-  }
-  if (url.protocol === "http:" && isLoopbackHost(url.hostname)) {
-    return normalizeBaseUrlPath(url);
-  }
-  throw new CapletsError(
-    "REQUEST_INVALID",
-    "CAPLETS_SERVER_URL must use https except loopback development URLs.",
-  );
-}
-
-export function isLoopbackHost(host: string): boolean {
-  const normalized = host.toLocaleLowerCase();
-  return (
-    normalized === "localhost" ||
-    normalized === "127.0.0.1" ||
-    normalized === "::1" ||
-    normalized === "[::1]"
-  );
-}
-
-function normalizeBaseUrlPath(url: URL): URL {
-  const normalized = new URL(url.toString());
-  normalized.pathname =
-    normalized.pathname === "/" ? "/" : normalized.pathname.replace(/\/+$/u, "");
-  return normalized;
-}
-
-function parseMode(value: string): CapletsMode {
-  if (value === "auto" || value === "local" || value === "remote") return value;
-  throw new CapletsError(
-    "REQUEST_INVALID",
-    `Expected CAPLETS_MODE to be auto, local, or remote, got ${value}`,
-  );
-}
-
-function basicAuthHeader(user: string, password: string): string {
-  return `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
-}
-
-function nonEmpty(value: string | undefined, label: string): string | undefined {
-  if (value === undefined) return undefined;
-  const trimmed = value.trim();
-  if (!trimmed) throw new CapletsError("REQUEST_INVALID", `${label} must not be empty`);
-  return trimmed;
-}
-
-function hasEnv(value: string | undefined): boolean {
-  return value !== undefined && value.trim() !== "";
-}
-```
-
-- [ ] **Step 4: Run server option tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/server-options.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit server option resolution**
-
-Run:
-
-```sh
-git add packages/core/src/server/options.ts packages/core/test/server-options.test.ts
-git commit -m "feat(core): add unified Caplets server options"
-```
-
----
-
-## Task 2: Update native integrations to use unified env vars
-
-**Files:**
-
-- Modify: `packages/core/src/native/options.ts`
-- Modify: `packages/core/src/native/remote.ts`
-- Modify: `packages/opencode/src/index.ts`
-- Modify: `packages/pi/src/index.ts`
-- Test: `packages/core/test/native-options.test.ts`
-- Test: `packages/core/test/native-remote.test.ts`
-- Test: `packages/opencode/test/opencode.test.ts`
-- Test: `packages/pi/test/pi.test.ts`
-
-- [ ] **Step 1: Update native option tests for unified vars**
-
-Modify `packages/core/test/native-options.test.ts` so env-driven tests use base URLs and new env names:
-
-```ts
-expect(
-  resolveNativeCapletsServiceOptions({}, { CAPLETS_SERVER_URL: "http://127.0.0.1:5387/caplets" }),
-).toMatchObject({
-  mode: "remote",
-  remote: {
-    url: new URL("http://127.0.0.1:5387/caplets/mcp"),
-    auth: { enabled: false, user: "caplets" },
-    pollIntervalMs: 30_000,
-  },
-});
-```
-
-Replace the explicit local-mode test with:
-
-```ts
-expect(
-  resolveNativeCapletsServiceOptions(
-    {},
-    {
-      CAPLETS_MODE: "local",
-      CAPLETS_SERVER_URL: "http://127.0.0.1:5387/caplets",
-    },
-  ),
-).toEqual({ mode: "local" });
-```
-
-Replace the missing remote URL assertion with:
-
-```ts
-expect(() => resolveNativeCapletsServiceOptions({}, { CAPLETS_MODE: "remote" })).toThrow(
-  expect.objectContaining({ code: "REQUEST_INVALID" }) as CapletsError,
-);
-```
-
-Replace env override assertions with `CAPLETS_SERVER_URL`, `CAPLETS_SERVER_USER`, and `CAPLETS_SERVER_PASSWORD`. Replace embedded credential error text to mention `CAPLETS_SERVER_USER/CAPLETS_SERVER_PASSWORD`.
-
-- [ ] **Step 2: Update remote auth error guidance test**
-
-Modify `packages/core/test/native-remote.test.ts` auth failure expectation:
-
-```ts
-await expect(service.execute("alpha", {})).rejects.toMatchObject({
-  code: "AUTH_FAILED",
-  message: expect.stringContaining("CAPLETS_SERVER_USER"),
-} satisfies Partial<CapletsError>);
-```
-
-- [ ] **Step 3: Update OpenCode config test to pass base server config**
-
-Modify `packages/opencode/test/opencode.test.ts` config propagation test to pass:
-
-```ts
-await plugin(
-  {} as never,
-  {
-    mode: "remote",
-    server: {
-      url: "https://caplets.example.com/caplets",
-      user: "caplets",
-    },
-    remote: { pollIntervalMs: 5_000 },
-  } as never,
-);
-
-expect(nativeMocks.createNativeCapletsService).toHaveBeenCalledWith({
-  mode: "remote",
-  server: {
-    url: "https://caplets.example.com/caplets",
-    user: "caplets",
-  },
-  remote: { pollIntervalMs: 5_000 },
-});
-```
-
-- [ ] **Step 4: Update Pi settings tests to parse unified server shape**
-
-In `packages/pi/test/pi.test.ts`, update the settings/args propagation tests so accepted settings include:
-
-```json
-{
-  "caplets": {
-    "mode": "remote",
-    "server": {
-      "url": "https://caplets.example.com/caplets",
-      "user": "caplets"
-    },
-    "remote": {
-      "pollIntervalMs": 5000
-    }
-  }
-}
-```
-
-Expected options passed to `createNativeCapletsService`:
-
-```ts
-{
-  mode: "remote",
-  server: { url: "https://caplets.example.com/caplets", user: "caplets" },
-  remote: { pollIntervalMs: 5_000 },
-}
-```
-
-- [ ] **Step 5: Run native and integration tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/native-options.test.ts test/native-remote.test.ts
-pnpm --filter @caplets/opencode test -- opencode.test.ts
-pnpm --filter @caplets/pi test -- pi.test.ts
-```
-
-Expected: FAIL because implementation still reads the legacy remote env names and OpenCode/Pi config types do not expose `server`.
-
-- [ ] **Step 6: Implement native option resolution with shared server options**
-
-Modify `packages/core/src/native/options.ts`:
-
-```ts
-import {
-  mcpUrlForBase,
-  resolveCapletsMode,
-  resolveCapletsServer,
-  type CapletsMode,
-  type CapletsServerEnv,
-  type CapletsServerInput,
-} from "../server/options";
-
-export type NativeCapletsMode = CapletsMode;
-
-export type NativeRemoteCapletsOptions = {
-  pollIntervalMs?: number;
-  fetch?: typeof fetch;
-};
-
-export type NativeCapletsServiceResolutionInput = {
-  mode?: NativeCapletsMode;
-  server?: CapletsServerInput;
-  remote?: NativeRemoteCapletsOptions;
-};
-
-export type NativeCapletsEnv = CapletsServerEnv;
-
-export function resolveNativeCapletsServiceOptions(
-  input: NativeCapletsServiceResolutionInput = {},
-  env: NativeCapletsEnv = process.env,
-): ResolvedNativeCapletsServiceOptions {
-  const mode = resolveCapletsMode({ mode: input.mode, serverUrl: input.server?.url }, env);
-  if (mode.mode === "local") return { mode: "local" };
-
-  const server = resolveCapletsServer(
-    {
-      ...input.server,
-      fetch: input.remote?.fetch ?? input.server?.fetch,
-    },
-    env,
-  );
-
-  return {
-    mode: "remote",
-    remote: {
-      url: mcpUrlForBase(server.baseUrl),
-      auth: server.auth,
-      pollIntervalMs: parsePollInterval(input.remote?.pollIntervalMs),
-      requestInit: server.requestInit,
-      ...(server.fetch ? { fetch: server.fetch } : {}),
-    },
-  };
-}
-```
-
-Keep the existing `ResolvedNativeCapletsServiceOptions` type and `parsePollInterval()` helper. Remove URL parsing and Basic Auth helper duplication from this file.
-
-- [ ] **Step 7: Update native remote auth guidance**
-
-Modify `remoteAuthError()` in `packages/core/src/native/remote.ts`:
-
-```ts
-return new CapletsError(
-  "AUTH_FAILED",
-  "Remote Caplets authentication failed; check CAPLETS_SERVER_USER and CAPLETS_SERVER_PASSWORD.",
-);
-```
-
-- [ ] **Step 8: Update OpenCode option type**
-
-Modify `packages/opencode/src/index.ts`:
-
-```ts
-export type CapletsOpenCodeConfig = Pick<NativeCapletsServiceOptions, "mode" | "server" | "remote">;
-
-function normalizeOpenCodeConfig(config: CapletsOpenCodeConfig | undefined): CapletsOpenCodeConfig {
-  if (!config) return {};
-  return {
-    ...(config.mode ? { mode: config.mode } : {}),
-    ...(config.server ? { server: config.server } : {}),
-    ...(config.remote ? { remote: config.remote } : {}),
-  };
-}
-```
-
-- [ ] **Step 9: Update Pi option parsing**
-
-Modify `packages/pi/src/index.ts`:
-
-```ts
-type PiNativeCapletsOptions = Pick<NativeCapletsServiceOptions, "mode" | "server" | "remote">;
-```
-
-In `parsePiNativeOptions()`, add parsing for `server`:
-
-```ts
-const server = objectProperty(value, "server");
-if (server) {
-  const parsedServer: NonNullable<PiNativeCapletsOptions["server"]> = {};
-  for (const key of ["url", "user", "password"] as const) {
-    const field = server[key];
-    if (field !== undefined) {
-      if (typeof field !== "string") return undefined;
-      parsedServer[key] = field;
-    }
-  }
-  result.server = parsedServer;
-}
-```
-
-Keep `remote.pollIntervalMs` parsing and remove `remote.url`, `remote.user`, and `remote.password` parsing from the target shape.
-
-- [ ] **Step 10: Run native and integration tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/native-options.test.ts test/native-remote.test.ts
-pnpm --filter @caplets/opencode test -- opencode.test.ts
-pnpm --filter @caplets/pi test -- pi.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 11: Commit unified native config**
-
-Run:
-
-```sh
-git add packages/core/src/native/options.ts packages/core/src/native/remote.ts packages/opencode/src/index.ts packages/pi/src/index.ts packages/core/test/native-options.test.ts packages/core/test/native-remote.test.ts packages/opencode/test/opencode.test.ts packages/pi/test/pi.test.ts
-git commit -m "feat(native): use unified Caplets server config"
-```
-
----
-
-## Task 3: Change HTTP serve path to a service base path
-
-**Files:**
-
-- Modify: `packages/core/src/serve/options.ts`
-- Modify: `packages/core/src/serve/http.ts`
-- Test: `packages/core/test/serve-options.test.ts`
-- Test: `packages/core/test/serve-http.test.ts`
-
-- [ ] **Step 1: Update serve option tests for base path semantics**
-
-Modify `packages/core/test/serve-options.test.ts`:
-
-```ts
-it("defaults HTTP serving to localhost port 5387 and root base path", () => {
-  expect(resolveServeOptions({ transport: "http" }, {})).toMatchObject({
-    transport: "http",
-    host: "127.0.0.1",
-    port: 5387,
-    path: "/",
-    auth: { enabled: false, user: "caplets" },
-  });
-});
-
-it("uses CAPLETS_SERVER_URL as HTTP serve defaults", () => {
-  expect(
-    resolveServeOptions(
-      { transport: "http" },
-      {
-        CAPLETS_SERVER_URL: "http://127.0.0.1:7777/caplets",
-        CAPLETS_SERVER_PASSWORD: ["server", "password"].join("-"),
-      },
-    ),
-  ).toMatchObject({
-    transport: "http",
-    host: "127.0.0.1",
-    port: 7777,
-    path: "/caplets",
-    auth: {
-      enabled: true,
-      user: "caplets",
-      password: ["server", "password"].join("-"),
-    },
-  });
-});
-
-it("lets explicit HTTP flags override CAPLETS_SERVER_URL defaults", () => {
-  expect(
-    resolveServeOptions(
-      { transport: "http", host: "127.0.0.1", port: "9999", path: "/local" },
-      { CAPLETS_SERVER_URL: "http://127.0.0.1:7777/caplets" },
-    ),
-  ).toMatchObject({ host: "127.0.0.1", port: 9999, path: "/local" });
-});
-```
-
-- [ ] **Step 2: Update HTTP app tests for mounted subroutes**
-
-Modify `packages/core/test/serve-http.test.ts` helper default path to `/`:
-
-```ts
-function httpOptions(overrides: Partial<HttpServeOptions> = {}): HttpServeOptions {
-  return {
-    transport: "http",
-    host: "127.0.0.1",
-    port: 5387,
-    path: "/",
-    auth: { enabled: false, user: "caplets" },
-    warnUnauthenticatedNetwork: false,
-    loopback: true,
-    ...overrides,
-  };
-}
-```
-
-Add a base-path route test:
-
-```ts
-it("mounts health, mcp, and control under a service base path", async () => {
-  const { engine } = testEngine();
-  const app = createHttpServeApp(httpOptions({ path: "/caplets" }), engine, {
-    writeErr: () => {},
-  });
-
-  expect((await app.request("http://127.0.0.1:5387/healthz")).status).toBe(404);
-  expect((await app.request("http://127.0.0.1:5387/caplets/healthz")).status).toBe(200);
-  expect((await app.request("http://127.0.0.1:5387/caplets/mcp/extra")).status).toBe(404);
-
-  await engine.close();
-});
-```
-
-Update root info assertions to expect `base`, `mcp`, `control`, and `health`:
-
-```ts
-await expect(root.json()).resolves.toMatchObject({
-  name: "caplets",
-  transport: "http",
-  base: "/",
-  mcp: "/mcp",
-  control: "/control",
-  health: "/healthz",
-  auth: { type: "basic", enabled: false },
-});
-```
-
-- [ ] **Step 3: Run serve tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/serve-options.test.ts test/serve-http.test.ts
-```
-
-Expected: FAIL because current HTTP default path is `/mcp` and route mounting treats `path` as the MCP endpoint.
-
-- [ ] **Step 4: Implement base-path serve option resolution**
-
-Modify `packages/core/src/serve/options.ts`:
-
-```ts
-import { parseServerBaseUrl, isLoopbackHost as isServerLoopbackHost } from "../server/options";
-
-export type ServeEnv = Partial<
-  Record<"CAPLETS_SERVER_URL" | "CAPLETS_SERVER_USER" | "CAPLETS_SERVER_PASSWORD", string>
->;
-```
-
-Inside HTTP resolution:
-
-```ts
-const serverUrl = env.CAPLETS_SERVER_URL ? parseServerBaseUrl(env.CAPLETS_SERVER_URL) : undefined;
-const host = nonEmpty(raw.host, "--host") ?? serverUrl?.hostname ?? "127.0.0.1";
-const port = parsePort(raw.port ?? (serverUrl?.port ? Number(serverUrl.port) : 5387));
-const path = normalizeHttpPath(raw.path ?? serverUrl?.pathname ?? "/");
-```
-
-Change the previous default from `"/mcp"` to `"/"`. Keep explicit flag validation and auth handling.
-
-- [ ] **Step 5: Implement service-base route helpers**
-
-Modify `packages/core/src/serve/http.ts` with helpers:
-
-```ts
-function routePath(basePath: string, child: string): string {
-  const base = basePath === "/" ? "" : basePath.replace(/\/+$/u, "");
-  return `${base}/${child}`;
-}
-
-function servicePaths(basePath: string): {
-  base: string;
-  health: string;
-  mcp: string;
-  control: string;
-} {
-  return {
-    base: basePath,
-    health: routePath(basePath, "healthz"),
-    mcp: routePath(basePath, "mcp"),
-    control: routePath(basePath, "control"),
-  };
-}
-```
-
-Use `const paths = servicePaths(options.path);` in `createHttpServeApp()`. Change routes:
-
-```ts
-app.get(paths.base, (c) => c.json({ name: "caplets", transport: "http", base: paths.base, mcp: paths.mcp, control: paths.control, health: paths.health, auth: { type: "basic", enabled: options.auth.enabled } }));
-app.get(paths.health, (c) => c.json({ status: "ok", transport: "http", basePath: paths.base, mcpPath: paths.mcp, controlPath: paths.control }));
-app.all(paths.mcp, basicAuth(options.auth), async (c) => { ...existing MCP session handling... });
-```
-
-Update `serveHttp()` logs:
-
-```ts
-const baseUrl = `http://${formatHost(options.host)}:${options.port}${options.path === "/" ? "" : options.path}`;
-writeErr(`Caplets HTTP service listening on ${baseUrl}\n`);
-writeErr(`MCP endpoint: ${baseUrl}/mcp\n`);
-writeErr(`Control endpoint: ${baseUrl}/control\n`);
-writeErr(`Health check: ${baseUrl}/healthz\n`);
-```
-
-- [ ] **Step 6: Run serve tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/serve-options.test.ts test/serve-http.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit service base-path serving**
-
-Run:
-
-```sh
-git add packages/core/src/serve/options.ts packages/core/src/serve/http.ts packages/core/test/serve-options.test.ts packages/core/test/serve-http.test.ts
-git commit -m "feat(serve): mount HTTP service under a base path"
-```
-
----
-
-## Task 4: Add remote control client and response types
-
-**Files:**
-
-- Create: `packages/core/src/remote-control/types.ts`
-- Create: `packages/core/src/remote-control/client.ts`
-- Test: `packages/core/test/remote-control-client.test.ts`
-
-- [ ] **Step 1: Write failing remote control client tests**
-
-Create `packages/core/test/remote-control-client.test.ts`:
-
-```ts
-import { describe, expect, it, vi } from "vitest";
-import { CapletsError } from "../src/errors";
-import { RemoteControlClient } from "../src/remote-control/client";
-
-describe("RemoteControlClient", () => {
-  it("posts structured requests to the derived control endpoint", async () => {
-    const fetchMock = vi.fn(
-      async () =>
-        new Response(JSON.stringify({ ok: true, result: { rows: [] } }), {
-          status: 200,
-          headers: { "content-type": "application/json" },
-        }),
-    );
-    const client = new RemoteControlClient({
-      baseUrl: new URL("http://127.0.0.1:5387/caplets"),
-      requestInit: { headers: { Authorization: "Basic test" } },
-      fetch: fetchMock as typeof fetch,
-    });
-
-    await expect(client.request("list", { includeDisabled: true })).resolves.toEqual({ rows: [] });
-
-    expect(fetchMock).toHaveBeenCalledWith(
-      new URL("http://127.0.0.1:5387/caplets/control"),
-      expect.objectContaining({
-        method: "POST",
-        headers: expect.objectContaining({
-          Authorization: "Basic test",
-          "content-type": "application/json",
-        }),
-        body: JSON.stringify({
-          command: "list",
-          arguments: { includeDisabled: true },
-        }),
-      }),
-    );
-  });
-
-  it("maps control errors into CapletsError", async () => {
-    const fetchMock = vi.fn(
-      async () =>
-        new Response(
-          JSON.stringify({
-            ok: false,
-            error: {
-              code: "CONFIG_NOT_FOUND",
-              message: "Remote config missing",
-            },
-          }),
-          { status: 200, headers: { "content-type": "application/json" } },
-        ),
-    );
-    const client = new RemoteControlClient({
-      baseUrl: new URL("https://caplets.example.com"),
-      requestInit: {},
-      fetch: fetchMock as typeof fetch,
-    });
-
-    await expect(client.request("list", {})).rejects.toMatchObject({
-      code: "CONFIG_NOT_FOUND",
-      message: "Remote config missing",
-    } satisfies Partial<CapletsError>);
-  });
-
-  it("uses safe auth and availability errors without leaking headers", async () => {
-    const fetchMock = vi.fn(async () => new Response("Unauthorized", { status: 401 }));
-    const client = new RemoteControlClient({
-      baseUrl: new URL("https://caplets.example.com/caplets"),
-      requestInit: { headers: { Authorization: "Basic secret" } },
-      fetch: fetchMock as typeof fetch,
-    });
-
-    await expect(client.request("list", {})).rejects.toMatchObject({
-      code: "AUTH_FAILED",
-      message: expect.stringContaining("Remote Caplets control authentication failed"),
-    } satisfies Partial<CapletsError>);
-    await expect(client.request("list", {})).rejects.not.toThrow(/secret/u);
-  });
-});
-```
-
-- [ ] **Step 2: Run remote control client tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/remote-control-client.test.ts
-```
-
-Expected: FAIL with module-not-found for `../src/remote-control/client`.
-
-- [ ] **Step 3: Add remote control types**
-
-Create `packages/core/src/remote-control/types.ts`:
-
-```ts
-export type RemoteCliCommand =
-  | "list"
-  | "get_caplet"
-  | "check_backend"
-  | "list_tools"
-  | "search_tools"
-  | "get_tool"
-  | "call_tool"
-  | "init"
-  | "add"
-  | "install"
-  | "auth_login_start"
-  | "auth_login_complete"
-  | "auth_logout"
-  | "auth_list";
-
-export type RemoteCliRequest = {
-  command: RemoteCliCommand;
-  arguments: Record<string, unknown>;
-};
-
-export type RemoteCliResponse =
-  | { ok: true; result: unknown; warnings?: string[] }
-  | {
-      ok: false;
-      error: { code: string; message: string; nextAction?: string };
-      warnings?: string[];
-    };
-```
-
-- [ ] **Step 4: Add remote control client**
-
-Create `packages/core/src/remote-control/client.ts`:
-
-```ts
-import { CapletsError, toSafeError } from "../errors";
-import { controlUrlForBase } from "../server/options";
-import type { RemoteCliCommand, RemoteCliRequest, RemoteCliResponse } from "./types";
-
-export type RemoteControlClientOptions = {
-  baseUrl: URL;
-  requestInit: RequestInit;
-  fetch?: typeof fetch;
-};
-
-export class RemoteControlClient {
-  private readonly fetchImpl: typeof fetch;
-
-  constructor(private readonly options: RemoteControlClientOptions) {
-    this.fetchImpl = options.fetch ?? fetch;
-  }
-
-  async request(command: RemoteCliCommand, args: Record<string, unknown>): Promise<unknown> {
-    const body: RemoteCliRequest = { command, arguments: args };
-    let response: Response;
-    try {
-      response = await this.fetchImpl(controlUrlForBase(this.options.baseUrl), {
-        ...this.options.requestInit,
-        method: "POST",
-        headers: {
-          ...headersObject(this.options.requestInit.headers),
-          "content-type": "application/json",
-        },
-        body: JSON.stringify(body),
-      });
-    } catch (error) {
-      throw new CapletsError(
-        "SERVER_UNAVAILABLE",
-        `Remote Caplets server unavailable at ${safeBaseUrl(this.options.baseUrl)}.`,
-        toSafeError(error),
-      );
-    }
-
-    if (response.status === 401 || response.status === 403) {
-      throw new CapletsError(
-        "AUTH_FAILED",
-        "Remote Caplets control authentication failed; check CAPLETS_SERVER_USER and CAPLETS_SERVER_PASSWORD.",
-      );
-    }
-    if (!response.ok) {
-      throw new CapletsError(
-        "SERVER_UNAVAILABLE",
-        `Remote Caplets control request failed with HTTP ${response.status} at ${safeBaseUrl(this.options.baseUrl)}.`,
-      );
-    }
-
-    const payload = (await response.json()) as RemoteCliResponse;
-    if (!payload.ok) {
-      throw new CapletsError(payload.error.code, payload.error.message, {
-        ...(payload.error.nextAction ? { nextAction: payload.error.nextAction } : {}),
-      });
-    }
-    return payload.result;
-  }
-}
-
-function headersObject(headers: RequestInit["headers"]): Record<string, string> {
-  if (!headers) return {};
-  if (headers instanceof Headers) return Object.fromEntries(headers.entries());
-  if (Array.isArray(headers)) return Object.fromEntries(headers);
-  return headers as Record<string, string>;
-}
-
-function safeBaseUrl(baseUrl: URL): string {
-  const safe = new URL(baseUrl.toString());
-  safe.username = "";
-  safe.password = "";
-  safe.search = "";
-  safe.hash = "";
-  return safe.toString();
-}
-```
-
-- [ ] **Step 5: Run remote control client tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/remote-control-client.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit remote control client**
-
-Run:
-
-```sh
-git add packages/core/src/remote-control/types.ts packages/core/src/remote-control/client.ts packages/core/test/remote-control-client.test.ts
-git commit -m "feat(cli): add remote control client"
-```
-
----
-
-## Task 5: Add control endpoint dispatch for read, execute, and mutation commands
-
-**Files:**
-
-- Create: `packages/core/src/remote-control/dispatch.ts`
-- Modify: `packages/core/src/serve/http.ts`
-- Test: `packages/core/test/remote-control-dispatch.test.ts`
-- Test: `packages/core/test/serve-http.test.ts`
-
-- [ ] **Step 1: Write failing dispatch tests**
-
-Create `packages/core/test/remote-control-dispatch.test.ts` with read and mutation coverage:
-
-```ts
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { dispatchRemoteCliRequest } from "../src/remote-control/dispatch";
-
-const dirs: string[] = [];
-
-afterEach(() => {
-  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
-});
-
-describe("dispatchRemoteCliRequest", () => {
-  it("lists remote server Caplets from server-side config", async () => {
-    const fixture = remoteFixture();
-
-    const result = await dispatchRemoteCliRequest(
-      { command: "list", arguments: { includeDisabled: false } },
-      fixture.context,
-    );
-
-    expect(result).toEqual({
-      ok: true,
-      result: [
-        expect.objectContaining({
-          server: "status",
-          backend: "http",
-          source: "global-config",
-        }),
-      ],
-    });
-  });
-
-  it("executes direct Caplet operations through server-side engine", async () => {
-    const fixture = remoteFixture();
-
-    const result = await dispatchRemoteCliRequest(
-      {
-        command: "get_caplet",
-        arguments: { caplet: "status", request: { operation: "get_caplet" } },
-      },
-      fixture.context,
-    );
-
-    expect(result.ok).toBe(true);
-    expect(JSON.stringify(result)).toContain("Status API");
-  });
-
-  it("writes added Caplets to the server-side destination root", async () => {
-    const fixture = remoteFixture();
-
-    const result = await dispatchRemoteCliRequest(
-      {
-        command: "add",
-        arguments: {
-          kind: "mcp",
-          id: "remote-tools",
-          options: { url: "https://mcp.example.com/mcp", transport: "http" },
-        },
-      },
-      fixture.context,
-    );
-
-    expect(result).toEqual({
-      ok: true,
-      result: expect.objectContaining({
-        remote: true,
-        label: "MCP",
-        path: expect.any(String),
-      }),
-    });
-    expect(existsSync(join(fixture.projectRoot, ".caplets", "remote-tools.md"))).toBe(true);
-    expect(
-      readFileSync(join(fixture.projectRoot, ".caplets", "remote-tools.md"), "utf8"),
-    ).toContain("mcpServer:");
-  });
-});
-
-function remoteFixture() {
-  const dir = mkdtempSync(join(tmpdir(), "caplets-remote-control-"));
-  dirs.push(dir);
-  const userRoot = join(dir, "user");
-  const projectRoot = join(dir, "project");
-  mkdirSync(userRoot, { recursive: true });
-  mkdirSync(join(projectRoot, ".caplets"), { recursive: true });
-  const configPath = join(userRoot, "config.json");
-  const projectConfigPath = join(projectRoot, ".caplets", "config.json");
-  writeFileSync(
-    configPath,
-    JSON.stringify({
-      httpApis: {
-        status: {
-          name: "Status API",
-          description: "Check status.",
-          baseUrl: "http://127.0.0.1:1",
-          auth: { type: "none" },
-          actions: { check: { method: "GET", path: "/check" } },
-        },
-      },
-    }),
-  );
-  writeFileSync(projectConfigPath, JSON.stringify({ mcpServers: {} }));
-  return {
-    projectRoot,
-    context: {
-      configPath,
-      projectConfigPath,
-      projectCapletsRoot: join(projectRoot, ".caplets"),
-      authDir: join(dir, "state", "auth"),
-      writeErr: () => {},
-    },
-  };
-}
-```
-
-- [ ] **Step 2: Add HTTP control endpoint test**
-
-Add to `packages/core/test/serve-http.test.ts`:
-
-```ts
-it("requires Basic Auth on the control endpoint and dispatches requests", async () => {
-  const { engine } = testEngine();
-  const password = ["control", "password"].join("-");
-  const app = createHttpServeApp(
-    httpOptions({ auth: { enabled: true, user: "caplets", password } }),
-    engine,
-    { writeErr: () => {} },
-  );
-
-  expect((await app.request("http://127.0.0.1:5387/control", { method: "POST" })).status).toBe(401);
-
-  const response = await app.request("http://127.0.0.1:5387/control", {
-    method: "POST",
-    headers: {
-      authorization: `Basic ${Buffer.from(`caplets:${password}`).toString("base64")}`,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({
-      command: "list",
-      arguments: { includeDisabled: false },
-    }),
-  });
-
-  expect(response.status).toBe(200);
-  await expect(response.json()).resolves.toMatchObject({ ok: true });
-
-  await engine.close();
-});
-```
-
-- [ ] **Step 3: Run dispatch and HTTP tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/remote-control-dispatch.test.ts test/serve-http.test.ts
-```
-
-Expected: FAIL because `dispatchRemoteCliRequest` and `/control` do not exist.
-
-- [ ] **Step 4: Implement remote control dispatch**
-
-Create `packages/core/src/remote-control/dispatch.ts`:
-
-```ts
-import {
-  addCliCaplet,
-  addGraphqlCaplet,
-  addHttpCaplet,
-  addMcpCaplet,
-  addOpenApiCaplet,
-} from "../cli/add";
-import { initConfig } from "../cli/init";
-import { installCaplets } from "../cli/install";
-import { listCaplets } from "../cli/inspection";
-import { loadConfigWithSources } from "../config";
-import { CapletsEngine, type CapletsEngineOptions } from "../engine";
-import { toSafeError } from "../errors";
-import type { RemoteCliRequest, RemoteCliResponse } from "./types";
-
-export type RemoteControlDispatchContext = CapletsEngineOptions & {
-  projectCapletsRoot: string;
-};
-
-export async function dispatchRemoteCliRequest(
-  request: RemoteCliRequest,
-  context: RemoteControlDispatchContext,
-): Promise<RemoteCliResponse> {
-  try {
-    const result = await dispatchRemoteCliRequestUnsafe(request, context);
-    return { ok: true, result };
-  } catch (error) {
-    const safe = toSafeError(error, "INTERNAL_ERROR") as {
-      code?: string;
-      message?: string;
-      nextAction?: string;
-    };
-    return {
-      ok: false,
-      error: {
-        code: safe.code ?? "INTERNAL_ERROR",
-        message: safe.message ?? "Remote control command failed.",
-        ...(safe.nextAction ? { nextAction: safe.nextAction } : {}),
-      },
-    };
-  }
-}
-
-async function dispatchRemoteCliRequestUnsafe(
-  request: RemoteCliRequest,
-  context: RemoteControlDispatchContext,
-): Promise<unknown> {
-  switch (request.command) {
-    case "list":
-      return listCaplets(loadConfigWithSources(context.configPath, context.projectConfigPath), {
-        includeDisabled: Boolean(request.arguments.includeDisabled),
-      });
-    case "get_caplet":
-    case "check_backend":
-    case "list_tools":
-    case "search_tools":
-    case "get_tool":
-    case "call_tool":
-      return await executeRemoteCapletOperation(request, context);
-    case "init":
-      return {
-        remote: true,
-        path: initConfig({
-          path: context.configPath,
-          force: Boolean(request.arguments.force),
-        }),
-      };
-    case "add":
-      return dispatchAdd(request.arguments, context.projectCapletsRoot);
-    case "install":
-      return {
-        remote: true,
-        ...installCaplets(stringArg(request.arguments.repo, "repo"), {
-          capletIds: stringArrayArg(request.arguments.capletIds),
-          force: Boolean(request.arguments.force),
-          destinationRoot: context.projectCapletsRoot,
-        }),
-      };
-    default:
-      throw new Error(`Unsupported remote control command ${request.command}`);
-  }
-}
-
-async function executeRemoteCapletOperation(
-  request: RemoteCliRequest,
-  context: RemoteControlDispatchContext,
-): Promise<unknown> {
-  const engine = new CapletsEngine({ ...context, watch: false });
-  try {
-    return await engine.execute(
-      stringArg(request.arguments.caplet, "caplet"),
-      objectArg(request.arguments.request, "request"),
-    );
-  } finally {
-    await engine.close();
-  }
-}
-
-function dispatchAdd(args: Record<string, unknown>, destinationRoot: string): unknown {
-  const kind = stringArg(args.kind, "kind");
-  const id = stringArg(args.id, "id");
-  const options = objectArg(args.options, "options");
-  const common = { ...options, destinationRoot, print: false };
-  switch (kind) {
-    case "cli":
-      return { remote: true, label: "CLI", ...addCliCaplet(id, common) };
-    case "mcp":
-      return { remote: true, label: "MCP", ...addMcpCaplet(id, common) };
-    case "openapi":
-      return {
-        remote: true,
-        label: "OpenAPI",
-        ...addOpenApiCaplet(id, common),
-      };
-    case "graphql":
-      return {
-        remote: true,
-        label: "GraphQL",
-        ...addGraphqlCaplet(id, common),
-      };
-    case "http":
-      return { remote: true, label: "HTTP", ...addHttpCaplet(id, common) };
-    default:
-      throw new Error(`Unsupported add kind ${kind}`);
-  }
-}
-
-function stringArg(value: unknown, key: string): string {
-  if (typeof value !== "string" || value.length === 0)
-    throw new Error(`Expected string argument ${key}`);
-  return value;
-}
-
-function stringArrayArg(value: unknown): string[] | undefined {
-  if (value === undefined) return undefined;
-  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
-    throw new Error("Expected string array argument capletIds");
-  }
-  return value;
-}
-
-function objectArg(value: unknown, key: string): Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value))
-    throw new Error(`Expected object argument ${key}`);
-  return value as Record<string, unknown>;
-}
-```
-
-- [ ] **Step 5: Wire `/control` into HTTP app**
-
-Modify `packages/core/src/serve/http.ts`:
-
-```ts
-import { resolveProjectCapletsRoot } from "../config";
-import { dispatchRemoteCliRequest } from "../remote-control/dispatch";
-import type { RemoteCliRequest } from "../remote-control/types";
-```
-
-Add route after MCP route:
-
-```ts
-app.post(paths.control, basicAuth(options.auth), async (c) => {
-  const request = (await c.req.json()) as RemoteCliRequest;
-  const result = await dispatchRemoteCliRequest(request, {
-    ...engineOptionsFromEngine(engine),
-    projectCapletsRoot: resolveProjectCapletsRoot(),
-    writeErr,
-  });
-  return c.json(result, result.ok ? 200 : 200);
-});
-```
-
-To avoid reverse-engineering private `CapletsEngine` options, change `createHttpServeApp()` signature to accept an optional dispatch context:
-
-```ts
-type HttpServeIo = {
-  writeErr?: (value: string) => void;
-  control?: Omit<RemoteControlDispatchContext, "writeErr">;
-};
-```
-
-Then pass `io.control ?? { projectCapletsRoot: resolveProjectCapletsRoot() }` to dispatch with `writeErr` merged. In `serveHttp()`, pass the same `engineOptions` values into `control`:
-
-```ts
-const app = createHttpServeApp(options, engine, {
-  writeErr,
-  control: {
-    ...engineOptions,
-    projectCapletsRoot: resolveProjectCapletsRoot(),
-  },
-});
-```
-
-Update tests that need temp config to pass `control` options when creating the app.
-
-- [ ] **Step 6: Run dispatch and HTTP tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/remote-control-dispatch.test.ts test/serve-http.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit control endpoint dispatch**
-
-Run:
-
-```sh
-git add packages/core/src/remote-control/dispatch.ts packages/core/src/serve/http.ts packages/core/test/remote-control-dispatch.test.ts packages/core/test/serve-http.test.ts
-git commit -m "feat(serve): add remote CLI control endpoint"
-```
-
----
-
-## Task 6: Route read/execute CLI commands through remote control
-
-**Files:**
-
-- Modify: `packages/core/src/cli.ts`
-- Test: `packages/core/test/cli-remote.test.ts`
-
-- [ ] **Step 1: Write failing CLI remote tests for list and direct operations**
-
-Create `packages/core/test/cli-remote.test.ts`:
-
-```ts
-import { describe, expect, it, vi } from "vitest";
-import { runCli } from "../src/cli";
-
-describe("remote CLI routing", () => {
-  it("routes list through remote control when CAPLETS_MODE selects remote", async () => {
-    const out: string[] = [];
-    const fetchMock = vi.fn(
-      async () =>
-        new Response(
-          JSON.stringify({
-            ok: true,
-            result: [
-              {
-                server: "github",
-                backend: "mcp",
-                name: "GitHub",
-                description: "GitHub tools",
-                disabled: false,
-                status: "not_started",
-                source: "global-config",
-                path: "/srv/caplets/github.md",
-                shadows: [],
-              },
-            ],
-          }),
-          { status: 200, headers: { "content-type": "application/json" } },
-        ),
-    );
-
-    await runCli(["list", "--json"], {
-      env: {
-        CAPLETS_MODE: "remote",
-        CAPLETS_SERVER_URL: "http://127.0.0.1:5387/caplets",
-      },
-      fetch: fetchMock as typeof fetch,
-      writeOut: (value) => out.push(value),
-    });
-
-    expect(JSON.parse(out.join(""))[0]).toMatchObject({ server: "github" });
-    expect(fetchMock).toHaveBeenCalledWith(
-      new URL("http://127.0.0.1:5387/caplets/control"),
-      expect.objectContaining({
-        body: JSON.stringify({
-          command: "list",
-          arguments: { includeDisabled: false },
-        }),
-      }),
-    );
-  });
-
-  it("routes call-tool through remote control and preserves JSON formatting", async () => {
-    const out: string[] = [];
-    const fetchMock = vi.fn(
-      async () =>
-        new Response(
-          JSON.stringify({
-            ok: true,
-            result: { structuredContent: { json: { ok: true } } },
-          }),
-          { status: 200, headers: { "content-type": "application/json" } },
-        ),
-    );
-
-    await runCli(["call-tool", "github.search", "--args", '{"q":"caplets"}', "--format", "json"], {
-      env: {
-        CAPLETS_MODE: "remote",
-        CAPLETS_SERVER_URL: "http://127.0.0.1:5387",
-      },
-      fetch: fetchMock as typeof fetch,
-      writeOut: (value) => out.push(value),
-    });
-
-    expect(JSON.parse(out.join(""))).toEqual({
-      structuredContent: { json: { ok: true } },
-    });
-    expect(fetchMock).toHaveBeenCalledWith(
-      new URL("http://127.0.0.1:5387/control"),
-      expect.objectContaining({
-        body: JSON.stringify({
-          command: "call_tool",
-          arguments: {
-            caplet: "github",
-            request: {
-              operation: "call_tool",
-              tool: "search",
-              arguments: { q: "caplets" },
-            },
-          },
-        }),
-      }),
-    );
-  });
-
-  it("keeps local-only config paths local even when remote is configured", async () => {
-    const out: string[] = [];
-    const fetchMock = vi.fn();
-
-    await runCli(["config", "path"], {
-      env: {
-        CAPLETS_MODE: "remote",
-        CAPLETS_SERVER_URL: "http://127.0.0.1:5387",
-      },
-      fetch: fetchMock as unknown as typeof fetch,
-      writeOut: (value) => out.push(value),
-    });
-
-    expect(fetchMock).not.toHaveBeenCalled();
-    expect(out.join("")).toContain("config.json");
-  });
-});
-```
-
-- [ ] **Step 2: Run CLI remote tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-remote.test.ts
-```
-
-Expected: FAIL because `CliIO` has no `env` or `fetch`, and commands do not route remotely.
-
-- [ ] **Step 3: Add CLI IO seams and remote helpers**
-
-Modify `CliIO` in `packages/core/src/cli.ts`:
-
-```ts
-type CliIO = {
-  writeOut?: (value: string) => void;
-  writeErr?: (value: string) => void;
-  authDir?: string;
-  version?: string;
-  setExitCode?: (code: number) => void;
-  serve?: (options: ServeOptions) => Promise<void>;
-  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
-  fetch?: typeof fetch;
-};
-```
-
-Add imports:
-
-```ts
-import { RemoteControlClient } from "./remote-control/client";
-import type { RemoteCliCommand } from "./remote-control/types";
-import { resolveCapletsMode, resolveCapletsServer } from "./server/options";
-```
-
-Add helper:
-
-```ts
-function remoteClientForCli(io: CliIO): RemoteControlClient | undefined {
-  const env = io.env ?? process.env;
-  if (resolveCapletsMode({}, env).mode !== "remote") return undefined;
-  const server = resolveCapletsServer({ fetch: io.fetch }, env);
-  return new RemoteControlClient({
-    baseUrl: server.baseUrl,
-    requestInit: server.requestInit,
-    ...(server.fetch ? { fetch: server.fetch } : {}),
-  });
-}
-```
-
-Use `io.env` in `envConfigPath()` by changing it to accept env:
-
-```ts
-function envConfigPath(env: Record<string, string | undefined> = process.env): string | undefined {
-  return env.CAPLETS_CONFIG?.trim() || undefined;
-}
-```
-
-Replace calls to `envConfigPath()` inside `createProgram(io)` with `envConfigPath(io.env ?? process.env)`.
-
-- [ ] **Step 4: Route `list` remotely**
-
-In the `list` action, add:
-
-```ts
-const remote = remoteClientForCli(io);
-if (remote) {
-  const rows = await remote.request("list", {
-    includeDisabled: Boolean(options.all),
-  });
-  if (options.json || options.format === "json") {
-    writeOut(`${JSON.stringify(rows, null, 2)}\n`);
-    return;
-  }
-  writeOut(
-    formatCapletList(rows as Parameters<typeof formatCapletList>[0], options.format ?? "plain"),
-  );
-  return;
-}
-```
-
-Make the action async.
-
-- [ ] **Step 5: Route direct operation commands remotely**
-
-Modify `executeOperation()` to accept `remote?: RemoteControlClient`:
-
-```ts
-type ExecuteOperationIO = Required<Pick<CliIO, "writeOut" | "writeErr" | "setExitCode">> & {
-  authDir?: string | undefined;
-  format?: CliOutputFormat | undefined;
-  remote?: RemoteControlClient | undefined;
-};
-```
-
-At the start of `executeOperation()`:
-
-```ts
-const command = remoteCommandForOperation(request);
-if (io.remote && command) {
-  const result = await io.remote.request(command, { caplet, request });
-  const output = cliOutputForOperation(result, { ...request, caplet }, io.format ?? "markdown");
-  io.writeOut(typeof output === "string" ? `${output}\n` : `${JSON.stringify(output, null, 2)}\n`);
-  if (isPlainObject(result) && result.isError === true) io.setExitCode(1);
-  return;
-}
-```
-
-Add helper:
-
-```ts
-function remoteCommandForOperation(request: Record<string, unknown>): RemoteCliCommand | undefined {
-  switch (request.operation) {
-    case "get_caplet":
-    case "check_backend":
-    case "list_tools":
-    case "search_tools":
-    case "get_tool":
-    case "call_tool":
-      return request.operation;
-    default:
-      return undefined;
-  }
-}
-```
-
-When each command calls `executeOperation`, pass `remote: remoteClientForCli(io)`.
-
-- [ ] **Step 6: Run CLI remote tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-remote.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit remote read/execute CLI routing**
-
-Run:
-
-```sh
-git add packages/core/src/cli.ts packages/core/test/cli-remote.test.ts
-git commit -m "feat(cli): route read commands through remote control"
-```
-
----
-
-## Task 7: Route mutating CLI commands through remote control
-
-**Files:**
-
-- Modify: `packages/core/src/cli.ts`
-- Test: `packages/core/test/cli-remote.test.ts`
-
-- [ ] **Step 1: Add failing mutation routing tests**
-
-Append to `packages/core/test/cli-remote.test.ts`:
-
-```ts
-it("routes add mcp through remote control and labels the remote path", async () => {
-  const out: string[] = [];
-  const fetchMock = vi.fn(
-    async () =>
-      new Response(
-        JSON.stringify({
-          ok: true,
-          result: {
-            remote: true,
-            label: "MCP",
-            path: "/srv/caplets/.caplets/github.md",
-            text: "mcpServer:\n",
-          },
-        }),
-        { status: 200, headers: { "content-type": "application/json" } },
-      ),
-  );
-
-  await runCli(
-    ["add", "mcp", "github", "--url", "https://mcp.example.com/mcp", "--transport", "http"],
-    {
-      env: {
-        CAPLETS_MODE: "remote",
-        CAPLETS_SERVER_URL: "http://127.0.0.1:5387",
-      },
-      fetch: fetchMock as typeof fetch,
-      writeOut: (value) => out.push(value),
-    },
-  );
-
-  expect(out.join("")).toBe("Wrote remote MCP Caplet to /srv/caplets/.caplets/github.md\n");
-  expect(fetchMock).toHaveBeenCalledWith(
-    new URL("http://127.0.0.1:5387/control"),
-    expect.objectContaining({
-      body: JSON.stringify({
-        command: "add",
-        arguments: {
-          kind: "mcp",
-          id: "github",
-          options: {
-            url: "https://mcp.example.com/mcp",
-            transport: "http",
-            global: undefined,
-            print: undefined,
-            output: undefined,
-            force: undefined,
-          },
-        },
-      }),
-    }),
-  );
-});
-
-it("routes install through remote control", async () => {
-  const out: string[] = [];
-  const fetchMock = vi.fn(
-    async () =>
-      new Response(
-        JSON.stringify({
-          ok: true,
-          result: {
-            remote: true,
-            installed: [
-              {
-                id: "github",
-                destination: "/srv/caplets/.caplets/github",
-                source: "repo#caplets/github",
-                kind: "directory",
-              },
-            ],
-          },
-        }),
-        { status: 200, headers: { "content-type": "application/json" } },
-      ),
-  );
-
-  await runCli(["install", "spiritledsoftware/caplets", "github"], {
-    env: {
-      CAPLETS_MODE: "remote",
-      CAPLETS_SERVER_URL: "http://127.0.0.1:5387",
-    },
-    fetch: fetchMock as typeof fetch,
-    writeOut: (value) => out.push(value),
-  });
-
-  expect(out.join("")).toBe("Installed github to remote /srv/caplets/.caplets/github\n");
-});
-```
-
-- [ ] **Step 2: Run mutation routing tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-remote.test.ts
-```
-
-Expected: FAIL because mutating commands still call local helpers.
-
-- [ ] **Step 3: Add remote add result formatter**
-
-Modify `writeAddResult()` in `packages/core/src/cli.ts`:
-
-```ts
-function writeAddResult(
-  writeOut: (value: string) => void,
-  label: string,
-  result: { path?: string; text: string; remote?: boolean },
-): void {
-  if (result.path) {
-    writeOut(`Wrote ${result.remote ? "remote " : ""}${label} Caplet to ${result.path}\n`);
-    return;
-  }
-  writeOut(result.text);
-}
-```
-
-- [ ] **Step 4: Route add subcommands remotely**
-
-For each `add` subcommand action, compute `const remote = remoteClientForCli(io);` and, when present, call:
-
-```ts
-const result = (await remote.request("add", {
-  kind: "mcp",
-  id,
-  options,
-})) as { path?: string; text: string; remote?: boolean };
-writeAddResult(writeOut, "MCP", result);
-return;
-```
-
-Use `kind: "cli"`, `"openapi"`, `"graphql"`, and `"http"` for the other add subcommands. Do not pass `destinationRoot`; the server dispatch owns server-side destinations.
-
-- [ ] **Step 5: Route install remotely**
-
-In the `install` action, add remote branch before local `installCaplets()`:
-
-```ts
-const remote = remoteClientForCli(io);
-if (remote) {
-  const result = (await remote.request("install", {
-    repo,
-    capletIds,
-    force: Boolean(options.force),
-  })) as { installed: Array<{ id: string; destination: string }> };
-  for (const caplet of result.installed) {
-    writeOut(`Installed ${caplet.id} to remote ${caplet.destination}\n`);
-  }
-  return;
-}
-```
-
-- [ ] **Step 6: Route init remotely when remote mode is active**
-
-In the `init` action, add remote branch:
-
-```ts
-const remote = remoteClientForCli(io);
-if (remote) {
-  const result = (await remote.request("init", {
-    force: Boolean(options.force),
-  })) as {
-    path: string;
-    remote: true;
-  };
-  writeOut(`Created remote Caplets config at ${result.path}\n`);
-  return;
-}
-```
-
-- [ ] **Step 7: Run mutation routing tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-remote.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 8: Commit remote mutation routing**
-
-Run:
-
-```sh
-git add packages/core/src/cli.ts packages/core/test/cli-remote.test.ts
-git commit -m "feat(cli): route mutations through remote control"
-```
-
----
-
-## Task 8: Add remote auth list/logout and remote auth login flow
-
-**Files:**
-
-- Create: `packages/core/src/remote-control/auth-flow.ts`
-- Modify: `packages/core/src/remote-control/dispatch.ts`
-- Modify: `packages/core/src/serve/http.ts`
-- Modify: `packages/core/src/cli/auth.ts`
-- Modify: `packages/core/src/cli.ts`
-- Test: `packages/core/test/remote-control-dispatch.test.ts`
-- Test: `packages/core/test/cli-remote.test.ts`
-
-- [ ] **Step 1: Expose structured local auth helpers**
-
-Modify `packages/core/src/cli/auth.ts` to export result-producing helpers in addition to current printing wrappers:
-
-```ts
-export type AuthStatusRow = {
-  server: string;
-  status: "missing" | "expired" | "authenticated";
-  expiresAt?: string;
-  scope?: string;
-};
-
-export function listAuthRows(options: { authDir?: string; configPath?: string }): AuthStatusRow[] {
-  const config = loadConfig(options.configPath);
-  return authTargets(config)
-    .sort((left, right) => left.server.localeCompare(right.server))
-    .map((server) => {
-      const bundle = readTokenBundle(server.server, options.authDir);
-      const status = !bundle
-        ? "missing"
-        : isTokenBundleExpired(bundle)
-          ? "expired"
-          : "authenticated";
-      return {
-        server: server.server,
-        status,
-        ...(bundle?.expiresAt ? { expiresAt: bundle.expiresAt } : {}),
-        ...(bundle?.scope ? { scope: bundle.scope } : {}),
-      };
-    });
-}
-
-export function logoutAuthResult(
-  serverId: string,
-  options: { authDir?: string; configPath?: string },
-): { server: string; deleted: boolean } {
-  const target = findAuthTarget(serverId, loadConfig(options.configPath));
-  assertLoginTarget(target, serverId);
-  return {
-    server: serverId,
-    deleted: deleteTokenBundle(serverId, options.authDir),
-  };
-}
-```
-
-Change existing `listAuth()` and `logoutAuth()` to use these helpers and preserve exact current output.
-
-- [ ] **Step 2: Add failing remote auth tests**
-
-Append to `packages/core/test/remote-control-dispatch.test.ts`:
-
-```ts
-it("lists and logs out server-side auth credentials", async () => {
-  const fixture = remoteFixtureWithOAuth();
-  writeTokenBundle(
-    {
-      server: "remote",
-      accessToken: "secret-access-token",
-      expiresAt: "2999-01-01T00:00:00.000Z",
-    },
-    fixture.context.authDir,
-  );
-
-  const listed = await dispatchRemoteCliRequest(
-    { command: "auth_list", arguments: {} },
-    fixture.context,
-  );
-  expect(listed).toEqual({
-    ok: true,
-    result: [expect.objectContaining({ server: "remote", status: "authenticated" })],
-  });
-
-  const loggedOut = await dispatchRemoteCliRequest(
-    { command: "auth_logout", arguments: { server: "remote" } },
-    fixture.context,
-  );
-  expect(loggedOut).toEqual({
-    ok: true,
-    result: { server: "remote", deleted: true },
-  });
-});
-```
-
-Add helper config with an OAuth remote MCP server and import `writeTokenBundle`.
-
-Append to `packages/core/test/cli-remote.test.ts`:
-
-```ts
-it("routes auth list and logout through remote control", async () => {
-  const out: string[] = [];
-  const fetchMock = vi
-    .fn()
-    .mockResolvedValueOnce(
-      new Response(
-        JSON.stringify({
-          ok: true,
-          result: [{ server: "remote", status: "authenticated" }],
-        }),
-        {
-          status: 200,
-          headers: { "content-type": "application/json" },
-        },
-      ),
-    )
-    .mockResolvedValueOnce(
-      new Response(
-        JSON.stringify({
-          ok: true,
-          result: { server: "remote", deleted: true },
-        }),
-        {
-          status: 200,
-          headers: { "content-type": "application/json" },
-        },
-      ),
-    );
-
-  const io = {
-    env: {
-      CAPLETS_MODE: "remote",
-      CAPLETS_SERVER_URL: "http://127.0.0.1:5387",
-    },
-    fetch: fetchMock as typeof fetch,
-    writeOut: (value: string) => out.push(value),
-  };
-
-  await runCli(["auth", "list", "--json"], io);
-  await runCli(["auth", "logout", "remote"], io);
-
-  expect(JSON.parse(out[0]!)).toEqual([{ server: "remote", status: "authenticated" }]);
-  expect(out[1]).toBe("Deleted remote OAuth credentials for `remote`.\n");
-});
-```
-
-- [ ] **Step 3: Run remote auth tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/remote-control-dispatch.test.ts test/cli-remote.test.ts
-```
-
-Expected: FAIL because auth dispatch and CLI auth routing do not exist.
-
-- [ ] **Step 4: Implement auth list/logout dispatch**
-
-Modify `packages/core/src/remote-control/dispatch.ts` imports:
-
-```ts
-import { listAuthRows, logoutAuthResult } from "../cli/auth";
-```
-
-Add cases:
-
-```ts
-case "auth_list":
-  return listAuthRows({ configPath: context.configPath, authDir: context.authDir });
-case "auth_logout":
-  return logoutAuthResult(stringArg(request.arguments.server, "server"), {
-    configPath: context.configPath,
-    authDir: context.authDir,
-  });
-```
-
-- [ ] **Step 5: Implement CLI auth list/logout routing**
-
-In `packages/core/src/cli.ts`, route `auth list` remotely:
-
-```ts
-const remote = remoteClientForCli(io);
-if (remote) {
-  const rows = await remote.request("auth_list", {});
-  if (format === "json") {
-    writeOut(`${JSON.stringify(rows, null, 2)}\n`);
-    return;
-  }
-  writeOut(formatAuthRows(rows as AuthStatusRow[], format));
-  return;
-}
-```
-
-Extract current `listAuth` formatting into an exported helper or keep a small CLI-local formatter matching existing text.
-
-Route `auth logout` remotely:
-
-```ts
-const remote = remoteClientForCli(io);
-if (remote) {
-  const result = (await remote.request("auth_logout", {
-    server: serverId,
-  })) as {
-    deleted: boolean;
-  };
-  writeOut(
-    result.deleted
-      ? `Deleted remote OAuth credentials for \`${serverId}\`.\n`
-      : `No remote OAuth credentials found for \`${serverId}\`.\n`,
-  );
-  return;
-}
-```
-
-- [ ] **Step 6: Add remote auth login flow store**
-
-Create `packages/core/src/remote-control/auth-flow.ts`:
-
-```ts
-import { randomUUID } from "node:crypto";
-
-export type RemoteAuthFlow = {
-  id: string;
-  server: string;
-  authorizationUrl: string;
-  createdAt: number;
-  complete(callbackUrl: string): Promise<void>;
-};
-
-export class RemoteAuthFlowStore {
-  private readonly flows = new Map<string, RemoteAuthFlow>();
-
-  create(flow: Omit<RemoteAuthFlow, "id" | "createdAt">): RemoteAuthFlow {
-    const created: RemoteAuthFlow = {
-      id: randomUUID(),
-      createdAt: Date.now(),
-      ...flow,
-    };
-    this.flows.set(created.id, created);
-    return created;
-  }
-
-  get(id: string): RemoteAuthFlow | undefined {
-    return this.flows.get(id);
-  }
-
-  delete(id: string): void {
-    this.flows.delete(id);
-  }
-}
-```
-
-- [ ] **Step 7: Refactor OAuth start/complete for remote callbacks**
-
-Modify `packages/core/src/auth.ts` to add start/complete helpers that use an externally supplied redirect URI. Add these exports:
-
-```ts
-export type StartedOAuthFlow = {
-  authorizationUrl: string;
-  complete(callbackUrl: string): Promise<void>;
-};
-
-export async function startOAuthFlow(
-  server: CapletServerConfig,
-  options: {
-    redirectUri: string;
-    authDir?: string;
-    print?: (line: string) => void;
-  },
-): Promise<StartedOAuthFlow>;
-
-export async function startGenericOAuthFlow(
-  target: GenericAuthTarget,
-  options: {
-    redirectUri: string;
-    authDir?: string;
-    print?: (line: string) => void;
-  },
-): Promise<StartedOAuthFlow>;
-```
-
-For MCP OAuth, reuse `FileOAuthProvider` with `redirectUri`. Capture `redirectUrl` from `redirectToAuthorization`. Return `complete(callbackUrl)` that extracts `code` and `state`, validates state, calls `auth(provider, { serverUrl: server.url, authorizationCode: code, scope })`, and stores tokens through the existing provider.
-
-For generic OAuth, move the URL construction and token exchange code from `runGenericOAuthFlow()` into the new start helper. Return `complete(callbackUrl)` that extracts `code` and `state`, validates state, exchanges the authorization code against the token endpoint, and writes the token bundle through existing `writeTokenBundle()` logic.
-
-Then rewrite existing `runOAuthFlow()` and `runGenericOAuthFlow()` as wrappers that create the loopback callback, call the new start helper, open/print the returned authorization URL, wait for callback/manual input, call `complete()`, and preserve existing output behavior.
-
-- [ ] **Step 8: Implement auth login dispatch and HTTP callback**
-
-Add `authFlowStore?: RemoteAuthFlowStore` to `HttpServeIo` and create a default store inside `createHttpServeApp()`.
-
-In `dispatchRemoteCliRequestUnsafe()` add:
-
-```ts
-case "auth_login_start":
-  return await startRemoteAuthLogin(stringArg(request.arguments.server, "server"), context);
-case "auth_login_complete":
-  return await completeRemoteAuthLogin(
-    stringArg(request.arguments.flowId, "flowId"),
-    stringArg(request.arguments.callbackUrl, "callbackUrl"),
-    context,
-  );
-```
-
-The start result shape:
-
-```ts
-{
-  server: string;
-  flowId: string;
-  authorizationUrl: string;
-}
-```
-
-Add route in `packages/core/src/serve/http.ts`:
-
-```ts
-app.get(routePath(paths.control, "auth/callback/:flowId"), async (c) => {
-  const flowId = c.req.param("flowId");
-  const callbackUrl = c.req.url;
-  const result = await dispatchRemoteCliRequest(
-    { command: "auth_login_complete", arguments: { flowId, callbackUrl } },
-    controlContext,
-  );
-  return result.ok
-    ? c.text("Caplets authentication complete. You can return to your terminal.")
-    : c.text(result.error.message, 400);
-});
-```
-
-- [ ] **Step 9: Implement CLI remote auth login**
-
-In `auth login` action, remote branch:
-
-```ts
-const remote = remoteClientForCli(io);
-if (remote) {
-  const started = (await remote.request("auth_login_start", {
-    server: serverId,
-  })) as {
-    server: string;
-    flowId: string;
-    authorizationUrl: string;
-  };
-  writeOut(`Open this URL to authorize ${serverId}:\n${started.authorizationUrl}\n`);
-  if (options.open !== false) {
-    await openBrowser(started.authorizationUrl);
-  }
-  writeOut(`Authenticated \`${serverId}\`.\n`);
-  return;
-}
-```
-
-Reuse the existing browser-opening helper or extract one from `auth.ts`. For v1, the browser callback completes against the server route, so the CLI does not receive tokens.
-
-- [ ] **Step 10: Run auth-focused tests**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/auth.test.ts test/remote-control-dispatch.test.ts test/cli-remote.test.ts test/serve-http.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 11: Commit remote auth support**
-
-Run:
-
-```sh
-git add packages/core/src/auth.ts packages/core/src/cli/auth.ts packages/core/src/cli.ts packages/core/src/remote-control/auth-flow.ts packages/core/src/remote-control/dispatch.ts packages/core/src/serve/http.ts packages/core/test/remote-control-dispatch.test.ts packages/core/test/cli-remote.test.ts packages/core/test/serve-http.test.ts
-git commit -m "feat(cli): store remote auth credentials on server"
-```
-
----
-
-## Task 9: Add end-to-end remote CLI coverage
-
-**Files:**
-
-- Modify: `packages/core/test/cli-remote.test.ts`
-
-- [ ] **Step 1: Add in-process remote server CLI test**
-
-Append an integration-style test to `packages/core/test/cli-remote.test.ts`:
-
-```ts
-it("uses a remote in-process control app without mutating local config", async () => {
-  const remote = makeRemoteServerFixture();
-  const local = makeLocalClientFixture();
-  const out: string[] = [];
-
-  await runCli(["add", "mcp", "remote-tools", "--url", "https://mcp.example.com/mcp"], {
-    env: {
-      CAPLETS_MODE: "remote",
-      CAPLETS_SERVER_URL: "http://127.0.0.1:5387/caplets",
-      CAPLETS_CONFIG: local.configPath,
-    },
-    fetch: remote.app.fetch.bind(remote.app) as typeof fetch,
-    writeOut: (value) => out.push(value),
-  });
-
-  expect(existsSync(join(remote.projectRoot, ".caplets", "remote-tools.md"))).toBe(true);
-  expect(existsSync(join(local.projectRoot, ".caplets", "remote-tools.md"))).toBe(false);
-  expect(out.join("")).toContain("remote");
-
-  await remote.engine.close();
-});
-```
-
-Implement `makeRemoteServerFixture()` and `makeLocalClientFixture()` in the test file using the patterns from `serve-http.test.ts` and `cli.test.ts`.
-
-- [ ] **Step 2: Run end-to-end remote CLI test**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-remote.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Commit end-to-end coverage**
-
-Run:
-
-```sh
-git add packages/core/test/cli-remote.test.ts
-git commit -m "test(cli): cover remote control server routing"
-```
-
----
-
-## Task 10: Update documentation and release metadata
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `packages/cli/README.md`
-- Modify: `packages/opencode/README.md`
-- Modify: `packages/pi/README.md`
-- Create: `.changeset/remote-cli-control.md`
-
-- [ ] **Step 1: Update root and CLI README remote service docs**
-
-In `README.md` and `packages/cli/README.md`, replace old remote env examples with:
-
-```sh
-CAPLETS_MODE=remote \
-CAPLETS_SERVER_URL=https://caplets.example.com/caplets \
-CAPLETS_SERVER_USER=caplets \
-CAPLETS_SERVER_PASSWORD=... \
-caplets list
-```
-
-Document endpoints:
-
-```text
-CAPLETS_SERVER_URL=https://caplets.example.com/caplets
-MCP endpoint:      https://caplets.example.com/caplets/mcp
-Control endpoint:  https://caplets.example.com/caplets/control
-Health endpoint:   https://caplets.example.com/caplets/healthz
-```
-
-Document serving:
-
-```sh
-CAPLETS_SERVER_URL=http://127.0.0.1:5387/caplets \
-CAPLETS_SERVER_PASSWORD=... \
-caplets serve --transport http
-```
-
-State that `--path` is the service base path.
-
-- [ ] **Step 2: Update OpenCode and Pi READMEs**
-
-In `packages/opencode/README.md` and `packages/pi/README.md`, document:
-
-```sh
-CAPLETS_MODE=remote
-CAPLETS_SERVER_URL=https://caplets.example.com/caplets
-CAPLETS_SERVER_USER=caplets
-CAPLETS_SERVER_PASSWORD=...
-```
-
-Show explicit config shape:
-
-```json
-{
-  "mode": "remote",
-  "server": {
-    "url": "https://caplets.example.com/caplets",
-    "user": "caplets"
-  },
-  "remote": {
-    "pollIntervalMs": 30000
-  }
-}
-```
-
-- [ ] **Step 3: Add changeset**
-
-Create `.changeset/remote-cli-control.md`:
-
-```md
----
-"@caplets/core": minor
-"caplets": minor
-"@caplets/opencode": minor
-"@caplets/pi": minor
----
-
-Add unified Caplets server configuration and remote CLI control support. `caplets serve --transport http` now mounts a service base path with `/mcp`, `/control`, and `/healthz` subroutes, while CLI and native integrations can use `CAPLETS_MODE` plus `CAPLETS_SERVER_*` settings to operate against a remote Caplets service.
-```
-
-- [ ] **Step 4: Run docs format check**
-
-Run:
-
-```sh
-pnpm exec oxfmt --check README.md packages/cli/README.md packages/opencode/README.md packages/pi/README.md .changeset/remote-cli-control.md
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit docs and changeset**
-
-Run:
-
-```sh
-git add README.md packages/cli/README.md packages/opencode/README.md packages/pi/README.md .changeset/remote-cli-control.md
-git commit -m "docs: document remote CLI control mode"
-```
-
----
-
-## Task 11: Final verification
-
-**Files:**
-
-- No source files changed in this task unless verification finds defects.
-
-- [ ] **Step 1: Run LSP diagnostics**
-
-Run diagnostics before package commands:
-
-```text
-lsp_diagnostics packages/core/src
-lsp_diagnostics packages/opencode/src
-lsp_diagnostics packages/pi/src
-```
-
-Expected: no TypeScript errors.
-
-- [ ] **Step 2: Run focused test suites**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/server-options.test.ts test/serve-options.test.ts test/serve-http.test.ts test/remote-control-client.test.ts test/remote-control-dispatch.test.ts test/cli-remote.test.ts test/native-options.test.ts test/native-remote.test.ts test/auth.test.ts
-pnpm --filter @caplets/opencode test -- opencode.test.ts
-pnpm --filter @caplets/pi test -- pi.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Run package checks**
-
-Run:
-
-```sh
-pnpm format:check
-pnpm lint
-pnpm typecheck
-pnpm test
-pnpm schema:check
-pnpm build
-```
-
-Expected: PASS.
-
-- [ ] **Step 4: Run full verification gate**
-
-Run:
-
-```sh
-pnpm verify
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Inspect final git state**
-
-Run:
-
-```sh
-git status --short
-git log --oneline -12
-```
-
-Expected: only intentional tracked changes are present, and commits from this plan appear in history.
-
----
-
-## Self-review
-
-- Spec coverage: Tasks 1 and 2 cover unified environment and native/CLI mode selection. Task 3 covers base-path HTTP serving. Tasks 4 and 5 cover the structured `/control` API and command-semantic server dispatch. Tasks 6 and 7 cover remote CLI read, execute, and mutation routing. Task 8 covers server-owned downstream auth credentials and remote auth login/list/logout. Task 9 verifies remote server state changes without local mutation. Task 10 covers docs and release metadata. Task 11 covers verification.
-- Placeholder scan: The plan contains no placeholders, deferred requirements, or unspecified test commands.
-- Type consistency: `CapletsMode`, `CapletsServerInput`, `ResolvedCapletsServer`, `RemoteCliRequest`, `RemoteCliResponse`, `RemoteControlClient`, `RemoteControlDispatchContext`, and `RemoteAuthFlowStore` are introduced before later tasks consume them.
diff --git a/docs/plans/2026-05-21-cli-completions.md b/docs/plans/2026-05-21-cli-completions.md
deleted file mode 100644
index 9a4313d6..00000000
--- a/docs/plans/2026-05-21-cli-completions.md
+++ /dev/null
@@ -1,746 +0,0 @@
-# CLI Completions Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add Bash, Zsh, and Fish completion support to the `caplets` npm CLI with static command/option suggestions and safe config-aware Caplet ID suggestions.
-
-**Architecture:** Put completion script generation and completion resolution in a focused core module, then wire it into the existing Commander CLI through a public `completion` command and hidden `__complete` command. Remote mode uses the structured `/control` API with a `complete_cli` command so completion remains server-owned and never executes raw CLI strings remotely.
-
-**Tech Stack:** TypeScript, Commander, Vitest, Caplets remote control, pnpm 11.0.9.
-
----
-
-## Scope and constraints
-
-- Use `pnpm` only.
-- Implement completion support in `@caplets/core` because `packages/cli` delegates CLI behavior to core.
-- Support `bash`, `zsh`, and `fish`.
-- Do not add npm `postinstall` behavior.
-- Do not edit user shell startup files automatically.
-- Do not start downstream MCP servers, run OpenAPI/GraphQL/HTTP calls, or execute configured CLI tools while completing.
-- Keep completion failures quiet for `__complete`; explicit `completion <shell>` errors may fail clearly.
-- Remote mode must use command-semantic `/control`, not raw command strings.
-- Add a changeset because this is a user-facing CLI feature.
-
-## File structure
-
-- Create `packages/core/src/cli/completion.ts`
-  - Own supported shell names, static completion tables, shell script generation, and completion resolution.
-- Modify `packages/core/src/cli.ts`
-  - Add `completion <shell>` and hidden `__complete` commands.
-  - Route hidden completion to remote mode when applicable.
-- Modify `packages/core/src/remote-control/types.ts`
-  - Add `complete_cli` to `RemoteCliCommand`.
-- Modify `packages/core/src/remote-control/dispatch.ts`
-  - Dispatch `complete_cli` using server-owned config and the shared completion resolver.
-- Add `packages/core/test/cli-completion.test.ts`
-  - Test shell script emission and local resolver behavior.
-- Modify `packages/core/test/cli-remote.test.ts`
-  - Test remote-mode hidden completion routing.
-- Modify `packages/core/test/remote-control-dispatch.test.ts`
-  - Test server-side `complete_cli` dispatch.
-- Modify `README.md` and `packages/cli/README.md`
-  - Document completion installation snippets.
-- Add `.changeset/cli-completions.md`
-  - Release note for `caplets`; include `@caplets/core` if exported APIs are changed.
-
----
-
-### Task 1: Add completion resolver and script generator
-
-**Files:**
-
-- Create: `packages/core/src/cli/completion.ts`
-- Test: `packages/core/test/cli-completion.test.ts`
-
-- [ ] **Step 1: Write failing resolver and script tests**
-
-Create `packages/core/test/cli-completion.test.ts`:
-
-```ts
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { completeCliWords, completionScript } from "../src/cli/completion";
-
-const dirs: string[] = [];
-
-afterEach(() => {
-  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
-});
-
-describe("CLI completion scripts", () => {
-  it("emits Bash, Zsh, and Fish scripts that call caplets __complete", () => {
-    expect(completionScript("bash")).toContain("caplets __complete --shell bash");
-    expect(completionScript("bash")).toContain(
-      "complete -o default -F _caplets_completions caplets",
-    );
-
-    expect(completionScript("zsh")).toContain("#compdef caplets");
-    expect(completionScript("zsh")).toContain("caplets __complete --shell zsh");
-
-    expect(completionScript("fish")).toContain("complete -c caplets");
-    expect(completionScript("fish")).toContain("caplets __complete --shell fish");
-  });
-
-  it("rejects unknown shells for explicit script generation", () => {
-    expect(() => completionScript("powershell" as never)).toThrow(
-      expect.objectContaining({ code: "REQUEST_INVALID" }),
-    );
-  });
-});
-
-describe("CLI completion resolver", () => {
-  it("suggests top-level commands", () => {
-    expect(completeCliWords([""])).toEqual(
-      expect.arrayContaining(["add", "auth", "call-tool", "completion", "serve"]),
-    );
-  });
-
-  it("suggests nested static subcommands and enum values", () => {
-    expect(completeCliWords(["add", ""])).toEqual(["cli", "mcp", "openapi", "graphql", "http"]);
-    expect(completeCliWords(["completion", ""])).toEqual(["bash", "zsh", "fish"]);
-    expect(completeCliWords(["serve", "--transport", ""])).toEqual(["stdio", "http"]);
-    expect(completeCliWords(["call-tool", "github.search", "--format", ""])).toEqual([
-      "markdown",
-      "md",
-      "plain",
-      "json",
-    ]);
-  });
-
-  it("suggests enabled Caplet IDs from local config", () => {
-    const dir = mkdtempSync(join(tmpdir(), "caplets-completion-"));
-    dirs.push(dir);
-    const configPath = join(dir, "config.json");
-    mkdirSync(dirname(configPath), { recursive: true });
-    writeFileSync(
-      configPath,
-      JSON.stringify({
-        mcpServers: {
-          github: { name: "GitHub", description: "GitHub", command: "node" },
-          disabled: { name: "Disabled", description: "Disabled", command: "node", disabled: true },
-        },
-        cliTools: {
-          repo: { name: "Repo", description: "Repo", actions: {} },
-        },
-      }),
-    );
-
-    expect(completeCliWords(["get-caplet", ""], { configPath })).toEqual(["github", "repo"]);
-    expect(completeCliWords(["call-tool", "git"], { configPath })).toEqual(["github."]);
-    expect(completeCliWords(["auth", "login", ""], { configPath })).toEqual(["github", "repo"]);
-  });
-
-  it("returns no suggestions instead of throwing when config loading fails", () => {
-    expect(completeCliWords(["get-caplet", ""], { configPath: "/missing/config.json" })).toEqual(
-      [],
-    );
-  });
-});
-```
-
-- [ ] **Step 2: Run focused tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts
-```
-
-Expected: FAIL because `packages/core/src/cli/completion.ts` does not exist.
-
-- [ ] **Step 3: Implement completion module**
-
-Create `packages/core/src/cli/completion.ts`:
-
-```ts
-import { loadConfigWithSources } from "../config";
-import { CapletsError } from "../errors";
-import { listCaplets } from "./inspection";
-
-export const completionShells = ["bash", "zsh", "fish"] as const;
-export type CompletionShell = (typeof completionShells)[number];
-
-export type CompletionOptions = {
-  configPath?: string;
-  projectConfigPath?: string;
-};
-
-const topLevelCommands = [
-  "serve",
-  "init",
-  "list",
-  "install",
-  "add",
-  "get-caplet",
-  "check-backend",
-  "list-tools",
-  "search-tools",
-  "get-tool",
-  "call-tool",
-  "list-resources",
-  "search-resources",
-  "list-resource-templates",
-  "read-resource",
-  "list-prompts",
-  "search-prompts",
-  "get-prompt",
-  "complete",
-  "config",
-  "auth",
-  "completion",
-];
-
-const subcommands: Record<string, string[]> = {
-  add: ["cli", "mcp", "openapi", "graphql", "http"],
-  auth: ["login", "logout", "list"],
-  completion: ["bash", "zsh", "fish"],
-  config: ["path", "paths"],
-};
-
-const optionValueSuggestions: Record<string, Record<string, string[]>> = {
-  "*": {
-    "--format": ["markdown", "md", "plain", "json"],
-  },
-  serve: {
-    "--transport": ["stdio", "http"],
-  },
-  "add:mcp": {
-    "--transport": ["http", "sse"],
-  },
-  "add:cli": {
-    "--include": ["git", "gh", "package"],
-  },
-};
-
-const capletIdCommands = new Set([
-  "get-caplet",
-  "check-backend",
-  "list-tools",
-  "search-tools",
-  "list-resources",
-  "search-resources",
-  "list-resource-templates",
-  "read-resource",
-  "list-prompts",
-  "search-prompts",
-  "complete",
-]);
-
-const qualifiedTargetCommands = new Set(["get-tool", "call-tool", "get-prompt"]);
-
-export function completionScript(shell: CompletionShell): string {
-  switch (shell) {
-    case "bash":
-      return bashCompletionScript();
-    case "zsh":
-      return zshCompletionScript();
-    case "fish":
-      return fishCompletionScript();
-    default:
-      throw new CapletsError("REQUEST_INVALID", "completion shell must be bash, zsh, or fish");
-  }
-}
-
-export function completeCliWords(words: string[], options: CompletionOptions = {}): string[] {
-  try {
-    const normalized = words.length === 0 ? [""] : words;
-    const current = normalized.at(-1) ?? "";
-    const previous = normalized.at(-2);
-    const command = normalized[0] ?? "";
-    const subcommand = normalized[1] ?? "";
-
-    const optionValues = suggestionsForOptionValue(command, subcommand, previous);
-    if (optionValues) return prefixFilter(optionValues, current);
-
-    if (normalized.length === 1) return prefixFilter(topLevelCommands, current);
-
-    if (normalized.length === 2 && subcommands[command]) {
-      return prefixFilter(subcommands[command], current);
-    }
-
-    if (normalized.length === 2 && capletIdCommands.has(command)) {
-      return prefixFilter(configuredCapletIds(options), current);
-    }
-
-    if (normalized.length === 2 && qualifiedTargetCommands.has(command)) {
-      return prefixFilter(
-        configuredCapletIds(options).map((id) => `${id}.`),
-        current,
-      );
-    }
-
-    if (command === "auth" && ["login", "logout"].includes(subcommand) && normalized.length === 3) {
-      return prefixFilter(configuredCapletIds(options), current);
-    }
-
-    return [];
-  } catch {
-    return [];
-  }
-}
-
-function suggestionsForOptionValue(
-  command: string,
-  subcommand: string,
-  previous: string | undefined,
-): string[] | undefined {
-  if (!previous) return undefined;
-  return (
-    optionValueSuggestions[`${command}:${subcommand}`]?.[previous] ??
-    optionValueSuggestions[command]?.[previous] ??
-    optionValueSuggestions["*"]?.[previous]
-  );
-}
-
-function configuredCapletIds(options: CompletionOptions): string[] {
-  const loaded = loadConfigWithSources(options.configPath, options.projectConfigPath);
-  return listCaplets(loaded, { includeDisabled: false }).map((row) => row.server);
-}
-
-function prefixFilter(values: string[], prefix: string): string[] {
-  return values.filter((value) => value.startsWith(prefix));
-}
-
-function bashCompletionScript(): string {
-  return `# caplets bash completion
-_caplets_completions() {
-  local IFS=$'\\n'
-  COMPREPLY=( $(caplets __complete --shell bash -- "${COMP_WORDS[@]:1}") )
-}
-complete -o default -F _caplets_completions caplets
-`;
-}
-
-function zshCompletionScript(): string {
-  return `#compdef caplets
-_caplets() {
-  local -a suggestions
-  suggestions=("${(@f)$(caplets __complete --shell zsh -- "${words[@]:1}")}")
-  compadd -- $suggestions
-}
-_caplets "$@"
-`;
-}
-
-function fishCompletionScript(): string {
-  return `# caplets fish completion
-function __caplets_complete
-  set -l tokens (commandline -opc)
-  set -l current (commandline -ct)
-  caplets __complete --shell fish -- $tokens[2..-1] $current
-end
-complete -c caplets -f -a '(__caplets_complete)'
-`;
-}
-```
-
-- [ ] **Step 4: Run focused tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit resolver module**
-
-```sh
-git add packages/core/src/cli/completion.ts packages/core/test/cli-completion.test.ts
-git commit -m "feat(cli): add completion resolver"
-```
-
----
-
-### Task 2: Wire public and hidden CLI commands
-
-**Files:**
-
-- Modify: `packages/core/src/cli.ts`
-- Test: `packages/core/test/cli.test.ts`
-
-- [ ] **Step 1: Write failing CLI command tests**
-
-Add this `describe` block to `packages/core/test/cli.test.ts` before helper functions:
-
-```ts
-describe("cli completion commands", () => {
-  it("prints completion scripts", async () => {
-    const out: string[] = [];
-
-    await runCli(["completion", "bash"], { writeOut: (value) => out.push(value) });
-
-    expect(out.join("")).toContain("caplets __complete --shell bash");
-    expect(out.join("")).toContain("complete -o default -F _caplets_completions caplets");
-  });
-
-  it("runs the hidden completion endpoint", async () => {
-    const out: string[] = [];
-
-    await runCli(["__complete", "--shell", "bash", "--", "add", ""], {
-      writeOut: (value) => out.push(value),
-    });
-
-    expect(out.join("").split("\n").filter(Boolean)).toEqual([
-      "cli",
-      "mcp",
-      "openapi",
-      "graphql",
-      "http",
-    ]);
-  });
-
-  it("uses configured Caplet IDs in local completion", async () => {
-    const dir = mkdtempSync(join(tmpdir(), "caplets-cli-completion-"));
-    const configPath = join(dir, "config.json");
-    const out: string[] = [];
-    try {
-      writeInspectionConfig(configPath);
-      await runCli(["__complete", "--shell", "bash", "--", "get-caplet", ""], {
-        env: { CAPLETS_CONFIG: configPath },
-        writeOut: (value) => out.push(value),
-      });
-
-      expect(out.join("").split("\n").filter(Boolean)).toEqual(["catalog", "filesystem", "users"]);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-});
-```
-
-- [ ] **Step 2: Run focused tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli.test.ts
-```
-
-Expected: FAIL because `completion` and `__complete` commands are not registered.
-
-- [ ] **Step 3: Import completion helpers**
-
-Modify the imports near the top of `packages/core/src/cli.ts`:
-
-```ts
-import {
-  completeCliWords,
-  completionScript,
-  completionShells,
-  type CompletionShell,
-} from "./cli/completion";
-```
-
-- [ ] **Step 4: Register `completion` and `__complete` commands**
-
-Add these commands in `createProgram()` after the base `program` configuration and before `serve`:
-
-```ts
-program
-  .command("completion")
-  .description("Print a shell completion script.")
-  .argument("<shell>", "completion shell: bash, zsh, or fish")
-  .action((shell: string) => {
-    if (!completionShells.includes(shell as CompletionShell)) {
-      throw new CapletsError("REQUEST_INVALID", "completion shell must be bash, zsh, or fish");
-    }
-    writeOut(completionScript(shell as CompletionShell));
-  });
-
-program
-  .command("__complete")
-  .description("Internal shell completion endpoint.")
-  .hideHelp()
-  .option("--shell <shell>", "completion shell")
-  .allowUnknownOption(true)
-  .argument("[words...]", "words to complete")
-  .action(async (words: string[], options: { shell?: string }) => {
-    const shell = completionShells.includes(options.shell as CompletionShell)
-      ? (options.shell as CompletionShell)
-      : "bash";
-    const remote = remoteClientForCli(io);
-    const suggestions = remote
-      ? ((await remote.request("complete_cli", { shell, words })) as string[])
-      : completeCliWords(words, { configPath: currentConfigPath() });
-    if (suggestions.length > 0) writeOut(`${suggestions.join("\n")}\n`);
-  });
-```
-
-- [ ] **Step 5: Run focused tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit CLI wiring**
-
-```sh
-git add packages/core/src/cli.ts packages/core/test/cli.test.ts
-git commit -m "feat(cli): expose shell completion commands"
-```
-
----
-
-### Task 3: Add structured remote completion support
-
-**Files:**
-
-- Modify: `packages/core/src/remote-control/types.ts`
-- Modify: `packages/core/src/remote-control/dispatch.ts`
-- Test: `packages/core/test/remote-control-dispatch.test.ts`
-- Test: `packages/core/test/cli-remote.test.ts`
-
-- [ ] **Step 1: Write failing remote dispatch test**
-
-Add to `packages/core/test/remote-control-dispatch.test.ts`:
-
-```ts
-it("dispatches complete_cli using server-owned config", async () => {
-  const context = testContext();
-  writeFileSync(
-    context.configPath,
-    JSON.stringify({
-      mcpServers: {
-        github: { name: "GitHub", description: "GitHub", command: "node" },
-      },
-      httpApis: {
-        users: {
-          name: "Users",
-          description: "Users",
-          baseUrl: "https://api.example.com",
-          actions: {},
-        },
-      },
-    }),
-  );
-
-  const response = await dispatchRemoteCliRequest(
-    { command: "complete_cli", arguments: { shell: "bash", words: ["get-caplet", ""] } },
-    context,
-  );
-
-  expect(response).toEqual({ ok: true, result: ["github", "users"] });
-});
-```
-
-- [ ] **Step 2: Write failing remote CLI routing test**
-
-Add to `packages/core/test/cli-remote.test.ts` inside `describe("remote CLI routing", ...)`:
-
-```ts
-it("routes hidden completion through remote control in remote mode", async () => {
-  const requests: unknown[] = [];
-  const out: string[] = [];
-  const fetch = vi.fn(async (_url: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
-    requests.push(JSON.parse(String(init?.body ?? "{}")));
-    return Response.json({ ok: true, result: ["github", "linear"] });
-  });
-
-  await runCli(["__complete", "--shell", "bash", "--", "get-caplet", ""], {
-    env: {
-      CAPLETS_MODE: "remote",
-      CAPLETS_SERVER_URL: "http://127.0.0.1:5387/caplets",
-    },
-    fetch,
-    writeOut: (value) => out.push(value),
-  });
-
-  expect(requests).toEqual([
-    { command: "complete_cli", arguments: { shell: "bash", words: ["get-caplet", ""] } },
-  ]);
-  expect(out.join("")).toBe("github\nlinear\n");
-});
-```
-
-- [ ] **Step 3: Run focused tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/remote-control-dispatch.test.ts test/cli-remote.test.ts
-```
-
-Expected: FAIL because `complete_cli` is not a valid remote command.
-
-- [ ] **Step 4: Add remote command type**
-
-Modify `packages/core/src/remote-control/types.ts` by adding `"complete_cli"` to `RemoteCliCommand` after `"install"`:
-
-```ts
-  | "complete_cli"
-```
-
-- [ ] **Step 5: Dispatch remote completion**
-
-Modify `packages/core/src/remote-control/dispatch.ts` imports:
-
-```ts
-import { completeCliWords, completionShells, type CompletionShell } from "./../cli/completion";
-```
-
-Add this branch after the `install` branch and before auth branches:
-
-```ts
-if (request.command === "complete_cli") {
-  const shell = optionalString(request.arguments, "shell") ?? "bash";
-  if (!completionShells.includes(shell as CompletionShell)) return [];
-  return completeCliWords(optionalStringArray(request.arguments, "words") ?? [""], {
-    configPath: context.configPath,
-    projectConfigPath: context.projectConfigPath,
-  });
-}
-```
-
-- [ ] **Step 6: Run focused tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/remote-control-dispatch.test.ts test/cli-remote.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit remote support**
-
-```sh
-git add packages/core/src/remote-control/types.ts packages/core/src/remote-control/dispatch.ts packages/core/test/remote-control-dispatch.test.ts packages/core/test/cli-remote.test.ts
-git commit -m "feat(cli): route completions through remote control"
-```
-
----
-
-### Task 4: Document npm package installation flow
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `packages/cli/README.md`
-- Create: `.changeset/cli-completions.md`
-
-- [ ] **Step 1: Update README completion docs**
-
-Add this section after the direct CLI operation examples in `README.md`:
-
-````md
-### Shell completions
-
-The npm package ships shell completion generators for Bash, Zsh, and Fish. Installation is explicit: `npm install -g caplets` does not modify shell startup files or system completion directories.
-
-```sh
-# Bash
-mkdir -p ~/.local/share/bash-completion/completions
-caplets completion bash > ~/.local/share/bash-completion/completions/caplets
-
-# Zsh
-mkdir -p ~/.zsh/completions
-caplets completion zsh > ~/.zsh/completions/_caplets
-
-# Fish
-mkdir -p ~/.config/fish/completions
-caplets completion fish > ~/.config/fish/completions/caplets.fish
-```
-````
-
-Completions include command names, options, common enum values, and configured Caplet IDs. They do not probe downstream MCP servers, HTTP APIs, GraphQL endpoints, OpenAPI specs, or configured CLI tools during tab completion.
-
-- [ ] **Step 2: Ensure package README mirrors root README**
-
-Because `packages/cli` copies the root README in `prepack`, either let the root README flow through unchanged or add the same section to `packages/cli/README.md` if the file is currently committed separately.
-
-- [ ] **Step 3: Add changeset**
-
-Create `.changeset/cli-completions.md`:
-
-```md
----
-"caplets": minor
-"@caplets/core": minor
----
-
-Add Bash, Zsh, and Fish shell completion generation plus config-aware completion suggestions for the Caplets CLI.
-```
-
-- [ ] **Step 4: Run docs-sensitive checks**
-
-Run:
-
-```sh
-pnpm format:check
-pnpm --filter caplets test
-```
-
-Expected: both commands pass.
-
-- [ ] **Step 5: Commit docs and changeset**
-
-```sh
-git add README.md packages/cli/README.md .changeset/cli-completions.md
-git commit -m "docs(cli): document shell completions"
-```
-
----
-
-### Task 5: Full verification and final cleanup
-
-**Files:**
-
-- Verify all changed files.
-
-- [ ] **Step 1: Run full repository verification**
-
-Run:
-
-```sh
-pnpm verify
-```
-
-Expected: format, lint, typecheck, schema check, tests, benchmark check, and build all pass.
-
-- [ ] **Step 2: Inspect final diff**
-
-Run:
-
-```sh
-git status --short
-git diff --stat
-```
-
-Expected: only intended completion, docs, tests, and changeset files are modified.
-
-- [ ] **Step 3: Commit any verification fixes**
-
-If verification required fixes, commit them:
-
-```sh
-git add <fixed-files>
-git commit -m "fix(cli): polish shell completions"
-```
-
-- [ ] **Step 4: Push branch**
-
-Run:
-
-```sh
-git push -u origin feat/cli-completions
-```
-
-Expected: branch pushes successfully.
-
----
-
-## Self-review checklist
-
-- Spec coverage: covers public completion generation, hidden resolver, static suggestions, config-aware suggestions, remote mode, docs, and changeset.
-- Placeholder scan: no `TBD` or open implementation decisions remain.
-- Type consistency: plan uses `CompletionShell`, `completeCliWords`, `completionScript`, and `complete_cli` consistently across core CLI and remote control.
-- Risk check: plan explicitly avoids npm postinstall side effects and live downstream probing during completion.
diff --git a/docs/plans/2026-05-21-completion-discovery-refactor.md b/docs/plans/2026-05-21-completion-discovery-refactor.md
deleted file mode 100644
index 1ddec9df..00000000
--- a/docs/plans/2026-05-21-completion-discovery-refactor.md
+++ /dev/null
@@ -1,1309 +0,0 @@
-# Completion Discovery Refactor Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans or superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Replace duplicated CLI completion command lists with shared metadata and add cache-backed live downstream completions for qualified tools, prompts, resources, and resource templates.
-
-**Architecture:** A shared command metadata module feeds both Commander registration and completion resolution. A focused completion discovery layer loads config, consults a platform-native persistent cache, performs bounded live discovery through existing managers, and returns best-effort candidates while preserving remote/server state ownership. Completion cache entries store only secret-free candidate metadata keyed by backend/config fingerprints.
-
-**Tech Stack:** TypeScript, Commander, Zod config schema, Vitest, Node filesystem/path APIs, existing Caplets managers (`DownstreamManager`, `OpenApiManager`, `GraphQLManager`, `HttpActionManager`, `CliToolsManager`, `CapletSetManager`).
-
----
-
-## File structure
-
-- Create `packages/core/src/cli/commands.ts`
-  - Shared source of truth for top-level command names, hidden command names, subcommands, completion shells, option enum values, and command categories (`capletIdCommands`, `qualifiedToolCommands`, etc.).
-- Modify `packages/core/src/cli.ts`
-  - Use command metadata constants when registering Commander commands.
-  - Pass async completion options to `completeCliWords`.
-- Modify `packages/core/src/cli/completion.ts`
-  - Consume shared command metadata.
-  - Support async cache-backed discovery for qualified targets and option-context completions.
-- Create `packages/core/src/cli/completion-cache.ts`
-  - Platform-cache-backed JSON cache helpers, cache keying, TTL checks, negative-cache entries, pruning, and atomic writes.
-- Create `packages/core/src/cli/completion-discovery.ts`
-  - Discovery orchestration, config-defined candidates, live manager-backed discovery, timeout/budget handling, fallback behavior, and candidate formatting.
-- Modify `packages/core/src/config/paths.ts`
-  - Add platform-native cache base and completion cache directory helpers.
-- Modify `packages/core/src/config.ts`
-  - Add `CompletionConfig`, defaults, parsing, merge support, and schema descriptions.
-- Modify `packages/core/src/engine.ts`
-  - Add an engine method for server-owned completion discovery used by remote control.
-- Modify `packages/core/src/remote-control/dispatch.ts`
-  - Route `complete_cli` through the engine discovery path instead of the purely static resolver.
-- Modify `packages/core/test/cli-completion.test.ts`
-  - Expand static metadata sync, qualified target, cache, timeout, and config-defined completion coverage.
-- Modify `packages/core/test/config.test.ts` and/or `packages/core/test/config-paths.test.ts`
-  - Cover completion config defaults and platform cache paths.
-- Modify `packages/core/test/remote-control-dispatch.test.ts`
-  - Cover server-owned remote completion discovery and secret-free responses.
-- Modify `README.md`, `packages/cli/README.md`, `.changeset/cli-completions.md`, and `schemas/caplets-config.schema.json`.
-
----
-
-## Task 1: Move CLI command completion metadata into a shared module
-
-**Files:**
-
-- Create: `packages/core/src/cli/commands.ts`
-- Modify: `packages/core/src/cli/completion.ts`
-- Modify: `packages/core/src/cli.ts`
-- Test: `packages/core/test/cli-completion.test.ts`
-
-- [ ] **Step 1: Write the failing metadata sync test**
-
-Add this test to `packages/core/test/cli-completion.test.ts` if it is not already present:
-
-```ts
-it("keeps top-level command suggestions in sync with registered CLI commands", () => {
-  const registeredCommands = createProgram()
-    .commands.filter((command) => command.name() !== "__complete")
-    .map((command) => command.name())
-    .sort();
-
-  expect(completeCliWords([""]).toSorted()).toEqual(registeredCommands);
-});
-```
-
-- [ ] **Step 2: Run the test before refactor**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts
-```
-
-Expected: PASS today, but still backed by a duplicated list. The refactor must keep this green while removing the duplicate source.
-
-- [ ] **Step 3: Add shared command metadata**
-
-Create `packages/core/src/cli/commands.ts`:
-
-```ts
-export const completionShells = ["bash", "zsh", "fish", "powershell", "cmd"] as const;
-export type CompletionShell = (typeof completionShells)[number];
-
-export const cliCommands = {
-  completion: "completion",
-  completeHidden: "__complete",
-  serve: "serve",
-  init: "init",
-  list: "list",
-  install: "install",
-  add: "add",
-  getCaplet: "get-caplet",
-  checkBackend: "check-backend",
-  listTools: "list-tools",
-  searchTools: "search-tools",
-  getTool: "get-tool",
-  callTool: "call-tool",
-  listResources: "list-resources",
-  searchResources: "search-resources",
-  listResourceTemplates: "list-resource-templates",
-  readResource: "read-resource",
-  listPrompts: "list-prompts",
-  searchPrompts: "search-prompts",
-  getPrompt: "get-prompt",
-  complete: "complete",
-  config: "config",
-  auth: "auth",
-} as const;
-
-export const topLevelCommandNames = [
-  cliCommands.serve,
-  cliCommands.init,
-  cliCommands.list,
-  cliCommands.install,
-  cliCommands.add,
-  cliCommands.getCaplet,
-  cliCommands.checkBackend,
-  cliCommands.listTools,
-  cliCommands.searchTools,
-  cliCommands.getTool,
-  cliCommands.callTool,
-  cliCommands.listResources,
-  cliCommands.searchResources,
-  cliCommands.listResourceTemplates,
-  cliCommands.readResource,
-  cliCommands.listPrompts,
-  cliCommands.searchPrompts,
-  cliCommands.getPrompt,
-  cliCommands.complete,
-  cliCommands.config,
-  cliCommands.auth,
-  cliCommands.completion,
-] as const;
-
-export const cliSubcommands = {
-  [cliCommands.add]: ["cli", "mcp", "openapi", "graphql", "http"],
-  [cliCommands.auth]: ["login", "logout", "list"],
-  [cliCommands.completion]: [...completionShells],
-  [cliCommands.config]: ["path", "paths"],
-} as const satisfies Record<string, readonly string[]>;
-
-export const capletIdCommands = new Set<string>([
-  cliCommands.getCaplet,
-  cliCommands.checkBackend,
-  cliCommands.listTools,
-  cliCommands.searchTools,
-  cliCommands.listResources,
-  cliCommands.searchResources,
-  cliCommands.listResourceTemplates,
-  cliCommands.readResource,
-  cliCommands.listPrompts,
-  cliCommands.searchPrompts,
-  cliCommands.complete,
-]);
-
-export const qualifiedToolCommands = new Set<string>([cliCommands.getTool, cliCommands.callTool]);
-
-export const qualifiedPromptCommands = new Set<string>([cliCommands.getPrompt]);
-```
-
-- [ ] **Step 4: Update completion resolver imports**
-
-In `packages/core/src/cli/completion.ts`, remove the local `completionShells`, `CompletionShell`, `topLevelCommands`, `subcommands`, `capletIdCommands`, and `qualifiedTargetCommands` definitions. Import the shared metadata:
-
-```ts
-import {
-  capletIdCommands,
-  cliCommands,
-  cliSubcommands,
-  completionShells,
-  qualifiedPromptCommands,
-  qualifiedToolCommands,
-  topLevelCommandNames,
-  type CompletionShell,
-} from "./commands";
-
-export { completionShells, type CompletionShell } from "./commands";
-```
-
-Update resolver references:
-
-```ts
-if (normalized.length === 1) return prefixFilter(topLevelCommandNames, current);
-
-if (normalized.length === 2 && cliSubcommands[command]) {
-  return prefixFilter(cliSubcommands[command], current);
-}
-
-if (
-  normalized.length === 2 &&
-  (qualifiedToolCommands.has(command) || qualifiedPromptCommands.has(command))
-) {
-  return prefixFilter(
-    configuredCapletIds(options).map((id) => `${id}.`),
-    current,
-  );
-}
-
-if (
-  command === cliCommands.auth &&
-  ["login", "logout"].includes(subcommand) &&
-  normalized.length === 3
-) {
-  return prefixFilter(configuredCapletIds(options), current);
-}
-```
-
-- [ ] **Step 5: Update Commander registration to use metadata constants**
-
-In `packages/core/src/cli.ts`, import:
-
-```ts
-import { cliCommands } from "./cli/commands";
-```
-
-Replace each top-level `.command("...")` string with its metadata constant, for example:
-
-```ts
-program.command(cliCommands.completion);
-program.command(cliCommands.completeHidden, { hidden: true });
-program.command(cliCommands.serve);
-program.command(cliCommands.callTool);
-```
-
-For grouped commands:
-
-```ts
-const add = program.command(cliCommands.add).description("Add generated Caplet files.");
-const config = program.command(cliCommands.config).description("Inspect Caplets config locations.");
-const auth = program
-  .command(cliCommands.auth)
-  .description("Manage OAuth credentials for remote servers.");
-```
-
-- [ ] **Step 6: Verify metadata refactor**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts test/cli.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit metadata refactor**
-
-```sh
-git add packages/core/src/cli/commands.ts packages/core/src/cli/completion.ts packages/core/src/cli.ts packages/core/test/cli-completion.test.ts
-git commit -m "refactor(cli): share completion command metadata"
-```
-
----
-
-## Task 2: Add completion config defaults and platform cache paths
-
-**Files:**
-
-- Modify: `packages/core/src/config/paths.ts`
-- Modify: `packages/core/src/config.ts`
-- Test: `packages/core/test/config.test.ts`
-- Test: `packages/core/test/config-paths.test.ts` if present, otherwise add path tests to `packages/core/test/config.test.ts`
-- Generated: `schemas/caplets-config.schema.json`
-
-- [ ] **Step 1: Write failing config tests**
-
-Add assertions that parsing an otherwise minimal config includes completion defaults:
-
-```ts
-expect(config.options.completion).toEqual({
-  discoveryTimeoutMs: 750,
-  overallTimeoutMs: 1500,
-  cacheTtlMs: 300_000,
-  negativeCacheTtlMs: 30_000,
-});
-```
-
-Add an override test:
-
-```ts
-const config = parseConfig({
-  version: 1,
-  completion: {
-    discoveryTimeoutMs: 250,
-    overallTimeoutMs: 1000,
-    cacheTtlMs: 60_000,
-    negativeCacheTtlMs: 10_000,
-  },
-  mcpServers: {},
-});
-expect(config.options.completion.discoveryTimeoutMs).toBe(250);
-```
-
-Add path tests:
-
-```ts
-expect(defaultCacheBaseDir({ XDG_CACHE_HOME: "/tmp/cache" }, "/home/alice", "linux")).toBe(
-  "/tmp/cache",
-);
-expect(defaultCacheBaseDir({}, "/Users/alice", "darwin")).toBe("/Users/alice/Library/Caches");
-expect(
-  defaultCacheBaseDir(
-    { LOCALAPPDATA: "C:\\Users\\Alice\\AppData\\Local" },
-    "C:\\Users\\Alice",
-    "win32",
-  ),
-).toBe("C:\\Users\\Alice\\AppData\\Local");
-```
-
-- [ ] **Step 2: Run tests and verify failure**
-
-```sh
-pnpm --filter @caplets/core test -- test/config.test.ts
-```
-
-Expected: FAIL because `completion` config and cache path helpers do not exist yet.
-
-- [ ] **Step 3: Add path helpers**
-
-In `packages/core/src/config/paths.ts`, add:
-
-```ts
-export function defaultCacheBaseDir(
-  env: PathEnv = process.env,
-  home = homedir(),
-  platform: Platform = process.platform,
-): string {
-  if (platform === "win32") {
-    return env.LOCALAPPDATA && win32.isAbsolute(env.LOCALAPPDATA)
-      ? env.LOCALAPPDATA
-      : win32.join(home, "AppData", "Local");
-  }
-
-  if (platform === "darwin") {
-    return posix.join(home, "Library", "Caches");
-  }
-
-  return env.XDG_CACHE_HOME && posix.isAbsolute(env.XDG_CACHE_HOME)
-    ? env.XDG_CACHE_HOME
-    : posix.join(home, ".cache");
-}
-
-export function defaultCompletionCacheDir(
-  env: PathEnv = process.env,
-  home = homedir(),
-  platform: Platform = process.platform,
-): string {
-  const pathJoin = platform === "win32" ? win32.join : posix.join;
-  return pathJoin(defaultCacheBaseDir(env, home, platform), "caplets", "completions");
-}
-
-export const DEFAULT_COMPLETION_CACHE_DIR = defaultCompletionCacheDir();
-```
-
-Export `DEFAULT_COMPLETION_CACHE_DIR`, `defaultCacheBaseDir`, and `defaultCompletionCacheDir` from `packages/core/src/config.ts`.
-
-- [ ] **Step 4: Add completion config schema**
-
-In `packages/core/src/config.ts`, add:
-
-```ts
-export type CompletionConfig = {
-  discoveryTimeoutMs: number;
-  overallTimeoutMs: number;
-  cacheTtlMs: number;
-  negativeCacheTtlMs: number;
-};
-```
-
-Change `CapletsOptions`:
-
-```ts
-export type CapletsOptions = {
-  defaultSearchLimit: number;
-  maxSearchLimit: number;
-  completion: CompletionConfig;
-};
-```
-
-Add schema:
-
-```ts
-const completionConfigSchema = z
-  .object({
-    discoveryTimeoutMs: z.number().int().positive().default(750),
-    overallTimeoutMs: z.number().int().positive().default(1500),
-    cacheTtlMs: z.number().int().nonnegative().default(300_000),
-    negativeCacheTtlMs: z.number().int().nonnegative().default(30_000),
-  })
-  .strict()
-  .default({});
-```
-
-Add `completion: completionConfigSchema` to the top-level config object and return it in `parseConfig`:
-
-```ts
-options: {
-  defaultSearchLimit: parsed.data.defaultSearchLimit,
-  maxSearchLimit: parsed.data.maxSearchLimit,
-  completion: parsed.data.completion,
-},
-```
-
-- [ ] **Step 5: Generate config schema**
-
-Run:
-
-```sh
-pnpm schema:generate
-```
-
-Expected: `schemas/caplets-config.schema.json` changes to include `completion`.
-
-- [ ] **Step 6: Verify config changes**
-
-```sh
-pnpm --filter @caplets/core test -- test/config.test.ts
-pnpm schema:check
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit config changes**
-
-```sh
-git add packages/core/src/config.ts packages/core/src/config/paths.ts packages/core/test/config.test.ts schemas/caplets-config.schema.json
-git commit -m "feat(cli): configure completion discovery cache"
-```
-
----
-
-## Task 3: Implement secret-free persistent completion cache
-
-**Files:**
-
-- Create: `packages/core/src/cli/completion-cache.ts`
-- Test: `packages/core/test/cli-completion-cache.test.ts`
-
-- [ ] **Step 1: Write cache tests**
-
-Create `packages/core/test/cli-completion-cache.test.ts` with tests for fresh, stale, negative, and secret-free behavior:
-
-```ts
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import {
-  completionCacheKey,
-  readCompletionCacheEntry,
-  writeCompletionCacheEntry,
-} from "../src/cli/completion-cache";
-
-const dirs: string[] = [];
-
-afterEach(() => {
-  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
-});
-
-describe("completion cache", () => {
-  it("round-trips fresh positive entries", () => {
-    const dir = mkdtempSync(join(tmpdir(), "caplets-completion-cache-"));
-    dirs.push(dir);
-    const key = completionCacheKey({
-      server: "repo",
-      backend: "cli",
-      kind: "tools",
-      fingerprint: "abc",
-    });
-    writeCompletionCacheEntry(dir, key, {
-      status: "positive",
-      fetchedAt: 1000,
-      expiresAt: 2000,
-      candidates: [{ value: "repo.status" }],
-    });
-    expect(readCompletionCacheEntry(dir, key, 1500)).toEqual(
-      expect.objectContaining({ status: "positive", fresh: true }),
-    );
-  });
-
-  it("marks expired entries as stale instead of deleting usable candidates", () => {
-    const dir = mkdtempSync(join(tmpdir(), "caplets-completion-cache-"));
-    dirs.push(dir);
-    const key = completionCacheKey({
-      server: "repo",
-      backend: "cli",
-      kind: "tools",
-      fingerprint: "abc",
-    });
-    writeCompletionCacheEntry(dir, key, {
-      status: "positive",
-      fetchedAt: 1000,
-      expiresAt: 2000,
-      candidates: [{ value: "repo.status" }],
-    });
-    expect(readCompletionCacheEntry(dir, key, 2500)).toEqual(
-      expect.objectContaining({ status: "positive", fresh: false }),
-    );
-  });
-
-  it("stores negative entries without candidates", () => {
-    const dir = mkdtempSync(join(tmpdir(), "caplets-completion-cache-"));
-    dirs.push(dir);
-    const key = completionCacheKey({
-      server: "github",
-      backend: "mcp",
-      kind: "tools",
-      fingerprint: "abc",
-    });
-    writeCompletionCacheEntry(dir, key, {
-      status: "negative",
-      fetchedAt: 1000,
-      expiresAt: 2000,
-      reason: "auth_required",
-    });
-    expect(readCompletionCacheEntry(dir, key, 1500)).toEqual(
-      expect.objectContaining({ status: "negative", fresh: true, reason: "auth_required" }),
-    );
-  });
-});
-```
-
-- [ ] **Step 2: Run tests and verify failure**
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion-cache.test.ts
-```
-
-Expected: FAIL because cache module is missing.
-
-- [ ] **Step 3: Implement cache module**
-
-Create `packages/core/src/cli/completion-cache.ts`:
-
-```ts
-import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-
-export type CompletionDiscoveryKind = "tools" | "prompts" | "resources" | "resourceTemplates";
-
-export type CompletionCandidate = {
-  value: string;
-  label?: string | undefined;
-  description?: string | undefined;
-};
-
-export type CompletionCacheKeyInput = {
-  server: string;
-  backend: string;
-  kind: CompletionDiscoveryKind;
-  fingerprint: string;
-};
-
-export type CompletionCacheEntry =
-  | {
-      status: "positive";
-      fetchedAt: number;
-      expiresAt: number;
-      candidates: CompletionCandidate[];
-    }
-  | {
-      status: "negative";
-      fetchedAt: number;
-      expiresAt: number;
-      reason: "auth_required" | "timeout" | "unavailable" | "unsupported" | "error";
-    };
-
-export type ReadCompletionCacheEntry = CompletionCacheEntry & { fresh: boolean };
-
-export function completionCacheKey(input: CompletionCacheKeyInput): string {
-  return createHash("sha256").update(JSON.stringify(input)).digest("hex");
-}
-
-export function readCompletionCacheEntry(
-  cacheDir: string,
-  key: string,
-  now = Date.now(),
-): ReadCompletionCacheEntry | undefined {
-  try {
-    const parsed = JSON.parse(
-      readFileSync(cachePath(cacheDir, key), "utf8"),
-    ) as CompletionCacheEntry;
-    if (parsed.status === "positive" && Array.isArray(parsed.candidates)) {
-      return { ...parsed, fresh: now <= parsed.expiresAt };
-    }
-    if (parsed.status === "negative" && typeof parsed.reason === "string") {
-      return { ...parsed, fresh: now <= parsed.expiresAt };
-    }
-  } catch {
-    return undefined;
-  }
-  return undefined;
-}
-
-export function writeCompletionCacheEntry(
-  cacheDir: string,
-  key: string,
-  entry: CompletionCacheEntry,
-): void {
-  mkdirSync(cacheDir, { recursive: true });
-  const path = cachePath(cacheDir, key);
-  const tempPath = `${path}.${process.pid}.tmp`;
-  writeFileSync(tempPath, JSON.stringify(entry), { mode: 0o600 });
-  renameSync(tempPath, path);
-}
-
-function cachePath(cacheDir: string, key: string): string {
-  return join(cacheDir, `${key}.json`);
-}
-```
-
-- [ ] **Step 4: Verify cache tests**
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion-cache.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit cache module**
-
-```sh
-git add packages/core/src/cli/completion-cache.ts packages/core/test/cli-completion-cache.test.ts
-git commit -m "feat(cli): add persistent completion cache"
-```
-
----
-
-## Task 4: Add cache-backed completion discovery orchestration
-
-**Files:**
-
-- Create: `packages/core/src/cli/completion-discovery.ts`
-- Modify: `packages/core/src/cli/completion.ts`
-- Modify: `packages/core/src/engine.ts`
-- Test: `packages/core/test/cli-completion.test.ts`
-
-- [ ] **Step 1: Write failing qualified target tests**
-
-In `packages/core/test/cli-completion.test.ts`, add tests for config-defined qualified targets:
-
-```ts
-it("suggests config-defined tool names for qualified CLI and HTTP targets", async () => {
-  const { dir, configPath } = writeCompletionConfig({
-    cliTools: {
-      repo: {
-        name: "Repo",
-        description: "Run repository maintenance commands.",
-        actions: {
-          status: {
-            description: "Print repository status.",
-            command: process.execPath,
-            args: ["--version"],
-          },
-          build: {
-            description: "Build the repository.",
-            command: process.execPath,
-            args: ["--version"],
-          },
-        },
-      },
-    },
-    httpApis: {
-      status_api: {
-        name: "Status API",
-        description: "Check service status through HTTP actions.",
-        baseUrl: "https://api.example.com",
-        auth: { type: "none" },
-        actions: { check: { method: "GET", path: "/status" } },
-      },
-    },
-  });
-  dirs.push(dir);
-
-  await expect(completeCliWords(["call-tool", "repo."], { configPath })).resolves.toEqual([
-    "repo.status",
-    "repo.build",
-  ]);
-  await expect(completeCliWords(["get-tool", "status_api."], { configPath })).resolves.toEqual([
-    "status_api.check",
-  ]);
-});
-```
-
-Update existing synchronous `completeCliWords(...)` tests to `await completeCliWords(...)` if the resolver becomes async.
-
-- [ ] **Step 2: Run tests and verify failure**
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts
-```
-
-Expected: FAIL because `completeCliWords` does not yet return qualified tool names.
-
-- [ ] **Step 3: Implement discovery function signatures**
-
-Create `packages/core/src/cli/completion-discovery.ts` with public entry points:
-
-```ts
-import type { CapletConfig, CapletsConfig, CompletionConfig } from "../config";
-import type { CompletionDiscoveryKind, CompletionCandidate } from "./completion-cache";
-
-export type CompletionDiscoveryManagers = {
-  listTools?: (server: CapletConfig) => Promise<Array<{ name: string; description?: string }>>;
-  listPrompts?: (server: CapletConfig) => Promise<Array<{ name: string; description?: string }>>;
-  listResources?: (
-    server: CapletConfig,
-  ) => Promise<Array<{ uri: string; name?: string; description?: string }>>;
-  listResourceTemplates?: (
-    server: CapletConfig,
-  ) => Promise<Array<{ uriTemplate: string; name?: string; description?: string }>>;
-};
-
-export type CompletionDiscoveryOptions = {
-  config: CapletsConfig;
-  cacheDir?: string | undefined;
-  managers?: CompletionDiscoveryManagers | undefined;
-  now?: number | undefined;
-};
-
-export async function discoverCompletionCandidates(
-  serverId: string,
-  kind: CompletionDiscoveryKind,
-  options: CompletionDiscoveryOptions,
-): Promise<CompletionCandidate[]> {
-  // Implement in later steps.
-  return configDefinedCandidates(serverId, kind, options.config);
-}
-```
-
-- [ ] **Step 4: Add config-defined candidates**
-
-Implement `configDefinedCandidates`:
-
-```ts
-function configDefinedCandidates(
-  serverId: string,
-  kind: CompletionDiscoveryKind,
-  config: CapletsConfig,
-): CompletionCandidate[] {
-  if (kind !== "tools") return [];
-  const cli = config.cliTools[serverId];
-  if (cli && !cli.disabled) {
-    return Object.keys(cli.actions).map((name) => ({ value: `${serverId}.${name}` }));
-  }
-  const http = config.httpApis[serverId];
-  if (http && !http.disabled) {
-    return Object.keys(http.actions).map((name) => ({ value: `${serverId}.${name}` }));
-  }
-  const graphql = config.graphqlEndpoints[serverId];
-  if (graphql && !graphql.disabled && graphql.operations) {
-    return Object.keys(graphql.operations).map((name) => ({ value: `${serverId}.${name}` }));
-  }
-  return [];
-}
-```
-
-- [ ] **Step 5: Wire async resolver for qualified tool/prompt contexts**
-
-In `packages/core/src/cli/completion.ts`, change:
-
-```ts
-export async function completeCliWords(words: string[], options: CompletionOptions = {}): Promise<string[]> {
-```
-
-When context is `call-tool` or `get-tool` and the current token contains a dot, split the server prefix and call `discoverCompletionCandidates(serverId, "tools", ...)`. Filter returned values by full prefix.
-
-When context is `get-prompt` and the current token contains a dot, call `discoverCompletionCandidates(serverId, "prompts", ...)`.
-
-For existing top-level/static cases, return immediately as before. Update CLI call sites to `await completeCliWords(...)`.
-
-- [ ] **Step 6: Add engine-owned discovery manager wiring**
-
-In `packages/core/src/engine.ts`, add:
-
-```ts
-async completeCliWords(words: string[]): Promise<string[]> {
-  const { completeCliWords } = await import("./cli/completion");
-  return await completeCliWords(words, {
-    config: this.registry.config,
-    managers: {
-      listTools: async (server) => {
-        const result = await handleServerTool(
-          server,
-          { operation: "list_tools" },
-          this.registry,
-          this.downstream,
-          this.openapi,
-          this.graphql,
-          this.http,
-          this.cli,
-          this.capletSets,
-        );
-        return result?.structuredContent?.result?.tools?.map((tool: { tool: string; description?: string }) => ({
-          name: tool.tool,
-          description: tool.description,
-        })) ?? [];
-      },
-      listPrompts: async (server) => {
-        if (server.backend !== "mcp") return [];
-        return (await this.downstream.listPrompts(server)).map((prompt) => ({
-          name: prompt.name,
-          description: prompt.description,
-        }));
-      },
-      listResources: async (server) => {
-        if (server.backend !== "mcp") return [];
-        return (await this.downstream.listResources(server)).map((resource) => ({
-          uri: resource.uri,
-          name: resource.name,
-          description: resource.description,
-        }));
-      },
-      listResourceTemplates: async (server) => {
-        if (server.backend !== "mcp") return [];
-        return (await this.downstream.listResourceTemplates(server)).map((template) => ({
-          uriTemplate: template.uriTemplate,
-          name: template.name,
-          description: template.description,
-        }));
-      },
-    },
-  });
-}
-```
-
-During implementation, prefer direct manager calls over parsing `handleServerTool` results where practical; the snippet above documents the shape and fallback behavior.
-
-- [ ] **Step 7: Verify qualified config-defined completion**
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts test/cli.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 8: Commit discovery orchestration base**
-
-```sh
-git add packages/core/src/cli/completion.ts packages/core/src/cli/completion-discovery.ts packages/core/src/engine.ts packages/core/test/cli-completion.test.ts packages/core/test/cli.test.ts
-git commit -m "feat(cli): complete qualified configured targets"
-```
-
----
-
-## Task 5: Add live discovery, persistent cache, and timeout behavior
-
-**Files:**
-
-- Modify: `packages/core/src/cli/completion-discovery.ts`
-- Modify: `packages/core/src/cli/completion.ts`
-- Test: `packages/core/test/cli-completion.test.ts`
-- Test: `packages/core/test/cli-completion-cache.test.ts`
-
-- [ ] **Step 1: Write tests for cache-first and timeout fallback**
-
-Add tests that pass fake managers:
-
-```ts
-it("uses cached discovered tool names when live discovery times out", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "caplets-completion-cache-"));
-  dirs.push(dir);
-  const { configPath } = writeMcpConfig(dir, "github");
-
-  await completeCliWords(["call-tool", "github."], {
-    configPath,
-    cacheDir: dir,
-    managers: {
-      listTools: async () => [{ name: "search" }],
-    },
-  });
-
-  await expect(
-    completeCliWords(["call-tool", "github."], {
-      configPath,
-      cacheDir: dir,
-      managers: {
-        listTools: async () => await new Promise(() => {}),
-      },
-      completion: {
-        discoveryTimeoutMs: 10,
-        overallTimeoutMs: 20,
-        cacheTtlMs: 0,
-        negativeCacheTtlMs: 30_000,
-      },
-    }),
-  ).resolves.toEqual(["github.search"]);
-});
-```
-
-Add a negative-cache test that verifies a failing manager is not called again until TTL expiry.
-
-- [ ] **Step 2: Run tests and verify failure**
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts test/cli-completion-cache.test.ts
-```
-
-Expected: FAIL until discovery cache is wired.
-
-- [ ] **Step 3: Implement fingerprints**
-
-In `completion-discovery.ts`, implement a secret-free fingerprint function:
-
-```ts
-function completionFingerprint(
-  server: CapletConfig,
-  kind: CompletionDiscoveryKind,
-  completion: CompletionConfig,
-): string {
-  return JSON.stringify({
-    kind,
-    completion: {
-      discoveryTimeoutMs: completion.discoveryTimeoutMs,
-      cacheTtlMs: completion.cacheTtlMs,
-      negativeCacheTtlMs: completion.negativeCacheTtlMs,
-    },
-    server: secretFreeServerShape(server),
-  });
-}
-```
-
-`secretFreeServerShape` must include only the fields listed in the spec and must not include env values, auth token/header values, or response data.
-
-- [ ] **Step 4: Implement timeout helper**
-
-Add:
-
-```ts
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
-  let timeout: NodeJS.Timeout | undefined;
-  try {
-    return await Promise.race([
-      promise,
-      new Promise<T>((_, reject) => {
-        timeout = setTimeout(() => reject(new Error("completion discovery timeout")), timeoutMs);
-      }),
-    ]);
-  } finally {
-    if (timeout) clearTimeout(timeout);
-  }
-}
-```
-
-- [ ] **Step 5: Implement cache-backed discovery flow**
-
-In `discoverCompletionCandidates`:
-
-1. Find enabled server by ID.
-2. Build cache key from server/backend/kind/fingerprint.
-3. Read cache entry.
-4. Return fresh positive cache immediately.
-5. Return static/config candidates immediately if fresh negative cache exists.
-6. Attempt live discovery with `Math.min(discoveryTimeoutMs, remainingOverallBudget)`.
-7. On success, write positive cache and return discovered candidates plus config-defined candidates, deduped.
-8. On failure/timeout, write negative cache and return stale positive candidates if available, otherwise config-defined candidates.
-
-- [ ] **Step 6: Implement live manager selection**
-
-Add:
-
-```ts
-async function liveCandidates(
-  server: CapletConfig,
-  kind: CompletionDiscoveryKind,
-  managers: CompletionDiscoveryManagers | undefined,
-): Promise<CompletionCandidate[]> {
-  if (kind === "tools" && managers?.listTools) {
-    return (await managers.listTools(server)).map((tool) => ({
-      value: `${server.server}.${tool.name}`,
-      description: tool.description,
-    }));
-  }
-  if (server.backend !== "mcp") return [];
-  if (kind === "prompts" && managers?.listPrompts) {
-    return (await managers.listPrompts(server)).map((prompt) => ({
-      value: `${server.server}.${prompt.name}`,
-      description: prompt.description,
-    }));
-  }
-  if (kind === "resources" && managers?.listResources) {
-    return (await managers.listResources(server)).map((resource) => ({
-      value: resource.uri,
-      label: resource.name,
-      description: resource.description,
-    }));
-  }
-  if (kind === "resourceTemplates" && managers?.listResourceTemplates) {
-    return (await managers.listResourceTemplates(server)).map((template) => ({
-      value: template.uriTemplate,
-      label: template.name,
-      description: template.description,
-    }));
-  }
-  return [];
-}
-```
-
-- [ ] **Step 7: Verify cache/live behavior**
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts test/cli-completion-cache.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 8: Commit cache-backed live discovery**
-
-```sh
-git add packages/core/src/cli/completion-discovery.ts packages/core/src/cli/completion.ts packages/core/test/cli-completion.test.ts packages/core/test/cli-completion-cache.test.ts
-git commit -m "feat(cli): cache live completion discovery"
-```
-
----
-
-## Task 6: Complete resources, templates, and `complete` option contexts
-
-**Files:**
-
-- Modify: `packages/core/src/cli/completion.ts`
-- Modify: `packages/core/src/cli/completion-discovery.ts`
-- Test: `packages/core/test/cli-completion.test.ts`
-
-- [ ] **Step 1: Write tests for MCP resource/prompt contexts**
-
-Add tests:
-
-```ts
-it("suggests resource URIs for read-resource after a selected backend", async () => {
-  const { dir, configPath } = writeMcpConfigWithDir("docs");
-  dirs.push(dir);
-  await expect(
-    completeCliWords(["read-resource", "docs", "file://"], {
-      configPath,
-      managers: { listResources: async () => [{ uri: "file:///repo/README.md" }] },
-    }),
-  ).resolves.toEqual(["file:///repo/README.md"]);
-});
-
-it("suggests prompt and resource-template option values for complete", async () => {
-  const { dir, configPath } = writeMcpConfigWithDir("docs");
-  dirs.push(dir);
-  await expect(
-    completeCliWords(["complete", "docs", "--prompt", ""], {
-      configPath,
-      managers: { listPrompts: async () => [{ name: "summarize" }] },
-    }),
-  ).resolves.toEqual(["summarize"]);
-  await expect(
-    completeCliWords(["complete", "docs", "--resource-template", "file://"], {
-      configPath,
-      managers: { listResourceTemplates: async () => [{ uriTemplate: "file:///repo/{path}" }] },
-    }),
-  ).resolves.toEqual(["file:///repo/{path}"]);
-});
-```
-
-- [ ] **Step 2: Run tests and verify failure**
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts
-```
-
-Expected: FAIL until option context support is implemented.
-
-- [ ] **Step 3: Implement read-resource positional completion**
-
-In `completeCliWords`:
-
-```ts
-if (command === cliCommands.readResource && normalized.length === 3) {
-  return prefixFilter(
-    (await discoverCompletionCandidates(subcommand, "resources", discoveryOptions(options))).map(
-      (candidate) => candidate.value,
-    ),
-    current,
-  );
-}
-```
-
-- [ ] **Step 4: Implement complete option context discovery**
-
-When `previous === "--prompt"` and `command === "complete"`, discover `prompts` for `normalized[1]`. When `previous === "--resource-template"`, discover `resourceTemplates` for `normalized[1]`.
-
-```ts
-if (command === cliCommands.complete && previous === "--prompt" && subcommand) {
-  return prefixFilter(
-    (await discoverCompletionCandidates(subcommand, "prompts", discoveryOptions(options))).map(
-      (candidate) => candidate.value.replace(`${subcommand}.`, ""),
-    ),
-    current,
-  );
-}
-```
-
-Resource-template values should be returned as raw URI templates, not `server.template` qualified names, because the CLI option accepts the URI template only.
-
-- [ ] **Step 5: Verify broader contexts**
-
-```sh
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit resource/template completion**
-
-```sh
-git add packages/core/src/cli/completion.ts packages/core/src/cli/completion-discovery.ts packages/core/test/cli-completion.test.ts
-git commit -m "feat(cli): complete MCP resources and prompts"
-```
-
----
-
-## Task 7: Route remote completions through server-owned discovery
-
-**Files:**
-
-- Modify: `packages/core/src/engine.ts`
-- Modify: `packages/core/src/remote-control/dispatch.ts`
-- Test: `packages/core/test/remote-control-dispatch.test.ts`
-- Test: `packages/core/test/cli-remote.test.ts`
-
-- [ ] **Step 1: Write failing remote discovery test**
-
-In `packages/core/test/remote-control-dispatch.test.ts`, add a context with CLI/HTTP config actions and assert `complete_cli` returns qualified tool names:
-
-```ts
-it("routes complete_cli through server-owned discovery", async () => {
-  const context = testContext();
-  const response = await dispatchRemoteCliRequest(
-    {
-      command: "complete_cli",
-      arguments: { shell: "bash", words: ["call-tool", "server_status."] },
-    },
-    context,
-  );
-  expect(response).toMatchObject({ ok: true });
-  expect(response.ok && response.result).toEqual(["server_status.check"]);
-});
-```
-
-- [ ] **Step 2: Run tests and verify failure**
-
-```sh
-pnpm --filter @caplets/core test -- test/remote-control-dispatch.test.ts test/cli-remote.test.ts
-```
-
-Expected: FAIL until `complete_cli` uses `CapletsEngine.completeCliWords`.
-
-- [ ] **Step 3: Update remote dispatch**
-
-In `packages/core/src/remote-control/dispatch.ts`, change the `complete_cli` branch:
-
-```ts
-if (request.command === "complete_cli") {
-  const shell = optionalString(request.arguments, "shell") ?? "bash";
-  if (!completionShells.includes(shell as CompletionShell)) return [];
-  const engine = new CapletsEngine(context);
-  try {
-    return await engine.completeCliWords(optionalStringArray(request.arguments, "words") ?? [""]);
-  } finally {
-    await engine.close();
-  }
-}
-```
-
-- [ ] **Step 4: Ensure remote client failures remain quiet**
-
-Keep the `try/catch` around `remote.request("complete_cli", ...)` in `cli.ts`. Confirm `packages/core/test/cli-remote.test.ts` still has the quiet-failure test.
-
-- [ ] **Step 5: Verify remote completion**
-
-```sh
-pnpm --filter @caplets/core test -- test/remote-control-dispatch.test.ts test/cli-remote.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit remote discovery routing**
-
-```sh
-git add packages/core/src/engine.ts packages/core/src/remote-control/dispatch.ts packages/core/test/remote-control-dispatch.test.ts packages/core/test/cli-remote.test.ts
-git commit -m "feat(cli): discover completions on remote server"
-```
-
----
-
-## Task 8: Update docs and changeset
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `packages/cli/README.md`
-- Modify: `.changeset/cli-completions.md`
-
-- [ ] **Step 1: Update README completion behavior notes**
-
-Add a paragraph after the existing shell completion install snippets:
-
-```md
-Completions include command names, options, common enum values, configured Caplet IDs, and cache-backed downstream names for qualified targets such as `caplets call-tool repo.<TAB>`. Downstream discovery is bounded by the `completion` config timeouts and a platform-native cache directory. Generated shell scripts suppress completion stderr; run the underlying CLI command directly when debugging completion behavior.
-```
-
-Add config example:
-
-```json
-{
-  "completion": {
-    "discoveryTimeoutMs": 750,
-    "overallTimeoutMs": 1500,
-    "cacheTtlMs": 300000,
-    "negativeCacheTtlMs": 30000
-  }
-}
-```
-
-Mention auth:
-
-```md
-Backends that require OAuth or token auth may need `caplets auth login <server>` before live downstream completions can return richer results. Completion never starts interactive login flows.
-```
-
-- [ ] **Step 2: Mirror package README**
-
-Apply the same README changes to `packages/cli/README.md` if it is committed independently.
-
-- [ ] **Step 3: Update changeset**
-
-Change `.changeset/cli-completions.md` body to:
-
-```md
-Add Bash, Zsh, Fish, PowerShell, and cmd shell completion generation plus config-aware and cache-backed downstream completion suggestions for the Caplets CLI.
-```
-
-- [ ] **Step 4: Verify docs formatting**
-
-```sh
-pnpm format:check
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit docs**
-
-```sh
-git add README.md packages/cli/README.md .changeset/cli-completions.md
-git commit -m "docs(cli): describe cache-backed completions"
-```
-
----
-
-## Task 9: Final verification and push
-
-**Files:**
-
-- All changed implementation, tests, docs, schema, and changeset files.
-
-- [ ] **Step 1: Run full verification**
-
-```sh
-pnpm verify
-```
-
-Expected:
-
-- format check passes
-- lint passes
-- typecheck passes
-- schema check passes
-- all Vitest tests pass
-- benchmark check passes
-- build passes
-
-- [ ] **Step 2: Inspect working tree**
-
-```sh
-git status --short
-git diff --stat
-```
-
-Expected: no unstaged implementation/doc changes. `.brv` may be modified by ByteRover; stage only if the existing hook/workflow requires it.
-
-- [ ] **Step 3: Push branch**
-
-```sh
-git push
-```
-
-Expected: `feat/cli-completions` is updated on PR #71.
-
-- [ ] **Step 4: Check PR status**
-
-```sh
-gh pr view 71 --json url,headRefOid,statusCheckRollup
-```
-
-Expected: PR points at the final pushed commit and CI has started or passed.
-
----
-
-## Self-review checklist
-
-- Spec coverage: shared metadata, platform cache path, config defaults, persistent cache, stale/negative cache behavior, qualified tool/prompt/resource/template completions, remote server ownership, docs, schema, and verification are all mapped to tasks.
-- Placeholder scan: no implementation step depends on `TODO` or unspecified behavior; every task has concrete files, commands, and expected results.
-- Type consistency: `CompletionShell`, `CompletionDiscoveryKind`, `CompletionCandidate`, `CompletionConfig`, `completeCliWords`, and `discoverCompletionCandidates` names are consistent across tasks.
diff --git a/docs/plans/2026-05-21-docker-self-hosting.md b/docs/plans/2026-05-21-docker-self-hosting.md
deleted file mode 100644
index cf6348d2..00000000
--- a/docs/plans/2026-05-21-docker-self-hosting.md
+++ /dev/null
@@ -1,474 +0,0 @@
-# Docker Self-Hosting Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add source-build Docker and Docker Compose support so Caplets can be self-hosted as an HTTP service with persistent server-owned state.
-
-**Architecture:** The implementation adds root container artifacts only: a multi-stage `Dockerfile`, a focused `.dockerignore`, and a `docker-compose.yml` service that runs `caplets serve --transport http`. Runtime state is persisted under `/data` via XDG environment variables, while Compose owns external bind address/port configuration and passes through unified `CAPLETS_SERVER_*` settings.
-
-**Tech Stack:** Docker, Docker Compose, Node.js 24 slim images, Corepack, `pnpm@11.0.9`, Caplets CLI HTTP serve mode.
-
----
-
-## File Structure
-
-- Create: `.dockerignore`
-  - Keeps Docker build contexts small and prevents local caches, VCS metadata, generated output, and secret-bearing local state from entering the image build context.
-- Create: `Dockerfile`
-  - Multi-stage source-build image for the monorepo.
-  - Build stage installs workspace dependencies and runs `pnpm build`.
-  - Runtime stage copies the built workspace and starts the HTTP Caplets server.
-- Create: `docker-compose.yml`
-  - Local/self-hosted Compose service with configurable host binding, port, credentials, health check, and durable named volume.
-- Modify: `README.md`
-  - Adds a Docker Compose self-hosting section near the existing “Remote Caplets service” docs.
-- Existing reference only: `docs/specs/2026-05-21-docker-self-hosting-design.md`
-  - Source of truth for the approved design.
-
----
-
-### Task 1: Add Docker build context rules
-
-**Files:**
-
-- Create: `.dockerignore`
-
-- [ ] **Step 1: Create `.dockerignore`**
-
-Create `.dockerignore` with exactly this content:
-
-```dockerignore
-.git
-.github
-.husky
-.brv
-.pi
-.pi-lens
-.opencode
-.claude-plugin
-node_modules
-**/node_modules
-dist
-**/dist
-.turbo
-coverage
-*.log
-.env
-.env.*
-!.env.example
-.caplets
-**/.caplets
-.DS_Store
-```
-
-Rationale:
-
-- `node_modules`, `dist`, `.turbo`, and `coverage` are regenerated inside Docker.
-- `.git`, agent state directories, and local Caplets config/state should not enter the image context.
-- `.env` files are excluded to avoid accidental secret inclusion.
-
-- [ ] **Step 2: Verify `.dockerignore` exists and is formatted as plain text**
-
-Run:
-
-```bash
-test -f .dockerignore && sed -n '1,120p' .dockerignore
-```
-
-Expected output contains the entries from Step 1 and exits with status `0`.
-
-- [ ] **Step 3: Commit Docker ignore rules**
-
-Run:
-
-```bash
-git add .dockerignore
-git commit -m "build: add docker ignore rules"
-```
-
-Expected: commit succeeds and includes only `.dockerignore`.
-
----
-
-### Task 2: Add the source-build Dockerfile
-
-**Files:**
-
-- Create: `Dockerfile`
-
-- [ ] **Step 1: Create `Dockerfile`**
-
-Create `Dockerfile` with exactly this content:
-
-```dockerfile
-# syntax=docker/dockerfile:1.7
-
-ARG NODE_VERSION=24-bookworm-slim
-ARG PNPM_VERSION=11.0.9
-
-FROM node:${NODE_VERSION} AS build
-ARG PNPM_VERSION
-WORKDIR /app
-
-RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
-
-COPY package.json pnpm-lock.yaml pnpm-workspace.yaml turbo.json tsconfig.json vitest.config.ts ./
-COPY packages/core/package.json packages/core/package.json
-COPY packages/cli/package.json packages/cli/package.json
-COPY packages/opencode/package.json packages/opencode/package.json
-COPY packages/pi/package.json packages/pi/package.json
-COPY packages/benchmarks/package.json packages/benchmarks/package.json
-
-RUN pnpm install --frozen-lockfile
-
-COPY . .
-
-RUN pnpm build
-
-FROM node:${NODE_VERSION} AS runtime
-ARG PNPM_VERSION
-ENV NODE_ENV=production \
-    XDG_CONFIG_HOME=/data/config \
-    XDG_STATE_HOME=/data/state \
-    CAPLETS_SERVER_URL=http://127.0.0.1:5387
-WORKDIR /app
-
-RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
-
-COPY --from=build /app /app
-
-VOLUME ["/data"]
-EXPOSE 5387
-
-CMD ["pnpm", "--filter", "caplets", "exec", "caplets", "serve", "--transport", "http", "--host", "0.0.0.0"]
-```
-
-Notes for implementer:
-
-- Keep `CAPLETS_SERVER_URL` as a default only. Compose will override it for user-facing deployments.
-- `XDG_CONFIG_HOME=/data/config` makes the default config path `/data/config/caplets/config.json`.
-- `XDG_STATE_HOME=/data/state` makes auth state persist under `/data/state/caplets/auth`.
-- The runtime image intentionally copies the built workspace and `node_modules` from the build stage to preserve workspace links for local-source execution.
-
-- [ ] **Step 2: Validate Dockerfile parses with Docker**
-
-Run:
-
-```bash
-docker build --target runtime -t caplets:self-host-test .
-```
-
-Expected: build succeeds. The final lines should include an image tagged `caplets:self-host-test`.
-
-If Docker is unavailable in the execution environment, record the exact Docker error in the task notes and continue to Step 3; do not claim the Docker build was verified.
-
-- [ ] **Step 3: Commit the Dockerfile**
-
-Run:
-
-```bash
-git add Dockerfile
-git commit -m "build: add caplets docker image"
-```
-
-Expected: commit succeeds and includes only `Dockerfile`.
-
----
-
-### Task 3: Add Docker Compose service
-
-**Files:**
-
-- Create: `docker-compose.yml`
-
-- [ ] **Step 1: Create `docker-compose.yml`**
-
-Create `docker-compose.yml` with exactly this content:
-
-```yaml
-services:
-  caplets:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    image: caplets:local
-    restart: unless-stopped
-    environment:
-      CAPLETS_SERVER_URL: ${CAPLETS_SERVER_URL:-http://127.0.0.1:5387}
-      CAPLETS_SERVER_USER: ${CAPLETS_SERVER_USER:-caplets}
-      CAPLETS_SERVER_PASSWORD: ${CAPLETS_SERVER_PASSWORD:-}
-      XDG_CONFIG_HOME: /data/config
-      XDG_STATE_HOME: /data/state
-    ports:
-      - "${CAPLETS_BIND_ADDRESS:-127.0.0.1}:${CAPLETS_PORT:-5387}:5387"
-    volumes:
-      - caplets-data:/data
-    healthcheck:
-      test:
-        - CMD-SHELL
-        - >-
-          node -e "fetch('http://127.0.0.1:5387/healthz').then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1))"
-      interval: 30s
-      timeout: 5s
-      retries: 5
-      start_period: 10s
-
-volumes:
-  caplets-data:
-```
-
-Rationale:
-
-- The container listens internally on `0.0.0.0:5387` from the Dockerfile command.
-- Compose defaults external binding to `127.0.0.1` for safety.
-- `CAPLETS_SERVER_PASSWORD` is intentionally empty by default so local loopback startup works without hard-coded secrets.
-- Self-hosters exposing beyond loopback must set `CAPLETS_SERVER_PASSWORD` and should place the service behind HTTPS/TLS.
-
-- [ ] **Step 2: Validate Compose renders correctly**
-
-Run:
-
-```bash
-docker compose config
-```
-
-Expected: command exits `0` and rendered output includes:
-
-```yaml
-ports:
-  - mode: ingress
-    host_ip: 127.0.0.1
-    target: 5387
-    published: "5387"
-```
-
-Compose output formatting can vary by Docker Compose version. If the exact YAML differs, verify these equivalent facts in the rendered output:
-
-- service name is `caplets`
-- published port is `5387`
-- host IP is `127.0.0.1`
-- named volume `caplets-data` is declared
-
-- [ ] **Step 3: Validate LAN binding override renders correctly**
-
-Run:
-
-```bash
-CAPLETS_BIND_ADDRESS=0.0.0.0 CAPLETS_PORT=15387 docker compose config
-```
-
-Expected: command exits `0` and rendered output shows host IP `0.0.0.0` and published port `15387` for target port `5387`.
-
-- [ ] **Step 4: Commit Compose service**
-
-Run:
-
-```bash
-git add docker-compose.yml
-git commit -m "build: add docker compose service"
-```
-
-Expected: commit succeeds and includes only `docker-compose.yml`.
-
----
-
-### Task 4: Document Docker self-hosting
-
-**Files:**
-
-- Modify: `README.md` after the remote HTTP service paragraph and before “Native integrations and remote-capable CLI commands read remote client settings from environment variables:”
-
-- [ ] **Step 1: Insert Docker Compose documentation**
-
-In `README.md`, find this paragraph under `### Remote Caplets service`:
-
-```markdown
-`caplets serve --transport http` serves plain HTTP. For non-loopback or network access, expose it only through HTTPS/TLS (for example, a reverse proxy or secure tunnel) and enable Basic Auth; Basic Auth over plain HTTP exposes credentials. Keep credentials out of plugin manifests.
-```
-
-Immediately after it, insert this section:
-
-````markdown
-#### Docker Compose self-hosting
-
-This repository includes a source-build Docker image and Compose service for running the HTTP service from the checked-out source tree:
-
-```sh
-CAPLETS_SERVER_PASSWORD=change-me docker compose up --build
-```
-
-By default, Compose publishes the service on loopback only:
-
-- Base URL: `http://127.0.0.1:5387`
-- MCP endpoint: `http://127.0.0.1:5387/mcp`
-- Control endpoint: `http://127.0.0.1:5387/control`
-- Health endpoint: `http://127.0.0.1:5387/healthz`
-
-The service stores Caplets config and auth state in a Docker named volume mounted at `/data`. To use a host-visible bind mount instead, replace this Compose volume entry:
-
-```yaml
-volumes:
-  - caplets-data:/data
-```
-
-with:
-
-```yaml
-volumes:
-  - ./data:/data
-```
-
-To expose the service to a LAN interface or reverse proxy, set an explicit bind address and public base URL:
-
-```sh
-CAPLETS_BIND_ADDRESS=0.0.0.0 \
-CAPLETS_SERVER_URL=https://caplets.example.com \
-CAPLETS_SERVER_PASSWORD=change-me \
-docker compose up --build
-```
-
-Only expose Caplets beyond loopback through HTTPS/TLS and Basic Auth. `CAPLETS_SERVER_PASSWORD` protects both the MCP and control endpoints; downstream provider tokens and auth files remain server-owned inside the mounted `/data` location.
-````
-
-Important markdown escaping note: the inserted section contains fenced code blocks inside markdown. Keep each fence exactly as shown.
-
-- [ ] **Step 2: Verify README formatting**
-
-Run:
-
-```bash
-pnpm format:check README.md
-```
-
-Expected: `All matched files use the correct format.`
-
-- [ ] **Step 3: Commit README documentation**
-
-Run:
-
-```bash
-git add README.md
-git commit -m "docs: document docker self-hosting"
-```
-
-Expected: commit succeeds and includes only `README.md`.
-
----
-
-### Task 5: Run final verification
-
-**Files:**
-
-- Verify: `.dockerignore`
-- Verify: `Dockerfile`
-- Verify: `docker-compose.yml`
-- Verify: `README.md`
-
-- [ ] **Step 1: Run formatting check for changed text files**
-
-Run:
-
-```bash
-pnpm format:check .dockerignore Dockerfile docker-compose.yml README.md docs/specs/2026-05-21-docker-self-hosting-design.md
-```
-
-Expected: command exits `0` and reports all matched files use correct format.
-
-- [ ] **Step 2: Run Compose config validation**
-
-Run:
-
-```bash
-docker compose config
-```
-
-Expected: command exits `0` and renders the `caplets` service and `caplets-data` volume.
-
-If Docker Compose is unavailable, record the exact command failure in the task notes and continue; do not claim Compose was verified.
-
-- [ ] **Step 3: Run Docker image build verification**
-
-Run:
-
-```bash
-docker build -t caplets:self-host-test .
-```
-
-Expected: command exits `0` and creates image `caplets:self-host-test`.
-
-If Docker is unavailable, record the exact command failure in the task notes and continue; do not claim the image build was verified.
-
-- [ ] **Step 4: Optionally run service smoke test when Docker daemon is available**
-
-Run:
-
-```bash
-CAPLETS_SERVER_PASSWORD=change-me docker compose up --build -d
-sleep 5
-curl --fail http://127.0.0.1:5387/healthz
-docker compose down
-```
-
-Expected:
-
-- `curl` exits `0`.
-- Response body is JSON with a healthy Caplets HTTP service, including `transport` set to `http`.
-- `docker compose down` exits `0` and stops the service.
-
-If the service fails to become healthy, inspect logs with:
-
-```bash
-docker compose logs caplets
-```
-
-Fix the issue before completing the task.
-
-- [ ] **Step 5: Run repo-level non-Docker checks**
-
-Run:
-
-```bash
-pnpm verify
-```
-
-Expected: command exits `0`.
-
-- [ ] **Step 6: Commit any verification fixes**
-
-If Steps 1-5 required fixes, commit those fixes:
-
-```bash
-git add .dockerignore Dockerfile docker-compose.yml README.md
-git commit -m "fix: polish docker self-hosting setup"
-```
-
-If no fixes were required, do not create an empty commit.
-
----
-
-## Self-Review
-
-### Spec coverage
-
-- Root `Dockerfile`: Task 2.
-- Root `docker-compose.yml`: Task 3.
-- README Docker usage docs: Task 4.
-- Unified env alignment: Task 2 and Task 3 use `CAPLETS_SERVER_URL`, `CAPLETS_SERVER_USER`, `CAPLETS_SERVER_PASSWORD`, and XDG state/config paths; Task 4 documents remote clients with the same server URL model.
-- Source-build image rather than npm-install-only image: Task 2.
-- Configurable external binding: Task 3 and Task 4.
-- Named volume default and bind-mount alternative: Task 3 and Task 4.
-- Health check: Task 3 and Task 5.
-- Security guidance for loopback defaults, HTTPS/TLS, Basic Auth, and server-owned state: Task 3 and Task 4.
-- Verification commands: Task 2, Task 3, and Task 5.
-
-### Placeholder scan
-
-No placeholder markers are present. Every file creation step includes exact content. Every verification step includes exact commands and expected outcomes.
-
-### Type and name consistency
-
-- Compose service name is consistently `caplets`.
-- Named volume is consistently `caplets-data`.
-- Internal port is consistently `5387`.
-- External bind variables are consistently `CAPLETS_BIND_ADDRESS` and `CAPLETS_PORT`.
-- Unified server variables are consistently `CAPLETS_SERVER_URL`, `CAPLETS_SERVER_USER`, and `CAPLETS_SERVER_PASSWORD`.
diff --git a/docs/plans/2026-05-21-ghcr-release-publishing.md b/docs/plans/2026-05-21-ghcr-release-publishing.md
deleted file mode 100644
index 01214df9..00000000
--- a/docs/plans/2026-05-21-ghcr-release-publishing.md
+++ /dev/null
@@ -1,296 +0,0 @@
-# GHCR Release Publishing Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Publish the Caplets Docker image to GitHub Container Registry when the existing Changesets release workflow publishes npm packages.
-
-**Architecture:** Extend `.github/workflows/release.yml` in-place. The release job keeps the current install, verify, and Changesets publish flow, then runs Docker metadata/login/build-push steps only when `changesets/action` reports `published == 'true'` and the published package list includes the `caplets` CLI package. The image is pushed to `ghcr.io/spiritledsoftware/caplets` with `latest`, semantic version, `v`-prefixed semantic version, and short SHA tags.
-
-**Tech Stack:** GitHub Actions, Changesets, Docker Buildx, GHCR, `docker/login-action`, `docker/metadata-action`, `docker/build-push-action`, Node.js 24, pnpm 11.0.9.
-
----
-
-## File Structure
-
-- Modify: `.github/workflows/release.yml`
-  - Add job-scoped `packages: write` permission for GHCR publishing.
-  - Add an `id: changesets` to the existing Changesets action step.
-  - Add a step to check whether the `caplets` CLI package was published, then read `packages/cli/package.json` version for Docker metadata.
-  - Add QEMU, Docker Buildx, GHCR login, metadata, and build-push steps gated on published CLI releases.
-- Verify only: `Dockerfile`
-  - Existing source-build image is the image pushed by the workflow.
-
----
-
-### Task 1: Add GHCR permissions and Changesets output ID
-
-**Files:**
-
-- Modify: `.github/workflows/release.yml`
-
-- [ ] **Step 1: Update workflow permissions and Changesets step ID**
-
-In `.github/workflows/release.yml`, change the permissions block from:
-
-```yaml
-permissions:
-  contents: write
-  pull-requests: write
-  id-token: write
-```
-
-to keep workflow-level permissions unchanged and add job-scoped package publishing permission:
-
-```yaml
-permissions:
-  contents: write
-  pull-requests: write
-  id-token: write
-
-jobs:
-  release:
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-      packages: write
-```
-
-Then change the Changesets step from:
-
-```yaml
-- name: Create release PR or publish
-  uses: changesets/action@v1
-```
-
-to:
-
-```yaml
-- name: Create release PR or publish
-  id: changesets
-  uses: changesets/action@v1
-```
-
-- [ ] **Step 2: Verify workflow formatting**
-
-Run:
-
-```bash
-pnpm format:check .github/workflows/release.yml
-```
-
-Expected: command exits `0` and reports all matched files use the correct format.
-
-- [ ] **Step 3: Commit workflow release output plumbing**
-
-Run:
-
-```bash
-git add .github/workflows/release.yml
-git commit -m "ci: expose release publish result"
-```
-
-Expected: commit succeeds and includes only `.github/workflows/release.yml`.
-
----
-
-### Task 2: Add Docker image metadata and publishing steps
-
-**Files:**
-
-- Modify: `.github/workflows/release.yml`
-
-- [ ] **Step 1: Insert Docker publish steps after Changesets**
-
-Immediately after the existing `Create release PR or publish` step, insert:
-
-```yaml
-- name: Check whether CLI package was published
-  if: steps.changesets.outputs.published == 'true'
-  id: cli-package
-  env:
-    PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }}
-  run: |
-    cli_published=$(node <<'NODE'
-    const publishedPackages = JSON.parse(process.env.PUBLISHED_PACKAGES || '[]');
-    const cliPublished = publishedPackages.some((pkg) => pkg && pkg.name === 'caplets');
-    process.stdout.write(cliPublished ? 'true' : 'false');
-    NODE
-    )
-    echo "published=${cli_published}" >> "$GITHUB_OUTPUT"
-
-- name: Read Docker image version
-  if: steps.changesets.outputs.published == 'true' && steps.cli-package.outputs.published == 'true'
-  id: image-version
-  run: echo "version=$(node -p \"require('./packages/cli/package.json').version\")" >> "$GITHUB_OUTPUT"
-
-- name: Setup QEMU
-  if: steps.changesets.outputs.published == 'true' && steps.cli-package.outputs.published == 'true'
-  uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130
-
-- name: Setup Docker Buildx
-  if: steps.changesets.outputs.published == 'true' && steps.cli-package.outputs.published == 'true'
-  uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f
-
-- name: Log in to GitHub Container Registry
-  if: steps.changesets.outputs.published == 'true' && steps.cli-package.outputs.published == 'true'
-  uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9
-  with:
-    registry: ghcr.io
-    username: ${{ github.actor }}
-    password: ${{ secrets.GITHUB_TOKEN }}
-
-- name: Generate Docker metadata
-  if: steps.changesets.outputs.published == 'true' && steps.cli-package.outputs.published == 'true'
-  id: docker-meta
-  uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051
-  with:
-    images: ghcr.io/spiritledsoftware/caplets
-    tags: |
-      type=raw,value=latest
-      type=raw,value=${{ steps.image-version.outputs.version }}
-      type=raw,value=v${{ steps.image-version.outputs.version }}
-      type=sha,format=short,prefix=sha-
-
-- name: Publish Docker image
-  if: steps.changesets.outputs.published == 'true' && steps.cli-package.outputs.published == 'true'
-  uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8
-  with:
-    context: .
-    file: ./Dockerfile
-    platforms: linux/amd64,linux/arm64
-    push: true
-    tags: ${{ steps.docker-meta.outputs.tags }}
-    labels: ${{ steps.docker-meta.outputs.labels }}
-```
-
-- [ ] **Step 2: Verify workflow formatting**
-
-Run:
-
-```bash
-pnpm format:check .github/workflows/release.yml
-```
-
-Expected: command exits `0` and reports all matched files use the correct format.
-
-- [ ] **Step 3: Commit Docker publishing steps**
-
-Run:
-
-```bash
-git add .github/workflows/release.yml
-git commit -m "ci: publish docker image on release"
-```
-
-Expected: commit succeeds and includes only `.github/workflows/release.yml`.
-
----
-
-### Task 3: Verify release workflow and Docker image build
-
-**Files:**
-
-- Verify: `.github/workflows/release.yml`
-- Verify: `Dockerfile`
-
-- [ ] **Step 1: Run workflow formatting check**
-
-Run:
-
-```bash
-pnpm format:check .github/workflows/release.yml
-```
-
-Expected: command exits `0` and reports all matched files use the correct format.
-
-- [ ] **Step 2: Check workflow contains required release gates and tags**
-
-Run:
-
-```bash
-node <<'NODE'
-const fs = require('node:fs');
-const workflow = fs.readFileSync('.github/workflows/release.yml', 'utf8');
-const required = [
-  'packages: write',
-  'id: changesets',
-  "if: steps.changesets.outputs.published == 'true' && steps.cli-package.outputs.published == 'true'",
-  'id: cli-package',
-  'uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130',
-  'uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9',
-  'uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051',
-  'uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8',
-  'images: ghcr.io/spiritledsoftware/caplets',
-  'type=raw,value=latest',
-  'type=raw,value=${{ steps.image-version.outputs.version }}',
-  'type=raw,value=v${{ steps.image-version.outputs.version }}',
-  'type=sha,format=short,prefix=sha-',
-];
-const missing = required.filter((entry) => !workflow.includes(entry));
-if (missing.length > 0) {
-  console.error(`Missing workflow entries:\n${missing.join('\n')}`);
-  process.exit(1);
-}
-NODE
-```
-
-Expected: command exits `0` with no missing workflow entries.
-
-- [ ] **Step 3: Verify the Docker image still builds**
-
-Run:
-
-```bash
-docker build -t caplets:self-host-test .
-```
-
-Expected: command exits `0` and creates image `caplets:self-host-test`.
-
-If Docker is unavailable, record the exact Docker error in task notes and continue; do not claim Docker build verification passed.
-
-- [ ] **Step 4: Run focused repo checks**
-
-Run:
-
-```bash
-pnpm verify
-```
-
-Expected: command exits `0`.
-
-- [ ] **Step 5: Commit verification fixes if needed**
-
-If verification required fixes, run:
-
-```bash
-git add .github/workflows/release.yml
-git commit -m "fix: polish docker release publishing"
-```
-
-Expected: commit succeeds only if fixes were made. If no fixes were required, do not create an empty commit.
-
----
-
-## Self-Review
-
-### Spec coverage
-
-- GHCR target image `ghcr.io/spiritledsoftware/caplets`: Task 2.
-- Publish only after a real CLI package release: Tasks 1 and 2 gate on both `steps.changesets.outputs.published == 'true'` and `steps.cli-package.outputs.published == 'true'`.
-- Use repository-scoped token and no extra long-lived registry secret: Task 2 uses `docker/login-action` pinned to a full commit SHA with `secrets.GITHUB_TOKEN`.
-- Add required GitHub Packages permission: Task 1.
-- Tags for `latest`, semantic version, `v` semantic version, and short SHA: Task 2 and Task 3.
-- Multi-platform Docker publishing includes QEMU registration before Buildx: Task 2.
-- Local verification of workflow and Dockerfile: Task 3.
-
-### Placeholder scan
-
-No placeholder markers are present. Every edit step includes exact YAML or exact verification commands.
-
-### Type and name consistency
-
-- Changesets step ID is consistently `changesets`.
-- Version step ID is consistently `image-version`.
-- Docker metadata step ID is consistently `docker-meta`.
-- Image name is consistently `ghcr.io/spiritledsoftware/caplets`.
diff --git a/docs/plans/2026-05-21-mcp-resources-prompts.md b/docs/plans/2026-05-21-mcp-resources-prompts.md
deleted file mode 100644
index 397e1aa3..00000000
--- a/docs/plans/2026-05-21-mcp-resources-prompts.md
+++ /dev/null
@@ -1,2182 +0,0 @@
-# MCP Resources and Prompts Implementation Plan
-
-> Superseded for remote/server environment naming: current client integrations use `CAPLETS_REMOTE_*`, while the process hosting `caplets serve --transport http` uses `CAPLETS_SERVER_*`. This plan remains historical implementation context.
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add MCP resource, resource-template, prompt, and completion support to MCP-backed Caplets while keeping non-MCP backends tool-only.
-
-**Architecture:** Generate backend-aware Caplet operation schemas, route MCP-only operations only for `backend: "mcp"`, and extend `DownstreamManager` to cache and forward MCP resources/prompts/completions through the existing managed MCP connection. CLI, remote control, Pi, and OpenCode consume the same backend-aware operation model so agents are not invited to call MCP-specific operations on OpenAPI, GraphQL, HTTP, CLI, or Caplet-set backends.
-
-**Tech Stack:** TypeScript, Zod 4, MCP SDK 1.29, Commander, Vitest, Pi/OpenCode native adapters, pnpm 11.0.9.
-
----
-
-## Scope and constraints
-
-- Use `pnpm` only.
-- Preserve one top-level Caplets tool per enabled Caplet.
-- Do not flatten downstream resources/prompts into Caplets `tools/list`.
-- Do not expose MCP-only operation names in generated schemas for non-MCP backends.
-- Keep `get_caplet` non-probing; live MCP capability observation belongs in `check_backend` and operation results.
-- Use command-semantic remote control via `/control`; do not add raw CLI-string execution.
-- Keep remote mode server-owned for config, Caplet files, and downstream auth secrets.
-- Add a changeset because the generated tool schema, CLI surface, and package docs are user-facing.
-
-## File structure
-
-- Modify `packages/core/src/generated-tool-input-schema.ts`
-  - Own backend-aware operation arrays, field descriptions, JSON Schema generation, and Zod schema generation.
-- Modify `packages/core/src/tools.ts`
-  - Validate requests with the selected Caplet backend, dispatch MCP-only operations, and annotate resource/prompt/completion results.
-- Modify `packages/core/src/downstream.ts`
-  - Add MCP resource, resource-template, prompt, completion, capability, cache, compact, and search methods.
-- Modify `packages/core/src/errors.ts`
-  - Add `UNSUPPORTED_OPERATION`, `UNSUPPORTED_CAPABILITY`, `RESOURCE_NOT_FOUND`, `PROMPT_NOT_FOUND`, `DOWNSTREAM_RESOURCE_ERROR`, `DOWNSTREAM_PROMPT_ERROR`, and `DOWNSTREAM_COMPLETION_ERROR`.
-- Modify `packages/core/src/capability-description.ts`
-  - Describe MCP-backed Caplets as tools/resources/prompts/completions; keep non-MCP descriptions tool-oriented.
-- Modify `packages/core/src/serve/session.ts`
-  - Register and update each Caplet tool with its backend-specific input schema.
-- Modify `packages/core/src/native/service.ts`
-  - Include backend-aware schema metadata in `NativeCapletTool`.
-- Modify `packages/core/src/native/tools.ts`
-  - Add MCP-specific guidance only for MCP-backed Caplets.
-- Modify `packages/core/src/native/remote.ts`
-  - Preserve remote tool input schema metadata when available from remote MCP `tools/list`.
-- Modify `packages/pi/src/index.ts`
-  - Use each native Caplet tool's JSON Schema instead of the global schema.
-- Modify `packages/opencode/src/schema.ts` and `packages/opencode/src/hooks.ts`
-  - Generate OpenCode argument schemas from each native Caplet tool's operation set.
-- Modify `packages/core/src/cli.ts`
-  - Add resource/prompt/completion commands, remote routing, and human summaries.
-- Modify `packages/core/src/remote-control/types.ts` and `packages/core/src/remote-control/dispatch.ts`
-  - Add command-semantic remote operation names and request validation.
-- Modify `README.md`, `packages/cli/README.md`, `packages/pi/README.md`, and `packages/opencode/README.md`.
-- Add `.changeset/mcp-resources-prompts.md` for `@caplets/core`, `caplets`, `@caplets/pi`, and `@caplets/opencode`.
-- Modify tests:
-  - `packages/core/test/tools.test.ts`
-  - `packages/core/test/downstream.test.ts`
-  - `packages/core/test/serve-session.test.ts`
-  - `packages/core/test/cli.test.ts`
-  - `packages/core/test/cli-remote.test.ts`
-  - `packages/core/test/remote-control-dispatch.test.ts`
-  - `packages/core/test/native-remote.test.ts`
-  - `packages/pi/test/pi.test.ts`
-  - `packages/opencode/test/opencode.test.ts`
-
----
-
-### Task 1: Add backend-aware generated schemas and validation
-
-**Files:**
-
-- Modify: `packages/core/src/generated-tool-input-schema.ts`
-- Modify: `packages/core/src/tools.ts`
-- Modify: `packages/core/src/errors.ts`
-- Test: `packages/core/test/tools.test.ts`
-
-- [ ] **Step 1: Write failing schema and validation tests**
-
-Add these tests to `packages/core/test/tools.test.ts` inside `describe("generated tool request validation", ...)`:
-
-```ts
-import {
-  generatedToolInputJsonSchemaForCaplet,
-  generatedToolInputSchemaForCaplet,
-  mcpOperations,
-  operations,
-} from "../src/generated-tool-input-schema";
-
-it("generates tool-only schemas for non-MCP Caplets", () => {
-  const nonMcp = generatedToolInputJsonSchemaForCaplet({ backend: "http" });
-  expect(nonMcp.properties.operation.enum).toEqual(operations);
-  expect(nonMcp.properties.operation.enum).not.toContain("list_resources");
-  expect(nonMcp.properties).not.toHaveProperty("uri");
-  expect(nonMcp.properties).not.toHaveProperty("prompt");
-  expect(nonMcp.properties).not.toHaveProperty("ref");
-  expect(nonMcp.properties).not.toHaveProperty("argument");
-});
-
-it("generates MCP capability schemas only for MCP Caplets", () => {
-  const mcp = generatedToolInputJsonSchemaForCaplet({ backend: "mcp" });
-  expect(mcp.properties.operation.enum).toEqual(mcpOperations);
-  expect(mcp.properties.operation.enum).toContain("list_resources");
-  expect(mcp.properties.operation.enum).toContain("get_prompt");
-  expect(mcp.properties.operation.enum).toContain("complete");
-  expect(mcp.properties).toHaveProperty("uri");
-  expect(mcp.properties).toHaveProperty("prompt");
-  expect(mcp.properties).toHaveProperty("ref");
-  expect(mcp.properties).toHaveProperty("argument");
-});
-
-it("validates MCP-only operation request shapes for MCP backends", () => {
-  expect(
-    validateOperationRequest({ operation: "read_resource", uri: "file:///x" }, 50, "mcp"),
-  ).toEqual({ operation: "read_resource", uri: "file:///x" });
-  expect(
-    validateOperationRequest({ operation: "get_prompt", prompt: "review" }, 50, "mcp"),
-  ).toEqual({ operation: "get_prompt", prompt: "review", arguments: {} });
-  expect(
-    validateOperationRequest(
-      {
-        operation: "complete",
-        ref: { type: "prompt", name: "review" },
-        argument: { name: "issueId", value: "CAP-" },
-      },
-      50,
-      "mcp",
-    ),
-  ).toEqual({
-    operation: "complete",
-    ref: { type: "prompt", name: "review" },
-    argument: { name: "issueId", value: "CAP-" },
-  });
-});
-
-it("rejects MCP-only operations for non-MCP backends", () => {
-  expect(() => validateOperationRequest({ operation: "list_resources" }, 50, "http")).toThrow(
-    expect.objectContaining({ code: "UNSUPPORTED_OPERATION" }),
-  );
-});
-
-it("rejects operation-specific extra fields for MCP-only operations", () => {
-  expect(() =>
-    validateOperationRequest({ operation: "list_resources", tool: "x" }, 50, "mcp"),
-  ).toThrow(expect.objectContaining({ code: "REQUEST_INVALID" }));
-  expect(() =>
-    validateOperationRequest(
-      { operation: "get_prompt", prompt: "x", fields: ["message"] },
-      50,
-      "mcp",
-    ),
-  ).toThrow(expect.objectContaining({ code: "REQUEST_INVALID" }));
-  expect(() =>
-    validateOperationRequest(
-      { operation: "complete", ref: { type: "prompt", name: "x" } },
-      50,
-      "mcp",
-    ),
-  ).toThrow(expect.objectContaining({ code: "REQUEST_INVALID" }));
-});
-```
-
-- [ ] **Step 2: Run focused tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: FAIL because `generatedToolInputJsonSchemaForCaplet`, `generatedToolInputSchemaForCaplet`, `mcpOperations`, new errors, and the third `validateOperationRequest` parameter do not exist.
-
-- [ ] **Step 3: Add error codes**
-
-Modify `packages/core/src/errors.ts` by inserting the new codes before `UNSUPPORTED_TRANSPORT`:
-
-```ts
-  "UNSUPPORTED_OPERATION",
-  "UNSUPPORTED_CAPABILITY",
-  "RESOURCE_NOT_FOUND",
-  "PROMPT_NOT_FOUND",
-  "DOWNSTREAM_RESOURCE_ERROR",
-  "DOWNSTREAM_PROMPT_ERROR",
-  "DOWNSTREAM_COMPLETION_ERROR",
-```
-
-- [ ] **Step 4: Implement backend-aware schema exports**
-
-Replace `packages/core/src/generated-tool-input-schema.ts` with this shape, preserving the exported `operations`, `generatedToolInputDescriptions`, `generatedToolInputJsonSchema()`, and adding MCP-aware exports:
-
-```ts
-import { z } from "zod";
-
-export const operations = [
-  "get_caplet",
-  "check_backend",
-  "list_tools",
-  "search_tools",
-  "get_tool",
-  "call_tool",
-] as const;
-
-export const mcpOperations = [
-  ...operations,
-  "list_resources",
-  "search_resources",
-  "list_resource_templates",
-  "read_resource",
-  "list_prompts",
-  "search_prompts",
-  "get_prompt",
-  "complete",
-] as const;
-
-export type GeneratedOperation = (typeof operations)[number];
-export type GeneratedMcpOperation = (typeof mcpOperations)[number];
-export type CapletSchemaBackend = { backend: string };
-
-export const generatedToolInputDescriptions = {
-  operation:
-    "Wrapper operation. Non-MCP Caplets expose tool operations only; MCP Caplets also expose resources, prompts, and completions.",
-  query: "Required for search operations only.",
-  limit: "Optional list/search result limit.",
-  tool: "Exact downstream tool name for get_tool or call_tool.",
-  arguments: "JSON object for call_tool inputs or get_prompt arguments.",
-  fields: "Optional call_tool structured output paths when outputSchema allows it.",
-  uri: "Exact downstream resource URI for read_resource.",
-  prompt: "Exact downstream prompt name for get_prompt.",
-  ref: "Completion target reference for complete.",
-  argument: "Completion argument object for complete.",
-} as const;
-
-export const completionRefSchema = z.union([
-  z.object({ type: z.literal("prompt"), name: z.string().min(1) }).strict(),
-  z.object({ type: z.literal("resourceTemplate"), uri: z.string().min(1) }).strict(),
-]);
-
-export const completionArgumentSchema = z
-  .object({ name: z.string().min(1), value: z.string() })
-  .strict();
-
-const baseShape = {
-  query: z.string().optional().describe(generatedToolInputDescriptions.query),
-  limit: z.number().int().positive().optional().describe(generatedToolInputDescriptions.limit),
-  tool: z.string().optional().describe(generatedToolInputDescriptions.tool),
-  arguments: z
-    .record(z.string(), z.unknown())
-    .optional()
-    .describe(generatedToolInputDescriptions.arguments),
-  fields: z
-    .array(z.string().min(1))
-    .min(1)
-    .optional()
-    .describe(generatedToolInputDescriptions.fields),
-};
-
-export function generatedToolInputSchemaForCaplet(caplet: CapletSchemaBackend) {
-  const operationValues = caplet.backend === "mcp" ? mcpOperations : operations;
-  return z
-    .object({
-      operation: z.enum(operationValues).describe(generatedToolInputDescriptions.operation),
-      ...baseShape,
-      ...(caplet.backend === "mcp"
-        ? {
-            uri: z.string().optional().describe(generatedToolInputDescriptions.uri),
-            prompt: z.string().optional().describe(generatedToolInputDescriptions.prompt),
-            ref: completionRefSchema.optional().describe(generatedToolInputDescriptions.ref),
-            argument: completionArgumentSchema
-              .optional()
-              .describe(generatedToolInputDescriptions.argument),
-          }
-        : {}),
-    })
-    .strict();
-}
-
-export const generatedToolInputSchema = generatedToolInputSchemaForCaplet({ backend: "tool" });
-
-export function generatedToolInputJsonSchemaForCaplet(caplet: CapletSchemaBackend) {
-  const mcp = caplet.backend === "mcp";
-  return {
-    type: "object",
-    properties: {
-      operation: {
-        type: "string",
-        enum: mcp ? mcpOperations : operations,
-        description: generatedToolInputDescriptions.operation,
-      },
-      query: { type: "string", description: generatedToolInputDescriptions.query },
-      limit: { type: "integer", minimum: 1, description: generatedToolInputDescriptions.limit },
-      tool: { type: "string", description: generatedToolInputDescriptions.tool },
-      arguments: { type: "object", description: generatedToolInputDescriptions.arguments },
-      fields: {
-        type: "array",
-        items: { type: "string", minLength: 1 },
-        minItems: 1,
-        description: generatedToolInputDescriptions.fields,
-      },
-      ...(mcp
-        ? {
-            uri: { type: "string", description: generatedToolInputDescriptions.uri },
-            prompt: { type: "string", description: generatedToolInputDescriptions.prompt },
-            ref: {
-              oneOf: [
-                {
-                  type: "object",
-                  properties: { type: { const: "prompt" }, name: { type: "string", minLength: 1 } },
-                  required: ["type", "name"],
-                  additionalProperties: false,
-                },
-                {
-                  type: "object",
-                  properties: {
-                    type: { const: "resourceTemplate" },
-                    uri: { type: "string", minLength: 1 },
-                  },
-                  required: ["type", "uri"],
-                  additionalProperties: false,
-                },
-              ],
-              description: generatedToolInputDescriptions.ref,
-            },
-            argument: {
-              type: "object",
-              properties: { name: { type: "string", minLength: 1 }, value: { type: "string" } },
-              required: ["name", "value"],
-              additionalProperties: false,
-              description: generatedToolInputDescriptions.argument,
-            },
-          }
-        : {}),
-    },
-    required: ["operation"],
-    additionalProperties: false,
-  } as const;
-}
-
-export function generatedToolInputJsonSchema() {
-  return generatedToolInputJsonSchemaForCaplet({ backend: "tool" });
-}
-```
-
-- [ ] **Step 5: Extend `validateOperationRequest`**
-
-Modify `packages/core/src/tools.ts` so `handleServerTool` passes `server.backend` and `validateOperationRequest` accepts backend:
-
-```ts
-const parsed = validateOperationRequest(
-  request,
-  registry.config.options.maxSearchLimit,
-  server.backend,
-);
-```
-
-Update the function signature and parsing start:
-
-```ts
-export function validateOperationRequest(
-  request: unknown,
-  maxSearchLimit: number,
-  backend: string = "tool",
-): RequiredOperationRequest {
-  const result = generatedToolInputSchemaForCaplet({ backend }).safeParse(request);
-  if (
-    request &&
-    typeof request === "object" &&
-    "operation" in request &&
-    typeof (request as { operation?: unknown }).operation === "string" &&
-    !mcpOperations.includes((request as { operation: string }).operation as never)
-  ) {
-    throw new CapletsError(
-      "UNKNOWN_OPERATION",
-      `Unknown operation: ${(request as { operation: string }).operation}`,
-    );
-  }
-  if (
-    request &&
-    typeof request === "object" &&
-    "operation" in request &&
-    typeof (request as { operation?: unknown }).operation === "string" &&
-    backend !== "mcp" &&
-    mcpOperations.includes((request as { operation: string }).operation as never) &&
-    !operations.includes((request as { operation: string }).operation as never)
-  ) {
-    throw new CapletsError(
-      "UNSUPPORTED_OPERATION",
-      `${(request as { operation: string }).operation} is only available for MCP-backed Caplets`,
-    );
-  }
-  if (!result.success) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "Generated server tool request is invalid",
-      result.error.issues,
-    );
-  }
-  const value = result.data;
-  // keep existing allowed() helper and existing operation cases, then add the MCP-only cases below
-}
-```
-
-Add operation cases after `call_tool`:
-
-```ts
-case "list_resources":
-case "list_resource_templates":
-case "list_prompts":
-  allowed(["limit"]);
-  if (value.limit !== undefined && value.limit > maxSearchLimit) {
-    throw new CapletsError("REQUEST_INVALID", `${value.operation} limit must be <= ${maxSearchLimit}`);
-  }
-  return value.limit === undefined ? { operation: value.operation } : { operation: value.operation, limit: value.limit };
-case "search_resources":
-case "search_prompts":
-  allowed(["query", "limit"]);
-  if (!value.query) throw new CapletsError("REQUEST_INVALID", `${value.operation} requires query`);
-  if (value.limit !== undefined && value.limit > maxSearchLimit) {
-    throw new CapletsError("REQUEST_INVALID", `${value.operation} limit must be <= ${maxSearchLimit}`);
-  }
-  return value.limit === undefined
-    ? { operation: value.operation, query: value.query }
-    : { operation: value.operation, query: value.query, limit: value.limit };
-case "read_resource":
-  allowed(["uri"]);
-  if (!value.uri) throw new CapletsError("REQUEST_INVALID", "read_resource requires uri");
-  return { operation: "read_resource", uri: value.uri };
-case "get_prompt":
-  allowed(["prompt", "arguments"]);
-  if (!value.prompt) throw new CapletsError("REQUEST_INVALID", "get_prompt requires prompt");
-  if (value.arguments !== undefined && !isPlainObject(value.arguments)) {
-    throw new CapletsError("REQUEST_INVALID", "get_prompt.arguments must be a JSON object");
-  }
-  return { operation: "get_prompt", prompt: value.prompt, arguments: value.arguments ?? {} };
-case "complete":
-  allowed(["ref", "argument"]);
-  if (!value.ref) throw new CapletsError("REQUEST_INVALID", "complete requires ref");
-  if (!value.argument) throw new CapletsError("REQUEST_INVALID", "complete requires argument");
-  return { operation: "complete", ref: value.ref, argument: value.argument };
-```
-
-Extend `RequiredOperationRequest` with exact union members:
-
-```ts
-  | { operation: "list_resources" | "list_resource_templates" | "list_prompts"; limit?: number }
-  | { operation: "search_resources" | "search_prompts"; query: string; limit?: number }
-  | { operation: "read_resource"; uri: string }
-  | { operation: "get_prompt"; prompt: string; arguments: Record<string, unknown> }
-  | {
-      operation: "complete";
-      ref: { type: "prompt"; name: string } | { type: "resourceTemplate"; uri: string };
-      argument: { name: string; value: string };
-    };
-```
-
-- [ ] **Step 6: Run schema tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: PASS for validation tests; handler tests may still fail for unimplemented MCP operation dispatch if tests were added beyond this task.
-
-- [ ] **Step 7: Commit Task 1**
-
-```sh
-git add packages/core/src/generated-tool-input-schema.ts packages/core/src/tools.ts packages/core/src/errors.ts packages/core/test/tools.test.ts
-git commit -m "feat(core): add backend-aware Caplet operation schemas"
-```
-
----
-
-### Task 2: Wire backend-specific schemas into MCP serving and native integrations
-
-**Files:**
-
-- Modify: `packages/core/src/capability-description.ts`
-- Modify: `packages/core/src/serve/session.ts`
-- Modify: `packages/core/src/native/service.ts`
-- Modify: `packages/core/src/native/tools.ts`
-- Modify: `packages/core/src/native/remote.ts`
-- Modify: `packages/pi/src/index.ts`
-- Modify: `packages/opencode/src/schema.ts`
-- Modify: `packages/opencode/src/hooks.ts`
-- Test: `packages/core/test/serve-session.test.ts`
-- Test: `packages/core/test/native-remote.test.ts`
-- Test: `packages/pi/test/pi.test.ts`
-- Test: `packages/opencode/test/opencode.test.ts`
-
-- [ ] **Step 1: Write failing MCP session schema tests**
-
-Add to `packages/core/test/serve-session.test.ts`:
-
-```ts
-it("registers MCP Caplets with MCP-only operations and non-MCP Caplets without them", async () => {
-  const { dir, configPath, projectConfigPath } = tempConfig({
-    mcpServers: {
-      docs: { name: "Docs", description: "Read docs.", command: "node" },
-    },
-    httpApis: {
-      status: {
-        name: "Status",
-        description: "Check status.",
-        baseUrl: "http://127.0.0.1:1",
-        auth: { type: "none" },
-        actions: { check: { method: "GET", path: "/status" } },
-      },
-    },
-  });
-  dirs.push(dir);
-  const engine = new CapletsEngine({ configPath, projectConfigPath, watch: false });
-  const server = mockServer();
-  const session = new CapletsMcpSession(engine, { server });
-
-  const docsOptions = server.registerTool.mock.calls.find(([name]) => name === "docs")?.[1];
-  const statusOptions = server.registerTool.mock.calls.find(([name]) => name === "status")?.[1];
-  expect(docsOptions.inputSchema.shape.operation.options).toContain("list_resources");
-  expect(docsOptions.description).toContain("resources");
-  expect(statusOptions.inputSchema.shape.operation.options).not.toContain("list_resources");
-  expect(statusOptions.description).not.toContain("read_resource");
-
-  await session.close();
-  await engine.close();
-});
-```
-
-Update `mockServer()` in the same file so `registerTool` records the options argument:
-
-```ts
-registerTool: vi.fn((name: string, _options: unknown) => {
-```
-
-- [ ] **Step 2: Write failing native adapter tests**
-
-Add to `packages/core/test/native-remote.test.ts`:
-
-```ts
-it("preserves remote input schema metadata on native tools", async () => {
-  const schema = {
-    type: "object",
-    properties: {
-      operation: { type: "string", enum: ["get_caplet", "list_resources"] },
-    },
-    required: ["operation"],
-  };
-  const fixture = client([
-    { name: "docs", title: "Docs", description: "Docs", inputSchema: schema } as never,
-  ]);
-  const service = new RemoteNativeCapletsService({ client: fixture.api, pollIntervalMs: 60_000 });
-  await service.reload();
-  expect(service.listTools()[0]?.inputSchema).toEqual(schema);
-  await service.close();
-});
-```
-
-Add a Pi test near existing tool registration tests in `packages/pi/test/pi.test.ts`:
-
-```ts
-it("registers each Caplet with its native input schema", async () => {
-  const schema = {
-    type: "object",
-    properties: { operation: { type: "string", enum: ["get_caplet", "list_resources"] } },
-    required: ["operation"],
-  };
-  const service = mockService([
-    {
-      caplet: "docs",
-      toolName: "caplets_docs",
-      title: "Docs",
-      description: "Docs",
-      promptGuidance: [],
-      inputSchema: schema,
-    },
-  ]);
-  const pi = mockPi();
-  await createCapletsPiExtension({ service })(pi);
-  expect(pi.registerTool).toHaveBeenCalledWith(expect.objectContaining({ parameters: schema }));
-});
-```
-
-Add an OpenCode test near schema/tool tests in `packages/opencode/test/opencode.test.ts`:
-
-```ts
-it("builds OpenCode args from the Caplet operation set", async () => {
-  const service = mockService([
-    {
-      caplet: "docs",
-      toolName: "caplets_docs",
-      title: "Docs",
-      description: "Docs",
-      promptGuidance: [],
-      operationNames: ["get_caplet", "list_resources"],
-    },
-  ]);
-  const hooks = await createCapletsOpenCodeHooks(service);
-  expect(Object.keys(hooks.tool ?? {})).toEqual(["caplets_docs"]);
-  expect(service.listTools()[0]?.operationNames).toEqual(["get_caplet", "list_resources"]);
-});
-```
-
-- [ ] **Step 3: Run focused tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/serve-session.test.ts test/native-remote.test.ts
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: FAIL because registered tools still use the global schema and native tools do not carry schema metadata.
-
-- [ ] **Step 4: Update capability descriptions**
-
-Change `packages/core/src/capability-description.ts`:
-
-```ts
-import type { CapletConfig } from "./config";
-
-export function capabilityDescription(server: CapletConfig): string {
-  return [
-    `${server.name} Caplet.`,
-    server.description,
-    server.backend === "mcp"
-      ? "Use get_caplet for details; use tools for actions, resources for readable context, prompts for reusable workflows, and complete for prompt/resource-template arguments."
-      : "Use get_caplet for details when needed; use search_tools or list_tools to discover downstream operations.",
-  ]
-    .filter(Boolean)
-    .join(" ");
-}
-```
-
-- [ ] **Step 5: Register backend-specific MCP tool schemas**
-
-In `packages/core/src/serve/session.ts`, import `generatedToolInputSchemaForCaplet` instead of `generatedToolInputSchema`. In both `tool.update()` and `registerTool()`, pass the backend-aware input schema:
-
-```ts
-inputSchema: generatedToolInputSchemaForCaplet(caplet),
-```
-
-For `tool.update`, include the field with title, description, callback, and enabled:
-
-```ts
-tool.update({
-  title: caplet.name,
-  description: capabilityDescription(caplet),
-  inputSchema: generatedToolInputSchemaForCaplet(caplet),
-  callback: async (request) => this.handleTool(serverId, request),
-  enabled: true,
-});
-```
-
-- [ ] **Step 6: Add native schema fields**
-
-Modify `NativeCapletTool` in `packages/core/src/native/service.ts`:
-
-```ts
-export type NativeCapletTool = {
-  caplet: string;
-  toolName: string;
-  title: string;
-  description: string;
-  promptGuidance: string[];
-  inputSchema: ReturnType<typeof generatedToolInputJsonSchemaForCaplet>;
-  operationNames: string[];
-};
-```
-
-Import schema helpers and populate local native tools:
-
-```ts
-import { generatedToolInputJsonSchemaForCaplet } from "../generated-tool-input-schema";
-
-const inputSchema = generatedToolInputJsonSchemaForCaplet(caplet);
-return {
-  caplet: caplet.server,
-  toolName,
-  title: caplet.name,
-  description: nativeCapletToolDescription(toolName, caplet),
-  promptGuidance: nativeCapletPromptGuidance(toolName, caplet),
-  inputSchema,
-  operationNames: [...inputSchema.properties.operation.enum],
-};
-```
-
-- [ ] **Step 7: Update native prompt guidance**
-
-Modify `packages/core/src/native/tools.ts`:
-
-```ts
-export function nativeCapletsSystemGuidance(toolNames: string[]): string {
-  const tools = toolNames.length > 0 ? toolNames.map((tool) => `- ${tool}`).join("\n") : "- none";
-  return [
-    "## Caplets Native Tools",
-    "",
-    "Caplets tools expose configured capability domains through progressive discovery.",
-    "",
-    "Available Caplets native tools:",
-    tools,
-    "",
-    "Flow: get_caplet when the domain is unfamiliar; use search_tools/list_tools for actions; MCP-backed Caplets may also expose resources, prompts, and completions in their tool schema.",
-    "Use fields on call_tool when a non-GraphQL downstream outputSchema allows selecting only needed structured paths.",
-  ].join("\n");
-}
-
-export function nativeCapletPromptGuidance(toolName: string, caplet: CapletConfig): string[] {
-  return caplet.backend === "mcp"
-    ? [
-        `Use ${toolName} for the ${caplet.name} Caplet capability domain.`,
-        "Prefer resources for readable context, prompts for reusable workflows, and tools for actions.",
-      ]
-    : [`Use ${toolName} for the ${caplet.name} Caplet capability domain.`];
-}
-```
-
-- [ ] **Step 8: Preserve schema metadata for remote native tools**
-
-Modify `packages/core/src/native/remote.ts`:
-
-```ts
-export type RemoteCapletsTool = {
-  name: string;
-  title?: string | undefined;
-  description?: string | undefined;
-  inputSchema?: unknown;
-};
-```
-
-In `createSdkRemoteCapletsClient().listTools()` include `inputSchema`:
-
-```ts
-...(tool.inputSchema ? { inputSchema: tool.inputSchema } : {}),
-```
-
-In `remoteToolToNativeTool`, derive operation names:
-
-```ts
-const inputSchema = isPlainObject(tool.inputSchema)
-  ? tool.inputSchema
-  : generatedToolInputJsonSchemaForCaplet({ backend: "tool" });
-const operationNames = operationNamesFromSchema(inputSchema);
-```
-
-Add helpers:
-
-```ts
-function operationNamesFromSchema(schema: Record<string, unknown>): string[] {
-  const properties = schema.properties;
-  if (!isPlainObject(properties)) return [...operations];
-  const operation = properties.operation;
-  if (!isPlainObject(operation) || !Array.isArray(operation.enum)) return [...operations];
-  return operation.enum.filter((value): value is string => typeof value === "string");
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-```
-
-Return `inputSchema` and `operationNames` from `remoteToolToNativeTool`.
-
-- [ ] **Step 9: Use native schemas in Pi and OpenCode**
-
-In `packages/pi/src/index.ts`, remove the import of `generatedToolInputJsonSchema` and change `createPiTool`:
-
-```ts
-parameters: caplet.inputSchema as ToolDefinition["parameters"],
-```
-
-In `packages/opencode/src/schema.ts`, replace the fixed schema helper with:
-
-```ts
-import { tool } from "@opencode-ai/plugin";
-import { operations } from "@caplets/core/generated-tool-input-schema";
-
-export function capletsOpenCodeArgs(operationNames: string[] = [...operations]) {
-  const enumValues = operationNames.length > 0 ? operationNames : [...operations];
-  return {
-    operation: tool.schema.enum(enumValues as [string, ...string[]]),
-    query: tool.schema.string().optional(),
-    limit: tool.schema.number().int().positive().optional(),
-    tool: tool.schema.string().optional(),
-    arguments: tool.schema.record(tool.schema.string(), tool.schema.unknown()).optional(),
-    fields: tool.schema.array(tool.schema.string().min(1)).min(1).optional(),
-    uri: tool.schema.string().optional(),
-    prompt: tool.schema.string().optional(),
-    ref: tool.schema.unknown().optional(),
-    argument: tool.schema.unknown().optional(),
-  };
-}
-```
-
-In `packages/opencode/src/hooks.ts`, call:
-
-```ts
-args: capletsOpenCodeArgs(caplet.operationNames),
-```
-
-- [ ] **Step 10: Run native and session tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/serve-session.test.ts test/native-remote.test.ts
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 11: Commit Task 2**
-
-```sh
-git add packages/core/src/capability-description.ts packages/core/src/serve/session.ts packages/core/src/native/service.ts packages/core/src/native/tools.ts packages/core/src/native/remote.ts packages/pi/src/index.ts packages/opencode/src/schema.ts packages/opencode/src/hooks.ts packages/core/test/serve-session.test.ts packages/core/test/native-remote.test.ts packages/pi/test/pi.test.ts packages/opencode/test/opencode.test.ts
-git commit -m "feat(core): expose backend-specific Caplet schemas"
-```
-
----
-
-### Task 3: Add MCP resources, prompts, completions, and cache handling to DownstreamManager
-
-**Files:**
-
-- Modify: `packages/core/src/downstream.ts`
-- Modify: `packages/core/test/fixtures/stdio-server.ts`
-- Test: `packages/core/test/downstream.test.ts`
-
-- [ ] **Step 1: Extend the stdio MCP fixture**
-
-Modify `packages/core/test/fixtures/stdio-server.ts` to import `ResourceTemplate` and register resource/prompt capabilities:
-
-```ts
-import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp";
-```
-
-Append before `await server.connect(...)`:
-
-```ts
-server.registerResource(
-  "README",
-  "file:///repo/README.md",
-  { description: "Project README", mimeType: "text/markdown" },
-  async (uri) => ({
-    contents: [{ uri: uri.href, text: "# Fixture README", mimeType: "text/markdown" }],
-  }),
-);
-
-server.registerResource(
-  "Repository file",
-  new ResourceTemplate("file:///repo/{path}", {
-    list: async () => ({
-      resources: [
-        { uri: "file:///repo/src/index.ts", name: "src/index.ts", mimeType: "text/typescript" },
-      ],
-    }),
-    complete: {
-      path: (value) => ["README.md", "src/index.ts"].filter((path) => path.startsWith(value)),
-    },
-  }),
-  { description: "Read a repository file", mimeType: "text/plain" },
-  async (uri) => ({
-    contents: [{ uri: uri.href, text: `content:${uri.href}`, mimeType: "text/plain" }],
-  }),
-);
-
-server.registerPrompt(
-  "review_issue",
-  {
-    description: "Review an issue before implementation.",
-    argsSchema: { issueId: z.string().describe("Issue ID") },
-  },
-  ({ issueId }) => ({
-    messages: [{ role: "user", content: { type: "text", text: `Review ${issueId}` } }],
-  }),
-);
-```
-
-- [ ] **Step 2: Write failing downstream tests**
-
-Add to `packages/core/test/downstream.test.ts`:
-
-```ts
-it("lists, searches, and reads MCP resources and templates", async () => {
-  const fixture = join(fixturesDir, "stdio-server.ts");
-  const config = parseConfig({
-    mcpServers: {
-      fixture: {
-        name: "Fixture",
-        description: "Fixture server.",
-        command: "pnpm",
-        args: ["exec", "tsx", fixture],
-      },
-    },
-  });
-  const manager = new DownstreamManager(new ServerRegistry(config));
-  const server = config.mcpServers.fixture!;
-  try {
-    const resources = await manager.listResources(server);
-    expect(resources.map((resource) => resource.uri)).toContain("file:///repo/README.md");
-    expect(manager.searchResources(server, resources, "readme", 10)).toEqual([
-      expect.objectContaining({ kind: "resource", uri: "file:///repo/README.md" }),
-    ]);
-
-    const templates = await manager.listResourceTemplates(server);
-    expect(templates).toEqual([expect.objectContaining({ uriTemplate: "file:///repo/{path}" })]);
-
-    const read = await manager.readResource(server, "file:///repo/README.md");
-    expect(read).toMatchObject({
-      contents: [{ uri: "file:///repo/README.md", text: "# Fixture README" }],
-    });
-  } finally {
-    await manager.close();
-  }
-});
-
-it("lists, searches, gets prompts, and forwards completions", async () => {
-  const fixture = join(fixturesDir, "stdio-server.ts");
-  const config = parseConfig({
-    mcpServers: {
-      fixture: {
-        name: "Fixture",
-        description: "Fixture server.",
-        command: "pnpm",
-        args: ["exec", "tsx", fixture],
-      },
-    },
-  });
-  const manager = new DownstreamManager(new ServerRegistry(config));
-  const server = config.mcpServers.fixture!;
-  try {
-    const prompts = await manager.listPrompts(server);
-    expect(prompts).toEqual([expect.objectContaining({ name: "review_issue" })]);
-    expect(manager.searchPrompts(server, prompts, "issue", 10)).toEqual([
-      expect.objectContaining({ prompt: "review_issue" }),
-    ]);
-
-    const prompt = await manager.getPrompt(server, "review_issue", { issueId: "CAP-123" });
-    expect(prompt).toMatchObject({
-      messages: [{ role: "user", content: { text: "Review CAP-123" } }],
-    });
-
-    const completion = await manager.complete(server, {
-      ref: { type: "resourceTemplate", uri: "file:///repo/{path}" },
-      argument: { name: "path", value: "src/" },
-    });
-    expect(completion).toMatchObject({ completion: { values: ["src/index.ts"] } });
-  } finally {
-    await manager.close();
-  }
-});
-
-it("returns UNSUPPORTED_CAPABILITY when the server does not advertise resources", async () => {
-  const config = parseConfig({
-    mcpServers: { empty: { name: "Empty", description: "No resources.", command: "node" } },
-  });
-  const server = config.mcpServers.empty!;
-  const manager = new DownstreamManager(new ServerRegistry(config));
-  vi.spyOn(manager as never, "connect").mockResolvedValue({
-    client: { getServerCapabilities: () => ({ tools: {} }) },
-  } as never);
-  await expect(manager.listResources(server)).rejects.toMatchObject({
-    code: "UNSUPPORTED_CAPABILITY",
-  });
-});
-```
-
-- [ ] **Step 3: Run downstream tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/downstream.test.ts
-```
-
-Expected: FAIL because `DownstreamManager` has no resource/prompt/completion methods.
-
-- [ ] **Step 4: Add MCP imports, cache fields, and compact types**
-
-Modify `packages/core/src/downstream.ts` imports:
-
-```ts
-import {
-  CompatibilityCallToolResultSchema,
-  CompleteResultSchema,
-  type CompleteRequestParams,
-  ListPromptsResultSchema,
-  ListResourceTemplatesResultSchema,
-  ListResourcesResultSchema,
-  PromptListChangedNotificationSchema,
-  type Prompt,
-  ReadResourceResultSchema,
-  ResourceListChangedNotificationSchema,
-  type Resource,
-  type ResourceTemplate as McpResourceTemplate,
-  ToolListChangedNotificationSchema,
-  type Tool,
-} from "@modelcontextprotocol/sdk/types";
-```
-
-Extend `ManagedConnection`:
-
-```ts
-  resources?: Resource[];
-  resourcesFetchedAt?: number;
-  resourceTemplates?: McpResourceTemplate[];
-  resourceTemplatesFetchedAt?: number;
-  prompts?: Prompt[];
-  promptsFetchedAt?: number;
-```
-
-Add compact types near `CompactTool`:
-
-```ts
-export type CompactResource = {
-  id: string;
-  kind: "resource";
-  uri: string;
-  name?: string;
-  description?: string;
-  mimeType?: string;
-  size?: number;
-};
-export type CompactResourceTemplate = {
-  id: string;
-  kind: "resourceTemplate";
-  uriTemplate: string;
-  name?: string;
-  description?: string;
-  mimeType?: string;
-};
-export type CompactPrompt = {
-  id: string;
-  prompt: string;
-  description?: string;
-  arguments?: Prompt["arguments"];
-};
-```
-
-- [ ] **Step 5: Add notification-based invalidation**
-
-Inside `connect()` before `await client.connect(...)`, register handlers:
-
-```ts
-client.setNotificationHandler(ToolListChangedNotificationSchema, () => {
-  connection.tools = undefined;
-  connection.toolsFetchedAt = undefined;
-});
-client.setNotificationHandler(ResourceListChangedNotificationSchema, () => {
-  connection.resources = undefined;
-  connection.resourcesFetchedAt = undefined;
-  connection.resourceTemplates = undefined;
-  connection.resourceTemplatesFetchedAt = undefined;
-});
-client.setNotificationHandler(PromptListChangedNotificationSchema, () => {
-  connection.prompts = undefined;
-  connection.promptsFetchedAt = undefined;
-});
-```
-
-- [ ] **Step 6: Add capability assertion helpers**
-
-Add helpers in `DownstreamManager`:
-
-```ts
-private async assertCapability(server: CapletServerConfig, capability: "resources" | "prompts" | "completions"): Promise<ManagedConnection> {
-  const connection = await this.connect(server);
-  const capabilities = connection.client.getServerCapabilities();
-  if (!capabilities?.[capability]) {
-    throw new CapletsError(
-      "UNSUPPORTED_CAPABILITY",
-      `${server.server} does not advertise MCP ${capability}`,
-      { server: server.server, capability },
-    );
-  }
-  return connection;
-}
-
-private isCacheFresh(fetchedAt: number | undefined, ttlMs: number): boolean {
-  return fetchedAt !== undefined && ttlMs > 0 && Date.now() - fetchedAt <= ttlMs;
-}
-```
-
-- [ ] **Step 7: Implement list/read/get/complete methods**
-
-Add public methods to `DownstreamManager`:
-
-```ts
-async listResources(server: CapletServerConfig, force = false): Promise<Resource[]> {
-  const connection = await this.assertCapability(server, "resources");
-  if (!force && connection.resources && this.isCacheFresh(connection.resourcesFetchedAt, server.toolCacheTtlMs)) {
-    return connection.resources;
-  }
-  const resources: Resource[] = [];
-  let cursor: string | undefined;
-  do {
-    const result = await connection.client.listResources(cursor ? { cursor } : undefined, { timeout: server.startupTimeoutMs });
-    resources.push(...(result.resources ?? []));
-    cursor = result.nextCursor;
-  } while (cursor);
-  connection.resources = resources;
-  connection.resourcesFetchedAt = Date.now();
-  return resources;
-}
-
-async listResourceTemplates(server: CapletServerConfig, force = false): Promise<McpResourceTemplate[]> {
-  const connection = await this.assertCapability(server, "resources");
-  if (!force && connection.resourceTemplates && this.isCacheFresh(connection.resourceTemplatesFetchedAt, server.toolCacheTtlMs)) {
-    return connection.resourceTemplates;
-  }
-  const templates: McpResourceTemplate[] = [];
-  let cursor: string | undefined;
-  do {
-    const result = await connection.client.listResourceTemplates(cursor ? { cursor } : undefined, { timeout: server.startupTimeoutMs });
-    templates.push(...(result.resourceTemplates ?? []));
-    cursor = result.nextCursor;
-  } while (cursor);
-  connection.resourceTemplates = templates;
-  connection.resourceTemplatesFetchedAt = Date.now();
-  return templates;
-}
-
-async readResource(server: CapletServerConfig, uri: string) {
-  const connection = await this.assertCapability(server, "resources");
-  try {
-    return await connection.client.readResource({ uri }, { timeout: server.callTimeoutMs });
-  } catch (error) {
-    throw new CapletsError("DOWNSTREAM_RESOURCE_ERROR", `Downstream resource read failed for ${server.server}/${uri}`, toSafeError(error));
-  }
-}
-
-async listPrompts(server: CapletServerConfig, force = false): Promise<Prompt[]> {
-  const connection = await this.assertCapability(server, "prompts");
-  if (!force && connection.prompts && this.isCacheFresh(connection.promptsFetchedAt, server.toolCacheTtlMs)) {
-    return connection.prompts;
-  }
-  const prompts: Prompt[] = [];
-  let cursor: string | undefined;
-  do {
-    const result = await connection.client.listPrompts(cursor ? { cursor } : undefined, { timeout: server.startupTimeoutMs });
-    prompts.push(...(result.prompts ?? []));
-    cursor = result.nextCursor;
-  } while (cursor);
-  connection.prompts = prompts;
-  connection.promptsFetchedAt = Date.now();
-  return prompts;
-}
-
-async getPrompt(server: CapletServerConfig, promptName: string, args: Record<string, unknown>) {
-  const prompts = await this.listPrompts(server);
-  if (!prompts.some((prompt) => prompt.name === promptName)) {
-    throw new CapletsError("PROMPT_NOT_FOUND", `Prompt ${promptName} was not found on ${server.server}`);
-  }
-  const connection = await this.assertCapability(server, "prompts");
-  try {
-    return await connection.client.getPrompt({ name: promptName, arguments: stringifyPromptArgs(args) }, { timeout: server.callTimeoutMs });
-  } catch (error) {
-    throw new CapletsError("DOWNSTREAM_PROMPT_ERROR", `Downstream prompt failed for ${server.server}/${promptName}`, toSafeError(error));
-  }
-}
-
-async complete(server: CapletServerConfig, request: { ref: { type: "prompt"; name: string } | { type: "resourceTemplate"; uri: string }; argument: { name: string; value: string } }) {
-  const connection = await this.assertCapability(server, "completions");
-  const params: CompleteRequestParams = {
-    ref: request.ref.type === "prompt" ? { type: "ref/prompt", name: request.ref.name } : { type: "ref/resource", uri: request.ref.uri },
-    argument: request.argument,
-  };
-  try {
-    return await connection.client.complete(params, { timeout: server.callTimeoutMs });
-  } catch (error) {
-    throw new CapletsError("DOWNSTREAM_COMPLETION_ERROR", `Downstream completion failed for ${server.server}`, toSafeError(error));
-  }
-}
-```
-
-Add helper:
-
-```ts
-function stringifyPromptArgs(args: Record<string, unknown>): Record<string, string> {
-  return Object.fromEntries(
-    Object.entries(args).map(([key, value]) => [
-      key,
-      typeof value === "string" ? value : JSON.stringify(value),
-    ]),
-  );
-}
-```
-
-- [ ] **Step 8: Add compact and search helpers**
-
-Add methods:
-
-```ts
-compactResource(server: CapletServerConfig, resource: Resource): CompactResource {
-  return {
-    id: server.server,
-    kind: "resource",
-    uri: resource.uri,
-    ...(resource.name ? { name: resource.name } : {}),
-    ...(resource.description ? { description: resource.description } : {}),
-    ...(resource.mimeType ? { mimeType: resource.mimeType } : {}),
-    ...(typeof resource.size === "number" ? { size: resource.size } : {}),
-  };
-}
-
-compactResourceTemplate(server: CapletServerConfig, template: McpResourceTemplate): CompactResourceTemplate {
-  return {
-    id: server.server,
-    kind: "resourceTemplate",
-    uriTemplate: template.uriTemplate,
-    ...(template.name ? { name: template.name } : {}),
-    ...(template.description ? { description: template.description } : {}),
-    ...(template.mimeType ? { mimeType: template.mimeType } : {}),
-  };
-}
-
-compactPrompt(server: CapletServerConfig, prompt: Prompt): CompactPrompt {
-  return {
-    id: server.server,
-    prompt: prompt.name,
-    ...(prompt.description ? { description: prompt.description } : {}),
-    ...(prompt.arguments ? { arguments: prompt.arguments } : {}),
-  };
-}
-
-searchResources(server: CapletServerConfig, resources: Resource[], query: string, limit: number): Array<CompactResource | CompactResourceTemplate> {
-  const lower = query.toLocaleLowerCase();
-  return resources
-    .map((resource) => this.compactResource(server, resource))
-    .filter((resource) => [resource.uri, resource.name, resource.description, resource.mimeType].some((value) => value?.toLocaleLowerCase().includes(lower)))
-    .slice(0, limit);
-}
-
-searchResourceTemplates(server: CapletServerConfig, templates: McpResourceTemplate[], query: string, limit: number): CompactResourceTemplate[] {
-  const lower = query.toLocaleLowerCase();
-  return templates
-    .map((template) => this.compactResourceTemplate(server, template))
-    .filter((template) => [template.uriTemplate, template.name, template.description, template.mimeType].some((value) => value?.toLocaleLowerCase().includes(lower)))
-    .slice(0, limit);
-}
-
-searchPrompts(server: CapletServerConfig, prompts: Prompt[], query: string, limit: number): CompactPrompt[] {
-  const lower = query.toLocaleLowerCase();
-  return prompts
-    .map((prompt) => this.compactPrompt(server, prompt))
-    .filter((prompt) => [prompt.prompt, prompt.description, ...(prompt.arguments ?? []).flatMap((arg) => [arg.name, arg.description])].some((value) => value?.toLocaleLowerCase().includes(lower)))
-    .slice(0, limit);
-}
-```
-
-- [ ] **Step 9: Enrich `checkServer` with MCP capabilities and counts**
-
-Change `checkServer` so it still refreshes tools and additionally reports best-effort counts:
-
-```ts
-const connection = await this.connect(server);
-const capabilities = connection.client.getServerCapabilities() ?? {};
-const tools = await this.refreshTools(server, true);
-const result = {
-  id: server.server,
-  status: "available",
-  capabilities: {
-    tools: Boolean(capabilities.tools),
-    resources: Boolean(capabilities.resources),
-    resourceTemplates: Boolean(capabilities.resources),
-    prompts: Boolean(capabilities.prompts),
-    completions: Boolean(capabilities.completions),
-  },
-  toolCount: tools.length,
-  elapsedMs: Date.now() - startedAt,
-};
-if (capabilities.resources) {
-  Object.assign(result, {
-    resourceCount: (await this.listResources(server, true)).length,
-    resourceTemplateCount: (await this.listResourceTemplates(server, true)).length,
-  });
-}
-if (capabilities.prompts) {
-  Object.assign(result, { promptCount: (await this.listPrompts(server, true)).length });
-}
-return result;
-```
-
-- [ ] **Step 10: Run downstream tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/downstream.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 11: Commit Task 3**
-
-```sh
-git add packages/core/src/downstream.ts packages/core/test/fixtures/stdio-server.ts packages/core/test/downstream.test.ts
-git commit -m "feat(core): add MCP resource and prompt forwarding"
-```
-
----
-
-### Task 4: Dispatch MCP operations through generated Caplet tools
-
-**Files:**
-
-- Modify: `packages/core/src/tools.ts`
-- Test: `packages/core/test/tools.test.ts`
-
-- [ ] **Step 1: Write failing handler tests**
-
-Add to `packages/core/test/tools.test.ts` inside `describe("generated tool handlers", ...)`:
-
-```ts
-it("lists and searches MCP resources through handleServerTool", async () => {
-  const downstream = {
-    listResources: vi.fn().mockResolvedValue([
-      {
-        uri: "file:///repo/README.md",
-        name: "README",
-        description: "Docs",
-        mimeType: "text/markdown",
-      },
-    ]),
-    listResourceTemplates: vi
-      .fn()
-      .mockResolvedValue([
-        { uriTemplate: "file:///repo/{path}", name: "File", description: "Repo file" },
-      ]),
-    compactResource: (_server: unknown, resource: unknown) => ({
-      id: "alpha",
-      kind: "resource",
-      ...(resource as object),
-    }),
-    compactResourceTemplate: (_server: unknown, template: unknown) => ({
-      id: "alpha",
-      kind: "resourceTemplate",
-      ...(template as object),
-    }),
-    searchResources: vi.fn((_server, resources) =>
-      resources.map((resource: unknown) => ({
-        id: "alpha",
-        kind: "resource",
-        ...(resource as object),
-      })),
-    ),
-    searchResourceTemplates: vi.fn((_server, templates) =>
-      templates.map((template: unknown) => ({
-        id: "alpha",
-        kind: "resourceTemplate",
-        ...(template as object),
-      })),
-    ),
-  } as unknown as DownstreamManager;
-
-  const listed = (await handleServerTool(
-    server,
-    { operation: "list_resources" },
-    registry,
-    downstream,
-  )) as any;
-  expect(listed.structuredContent.result.resources).toEqual([
-    expect.objectContaining({ uri: "file:///repo/README.md" }),
-  ]);
-  expect(listed.structuredContent.result.resourceTemplates).toEqual([
-    expect.objectContaining({ uriTemplate: "file:///repo/{path}" }),
-  ]);
-
-  const searched = (await handleServerTool(
-    server,
-    { operation: "search_resources", query: "readme" },
-    registry,
-    downstream,
-  )) as any;
-  expect(searched.structuredContent.result.matches).toEqual([
-    expect.objectContaining({ kind: "resource" }),
-    expect.objectContaining({ kind: "resourceTemplate" }),
-  ]);
-});
-
-it("reads resources, gets prompts, and completes with Caplets metadata", async () => {
-  const downstream = {
-    readResource: vi
-      .fn()
-      .mockResolvedValue({ contents: [{ uri: "file:///repo/README.md", text: "hello" }] }),
-    getPrompt: vi.fn().mockResolvedValue({
-      messages: [{ role: "user", content: { type: "text", text: "Review CAP-1" } }],
-    }),
-    complete: vi.fn().mockResolvedValue({ completion: { values: ["CAP-1"] } }),
-  } as unknown as DownstreamManager;
-
-  const read = (await handleServerTool(
-    server,
-    { operation: "read_resource", uri: "file:///repo/README.md" },
-    registry,
-    downstream,
-  )) as any;
-  expect(read.contents[0].text).toBe("hello");
-  expect(read._meta.caplets).toMatchObject({
-    operation: "read_resource",
-    uri: "file:///repo/README.md",
-  });
-
-  const prompt = (await handleServerTool(
-    server,
-    { operation: "get_prompt", prompt: "review_issue", arguments: { issueId: "CAP-1" } },
-    registry,
-    downstream,
-  )) as any;
-  expect(prompt.messages[0].content.text).toBe("Review CAP-1");
-  expect(prompt._meta.caplets).toMatchObject({ operation: "get_prompt", prompt: "review_issue" });
-
-  const completion = (await handleServerTool(
-    server,
-    {
-      operation: "complete",
-      ref: { type: "prompt", name: "review_issue" },
-      argument: { name: "issueId", value: "CAP-" },
-    },
-    registry,
-    downstream,
-  )) as any;
-  expect(completion.completion.values).toEqual(["CAP-1"]);
-  expect(completion._meta.caplets).toMatchObject({ operation: "complete" });
-});
-```
-
-- [ ] **Step 2: Run handler tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: FAIL because `handleServerTool` does not dispatch MCP-only operations and metadata type lacks `uri`/`prompt`.
-
-- [ ] **Step 3: Extend metadata**
-
-In `packages/core/src/tools.ts`, update `CapletResultMetadata`:
-
-```ts
-  uri?: string;
-  prompt?: string;
-```
-
-Update `metadataFor` signature:
-
-```ts
-export function metadataFor(
-  server: CapletConfig,
-  operation: RequiredOperationRequest["operation"],
-  target?: string | { tool?: string; uri?: string; prompt?: string },
-  startedAt?: number,
-): CapletResultMetadata {
-  const targetFields = typeof target === "string" ? { tool: target } : (target ?? {});
-  return {
-    id: server.server,
-    name: server.name,
-    backend: server.backend,
-    operation,
-    ...targetFields,
-    status: "ok",
-    ...(startedAt === undefined ? {} : { elapsedMs: Date.now() - startedAt }),
-  };
-}
-```
-
-Add a generic annotation helper:
-
-```ts
-export function annotateMcpResult<T extends object>(result: T, metadata: CapletResultMetadata): T {
-  const existingMeta = (result as { _meta?: unknown })._meta;
-  return {
-    ...result,
-    _meta: {
-      ...(isPlainObject(existingMeta) ? existingMeta : {}),
-      caplets: metadata,
-    },
-  };
-}
-```
-
-- [ ] **Step 4: Dispatch MCP-only operations**
-
-Add switch cases in `handleServerTool` after `call_tool`:
-
-```ts
-case "list_resources": {
-  const backend = mcpBackendFor(server, downstream);
-  const resources = await backend.listResources(server as never);
-  const templates = await backend.listResourceTemplates(server as never);
-  const limit = parsed.limit ?? resources.length + templates.length;
-  return jsonResult(
-    {
-      id: server.server,
-      name: server.name,
-      resources: resources.slice(0, limit).map((resource) => backend.compactResource(server as never, resource)),
-      resourceTemplates: templates.slice(0, Math.max(0, limit - resources.length)).map((template) => backend.compactResourceTemplate(server as never, template)),
-    },
-    metadataFor(server, "list_resources", undefined, startedAt),
-  );
-}
-case "search_resources": {
-  const backend = mcpBackendFor(server, downstream);
-  const resources = await backend.listResources(server as never);
-  const templates = await backend.listResourceTemplates(server as never);
-  const limit = parsed.limit ?? registry.config.options.defaultSearchLimit;
-  const resourceMatches = backend.searchResources(server as never, resources, parsed.query, limit);
-  const templateMatches = backend.searchResourceTemplates(server as never, templates, parsed.query, Math.max(0, limit - resourceMatches.length));
-  return jsonResult({ id: server.server, name: server.name, query: parsed.query, matches: [...resourceMatches, ...templateMatches] }, metadataFor(server, "search_resources", undefined, startedAt));
-}
-case "list_resource_templates": {
-  const backend = mcpBackendFor(server, downstream);
-  const templates = await backend.listResourceTemplates(server as never);
-  const limit = parsed.limit ?? templates.length;
-  return jsonResult({ id: server.server, name: server.name, resourceTemplates: templates.slice(0, limit).map((template) => backend.compactResourceTemplate(server as never, template)) }, metadataFor(server, "list_resource_templates", undefined, startedAt));
-}
-case "read_resource": {
-  const result = await mcpBackendFor(server, downstream).readResource(server as never, parsed.uri);
-  return annotateMcpResult(result, metadataFor(server, "read_resource", { uri: parsed.uri }, startedAt));
-}
-case "list_prompts": {
-  const backend = mcpBackendFor(server, downstream);
-  const prompts = await backend.listPrompts(server as never);
-  const limit = parsed.limit ?? prompts.length;
-  return jsonResult({ id: server.server, name: server.name, prompts: prompts.slice(0, limit).map((prompt) => backend.compactPrompt(server as never, prompt)) }, metadataFor(server, "list_prompts", undefined, startedAt));
-}
-case "search_prompts": {
-  const backend = mcpBackendFor(server, downstream);
-  const prompts = await backend.listPrompts(server as never);
-  const limit = parsed.limit ?? registry.config.options.defaultSearchLimit;
-  return jsonResult({ id: server.server, name: server.name, query: parsed.query, prompts: backend.searchPrompts(server as never, prompts, parsed.query, limit) }, metadataFor(server, "search_prompts", undefined, startedAt));
-}
-case "get_prompt": {
-  const result = await mcpBackendFor(server, downstream).getPrompt(server as never, parsed.prompt, parsed.arguments);
-  return annotateMcpResult(result, metadataFor(server, "get_prompt", { prompt: parsed.prompt }, startedAt));
-}
-case "complete": {
-  const result = await mcpBackendFor(server, downstream).complete(server as never, { ref: parsed.ref, argument: parsed.argument });
-  return annotateMcpResult(result, metadataFor(server, "complete", undefined, startedAt));
-}
-```
-
-Add helper near `backendFor`:
-
-```ts
-function mcpBackendFor(server: CapletConfig, downstream: DownstreamManager) {
-  if (server.backend !== "mcp") {
-    throw new CapletsError(
-      "UNSUPPORTED_OPERATION",
-      "MCP resource, prompt, and completion operations require an MCP-backed Caplet",
-    );
-  }
-  return downstream;
-}
-```
-
-- [ ] **Step 5: Run tools tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit Task 4**
-
-```sh
-git add packages/core/src/tools.ts packages/core/test/tools.test.ts
-git commit -m "feat(core): dispatch MCP resources and prompts"
-```
-
----
-
-### Task 5: Add CLI and remote-control operation support
-
-**Files:**
-
-- Modify: `packages/core/src/cli.ts`
-- Modify: `packages/core/src/remote-control/types.ts`
-- Modify: `packages/core/src/remote-control/dispatch.ts`
-- Test: `packages/core/test/cli.test.ts`
-- Test: `packages/core/test/cli-remote.test.ts`
-- Test: `packages/core/test/remote-control-dispatch.test.ts`
-
-- [ ] **Step 1: Write failing CLI routing tests**
-
-Add to `packages/core/test/cli-remote.test.ts`:
-
-```ts
-it("routes read-resource through remote control", async () => {
-  const requests: unknown[] = [];
-  const out: string[] = [];
-  const fetch = vi.fn(async (url: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
-    requests.push({ url: String(url), body: init?.body });
-    return Response.json({
-      ok: true,
-      result: { contents: [{ uri: "file:///repo/README.md", text: "hello" }] },
-    });
-  });
-
-  await runCli(["read-resource", "docs", "file:///repo/README.md", "--format", "json"], {
-    env: { CAPLETS_MODE: "remote", CAPLETS_SERVER_URL: "http://127.0.0.1:5387/caplets" },
-    fetch,
-    writeOut: (value) => out.push(value),
-  });
-
-  expect(requests).toEqual([
-    {
-      url: "http://127.0.0.1:5387/caplets/control",
-      body: JSON.stringify({
-        command: "read_resource",
-        arguments: {
-          caplet: "docs",
-          request: { operation: "read_resource", uri: "file:///repo/README.md" },
-        },
-      }),
-    },
-  ]);
-  expect(JSON.parse(out.join(""))).toEqual({
-    contents: [{ uri: "file:///repo/README.md", text: "hello" }],
-  });
-});
-```
-
-Add to `packages/core/test/remote-control-dispatch.test.ts`:
-
-```ts
-it("accepts new MCP engine commands through remote dispatch", async () => {
-  const context = testContext({
-    mcpServers: { docs: { name: "Docs", description: "Docs.", command: "node" } },
-  });
-  const response = await dispatchRemoteCliRequest(
-    {
-      command: "list_resources",
-      arguments: { caplet: "docs", request: { operation: "list_resources" } },
-    },
-    context,
-  );
-  expect(response).toMatchObject({
-    ok: false,
-    error: { code: expect.stringMatching(/SERVER_|UNSUPPORTED_|DOWNSTREAM_/u) },
-  });
-});
-```
-
-- [ ] **Step 2: Write failing local CLI command tests**
-
-Add to `packages/core/test/cli.test.ts`:
-
-```ts
-it("prints help with MCP resource and prompt commands", async () => {
-  const out: string[] = [];
-  await runCli(["--help"], {
-    writeOut: (value) => out.push(value),
-    writeErr: (value) => out.push(value),
-  });
-  const text = out.join("");
-  expect(text).toContain("list-resources");
-  expect(text).toContain("read-resource");
-  expect(text).toContain("list-prompts");
-  expect(text).toContain("get-prompt");
-  expect(text).toContain("complete");
-});
-```
-
-- [ ] **Step 3: Run CLI tests to verify red**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli.test.ts test/cli-remote.test.ts test/remote-control-dispatch.test.ts
-```
-
-Expected: FAIL because commands and remote command names do not exist.
-
-- [ ] **Step 4: Extend remote-control command types and dispatch set**
-
-In `packages/core/src/remote-control/types.ts`, add these to `RemoteCliCommand` after `call_tool`:
-
-```ts
-  | "list_resources"
-  | "search_resources"
-  | "list_resource_templates"
-  | "read_resource"
-  | "list_prompts"
-  | "search_prompts"
-  | "get_prompt"
-  | "complete"
-```
-
-In `packages/core/src/remote-control/dispatch.ts`, add the same strings to `ENGINE_COMMANDS`.
-
-- [ ] **Step 5: Route new operations from CLI remote mode**
-
-In `packages/core/src/cli.ts`, extend `remoteCommandForOperation` switch:
-
-```ts
-    case "list_resources":
-    case "search_resources":
-    case "list_resource_templates":
-    case "read_resource":
-    case "list_prompts":
-    case "search_prompts":
-    case "get_prompt":
-    case "complete":
-      return operation;
-```
-
-- [ ] **Step 6: Add CLI commands**
-
-In `packages/core/src/cli.ts`, add commands after `call-tool`:
-
-```ts
-program
-  .command("list-resources")
-  .description("List MCP resources for a configured MCP Caplet.")
-  .argument("<caplet>")
-  .option("--limit <n>", "maximum number of resources to return", parsePositiveInteger)
-  .option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat)
-  .action(async (caplet: string, options: { limit?: number; format?: CliOutputFormat }) => {
-    await executeOperation(
-      caplet,
-      options.limit === undefined
-        ? { operation: "list_resources" }
-        : { operation: "list_resources", limit: options.limit },
-      {
-        writeOut,
-        writeErr,
-        setExitCode,
-        authDir: io.authDir,
-        env,
-        remote: remoteClientForCli(io),
-        format: options.format,
-      },
-    );
-  });
-
-program
-  .command("search-resources")
-  .description("Search MCP resources and resource templates for a configured MCP Caplet.")
-  .argument("<caplet>")
-  .argument("<query>")
-  .option("--limit <n>", "maximum number of matches to return", parsePositiveInteger)
-  .option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat)
-  .action(
-    async (
-      caplet: string,
-      query: string,
-      options: { limit?: number; format?: CliOutputFormat },
-    ) => {
-      await executeOperation(
-        caplet,
-        options.limit === undefined
-          ? { operation: "search_resources", query }
-          : { operation: "search_resources", query, limit: options.limit },
-        {
-          writeOut,
-          writeErr,
-          setExitCode,
-          authDir: io.authDir,
-          env,
-          remote: remoteClientForCli(io),
-          format: options.format,
-        },
-      );
-    },
-  );
-
-program
-  .command("list-resource-templates")
-  .description("List MCP resource templates for a configured MCP Caplet.")
-  .argument("<caplet>")
-  .option("--limit <n>", "maximum number of templates to return", parsePositiveInteger)
-  .option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat)
-  .action(async (caplet: string, options: { limit?: number; format?: CliOutputFormat }) => {
-    await executeOperation(
-      caplet,
-      options.limit === undefined
-        ? { operation: "list_resource_templates" }
-        : { operation: "list_resource_templates", limit: options.limit },
-      {
-        writeOut,
-        writeErr,
-        setExitCode,
-        authDir: io.authDir,
-        env,
-        remote: remoteClientForCli(io),
-        format: options.format,
-      },
-    );
-  });
-
-program
-  .command("read-resource")
-  .description("Read one MCP resource by URI.")
-  .argument("<caplet>")
-  .argument("<uri>")
-  .option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat)
-  .action(async (caplet: string, uri: string, options: { format?: CliOutputFormat }) => {
-    await executeOperation(
-      caplet,
-      { operation: "read_resource", uri },
-      {
-        writeOut,
-        writeErr,
-        setExitCode,
-        authDir: io.authDir,
-        env,
-        remote: remoteClientForCli(io),
-        format: options.format,
-      },
-    );
-  });
-
-program
-  .command("list-prompts")
-  .description("List MCP prompts for a configured MCP Caplet.")
-  .argument("<caplet>")
-  .option("--limit <n>", "maximum number of prompts to return", parsePositiveInteger)
-  .option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat)
-  .action(async (caplet: string, options: { limit?: number; format?: CliOutputFormat }) => {
-    await executeOperation(
-      caplet,
-      options.limit === undefined
-        ? { operation: "list_prompts" }
-        : { operation: "list_prompts", limit: options.limit },
-      {
-        writeOut,
-        writeErr,
-        setExitCode,
-        authDir: io.authDir,
-        env,
-        remote: remoteClientForCli(io),
-        format: options.format,
-      },
-    );
-  });
-
-program
-  .command("search-prompts")
-  .description("Search MCP prompts for a configured MCP Caplet.")
-  .argument("<caplet>")
-  .argument("<query>")
-  .option("--limit <n>", "maximum number of prompts to return", parsePositiveInteger)
-  .option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat)
-  .action(
-    async (
-      caplet: string,
-      query: string,
-      options: { limit?: number; format?: CliOutputFormat },
-    ) => {
-      await executeOperation(
-        caplet,
-        options.limit === undefined
-          ? { operation: "search_prompts", query }
-          : { operation: "search_prompts", query, limit: options.limit },
-        {
-          writeOut,
-          writeErr,
-          setExitCode,
-          authDir: io.authDir,
-          env,
-          remote: remoteClientForCli(io),
-          format: options.format,
-        },
-      );
-    },
-  );
-
-program
-  .command("get-prompt")
-  .description("Get one MCP prompt by name.")
-  .argument("<caplet.prompt>", "qualified target, split on the first dot")
-  .option("--args <json-object>", "JSON object of prompt arguments")
-  .option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat)
-  .action(async (target: string, options: { args?: string; format?: CliOutputFormat }) => {
-    const { caplet, tool: prompt } = parseQualifiedTarget(target);
-    await executeOperation(
-      caplet,
-      {
-        operation: "get_prompt",
-        prompt,
-        arguments: parseJsonObjectOption(options.args, "get-prompt --args"),
-      },
-      {
-        writeOut,
-        writeErr,
-        setExitCode,
-        authDir: io.authDir,
-        env,
-        remote: remoteClientForCli(io),
-        format: options.format,
-      },
-    );
-  });
-
-program
-  .command("complete")
-  .description("Complete an MCP prompt or resource-template argument.")
-  .argument("<caplet>")
-  .requiredOption("--argument <name>", "argument name")
-  .option("--value <value>", "argument prefix", "")
-  .option("--prompt <name>", "prompt name to complete")
-  .option("--resource-template <uri-template>", "resource template URI to complete")
-  .option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat)
-  .action(
-    async (
-      caplet: string,
-      options: {
-        argument: string;
-        value: string;
-        prompt?: string;
-        resourceTemplate?: string;
-        format?: CliOutputFormat;
-      },
-    ) => {
-      const ref = completionRefFromOptions(options);
-      await executeOperation(
-        caplet,
-        { operation: "complete", ref, argument: { name: options.argument, value: options.value } },
-        {
-          writeOut,
-          writeErr,
-          setExitCode,
-          authDir: io.authDir,
-          env,
-          remote: remoteClientForCli(io),
-          format: options.format,
-        },
-      );
-    },
-  );
-```
-
-Add helpers:
-
-```ts
-function parseJsonObjectOption(value: string | undefined, label: string): Record<string, unknown> {
-  if (value === undefined) return {};
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(value);
-  } catch (error) {
-    throw new CapletsError("REQUEST_INVALID", `${label} must be valid JSON`, error);
-  }
-  if (!isPlainObject(parsed)) {
-    throw new CapletsError("REQUEST_INVALID", `${label} must be a JSON object`);
-  }
-  return parsed;
-}
-
-function completionRefFromOptions(options: { prompt?: string; resourceTemplate?: string }) {
-  if (options.prompt && options.resourceTemplate) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "complete accepts either --prompt or --resource-template, not both",
-    );
-  }
-  if (options.prompt) return { type: "prompt", name: options.prompt };
-  if (options.resourceTemplate) return { type: "resourceTemplate", uri: options.resourceTemplate };
-  throw new CapletsError("REQUEST_INVALID", "complete requires --prompt or --resource-template");
-}
-```
-
-- [ ] **Step 7: Add CLI human summaries**
-
-Extend `markdownSummaryForOperation` and `plainSummaryForOperation` with cases for the new operations. Use these concrete summaries:
-
-```ts
-case "list_resources":
-case "search_resources": {
-  const resources = Array.isArray(payload.resources) ? payload.resources : [];
-  const templates = Array.isArray(payload.resourceTemplates) ? payload.resourceTemplates : [];
-  const matches = Array.isArray(payload.matches) ? payload.matches : [...resources, ...templates];
-  return [`## MCP resources for \`${id}\``, "", `${matches.length} item${matches.length === 1 ? "" : "s"} found.`, "", ...formatResourceLines(matches, "markdown")].join("\n");
-}
-case "list_resource_templates": {
-  const templates = Array.isArray(payload.resourceTemplates) ? payload.resourceTemplates : [];
-  return [`## MCP resource templates for \`${id}\``, "", ...formatResourceLines(templates, "markdown")].join("\n");
-}
-case "read_resource":
-  return [`## Resource \`${String(request.uri ?? "") }\``, "", summarizeResourceRead(payload), "", "Use `--format json` to inspect all contents."].join("\n");
-case "list_prompts":
-case "search_prompts": {
-  const prompts = Array.isArray(payload.prompts) ? payload.prompts : [];
-  return [`## MCP prompts for \`${id}\``, "", ...formatPromptLines(prompts, "markdown")].join("\n");
-}
-case "get_prompt":
-  return [`## Prompt \`${String(request.caplet)}.${String(request.prompt)}\``, "", summarizePromptResult(payload), "", "Use `--format json` to inspect all messages."].join("\n");
-case "complete":
-  return [`## Completion for \`${id}\``, "", summarizeCompletionResult(payload)].join("\n");
-```
-
-Add `formatResourceLines`, `formatPromptLines`, `summarizeResourceRead`, `summarizePromptResult`, and `summarizeCompletionResult` below `formatToolLines`; each should use `compactDescription` and `previewValue` already present in the file.
-
-- [ ] **Step 8: Run CLI and remote-control tests to verify green**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/cli.test.ts test/cli-remote.test.ts test/remote-control-dispatch.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 9: Commit Task 5**
-
-```sh
-git add packages/core/src/cli.ts packages/core/src/remote-control/types.ts packages/core/src/remote-control/dispatch.ts packages/core/test/cli.test.ts packages/core/test/cli-remote.test.ts packages/core/test/remote-control-dispatch.test.ts
-git commit -m "feat(cli): add MCP resource and prompt commands"
-```
-
----
-
-### Task 6: Update docs, changeset, and benchmarks if the surface changed
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `packages/cli/README.md` if present
-- Modify: `packages/pi/README.md`
-- Modify: `packages/opencode/README.md`
-- Create: `.changeset/mcp-resources-prompts.md`
-- Modify: `docs/benchmarks/coding-agent.md` only if `pnpm benchmark:check` reports drift.
-
-- [ ] **Step 1: Document the new MCP capability model**
-
-In `README.md`, update the first description of scoped operations to mention MCP-only resources/prompts/completions:
-
-```md
-For MCP-backed Caplets, the scoped operation set also includes resource discovery/reading, prompt listing/rendering, resource-template discovery, and completion for prompt or template arguments. Non-MCP backends continue to expose only tool/action operations.
-```
-
-Add examples near the CLI examples:
-
-```sh
-caplets list-resources docs
-caplets read-resource docs file:///repo/README.md
-caplets list-prompts linear
-caplets get-prompt linear.review_issue --args '{"issueId":"CAP-123"}'
-caplets complete docs --resource-template 'file:///repo/{path}' --argument path --value src/
-```
-
-In package READMEs that exist, add one sentence:
-
-```md
-MCP-backed Caplets advertise resource, prompt, template, and completion operations in their generated schema; OpenAPI, GraphQL, HTTP, CLI, and Caplet-set backends remain tool/action-only.
-```
-
-- [ ] **Step 2: Add a changeset**
-
-Create `.changeset/mcp-resources-prompts.md`:
-
-```md
----
-"@caplets/core": minor
-"caplets": minor
-"@caplets/pi": minor
-"@caplets/opencode": minor
----
-
-Expose MCP resources, resource templates, prompts, and completions through MCP-backed Caplets while keeping non-MCP backend schemas tool-only.
-```
-
-- [ ] **Step 3: Run formatting and benchmark check**
-
-Run:
-
-```sh
-pnpm format:check
-pnpm benchmark:check
-```
-
-Expected: PASS, or `pnpm benchmark:check` fails only because `docs/benchmarks/coding-agent.md` needs regeneration.
-
-- [ ] **Step 4: Regenerate benchmark docs only on benchmark drift**
-
-If Step 3 reports benchmark documentation drift, run:
-
-```sh
-pnpm benchmark
-pnpm benchmark:check
-```
-
-Expected: PASS and `docs/benchmarks/coding-agent.md` is modified.
-
-- [ ] **Step 5: Commit Task 6**
-
-```sh
-git add README.md packages/core/README.md packages/cli/README.md packages/pi/README.md packages/opencode/README.md .changeset docs/benchmarks/coding-agent.md
-git commit -m "docs: describe MCP resource and prompt support"
-```
-
-If a listed README or benchmark file does not exist or was not modified, omit that path from `git add`.
-
----
-
-### Task 7: Full verification and cleanup
-
-**Files:**
-
-- No planned source edits unless verification exposes a failure.
-
-- [ ] **Step 1: Run focused tests**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/tools.test.ts test/downstream.test.ts test/serve-session.test.ts test/cli.test.ts test/cli-remote.test.ts test/remote-control-dispatch.test.ts test/native-remote.test.ts
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 2: Run typecheck**
-
-Run:
-
-```sh
-pnpm typecheck
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Run the full repository gate**
-
-Run:
-
-```sh
-pnpm verify
-```
-
-Expected: PASS. This runs format, lint, typecheck, schema check, tests, benchmark check, and build.
-
-- [ ] **Step 4: Commit verification fixes if any were required**
-
-If Step 1, 2, or 3 required source fixes, inspect the changed files and commit only the verification fixes:
-
-```sh
-git status --short
-git add packages/core/src packages/core/test packages/pi/src packages/pi/test packages/opencode/src packages/opencode/test README.md packages/cli/README.md packages/pi/README.md packages/opencode/README.md .changeset docs/benchmarks/coding-agent.md
-git commit -m "fix: stabilize MCP resource and prompt support"
-```
-
-If no files changed after verification, do not create a commit. If `git status --short` shows unrelated files, do not add them.
-
-- [ ] **Step 5: Report final status**
-
-Collect:
-
-```sh
-git status --short
-git log --oneline -5
-```
-
-Expected: only unrelated local files remain unstaged; implementation commits are present.
-
----
-
-## Self-review checklist
-
-- Spec coverage:
-  - Backend-aware schemas: Task 1 and Task 2.
-  - MCP resource/template list, search, and read: Task 3 and Task 4.
-  - MCP prompt list, search, and get: Task 3 and Task 4.
-  - MCP completion: Task 3 and Task 4.
-  - Non-MCP backends do not advertise MCP operations: Task 1 and Task 2.
-  - CLI and remote-control support: Task 5.
-  - Native integration support: Task 2.
-  - Docs and changeset: Task 6.
-  - Verification: Task 7.
-- Placeholder scan: no placeholder sections are intentionally left for the implementer.
-- Type consistency:
-  - User-facing completion refs use `{ type: "prompt", name }` and `{ type: "resourceTemplate", uri }`.
-  - Downstream MCP SDK refs are converted to `{ type: "ref/prompt", name }` and `{ type: "ref/resource", uri }` in `DownstreamManager.complete`.
-  - `operationNames` come from `inputSchema.properties.operation.enum`.
-  - Remote-control commands exactly match operation names for engine-routed operations.
diff --git a/docs/plans/2026-05-23-ast-grep-premade-caplet.md b/docs/plans/2026-05-23-ast-grep-premade-caplet.md
deleted file mode 100644
index ec1689fa..00000000
--- a/docs/plans/2026-05-23-ast-grep-premade-caplet.md
+++ /dev/null
@@ -1,216 +0,0 @@
-# ast-grep Premade Caplet Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a premade `ast-grep` Caplet under `caplets/` that exposes ast-grep's agent-useful CLI capabilities through the Caplets CLI backend.
-
-**Architecture:** Implement a static Markdown Caplet manifest at `caplets/ast-grep/CAPLET.md` using explicit `cliTools.actions`, matching existing premade examples such as `repo-cli` and `github-cli`. The Caplet uses the `ast-grep` executable, not `sg`, and exposes bounded request/response actions instead of arbitrary command passthrough.
-
-**Tech Stack:** Caplets Markdown manifests, YAML frontmatter, `cliTools`, ast-grep CLI, Vitest config loader tests, README documentation.
-
----
-
-## Scope
-
-- Include: `version`, one-off `run` search/debug/rewrite-apply actions, `scan` diagnostics/report/rewrite-apply actions, `test` rule-test/snapshot-update actions, and `new` scaffolding actions.
-- Exclude: help actions, shell-completion actions, `ast-grep lsp`, and interactive flows. Help and completions are not useful to agents once the Caplet action specs are explicit. LSP and interactive flows are long-running or TTY-oriented, while the CLI backend is request/response-oriented.
-- Safety: read-only search/scan/test actions set `readOnlyHint: true`; rewrite apply-all, snapshot update, and scaffolding actions set `destructiveHint: true`.
-- Path limitation: path-oriented actions accept one `path` per call because CLI backend interpolation substitutes primitive values, not argv arrays.
-
-## File Structure
-
-- Create: `caplets/ast-grep/CAPLET.md`
-  - Owns metadata, ast-grep CLI actions, schemas, annotations, and usage notes.
-- Modify: `packages/core/test/config.test.ts`
-  - Extends repository example loadability coverage with representative ast-grep CLI action assertions.
-- Modify: `README.md`
-  - Adds ast-grep to the premade Caplet list.
-
-## Task 1: Add ast-grep Caplet Manifest
-
-**Files:**
-
-- Create: `caplets/ast-grep/CAPLET.md`
-
-- [ ] **Step 1: Create `caplets/ast-grep/CAPLET.md`**
-
-Create a directory-style Caplet with frontmatter containing:
-
-```yaml
-$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
-name: ast-grep CLI
-description: Search, scan, test, rewrite, and scaffold ast-grep rules through curated CLI tools.
-tags:
-  - cli
-  - code
-  - search
-cliTools:
-  timeoutMs: 120000
-  maxOutputBytes: 1000000
-  actions:
-    version: ...
-    run_pattern_text: ...
-    run_pattern_json: ...
-    run_pattern_debug_query: ...
-    run_pattern_with_context: ...
-    run_pattern_with_globs_json: ...
-    run_rewrite_apply_all: ...
-    scan_project: ...
-    scan_project_json: ...
-    scan_project_sarif: ...
-    scan_project_github: ...
-    scan_with_config_json: ...
-    scan_rule_json: ...
-    scan_inline_rules_json: ...
-    scan_filter_json: ...
-    scan_inspect_summary: ...
-    scan_rewrite_apply_all: ...
-    test_rules: ...
-    test_rules_with_config: ...
-    test_rules_filter: ...
-    test_rules_skip_snapshots: ...
-    test_rules_update_snapshots: ...
-    new_project_yes: ...
-    new_rule_yes: ...
-    new_test_yes: ...
-    new_util_yes: ...
-```
-
-Use `command: ast-grep` for every action. Do not use `sg`.
-
-Use `output: { type: json }` for compact JSON and SARIF-producing actions.
-
-Use action-level `cwd: $input.cwd` for `new_*_yes` actions instead of `--base-dir`, because current ast-grep CLI help does not reliably expose `--base-dir`.
-
-- [ ] **Step 2: Add user-facing notes**
-
-After frontmatter, document:
-
-```md
-# ast-grep CLI
-
-Use this Caplet to expose ast-grep's structural search, scan, rule testing, rewrite, and scaffold workflows without giving an agent unrestricted shell access.
-
-The manifest uses the full `ast-grep` executable instead of `sg` because `sg` can collide with the Linux `setgroups` command. Install ast-grep separately with npm, Cargo, Homebrew, or another supported package manager before using these tools.
-
-Path-oriented actions intentionally accept one `path` argument per call because the CLI backend interpolates primitive arguments, not path arrays.
-
-The `ast-grep lsp` server is intentionally not exposed. The LSP command is a long-running server process, while the Caplets CLI backend is designed for bounded request/response tool calls.
-
-Interactive ast-grep workflows are not exposed for the same reason; use non-interactive apply-all rewrite and snapshot-update actions when file changes are intended.
-```
-
-- [ ] **Step 3: Validate the manifest loads**
-
-Run: `CAPLETS_MODE=local pnpm --filter @caplets/core test test/config.test.ts`
-
-Expected: PASS.
-
-## Task 2: Assert ast-grep Is Loaded As A CLI Example
-
-**Files:**
-
-- Modify: `packages/core/test/config.test.ts`
-
-- [ ] **Step 1: Extend `keeps repository example Caplets loadable`**
-
-Add an expectation for `config.cliTools["ast-grep"]` that verifies:
-
-```ts
-expect(config.cliTools["ast-grep"]).toMatchObject({
-  server: "ast-grep",
-  name: "ast-grep CLI",
-  actions: {
-    run_pattern_json: {
-      command: "ast-grep",
-      args: [
-        "run",
-        "--pattern",
-        "$input.pattern",
-        "--lang",
-        "$input.lang",
-        "--json=compact",
-        "--color",
-        "never",
-        "$input.path",
-      ],
-      output: { type: "json" },
-      annotations: { readOnlyHint: true },
-    },
-    run_rewrite_apply_all: {
-      command: "ast-grep",
-      annotations: { destructiveHint: true },
-    },
-    new_rule_yes: {
-      command: "ast-grep",
-      cwd: expect.stringMatching(/caplets[/\\]ast-grep[/\\]\$input\.cwd$/),
-      annotations: { destructiveHint: true },
-    },
-  },
-});
-```
-
-- [ ] **Step 2: Run focused test**
-
-Run: `CAPLETS_MODE=local pnpm --filter @caplets/core test test/config.test.ts`
-
-Expected: PASS.
-
-## Task 3: Document ast-grep In The Premade Caplet List
-
-**Files:**
-
-- Modify: `README.md`
-
-- [ ] **Step 1: Add ast-grep to the example list**
-
-In the list under `This repository includes polished working examples under [caplets/](caplets/):`, add:
-
-```md
-- `ast-grep`: Structural code search, scan, rewrite, rule testing, and scaffolding through the `ast-grep` CLI.
-```
-
-- [ ] **Step 2: Run formatting check**
-
-Run: `pnpm format:check README.md caplets/ast-grep/CAPLET.md docs/plans/2026-05-23-ast-grep-premade-caplet.md packages/core/test/config.test.ts`
-
-Expected: PASS.
-
-## Task 4: Final Verification
-
-**Files:**
-
-- Verify: `caplets/ast-grep/CAPLET.md`
-- Verify: `packages/core/test/config.test.ts`
-- Verify: `README.md`
-- Verify: `docs/plans/2026-05-23-ast-grep-premade-caplet.md`
-
-- [ ] **Step 1: Run schema validation**
-
-Run: `pnpm schema:check`
-
-Expected: PASS.
-
-- [ ] **Step 2: Run typecheck**
-
-Run: `pnpm typecheck`
-
-Expected: PASS.
-
-- [ ] **Step 3: Run focused tests**
-
-Run: `CAPLETS_MODE=local pnpm --filter @caplets/core test test/config.test.ts`
-
-Expected: PASS.
-
-- [ ] **Step 4: Inspect final diff**
-
-Run: `git diff -- caplets/ast-grep/CAPLET.md packages/core/test/config.test.ts README.md docs/plans/2026-05-23-ast-grep-premade-caplet.md`
-
-Expected: Diff contains only the ast-grep premade Caplet, its focused test assertion, README list entry, and this plan.
-
-## Self-Review
-
-- Spec coverage: This plan covers the premade manifest, agent-useful ast-grep command groups, destructive/read-only annotations, excluded help/completion/LSP/interactive flows, README documentation, and focused validation.
-- Placeholder scan: No placeholders, TBDs, or incomplete steps remain.
-- Type consistency: The plan uses existing `cliTools.actions`, `inputSchema`, `output`, `cwd`, and `annotations` fields from the repository's CLI backend schema.
diff --git a/docs/plans/2026-05-23-coding-agent-showcase-caplets.md b/docs/plans/2026-05-23-coding-agent-showcase-caplets.md
deleted file mode 100644
index b52ab1a9..00000000
--- a/docs/plans/2026-05-23-coding-agent-showcase-caplets.md
+++ /dev/null
@@ -1,221 +0,0 @@
-# Coding Agent Showcase Caplets Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add high-value premade Caplets for coding agents covering HTTP, OpenAPI, MCP, CLI, and CapletSet backends while intentionally skipping GraphQL for now.
-
-**Architecture:** Add top-level registry Caplets for OSV, npm, PyPI, DeepWiki, Sourcegraph, and Playwright. Add a `coding-agent-toolkit` CapletSet whose nested child entries are symlinks to the canonical top-level examples, and update install behavior so selected directory Caplet installs materialize internal symlinks as real files/directories.
-
-**Tech Stack:** Caplets Markdown manifests, local and remote OpenAPI YAML specs, HTTP action backend, OpenAPI backend, MCP backend, CapletSet backend, Node `fs.cpSync`, Vitest.
-
----
-
-## Scope
-
-- Add `osv` using `httpApi`.
-- Add `npm` using `openapiEndpoint.specUrl` pointed at npm's published OpenAPI YAML.
-- Add `pypi` using `openapiEndpoint` and a curated local `pypi.openapi.yaml`.
-- Add `deepwiki`, `sourcegraph`, and `playwright` using `mcpServer`.
-- Add `coding-agent-toolkit` using `capletSet` with symlinked child Caplets.
-- Preserve canonical GitHub as `github` MCP and do not add GitHub REST/GraphQL.
-- Keep pre-existing `github-cli` documented as secondary to canonical `github` MCP, not as a new showcase Caplet.
-- Skip GraphQL-backed showcase examples for now.
-
-## Files
-
-- Modify: `packages/core/src/cli/install.ts` to dereference symlinks when copying directory Caplets.
-- Modify: `packages/core/test/cli.test.ts` to verify selected installs of symlinked toolkit children are self-contained.
-- Create: `caplets/osv/CAPLET.md`.
-- Create: `caplets/npm/CAPLET.md`.
-- Create: `caplets/pypi/CAPLET.md` and `caplets/pypi/pypi.openapi.yaml`.
-- Create: `caplets/deepwiki/CAPLET.md`.
-- Create: `caplets/sourcegraph/CAPLET.md`.
-- Create: `caplets/playwright/CAPLET.md`.
-- Create: `caplets/coding-agent-toolkit/CAPLET.md` and symlinks under `caplets/coding-agent-toolkit/caplets/`.
-- Modify: `packages/core/test/config.test.ts` to assert the new repository examples load.
-- Modify: `README.md` to list the new examples and clarify toolkit behavior.
-
-## Task 1: Symlink Materialization In Selected Directory Installs
-
-**Files:**
-
-- Modify: `packages/core/src/cli/install.ts`
-- Modify: `packages/core/test/cli.test.ts`
-
-- [ ] **Step 1: Add a failing install test**
-
-Add a test near the existing install tests that creates `caplets/osv/CAPLET.md`, `caplets/coding-agent-toolkit/CAPLET.md`, and a symlink `caplets/coding-agent-toolkit/caplets/osv -> ../../osv`. Run `installCaplets(repo, { capletIds: ["coding-agent-toolkit"], destinationRoot })` and assert `destinationRoot/coding-agent-toolkit/caplets/osv/CAPLET.md` exists and `lstatSync(destinationRoot/coding-agent-toolkit/caplets/osv).isSymbolicLink()` is `false`.
-
-- [ ] **Step 2: Run the focused test and observe failure**
-
-Run: `CAPLETS_MODE=local pnpm --filter @caplets/core test test/cli.test.ts`
-
-Expected before implementation: the new assertion fails because copied child entries remain symlinks or selected install is not self-contained.
-
-- [ ] **Step 3: Implement symlink materialization**
-
-In `copyInstallPath`, call `cpSync` with `dereference: plan.kind === "directory"` so symlinks inside directory Caplets are copied as their targets while file Caplet behavior remains unchanged.
-
-- [ ] **Step 4: Run the focused test again**
-
-Run: `CAPLETS_MODE=local pnpm --filter @caplets/core test test/cli.test.ts`
-
-Expected: PASS.
-
-## Task 2: OSV HTTP Caplet
-
-**Files:**
-
-- Create: `caplets/osv/CAPLET.md`
-
-- [ ] **Step 1: Add OSV manifest**
-
-Create an HTTP Caplet named `OSV Vulnerabilities` with `baseUrl: https://api.osv.dev`, `auth: { type: none }`, and actions:
-
-- `query_package_version`: `POST /v1/query`, body with `package.name`, `package.ecosystem`, `version`, optional `page_token`.
-- `query_purl`: `POST /v1/query`, body with `package.purl`, optional `page_token`.
-- `query_commit`: `POST /v1/query`, body with `commit`, optional `page_token`.
-- `query_batch`: `POST /v1/querybatch`, body `queries: $input.queries`.
-- `get_vulnerability`: `GET /v1/vulns/{id}`.
-  Mark every action read-only.
-
-- [ ] **Step 2: Run focused config test**
-
-Run: `CAPLETS_MODE=local pnpm --filter @caplets/core test test/config.test.ts`
-
-Expected: PASS once loadability assertions are updated in Task 7; before Task 7, this at minimum must not introduce parse errors.
-
-## Task 3: NPM OpenAPI Caplet
-
-**Files:**
-
-- Create: `caplets/npm/CAPLET.md`
-
-- [ ] **Step 1: Add npm Caplet manifest**
-
-Create `caplets/npm/CAPLET.md` with `openapiEndpoint.specUrl` pointed at npm's published OpenAPI YAML, `auth.type: none`, and docs explaining that the spec is loaded remotely.
-
-## Task 4: PyPI OpenAPI Caplet
-
-**Files:**
-
-- Create: `caplets/pypi/CAPLET.md`
-- Create: `caplets/pypi/pypi.openapi.yaml`
-
-- [ ] **Step 1: Add curated PyPI OpenAPI spec**
-
-Create a small OpenAPI 3.0.3 spec with `servers: [{ url: https://pypi.org }]` and operations:
-
-- `GET /pypi/{project}/json` for latest project JSON metadata.
-- `GET /pypi/{project}/{version}/json` for release-specific JSON metadata.
-- `GET /simple/{project}/` with `Accept: application/vnd.pypi.simple.v1+json` header parameter for Simple API JSON project detail.
-  Use operation IDs `get_project`, `get_release`, and `get_simple_project`.
-
-- [ ] **Step 2: Add PyPI Caplet manifest**
-
-Create `caplets/pypi/CAPLET.md` with `openapiEndpoint.specPath: ./pypi.openapi.yaml`, `auth.type: none`, and docs explaining JSON API and Simple API coverage.
-
-## Task 5: MCP Caplets
-
-**Files:**
-
-- Create: `caplets/deepwiki/CAPLET.md`
-- Create: `caplets/sourcegraph/CAPLET.md`
-- Create: `caplets/playwright/CAPLET.md`
-
-- [ ] **Step 1: Add DeepWiki MCP Caplet**
-
-Create a DeepWiki MCP Caplet using the best known MCP connection from repository conventions. If no public endpoint is documented, use `url: https://mcp.deepwiki.com/mcp` with `transport: http` and document that hosted endpoint availability may depend on DeepWiki's current MCP service.
-
-- [ ] **Step 2: Add Sourcegraph MCP Caplet**
-
-Create Sourcegraph MCP with `url: https://sourcegraph.com/.api/mcp`, `transport: http`, and `auth.type: oauth2`. Document that self-managed users should change the host to `https://<sourcegraph-host>/.api/mcp` and may use access-token headers if their instance does not support OAuth/DCR.
-
-- [ ] **Step 3: Add Playwright MCP Caplet**
-
-Create Playwright MCP using stdio: `command: npx`, args `-y`, `@playwright/mcp@latest`, `--headless`. Document that removing `--headless` enables a visible browser and that advanced users can use a config file.
-
-## Task 6: Symlinked Coding Agent Toolkit CapletSet
-
-**Files:**
-
-- Create: `caplets/coding-agent-toolkit/CAPLET.md`
-- Create symlinks under: `caplets/coding-agent-toolkit/caplets/`
-
-- [ ] **Step 1: Add toolkit manifest**
-
-Create `caplets/coding-agent-toolkit/CAPLET.md` with `capletSet.capletsRoot: ./caplets`, tags `coding-agent`, `toolkit`, `caplets`, and body explaining the toolkit is symlink-backed in the source repository but materialized when installed.
-
-- [ ] **Step 2: Add child symlinks**
-
-Create symlinks:
-
-- `ast-grep -> ../../ast-grep`
-- `repo-cli -> ../../repo-cli`
-- `osv -> ../../osv`
-- `npm -> ../../npm`
-- `pypi -> ../../pypi`
-- `deepwiki -> ../../deepwiki`
-- `sourcegraph -> ../../sourcegraph`
-- `playwright -> ../../playwright`
-
-## Task 7: Repository Docs And Loadability Tests
-
-**Files:**
-
-- Modify: `packages/core/test/config.test.ts`
-- Modify: `README.md`
-
-- [ ] **Step 1: Extend repository example loadability assertions**
-
-Assert that `config.httpApis.osv`, `config.openapiEndpoints.npm`, `config.openapiEndpoints.pypi`, `config.mcpServers.deepwiki`, `config.mcpServers.sourcegraph`, `config.mcpServers.playwright`, and `config.capletSets["coding-agent-toolkit"]` load with representative fields.
-
-- [ ] **Step 2: Update README example list**
-
-Add bullets for `osv`, `npm`, `pypi`, `deepwiki`, `sourcegraph`, `playwright`, and `coding-agent-toolkit`. Note that GraphQL is intentionally not included in this showcase batch.
-
-- [ ] **Step 3: Run focused tests**
-
-Run: `CAPLETS_MODE=local pnpm --filter @caplets/core test test/config.test.ts test/cli.test.ts`
-
-Expected: PASS.
-
-## Task 8: Final Verification
-
-**Files:**
-
-- Verify all changed files.
-
-- [ ] **Step 1: Run format check**
-
-Run: `pnpm format:check`
-
-Expected: PASS.
-
-- [ ] **Step 2: Run schema check**
-
-Run: `pnpm schema:check`
-
-Expected: PASS.
-
-- [ ] **Step 3: Run typecheck**
-
-Run: `pnpm typecheck`
-
-Expected: PASS.
-
-- [ ] **Step 4: Run focused tests**
-
-Run: `CAPLETS_MODE=local pnpm --filter @caplets/core test test/config.test.ts test/cli.test.ts`
-
-Expected: PASS.
-
-- [ ] **Step 5: Inspect diff and symlinks**
-
-Run: `git status --short` and inspect the diff for the changed files. Confirm toolkit child entries are symlinks in the source repo and materialized by install tests.
-
-## Self-Review
-
-- Spec coverage: Covers the final approved list, skips GraphQL, keeps GitHub consolidated, and handles symlinked toolkit install behavior.
-- Placeholder scan: No placeholders or TBDs remain.
-- Type consistency: Uses existing `mcpServer`, `httpApi`, `openapiEndpoint`, `capletSet`, `inputSchema`, `jsonBody`, and `annotations` frontmatter fields.
diff --git a/docs/plans/2026-05-24-remote-local-interop.md b/docs/plans/2026-05-24-remote-local-interop.md
deleted file mode 100644
index 147ae5ed..00000000
--- a/docs/plans/2026-05-24-remote-local-interop.md
+++ /dev/null
@@ -1,135 +0,0 @@
-# Remote Local Interop Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make remote mode use a merged Caplets view from the remote server, user-global local Caplets, and project local Caplets, with explicit write targets.
-
-**Architecture:** Keep strict local-mode loading unchanged. Add best-effort local overlay loaders used only in remote-mode composition, then merge remote, global, and project layers by Caplet ID with higher-priority layers shadowing lower-priority layers. Mutations use explicit target flags so remote mode no longer silently sends local writes to the server.
-
-**Tech Stack:** TypeScript, Vitest, Commander, MCP SDK remote client, existing CapletsEngine, pnpm.
-
-**Final status:** Implemented. The checklist below is retained as the original execution plan; remote/local interop, target flags, auth disambiguation, documentation updates, and final review fixes are complete. Final review additionally confirmed local `caplets list` and `caplets config paths --json` honor `CAPLETS_PROJECT_CONFIG`.
-
----
-
-## Resolved Decisions
-
-- Remote mode read/execute surfaces use a merged view: remote server, user-global local, project local.
-- Priority is ascending: remote < global local < project local.
-- Higher-priority IDs shadow lower-priority IDs across backend types.
-- Local overlay loading is best-effort in remote mode.
-- Invalid local config warns and falls back to remaining valid layers.
-- Invalid Caplet files warn and are skipped individually.
-- A sibling directory Caplet `foo/CAPLET.md` wins over `foo.md`; warn that `foo.md` was shadowed.
-- If the winning `CAPLET.md` is invalid, drop that ID from that layer rather than falling back to `foo.md`.
-- Mutation target flags are shared: no flag and `--project` write project local, `--global` writes user-global local, `--remote` writes server remote.
-- Auth commands use explicit target flags when IDs are ambiguous.
-
-## Files
-
-- Modify `packages/core/src/caplet-files.ts`: add best-effort Caplet file loading with per-file warnings and `CAPLET.md` duplicate precedence.
-- Modify `packages/core/src/config.ts`: add best-effort local overlay config loading and source metadata support for remote rows.
-- Modify `packages/core/src/engine.ts`: add a config-loader seam so remote-overlay local engines can use best-effort config without changing strict local mode.
-- Modify `packages/core/src/native/service.ts`: return a composite remote/local service in remote mode instead of remote-only.
-- Modify `packages/core/src/native/remote.ts`: keep remote service behavior, expose it for composition where needed.
-- Modify `packages/core/src/cli.ts`: merge remote/local reads, route operations to local when shadowed, add mutation target flags.
-- Modify `packages/core/src/cli/auth.ts`: add source-aware auth target resolution and ambiguity errors.
-- Modify `packages/core/src/cli/init.ts`: support project-local init path.
-- Modify `packages/core/src/cli/inspection.ts`: allow remote source rows and merged shadow warnings.
-- Modify `packages/core/test/config.test.ts`: cover tolerant file loading and `CAPLET.md` precedence.
-- Modify `packages/core/test/native-remote.test.ts`: cover composite remote/local native service shadowing.
-- Modify `packages/core/test/cli-remote.test.ts`: cover merged list/execute behavior and mutation flags.
-- Modify `packages/core/test/auth.test.ts`: cover auth ambiguity and target flags.
-- Modify docs in `README.md` and `packages/cli/README.md`.
-
----
-
-## Task 1: Best-Effort Caplet File Loading
-
-- [ ] Add an exported loader named `loadCapletFilesWithPathsBestEffort(root)` that returns `{ config, paths, warnings } | undefined`.
-- [ ] Preserve `loadCapletFilesWithPaths(root)` strict behavior for existing local mode.
-- [ ] In best-effort mode, discover all candidate files and collect warnings instead of throwing for invalid files.
-- [ ] If `foo.md` and `foo/CAPLET.md` both exist, select `foo/CAPLET.md` and warn that `foo.md` was shadowed.
-- [ ] If the selected file is invalid, warn and skip only that file. Do not fall back to a shadowed sibling `foo.md`.
-- [ ] If duplicate IDs remain after precedence rules, warn and skip that ID only.
-- [ ] Add tests proving one invalid file does not prevent valid sibling Caplets from loading and proving `CAPLET.md` wins over `foo.md`.
-- [ ] Run `pnpm --filter @caplets/core test -- test/config.test.ts`.
-
-## Task 2: Best-Effort Overlay Config Loader
-
-- [ ] Add a config helper, `loadLocalOverlayConfigWithSources(path, projectPath)`, that loads global config, global files, project config, and project files independently.
-- [ ] Preserve strict `loadConfig` and `loadConfigWithSources` behavior.
-- [ ] On invalid global config or project config, return a warning and ignore only that source.
-- [ ] On invalid file-backed Caplets, use the Task 1 per-file warnings.
-- [ ] Preserve existing source and shadow metadata for valid sources.
-- [ ] Return an empty normalized config result when no valid local sources exist.
-- [ ] Add tests for invalid config fallback, mixed valid/invalid layers, and shadow metadata.
-- [ ] Run `pnpm --filter @caplets/core test -- test/config.test.ts`.
-
-## Task 3: Composite Native Remote Service
-
-- [ ] In `createNativeCapletsService`, remote mode should create both `RemoteNativeCapletsService` and a local overlay service using the best-effort config loader.
-- [ ] Merge list tools in priority order: remote first, then global/project local; local tools with matching `caplet` IDs shadow remote tools.
-- [ ] Execute local Caplet IDs locally and remote-only IDs remotely.
-- [ ] Reload both sides and emit one merged tools-changed event when the merged set changes.
-- [ ] Close both services idempotently.
-- [ ] Preserve last known-good merged tools if a reload only produces warnings or fails unexpectedly.
-- [ ] Add native remote tests for shadowing, local execution, remote fallback, reload events, and close behavior.
-- [ ] Run `pnpm --filter @caplets/core test -- test/native-remote.test.ts`.
-
-## Task 4: CLI Merged Read/Execute Routing
-
-- [ ] For `list`, request remote rows and load local overlay rows, then merge by ID using remote < global < project precedence.
-- [ ] Include shadow warnings for remote rows hidden by local rows.
-- [ ] For `get-caplet`, `check-backend`, `list-tools`, `search-tools`, `get-tool`, `call-tool`, resources, prompts, and completion, check the local overlay first.
-- [ ] If a local overlay contains the target ID, execute locally through a local `CapletsEngine` using best-effort overlay config.
-- [ ] If no local overlay contains the target ID, route to remote control.
-- [ ] Print local overlay warnings to stderr and continue.
-- [ ] Preserve existing remote failure behavior for remote-only Caplets.
-- [ ] Add CLI tests for merged list output, project shadowing of remote, global shadowing of remote, local execution, and remote fallback.
-- [ ] Run `pnpm --filter @caplets/core test -- test/cli-remote.test.ts`.
-
-## Task 5: Mutation Target Flags
-
-- [ ] Add shared target parsing for `--project`, `--global`, and `--remote`.
-- [ ] Reject combinations like `--project --global`, `--project --remote`, and `--global --remote`.
-- [ ] Change `init` so no flag and `--project` create `./.caplets/config.json`.
-- [ ] Make `init --global` create the user config.
-- [ ] Make `init --remote` route to remote control.
-- [ ] Make `add` and `install` default to project local even when `CAPLETS_MODE=remote`.
-- [ ] Make `add --global` and `install --global` write user-global local.
-- [ ] Make `add --remote` and `install --remote` route to remote control.
-- [ ] Remove current behavior where remote mode automatically routes add/install/init remotely.
-- [ ] Add CLI tests for each target and invalid target combinations.
-- [ ] Run `pnpm --filter @caplets/core test -- test/cli-remote.test.ts`.
-
-## Task 6: Auth Targeting And Ambiguity
-
-- [ ] Add `--project`, `--global`, and `--remote` to `auth login`, `auth logout`, and `auth list`.
-- [ ] With no flag, detect whether the requested ID appears in multiple scopes.
-- [ ] If ambiguous, fail with a clear message telling the user to pass `--project`, `--global`, or `--remote`.
-- [ ] `auth list` with no flag should show all available local and remote auth rows with a `source` field.
-- [ ] `auth list --project`, `--global`, or `--remote` should show only that scope.
-- [ ] Remote auth remains server-owned and uses existing remote control requests.
-- [ ] Local auth continues using the existing local auth store keyed by server ID; flags disambiguate which Caplet config drives the auth flow.
-- [ ] Add auth tests for ambiguity, target flags, source output, and remote requests.
-- [ ] Run `pnpm --filter @caplets/core test -- test/auth.test.ts` and `pnpm --filter @caplets/core test -- test/cli-remote.test.ts`.
-
-## Task 7: Docs
-
-- [ ] Document the merged remote mode priority order.
-- [ ] Document that local overlays are best-effort in remote mode.
-- [ ] Document warnings and fallback behavior.
-- [ ] Document mutation target flags and defaults.
-- [ ] Document auth ambiguity and explicit target flags.
-- [ ] Update `README.md` and `packages/cli/README.md`.
-
-## Verification
-
-- [ ] Run `pnpm --filter @caplets/core test -- test/config.test.ts`.
-- [ ] Run `pnpm --filter @caplets/core test -- test/native-remote.test.ts`.
-- [ ] Run `pnpm --filter @caplets/core test -- test/cli-remote.test.ts`.
-- [ ] Run `pnpm --filter @caplets/core test -- test/auth.test.ts`.
-- [ ] Run `pnpm --filter @caplets/core test`.
-- [ ] Run `pnpm typecheck`.
-- [ ] Run `pnpm verify` before completion.
diff --git a/docs/plans/2026-05-26-lsp-registry-caplet.md b/docs/plans/2026-05-26-lsp-registry-caplet.md
deleted file mode 100644
index 5f4879fc..00000000
--- a/docs/plans/2026-05-26-lsp-registry-caplet.md
+++ /dev/null
@@ -1,370 +0,0 @@
-# LSP Registry Caplet Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make `caplets/lsp` a polished registry Caplet backed by `language-server-mcp`, included in examples, toolkit, tests, and release notes.
-
-**Architecture:** Keep `lsp` as a directory-style MCP Caplet that launches `npx -y language-server-mcp`. Add documentation in the Caplet card and README, include it in the `coding-agent-toolkit` via source symlink, and extend repository example config tests to validate it loads without live MCP startup.
-
-**Tech Stack:** Markdown Caplet frontmatter, Caplets repository example loader, Vitest, pnpm, Changesets.
-
----
-
-## File Structure
-
-- Modify `caplets/lsp/CAPLET.md`: polished manifest description/tags and complete usage/safety/examples body.
-- Create symlink `caplets/coding-agent-toolkit/caplets/lsp -> ../../lsp`: toolkit child pointing to the canonical top-level LSP Caplet.
-- Modify `README.md`: add `lsp` to the polished examples list.
-- Modify `packages/core/test/config.test.ts`: add `config.mcpServers.lsp` assertion in the existing showcase Caplets test.
-- Create `.changeset/lsp-registry-caplet.md`: patch changeset for the user-facing `caplets` package examples/toolkit update.
-
----
-
-### Task 1: Add failing config coverage for the LSP Caplet
-
-**Files:**
-
-- Modify: `packages/core/test/config.test.ts`
-- Test: `packages/core/test/config.test.ts`
-
-- [ ] **Step 1: Write the failing test assertion**
-
-In `packages/core/test/config.test.ts`, find the existing assertion block:
-
-```ts
-      expect(config.mcpServers.playwright).toMatchObject({
-        server: "playwright",
-        name: "Playwright",
-        command: "npx",
-        args: ["-y", "@playwright/mcp@0.0.75", "--headless"],
-      });
-      expect(config.capletSets["coding-agent-toolkit"]).toMatchObject({
-```
-
-Replace it with:
-
-```ts
-      expect(config.mcpServers.playwright).toMatchObject({
-        server: "playwright",
-        name: "Playwright",
-        command: "npx",
-        args: ["-y", "@playwright/mcp@0.0.75", "--headless"],
-      });
-      expect(config.mcpServers.lsp).toMatchObject({
-        server: "lsp",
-        name: "LSP",
-        command: "npx",
-        args: ["-y", "language-server-mcp"],
-      });
-      expect(config.capletSets["coding-agent-toolkit"]).toMatchObject({
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/config.test.ts
-```
-
-Expected: FAIL because the current `caplets/lsp/CAPLET.md` manifest name is `lsp`, so `name: "LSP"` does not match yet.
-
-- [ ] **Step 3: Commit failing test**
-
-```sh
-git add packages/core/test/config.test.ts
-git commit -m "test: cover lsp registry caplet loading"
-```
-
----
-
-### Task 2: Polish the LSP Caplet card
-
-**Files:**
-
-- Modify: `caplets/lsp/CAPLET.md`
-- Test: `packages/core/test/config.test.ts`
-
-- [ ] **Step 1: Replace the Caplet card**
-
-Replace the entire contents of `caplets/lsp/CAPLET.md` with:
-
-````markdown
----
-# yaml-language-server: $schema=https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
-name: LSP
-description: Language Server Protocol tools for project-aware code intelligence through language-server-mcp.
-tags:
-  - mcp
-  - code
-  - lsp
-  - language-server
-  - diagnostics
-mcpServer:
-  command: npx
-  args: [-y, language-server-mcp]
----
-
-# LSP
-
-Use this Caplet to expose Language Server Protocol capabilities through `language-server-mcp` without handing every language-server operation to an agent up front.
-
-The server runs over stdio, starts local language servers lazily, and gives agents project-aware code intelligence for repositories that have LSP configuration or supported built-in language servers.
-
-## Good Fits
-
-- Inspect hover/type information before editing unfamiliar code.
-- Jump to definitions, declarations, implementations, and type definitions.
-- Find references and document/workspace symbols during refactors.
-- Read diagnostics from configured language servers before proposing fixes.
-- Request formatting, code actions, rename edits, and workspace edits.
-- Cross-check code review or planning assumptions with language-server-backed facts.
-
-## Setup
-
-Create a project-level `.lsp-mcp.jsonc` when the defaults are not enough:
-
-```jsonc
-{
-  "lsp": {
-    "servers": {
-      "typescript": {
-        "registry": "typescript",
-      },
-    },
-  },
-}
-```
-````
-
-For file-targeted tools, pass absolute or workspace-relative paths that resolve inside the workspace. A typical request includes `workspaceRoot`, `filePath`, `line`, and `character`:
-
-```json
-{
-  "workspaceRoot": "/absolute/path/to/project",
-  "filePath": "/absolute/path/to/project/src/index.ts",
-  "line": 3,
-  "character": 12
-}
-```
-
-`serverId` is optional for file-targeted tools. When omitted, `language-server-mcp` runs against configured or built-in servers whose language IDs or file extensions match the file. Add `"serverId": "typescript"` to force a specific server.
-
-Built-in registry IDs include common servers such as `typescript`, `deno`, `eslint`, `json`, `pyright`, `gopls`, `rust`, `svelte`, `vue`, `yaml-ls`, `bash`, `clangd`, `lua-ls`, and `terraform`. Mason and nvim-lspconfig aliases such as `ts_ls`, `denols`, `yamlls`, `bashls`, `rust_analyzer`, and compatibility aliases such as `python`, `go`, and `yaml` are also accepted by the downstream server.
-
-## Safety
-
-`language-server-mcp` defaults to conservative behavior for file modification and process execution:
-
-- Edit-producing tools return edits by default and do not write files unless `apply: true` is passed.
-- `apply: true` requires `serverId` when more than one matching LSP server would produce edits.
-- Applied edits are restricted to the workspace root unless the downstream server is configured with `security.allowExternalFiles: true`.
-- `workspace/executeCommand` is enabled by default, but can be disabled globally or restricted with per-server command allowlists.
-- LSP servers start lazily on first use and stop after an idle timeout by default.
-- Managed downloads are available only for supported built-ins and can be disabled with `downloads.enabled: false`.
-
-## Examples
-
-Ask for hover information at a symbol:
-
-```json
-{
-  "workspaceRoot": "/absolute/path/to/project",
-  "filePath": "/absolute/path/to/project/src/index.ts",
-  "line": 10,
-  "character": 18,
-  "serverId": "typescript"
-}
-```
-
-Read diagnostics for a source file:
-
-```json
-{
-  "workspaceRoot": "/absolute/path/to/project",
-  "filePath": "/absolute/path/to/project/src/index.ts"
-}
-```
-
-Request code actions without applying edits immediately:
-
-```json
-{
-  "workspaceRoot": "/absolute/path/to/project",
-  "filePath": "/absolute/path/to/project/src/index.ts",
-  "range": {
-    "start": { "line": 12, "character": 0 },
-    "end": { "line": 12, "character": 24 }
-  },
-  "apply": false,
-  "serverId": "typescript"
-}
-```
-
-````
-
-- [ ] **Step 2: Run test to verify it passes**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/config.test.ts
-````
-
-Expected: PASS. The new manifest name is `LSP`, and the backend command remains `npx -y language-server-mcp`.
-
-- [ ] **Step 3: Commit Caplet card**
-
-```sh
-git add caplets/lsp/CAPLET.md
-git commit -m "docs: polish lsp registry caplet"
-```
-
----
-
-### Task 3: Add LSP to the coding-agent toolkit
-
-**Files:**
-
-- Create symlink: `caplets/coding-agent-toolkit/caplets/lsp -> ../../lsp`
-- Test: `packages/core/test/cli.test.ts`
-- Test: `packages/core/test/config.test.ts`
-
-- [ ] **Step 1: Create the source-tree symlink**
-
-Run:
-
-```sh
-ln -s ../../lsp caplets/coding-agent-toolkit/caplets/lsp
-```
-
-Verify:
-
-```sh
-readlink caplets/coding-agent-toolkit/caplets/lsp
-```
-
-Expected output:
-
-```text
-../../lsp
-```
-
-- [ ] **Step 2: Run toolkit-related tests**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/config.test.ts test/cli.test.ts
-```
-
-Expected: PASS. Existing CapletSet loading and symlink materialization tests continue to pass with the additional child symlink.
-
-- [ ] **Step 3: Commit toolkit inclusion**
-
-```sh
-git add caplets/coding-agent-toolkit/caplets/lsp
-git commit -m "docs: add lsp to coding agent toolkit"
-```
-
----
-
-### Task 4: Document LSP in repository examples
-
-**Files:**
-
-- Modify: `README.md`
-
-- [ ] **Step 1: Add README example bullet**
-
-In `README.md`, find:
-
-```markdown
-- `sourcegraph`: Cross-repository code search and navigation through Sourcegraph MCP.
-- `playwright`: Headless browser automation for frontend inspection and testing through Playwright MCP.
-- `coding-agent-toolkit`: A CapletSet that bundles high-value coding-agent examples; source children are symlinks to canonical top-level examples and installed copies are materialized as self-contained files/directories.
-```
-
-Replace it with:
-
-```markdown
-- `sourcegraph`: Cross-repository code search and navigation through Sourcegraph MCP.
-- `playwright`: Headless browser automation for frontend inspection and testing through Playwright MCP.
-- `lsp`: Language Server Protocol-backed code intelligence through `language-server-mcp`.
-- `coding-agent-toolkit`: A CapletSet that bundles high-value coding-agent examples; source children are symlinks to canonical top-level examples and installed copies are materialized as self-contained files/directories.
-```
-
-- [ ] **Step 2: Run docs formatting check**
-
-Run:
-
-```sh
-pnpm format:check
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Commit README update**
-
-```sh
-git add README.md
-git commit -m "docs: list lsp registry example"
-```
-
----
-
-### Task 5: Add changeset and final verification
-
-**Files:**
-
-- Create: `.changeset/lsp-registry-caplet.md`
-- Test: repository checks
-
-- [ ] **Step 1: Create changeset**
-
-Create `.changeset/lsp-registry-caplet.md` with:
-
-```markdown
----
-"caplets": patch
----
-
-Add a polished LSP registry Caplet backed by `language-server-mcp` and include it in the coding-agent toolkit examples.
-```
-
-- [ ] **Step 2: Run focused checks**
-
-Run:
-
-```sh
-pnpm --filter @caplets/core test -- test/config.test.ts test/cli.test.ts
-pnpm format:check
-pnpm lint
-```
-
-Expected: all commands PASS.
-
-- [ ] **Step 3: Run full verification**
-
-Run:
-
-```sh
-pnpm verify
-```
-
-Expected: PASS for formatting, lint, typecheck, schema check, tests, benchmark check, and build.
-
-- [ ] **Step 4: Commit changeset**
-
-```sh
-git add .changeset/lsp-registry-caplet.md
-git commit -m "chore: add lsp registry caplet changeset"
-```
-
----
-
-## Self-Review Notes
-
-- Spec coverage: the plan expands `caplets/lsp/CAPLET.md`, keeps `npx -y language-server-mcp`, adds setup/safety/examples, updates README, adds toolkit symlink, extends config tests, and creates a changeset.
-- Placeholder scan: no placeholder tasks remain; each step includes exact file paths, commands, and expected outcomes.
-- Type/signature consistency: expected `config.mcpServers.lsp` fields match the planned frontmatter: `server: "lsp"`, `name: "LSP"`, `command: "npx"`, and `args: ["-y", "language-server-mcp"]`.
diff --git a/docs/plans/2026-05-27-agent-card-setup-tabs.md b/docs/plans/2026-05-27-agent-card-setup-tabs.md
deleted file mode 100644
index 921055bf..00000000
--- a/docs/plans/2026-05-27-agent-card-setup-tabs.md
+++ /dev/null
@@ -1,477 +0,0 @@
-# Agent Card Setup Tabs Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Turn the landing page's existing agent pills into tabs that show each agent's install command and configuration snippet.
-
-**Architecture:** Keep the integrations card in `apps/landing/src/pages/index.astro`, move agent data into a structured `agentSetups` array, render pills as accessible tab buttons, and render matching setup panels in the same card. Add small scoped client-side JavaScript to switch tabs and CSS to preserve the current card aesthetic while making commands/configurations readable.
-
-**Tech Stack:** Astro 6, plain TypeScript in Astro script, CSS in `apps/landing/src/styles/global.css`, pnpm repo scripts.
-
----
-
-## File structure
-
-- Modify `apps/landing/src/pages/index.astro`: replace the current `integrations` string array with structured `agentSetups` data, render the tabbed pills and setup panels, and add scoped tab-switching JavaScript.
-- Modify `apps/landing/src/styles/global.css`: style active/inactive agent pills, setup panels, command/configuration code blocks, and responsive behavior.
-- No new runtime dependencies.
-
-## Setup data to use
-
-Use these exact agent labels and setup strings unless the implementation discovers a more current repo-local source:
-
-```ts
-const agentSetups = [
-  {
-    id: "claude-code",
-    name: "Claude Code",
-    installCommand: "npm install -g caplets",
-    configSnippet: `{
-  "mcpServers": {
-    "caplets": {
-      "command": "caplets",
-      "args": ["serve"]
-    }
-  }
-}`,
-    note: "Use the universal MCP server from Claude Code's MCP configuration.",
-  },
-  {
-    id: "codex",
-    name: "Codex",
-    installCommand: "npm install -g caplets",
-    configSnippet: `[mcp_servers.caplets]
-command = "caplets"
-args = ["serve"]`,
-    note: "Register Caplets as a local MCP server in Codex config.",
-  },
-  {
-    id: "opencode",
-    name: "OpenCode",
-    installCommand: "npm install -g @caplets/opencode",
-    configSnippet: `{
-  "mcp": {
-    "caplets": {
-      "type": "local",
-      "command": ["caplets", "serve"]
-    }
-  }
-}`,
-    note: "Use MCP config or the native @caplets/opencode integration where available.",
-  },
-  {
-    id: "pi",
-    name: "Pi",
-    installCommand: "pi update && npm install -g @caplets/pi",
-    configSnippet: `{
-  "caplets": {
-    "enabled": true,
-    "configPath": "~/.config/caplets/config.json"
-  }
-}`,
-    note: "Use the native @caplets/pi integration with the same Caplets config file.",
-  },
-  {
-    id: "mcp-client",
-    name: "Any MCP client",
-    installCommand: "npm install -g caplets",
-    configSnippet: `{
-  "command": "caplets",
-  "args": ["serve"]
-}`,
-    note: "Any MCP-compatible client can launch Caplets over stdio.",
-  },
-];
-```
-
-## Task 1: Centralize agent setup data and render static panels
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-
-- [ ] **Step 1: Replace the current integrations array with structured data**
-
-In `apps/landing/src/pages/index.astro`, replace:
-
-```ts
-const integrations = ["Claude Code", "Codex", "OpenCode", "Pi", "Any MCP client"];
-```
-
-with the `agentSetups` array from the "Setup data to use" section, then add:
-
-```ts
-const integrations = agentSetups.map((agent) => agent.name);
-```
-
-This preserves the hero facts while making the integrations section data-driven.
-
-- [ ] **Step 2: Replace the integrations strip markup**
-
-Replace the current integrations section body:
-
-```astro
-<ul class="integration-strip" aria-label="Supported integrations">
-  {integrations.map((name) => <li>{name}</li>)}
-</ul>
-```
-
-with:
-
-```astro
-<div class="agent-setup-card" data-agent-tabs>
-  <div class="integration-strip" role="tablist" aria-label="Supported integrations">
-    {agentSetups.map((agent, index) => (
-      <button
-        class="integration-pill"
-        id={`agent-tab-${agent.id}`}
-        type="button"
-        role="tab"
-        aria-selected={index === 0 ? "true" : "false"}
-        aria-controls={`agent-panel-${agent.id}`}
-        data-agent-tab={agent.id}
-      >
-        {agent.name}
-      </button>
-    ))}
-  </div>
-  <div class="agent-setup-panels">
-    {agentSetups.map((agent, index) => (
-      <article
-        class="agent-setup-panel"
-        id={`agent-panel-${agent.id}`}
-        role="tabpanel"
-        aria-labelledby={`agent-tab-${agent.id}`}
-        data-agent-panel={agent.id}
-        hidden={index !== 0}
-      >
-        <p class="agent-setup-note">{agent.note}</p>
-        <div class="agent-setup-grid">
-          <div>
-            <span class="agent-setup-label">Install</span>
-            <pre><code>{agent.installCommand}</code></pre>
-          </div>
-          <div>
-            <span class="agent-setup-label">Configuration</span>
-            <pre><code>{agent.configSnippet}</code></pre>
-          </div>
-        </div>
-      </article>
-    ))}
-  </div>
-</div>
-```
-
-- [ ] **Step 3: Run the landing typecheck and verify expected initial failure or pass**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-```
-
-Expected: PASS. If it fails, fix only syntax/type issues in `index.astro` before continuing.
-
-- [ ] **Step 4: Commit static rendering**
-
-```bash
-git add apps/landing/src/pages/index.astro
-git commit -m "feat(landing): render agent setup panels"
-```
-
-## Task 2: Add tab behavior
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-
-- [ ] **Step 1: Add the tab switching script**
-
-Inside the existing `<script>` block, after `const canAnimate = ...;`, add:
-
-```ts
-const agentTabsRoot = document.querySelector<HTMLElement>("[data-agent-tabs]");
-const agentTabs = Array.from(document.querySelectorAll<HTMLButtonElement>("[data-agent-tab]"));
-const agentPanels = Array.from(document.querySelectorAll<HTMLElement>("[data-agent-panel]"));
-
-function selectAgentTab(selectedId: string) {
-  for (const tab of agentTabs) {
-    const isSelected = tab.dataset.agentTab === selectedId;
-    tab.setAttribute("aria-selected", String(isSelected));
-    tab.tabIndex = isSelected ? 0 : -1;
-  }
-
-  for (const panel of agentPanels) {
-    panel.hidden = panel.dataset.agentPanel !== selectedId;
-  }
-}
-
-if (agentTabsRoot && agentTabs.length > 0 && agentPanels.length > 0) {
-  selectAgentTab(agentTabs[0].dataset.agentTab ?? "");
-
-  for (const tab of agentTabs) {
-    tab.addEventListener("click", () => {
-      const selectedId = tab.dataset.agentTab;
-      if (selectedId) selectAgentTab(selectedId);
-    });
-
-    tab.addEventListener("keydown", (event: KeyboardEvent) => {
-      const currentIndex = agentTabs.indexOf(tab);
-      const lastIndex = agentTabs.length - 1;
-      const nextIndex =
-        event.key === "ArrowRight"
-          ? currentIndex + 1
-          : event.key === "ArrowLeft"
-            ? currentIndex - 1
-            : event.key === "Home"
-              ? 0
-              : event.key === "End"
-                ? lastIndex
-                : currentIndex;
-      const wrappedIndex = nextIndex < 0 ? lastIndex : nextIndex > lastIndex ? 0 : nextIndex;
-
-      if (wrappedIndex !== currentIndex) {
-        event.preventDefault();
-        const nextTab = agentTabs[wrappedIndex];
-        const selectedId = nextTab.dataset.agentTab;
-        nextTab.focus();
-        if (selectedId) selectAgentTab(selectedId);
-      }
-    });
-  }
-}
-```
-
-- [ ] **Step 2: Include panels in reveal targets**
-
-Replace the reveal target selector:
-
-```ts
-".problem, .proof, .integrations, .install, .proof-item, .integration-strip li, .terminal li";
-```
-
-with:
-
-```ts
-".problem, .proof, .integrations, .install, .proof-item, .integration-pill, .agent-setup-panel, .terminal li";
-```
-
-- [ ] **Step 3: Run typecheck**
-
-```bash
-pnpm --filter @caplets/landing typecheck
-```
-
-Expected: PASS with 0 errors.
-
-- [ ] **Step 4: Commit behavior**
-
-```bash
-git add apps/landing/src/pages/index.astro
-git commit -m "feat(landing): switch agent setup tabs"
-```
-
-## Task 3: Style pills as tabs and preserve card aesthetics
-
-**Files:**
-
-- Modify: `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Replace list-item pill styles with button/tab styles**
-
-Replace:
-
-```css
-.integration-strip li {
-  border: 1px solid var(--night-line);
-  border-radius: 999px;
-  padding: 10px 12px;
-  color: var(--night-text);
-  background: oklch(28% 0.018 100);
-  font-family: var(--font-mono);
-  font-size: 0.78rem;
-  font-weight: 700;
-}
-```
-
-with:
-
-```css
-.integration-pill {
-  border: 1px solid var(--night-line);
-  border-radius: 999px;
-  padding: 10px 12px;
-  color: var(--night-text);
-  background: oklch(28% 0.018 100);
-  font: inherit;
-  font-family: var(--font-mono);
-  font-size: 0.78rem;
-  font-weight: 700;
-  cursor: pointer;
-  transition:
-    background-color 180ms var(--ease-out),
-    border-color 180ms var(--ease-out),
-    color 180ms var(--ease-out),
-    transform 180ms var(--ease-out);
-}
-
-.integration-pill:hover,
-.integration-pill[aria-selected="true"] {
-  border-color: oklch(86% 0.08 35);
-  background: var(--parchment);
-  color: var(--night-ink);
-  transform: translateY(-1px);
-}
-```
-
-- [ ] **Step 2: Add setup panel styles after the pill styles**
-
-Add:
-
-```css
-.agent-setup-card {
-  min-width: 0;
-  display: grid;
-  gap: 18px;
-}
-
-.agent-setup-panels {
-  min-width: 0;
-  border: 1px solid var(--night-line);
-  border-radius: 20px;
-  background: oklch(25% 0.016 100);
-  overflow: hidden;
-}
-
-.agent-setup-panel {
-  padding: 18px;
-}
-
-.agent-setup-panel[hidden] {
-  display: none;
-}
-
-.agent-setup-note {
-  margin: 0 0 14px;
-  color: var(--night-muted);
-}
-
-.agent-setup-grid {
-  display: grid;
-  grid-template-columns: minmax(0, 0.82fr) minmax(0, 1.18fr);
-  gap: 12px;
-}
-
-.agent-setup-label {
-  display: block;
-  margin-bottom: 8px;
-  color: oklch(86% 0.08 35);
-  font-family: var(--font-mono);
-  font-size: 0.68rem;
-  font-weight: 800;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-}
-
-.agent-setup-panel pre {
-  min-width: 0;
-  min-height: 100%;
-  margin: 0;
-  padding: 14px;
-  border: 1px solid var(--night-line);
-  border-radius: 14px;
-  background: var(--night-ink);
-  color: var(--night-text);
-  overflow-x: auto;
-}
-
-.agent-setup-panel code {
-  font-family: var(--font-mono);
-  font-size: 0.78rem;
-  line-height: 1.5;
-  white-space: pre-wrap;
-  overflow-wrap: anywhere;
-}
-```
-
-- [ ] **Step 3: Update reduced-motion selector**
-
-Replace any remaining `.integration-strip li` selector in animation/reveal CSS with `.integration-pill` so reveal styling still applies to the new buttons.
-
-- [ ] **Step 4: Add responsive stacking**
-
-Inside the existing small-screen media query where `.integration-strip` is adjusted, add:
-
-```css
-.agent-setup-grid {
-  grid-template-columns: 1fr;
-}
-```
-
-- [ ] **Step 5: Run formatting and typecheck**
-
-```bash
-pnpm format:check
-pnpm --filter @caplets/landing typecheck
-```
-
-Expected: both PASS.
-
-- [ ] **Step 6: Commit styling**
-
-```bash
-git add apps/landing/src/styles/global.css
-git commit -m "style(landing): polish agent setup tabs"
-```
-
-## Task 4: Verify and document final state
-
-**Files:**
-
-- Modify only if verification reveals a bug: `apps/landing/src/pages/index.astro`, `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Run focused checks**
-
-```bash
-pnpm format:check
-pnpm lint
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-```
-
-Expected: all commands PASS.
-
-- [ ] **Step 2: Inspect the rendered output locally**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing build
-```
-
-Expected: Astro build completes and generated HTML includes `role="tablist"`, each agent label, install commands, and config snippets.
-
-- [ ] **Step 3: Commit verification fixes if any**
-
-If Step 1 or Step 2 required changes:
-
-```bash
-git add apps/landing/src/pages/index.astro apps/landing/src/styles/global.css
-git commit -m "fix(landing): verify agent setup tabs"
-```
-
-If no changes were required, do not create an empty commit.
-
-- [ ] **Step 4: Final status check**
-
-```bash
-git status --short
-```
-
-Expected: no unexpected unstaged changes. Existing unrelated user changes may remain and must be called out in the implementation summary.
-
-## Self-review
-
-- Spec coverage: The plan preserves the existing card, turns pills into tabs, shows install/config content per agent, centralizes data, includes accessibility semantics, and defines verification commands.
-- Placeholder scan: No TBD/TODO/fill-in placeholders remain.
-- Type consistency: The plan consistently uses `agentSetups`, `data-agent-tab`, `data-agent-panel`, `.integration-pill`, and `.agent-setup-panel` across markup, script, and CSS.
diff --git a/docs/plans/2026-05-27-lossless-markdown-result-content.md b/docs/plans/2026-05-27-lossless-markdown-result-content.md
deleted file mode 100644
index 2056d5bf..00000000
--- a/docs/plans/2026-05-27-lossless-markdown-result-content.md
+++ /dev/null
@@ -1,1831 +0,0 @@
-# Lossless Markdown Result Content Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make every Caplets-generated tool result expose the same untruncated data in both `structuredContent` and agent/human-readable Markdown `content`.
-
-**Architecture:** Add one shared lossless Markdown renderer in `@caplets/core`, then route every Caplets-generated result shape through backend-aware renderers. Keep `structuredContent` canonical and unchanged; make `content` a complete Markdown projection of that same data instead of a compact preview. Preserve downstream MCP-authored content, but append a complete structured-content Markdown section when downstream `structuredContent` would otherwise be invisible to content-only clients.
-
-**Tech Stack:** TypeScript, MCP SDK `CallToolResult`, Vitest, pnpm, existing Caplets core/pi/opencode packages.
-
----
-
-## Scope And Decisions
-
-- The core MCP Markdown renderer must not truncate `content`. Existing backend read limits such as HTTP `maxResponseBytes` and CLI `maxOutputBytes` still bound what Caplets receives from downstream systems; the Markdown renderer must not apply any additional truncation.
-- `structuredContent` remains the canonical machine-readable object and must not be removed or compacted.
-- `content` must contain all data from `structuredContent` in Markdown form for Caplets-generated results.
-- Use backend-aware Markdown for known shapes: HTTP/OpenAPI, GraphQL, CLI, discovery/listing, tools, errors, and generic structured results.
-- Nested API data stays in fenced JSON blocks. Do not recursively turn arbitrary object keys into headings.
-- MCP downstream `content` should be preserved when meaningful. If downstream returns `structuredContent`, append a Markdown rendering of that structured data so content-only MCP clients still see it.
-- Pi and OpenCode native integrations should consume the same core Markdown renderer for agent-visible payloads instead of maintaining local lossy formatting.
-- Pi UI rendering is a separate display concern: collapsed tool results must stay short/truncated, and expanded results opened with `ctrl+o` must show the full Markdown content.
-
-## File Structure
-
-- Modify `packages/core/src/result-content.ts`
-  - Replace compact preview behavior with lossless Markdown rendering helpers.
-  - Keep `compactJsonText()` and `compactText()` only if still used by other UI preview code.
-  - Export `markdownStructuredContent()`, `markdownCallToolResultContent()`, and `hasRenderableStructuredContent()`.
-- Modify `packages/core/src/index.ts`
-  - Export the result-content Markdown helpers for native integrations.
-- Modify `packages/core/src/tools.ts`
-  - Use Markdown `content` in `jsonResult()` discovery operations.
-  - Regenerate/append Markdown `content` in `annotateCallToolResult()` after metadata is known.
-  - Use Markdown `content` for field-selected results.
-- Modify generated backends:
-  - `packages/core/src/http-actions.ts`
-  - `packages/core/src/openapi.ts`
-  - `packages/core/src/graphql.ts`
-  - `packages/core/src/cli-tools.ts`
-  - Each manager should return Markdown content for direct manager calls as well as the shared wrapper path.
-- Modify `packages/core/src/errors.ts`
-  - Render safe errors as complete Markdown while keeping `structuredContent.error` unchanged.
-- Modify native integrations:
-  - `packages/pi/src/index.ts`
-  - `packages/opencode/src/hooks.ts`
-  - Prefer core Markdown projection of structured results.
-- Modify tests:
-  - `packages/core/test/result-content.test.ts`
-  - `packages/core/test/http-actions.test.ts`
-  - `packages/core/test/openapi.test.ts`
-  - `packages/core/test/graphql.test.ts`
-  - `packages/core/test/cli-tools.test.ts`
-  - `packages/core/test/tools.test.ts`
-  - `packages/core/test/downstream.test.ts`
-  - `packages/core/test/field-selection.test.ts`
-  - `packages/pi/test/pi.test.ts`
-  - `packages/opencode/test/opencode.test.ts`
-- Add a changeset because this changes user-visible MCP result content:
-  - `.changeset/lossless-markdown-results.md`
-
----
-
-## Markdown Format Contract
-
-### HTTP and OpenAPI
-
-````md
-# OSV Vulnerabilities call_tool query_purl
-
-## Response
-
-- **Status:** `200 OK`
-- **Elapsed:** `84 ms`
-
-## Headers
-
-```json
-{
-  "content-type": "application/json"
-}
-```
-````
-
-## Body
-
-```json
-{
-  "vulns": []
-}
-```
-
-````
-
-### GraphQL
-
-```md
-# GitHub GraphQL call_tool viewer
-
-## Response
-
-- **Status:** `200 OK`
-
-## Data
-
-```json
-{
-  "viewer": {
-    "login": "octocat"
-  }
-}
-````
-
-## Headers
-
-```json
-{
-  "content-type": "application/json"
-}
-```
-
-## Full Body
-
-```json
-{
-  "data": {
-    "viewer": {
-      "login": "octocat"
-    }
-  }
-}
-```
-
-````
-
-### CLI
-
-```md
-# Repo CLI call_tool search
-
-## Command Result
-
-- **Exit code:** `0`
-- **Elapsed:** `52 ms`
-
-## stdout
-
-```text
-matched line 1
-matched line 2
-````
-
-## stderr
-
-_No stderr._
-
-````
-
-When CLI output mode is JSON and parsing succeeds, include the parsed `json` field too:
-
-```md
-## Parsed JSON
-
-```json
-{
-  "matches": []
-}
-````
-
-````
-
-### Discovery and generated JSON results
-
-```md
-# OSV Vulnerabilities list_tools
-
-## Tools
-
-1. `query_purl` — Read-only OSV query for vulnerabilities affecting one package URL.
-2. `query_version` — Query vulnerabilities for one package version.
-
-## Full Result
-
-```json
-{
-  "id": "osv",
-  "name": "OSV Vulnerabilities",
-  "tools": []
-}
-````
-
-## Caplets Metadata
-
-```json
-{
-  "id": "osv",
-  "name": "OSV Vulnerabilities",
-  "backend": "http",
-  "operation": "list_tools",
-  "status": "ok"
-}
-```
-
-````
-
-### MCP downstream with both content and structured content
-
-```md
-# Browser call_tool browser_snapshot
-
-<downstream text content preserved exactly>
-
----
-
-## Structured Content
-
-```json
-{
-  "snapshot": "Page title: Example"
-}
-````
-
-````
-
-### Error result
-
-```md
-# Error
-
-## REQUEST_INVALID
-
-Generated server tool request is invalid.
-
-## Details
-
-```json
-{
-  "code": "REQUEST_INVALID",
-  "message": "Generated server tool request is invalid",
-  "details": []
-}
-````
-
-````
-
----
-
-### Task 1: Add Lossless Markdown Renderer Tests
-
-**Files:**
-- Modify: `packages/core/test/result-content.test.ts`
-
-- [ ] **Step 1: Replace compact-preview expectations with lossless Markdown expectations**
-
-Update the import at the top of `packages/core/test/result-content.test.ts`:
-
-```ts
-import { describe, expect, it } from "vitest";
-import {
-  compactJsonText,
-  hasRenderableStructuredContent,
-  markdownCallToolResultContent,
-  markdownStructuredContent,
-} from "../src/result-content";
-````
-
-Replace the existing compact HTTP preview test with these tests:
-
-````ts
-it("renders HTTP-like structured content as complete Markdown", () => {
-  const content = markdownStructuredContent(
-    {
-      status: 200,
-      statusText: "OK",
-      headers: { "content-type": "application/json" },
-      body: { vulns: [] },
-      elapsedMs: 12,
-    },
-    {
-      title: "OSV Vulnerabilities call_tool query_purl",
-      backend: "http",
-      operation: "call_tool",
-      tool: "query_purl",
-    },
-  );
-
-  expect(content).toEqual([
-    {
-      type: "text",
-      text: [
-        "# OSV Vulnerabilities call_tool query_purl",
-        "",
-        "## Response",
-        "",
-        "- **Status:** `200 OK`",
-        "- **Elapsed:** `12 ms`",
-        "",
-        "## Headers",
-        "",
-        "```json",
-        '{\n  "content-type": "application/json"\n}',
-        "```",
-        "",
-        "## Body",
-        "",
-        "```json",
-        '{\n  "vulns": []\n}',
-        "```",
-      ].join("\n"),
-    },
-  ]);
-});
-
-it("renders GraphQL body data and full body without losing fields", () => {
-  const text = markdownStructuredContent(
-    {
-      status: 200,
-      statusText: "OK",
-      headers: { "content-type": "application/json" },
-      body: { data: { viewer: { login: "octocat" } } },
-    },
-    { title: "GitHub GraphQL call_tool viewer", backend: "graphql" },
-  )[0]!.text;
-
-  expect(text).toContain("# GitHub GraphQL call_tool viewer");
-  expect(text).toContain("## Data");
-  expect(text).toContain('"viewer": {');
-  expect(text).toContain("## Full Body");
-  expect(text).toContain("## Headers");
-});
-
-it("renders CLI stdout stderr and parsed JSON without truncation", () => {
-  const text = markdownStructuredContent(
-    {
-      exitCode: 0,
-      stdout: '{"matches":[]}',
-      stderr: "",
-      elapsedMs: 52,
-      json: { matches: [] },
-    },
-    { title: "Repo CLI call_tool search", backend: "cli" },
-  )[0]!.text;
-
-  expect(text).toContain("# Repo CLI call_tool search");
-  expect(text).toContain("## Command Result");
-  expect(text).toContain("- **Exit code:** `0`");
-  expect(text).toContain("## stdout");
-  expect(text).toContain('{"matches":[]}');
-  expect(text).toContain("## stderr\n\n_No stderr._");
-  expect(text).toContain("## Parsed JSON");
-  expect(text).toContain('"matches": []');
-});
-
-it("renders discovery result lists and metadata", () => {
-  const text = markdownStructuredContent(
-    {
-      caplets: {
-        id: "osv",
-        name: "OSV Vulnerabilities",
-        backend: "http",
-        operation: "list_tools",
-        status: "ok",
-      },
-      result: {
-        id: "osv",
-        name: "OSV Vulnerabilities",
-        tools: [
-          {
-            id: "osv",
-            tool: "query_purl",
-            description: "Query vulnerabilities by package URL.",
-            hasInputSchema: true,
-            hasOutputSchema: false,
-          },
-        ],
-      },
-    },
-    { title: "OSV Vulnerabilities list_tools", operation: "list_tools" },
-  )[0]!.text;
-
-  expect(text).toContain("# OSV Vulnerabilities list_tools");
-  expect(text).toContain("## Tools");
-  expect(text).toContain("1. `query_purl` — Query vulnerabilities by package URL.");
-  expect(text).toContain("## Full Result");
-  expect(text).toContain("## Caplets Metadata");
-  expect(text).toContain('"operation": "list_tools"');
-});
-
-it("preserves downstream text and appends structured content for MCP results", () => {
-  const content = markdownCallToolResultContent(
-    {
-      content: [{ type: "text", text: "Downstream text" }],
-      structuredContent: { snapshot: { title: "Example" } },
-    },
-    { title: "Browser call_tool browser_snapshot", backend: "mcp" },
-  );
-
-  expect(content).toEqual([
-    {
-      type: "text",
-      text: [
-        "# Browser call_tool browser_snapshot",
-        "",
-        "Downstream text",
-        "",
-        "---",
-        "",
-        "## Structured Content",
-        "",
-        "```json",
-        '{\n  "snapshot": {\n    "title": "Example"\n  }\n}',
-        "```",
-      ].join("\n"),
-    },
-  ]);
-});
-
-it("detects renderable structured content while ignoring metadata-only objects", () => {
-  expect(hasRenderableStructuredContent({ body: { ok: true } })).toBe(true);
-  expect(hasRenderableStructuredContent({ caplets: { status: "ok" } })).toBe(false);
-  expect(hasRenderableStructuredContent(undefined)).toBe(false);
-});
-````
-
-- [ ] **Step 2: Run the focused test to verify it fails**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/result-content.test.ts
-```
-
-Expected: FAIL because `markdownStructuredContent`, `markdownCallToolResultContent`, and `hasRenderableStructuredContent` are not implemented yet, and existing compact content does not match the new Markdown contract.
-
----
-
-### Task 2: Implement Shared Lossless Markdown Renderer
-
-**Files:**
-
-- Modify: `packages/core/src/result-content.ts`
-- Modify: `packages/core/src/index.ts`
-- Test: `packages/core/test/result-content.test.ts`
-
-- [ ] **Step 1: Implement renderer types and public helpers**
-
-Replace the compact summary functions in `packages/core/src/result-content.ts` with this structure while keeping `compactJsonText()` and `compactText()` for UI preview callers that still need compact strings:
-
-```ts
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types";
-
-export type TextContentBlock = { type: "text"; text: string };
-
-export type ResultMarkdownContext = {
-  title?: string | undefined;
-  backend?: string | undefined;
-  operation?: string | undefined;
-  tool?: string | undefined;
-  uri?: string | undefined;
-  prompt?: string | undefined;
-  fields?: string[] | undefined;
-  isError?: boolean | undefined;
-};
-
-export function structuredOnlyContent(): [] {
-  return [];
-}
-
-export function textContent(text: string): TextContentBlock[] {
-  return text ? [{ type: "text", text }] : [];
-}
-
-export function compactJsonText(value: unknown, maxLength = 600): string {
-  return compactText(JSON.stringify(value) ?? String(value), maxLength);
-}
-
-export function compactText(value: string, maxLength = 600): string {
-  const collapsed = value.replace(/\s+/gu, " ").trim();
-  return collapsed.length > maxLength
-    ? `${collapsed.slice(0, maxLength - 1).trimEnd()}…`
-    : collapsed;
-}
-
-export function markdownStructuredContent(
-  value: unknown,
-  context: ResultMarkdownContext = {},
-): TextContentBlock[] {
-  return textContent(renderStructuredMarkdown(value, context));
-}
-
-export function markdownCallToolResultContent(
-  result: CallToolResult,
-  context: ResultMarkdownContext = {},
-): TextContentBlock[] {
-  if (result.isError === true && !hasRenderableStructuredContent(result.structuredContent)) {
-    return textContent(renderTextBlocksWithTitle(result.content, context));
-  }
-
-  const structuredContent = result.structuredContent;
-  const downstreamText = textBlocksToString(result.content);
-  const hasStructured = hasRenderableStructuredContent(structuredContent);
-
-  if (context.backend === "mcp" && downstreamText && hasStructured) {
-    return textContent(
-      [
-        markdownTitle(context),
-        "",
-        downstreamText,
-        "",
-        "---",
-        "",
-        "## Structured Content",
-        "",
-        jsonFence(structuredContent),
-      ].join("\n"),
-    );
-  }
-
-  if (hasStructured) {
-    return markdownStructuredContent(structuredContent, context);
-  }
-
-  if (downstreamText) {
-    return textContent(renderTextBlocksWithTitle(result.content, context));
-  }
-
-  return textContent(renderStructuredMarkdown(result, context));
-}
-
-export function compactStructuredContent(
-  value: unknown,
-  context: ResultMarkdownContext = {},
-): TextContentBlock[] {
-  return markdownStructuredContent(value, context);
-}
-
-export function compactCallToolResultContent(
-  result: CallToolResult,
-  context: ResultMarkdownContext = {},
-): TextContentBlock[] {
-  return markdownCallToolResultContent(result, context);
-}
-
-export function hasRenderableStructuredContent(value: unknown): boolean {
-  if (!isRecord(value)) {
-    return false;
-  }
-  return Object.keys(value).some((key) => key !== "caplets" && key !== "elapsedMs");
-}
-```
-
-Add these private rendering helpers below the public functions:
-
-```ts
-function renderStructuredMarkdown(value: unknown, context: ResultMarkdownContext): string {
-  const title = markdownTitle(context);
-  if (isDiscoveryWrapper(value)) {
-    return renderDiscoveryWrapper(value, context, title);
-  }
-  if (context.isError || isErrorStructuredContent(value)) {
-    return renderErrorMarkdown(value, title);
-  }
-  if (context.backend === "cli" || isCliResult(value)) {
-    return renderCliMarkdown(value, title);
-  }
-  if (context.backend === "graphql" || isGraphQlHttpResult(value)) {
-    return renderGraphQlMarkdown(value, title);
-  }
-  if (context.backend === "http" || context.backend === "openapi" || isHttpLikeResult(value)) {
-    return renderHttpMarkdown(value, title);
-  }
-  return [title, "", "## Result", "", jsonFence(value)].join("\n");
-}
-
-function markdownTitle(context: ResultMarkdownContext): string {
-  if (context.title) {
-    return `# ${context.title}`;
-  }
-  const parts = [context.operation, context.tool ?? context.uri ?? context.prompt].filter(
-    (part): part is string => Boolean(part),
-  );
-  return parts.length > 0 ? `# ${parts.join(" ")}` : "# Result";
-}
-
-function renderHttpMarkdown(value: unknown, title: string): string {
-  const record = asRecord(value);
-  const lines = [title, "", "## Response", ""];
-  const status = typeof record.status === "number" ? record.status : undefined;
-  const statusText = typeof record.statusText === "string" ? record.statusText : undefined;
-  if (status !== undefined || statusText) {
-    lines.push(`- **Status:** \`${[status, statusText].filter(Boolean).join(" ")}\``);
-  }
-  if (typeof record.elapsedMs === "number") {
-    lines.push(`- **Elapsed:** \`${record.elapsedMs} ms\``);
-  }
-  lines.push("", "## Headers", "", jsonFence(record.headers ?? {}), "", "## Body", "");
-  lines.push(renderBodyValue(record.body));
-  const additional = omitKeys(record, ["status", "statusText", "headers", "body", "elapsedMs"]);
-  if (Object.keys(additional).length > 0) {
-    lines.push("", "## Additional Fields", "", jsonFence(additional));
-  }
-  return lines.join("\n");
-}
-
-function renderGraphQlMarkdown(value: unknown, title: string): string {
-  const record = asRecord(value);
-  const body = asRecord(record.body);
-  if (!body || (!("data" in body) && !("errors" in body))) {
-    return renderHttpMarkdown(value, title);
-  }
-
-  const lines = [title, "", "## Response", ""];
-  const status = typeof record.status === "number" ? record.status : undefined;
-  const statusText = typeof record.statusText === "string" ? record.statusText : undefined;
-  if (status !== undefined || statusText) {
-    lines.push(`- **Status:** \`${[status, statusText].filter(Boolean).join(" ")}\``);
-  }
-  if (typeof record.elapsedMs === "number") {
-    lines.push(`- **Elapsed:** \`${record.elapsedMs} ms\``);
-  }
-  if ("data" in body) {
-    lines.push("", "## Data", "", jsonFence(body.data));
-  }
-  if ("errors" in body) {
-    lines.push("", "## Errors", "", jsonFence(body.errors));
-  }
-  lines.push("", "## Headers", "", jsonFence(record.headers ?? {}));
-  lines.push("", "## Full Body", "", jsonFence(record.body));
-  const additional = omitKeys(record, ["status", "statusText", "headers", "body", "elapsedMs"]);
-  if (Object.keys(additional).length > 0) {
-    lines.push("", "## Additional Fields", "", jsonFence(additional));
-  }
-  return lines.join("\n");
-}
-
-function renderCliMarkdown(value: unknown, title: string): string {
-  const record = asRecord(value);
-  const lines = [title, "", "## Command Result", ""];
-  if ("exitCode" in record) {
-    lines.push(`- **Exit code:** \`${String(record.exitCode)}\``);
-  }
-  if ("signal" in record) {
-    lines.push(`- **Signal:** \`${String(record.signal)}\``);
-  }
-  if (typeof record.elapsedMs === "number") {
-    lines.push(`- **Elapsed:** \`${record.elapsedMs} ms\``);
-  }
-  lines.push("", "## stdout", "", textFenceOrEmpty(record.stdout, "No stdout."));
-  lines.push("", "## stderr", "", textFenceOrEmpty(record.stderr, "No stderr."));
-  if ("json" in record) {
-    lines.push("", "## Parsed JSON", "", jsonFence(record.json));
-  }
-  if ("jsonParseError" in record) {
-    lines.push("", "## JSON Parse Error", "", jsonFence(record.jsonParseError));
-  }
-  const additional = omitKeys(record, [
-    "exitCode",
-    "signal",
-    "stdout",
-    "stderr",
-    "elapsedMs",
-    "json",
-    "jsonParseError",
-  ]);
-  if (Object.keys(additional).length > 0) {
-    lines.push("", "## Additional Fields", "", jsonFence(additional));
-  }
-  return lines.join("\n");
-}
-
-function renderDiscoveryWrapper(
-  value: { result: unknown; caplets?: unknown },
-  context: ResultMarkdownContext,
-  title: string,
-): string {
-  const result = asRecord(value.result);
-  const lines = [title, ""];
-  if (context.operation === "list_tools" || context.operation === "search_tools") {
-    lines.push("## Tools", "", renderNamedList(arrayValue(result?.tools), "tool"), "");
-  } else if (context.operation === "list_resources" || context.operation === "search_resources") {
-    lines.push(
-      "## Resources",
-      "",
-      renderNamedList(arrayValue(result?.resources ?? result?.matches), "uri"),
-      "",
-    );
-  } else if (context.operation === "list_resource_templates") {
-    lines.push(
-      "## Resource Templates",
-      "",
-      renderNamedList(arrayValue(result?.resourceTemplates), "uriTemplate"),
-      "",
-    );
-  } else if (context.operation === "list_prompts" || context.operation === "search_prompts") {
-    lines.push("## Prompts", "", renderNamedList(arrayValue(result?.prompts), "prompt"), "");
-  } else if (context.operation === "get_tool") {
-    lines.push("## Tool", "", renderToolSummary(asRecord(result?.tool)), "");
-  } else if (context.operation === "check_backend") {
-    lines.push("## Backend Status", "", renderBackendStatus(result), "");
-  } else if (context.operation === "get_caplet") {
-    lines.push("## Caplet", "", renderCapletSummary(result), "");
-  }
-  lines.push("## Full Result", "", jsonFence(value.result));
-  if (value.caplets !== undefined) {
-    lines.push("", "## Caplets Metadata", "", jsonFence(value.caplets));
-  }
-  return lines.join("\n");
-}
-
-function renderErrorMarkdown(value: unknown, title: string): string {
-  const error = asRecord(asRecord(value)?.error) ?? asRecord(value);
-  const code = typeof error?.code === "string" ? error.code : "Error";
-  const message = typeof error?.message === "string" ? error.message : "Tool call failed.";
-  return [
-    title === "# Result" ? "# Error" : title,
-    "",
-    `## ${code}`,
-    "",
-    message,
-    "",
-    "## Details",
-    "",
-    jsonFence(error ?? value),
-  ].join("\n");
-}
-```
-
-Add these lower-level helpers to the bottom of `packages/core/src/result-content.ts`:
-
-````ts
-function isDiscoveryWrapper(value: unknown): value is { result: unknown; caplets?: unknown } {
-  return isRecord(value) && "result" in value;
-}
-
-function isErrorStructuredContent(value: unknown): boolean {
-  return isRecord(value) && "error" in value;
-}
-
-function isHttpLikeResult(value: unknown): boolean {
-  return isRecord(value) && ("status" in value || "statusText" in value || "body" in value);
-}
-
-function isGraphQlHttpResult(value: unknown): boolean {
-  if (!isHttpLikeResult(value)) {
-    return false;
-  }
-  const body = asRecord((value as Record<string, unknown>).body);
-  return Boolean(body && ("data" in body || "errors" in body));
-}
-
-function isCliResult(value: unknown): boolean {
-  return isRecord(value) && ("exitCode" in value || "stdout" in value || "stderr" in value);
-}
-
-function renderBodyValue(value: unknown): string {
-  if (value === undefined) {
-    return "_No response body._";
-  }
-  if (typeof value === "string") {
-    return textFenceOrEmpty(value, "No response body.");
-  }
-  return jsonFence(value);
-}
-
-function textFenceOrEmpty(value: unknown, emptyMessage: string): string {
-  if (typeof value !== "string" || value.length === 0) {
-    return `_${emptyMessage}_`;
-  }
-  return ["```text", escapeCodeFence(value), "```"].join("\n");
-}
-
-function jsonFence(value: unknown): string {
-  return ["```json", escapeCodeFence(JSON.stringify(value, null, 2) ?? "null"), "```"].join("\n");
-}
-
-function escapeCodeFence(value: string): string {
-  return value.replace(/```/gu, "`\u200b``");
-}
-
-function textBlocksToString(content: CallToolResult["content"] | undefined): string {
-  if (!Array.isArray(content)) {
-    return "";
-  }
-  return content
-    .filter((item): item is { type: "text"; text: string } =>
-      Boolean(
-        item && typeof item === "object" && item.type === "text" && typeof item.text === "string",
-      ),
-    )
-    .map((item) => item.text)
-    .filter(Boolean)
-    .join("\n");
-}
-
-function renderTextBlocksWithTitle(
-  content: CallToolResult["content"] | undefined,
-  context: ResultMarkdownContext,
-): string {
-  const text = textBlocksToString(content);
-  return text ? [markdownTitle(context), "", text].join("\n") : markdownTitle(context);
-}
-
-function renderNamedList(items: unknown[], nameKey: string): string {
-  if (items.length === 0) {
-    return "_No items._";
-  }
-  return items
-    .map((item, index) => {
-      const record = asRecord(item);
-      const name =
-        stringValue(record?.[nameKey]) ?? stringValue(record?.name) ?? `Item ${index + 1}`;
-      const description = stringValue(record?.description);
-      return description
-        ? `${index + 1}. \`${name}\` — ${description}`
-        : `${index + 1}. \`${name}\``;
-    })
-    .join("\n");
-}
-
-function renderToolSummary(tool: Record<string, unknown> | undefined): string {
-  if (!tool) {
-    return "_Tool details unavailable._";
-  }
-  const lines = [];
-  const name = stringValue(tool.name);
-  const description = stringValue(tool.description);
-  if (name) lines.push(`- **Name:** \`${name}\``);
-  if (description) lines.push(`- **Description:** ${description}`);
-  if (tool.inputSchema !== undefined)
-    lines.push("", "### Input Schema", "", jsonFence(tool.inputSchema));
-  if (tool.outputSchema !== undefined)
-    lines.push("", "### Output Schema", "", jsonFence(tool.outputSchema));
-  if (tool.annotations !== undefined)
-    lines.push("", "### Annotations", "", jsonFence(tool.annotations));
-  return lines.length > 0 ? lines.join("\n") : jsonFence(tool);
-}
-
-function renderBackendStatus(result: Record<string, unknown> | undefined): string {
-  if (!result) {
-    return "_Backend status unavailable._";
-  }
-  const lines = [];
-  for (const key of [
-    "id",
-    "status",
-    "toolCount",
-    "resourceCount",
-    "resourceTemplateCount",
-    "promptCount",
-    "elapsedMs",
-  ]) {
-    if (result[key] !== undefined) {
-      const label = key === "elapsedMs" ? "Elapsed" : humanizeKey(key);
-      const suffix = key === "elapsedMs" ? " ms" : "";
-      lines.push(`- **${label}:** \`${String(result[key])}${suffix}\``);
-    }
-  }
-  if (result.error !== undefined) {
-    lines.push("", "### Error", "", jsonFence(result.error));
-  }
-  return lines.length > 0 ? lines.join("\n") : jsonFence(result);
-}
-
-function renderCapletSummary(result: Record<string, unknown> | undefined): string {
-  if (!result) {
-    return "_Caplet details unavailable._";
-  }
-  const lines = [];
-  for (const key of ["id", "name", "description"]) {
-    if (result[key] !== undefined) {
-      lines.push(`- **${humanizeKey(key)}:** ${String(result[key])}`);
-    }
-  }
-  const backend = asRecord(result.backend);
-  if (backend?.type !== undefined) {
-    lines.push(`- **Backend:** \`${String(backend.type)}\``);
-  }
-  return lines.length > 0 ? lines.join("\n") : jsonFence(result);
-}
-
-function omitKeys(record: Record<string, unknown>, keys: string[]): Record<string, unknown> {
-  const omitted = new Set(keys);
-  return Object.fromEntries(Object.entries(record).filter(([key]) => !omitted.has(key)));
-}
-
-function arrayValue(value: unknown): unknown[] {
-  return Array.isArray(value) ? value : [];
-}
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
-function humanizeKey(key: string): string {
-  return key.replace(/([A-Z])/gu, " $1").replace(/^./u, (char) => char.toUpperCase());
-}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return isRecord(value) ? value : undefined;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-````
-
-- [ ] **Step 2: Export helpers from core package index**
-
-Add this export to `packages/core/src/index.ts`:
-
-```ts
-export {
-  hasRenderableStructuredContent,
-  markdownCallToolResultContent,
-  markdownStructuredContent,
-} from "./result-content";
-export type { ResultMarkdownContext } from "./result-content";
-```
-
-- [ ] **Step 3: Run the focused renderer test**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/result-content.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 4: Commit renderer foundation**
-
-```bash
-git add packages/core/src/result-content.ts packages/core/src/index.ts packages/core/test/result-content.test.ts
-git commit -m "feat(core): render structured results as markdown content"
-```
-
----
-
-### Task 3: Wire Markdown Content Through Core Tool Wrappers
-
-**Files:**
-
-- Modify: `packages/core/src/tools.ts`
-- Modify: `packages/core/test/tools.test.ts`
-- Modify: `packages/core/test/field-selection.test.ts`
-
-- [ ] **Step 1: Add failing wrapper tests**
-
-In `packages/core/test/tools.test.ts`, update expectations that currently assert compact strings such as `"body"` or compact JSON previews. Add this test near existing OpenAPI/HTTP projection tests:
-
-```ts
-it("renders field-selected call_tool results as complete Markdown", async () => {
-  const result = await handleServerTool(
-    openApiServer,
-    { operation: "call_tool", tool: "getUser", arguments: { id: "42" }, fields: ["body.name"] },
-    openApiRegistry,
-    downstream,
-    openapi,
-  );
-
-  expect(result).toMatchObject({
-    structuredContent: { body: { name: "Ada" } },
-  });
-  expect(result.content[0].text).toContain("# OpenAPI call_tool getUser");
-  expect(result.content[0].text).toContain("## Body");
-  expect(result.content[0].text).toContain('"name": "Ada"');
-});
-```
-
-If the local fixture title is not `OpenAPI`, use the existing server name from that test file in the expectation.
-
-- [ ] **Step 2: Run wrapper tests to verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts test/field-selection.test.ts
-```
-
-Expected: FAIL because `jsonResult()`, `annotateCallToolResult()`, and field selection still use compact content or preserve compact backend content.
-
-- [ ] **Step 3: Import Markdown helpers in `packages/core/src/tools.ts`**
-
-Replace the existing result-content import:
-
-```ts
-import { compactStructuredContent } from "./result-content";
-```
-
-with:
-
-```ts
-import {
-  markdownCallToolResultContent,
-  markdownStructuredContent,
-  type ResultMarkdownContext,
-} from "./result-content";
-```
-
-- [ ] **Step 4: Add metadata-to-context helper**
-
-Add this helper below `metadataFor()` in `packages/core/src/tools.ts`:
-
-```ts
-function markdownContextFor(metadata: CapletResultMetadata): ResultMarkdownContext {
-  return {
-    title: [metadata.name, metadata.operation, metadata.tool ?? metadata.uri ?? metadata.prompt]
-      .filter(Boolean)
-      .join(" "),
-    backend: metadata.backend,
-    operation: metadata.operation,
-    ...(metadata.tool ? { tool: metadata.tool } : {}),
-    ...(metadata.uri ? { uri: metadata.uri } : {}),
-    ...(metadata.prompt ? { prompt: metadata.prompt } : {}),
-  };
-}
-```
-
-- [ ] **Step 5: Update `jsonResult()` to render Markdown content**
-
-Replace the `jsonResult()` implementation with:
-
-```ts
-export function jsonResult(value: unknown, metadata?: CapletResultMetadata): CallToolResult {
-  const structuredContent = {
-    ...(metadata === undefined ? {} : { caplets: metadata }),
-    result: value as Record<string, unknown>,
-  };
-  return {
-    content: markdownStructuredContent(
-      structuredContent,
-      metadata ? markdownContextFor(metadata) : { title: "Result" },
-    ),
-    structuredContent,
-  };
-}
-```
-
-- [ ] **Step 6: Update `annotateCallToolResult()` to produce final Markdown after metadata exists**
-
-Inside `annotateCallToolResult()`, replace the return object with:
-
-```ts
-const annotatedResult = {
-  ...result,
-  content: markdownCallToolResultContent(
-    result as CallToolResult,
-    markdownContextFor(annotatedMetadata),
-  ),
-  _meta: {
-    ...(isPlainObject(existingMeta) ? existingMeta : {}),
-    caplets: annotatedMetadata,
-  },
-};
-
-return annotatedResult as T & CallToolResult;
-```
-
-Keep the existing `existingMeta`, `artifacts`, and `annotatedMetadata` computation above this replacement unchanged.
-
-- [ ] **Step 7: Update `projectCallToolResult()` signature and content rendering**
-
-Change the function signature to:
-
-```ts
-export function projectCallToolResult<T extends object>(
-  result: T,
-  outputSchema: unknown,
-  fields: string[],
-  context: ResultMarkdownContext = {},
-): T & CallToolResult {
-```
-
-Replace the projected return block with:
-
-```ts
-return {
-  ...result,
-  content: markdownStructuredContent(projected, context),
-  structuredContent: projected,
-} as T & CallToolResult;
-```
-
-In `handleServerTool()` field-selection branch, compute metadata once and pass it to projection:
-
-```ts
-const metadata = metadataFor(server, "call_tool", parsed.tool, startedAt);
-const result = projectCallToolResult(
-  await backend.callTool(server as never, parsed.tool, parsed.arguments),
-  tool.outputSchema,
-  parsed.fields,
-  markdownContextFor(metadata),
-);
-return annotateCallToolResult(result, metadata);
-```
-
-- [ ] **Step 8: Run wrapper tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts test/field-selection.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 9: Commit wrapper wiring**
-
-```bash
-git add packages/core/src/tools.ts packages/core/test/tools.test.ts packages/core/test/field-selection.test.ts
-git commit -m "feat(core): render wrapped caplet results as markdown"
-```
-
----
-
-### Task 4: Wire HTTP and OpenAPI Backends
-
-**Files:**
-
-- Modify: `packages/core/src/http-actions.ts`
-- Modify: `packages/core/src/openapi.ts`
-- Modify: `packages/core/test/http-actions.test.ts`
-- Modify: `packages/core/test/openapi.test.ts`
-
-- [ ] **Step 1: Add failing HTTP action expectations**
-
-In `packages/core/test/http-actions.test.ts`, update the successful call test to assert Markdown content and unchanged structured content:
-
-```ts
-expect(result.structuredContent).toMatchObject({
-  status: 200,
-  statusText: "OK",
-  body: { ok: true },
-});
-expect(result.content[0].text).toContain("## Response");
-expect(result.content[0].text).toContain("- **Status:** `200 OK`");
-expect(result.content[0].text).toContain("## Body");
-expect(result.content[0].text).toContain('"ok": true');
-```
-
-Update the forbidden/non-2xx assertion to ensure error bodies remain visible:
-
-```ts
-expect(forbidden.structuredContent).toMatchObject({
-  status: 403,
-  statusText: "Forbidden",
-  body: { error: "denied" },
-});
-expect(forbidden.content[0].text).toContain("- **Status:** `403 Forbidden`");
-expect(forbidden.content[0].text).toContain('"error": "denied"');
-```
-
-- [ ] **Step 2: Add failing OpenAPI expectations**
-
-In `packages/core/test/openapi.test.ts`, update one successful call assertion:
-
-```ts
-expect(result.structuredContent).toMatchObject({
-  status: 200,
-  body: { name: "Ada" },
-});
-expect(result.content[0].text).toContain("## Response");
-expect(result.content[0].text).toContain("## Headers");
-expect(result.content[0].text).toContain("## Body");
-expect(result.content[0].text).toContain('"name": "Ada"');
-```
-
-- [ ] **Step 3: Run backend tests to verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/http-actions.test.ts test/openapi.test.ts
-```
-
-Expected: FAIL because direct manager calls still return compact content.
-
-- [ ] **Step 4: Update HTTP actions manager**
-
-In `packages/core/src/http-actions.ts`, replace the result-content import with:
-
-```ts
-import { markdownStructuredContent } from "./result-content";
-```
-
-Replace the `content` field in `callTool()` with:
-
-```ts
-        content: markdownStructuredContent(parsed, {
-          title: `${api.name} call_tool ${toolName}`,
-          backend: "http",
-          operation: "call_tool",
-          tool: toolName,
-        }),
-```
-
-- [ ] **Step 5: Update OpenAPI manager**
-
-In `packages/core/src/openapi.ts`, replace the result-content import with:
-
-```ts
-import { markdownStructuredContent } from "./result-content";
-```
-
-Replace the `content` field in `callTool()` with:
-
-```ts
-        content: markdownStructuredContent(parsed, {
-          title: `${endpoint.name} call_tool ${toolName}`,
-          backend: "openapi",
-          operation: "call_tool",
-          tool: toolName,
-        }),
-```
-
-- [ ] **Step 6: Run HTTP/OpenAPI tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/http-actions.test.ts test/openapi.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit HTTP/OpenAPI formatting**
-
-```bash
-git add packages/core/src/http-actions.ts packages/core/src/openapi.ts packages/core/test/http-actions.test.ts packages/core/test/openapi.test.ts
-git commit -m "feat(core): render http results as markdown content"
-```
-
----
-
-### Task 5: Wire GraphQL and CLI Backends
-
-**Files:**
-
-- Modify: `packages/core/src/graphql.ts`
-- Modify: `packages/core/src/cli-tools.ts`
-- Modify: `packages/core/test/graphql.test.ts`
-- Modify: `packages/core/test/cli-tools.test.ts`
-
-- [ ] **Step 1: Add failing GraphQL assertions**
-
-In `packages/core/test/graphql.test.ts`, update one successful operation assertion:
-
-```ts
-expect(result.structuredContent).toMatchObject({
-  status: 200,
-  body: { data: { viewer: { login: "octocat" } } },
-});
-expect(result.content[0].text).toContain("## Data");
-expect(result.content[0].text).toContain('"viewer": {');
-expect(result.content[0].text).toContain("## Full Body");
-```
-
-For an errors response test, add:
-
-```ts
-expect(result.content[0].text).toContain("## Errors");
-expect(result.content[0].text).toContain('"message"');
-```
-
-- [ ] **Step 2: Add failing CLI assertions**
-
-In `packages/core/test/cli-tools.test.ts`, update a successful text-output call assertion:
-
-```ts
-expect(result.structuredContent).toMatchObject({
-  exitCode: 0,
-  stdout: expect.stringContaining("hello"),
-  stderr: "",
-});
-expect(result.content[0].text).toContain("## Command Result");
-expect(result.content[0].text).toContain("- **Exit code:** `0`");
-expect(result.content[0].text).toContain("## stdout");
-expect(result.content[0].text).toContain("hello");
-expect(result.content[0].text).toContain("## stderr\n\n_No stderr._");
-```
-
-For a JSON-output CLI action test, add:
-
-```ts
-expect(result.structuredContent).toMatchObject({ json: { ok: true } });
-expect(result.content[0].text).toContain("## Parsed JSON");
-expect(result.content[0].text).toContain('"ok": true');
-```
-
-- [ ] **Step 3: Run backend tests to verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/graphql.test.ts test/cli-tools.test.ts
-```
-
-Expected: FAIL because GraphQL and CLI direct managers still return compact content.
-
-- [ ] **Step 4: Update GraphQL manager**
-
-In `packages/core/src/graphql.ts`, replace the result-content import with:
-
-```ts
-import { markdownStructuredContent } from "./result-content";
-```
-
-Replace the `content` field in `callTool()` with:
-
-```ts
-        content: markdownStructuredContent(result, {
-          title: `${endpoint.name} call_tool ${toolName}`,
-          backend: "graphql",
-          operation: "call_tool",
-          tool: toolName,
-        }),
-```
-
-- [ ] **Step 5: Update CLI tools manager**
-
-In `packages/core/src/cli-tools.ts`, replace the result-content import with:
-
-```ts
-import { markdownStructuredContent } from "./result-content";
-```
-
-Replace the `content` field in `callTool()` with:
-
-```ts
-        content: markdownStructuredContent(structured, {
-          title: `${config.name} call_tool ${toolName}`,
-          backend: "cli",
-          operation: "call_tool",
-          tool: toolName,
-        }),
-```
-
-- [ ] **Step 6: Run GraphQL/CLI tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/graphql.test.ts test/cli-tools.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit GraphQL/CLI formatting**
-
-```bash
-git add packages/core/src/graphql.ts packages/core/src/cli-tools.ts packages/core/test/graphql.test.ts packages/core/test/cli-tools.test.ts
-git commit -m "feat(core): render graphql and cli results as markdown content"
-```
-
----
-
-### Task 6: Render Safe Error Results as Complete Markdown
-
-**Files:**
-
-- Modify: `packages/core/src/errors.ts`
-- Modify: `packages/core/test/tools.test.ts`
-
-- [ ] **Step 1: Add failing error-result assertion**
-
-In the core test file that already asserts generated error results, update the expectation to require Markdown details:
-
-```ts
-expect(result.isError).toBe(true);
-expect(result.structuredContent).toMatchObject({
-  error: {
-    code: "REQUEST_INVALID",
-    message: expect.any(String),
-  },
-});
-expect(result.content[0].text).toContain("# Error");
-expect(result.content[0].text).toContain("## REQUEST_INVALID");
-expect(result.content[0].text).toContain("## Details");
-expect(result.content[0].text).toContain('"code": "REQUEST_INVALID"');
-```
-
-- [ ] **Step 2: Run error-related tests to verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: FAIL because `errorResult()` still returns one-line text.
-
-- [ ] **Step 3: Update `errorResult()`**
-
-In `packages/core/src/errors.ts`, import the Markdown helper:
-
-```ts
-import { markdownStructuredContent } from "./result-content";
-```
-
-Replace the `errorResult()` return object with:
-
-```ts
-export function errorResult(error: unknown, fallback?: CapletsErrorCode) {
-  const safe = toSafeError(error, fallback);
-  const structuredContent = { error: safe };
-  return {
-    isError: true,
-    content: markdownStructuredContent(structuredContent, {
-      title: "Error",
-      isError: true,
-    }),
-    structuredContent,
-  };
-}
-```
-
-- [ ] **Step 4: Run error-related tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit error formatting**
-
-```bash
-git add packages/core/src/errors.ts packages/core/test/tools.test.ts
-git commit -m "feat(core): render error results as markdown content"
-```
-
----
-
-### Task 7: Preserve Downstream MCP Content and Append Structured Content
-
-**Files:**
-
-- Modify: `packages/core/test/downstream.test.ts`
-- Modify: `packages/core/test/tools.test.ts`
-- Modify: `packages/core/src/tools.ts`
-
-- [ ] **Step 1: Add failing downstream MCP wrapper test**
-
-In `packages/core/test/tools.test.ts`, add a test using the existing mock downstream manager pattern:
-
-```ts
-it("preserves MCP downstream text and appends downstream structuredContent", async () => {
-  const downstream = mockDownstreamCallResult({
-    content: [{ type: "text", text: "Downstream authored response" }],
-    structuredContent: { answer: { value: 42 } },
-  });
-
-  const result = await handleServerTool(
-    mcpServer,
-    { operation: "call_tool", tool: "answer", arguments: {} },
-    registry,
-    downstream,
-  );
-
-  expect(result.structuredContent).toEqual({ answer: { value: 42 } });
-  expect(result.content[0].text).toContain("Downstream authored response");
-  expect(result.content[0].text).toContain("## Structured Content");
-  expect(result.content[0].text).toContain('"value": 42');
-});
-```
-
-Use the actual mock helper names already present in `packages/core/test/tools.test.ts`; keep the expected behavior exactly as shown.
-
-- [ ] **Step 2: Run MCP wrapper tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/tools.test.ts test/downstream.test.ts
-```
-
-Expected: PASS if Task 3 already routes `annotateCallToolResult()` through `markdownCallToolResultContent()`; otherwise FAIL and fix `annotateCallToolResult()` to use the Task 3 code exactly.
-
-- [ ] **Step 3: Commit downstream MCP behavior**
-
-```bash
-git add packages/core/src/tools.ts packages/core/test/tools.test.ts packages/core/test/downstream.test.ts
-git commit -m "feat(core): expose downstream structured content in markdown"
-```
-
----
-
-### Task 8: Update Pi Native Integration to Use Core Markdown and Keep UI Preview Truncated
-
-**Files:**
-
-- Modify: `packages/pi/src/index.ts`
-- Modify: `packages/pi/test/pi.test.ts`
-
-- [ ] **Step 1: Add failing Pi agent-content and renderer tests**
-
-Update the previously added structured body visibility test in `packages/pi/test/pi.test.ts` to assert the agent-visible payload is full Markdown, not raw JSON-only content:
-
-```ts
-expect(result?.content[0]?.text).toContain("# OSV Vulnerabilities call_tool query_purl");
-expect(result?.content[0]?.text).toContain("## Body");
-expect(result?.content[0]?.text).toContain('"vulns": []');
-```
-
-Add a long-field value to the mocked structured body so the collapsed renderer can prove truncation without losing expanded content:
-
-```ts
-const longAdvisory = "A".repeat(400);
-service.execute.mockResolvedValueOnce({
-  content: [{ type: "text", text: "status 200; OK; body" }],
-  structuredContent: {
-    status: 200,
-    statusText: "OK",
-    body: {
-      vulns: [
-        {
-          id: "GHSA-test",
-          summary: longAdvisory,
-        },
-      ],
-    },
-  },
-  _meta: {
-    caplets: {
-      name: "OSV Vulnerabilities",
-      operation: "call_tool",
-      tool: "query_purl",
-      status: "ok",
-    },
-  },
-});
-```
-
-Assert collapsed rendering is short and does not dump the full Markdown body:
-
-```ts
-const collapsed = renderText(
-  registered[0]?.renderResult(result!, { expanded: false, isPartial: false }, plainTheme),
-);
-expect(collapsed).toContain("✓ OSV Vulnerabilities call_tool query_purl complete");
-expect(collapsed.length).toBeLessThan(260);
-expect(collapsed).not.toContain(longAdvisory);
-expect(collapsed).toContain("ctrl+o to expand");
-```
-
-Assert expanded rendering, opened by `ctrl+o`, displays the full Markdown content:
-
-```ts
-const expanded = renderText(
-  registered[0]?.renderResult(result!, { expanded: true, isPartial: false }, plainTheme),
-);
-expect(expanded).toContain("✓ OSV Vulnerabilities call_tool query_purl complete");
-expect(expanded).toContain("## Body");
-expect(expanded).toContain('"id": "GHSA-test"');
-expect(expanded).toContain(longAdvisory);
-expect(expanded).toContain("ctrl+o to collapse");
-```
-
-- [ ] **Step 2: Run Pi tests to verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-```
-
-Expected: FAIL because Pi currently serializes structured content as raw pretty JSON or uses local logic rather than the core Markdown renderer. If the collapsed-renderer assertions already pass, keep them as regression coverage while fixing the agent-visible Markdown branch.
-
-- [ ] **Step 3: Import core Markdown helpers in Pi**
-
-In `packages/pi/src/index.ts`, add this import:
-
-```ts
-import {
-  hasRenderableStructuredContent,
-  markdownStructuredContent,
-  type ResultMarkdownContext,
-} from "@caplets/core";
-```
-
-- [ ] **Step 4: Add Pi context builder**
-
-Add this helper near `capletsMetadata()`:
-
-```ts
-function piMarkdownContext(details: unknown): ResultMarkdownContext {
-  const metadata = capletsMetadata(details);
-  if (!metadata) {
-    return { title: "Result" };
-  }
-  return {
-    title: [metadata.name, metadata.operation, metadata.tool].filter(Boolean).join(" "),
-    operation: metadata.operation,
-    tool: metadata.tool,
-  };
-}
-```
-
-- [ ] **Step 5: Update `agentContent()` without changing collapsed/expanded UI semantics**
-
-Replace the structured-content branch in `agentContent()` with:
-
-```ts
-const structured = objectProperty(result, "structuredContent");
-if (hasRenderableStructuredContent(structured)) {
-  return markdownStructuredContent(structured, piMarkdownContext({ result }));
-}
-```
-
-Keep the existing fallback that returns downstream text content or JSON stringification for non-structured results.
-
-Do not make `renderResult()` print full content in the collapsed state. Its current split must remain:
-
-```ts
-if (expanded) {
-  const output = resultFullContent(result.content);
-  // render full output
-}
-
-const preview = resultPreview(result.details, result.content);
-// render short preview only
-```
-
-If the Markdown result makes collapsed previews too noisy, adjust only `resultPreview()`/`compactText()` limits or summary logic so collapsed output stays short while `resultFullContent()` remains complete.
-
-- [ ] **Step 6: Run Pi tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit Pi integration**
-
-```bash
-git add packages/pi/src/index.ts packages/pi/test/pi.test.ts
-git commit -m "feat(pi): show structured caplet results as expandable markdown"
-```
-
----
-
-### Task 9: Update OpenCode Native Integration to Use Core Markdown
-
-**Files:**
-
-- Modify: `packages/opencode/src/hooks.ts`
-- Modify: `packages/opencode/test/opencode.test.ts`
-
-- [ ] **Step 1: Add failing OpenCode Markdown test**
-
-Update the existing OpenCode structured body visibility test in `packages/opencode/test/opencode.test.ts`:
-
-```ts
-expect(result).toContain("# OSV Vulnerabilities call_tool query_purl");
-expect(result).toContain("## Body");
-expect(result).toContain('"vulns": []');
-```
-
-- [ ] **Step 2: Run OpenCode tests to verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: FAIL because OpenCode currently returns raw JSON for structured content or compact text.
-
-- [ ] **Step 3: Import core Markdown helpers**
-
-In `packages/opencode/src/hooks.ts`, keep native service imports on the native subpath and import Markdown helpers from the core root export:
-
-```ts
-import { nativeCapletsSystemGuidance, type NativeCapletsService } from "@caplets/core/native";
-import { hasRenderableStructuredContent, markdownStructuredContent } from "@caplets/core";
-```
-
-- [ ] **Step 4: Update `compactOpenCodeResult()`**
-
-Replace the structured-content branch with:
-
-```ts
-const structuredContent = objectProperty(result, "structuredContent");
-if (hasRenderableStructuredContent(structuredContent)) {
-  return markdownStructuredContent(structuredContent, { title: "Result" })[0]?.text ?? "# Result";
-}
-```
-
-If the result includes `_meta.caplets`, build a title before calling `markdownStructuredContent()`:
-
-```ts
-const metadata = objectProperty(objectProperty(result, "_meta"), "caplets");
-const title = [
-  stringProperty(metadata, "name"),
-  stringProperty(metadata, "operation"),
-  stringProperty(metadata, "tool"),
-]
-  .filter(Boolean)
-  .join(" ");
-```
-
-Then pass:
-
-```ts
-{ title: title || "Result", operation: stringProperty(metadata, "operation"), tool: stringProperty(metadata, "tool") }
-```
-
-- [ ] **Step 5: Run OpenCode tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit OpenCode integration**
-
-```bash
-git add packages/opencode/src/hooks.ts packages/opencode/test/opencode.test.ts
-git commit -m "feat(opencode): show structured caplet results as markdown"
-```
-
----
-
-### Task 10: Add Changeset and Run Full Verification
-
-**Files:**
-
-- Create: `.changeset/lossless-markdown-results.md`
-- Modify: `docs/benchmarks/coding-agent.md` only if benchmark verification reports it stale
-
-- [ ] **Step 1: Create a changeset**
-
-Run:
-
-```bash
-pnpm changeset
-```
-
-Select packages:
-
-```text
-@caplets/core: patch
-@caplets/pi: patch
-@caplets/opencode: patch
-```
-
-Use this summary:
-
-```md
-Render structured Caplets results as lossless Markdown content while preserving canonical structuredContent.
-```
-
-If interactive Changesets is unavailable, create a changeset file manually with a unique filename:
-
-```md
----
-"@caplets/core": patch
-"@caplets/pi": patch
-"@caplets/opencode": patch
----
-
-Render structured Caplets results as lossless Markdown content while preserving canonical structuredContent.
-```
-
-- [ ] **Step 2: Run focused package tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/result-content.test.ts test/http-actions.test.ts test/openapi.test.ts test/graphql.test.ts test/cli-tools.test.ts test/tools.test.ts test/downstream.test.ts test/field-selection.test.ts
-pnpm --filter @caplets/pi test -- test/pi.test.ts
-pnpm --filter @caplets/opencode test -- test/opencode.test.ts
-```
-
-Expected: all selected tests PASS.
-
-- [ ] **Step 3: Run formatting and typechecks**
-
-Run:
-
-```bash
-pnpm format:check
-pnpm --filter @caplets/core typecheck
-pnpm --filter @caplets/pi typecheck
-pnpm --filter @caplets/opencode typecheck
-```
-
-Expected: all commands exit 0.
-
-- [ ] **Step 4: Run full verification gate**
-
-Run:
-
-```bash
-pnpm verify
-```
-
-Expected: `format:check`, `lint`, `typecheck`, `schema:check`, `test`, `benchmark:check`, and `build` all pass.
-
-- [ ] **Step 5: Commit final verification changes**
-
-```bash
-git add .changeset packages/core packages/pi packages/opencode docs/benchmarks/coding-agent.md
-git commit -m "feat: render caplet result content as markdown"
-```
-
-Only include `docs/benchmarks/coding-agent.md` if `pnpm verify` or `pnpm benchmark` updates it.
-
----
-
-## Self-Review Checklist
-
-- Every Caplets-generated `structuredContent` path has a complete Markdown `content` path.
-- No renderer-level truncation exists.
-- HTTP/OpenAPI body data appears fully in `content`.
-- GraphQL data/errors and full body appear fully in `content`.
-- CLI stdout/stderr and parsed JSON appear fully in `content`.
-- Discovery/list operations include readable lists plus full JSON result and Caplets metadata.
-- Error content includes the full safe error object.
-- Downstream MCP content is preserved, and downstream structured content is appended when present.
-- Pi and OpenCode use shared core Markdown rendering.
-- All changed behavior is covered by failing-first tests.
-- Full verification passes before claiming implementation complete.
diff --git a/docs/plans/2026-05-28-skillify-landing-page.md b/docs/plans/2026-05-28-skillify-landing-page.md
deleted file mode 100644
index 311bd3ed..00000000
--- a/docs/plans/2026-05-28-skillify-landing-page.md
+++ /dev/null
@@ -1,1188 +0,0 @@
-# Skillify Landing Page Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use `subagent-driven-development` (recommended) or `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Rework `apps/landing` so the Caplets landing page leads with trust, defines the coined product verb “skillify,” proves progressive disclosure through a realistic GitHub trace, and removes visual choreography that conflicts with the Caplets brand.
-
-**Architecture:** Keep the landing app as a focused Astro page with one stylesheet. Refactor content constants in `apps/landing/src/pages/index.astro`, rebuild the hero around an inspectable trace, add trust proof and copy affordances, then simplify `apps/landing/src/styles/global.css` by deleting major motion systems instead of hiding them. Preserve semantic HTML, ARIA tab behavior, keyboard support, reduced-motion behavior, and responsive layout.
-
-**Tech Stack:** Astro 6, TypeScript in Astro inline scripts, Tailwind CSS import, plain CSS, pnpm 11.
-
----
-
-## Decision Record
-
-These decisions came from the critique and grill-me session:
-
-1. Optimize first for **trust in the architecture**, then conceptual understanding, then install conversion.
-2. Replace the expressive map hero with a **proof-first product diagram**.
-3. Use a **realistic trace**, not a purely conceptual diagram.
-4. Use **GitHub** as the hero trace capability because it has higher trust stakes than docs lookup.
-5. Make **capability card** the dominant product concept. Keep “map” only as a supporting metaphor.
-6. Coin and define **skillify** as durable product language.
-7. Put “Skillify your backends” in the hero subhead and demonstrate it immediately.
-8. Use a tight definition in the hero, then a three-part proof framework below.
-9. Delete major animation systems, including pointer tilt, scroll-driven route resolution, route drift, heavy glow, and orchestration.
-10. Create this written plan before code changes.
-
-## File Structure
-
-### Modify: `apps/landing/src/pages/index.astro`
-
-Responsibilities after this plan:
-
-- Own content constants for capability trace, trust mechanics, proof framework, integration tabs, and install commands.
-- Render a trust-first hero with “skillify” defined in public-facing copy.
-- Render a realistic GitHub progressive-disclosure trace.
-- Render a three-part “What skillify means” proof framework.
-- Render trust mechanics with concrete status, source, auth redaction, timeout, error, and lossless-result examples.
-- Render copyable install/config snippets with progressive enhancement.
-- Keep no-JS integration content accessible.
-- Keep accessible tabs when JavaScript runs.
-
-### Modify: `apps/landing/src/styles/global.css`
-
-Responsibilities after this plan:
-
-- Preserve the Caplets warm-light design system.
-- Style the new hero trace, skillify framework, trust proof, and copy buttons.
-- Remove major choreography and decorative cartography styling.
-- Keep only restrained hover, focus, and content-reveal transitions.
-- Maintain responsive layouts at desktop, tablet, and phone widths.
-- Preserve reduced-motion behavior.
-
-### Optional Modify: `apps/landing/README.md`
-
-Only modify if implementation adds a new local QA note that is useful to future maintainers. This plan does not require it.
-
-## Canonical Copy and Content Decisions
-
-Use these exact product messages unless implementation reveals a factual problem:
-
-- Hero kicker: `Capability cards for coding agents`
-- Hero headline: `Skillify your backends.`
-- Hero lede: `Caplets turns MCP servers, APIs, and commands into focused agent capabilities: one card first, searchable tools next, inspectable schemas before calls, and preserved results after.`
-- Definition line: `To skillify a backend is to wrap it as a capability an agent can discover, inspect, call, and recover from one step at a time.`
-- Primary CTA: `Install Caplets`
-- Secondary CTA: `Inspect the repo`
-- Trust section heading: `Trust is visible before the call.`
-- Skillify framework heading: `What skillify means`
-
-Avoid em dashes in all new copy.
-
-## Task 1: Refactor Landing Content Constants
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-
-- [ ] **Step 1: Replace the current hero capability card constants with trace-oriented constants**
-
-In `apps/landing/src/pages/index.astro`, replace the existing `capabilityCards` constant with the following constants:
-
-```ts
-const heroTrace = {
-  capability: "github",
-  source: ".caplets/config.json",
-  status: "ready",
-  auth: "token present, redacted",
-  steps: [
-    {
-      label: "get_caplet",
-      detail: "Expose one card before any downstream tool list enters context.",
-      result: "search_tools · get_tool · call_tool",
-    },
-    {
-      label: 'search_tools("pull request")',
-      detail: "Find matching operations inside the selected capability only.",
-      result: "create_pull_request · list_pull_requests · request_review",
-    },
-    {
-      label: 'get_tool("create_pull_request")',
-      detail: "Inspect the preserved schema before an agent can invoke the operation.",
-      result: "title · body · base · head · reviewers?",
-    },
-    {
-      label: "call_tool(arguments)",
-      detail: "Forward the call and keep downstream content, structured data, and errors intact.",
-      result: "structuredContent + content",
-    },
-  ],
-};
-
-const skillifyFramework = [
-  {
-    title: "Discoverable as one capability",
-    copy: "A backend enters the agent context as a focused card with source, status, and next actions, not a flat wall of operations.",
-  },
-  {
-    title: "Inspectable before invocation",
-    copy: "Agents search inside the selected capability, then inspect exact tool schemas before any call is made.",
-  },
-  {
-    title: "Lossless after the call",
-    copy: "Caplets preserves structured content, resource links, images, and downstream error state instead of flattening results away.",
-  },
-];
-
-const trustMechanics = [
-  {
-    label: "Source",
-    value: ".caplets/config.json",
-    copy: "Users can see where the capability came from before trusting it.",
-  },
-  {
-    label: "Auth",
-    value: "GITHUB_TOKEN: redacted",
-    copy: "Secrets stay hidden while auth state remains inspectable.",
-  },
-  {
-    label: "Timeout",
-    value: "30s boundary",
-    copy: "Slow or stuck backends fail visibly instead of disappearing into agent context.",
-  },
-  {
-    label: "Error",
-    value: "safe message + raw detail scoped",
-    copy: "Recovery information stays useful without leaking sensitive configuration.",
-  },
-];
-```
-
-Delete any references to the removed `capabilityCards` constant during later tasks.
-
-- [ ] **Step 2: Normalize install command data**
-
-In the existing `agentSetups` array, ensure every generic global package install uses `npm install -g caplets` unless the specific client has a stronger documented install path. Replace the `installSteps` constant with:
-
-```ts
-const installSteps = [
-  "npm install -g caplets",
-  "caplets init",
-  "caplets add mcp docs --command npx --arg -y --arg @upstash/context7-mcp",
-  "caplets serve",
-];
-```
-
-- [ ] **Step 3: Run Astro typecheck**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-```
-
-Expected: PASS. If references to removed constants fail, continue to Task 2 and remove those references while rebuilding the hero.
-
-## Task 2: Rebuild the Hero Around Skillify and GitHub Trace
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-- Modify: `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Replace hero copy and visual markup**
-
-In `apps/landing/src/pages/index.astro`, replace the current `<section class="hero" aria-labelledby="hero-title">...</section>` with this structure:
-
-```astro
-<section class="hero" aria-labelledby="hero-title">
-  <div class="hero-copy">
-    <p class="kicker">Capability cards for coding agents</p>
-    <h1 id="hero-title">Skillify your backends.</h1>
-    <p class="hero-lede">
-      Caplets turns MCP servers, APIs, and commands into focused agent capabilities: one card
-      first, searchable tools next, inspectable schemas before calls, and preserved results after.
-    </p>
-    <p class="hero-definition">
-      To skillify a backend is to wrap it as a capability an agent can discover, inspect, call,
-      and recover from one step at a time.
-    </p>
-    <div class="hero-actions" aria-label="Primary actions">
-      <a class="button primary" href="#install">Install Caplets</a>
-      <a class="button secondary" href="https://github.com/spiritledsoftware/caplets">Inspect the repo</a>
-    </div>
-    <dl class="hero-facts" aria-label="Supported capability sources">
-      <div>
-        <dt>Backends</dt>
-        <dd>{backends.join(" · ")}</dd>
-      </div>
-      <div>
-        <dt>Clients</dt>
-        <dd>{integrations.join(" · ")}</dd>
-      </div>
-    </dl>
-  </div>
-
-  <aside class="trace-stage" id="trace" aria-label="GitHub capability trace example">
-    <div class="trace-header">
-      <span class="trace-status" aria-label={`Capability status: ${heroTrace.status}`}>{heroTrace.status}</span>
-      <span>{heroTrace.capability}</span>
-    </div>
-    <dl class="trace-metadata" aria-label="Capability metadata">
-      <div>
-        <dt>source</dt>
-        <dd>{heroTrace.source}</dd>
-      </div>
-      <div>
-        <dt>auth</dt>
-        <dd>{heroTrace.auth}</dd>
-      </div>
-    </dl>
-    <ol class="trace-steps" aria-label="Progressive disclosure trace">
-      {heroTrace.steps.map((step) => (
-        <li>
-          <div>
-            <span class="trace-label">{step.label}</span>
-            <p>{step.detail}</p>
-          </div>
-          <code>{step.result}</code>
-        </li>
-      ))}
-    </ol>
-  </aside>
-</section>
-```
-
-- [ ] **Step 2: Remove old hero visual CSS selectors**
-
-In `apps/landing/src/styles/global.css`, delete rules that only support the old map hero:
-
-```css
-.map-stage
-.map-stage::before
-.map-stage::after
-.map-toolbar
-.status-dot
-.route-field
-.route
-.route-backbone
-.map-stage.is-route-active .route-backbone
-.route-two
-.route-three
-.route-draw
-.route-draw-two
-.route-draw-three
-.capability-grid
-.capability-card
-.capability-card:hover
-.card-1
-.card-2
-.card-3
-.cartography-compass
-.cartography-compass span
-.cartography-compass span:nth-child(1)
-.cartography-compass span:nth-child(2)
-.cartography-compass span:nth-child(3)
-.card-topline
-.card-index
-.capability-card h2
-.capability-card p
-.capability-card ul
-.capability-card li
-.inspect-panel
-.inspect-panel code
-.inspect-panel p
-```
-
-Also delete keyframes used only by the old hero:
-
-```css
-@keyframes map-stage-enter
-@keyframes route-drift
-@keyframes card-enter;
-```
-
-- [ ] **Step 3: Add new trace hero CSS**
-
-Add this CSS near the existing hero styles:
-
-```css
-.hero-definition {
-  max-width: 62ch;
-  margin: -12px 0 28px;
-  color: var(--charred-ink);
-  font-size: clamp(0.98rem, 1.2vw, 1.1rem);
-  line-height: 1.55;
-}
-
-.trace-stage {
-  min-width: 0;
-  border: 1px solid var(--ash);
-  border-radius: 28px;
-  background:
-    linear-gradient(180deg, oklch(98% 0.014 82 / 0.98), oklch(96% 0.018 82 / 0.98)), var(--paper);
-  overflow: hidden;
-  box-shadow: 0 18px 54px oklch(24% 0.018 100 / 0.08);
-}
-
-.trace-header {
-  min-height: 58px;
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 16px;
-  padding: 0 18px;
-  border-bottom: 1px solid var(--ash);
-  color: var(--charred-ink);
-  font-family: var(--font-mono);
-  font-size: 0.82rem;
-  font-weight: 760;
-}
-
-.trace-status {
-  display: inline-flex;
-  align-items: center;
-  gap: 8px;
-  border: 1px solid color-mix(in oklch, var(--success), var(--ash) 45%);
-  border-radius: 999px;
-  background: oklch(95% 0.03 145);
-  color: oklch(34% 0.07 145);
-  padding: 5px 9px;
-  text-transform: uppercase;
-  letter-spacing: 0.055em;
-}
-
-.trace-status::before {
-  content: "";
-  width: 7px;
-  height: 7px;
-  border-radius: 999px;
-  background: currentColor;
-}
-
-.trace-metadata {
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  gap: 1px;
-  margin: 0;
-  background: var(--ash);
-}
-
-.trace-metadata div {
-  min-width: 0;
-  padding: 14px 16px;
-  background: var(--linen);
-}
-
-.trace-metadata dt,
-.trace-label {
-  font-family: var(--font-mono);
-  font-size: 0.72rem;
-  font-weight: 760;
-  letter-spacing: 0.055em;
-}
-
-.trace-metadata dt {
-  margin-bottom: 5px;
-  color: var(--ember-deep);
-  text-transform: uppercase;
-}
-
-.trace-metadata dd {
-  font-family: var(--font-mono);
-  color: var(--charred-ink);
-  overflow-wrap: anywhere;
-}
-
-.trace-steps {
-  display: grid;
-  gap: 0;
-  margin: 0;
-  padding: 0;
-  list-style: none;
-  counter-reset: trace;
-}
-
-.trace-steps li {
-  counter-increment: trace;
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) minmax(180px, 0.72fr);
-  gap: 18px;
-  padding: 18px;
-  border-top: 1px solid var(--ash);
-}
-
-.trace-steps li::before {
-  content: counter(trace, decimal-leading-zero);
-  grid-row: 1;
-  align-self: start;
-  width: fit-content;
-  border: 1px solid var(--ash);
-  border-radius: 999px;
-  background: var(--parchment);
-  color: var(--ember-deep);
-  padding: 4px 7px;
-  font-family: var(--font-mono);
-  font-size: 0.68rem;
-  font-weight: 760;
-}
-
-.trace-steps li > div {
-  min-width: 0;
-  display: grid;
-  gap: 7px;
-}
-
-.trace-label {
-  color: var(--charred-ink);
-  overflow-wrap: anywhere;
-}
-
-.trace-steps p {
-  margin: 0;
-  color: var(--olive);
-  font-size: 0.92rem;
-  line-height: 1.45;
-}
-
-.trace-steps code {
-  min-width: 0;
-  align-self: start;
-  border: 1px solid var(--ash);
-  border-radius: 14px;
-  background: var(--linen);
-  color: var(--charred-ink);
-  padding: 12px;
-  font-family: var(--font-mono);
-  font-size: 0.78rem;
-  line-height: 1.45;
-  overflow-wrap: anywhere;
-}
-```
-
-- [ ] **Step 4: Update hero grid sizing**
-
-Replace the current `.hero` grid columns:
-
-```css
-grid-template-columns: minmax(0, 0.92fr) minmax(420px, 1.08fr);
-```
-
-with:
-
-```css
-grid-template-columns: minmax(0, 0.86fr) minmax(460px, 1.14fr);
-```
-
-- [ ] **Step 5: Run focused checks**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-```
-
-Expected: both PASS.
-
-## Task 3: Add the Skillify Proof Framework
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-- Modify: `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Replace the current proof section with skillify framework copy**
-
-In `apps/landing/src/pages/index.astro`, replace the existing `<section class="proof" id="proof" aria-labelledby="proof-title">...</section>` with:
-
-```astro
-<section class="proof" id="proof" aria-labelledby="proof-title">
-  <div class="section-heading narrow">
-    <p class="kicker">What skillify means</p>
-    <h2 id="proof-title">A backend becomes safe for agents when it reveals itself in stages.</h2>
-  </div>
-  <div class="proof-list">
-    {skillifyFramework.map((point, index) => (
-      <article class="proof-item">
-        <p class="proof-eyebrow">0{index + 1}</p>
-        <h3>{point.title}</h3>
-        <p>{point.copy}</p>
-      </article>
-    ))}
-  </div>
-</section>
-```
-
-- [ ] **Step 2: Ensure proof card language avoids generic card-grid slop**
-
-Keep the three proof items because they are a compact framework, but avoid adding icons, decorative gradients, or identical marketing feature cards. The cards should remain text-led and precise.
-
-- [ ] **Step 3: Run focused checks**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-```
-
-Expected: both PASS.
-
-## Task 4: Add Concrete Trust Mechanics
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-- Modify: `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Insert a trust mechanics section after the proof section**
-
-In `apps/landing/src/pages/index.astro`, insert this section immediately after the proof section:
-
-```astro
-<section class="trust" aria-labelledby="trust-title">
-  <div class="section-heading">
-    <p class="kicker">Trust before invocation</p>
-    <h2 id="trust-title">Trust is visible before the call.</h2>
-  </div>
-  <div class="trust-grid">
-    {trustMechanics.map((item) => (
-      <article class="trust-item">
-        <span class="agent-setup-label">{item.label}</span>
-        <code>{item.value}</code>
-        <p>{item.copy}</p>
-      </article>
-    ))}
-  </div>
-  <div class="trust-error" role="note" aria-label="Safe error example">
-    <span class="agent-setup-label">Safe recovery example</span>
-    <p>
-      If a backend fails, Caplets keeps the error scoped to the capability, preserves useful
-      recovery detail, and redacts sensitive configuration before it reaches the agent.
-    </p>
-  </div>
-</section>
-```
-
-- [ ] **Step 2: Add trust section CSS**
-
-Add this CSS near the proof and integrations styles:
-
-```css
-.trust {
-  width: var(--content);
-  margin-inline: auto;
-}
-
-.trust-grid {
-  display: grid;
-  grid-template-columns: repeat(4, minmax(0, 1fr));
-  gap: 12px;
-}
-
-.trust-item,
-.trust-error {
-  min-width: 0;
-  border: 1px solid var(--ash);
-  border-radius: 22px;
-  background: var(--paper);
-  padding: 18px;
-}
-
-.trust-item code {
-  display: block;
-  margin: 10px 0 12px;
-  color: var(--charred-ink);
-  font-family: var(--font-mono);
-  font-size: 0.82rem;
-  line-height: 1.45;
-  overflow-wrap: anywhere;
-}
-
-.trust-item p,
-.trust-error p {
-  margin: 0;
-  color: var(--olive);
-}
-
-.trust-error {
-  margin-top: 12px;
-  background: var(--linen);
-}
-```
-
-- [ ] **Step 3: Update `main` spacing if needed**
-
-If the new trust section feels too disconnected, reduce the global section gap from:
-
-```css
-gap: clamp(74px, 10vw, 142px);
-```
-
-to:
-
-```css
-gap: clamp(64px, 8vw, 118px);
-```
-
-Use the smaller gap only if visual review shows excessive whitespace between proof and trust.
-
-- [ ] **Step 4: Run focused checks**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-```
-
-Expected: both PASS.
-
-## Task 5: Add Copy Buttons and Safer Snippet Semantics
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-- Modify: `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Add copy buttons to integration snippets**
-
-In the integration panel markup, replace each current snippet block:
-
-```astro
-<div>
-  <span class="agent-setup-label">Install</span>
-  <pre><code>{agent.installCommand}</code></pre>
-</div>
-<div>
-  <span class="agent-setup-label">Configuration</span>
-  <pre><code>{agent.configSnippet}</code></pre>
-</div>
-```
-
-with:
-
-```astro
-<div class="snippet-block">
-  <div class="snippet-heading">
-    <span class="agent-setup-label">Install</span>
-    <button class="copy-button" type="button" data-copy-value={agent.installCommand}>Copy</button>
-  </div>
-  <pre><code>{agent.installCommand}</code></pre>
-</div>
-<div class="snippet-block">
-  <div class="snippet-heading">
-    <span class="agent-setup-label">Configuration</span>
-    <button class="copy-button" type="button" data-copy-value={agent.configSnippet}>Copy</button>
-  </div>
-  <pre><code>{agent.configSnippet}</code></pre>
-</div>
-```
-
-- [ ] **Step 2: Add copy buttons to terminal install steps**
-
-Replace terminal list item markup:
-
-```astro
-<li><code>{step}</code></li>
-```
-
-with:
-
-```astro
-<li>
-  <code>{step}</code>
-  <button class="copy-button terminal-copy" type="button" data-copy-value={step}>Copy</button>
-</li>
-```
-
-- [ ] **Step 3: Add copy button script**
-
-Inside the existing `<script>` block, after tab setup constants, add:
-
-```ts
-const copyButtons = Array.from(document.querySelectorAll<HTMLButtonElement>("[data-copy-value]"));
-
-async function copyValue(button: HTMLButtonElement) {
-  const value = button.dataset.copyValue;
-  if (!value) return;
-
-  try {
-    await navigator.clipboard.writeText(value);
-    button.textContent = "Copied";
-    button.setAttribute("data-copied", "true");
-    window.setTimeout(() => {
-      button.textContent = "Copy";
-      button.removeAttribute("data-copied");
-    }, 1600);
-  } catch {
-    button.textContent = "Select text";
-    window.setTimeout(() => {
-      button.textContent = "Copy";
-    }, 2200);
-  }
-}
-
-for (const button of copyButtons) {
-  button.addEventListener("click", () => void copyValue(button));
-}
-```
-
-- [ ] **Step 4: Add copy button CSS**
-
-Add:
-
-```css
-.snippet-block {
-  min-width: 0;
-}
-
-.snippet-heading {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 12px;
-  margin-bottom: 8px;
-}
-
-.snippet-heading .agent-setup-label {
-  margin-bottom: 0;
-}
-
-.copy-button {
-  min-height: 32px;
-  border: 1px solid currentColor;
-  border-radius: 999px;
-  background: transparent;
-  color: inherit;
-  padding: 0 10px;
-  font: inherit;
-  font-family: var(--font-mono);
-  font-size: 0.68rem;
-  font-weight: 780;
-  cursor: pointer;
-  transition:
-    background-color 160ms var(--ease-out),
-    color 160ms var(--ease-out),
-    transform 160ms var(--ease-out);
-}
-
-.copy-button:hover,
-.copy-button[data-copied="true"] {
-  background: var(--parchment);
-  color: var(--night-ink);
-  transform: translateY(-1px);
-}
-
-.terminal li {
-  align-items: center;
-  grid-template-columns: 46px minmax(0, 1fr) auto;
-}
-
-.terminal-copy {
-  color: var(--night-muted);
-}
-```
-
-- [ ] **Step 5: Run focused checks**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-```
-
-Expected: both PASS.
-
-## Task 6: Make Integration Tabs No-JS Accessible
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-- Modify: `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Stop hiding integration panels in initial HTML**
-
-In the integration panel markup, remove the `hidden={index !== 0}` attribute from each `.agent-setup-panel`.
-
-- [ ] **Step 2: Add an enhancement class before hiding panels with JavaScript**
-
-At the start of the existing `<script>` block, add:
-
-```ts
-document.documentElement.classList.add("js-enabled");
-```
-
-Keep the existing call to `selectAgentTab(agentTabs[0].dataset.agentTab ?? "")`; it will hide inactive panels after JavaScript loads.
-
-- [ ] **Step 3: Scope hidden tab styling to enhanced mode**
-
-Keep the existing CSS rule:
-
-```css
-.agent-setup-panel[hidden] {
-  display: none;
-}
-```
-
-No extra rule is needed for no-JS because panels will no longer ship with `hidden`. Confirm no-JS displays all panels stacked in source order.
-
-- [ ] **Step 4: Run focused checks**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-```
-
-Expected: both PASS.
-
-## Task 7: Delete Major Motion Systems and Calm the Visual Language
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-- Modify: `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Remove scroll and pointer animation script code**
-
-In the `<script>` block, delete variables and functions used only by the old hero motion system:
-
-```ts
-const hero = document.querySelector(".hero") as HTMLElement | null;
-const mapStage = document.querySelector(".map-stage") as HTMLElement | null;
-const canAnimate = !window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-
-function clamp(value: number, min: number, max: number) { ... }
-
-let heroProgressFrame = 0;
-let mapStageRect = mapStage?.getBoundingClientRect();
-let pointerFrame = 0;
-let pendingPointer: PointerEvent | undefined;
-
-function refreshMapStageRect() { ... }
-function updateHeroProgress() { ... }
-function scheduleHeroProgressUpdate() { ... }
-
-if (canAnimate && hero && mapStage) { ... }
-```
-
-Replace it with a smaller reveal setup:
-
-```ts
-const canAnimate = !window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-
-if (canAnimate) {
-  const revealTargets = document.querySelectorAll<HTMLElement>(
-    ".problem, .proof, .trust, .integrations, .install, .proof-item, .trust-item, .trust-error, .agent-setup-panel, .terminal li",
-  );
-
-  if (!("IntersectionObserver" in window)) {
-    revealTargets.forEach((target) => target.classList.add("is-visible"));
-  } else {
-    document.documentElement.classList.add("motion-ready");
-    const revealObserver = new IntersectionObserver(
-      (entries) => {
-        for (const entry of entries) {
-          if (entry.isIntersecting) {
-            entry.target.classList.add("is-visible");
-            revealObserver.unobserve(entry.target);
-          }
-        }
-      },
-      { rootMargin: "0px 0px -10%", threshold: 0.12 },
-    );
-
-    revealTargets.forEach((target, index) => {
-      target.style.setProperty("--reveal-index", String(index % 3));
-      revealObserver.observe(target);
-    });
-  }
-}
-```
-
-- [ ] **Step 2: Remove route progress CSS dependencies**
-
-Delete uses of these variables where they only exist for old route motion:
-
-```css
---scroll-progress
---route-resolve
---pointer-x
---pointer-y
-```
-
-Delete these old motion-coupled rules entirely:
-
-```css
-.problem {
-  margin-top: calc(var(--route-resolve) * -34px);
-  transition: margin-top 120ms linear;
-}
-
-.problem .section-heading { ... }
-
-.dense-list { ... }
-
-.ordered-flow { ... }
-```
-
-Then keep static versions:
-
-```css
-.problem .section-heading {
-  opacity: 1;
-}
-
-.dense-list,
-.ordered-flow {
-  transform: none;
-}
-```
-
-- [ ] **Step 3: Calm global decorative backgrounds**
-
-Keep the warm linen grid, but reduce glow intensity by changing:
-
-```css
---page-warmth: oklch(91% 0.05 42 / 0.8);
-```
-
-to:
-
-```css
---page-warmth: oklch(91% 0.035 42 / 0.52);
-```
-
-Remove `backdrop-filter: blur(16px);` from `.site-header` unless visual review shows it is needed for readability over the page background.
-
-- [ ] **Step 4: Run focused checks**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-```
-
-Expected: both PASS.
-
-## Task 8: Responsive Pass for Trace, Trust, and Snippets
-
-**Files:**
-
-- Modify: `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Replace old mobile map rules**
-
-In the `@media (max-width: 980px)` block, delete any `.map-stage` rules. Add:
-
-```css
-.trace-stage {
-  max-width: 100%;
-}
-
-.trust-grid {
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-}
-```
-
-- [ ] **Step 2: Add phone trace and trust rules**
-
-In the `@media (max-width: 720px)` block, delete old map-specific rules for `.map-stage`, `.capability-grid`, `.capability-card`, `.route-field`, and `.inspect-panel`. Add:
-
-```css
-.trace-stage {
-  border-radius: 22px;
-}
-
-.trace-metadata,
-.trace-steps li,
-.trust-grid {
-  grid-template-columns: 1fr;
-}
-
-.trace-steps li {
-  gap: 12px;
-}
-
-.trace-steps code {
-  width: 100%;
-}
-
-.trust-item,
-.trust-error {
-  border-radius: 18px;
-}
-
-.terminal li {
-  grid-template-columns: 38px minmax(0, 1fr);
-}
-
-.terminal-copy {
-  grid-column: 2;
-  justify-self: start;
-}
-```
-
-- [ ] **Step 3: Check touch target sizes**
-
-Confirm `.copy-button`, `.button`, `.integration-pill`, `.top-nav a`, and `.header-action` have practical hit targets. If `.copy-button` at 32px feels too small on mobile, add inside the phone media query:
-
-```css
-.copy-button {
-  min-height: 40px;
-  padding-inline: 12px;
-}
-```
-
-- [ ] **Step 4: Run focused checks**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-```
-
-Expected: both PASS.
-
-## Task 9: Add Docs and Config Links if They Exist
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-
-- [ ] **Step 1: Inspect available docs routes or README anchors**
-
-Run:
-
-```bash
-find docs apps/landing/src -maxdepth 3 -type f | sort | grep -E '(README|docs|config|usage|getting|index)'
-```
-
-Expected: identify whether there is a stable public docs URL or only GitHub README/docs files.
-
-- [ ] **Step 2: Add a docs link only if stable**
-
-If there is a stable docs route or GitHub docs path, add a third header or footer link with concrete text such as `Config docs`. Do not invent a broken public URL.
-
-Acceptable example if the GitHub docs path exists:
-
-```astro
-<a href="https://github.com/spiritledsoftware/caplets/tree/main/docs">Docs</a>
-```
-
-If no stable docs link exists, skip this step and record that the repo link remains the docs path for now.
-
-- [ ] **Step 3: Run focused checks**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-```
-
-Expected: both PASS.
-
-## Task 10: Final Verification and Critique Recheck
-
-**Files:**
-
-- Verify only unless fixes are needed.
-
-- [ ] **Step 1: Format check**
-
-Run:
-
-```bash
-pnpm format:check
-```
-
-Expected: PASS. If it fails only on modified files, run `pnpm format` and review the diff.
-
-- [ ] **Step 2: Lint**
-
-Run:
-
-```bash
-pnpm lint
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Typecheck**
-
-Run:
-
-```bash
-pnpm typecheck
-```
-
-Expected: PASS.
-
-- [ ] **Step 4: Landing build**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing build
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Detector recheck**
-
-Run:
-
-```bash
-npx impeccable --json apps/landing/src/pages/index.astro
-```
-
-Expected: `[]` or clearly explainable findings. Any true findings must be fixed before completion.
-
-- [ ] **Step 6: Manual source review checklist**
-
-Review the final diff and confirm:
-
-- Hero leads with “Skillify your backends.”
-- Hero defines skillify clearly.
-- Hero trace uses GitHub and shows source, status, auth redaction, progressive steps, schema inspection, and preserved result.
-- “Capability card” language is dominant over “map.”
-- Trust mechanics are concrete, not vague claims.
-- Install command inconsistency is resolved.
-- Commands and snippets have copy buttons.
-- Integration content is accessible without JavaScript.
-- Pointer tilt, scroll route resolution, route drift, heavy route glow, and old cartography are removed.
-- Reduced-motion support remains.
-- No new copy contains em dashes.
-
-- [ ] **Step 7: Full verification if time allows**
-
-Run:
-
-```bash
-pnpm verify
-```
-
-Expected: PASS. If this is too broad for the implementation session, record focused checks that passed and any unrelated failures separately.
-
-## Self-Review
-
-### Spec Coverage
-
-- Trust-first objective: covered by Tasks 2, 4, and 10.
-- Skillify coined term: covered by Tasks 2 and 3.
-- Capability cards dominant, map demoted: covered by Tasks 2 and 7.
-- Realistic GitHub trace: covered by Task 2.
-- Trust mechanics and safe recovery: covered by Task 4.
-- Copy buttons: covered by Task 5.
-- No-JS integration fallback: covered by Task 6.
-- Motion removal: covered by Task 7.
-- Responsive fixes: covered by Task 8.
-- Install consistency: covered by Task 1.
-- Docs/config links: covered by Task 9.
-- Verification: covered by Task 10.
-
-### Placeholder Scan
-
-This plan intentionally avoids placeholder instructions. Where conditional behavior exists, such as docs link discovery, it specifies exact commands and acceptable outcomes.
-
-### Type Consistency
-
-New constants are `heroTrace`, `skillifyFramework`, and `trustMechanics`. Markup references those exact names. Copy button data uses `data-copy-value`, and script queries `[data-copy-value]`.
diff --git a/docs/plans/2026-05-29-caplets-growth-campaign.md b/docs/plans/2026-05-29-caplets-growth-campaign.md
deleted file mode 100644
index 8a14c909..00000000
--- a/docs/plans/2026-05-29-caplets-growth-campaign.md
+++ /dev/null
@@ -1,233 +0,0 @@
-# Caplets Growth Campaign Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Build the public campaign assets that make Caplets easy to understand, try, and share before wider launch.
-
-**Architecture:** The campaign centers on one message: “Give your agents capabilities, not giant tool walls.” The first implementation slice strengthens activation proof by adding a visible “100+ tools vs 3 capabilities” proof asset and a guided “Try the aha moment” path to the landing page and README. Later slices prepare outreach copy and launch-channel assets without changing product runtime behavior.
-
-**Tech Stack:** Astro landing page in `apps/landing`, project README Markdown, existing Caplets benchmark report in `docs/benchmarks/coding-agent.md`, pnpm 11.0.9, Node >=22.
-
----
-
-## File Structure
-
-- Modify: `apps/landing/src/pages/index.astro`
-  - Owns landing content, proof copy, install/try steps, and inline data arrays for static rendering.
-- Modify: `apps/landing/src/styles/global.css`
-  - Owns visual treatment for the proof asset and aha section. Keep to existing OKLCH variables and Caplets design laws.
-- Modify: `README.md`
-  - Mirrors the shortest activation path and proof numbers for GitHub visitors.
-- Reference: `docs/benchmarks/coding-agent.md`
-  - Source for deterministic proof numbers: 106 direct tools, 3 Caplets capabilities, 97.2% fewer initially visible tools, 87.8% smaller initial payload.
-- Create later: `docs/product/caplets-launch-posts.md`
-  - Draft HN, Reddit, X/Twitter, and outreach copy.
-- Create later: `docs/product/caplets-outreach-list.md`
-  - Manual outreach targets, status, and feedback notes.
-
-## Task 1: Add activation proof and aha path
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-- Modify: `apps/landing/src/styles/global.css`
-- Modify: `README.md`
-
-- [ ] **Step 1: Add text assertions before editing content**
-
-Create a temporary shell check that fails until the campaign proof copy exists:
-
-```bash
-node - <<'NODE'
-const fs = require('fs');
-const landing = fs.readFileSync('apps/landing/src/pages/index.astro', 'utf8');
-const readme = fs.readFileSync('README.md', 'utf8');
-const checks = [
-  [landing, '106 flat tools'],
-  [landing, '3 capability cards'],
-  [landing, 'Try the aha moment'],
-  [readme, 'Try the aha moment'],
-  [readme, '106 flat tools became 3 top-level capabilities'],
-];
-const missing = checks.filter(([text, needle]) => !text.includes(needle)).map(([, needle]) => needle);
-if (missing.length) {
-  console.error('Missing campaign copy:', missing.join(', '));
-  process.exit(1);
-}
-NODE
-```
-
-Expected before implementation: exits `1` and lists missing strings.
-
-- [ ] **Step 2: Add proof data and aha copy to `index.astro`**
-
-Add static constants near existing hero data:
-
-```ts
-const proofStats = [
-  {
-    value: "106",
-    label: "flat tools",
-    detail: "Direct MCP aggregation exposes every downstream operation up front.",
-  },
-  {
-    value: "3",
-    label: "capability cards",
-    detail: "Caplets starts with one focused card per tool source.",
-  },
-  {
-    value: "87.8%",
-    label: "smaller initial payload",
-    detail: "The deterministic benchmark cuts serialized tool metadata before discovery.",
-  },
-];
-
-const ahaSteps = [
-  "npm install -g caplets",
-  "caplets init",
-  "caplets add mcp context7 --command npx --arg -y --arg @upstash/context7-mcp",
-  "caplets serve",
-];
-```
-
-Add a proof block in the existing problem section so the before/after comparison has hard numbers. Add an aha section before the install section with copy-paste commands and the expected agent discovery path: `context7 → get_caplet → search_tools → get_tool → call_tool`.
-
-- [ ] **Step 3: Style the proof asset and aha path**
-
-In `apps/landing/src/styles/global.css`, add responsive styles for:
-
-- `.proof-asset`
-- `.proof-stat`
-- `.aha`
-- `.aha-path`
-- `.aha-commands`
-
-Use existing tokens: `--paper`, `--parchment`, `--ash`, `--charred-ink`, `--ember`, `--olive`. Do not add gradient text, glassmorphism, side-stripe borders, or decorative motion.
-
-- [ ] **Step 4: Mirror the activation path in README**
-
-Add a `## Try the aha moment` section before `## Quick Start`:
-
-````md
-## Try the aha moment
-
-Install Caplets, add Context7, and watch your agent see one capability before it searches downstream tools.
-
-```sh
-npm install -g caplets
-caplets init
-caplets add mcp context7 --command npx --arg -y --arg @upstash/context7-mcp
-caplets serve
-```
-````
-
-In the deterministic benchmark, 106 flat tools became 3 top-level capabilities with an 87.8% smaller initial payload. Your agent starts with `context7`, then drills in through `get_caplet`, `search_tools`, `get_tool`, and `call_tool` only when needed.
-
-````
-
-- [ ] **Step 5: Re-run the text assertions**
-
-Run the same Node assertion from Step 1.
-
-Expected after implementation: exits `0` with no output.
-
-- [ ] **Step 6: Verify landing page**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-````
-
-Expected: Astro check reports 0 errors, 0 warnings, 0 hints; build completes with 1 page built.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add README.md apps/landing/src/pages/index.astro apps/landing/src/styles/global.css docs/plans/2026-05-29-caplets-growth-campaign.md
-git commit -m "docs: plan caplets growth campaign"
-```
-
-## Task 2: Prepare launch copy drafts
-
-**Files:**
-
-- Create: `docs/product/caplets-launch-posts.md`
-
-- [ ] **Step 1: Draft HN post**
-
-Include title, opening paragraph, benchmark proof, setup command, and repo link. Use the headline: `Show HN: Caplets, give agents capabilities instead of giant tool walls`.
-
-- [ ] **Step 2: Draft X/Twitter thread**
-
-Write 6 to 8 short posts: pain, before visual, after visual, benchmark, Context7/GitHub demo, repo CTA.
-
-- [ ] **Step 3: Draft Reddit post**
-
-Write one technical, transparent post titled `I built Caplets to reduce MCP tool overload for coding agents`. Avoid asking for stars directly.
-
-- [ ] **Step 4: Verify copy constraints**
-
-Search the file for em dashes and replace them with commas, colons, semicolons, or parentheses:
-
-```bash
-node - <<'NODE'
-const fs = require('fs');
-const text = fs.readFileSync('docs/product/caplets-launch-posts.md', 'utf8');
-if (text.includes('—')) {
-  console.error('Found em dash in launch copy');
-  process.exit(1);
-}
-NODE
-```
-
-## Task 3: Prepare manual outreach tracker
-
-**Files:**
-
-- Create: `docs/product/caplets-outreach-list.md`
-
-- [ ] **Step 1: Create target categories**
-
-Add sections for MCP server authors, agent power users, awesome-list maintainers, AI devtool newsletter writers, and community moderators.
-
-- [ ] **Step 2: Add outreach message templates**
-
-Include a short DM template that asks for feedback on the 60-second demo rather than asking for a star.
-
-- [ ] **Step 3: Add tracking table**
-
-Columns: `Target`, `Channel`, `Why relevant`, `Status`, `Feedback`, `Follow-up`.
-
-## Task 4: Launch readiness review
-
-**Files:**
-
-- Modify: `docs/product/caplets-launch-posts.md`
-- Modify: `docs/product/caplets-outreach-list.md`
-- Modify as needed: `README.md`, `apps/landing/src/pages/index.astro`, `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Run full focused verification**
-
-```bash
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-pnpm format:check
-```
-
-Expected: all commands exit 0.
-
-- [ ] **Step 2: Review first-screen message**
-
-Confirm the landing page and README both surface the same message: `Give your agents capabilities, not giant tool walls.`
-
-- [ ] **Step 3: Review activation path**
-
-Confirm a fresh visitor can see install commands, a concrete MCP example, and the expected progressive discovery path without scrolling through broad feature lists first.
-
-## Self-Review
-
-- Spec coverage: The plan covers the immediate proof asset and aha section, then launch copy, outreach, and readiness review.
-- Placeholder scan: No TBD, TODO, or vague implementation placeholders remain.
-- Type consistency: Constants and CSS class names are defined in the same task that uses them.
diff --git a/docs/plans/2026-05-29-cli-integration-setup.md b/docs/plans/2026-05-29-cli-integration-setup.md
deleted file mode 100644
index 4eac40e2..00000000
--- a/docs/plans/2026-05-29-cli-integration-setup.md
+++ /dev/null
@@ -1,969 +0,0 @@
-# CLI Integration Setup Implementation Plan
-
-> Superseded for remote/server environment naming: current client integrations use `CAPLETS_REMOTE_*`, while the process hosting `caplets serve --transport http` uses `CAPLETS_SERVER_*`. This plan remains historical implementation context.
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a quick `caplets setup` CLI command that actually installs or configures supported agent integrations, with `--dry-run` available for preview.
-
-**Architecture:** Add an integration setup executor in `packages/core/src/cli/setup.ts` that models each setup as a list of concrete actions. Wire it into the existing Commander CLI in `packages/core/src/cli.ts`, inject the command runner for tests, and keep external mutations limited to explicit agent setup commands or explicit output paths.
-
-**Tech Stack:** TypeScript, Commander, Node `child_process.execFile`, Vitest, existing Caplets CLI helpers, `pnpm` verification.
-
----
-
-## Command Design
-
-The command should be:
-
-```bash
-caplets setup [integration]
-```
-
-Supported integrations:
-
-- `codex`
-- `claude-code`
-- `opencode`
-- `pi`
-- `mcp-client`
-
-Options:
-
-- `--remote`: configure the integration for a remote Caplets HTTP server where supported.
-- `--server-url <url>`: remote Caplets service base URL, defaulting to `CAPLETS_SERVER_URL` when present, otherwise `https://caplets.example.com/caplets`.
-- `--output <path>`: write generic MCP client config to a file. Required for `mcp-client`, because there is no universal MCP client config path.
-- `--dry-run`: print the exact actions without executing commands or writing files.
-- `--format <format>`: `plain` or `json`; default `plain`.
-
-Default behavior is mutating for concrete integrations. `caplets setup codex` runs Codex plugin commands. `caplets setup opencode` runs OpenCode's plugin installer. The command should fail if a required external binary is unavailable and should show the exact failed action.
-
-Known executable command shapes, verified locally where available:
-
-```bash
-codex plugin marketplace add spiritledsoftware/caplets
-codex plugin add caplets@caplets
-opencode plugin @caplets/opencode --global
-pi install npm:@caplets/pi
-```
-
-Claude Code is not installed in this environment, but existing repo docs use:
-
-```bash
-claude plugin marketplace add spiritledsoftware/caplets
-claude plugin install caplets@caplets
-```
-
-Out of scope for this first implementation:
-
-- Editing arbitrary unknown MCP client config files without `--output`.
-- Detecting every possible agent install location.
-- Managing secrets.
-- Starting or daemonizing `caplets serve`.
-
-## File Structure
-
-- Create: `packages/core/src/cli/setup.ts`
-  - Owns supported integration IDs.
-  - Owns setup action modeling.
-  - Executes external commands through an injected runner.
-  - Writes generic MCP config files only when `--output` is provided.
-  - Formats execution results for plain and JSON output.
-- Modify: `packages/core/src/cli/commands.ts`
-  - Adds `setup` to `cliCommands`.
-  - Adds `setup` to `topLevelCommandNames`.
-  - Adds setup integration completions to `cliSubcommands`.
-- Modify: `packages/core/src/cli.ts`
-  - Extends `CliIO` with an optional setup command runner.
-  - Imports setup helpers.
-  - Adds the Commander command.
-- Modify: `packages/core/src/cli/completion.ts`
-  - Adds `setup --format` value completion.
-- Test: `packages/core/test/cli.test.ts`
-  - Adds setup execution tests with injected command runners.
-- Test: `packages/core/test/cli-completion.test.ts`
-  - Adds completion tests for `setup`.
-- Modify: `README.md` and `packages/cli/README.md`
-  - Documents that `caplets setup` performs setup, and that `--dry-run` previews actions.
-- Create: `.changeset/quick-setup-cli.md`
-  - Patch release for `@caplets/core` and `caplets`, because this adds a user-facing CLI command exported through the published CLI package.
-
-## Task 1: Add Failing Setup Execution Tests
-
-**Files:**
-
-- Test: `packages/core/test/cli.test.ts`
-- Later create: `packages/core/src/cli/setup.ts`
-
-- [ ] **Step 1: Write failing tests for menu, Codex execution, and dry-run**
-
-Add this block near existing CLI command tests in `packages/core/test/cli.test.ts`:
-
-```ts
-describe("cli setup", () => {
-  it("prints supported integrations when no integration is provided", async () => {
-    const out: string[] = [];
-
-    await runCli(["setup"], { writeOut: (value) => out.push(value) });
-
-    const text = out.join("");
-    expect(text).toContain("Usage: caplets setup <integration>");
-    expect(text).toContain("codex");
-    expect(text).toContain("claude-code");
-    expect(text).toContain("opencode");
-    expect(text).toContain("pi");
-    expect(text).toContain("mcp-client");
-    expect(text).toContain("--dry-run");
-  });
-
-  it("runs Codex setup commands", async () => {
-    const out: string[] = [];
-    const commands: Array<{ command: string; args: string[] }> = [];
-
-    await runCli(["setup", "codex"], {
-      writeOut: (value) => out.push(value),
-      runSetupCommand: async (command, args) => {
-        commands.push({ command, args });
-        return { stdout: "", stderr: "" };
-      },
-    });
-
-    expect(commands).toEqual([
-      { command: "codex", args: ["plugin", "marketplace", "add", "spiritledsoftware/caplets"] },
-      { command: "codex", args: ["plugin", "add", "caplets@caplets"] },
-    ]);
-    expect(out.join("")).toContain("Completed Codex setup");
-  });
-
-  it("does not execute commands during dry-run", async () => {
-    const out: string[] = [];
-    const commands: Array<{ command: string; args: string[] }> = [];
-
-    await runCli(["setup", "codex", "--dry-run"], {
-      writeOut: (value) => out.push(value),
-      runSetupCommand: async (command, args) => {
-        commands.push({ command, args });
-        return { stdout: "", stderr: "" };
-      },
-    });
-
-    expect(commands).toEqual([]);
-    expect(out.join("")).toContain("Dry run");
-    expect(out.join("")).toContain("codex plugin marketplace add spiritledsoftware/caplets");
-    expect(out.join("")).toContain("codex plugin add caplets@caplets");
-  });
-});
-```
-
-- [ ] **Step 2: Run the focused test and verify it fails**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/cli.test.ts
-```
-
-Expected before implementation: tests fail because `setup` is an unknown command and `runSetupCommand` is not part of `CliIO`.
-
-## Task 2: Implement Setup Action Model and Local Execution
-
-**Files:**
-
-- Create: `packages/core/src/cli/setup.ts`
-- Modify: `packages/core/src/cli/commands.ts`
-- Modify: `packages/core/src/cli.ts`
-
-- [ ] **Step 1: Add command constants**
-
-In `packages/core/src/cli/commands.ts`, add `setup`:
-
-```ts
-export const cliCommands = {
-  completion: "completion",
-  completeHidden: "__complete",
-  serve: "serve",
-  init: "init",
-  setup: "setup",
-  list: "list",
-  install: "install",
-  add: "add",
-  inspect: "inspect",
-  checkBackend: "check-backend",
-  listTools: "list-tools",
-  searchTools: "search-tools",
-  getTool: "get-tool",
-  callTool: "call-tool",
-  listResources: "list-resources",
-  searchResources: "search-resources",
-  listResourceTemplates: "list-resource-templates",
-  readResource: "read-resource",
-  listPrompts: "list-prompts",
-  searchPrompts: "search-prompts",
-  getPrompt: "get-prompt",
-  complete: "complete",
-  config: "config",
-  auth: "auth",
-} as const;
-```
-
-Also insert `cliCommands.setup` in `topLevelCommandNames` after `init`, and add:
-
-```ts
-[cliCommands.setup]: ["codex", "claude-code", "opencode", "pi", "mcp-client"],
-```
-
-to `cliSubcommands`.
-
-- [ ] **Step 2: Create setup executor**
-
-Create `packages/core/src/cli/setup.ts`:
-
-```ts
-import { execFile } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { promisify } from "node:util";
-import { CapletsError } from "../errors";
-
-const execFileAsync = promisify(execFile);
-
-export const setupIntegrationIds = [
-  "codex",
-  "claude-code",
-  "opencode",
-  "pi",
-  "mcp-client",
-] as const;
-
-export type SetupIntegrationId = (typeof setupIntegrationIds)[number];
-export type SetupFormat = "plain" | "json";
-
-export type SetupCommandResult = {
-  stdout: string;
-  stderr: string;
-};
-
-export type SetupCommandRunner = (command: string, args: string[]) => Promise<SetupCommandResult>;
-
-export type SetupOptions = {
-  remote?: boolean;
-  serverUrl?: string;
-  output?: string;
-  dryRun?: boolean;
-  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
-  format?: SetupFormat;
-  runCommand?: SetupCommandRunner;
-};
-
-type SetupAction =
-  | { type: "command"; label: string; command: string; args: string[] }
-  | { type: "writeFile"; label: string; path: string; content: string };
-
-type SetupActionResult = {
-  label: string;
-  command?: string;
-  path?: string;
-  status: "planned" | "completed";
-};
-
-type SetupResult = {
-  integration: SetupIntegrationId;
-  name: string;
-  mode: "local" | "remote";
-  dryRun: boolean;
-  actions: SetupActionResult[];
-  nextSteps: string[];
-};
-
-const localMcpConfig = `{
-  "mcpServers": {
-    "caplets": {
-      "command": "caplets",
-      "args": ["serve"]
-    }
-  }
-}
-`;
-
-export function formatSetupMenu(): string {
-  return [
-    "Usage: caplets setup <integration>",
-    "",
-    "Supported integrations:",
-    "  codex        Run Codex plugin marketplace and plugin install commands",
-    "  claude-code  Run Claude Code plugin marketplace and plugin install commands",
-    "  opencode     Run OpenCode native plugin install",
-    "  pi           Run Pi extension install",
-    "  mcp-client   Write a generic MCP client config with --output",
-    "",
-    "Examples:",
-    "  caplets setup codex",
-    "  caplets setup opencode --dry-run",
-    "  caplets setup mcp-client --output ./caplets.mcp.json",
-    "",
-  ].join("\n");
-}
-
-export async function runSetup(integration: string, options: SetupOptions = {}): Promise<string> {
-  const result = await executeSetup(integration, options);
-  if (options.format === "json") return `${JSON.stringify(result, null, 2)}\n`;
-  return formatSetupResult(result);
-}
-
-async function executeSetup(integration: string, options: SetupOptions): Promise<SetupResult> {
-  const id = parseSetupIntegrationId(integration);
-  const definition = setupDefinition(id, options);
-  const actions: SetupActionResult[] = [];
-  const runner = options.runCommand ?? defaultSetupCommandRunner;
-
-  for (const action of definition.actions) {
-    if (action.type === "command") {
-      const commandText = formatCommand(action.command, action.args);
-      if (!options.dryRun) {
-        try {
-          await runner(action.command, action.args);
-        } catch (error) {
-          throw new CapletsError(
-            "REQUEST_FAILED",
-            `Setup action failed: ${commandText}${error instanceof Error ? `: ${error.message}` : ""}`,
-          );
-        }
-      }
-      actions.push({
-        label: action.label,
-        command: commandText,
-        status: options.dryRun ? "planned" : "completed",
-      });
-      continue;
-    }
-
-    if (!options.dryRun) {
-      mkdirSync(dirname(action.path), { recursive: true });
-      writeFileSync(action.path, action.content, { flag: "wx", mode: 0o600 });
-    }
-    actions.push({
-      label: action.label,
-      path: action.path,
-      status: options.dryRun ? "planned" : "completed",
-    });
-  }
-
-  return {
-    integration: id,
-    name: definition.name,
-    mode: options.remote ? "remote" : "local",
-    dryRun: Boolean(options.dryRun),
-    actions,
-    nextSteps: definition.nextSteps,
-  };
-}
-
-function setupDefinition(
-  id: SetupIntegrationId,
-  options: SetupOptions,
-): { name: string; actions: SetupAction[]; nextSteps: string[] } {
-  if (options.remote) return remoteSetupDefinition(id, options);
-
-  switch (id) {
-    case "codex":
-      return {
-        name: "Codex",
-        actions: [
-          {
-            type: "command",
-            label: "Add Caplets marketplace to Codex",
-            command: "codex",
-            args: ["plugin", "marketplace", "add", "spiritledsoftware/caplets"],
-          },
-          {
-            type: "command",
-            label: "Install Caplets Codex plugin",
-            command: "codex",
-            args: ["plugin", "add", "caplets@caplets"],
-          },
-        ],
-        nextSteps: [
-          "Try a premade Caplet: caplets install spiritledsoftware/caplets github",
-          'Ask Codex: codex "try using the github caplet"',
-        ],
-      };
-    case "claude-code":
-      return {
-        name: "Claude Code",
-        actions: [
-          {
-            type: "command",
-            label: "Add Caplets marketplace to Claude Code",
-            command: "claude",
-            args: ["plugin", "marketplace", "add", "spiritledsoftware/caplets"],
-          },
-          {
-            type: "command",
-            label: "Install Caplets Claude Code plugin",
-            command: "claude",
-            args: ["plugin", "install", "caplets@caplets"],
-          },
-        ],
-        nextSteps: [
-          "Restart Claude Code if it was already running.",
-          "Try a premade Caplet: caplets install spiritledsoftware/caplets github",
-        ],
-      };
-    case "opencode":
-      return {
-        name: "OpenCode",
-        actions: [
-          {
-            type: "command",
-            label: "Install OpenCode Caplets plugin globally",
-            command: "opencode",
-            args: ["plugin", "@caplets/opencode", "--global"],
-          },
-        ],
-        nextSteps: [
-          "OpenCode reads local Caplets config and exposes native caplets_<id> tools.",
-          "Try a premade Caplet: caplets install spiritledsoftware/caplets github",
-        ],
-      };
-    case "pi":
-      return {
-        name: "Pi",
-        actions: [
-          {
-            type: "command",
-            label: "Install Pi Caplets extension",
-            command: "pi",
-            args: ["install", "npm:@caplets/pi"],
-          },
-        ],
-        nextSteps: [
-          "Pi reads local Caplets config and exposes native tools.",
-          "Try a premade Caplet: caplets install spiritledsoftware/caplets github",
-        ],
-      };
-    case "mcp-client":
-      if (!options.output) {
-        throw new CapletsError(
-          "REQUEST_INVALID",
-          "caplets setup mcp-client requires --output <path> because MCP clients do not share one config path",
-        );
-      }
-      return {
-        name: "Any MCP client",
-        actions: [
-          {
-            type: "writeFile",
-            label: "Write generic MCP stdio config",
-            path: options.output,
-            content: localMcpConfig,
-          },
-        ],
-        nextSteps: ["Import the written MCP config into your MCP client."],
-      };
-  }
-}
-
-function remoteSetupDefinition(
-  id: SetupIntegrationId,
-  options: SetupOptions,
-): { name: string; actions: SetupAction[]; nextSteps: string[] } {
-  const serverUrl =
-    nonEmpty(options.serverUrl) ??
-    nonEmpty(options.env?.CAPLETS_SERVER_URL) ??
-    "https://caplets.example.com/caplets";
-
-  if (id === "opencode") {
-    return {
-      name: "OpenCode",
-      actions: [
-        {
-          type: "command",
-          label: "Install OpenCode Caplets plugin globally",
-          command: "opencode",
-          args: ["plugin", "@caplets/opencode", "--global"],
-        },
-      ],
-      nextSteps: [
-        `Run OpenCode with CAPLETS_MODE=remote and CAPLETS_SERVER_URL=${serverUrl}.`,
-        "Keep CAPLETS_SERVER_PASSWORD in your shell or secret manager.",
-      ],
-    };
-  }
-
-  if (id === "pi") {
-    return {
-      name: "Pi",
-      actions: [
-        {
-          type: "command",
-          label: "Install Pi Caplets extension",
-          command: "pi",
-          args: ["install", "npm:@caplets/pi"],
-        },
-      ],
-      nextSteps: [
-        `Start Pi with CAPLETS_MODE=remote and CAPLETS_SERVER_URL=${serverUrl}.`,
-        "Keep CAPLETS_SERVER_PASSWORD in your shell or secret manager.",
-      ],
-    };
-  }
-
-  if (!options.output) {
-    throw new CapletsError(
-      "REQUEST_INVALID",
-      "remote MCP-backed setup requires --output <path> so Caplets can write a client config without guessing your agent's secret storage",
-    );
-  }
-
-  return {
-    name: id === "codex" ? "Codex" : id === "claude-code" ? "Claude Code" : "Any MCP client",
-    actions: [
-      {
-        type: "writeFile",
-        label: "Write remote MCP config",
-        path: options.output,
-        content: `${JSON.stringify({ mcpServers: { caplets: { url: `${serverUrl.replace(/\/$/, "")}/mcp` } } }, null, 2)}\n`,
-      },
-    ],
-    nextSteps: [
-      "Add Basic Auth credentials through your agent's secret mechanism.",
-      "Do not hardcode CAPLETS_SERVER_PASSWORD in a committed config file.",
-    ],
-  };
-}
-
-function parseSetupIntegrationId(value: string): SetupIntegrationId {
-  if (setupIntegrationIds.includes(value as SetupIntegrationId)) {
-    return value as SetupIntegrationId;
-  }
-  throw new CapletsError(
-    "REQUEST_INVALID",
-    `setup integration must be one of: ${setupIntegrationIds.join(", ")}`,
-  );
-}
-
-async function defaultSetupCommandRunner(
-  command: string,
-  args: string[],
-): Promise<SetupCommandResult> {
-  const { stdout, stderr } = await execFileAsync(command, args, {
-    encoding: "utf8",
-    windowsHide: true,
-  });
-  return { stdout, stderr };
-}
-
-function formatSetupResult(result: SetupResult): string {
-  const lines = [
-    `${result.dryRun ? "Dry run" : "Completed"} ${result.name} setup (${result.mode})`,
-    "",
-  ];
-  for (const action of result.actions) {
-    if (action.command) lines.push(`- ${action.status}: ${action.command}`);
-    if (action.path) lines.push(`- ${action.status}: wrote ${action.path}`);
-  }
-  if (result.nextSteps.length > 0) {
-    lines.push("", "Next steps:");
-    for (const step of result.nextSteps) lines.push(`- ${step}`);
-  }
-  lines.push("");
-  return lines.join("\n");
-}
-
-function formatCommand(command: string, args: string[]): string {
-  return [command, ...args].join(" ");
-}
-
-function nonEmpty(value: string | undefined): string | undefined {
-  const trimmed = value?.trim();
-  return trimmed ? trimmed : undefined;
-}
-```
-
-- [ ] **Step 3: Wire Commander and injected runner**
-
-In `packages/core/src/cli.ts`, import:
-
-```ts
-import { runSetup, type SetupCommandRunner, type SetupFormat } from "./cli/setup";
-```
-
-Extend `CliIO`:
-
-```ts
-type CliIO = {
-  writeOut?: (value: string) => void;
-  writeErr?: (value: string) => void;
-  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
-  fetch?: typeof fetch;
-  authDir?: string;
-  version?: string;
-  setExitCode?: (code: number) => void;
-  serve?: (options: ServeOptions) => Promise<void>;
-  runSetupCommand?: SetupCommandRunner;
-};
-```
-
-Add this command after `init`:
-
-```ts
-program
-  .command(cliCommands.setup)
-  .description("Install or configure an agent integration for Caplets.")
-  .argument("[integration]", "integration: codex, claude-code, opencode, pi, or mcp-client")
-  .option("--remote", "configure for a remote Caplets server")
-  .option("--server-url <url>", "remote Caplets service base URL")
-  .option("--output <path>", "config path to write for generic MCP setup")
-  .option("--dry-run", "print actions without running commands or writing files")
-  .option("--format <format>", "output format: plain or json", parseSetupFormat)
-  .action(
-    async (
-      integration: string | undefined,
-      options: {
-        remote?: boolean;
-        serverUrl?: string;
-        output?: string;
-        dryRun?: boolean;
-        format?: SetupFormat;
-      },
-    ) => {
-      if (!integration) {
-        writeOut(formatSetupMenu());
-        return;
-      }
-      writeOut(
-        await runSetup(integration, {
-          ...options,
-          env,
-          runCommand: io.runSetupCommand,
-        }),
-      );
-    },
-  );
-```
-
-Keep `formatSetupMenu` imported:
-
-```ts
-import { formatSetupMenu, runSetup, type SetupCommandRunner, type SetupFormat } from "./cli/setup";
-```
-
-Add this helper near existing parse helpers:
-
-```ts
-function parseSetupFormat(value: string): SetupFormat {
-  if (value === "plain" || value === "json") return value;
-  throw new CapletsError("REQUEST_INVALID", "setup format must be plain or json");
-}
-```
-
-- [ ] **Step 4: Run the focused test and verify it passes**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/cli.test.ts
-```
-
-Expected: the new setup tests pass.
-
-## Task 3: Add File Write, Remote, JSON, and Failure Coverage
-
-**Files:**
-
-- Modify: `packages/core/test/cli.test.ts`
-- Modify: `packages/core/src/cli/setup.ts`
-
-- [ ] **Step 1: Write failing tests for generic config writing and invalid generic setup**
-
-Add:
-
-```ts
-it("writes a generic MCP client config when output is provided", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "caplets-setup-mcp-"));
-  const output = join(dir, "caplets.mcp.json");
-  const out: string[] = [];
-  try {
-    await runCli(["setup", "mcp-client", "--output", output], {
-      writeOut: (value) => out.push(value),
-    });
-
-    expect(readFileSync(output, "utf8")).toContain('"command": "caplets"');
-    expect(readFileSync(output, "utf8")).toContain('"args": ["serve"]');
-    expect(out.join("")).toContain("Completed Any MCP client setup");
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-it("rejects generic MCP client setup without output", async () => {
-  await expect(runCli(["setup", "mcp-client"], { writeErr: () => {} })).rejects.toThrow(
-    expect.objectContaining({ code: "REQUEST_INVALID" }) as CapletsError,
-  );
-});
-```
-
-- [ ] **Step 2: Write failing tests for remote JSON and command failure**
-
-Add:
-
-```ts
-it("runs remote OpenCode setup and reports JSON output", async () => {
-  const out: string[] = [];
-  const commands: Array<{ command: string; args: string[] }> = [];
-
-  await runCli(["setup", "opencode", "--remote", "--format", "json"], {
-    writeOut: (value) => out.push(value),
-    runSetupCommand: async (command, args) => {
-      commands.push({ command, args });
-      return { stdout: "", stderr: "" };
-    },
-  });
-
-  const parsed = JSON.parse(out.join(""));
-  expect(commands).toEqual([
-    { command: "opencode", args: ["plugin", "@caplets/opencode", "--global"] },
-  ]);
-  expect(parsed).toMatchObject({
-    integration: "opencode",
-    name: "OpenCode",
-    mode: "remote",
-    dryRun: false,
-  });
-});
-
-it("wraps setup command failures with the failed command", async () => {
-  await expect(
-    runCli(["setup", "codex"], {
-      writeErr: () => {},
-      runSetupCommand: async () => {
-        throw new Error("missing binary");
-      },
-    }),
-  ).rejects.toThrow(
-    expect.objectContaining({
-      code: "REQUEST_FAILED",
-      message: expect.stringContaining("codex plugin marketplace add spiritledsoftware/caplets"),
-    }) as CapletsError,
-  );
-});
-```
-
-- [ ] **Step 3: Run focused tests and verify failure before implementation**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/cli.test.ts
-```
-
-Expected before Task 2 implementation: failures identify missing setup behavior. Expected after Task 2 implementation: all setup tests pass.
-
-## Task 4: Add Completion Coverage
-
-**Files:**
-
-- Modify: `packages/core/test/cli-completion.test.ts`
-- Modify: `packages/core/src/cli/commands.ts`
-- Modify: `packages/core/src/cli/completion.ts`
-
-- [ ] **Step 1: Write failing completion tests**
-
-Add tests to `packages/core/test/cli-completion.test.ts`:
-
-```ts
-it("suggests setup as a top-level command", async () => {
-  await expect(completeCliWords(["set"])).resolves.toContain("setup");
-});
-
-it("suggests setup integrations", async () => {
-  await expect(completeCliWords(["setup", ""])).resolves.toEqual([
-    "codex",
-    "claude-code",
-    "opencode",
-    "pi",
-    "mcp-client",
-  ]);
-});
-
-it("suggests setup formats", async () => {
-  await expect(completeCliWords(["setup", "codex", "--format", ""])).resolves.toEqual([
-    "plain",
-    "json",
-  ]);
-});
-```
-
-- [ ] **Step 2: Run completion tests and verify failure**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts
-```
-
-Expected before implementation: `setup` and setup format suggestions are missing.
-
-- [ ] **Step 3: Add setup completion values**
-
-In `packages/core/src/cli/completion.ts`, update `optionValueSuggestions`:
-
-```ts
-const optionValueSuggestions: Record<string, Record<string, string[]>> = {
-  "*": { "--format": ["markdown", "md", "plain", "json"] },
-  setup: { "--format": ["plain", "json"] },
-  serve: { "--transport": ["stdio", "http"] },
-  "add:mcp": { "--transport": ["http", "sse"] },
-  "add:cli": { "--include": ["git", "gh", "package"] },
-};
-```
-
-The `cliSubcommands` update from Task 2 supplies integration suggestions.
-
-- [ ] **Step 4: Run completion tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/cli-completion.test.ts
-```
-
-Expected: completion tests pass.
-
-## Task 5: Document Mutating Setup
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `packages/cli/README.md`
-
-- [ ] **Step 1: Add setup command documentation**
-
-In both README files, near the existing integration table, add:
-
-````md
-### Quick integration setup
-
-Use `caplets setup` to install or configure an agent integration:
-
-```bash
-caplets setup codex
-caplets setup claude-code
-caplets setup opencode
-caplets setup pi
-caplets setup mcp-client --output ./caplets.mcp.json
-```
-
-Preview actions before changing anything:
-
-```bash
-caplets setup codex --dry-run
-```
-
-For native integrations that should connect to a remote Caplets HTTP service:
-
-```bash
-caplets setup opencode --remote --server-url https://caplets.example.com/caplets
-```
-
-`caplets setup` runs the supported agent installer commands or writes the explicit config path you pass with `--output`. It does not store secrets, edit unknown MCP client config locations, or start `caplets serve`.
-````
-
-- [ ] **Step 2: Run docs-sensitive checks**
-
-Run:
-
-```bash
-pnpm format:check
-```
-
-Expected: formatting passes.
-
-## Task 6: Add Changeset
-
-**Files:**
-
-- Create: `.changeset/quick-setup-cli.md`
-
-- [ ] **Step 1: Add a changeset**
-
-Create `.changeset/quick-setup-cli.md`:
-
-```md
----
-"@caplets/core": patch
-"caplets": patch
----
-
-Add `caplets setup` to install or configure supported agent integrations.
-```
-
-- [ ] **Step 2: Run focused package checks**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/cli.test.ts test/cli-completion.test.ts
-pnpm --filter @caplets/core typecheck
-```
-
-Expected: tests and typecheck pass.
-
-## Task 7: Full Verification
-
-**Files:**
-
-- All changed files.
-
-- [ ] **Step 1: Run the full gate**
-
-Run:
-
-```bash
-pnpm verify
-```
-
-Expected:
-
-- format check passes.
-- lint passes.
-- typecheck passes.
-- schema check passes.
-- Vitest passes.
-- benchmark check passes.
-- build passes.
-
-- [ ] **Step 2: Inspect final diff**
-
-Run:
-
-```bash
-git diff --check
-git status --short
-```
-
-Expected: no whitespace errors. Changed files should be limited to CLI setup implementation, tests, docs, and changeset, plus pre-existing unrelated work that should not be reverted.
-
-## Self-Review
-
-Spec coverage:
-
-- Setup performs real actions by default: covered by Tasks 1-3.
-- Dry-run preview: covered by Task 1.
-- Codex, Claude Code, OpenCode, Pi, and generic MCP client surfaces: covered by Task 2.
-- Generic MCP client safety through explicit `--output`: covered by Task 3.
-- Remote setup mode: covered by Tasks 2-3.
-- Completion support: covered by Task 4.
-- Documentation: covered by Task 5.
-- Release metadata: covered by Task 6.
-- Verification: covered by Task 7.
-
-Placeholder scan:
-
-- No unresolved implementation placeholders remain.
-- Every implementation step includes concrete file paths and code shapes.
-
-Type consistency:
-
-- `SetupIntegrationId`, `SetupFormat`, `SetupCommandRunner`, and `SetupCommandResult` are introduced before use.
-- Commander wiring uses `runSetup`, `formatSetupMenu`, and `parseSetupFormat` exactly as defined.
diff --git a/docs/plans/2026-05-29-landing-proof-led-activation.md b/docs/plans/2026-05-29-landing-proof-led-activation.md
deleted file mode 100644
index 686743fe..00000000
--- a/docs/plans/2026-05-29-landing-proof-led-activation.md
+++ /dev/null
@@ -1,927 +0,0 @@
-# Landing Page Proof-Led Activation Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Redesign the Caplets landing page around proof-led, agent-native activation so users add Caplets to their agent or MCP client before configuring Context7 as the first capability source.
-
-**Architecture:** Keep the implementation inside the existing Astro page and CSS file. Reorder and reshape page sections rather than introducing a new component system. Preserve the current client-side tab and copy-button script, but update the data and markup it operates on.
-
-**Tech Stack:** Astro, TypeScript-in-Astro script, plain CSS with existing OKLCH tokens, pnpm, Astro typecheck/build.
-
----
-
-## File Structure
-
-- Modify `apps/landing/src/pages/index.astro`
-  - Update top navigation labels.
-  - Replace the bottom-heavy install flow with an agent-native activation section near the top.
-  - Convert benchmark proof into a compact proof strip after the hero.
-  - Compress problem, capability, and trust explanation into one structured section.
-  - Keep integration tabs as expanded setup reference.
-  - Preserve copy-button and tab behavior.
-- Modify `apps/landing/src/styles/global.css`
-  - Add styles for the compact proof strip, activation section, and compressed explanation.
-  - Remove or retire styles only used by deleted repeated sections.
-  - Flatten the hero trace visual by reducing wide shadow and excessive roundness.
-  - Ensure responsive layout has no horizontal overflow.
-- Optionally modify `README.md`
-  - Only if implementation changes public activation wording already duplicated in README.
-- Do not modify `.brv/` files.
-- Do not modify `package.json` package manager metadata.
-
----
-
-### Task 1: Add Source Assertions for the New Story
-
-**Files:**
-
-- Create: `apps/landing/test/campaign-copy.test.mjs`
-- Modify: `apps/landing/package.json`
-
-- [ ] **Step 1: Add a source-level assertion script**
-
-Create `apps/landing/test/campaign-copy.test.mjs`:
-
-```js
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const page = readFileSync(resolve(__dirname, "../src/pages/index.astro"), "utf8");
-
-const required = [
-  "Give your agents capabilities, not giant tool walls.",
-  "106",
-  "3",
-  "87.8%",
-  "Claude Code",
-  "Codex",
-  "OpenCode",
-  "Pi",
-  "Any MCP client",
-  "caplets add mcp context7 --command npx --arg -y --arg @upstash/context7-mcp",
-  "context7",
-  "get_caplet",
-  "search_tools",
-  "get_tool",
-  "call_tool",
-];
-
-const forbiddenVisibleCopy = [
-  "01</span>",
-  "02</span>",
-  "03</span>",
-  "Try the aha moment",
-  "caplets serve\",\n];
-
-const missing = required.filter((needle) => !page.includes(needle));
-const forbidden = forbiddenVisibleCopy.filter((needle) => page.includes(needle));
-
-if (missing.length > 0 || forbidden.length > 0) {
-  if (missing.length > 0) console.error("Missing required copy:", missing);
-  if (forbidden.length > 0) console.error("Forbidden old copy remains:", forbidden);
-  process.exit(1);
-}
-```
-
-- [ ] **Step 2: Add a package script**
-
-In `apps/landing/package.json`, add this script while preserving existing scripts:
-
-```json
-"campaign:check": "node test/campaign-copy.test.mjs"
-```
-
-If the file currently contains:
-
-```json
-{
-  "scripts": {
-    "dev": "astro dev",
-    "build": "astro build",
-    "preview": "astro preview",
-    "typecheck": "astro check"
-  }
-}
-```
-
-it should become:
-
-```json
-{
-  "scripts": {
-    "dev": "astro dev",
-    "build": "astro build",
-    "preview": "astro preview",
-    "typecheck": "astro check",
-    "campaign:check": "node test/campaign-copy.test.mjs"
-  }
-}
-```
-
-- [ ] **Step 3: Run the new assertion and verify it fails before implementation**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing campaign:check
-```
-
-Expected: FAIL because the page still contains old activation structure and may still include the old manual `caplets serve` install step.
-
-- [ ] **Step 4: Commit the failing assertion**
-
-```bash
-git add apps/landing/test/campaign-copy.test.mjs apps/landing/package.json
-git commit -m "test: assert landing activation story"
-```
-
----
-
-### Task 2: Restructure Landing Page Content
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-
-- [ ] **Step 1: Replace activation data model**
-
-In `apps/landing/src/pages/index.astro`, replace the existing `installSteps` constant with these constants:
-
-```ts
-const context7Steps = [
-  "caplets init",
-  "caplets add mcp context7 --command npx --arg -y --arg @upstash/context7-mcp",
-];
-
-const discoveryPath = ["context7", "get_caplet", "search_tools", "get_tool", "call_tool"];
-
-const primaryAgentPaths = [
-  {
-    name: "Claude Code",
-    setup:
-      "Install the Caplets plugin from the marketplace, then add Context7 as your first source.",
-    command: "claude plugin marketplace add spiritledsoftware/caplets",
-  },
-  {
-    name: "Codex",
-    setup:
-      "Add the Caplets plugin marketplace, install the plugin, then add Context7 as your first source.",
-    command: "codex plugin marketplace add spiritledsoftware/caplets",
-  },
-  {
-    name: "Any MCP client",
-    setup: "Configure the client to launch Caplets as its MCP server command, then add Context7.",
-    command: '{ "command": "caplets", "args": ["serve"] }',
-  },
-];
-```
-
-Do not delete `agentSetups`; the expanded integration tabs still use it.
-
-- [ ] **Step 2: Update navigation labels**
-
-Replace the current top nav numbered links:
-
-```astro
-<a href="#trace"><span>01</span> Trace</a>
-<a href="#proof"><span>02</span> Proof</a>
-<a href="#install"><span>03</span> Install</a>
-```
-
-with plain labels:
-
-```astro
-<a href="#trace">Trace</a>
-<a href="#proof">Proof</a>
-<a href="#install">Add to agent</a>
-```
-
-- [ ] **Step 3: Update hero CTA labels**
-
-Replace:
-
-```astro
-<a class="button primary" href="#install">Install Caplets</a>
-<a class="button secondary" href="https://github.com/spiritledsoftware/caplets">Inspect the repo</a>
-```
-
-with:
-
-```astro
-<a class="button primary" href="#install">Add Caplets to your agent</a>
-<a class="button secondary" href="#proof">See the benchmark</a>
-```
-
-- [ ] **Step 4: Move proof strip immediately after hero**
-
-After the closing `</section>` for the hero, insert this new proof strip:
-
-```astro
-<section class="proof-strip" id="proof" aria-label="Deterministic benchmark proof">
-  <div class="proof-strip-copy">
-    <span>Deterministic benchmark</span>
-    <p>Direct MCP aggregation exposed 106 flat tools. Caplets started with 3 capability cards and an 87.8% smaller initial payload.</p>
-  </div>
-  <dl class="proof-strip-stats">
-    {proofStats.map((stat) => (
-      <div>
-        <dt>{stat.label}</dt>
-        <dd>{stat.value}</dd>
-      </div>
-    ))}
-  </dl>
-  <a href="https://github.com/spiritledsoftware/caplets/blob/main/docs/benchmarks/coding-agent.md">Read benchmark method</a>
-</section>
-```
-
-- [ ] **Step 5: Add agent-native activation section immediately after proof strip**
-
-Insert this section after `proof-strip`:
-
-```astro
-<section class="activation" id="install" aria-labelledby="activation-title">
-  <div class="activation-copy">
-    <p class="section-note">Add Caplets to your agent</p>
-    <h2 id="activation-title">Install the integration, then add Context7 as your first capability.</h2>
-    <p>
-      Start where you already work. Caplets should be loaded by your agent plugin, native integration,
-      or MCP client configuration, with Context7 as the first source to prove the flow.
-    </p>
-  </div>
-
-  <div class="agent-paths" aria-label="Fast setup paths">
-    {primaryAgentPaths.map((path) => (
-      <article class="agent-path">
-        <h3>{path.name}</h3>
-        <p>{path.setup}</p>
-        <code>{path.command}</code>
-      </article>
-    ))}
-  </div>
-
-  <div class="context7-setup">
-    <div>
-      <h3>Add Context7</h3>
-      <p>After the integration is installed, add Context7 and look for one `context7` capability inside your agent.</p>
-      <div class="discovery-path" aria-label="Expected discovery path">
-        {discoveryPath.map((step, index) => index === 0 ? <code>{step}</code> : <span>{step}</span>)}
-      </div>
-      <p class="setup-help">If setup fails, check Node 22+, `npx`, plugin installation, and your MCP client command configuration.</p>
-    </div>
-    <div class="terminal" role="region" aria-label="Context7 source commands">
-      <div class="terminal-bar" aria-hidden="true">
-        <span></span><span></span><span></span>
-      </div>
-      <ol>
-        {context7Steps.map((step, index) => (
-          <li>
-            <code id={`context7-step-${index + 1}`} tabindex="-1">{step}</code>
-            <button
-              class="copy-button terminal-copy"
-              type="button"
-              aria-controls={`context7-step-${index + 1}`}
-              data-copy-target={`context7-step-${index + 1}`}
-              data-copy-value={step}
-            >
-              Copy
-            </button>
-          </li>
-        ))}
-      </ol>
-    </div>
-  </div>
-</section>
-```
-
-- [ ] **Step 6: Replace repeated middle sections with one compressed explanation**
-
-Replace the existing `problem`, `proof`, and `trust` sections with this single section:
-
-```astro
-<section class="model" aria-labelledby="model-title">
-  <div class="section-heading narrow">
-    <p class="section-note">Why it works</p>
-    <h2 id="model-title">A capability gives the agent one decision before it sees every operation.</h2>
-  </div>
-  <div class="model-grid">
-    <article>
-      <h3>Before: flat tool wall</h3>
-      <p>Every downstream operation enters context before the agent knows which domain matters.</p>
-    </article>
-    <article>
-      <h3>After: capability first</h3>
-      <p>The agent chooses a source, searches inside that scope, inspects the schema, then calls the tool.</p>
-    </article>
-    <article>
-      <h3>Trust before invocation</h3>
-      <p>Source, auth state, timeout boundary, and safe error recovery stay visible before the call.</p>
-    </article>
-  </div>
-</section>
-```
-
-Delete the old `proof-asset` inside the problem section because the new `proof-strip` replaces it.
-
-- [ ] **Step 7: Rename integrations heading to expanded setup**
-
-Update the integrations section heading from:
-
-```astro
-<p class="section-note">Works where agents work</p>
-<h2 id="integrations-title">Run Caplets from the coding agent you already use.</h2>
-```
-
-to:
-
-```astro
-<p class="section-note">Expanded setup reference</p>
-<h2 id="integrations-title">Choose the integration your agent should load.</h2>
-```
-
-- [ ] **Step 8: Remove the old install section**
-
-Delete the old bottom `<section class="install" id="install" ...>` because the new `activation` section owns `id="install"`. Keep the footer.
-
-- [ ] **Step 9: Run the source assertion**
-
-Run:
-
-```bash
-pnpm --filter @caplets/landing campaign:check
-```
-
-Expected: PASS.
-
-- [ ] **Step 10: Commit content restructure**
-
-```bash
-git add apps/landing/src/pages/index.astro
-git commit -m "feat: restructure landing around agent activation"
-```
-
----
-
-### Task 3: Update CSS for New Section Rhythm
-
-**Files:**
-
-- Modify: `apps/landing/src/styles/global.css`
-
-- [ ] **Step 1: Update shared section selectors**
-
-Replace occurrences of shared selectors that list old sections:
-
-```css
-.problem,
-.proof,
-.integrations,
-.install,
-.site-footer
-```
-
-with:
-
-```css
-.proof-strip,
-.activation,
-.model,
-.integrations,
-.site-footer
-```
-
-For motion selectors, use:
-
-```css
-.motion-ready .proof-strip,
-.motion-ready .activation,
-.motion-ready .model,
-.motion-ready .integrations,
-.motion-ready .agent-path,
-.motion-ready .model-grid article,
-.motion-ready .agent-setup-panel,
-.motion-ready .terminal li
-```
-
-and the matching `.is-visible` selector list.
-
-- [ ] **Step 2: Flatten the trace artifact**
-
-Replace the current `.trace-stage` block with:
-
-```css
-.trace-stage {
-  min-width: 0;
-  border: 1px solid var(--ash);
-  border-radius: 18px;
-  background: var(--paper);
-  overflow: hidden;
-  box-shadow: 0 6px 0 oklch(24% 0.018 100 / 0.08);
-}
-```
-
-This removes the wide 54px blur shadow and over-rounded card feel.
-
-- [ ] **Step 3: Add proof strip styles**
-
-Add after the hero styles:
-
-```css
-.proof-strip {
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) auto auto;
-  gap: clamp(18px, 3vw, 34px);
-  align-items: center;
-  border-block: 1px solid var(--ash);
-  padding-block: clamp(18px, 3vw, 26px);
-}
-
-.proof-strip-copy {
-  min-width: 0;
-}
-
-.proof-strip-copy span {
-  display: block;
-  margin-bottom: 6px;
-  color: var(--ember-deep);
-  font-family: var(--font-mono);
-  font-size: 0.78rem;
-  font-weight: 800;
-}
-
-.proof-strip-copy p {
-  max-width: 68ch;
-  margin: 0;
-  color: var(--charred-ink);
-}
-
-.proof-strip-stats {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 1px;
-  margin: 0;
-  border: 1px solid var(--ash);
-  background: var(--ash);
-}
-
-.proof-strip-stats div {
-  min-width: 112px;
-  padding: 12px 14px;
-  background: var(--paper);
-}
-
-.proof-strip-stats dt {
-  color: var(--olive);
-  text-transform: none;
-  font-size: 0.82rem;
-}
-
-.proof-strip-stats dd {
-  color: var(--charred-ink);
-  font-family: var(--font-mono);
-  font-size: 1rem;
-  font-weight: 800;
-}
-
-.proof-strip a {
-  color: var(--charred-ink);
-  font-weight: 760;
-  white-space: nowrap;
-}
-```
-
-- [ ] **Step 4: Add activation styles**
-
-Add after proof strip styles:
-
-```css
-.activation {
-  display: grid;
-  gap: clamp(22px, 4vw, 40px);
-  border: 1px solid var(--ash);
-  border-radius: 20px;
-  background: var(--paper);
-  padding: clamp(22px, 4vw, 42px);
-}
-
-.activation-copy {
-  max-width: 860px;
-}
-
-.activation h2 {
-  max-width: 13ch;
-  margin: 0;
-  font-size: clamp(2.1rem, 4.2vw, 4.35rem);
-  line-height: 1.02;
-  letter-spacing: -0.038em;
-  text-wrap: balance;
-}
-
-.activation-copy p:last-child {
-  max-width: 68ch;
-  color: var(--olive);
-}
-
-.agent-paths {
-  display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
-  gap: 1px;
-  border: 1px solid var(--ash);
-  background: var(--ash);
-}
-
-.agent-path {
-  min-width: 0;
-  background: var(--linen);
-  padding: 18px;
-}
-
-.agent-path h3 {
-  margin-bottom: 8px;
-  font-size: 1.1rem;
-}
-
-.agent-path p {
-  color: var(--olive);
-}
-
-.agent-path code {
-  display: block;
-  color: var(--charred-ink);
-  font-family: var(--font-mono);
-  font-size: 0.78rem;
-  line-height: 1.45;
-  overflow-wrap: anywhere;
-}
-
-.context7-setup {
-  display: grid;
-  grid-template-columns: minmax(0, 0.78fr) minmax(320px, 1fr);
-  gap: clamp(20px, 4vw, 44px);
-  align-items: start;
-}
-
-.context7-setup h3 {
-  margin-bottom: 10px;
-  font-size: 1.35rem;
-}
-
-.context7-setup p {
-  color: var(--olive);
-}
-
-.discovery-path {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin: 18px 0;
-}
-
-.discovery-path code,
-.discovery-path span {
-  min-height: 34px;
-  display: inline-flex;
-  align-items: center;
-  border: 1px solid var(--ash);
-  border-radius: 999px;
-  padding: 7px 10px;
-  font-family: var(--font-mono);
-  font-size: 0.72rem;
-  font-weight: 760;
-}
-
-.discovery-path code {
-  background: var(--charred-ink);
-  color: var(--parchment);
-}
-
-.discovery-path span {
-  background: var(--linen);
-  color: var(--ember-deep);
-}
-
-.setup-help {
-  max-width: 62ch;
-  margin-bottom: 0;
-  font-size: 0.94rem;
-}
-```
-
-- [ ] **Step 5: Add compressed model styles**
-
-Add after activation styles:
-
-```css
-.model {
-  display: grid;
-  gap: 26px;
-}
-
-.model-grid {
-  display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
-  gap: 1px;
-  border: 1px solid var(--ash);
-  background: var(--ash);
-}
-
-.model-grid article {
-  min-width: 0;
-  background: var(--paper);
-  padding: 22px;
-}
-
-.model-grid h3 {
-  margin-bottom: 8px;
-  font-size: 1.25rem;
-}
-
-.model-grid p {
-  margin: 0;
-  color: var(--olive);
-}
-```
-
-- [ ] **Step 6: Retire deleted-section styles**
-
-Delete CSS blocks that are only used by removed markup:
-
-```css
-.comparison
-.dense-list
-.ordered-flow
-.tool-noise
-.proof-asset
-.proof-stats
-.proof-stat
-.proof-list
-.proof-item
-.proof-eyebrow
-.trust
-.trust-grid
-.trust-item
-.trust-error
-.aha-path
-.install
-.install-copy
-```
-
-Keep `.terminal`, `.terminal-bar`, `.terminal li`, `.terminal-copy`, `.integrations`, and all tab/copy styles.
-
-- [ ] **Step 7: Update responsive rules**
-
-In `@media (max-width: 980px)`, ensure these selectors collapse to one column:
-
-```css
-.proof-strip,
-.activation,
-.context7-setup,
-.agent-paths,
-.model-grid,
-.integrations {
-  grid-template-columns: 1fr;
-}
-
-.proof-strip-stats {
-  width: 100%;
-}
-```
-
-In `@media (max-width: 720px)`, ensure terminal rows and cards fit:
-
-```css
-.agent-path,
-.model-grid article {
-  padding: 16px;
-}
-
-.proof-strip a {
-  white-space: normal;
-}
-```
-
-- [ ] **Step 8: Run typecheck and campaign assertion**
-
-```bash
-pnpm --filter @caplets/landing campaign:check
-pnpm --filter @caplets/landing typecheck
-```
-
-Expected: both pass.
-
-- [ ] **Step 9: Commit CSS restructure**
-
-```bash
-git add apps/landing/src/styles/global.css
-git commit -m "style: tighten landing activation layout"
-```
-
----
-
-### Task 4: Update Motion Script Selectors
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro`
-
-- [ ] **Step 1: Update reveal target selector**
-
-In the script near the bottom of `apps/landing/src/pages/index.astro`, replace the old selector string:
-
-```ts
-".problem, .proof, .trust, .integrations, .install, .proof-item, .trust-item, .trust-error, .agent-setup-panel, .terminal li";
-```
-
-with:
-
-```ts
-".proof-strip, .activation, .model, .integrations, .agent-path, .model-grid article, .agent-setup-panel, .terminal li";
-```
-
-- [ ] **Step 2: Run typecheck**
-
-```bash
-pnpm --filter @caplets/landing typecheck
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Commit motion selector update**
-
-```bash
-git add apps/landing/src/pages/index.astro
-git commit -m "fix: update landing reveal targets"
-```
-
----
-
-### Task 5: Browser Verification and Polish
-
-**Files:**
-
-- Modify: `apps/landing/src/pages/index.astro` if browser inspection finds copy or structure defects.
-- Modify: `apps/landing/src/styles/global.css` if browser inspection finds spacing, contrast, overflow, or responsive defects.
-
-- [ ] **Step 1: Open the user dev server**
-
-Use the running server at:
-
-```text
-http://127.0.0.1:4321/
-```
-
-If port 4321 is not responding, ask the user before starting another server.
-
-- [ ] **Step 2: Inspect desktop layout**
-
-Use browser automation at `1440x1100`. Evaluate:
-
-```js
-(() => {
-  const vw = innerWidth;
-  const overflow = [...document.querySelectorAll("body *")]
-    .filter((el) => {
-      const r = el.getBoundingClientRect();
-      return r.right > vw + 1 || r.left < -1;
-    })
-    .map((el) => ({
-      tag: el.tagName,
-      cls: String(el.className),
-      text: el.textContent.trim().slice(0, 80),
-    }));
-
-  const sections = [...document.querySelectorAll("main > section")].map((el) => {
-    const r = el.getBoundingClientRect();
-    return { cls: String(el.className), top: Math.round(r.top), height: Math.round(r.height) };
-  });
-
-  return { scrollWidth: document.documentElement.scrollWidth, vw, overflow, sections };
-})();
-```
-
-Expected:
-
-```json
-{
-  "scrollWidth": 1440,
-  "vw": 1440,
-  "overflow": []
-}
-```
-
-Section heights should show activation near the top, before the compressed model and integrations.
-
-- [ ] **Step 3: Inspect mobile layout**
-
-Resize to `390x844` and run the same overflow script.
-
-Expected:
-
-```json
-{
-  "scrollWidth": 390,
-  "vw": 390,
-  "overflow": []
-}
-```
-
-Confirm the activation section appears before detailed integrations and that terminal code wraps rather than overflowing.
-
-- [ ] **Step 4: Check console messages**
-
-Expected: no browser errors or warnings from the app.
-
-- [ ] **Step 5: Apply minimal polish fixes**
-
-If any of these are observed, apply only the matching fix:
-
-- Horizontal overflow from code: add `overflow-wrap: anywhere` to the specific code selector.
-- Activation too visually heavy: reduce padding by one clamp step or remove a redundant border.
-- Proof strip feels like metric cards: reduce stat box padding and keep labels subdued.
-- Hero trace still looks like SaaS card: reduce border radius to `16px` or remove remaining shadow.
-
-- [ ] **Step 6: Run focused verification**
-
-```bash
-pnpm --filter @caplets/landing campaign:check
-pnpm --filter @caplets/landing typecheck
-pnpm --filter @caplets/landing build
-git diff --check
-```
-
-Expected: all pass.
-
-- [ ] **Step 7: Commit browser polish**
-
-If Step 5 changed files:
-
-```bash
-git add apps/landing/src/pages/index.astro apps/landing/src/styles/global.css
-git commit -m "fix: polish landing activation responsiveness"
-```
-
-If Step 5 changed nothing, do not create an empty commit.
-
----
-
-### Task 6: Final Verification and Report
-
-**Files:**
-
-- No source edits unless verification exposes a defect.
-
-- [ ] **Step 1: Run final source assertions**
-
-```bash
-pnpm --filter @caplets/landing campaign:check
-```
-
-Expected: PASS.
-
-- [ ] **Step 2: Run final typecheck**
-
-```bash
-pnpm --filter @caplets/landing typecheck
-```
-
-Expected: `0 errors`, `0 warnings`, `0 hints`.
-
-- [ ] **Step 3: Run final build**
-
-```bash
-pnpm --filter @caplets/landing build
-```
-
-Expected: build completes successfully and reports one page built.
-
-- [ ] **Step 4: Run whitespace check**
-
-```bash
-git diff --check
-```
-
-Expected: no output and exit code 0.
-
-- [ ] **Step 5: Summarize changed files and verification**
-
-Report:
-
-```text
-Changed files:
-- apps/landing/src/pages/index.astro
-- apps/landing/src/styles/global.css
-- apps/landing/package.json
-- apps/landing/test/campaign-copy.test.mjs
-- docs/specs/2026-05-29-landing-proof-led-activation-design.md
-- docs/plans/2026-05-29-landing-proof-led-activation.md
-
-Verification:
-- pnpm --filter @caplets/landing campaign:check: passed
-- pnpm --filter @caplets/landing typecheck: passed
-- pnpm --filter @caplets/landing build: passed
-- git diff --check: passed
-- Browser desktop/mobile overflow: none
-```
-
-Do not claim completion if any verification step fails.
diff --git a/docs/plans/2026-06-04-remote-attach-and-agent-integrations.md b/docs/plans/2026-06-04-remote-attach-and-agent-integrations.md
deleted file mode 100644
index 85ceaa2d..00000000
--- a/docs/plans/2026-06-04-remote-attach-and-agent-integrations.md
+++ /dev/null
@@ -1,1738 +0,0 @@
-# Remote Attach And Agent Integrations Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make `caplets serve` local-only, make `caplets attach` the remote-backed MCP server for self-hosted and Cloud upstreams, keep OpenCode/Pi on the shared resolver, and remove Codex/Claude native plugin artifacts.
-
-**Architecture:** Consolidate remote selection in Core around `CAPLETS_MODE` and `CAPLETS_REMOTE_*`, then reuse that resolver from the attach command and native integrations. `serve` keeps the existing local `CapletsEngine` path, while `attach` creates a remote-plus-local-overlay MCP surface and starts Project Binding automatically for Cloud selections.
-
-**Tech Stack:** TypeScript, Commander, Vitest, MCP SDK stdio and Streamable HTTP transports, Hono HTTP server, existing Cloud Auth store/client, existing Project Binding session manager, OpenCode and Pi native integration packages, pnpm.
-
----
-
-## Source Spec
-
-- Root design spec: `/Users/ianpascoe/src/caplets-mono/docs/superpowers/specs/2026-06-04-remote-attach-and-agent-integration-design.md`
-- Core plan location follows `core/AGENTS.md`: `/Users/ianpascoe/src/caplets-mono/core/docs/plans/`
-
-## File Structure
-
-- Modify `packages/core/src/remote/options.ts`: expand mode parsing to `auto | local | remote | cloud`, add Cloud URL detection, and keep self-hosted auth resolution separate from Cloud Auth.
-- Add `packages/core/src/remote/selection.ts`: resolve a full upstream selection for commands and integrations, including self-hosted remote options, Cloud credentials, refresh, selected workspace, and Project Binding metadata.
-- Modify `packages/core/src/project-binding/attach.ts`: consume the shared selection helper for one-shot Project Binding probes and long-running sessions; stop treating saved Cloud Auth as an implicit remote when no remote URL or Cloud mode is selected.
-- Add `packages/core/src/attach/options.ts`: resolve `caplets attach` server options, including `--transport stdio|http`, HTTP bind/auth options, and the remote selection.
-- Add `packages/core/src/attach/server.ts`: start the remote-backed MCP server for stdio and HTTP transports and own the attach server lifecycle.
-- Add `packages/core/src/serve/native-session.ts`: register MCP tools from a `NativeCapletsService` so `attach` can expose the remote-plus-local-overlay surface without inventing a second merge path.
-- Modify `packages/core/src/serve/http.ts`: extract the session creation seam so HTTP serving can use either local `CapletsMcpSession` or native-service-backed sessions.
-- Modify `packages/core/src/serve/index.ts`: export reusable serve helpers used by attach.
-- Modify `packages/core/src/cli.ts`: change `caplets attach` from binding-only default to MCP server default; keep `--once` as the Project Binding smoke path.
-- Modify `packages/core/src/native/options.ts`: use the shared resolver and expose `local | remote | cloud` semantics to OpenCode/Pi.
-- Modify `packages/core/src/native/service.ts`: start Cloud Project Binding from saved Cloud Auth in Cloud mode and preserve local overlay precedence.
-- Modify `packages/core/src/native/remote.ts`: adjust auth failure guidance for self-hosted vs Cloud modes.
-- Modify `packages/core/src/native.ts`: export new resolver and option types.
-- Modify `packages/core/test/remote-options.test.ts`: cover `CAPLETS_MODE=cloud`, auto Cloud detection, invalid mode/URL combinations, and self-hosted auth.
-- Add `packages/core/test/remote-selection.test.ts`: cover saved Cloud Auth loading, refresh, workspace matching, token precedence, and no-implicit-cloud behavior.
-- Modify `packages/core/test/attach-cli.test.ts`: cover attach server option parsing, `--once` Project Binding smoke behavior, local-mode rejection, and Cloud mode errors.
-- Add `packages/core/test/attach-server.test.ts`: cover stdio/http attach server delegation using a fake native service and fake serve transports.
-- Modify `packages/core/test/cloud-auth-refresh-attach.test.ts`: assert refresh occurs only through explicit Cloud selection.
-- Modify `packages/core/test/native-options.test.ts`: cover Cloud mode and auto Cloud detection for native integrations.
-- Modify `packages/core/test/native-remote.test.ts`: cover Cloud Project Binding startup and fallback semantics.
-- Modify `packages/core/test/agent-plugins.test.ts`: invert plugin assertions so Codex/Claude plugin artifacts are absent and manual MCP docs are present.
-- Delete `plugins/caplets/.codex-plugin/plugin.json`.
-- Delete `plugins/caplets/.claude-plugin/plugin.json`.
-- Delete `plugins/caplets/mcp.json`.
-- Delete `plugins/caplets/skills/caplets/SKILL.md`.
-- Delete `plugins/caplets/assets/icon.png` only if no package README or landing asset still references it; otherwise move the asset to a non-plugin docs asset path in the same task.
-- Delete `plugins/caplets/` after required children are removed.
-- Delete `.agents/plugins/marketplace.json`.
-- Delete `.claude-plugin/marketplace.json`.
-- Delete `scripts/sync-plugin-versions.ts`.
-- Modify `package.json`: remove `scripts/sync-plugin-versions.ts` from `version-packages`.
-- Modify `README.md`: replace Codex/Claude plugin install docs with manual MCP config for `serve` and `attach`.
-- Modify `packages/cli/README.md` if it contains plugin install guidance.
-- Modify `docs/native-integrations.md`: document OpenCode/Pi `CAPLETS_MODE` and `CAPLETS_REMOTE_*` behavior.
-- Modify `packages/opencode/README.md`: document local, self-hosted, and Cloud env flows.
-- Modify `packages/pi/README.md`: document local, self-hosted, and Cloud env/settings flows.
-- Add a Changesets entry for `@caplets/core`, `caplets`, `@caplets/opencode`, and `@caplets/pi`.
-
----
-
-## Task 1: Shared Remote Mode Semantics
-
-**Files:**
-
-- Modify: `packages/core/src/remote/options.ts`
-- Modify: `packages/core/test/remote-options.test.ts`
-
-- [ ] **Step 1: Add failing resolver tests**
-
-Append these cases to `packages/core/test/remote-options.test.ts`:
-
-```ts
-it("supports explicit cloud mode with a Caplets Cloud URL", () => {
-  expect(
-    resolveRemoteMode(
-      {},
-      {
-        CAPLETS_MODE: "cloud",
-        CAPLETS_REMOTE_URL: "https://cloud.caplets.dev",
-      },
-    ),
-  ).toEqual({ mode: "cloud" });
-});
-
-it("detects cloud mode in auto from CAPLETS_REMOTE_URL", () => {
-  expect(resolveRemoteMode({}, { CAPLETS_REMOTE_URL: "https://cloud.caplets.dev" })).toEqual({
-    mode: "cloud",
-  });
-});
-
-it("keeps non-Cloud CAPLETS_REMOTE_URL in self-hosted remote mode", () => {
-  expect(
-    resolveRemoteMode({}, { CAPLETS_REMOTE_URL: "https://caplets.example.com/caplets" }),
-  ).toEqual({
-    mode: "remote",
-  });
-});
-
-it("rejects explicit cloud mode with a non-Cloud URL", () => {
-  expect(() =>
-    resolveRemoteMode(
-      {},
-      {
-        CAPLETS_MODE: "cloud",
-        CAPLETS_REMOTE_URL: "https://caplets.example.com/caplets",
-      },
-    ),
-  ).toThrow(/CAPLETS_MODE=cloud requires CAPLETS_REMOTE_URL to point at Caplets Cloud/u);
-});
-
-it("rejects explicit cloud mode without CAPLETS_REMOTE_URL", () => {
-  expect(() => resolveRemoteMode({}, { CAPLETS_MODE: "cloud" })).toThrow(
-    /CAPLETS_MODE=cloud requires CAPLETS_REMOTE_URL/u,
-  );
-});
-
-it("parses cloud as a valid CAPLETS_MODE value", () => {
-  expect(() => resolveRemoteMode({}, { CAPLETS_MODE: "sidecar" })).toThrow(
-    /Expected CAPLETS_MODE to be auto, local, remote, or cloud/u,
-  );
-});
-```
-
-- [ ] **Step 2: Run resolver tests to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/remote-options.test.ts
-```
-
-Expected: FAIL because `cloud` is not accepted and auto always maps any remote URL to `remote`.
-
-- [ ] **Step 3: Implement mode expansion**
-
-In `packages/core/src/remote/options.ts`, change the mode type and parser:
-
-```ts
-export type CapletsRemoteMode = "local" | "remote" | "cloud";
-
-export function resolveRemoteMode(
-  input: CapletsRemoteModeInput = {},
-  env: CapletsRemoteEnv = process.env,
-): { mode: CapletsRemoteMode } {
-  const mode = parseCapletsMode(input.mode ?? env.CAPLETS_MODE ?? "auto");
-  if (mode === "local") return { mode: "local" };
-
-  const rawUrl =
-    nonEmpty(input.remoteUrl, "remoteUrl") ??
-    nonEmpty(env.CAPLETS_REMOTE_URL, "CAPLETS_REMOTE_URL");
-
-  if (mode === "remote") {
-    if (rawUrl === undefined) {
-      throw new CapletsError(
-        "REQUEST_INVALID",
-        "CAPLETS_MODE=remote requires CAPLETS_REMOTE_URL or remoteUrl.",
-      );
-    }
-    return { mode: "remote" };
-  }
-
-  if (mode === "cloud") {
-    if (rawUrl === undefined) {
-      throw new CapletsError("REQUEST_INVALID", "CAPLETS_MODE=cloud requires CAPLETS_REMOTE_URL.");
-    }
-    if (!isCapletsCloudUrl(rawUrl)) {
-      throw new CapletsError(
-        "REQUEST_INVALID",
-        "CAPLETS_MODE=cloud requires CAPLETS_REMOTE_URL to point at Caplets Cloud.",
-      );
-    }
-    return { mode: "cloud" };
-  }
-
-  if (rawUrl === undefined) return { mode: "local" };
-  return isCapletsCloudUrl(rawUrl) ? { mode: "cloud" } : { mode: "remote" };
-}
-
-export function isCapletsCloudUrl(value: string): boolean {
-  let url: URL;
-  try {
-    url = new URL(value);
-  } catch {
-    return false;
-  }
-  const host = url.hostname.toLowerCase();
-  return host === "cloud.caplets.dev" || host.endsWith(".preview.caplets.dev");
-}
-
-function parseCapletsMode(value: string): "auto" | CapletsRemoteMode {
-  if (value === "auto" || value === "local" || value === "remote" || value === "cloud") {
-    return value;
-  }
-  throw new CapletsError(
-    "REQUEST_INVALID",
-    `Expected CAPLETS_MODE to be auto, local, remote, or cloud, got ${value}`,
-  );
-}
-```
-
-- [ ] **Step 4: Run resolver tests to verify green**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/remote-options.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add packages/core/src/remote/options.ts packages/core/test/remote-options.test.ts
-git commit -m "feat(core): resolve cloud remote mode"
-```
-
----
-
-## Task 2: Full Upstream Selection With Cloud Auth
-
-**Files:**
-
-- Add: `packages/core/src/remote/selection.ts`
-- Modify: `packages/core/src/project-binding/attach.ts`
-- Add: `packages/core/test/remote-selection.test.ts`
-- Modify: `packages/core/test/cloud-auth-refresh-attach.test.ts`
-
-- [ ] **Step 1: Add failing selection tests**
-
-Create `packages/core/test/remote-selection.test.ts`:
-
-```ts
-import { describe, expect, it } from "vitest";
-import { CloudAuthStore } from "../src/cloud-auth/store";
-import { resolveRemoteSelection } from "../src/remote/selection";
-import { hostedCredentials, tempCloudAuthPath } from "./fixtures/cloud-auth";
-
-describe("resolveRemoteSelection", () => {
-  it("rejects attach selection in local mode", async () => {
-    await expect(resolveRemoteSelection({}, { CAPLETS_MODE: "local" })).rejects.toThrow(
-      /caplets attach requires a remote upstream; use caplets serve for local-only MCP/u,
-    );
-  });
-
-  it("rejects auto mode without a remote URL for attach", async () => {
-    await expect(resolveRemoteSelection({}, {})).rejects.toThrow(/CAPLETS_REMOTE_URL/u);
-  });
-
-  it("resolves self-hosted remote auth from CAPLETS_REMOTE variables", async () => {
-    await expect(
-      resolveRemoteSelection(
-        {},
-        {
-          CAPLETS_MODE: "remote",
-          CAPLETS_REMOTE_URL: "https://caplets.example.com/caplets",
-          CAPLETS_REMOTE_TOKEN: "remote-token",
-        },
-      ),
-    ).resolves.toMatchObject({
-      kind: "self_hosted_remote",
-      remote: {
-        baseUrl: new URL("https://caplets.example.com/caplets"),
-        auth: { type: "bearer", token: "remote-token" },
-      },
-    });
-  });
-
-  it("uses saved Cloud Auth in cloud mode and ignores self-hosted token vars", async () => {
-    const path = tempCloudAuthPath();
-    await new CloudAuthStore({ path }).save(hostedCredentials({ accessToken: "cloud-access" }));
-
-    const resolved = await resolveRemoteSelection(
-      {},
-      {
-        CAPLETS_MODE: "cloud",
-        CAPLETS_REMOTE_URL: "https://cloud.caplets.dev",
-        CAPLETS_REMOTE_TOKEN: "self-hosted-token",
-        CAPLETS_CLOUD_AUTH_PATH: path,
-      },
-    );
-
-    expect(resolved).toMatchObject({
-      kind: "hosted_cloud",
-      selectedWorkspace: "personal",
-      remote: {
-        baseUrl: new URL("https://cloud.caplets.dev"),
-        auth: { type: "bearer", token: "cloud-access" },
-      },
-    });
-  });
-
-  it("refreshes expired Cloud credentials before returning the upstream", async () => {
-    const path = tempCloudAuthPath();
-    await new CloudAuthStore({ path }).save(
-      hostedCredentials({
-        accessToken: "old-access",
-        refreshToken: "old-refresh",
-        expiresAt: "2026-06-03T00:00:00.000Z",
-      }),
-    );
-
-    const resolved = await resolveRemoteSelection(
-      {
-        fetch: async (url, init) => {
-          expect(String(url)).toBe("https://cloud.caplets.dev/api/cloud-client/refresh");
-          expect(JSON.parse(String(init?.body))).toEqual({ refreshToken: "old-refresh" });
-          return Response.json({
-            status: "authenticated",
-            cloudUrl: "https://cloud.caplets.dev",
-            workspaceId: "workspace_personal",
-            workspaceSlug: "personal",
-            accessToken: "new-access",
-            refreshToken: "new-refresh",
-            expiresAt: "2999-01-01T00:00:00.000Z",
-            scope: ["project_binding:read", "project_binding:write"],
-            tokenType: "Bearer",
-            credentialFamilyId: "family_123",
-          });
-        },
-      },
-      {
-        CAPLETS_MODE: "cloud",
-        CAPLETS_REMOTE_URL: "https://cloud.caplets.dev",
-        CAPLETS_CLOUD_AUTH_PATH: path,
-      },
-    );
-
-    expect(resolved.remote.auth).toEqual({ type: "bearer", token: "new-access" });
-  });
-
-  it("requires Cloud Auth when cloud mode is selected", async () => {
-    await expect(
-      resolveRemoteSelection(
-        {},
-        {
-          CAPLETS_MODE: "cloud",
-          CAPLETS_REMOTE_URL: "https://cloud.caplets.dev",
-        },
-      ),
-    ).rejects.toMatchObject({
-      projectBindingCode: "cloud_auth_required",
-    });
-  });
-});
-```
-
-- [ ] **Step 2: Run selection tests to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/remote-selection.test.ts
-```
-
-Expected: FAIL because `remote/selection.ts` does not exist.
-
-- [ ] **Step 3: Implement `resolveRemoteSelection`**
-
-Create `packages/core/src/remote/selection.ts` with these exports and behavior:
-
-```ts
-import { CloudAuthClient } from "../cloud-auth/client";
-import { CloudAuthStore, type CloudAuthCredentials } from "../cloud-auth/store";
-import { projectBindingError } from "../project-binding/errors";
-import { resolveCapletsRemote, resolveRemoteMode, type ResolvedCapletsRemote } from "./options";
-
-export type RemoteSelectionInput = {
-  remoteUrl?: string;
-  user?: string;
-  password?: string;
-  token?: string;
-  workspace?: string;
-  fetch?: typeof fetch;
-  requireUpstream?: boolean;
-};
-
-export type ResolvedRemoteSelection =
-  | {
-      kind: "self_hosted_remote";
-      remote: ResolvedCapletsRemote;
-    }
-  | {
-      kind: "hosted_cloud";
-      remote: ResolvedCapletsRemote;
-      selectedWorkspace: string;
-      credentials: CloudAuthCredentials;
-      cloudPresence: {
-        url: URL;
-        accessToken: string;
-        workspaceId: string;
-      };
-    };
-
-export async function resolveRemoteSelection(
-  input: RemoteSelectionInput = {},
-  env: Record<string, string | undefined> = process.env,
-): Promise<ResolvedRemoteSelection> {
-  const mode = resolveRemoteMode({ mode: env.CAPLETS_MODE, remoteUrl: input.remoteUrl }, env);
-  if (mode.mode === "local") {
-    throw new Error(
-      "caplets attach requires a remote upstream; use caplets serve for local-only MCP.",
-    );
-  }
-
-  if (mode.mode === "remote") {
-    return {
-      kind: "self_hosted_remote",
-      remote: resolveCapletsRemote(
-        {
-          url: input.remoteUrl,
-          user: input.user,
-          password: input.password,
-          token: input.token,
-          workspace: input.workspace,
-          fetch: input.fetch,
-        },
-        env,
-      ),
-    };
-  }
-
-  const store = new CloudAuthStore({ env });
-  let credentials = await store.load();
-  if (!credentials?.accessToken) throw projectBindingError("cloud_auth_required");
-
-  if (credentialsNeedRefresh(credentials)) {
-    if (!credentials.refreshToken) throw projectBindingError("cloud_auth_required");
-    const refreshed = await new CloudAuthClient({
-      cloudUrl: credentials.cloudUrl,
-      ...(input.fetch ? { fetch: input.fetch } : {}),
-    }).refresh({ refreshToken: credentials.refreshToken });
-    credentials = {
-      ...credentials,
-      ...refreshed,
-      refreshToken: refreshed.refreshToken ?? credentials.refreshToken,
-      createdAt: credentials.createdAt,
-      lastRefreshAt: new Date().toISOString(),
-    };
-    await store.save(credentials);
-  }
-
-  const selectedWorkspace = credentials.workspaceSlug ?? credentials.workspaceId;
-  if (
-    input.workspace &&
-    input.workspace !== credentials.workspaceId &&
-    input.workspace !== credentials.workspaceSlug
-  ) {
-    throw projectBindingError(
-      "workspace_switch_required",
-      `Requested workspace ${input.workspace} differs from saved Selected Workspace ${selectedWorkspace}.`,
-    );
-  }
-
-  const remoteUrl = input.remoteUrl ?? env.CAPLETS_REMOTE_URL ?? credentials.cloudUrl;
-  const remote = resolveCapletsRemote(
-    {
-      url: remoteUrl,
-      token: credentials.accessToken,
-      workspace: selectedWorkspace,
-      ...(input.fetch ? { fetch: input.fetch } : {}),
-    },
-    {},
-  );
-
-  return {
-    kind: "hosted_cloud",
-    remote,
-    selectedWorkspace,
-    credentials,
-    cloudPresence: {
-      url: new URL(remoteUrl),
-      accessToken: credentials.accessToken,
-      workspaceId: credentials.workspaceId,
-    },
-  };
-}
-
-function credentialsNeedRefresh(credentials: { expiresAt: string }): boolean {
-  const expiresAt = Date.parse(credentials.expiresAt);
-  return Number.isFinite(expiresAt) && expiresAt <= Date.now() + 60_000;
-}
-```
-
-During implementation, replace the plain `Error` local-mode failure with `CapletsError("REQUEST_INVALID", ...)` so JSON CLI handling remains structured.
-
-- [ ] **Step 4: Update Project Binding attach to use selection**
-
-In `packages/core/src/project-binding/attach.ts`:
-
-- Replace direct `resolveCapletsRemote(...)` calls with `await resolveRemoteSelection(...)`.
-- Remove `hasExplicitRemote(...)`; saved Cloud Auth must not implicitly select Cloud without `CAPLETS_MODE=cloud` or `CAPLETS_MODE=auto` plus a Cloud `CAPLETS_REMOTE_URL`.
-- Keep `authMode` values as `"self_hosted_remote"` and `"hosted_cloud"` from `selection.kind`.
-- Keep `selectedWorkspace` only for Cloud selections.
-
-The resolved return should be shaped like:
-
-```ts
-const selection = await resolveRemoteSelection(remoteInput, env);
-return {
-  projectRoot: raw.projectRoot ?? process.cwd(),
-  json: raw.json === true,
-  verbose: raw.verbose === true,
-  once: raw.once === true,
-  remote: selection.remote,
-  authMode: selection.kind,
-  ...(selection.kind === "hosted_cloud"
-    ? { selectedWorkspace: selection.selectedWorkspace }
-    : remoteInput.workspace
-      ? { selectedWorkspace: remoteInput.workspace }
-      : {}),
-};
-```
-
-- [ ] **Step 5: Update Cloud refresh attach tests**
-
-In `packages/core/test/cloud-auth-refresh-attach.test.ts`, update every attach call that expects Cloud Auth to pass:
-
-```ts
-{
-  CAPLETS_MODE: "cloud",
-  CAPLETS_REMOTE_URL: "https://cloud.caplets.dev",
-  CAPLETS_CLOUD_AUTH_PATH: path,
-}
-```
-
-Add one regression test:
-
-```ts
-it("does not implicitly use saved Cloud Auth without cloud mode or a Cloud remote URL", async () => {
-  const path = tempCloudAuthPath();
-  await new CloudAuthStore({ path }).save(hostedCredentials());
-
-  await expect(
-    attachProjectOnce({ projectRoot: "/repo" }, { CAPLETS_CLOUD_AUTH_PATH: path }),
-  ).rejects.toThrow(/CAPLETS_REMOTE_URL/u);
-});
-```
-
-- [ ] **Step 6: Run selection and attach tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/remote-selection.test.ts test/cloud-auth-refresh-attach.test.ts test/attach-cli.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add packages/core/src/remote/selection.ts packages/core/src/project-binding/attach.ts packages/core/test/remote-selection.test.ts packages/core/test/cloud-auth-refresh-attach.test.ts packages/core/test/attach-cli.test.ts
-git commit -m "feat(core): select remote upstreams for attach"
-```
-
----
-
-## Task 3: Native-Service-Backed MCP Sessions
-
-**Files:**
-
-- Add: `packages/core/src/serve/native-session.ts`
-- Modify: `packages/core/src/serve/index.ts`
-- Add: `packages/core/test/attach-server.test.ts`
-
-- [ ] **Step 1: Add failing session tests**
-
-Create `packages/core/test/attach-server.test.ts` with a fake MCP server:
-
-```ts
-import { describe, expect, it, vi } from "vitest";
-import { NativeCapletsMcpSession } from "../src/serve/native-session";
-
-describe("NativeCapletsMcpSession", () => {
-  it("registers tools from a native Caplets service", async () => {
-    const registered = new Map<string, unknown>();
-    const server = {
-      registerTool: vi.fn((name: string, definition: unknown, callback: unknown) => {
-        registered.set(name, { definition, callback });
-        return { remove: vi.fn(), update: vi.fn() };
-      }),
-      connect: vi.fn(async () => undefined),
-      close: vi.fn(async () => undefined),
-    };
-    const service = {
-      listTools: () => [
-        {
-          caplet: "remote-alpha",
-          toolName: "caplets_remote_alpha",
-          title: "Remote Alpha",
-          description: "Remote alpha tool",
-          promptGuidance: [],
-          inputSchema: {
-            type: "object",
-            properties: { operation: { type: "string", enum: ["inspect"] } },
-          },
-          operationNames: ["inspect"],
-        },
-      ],
-      execute: vi.fn(async () => ({ ok: true })),
-      reload: vi.fn(async () => true),
-      onToolsChanged: vi.fn(() => () => undefined),
-      close: vi.fn(async () => undefined),
-    };
-
-    const session = new NativeCapletsMcpSession(service, { server });
-
-    expect([...registered.keys()]).toEqual(["remote-alpha"]);
-    const tool = registered.get("remote-alpha") as {
-      callback: (request: unknown) => Promise<unknown>;
-    };
-    await expect(tool.callback({ operation: "inspect" })).resolves.toEqual({ ok: true });
-    expect(service.execute).toHaveBeenCalledWith("remote-alpha", { operation: "inspect" });
-    await session.close();
-    expect(service.close).toHaveBeenCalledOnce();
-  });
-
-  it("updates registered tools when the native service changes", () => {
-    let listener: ((tools: unknown[]) => void) | undefined;
-    const removed = vi.fn();
-    const updates: unknown[] = [];
-    const server = {
-      registerTool: vi.fn((_name: string, _definition: unknown, _callback: unknown) => ({
-        remove: removed,
-        update: (definition: unknown) => updates.push(definition),
-      })),
-      connect: vi.fn(async () => undefined),
-      close: vi.fn(async () => undefined),
-    };
-    const service = {
-      listTools: () => [
-        { caplet: "alpha", title: "Alpha", description: "Alpha", promptGuidance: [] },
-      ],
-      execute: vi.fn(async () => ({})),
-      reload: vi.fn(async () => true),
-      onToolsChanged: vi.fn((nextListener: (tools: unknown[]) => void) => {
-        listener = nextListener;
-        return () => undefined;
-      }),
-      close: vi.fn(async () => undefined),
-    };
-
-    new NativeCapletsMcpSession(service as never, { server });
-    listener?.([{ caplet: "beta", title: "Beta", description: "Beta", promptGuidance: [] }]);
-
-    expect(removed).toHaveBeenCalledOnce();
-    expect(server.registerTool).toHaveBeenCalledWith(
-      "beta",
-      expect.objectContaining({ title: "Beta" }),
-      expect.any(Function),
-    );
-  });
-});
-```
-
-- [ ] **Step 2: Run session tests to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/attach-server.test.ts
-```
-
-Expected: FAIL because `serve/native-session.ts` does not exist.
-
-- [ ] **Step 3: Implement native MCP session**
-
-Create `packages/core/src/serve/native-session.ts`:
-
-```ts
-import { McpServer, type RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp";
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport";
-import { version as packageJsonVersion } from "../../package.json";
-import type { NativeCapletsService, NativeCapletTool } from "../native/service";
-
-export type NativeToolServer = Pick<McpServer, "registerTool" | "connect" | "close">;
-
-export type NativeCapletsMcpSessionOptions = {
-  server?: NativeToolServer;
-};
-
-export class NativeCapletsMcpSession {
-  readonly server: NativeToolServer;
-  private readonly tools = new Map<string, RegisteredTool>();
-  private readonly unsubscribe: () => void;
-  private closed = false;
-
-  constructor(
-    private readonly service: NativeCapletsService,
-    options: NativeCapletsMcpSessionOptions = {},
-  ) {
-    this.server =
-      options.server ??
-      new McpServer({
-        name: "caplets",
-        version: packageJsonVersion,
-      });
-    this.unsubscribe = service.onToolsChanged((tools) => this.reconcileTools(tools));
-    this.reconcileTools(service.listTools());
-  }
-
-  async connect(transport: Transport): Promise<void> {
-    await this.server.connect(transport);
-  }
-
-  async close(): Promise<void> {
-    if (this.closed) return;
-    this.closed = true;
-    this.unsubscribe();
-    this.tools.clear();
-    await this.server.close();
-    await this.service.close();
-  }
-
-  private reconcileTools(next: NativeCapletTool[]): void {
-    const enabled = new Map(next.map((tool) => [tool.caplet, tool]));
-    for (const [id, registered] of this.tools) {
-      const tool = enabled.get(id);
-      if (!tool) {
-        registered.remove();
-        this.tools.delete(id);
-        continue;
-      }
-      registered.update(this.definition(tool));
-    }
-    for (const tool of enabled.values()) {
-      if (!this.tools.has(tool.caplet)) {
-        this.tools.set(
-          tool.caplet,
-          this.server.registerTool(tool.caplet, this.definition(tool), async (request) =>
-            this.service.execute(tool.caplet, request),
-          ),
-        );
-      }
-    }
-  }
-
-  private definition(tool: NativeCapletTool) {
-    return {
-      title: tool.title,
-      description: tool.description,
-      inputSchema: tool.inputSchema,
-    };
-  }
-}
-```
-
-During implementation, verify the installed MCP SDK overload. If `registerTool` requires Zod `paramsSchema` instead of raw JSON Schema, convert missing or raw schemas through the existing generated Caplets schema for remote tools and document the lossless raw schema follow-up in the commit body.
-
-- [ ] **Step 4: Export the session**
-
-In `packages/core/src/serve/index.ts`, export:
-
-```ts
-export { NativeCapletsMcpSession } from "./native-session";
-export type { NativeCapletsMcpSessionOptions, NativeToolServer } from "./native-session";
-```
-
-- [ ] **Step 5: Run session tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/attach-server.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add packages/core/src/serve/native-session.ts packages/core/src/serve/index.ts packages/core/test/attach-server.test.ts
-git commit -m "feat(core): expose native caplets over mcp"
-```
-
----
-
-## Task 4: `caplets attach` MCP Server
-
-**Files:**
-
-- Add: `packages/core/src/attach/options.ts`
-- Add: `packages/core/src/attach/server.ts`
-- Modify: `packages/core/src/cli.ts`
-- Modify: `packages/core/test/attach-cli.test.ts`
-- Modify: `packages/core/test/attach-server.test.ts`
-
-- [ ] **Step 1: Add failing CLI contract tests**
-
-In `packages/core/test/attach-cli.test.ts`, update help expectations:
-
-```ts
-expect(out.join("")).toContain("Start a remote-backed Caplets MCP server.");
-expect(out.join("")).toContain("--transport <transport>");
-expect(out.join("")).toContain("--once");
-```
-
-Add tests:
-
-```ts
-it("runs attach as a stdio MCP server by default", async () => {
-  const served: unknown[] = [];
-  await runCli(["attach"], {
-    env: {
-      CAPLETS_MODE: "remote",
-      CAPLETS_REMOTE_URL: "https://caplets.example.com/caplets",
-    },
-    attachServe: async (options) => {
-      served.push(options);
-    },
-  } as never);
-
-  expect(served).toHaveLength(1);
-  expect(served[0]).toMatchObject({
-    transport: "stdio",
-    selection: { kind: "self_hosted_remote" },
-  });
-});
-
-it("rejects attach server in local mode", async () => {
-  await expect(
-    runCli(["attach"], {
-      env: { CAPLETS_MODE: "local" },
-      attachServe: async () => undefined,
-    } as never),
-  ).rejects.toThrow(/use caplets serve for local-only MCP/u);
-});
-
-it("keeps attach --once as the finite Project Binding smoke path", async () => {
-  const out: string[] = [];
-  await runCli(["attach", "--once", "--remote-url", "https://caplets.example.com/caplets"], {
-    fetch: async () => Response.json({ error: "websocket_upgrade_required" }, { status: 426 }),
-    writeOut: (value) => out.push(value),
-  });
-  expect(out.join("")).toContain("Project Binding available at");
-});
-```
-
-The `attachServe` seam is intentionally test-only and mirrors the existing `serve` seam.
-
-- [ ] **Step 2: Run attach CLI tests to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/attach-cli.test.ts
-```
-
-Expected: FAIL because `attach` does not accept `--transport` and defaults to Project Binding session behavior.
-
-- [ ] **Step 3: Implement attach option resolution**
-
-Create `packages/core/src/attach/options.ts`:
-
-```ts
-import { resolveServeOptions, type RawServeOptions, type ServeOptions } from "../serve/options";
-import {
-  resolveRemoteSelection,
-  type RemoteSelectionInput,
-  type ResolvedRemoteSelection,
-} from "../remote/selection";
-
-export type RawAttachServeOptions = RemoteSelectionInput &
-  RawServeOptions & {
-    projectRoot?: string;
-  };
-
-export type AttachServeOptions = ServeOptions & {
-  projectRoot: string;
-  selection: ResolvedRemoteSelection;
-};
-
-export async function resolveAttachServeOptions(
-  raw: RawAttachServeOptions = {},
-  env: Record<string, string | undefined> = process.env,
-): Promise<AttachServeOptions> {
-  const selection = await resolveRemoteSelection(raw, env);
-  const serve = resolveServeOptions(raw, env);
-  return {
-    ...serve,
-    projectRoot: raw.projectRoot ?? process.cwd(),
-    selection,
-  };
-}
-```
-
-- [ ] **Step 4: Implement attach server lifecycle**
-
-Create `packages/core/src/attach/server.ts`:
-
-```ts
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
-import { createNativeCapletsService } from "../native/service";
-import { NativeCapletsMcpSession } from "../serve/native-session";
-import { serveHttpWithSessionFactory } from "../serve/http";
-import type { AttachServeOptions } from "./options";
-
-export type AttachServeIo = {
-  writeErr?: (value: string) => void;
-};
-
-export async function attachResolvedCaplets(
-  options: AttachServeOptions,
-  io: AttachServeIo = {},
-): Promise<void> {
-  const service = createNativeCapletsService({
-    mode: options.selection.kind === "hosted_cloud" ? "cloud" : "remote",
-    server: {
-      url: options.selection.remote.baseUrl.toString(),
-      fetch: options.selection.remote.fetch,
-    },
-    remote: {
-      fetch: options.selection.remote.fetch,
-      cloud:
-        options.selection.kind === "hosted_cloud"
-          ? {
-              url: options.selection.cloudPresence.url.toString(),
-              accessToken: options.selection.cloudPresence.accessToken,
-              workspaceId: options.selection.cloudPresence.workspaceId,
-              projectRoot: options.projectRoot,
-            }
-          : undefined,
-    },
-    ...(io.writeErr ? { writeErr: io.writeErr } : {}),
-  });
-  await service.reload();
-
-  if (options.transport === "stdio") {
-    const session = new NativeCapletsMcpSession(service);
-    await session.connect(new StdioServerTransport());
-    return;
-  }
-
-  await serveHttpWithSessionFactory(
-    options,
-    () => new NativeCapletsMcpSession(service),
-    io.writeErr,
-  );
-}
-```
-
-During implementation, copy credentials and request headers from `selection.remote.requestInit` into the native remote client options. The snippet above shows the lifecycle shape; the final code must preserve Bearer and Basic Auth headers.
-
-- [ ] **Step 5: Extract HTTP session factory**
-
-In `packages/core/src/serve/http.ts`, extract the existing `createHttpSession(...)` path behind a function that can accept either:
-
-```ts
-type HttpMcpSessionFactory = () => {
-  connect(transport: StreamableHTTPTransport): Promise<void>;
-  close(): Promise<void>;
-};
-```
-
-Export:
-
-```ts
-export async function serveHttpWithSessionFactory(
-  options: HttpServeOptions,
-  createSession: HttpMcpSessionFactory,
-  writeErr?: (value: string) => void,
-): Promise<void>;
-```
-
-Keep `serveHttp(...)` behavior unchanged by calling the new helper with a factory that creates the existing local `CapletsMcpSession`.
-
-- [ ] **Step 6: Wire CLI default attach behavior**
-
-In `packages/core/src/cli.ts`:
-
-- Add `attachServe?: (options: AttachServeOptions) => Promise<void>` to `CliIO`.
-- Add attach options `--transport`, `--host`, `--port`, `--path`, `--user`, `--password`, `--token`, `--allow-unauthenticated-http`, and `--trust-proxy`.
-- Keep `--once` on the existing `attachProjectOnce(...)` path.
-- For non-`--once`, call `resolveAttachServeOptions(...)`, then `io.attachServe ?? attachResolvedCaplets`.
-- Change description to `Start a remote-backed Caplets MCP server.`
-
-- [ ] **Step 7: Run attach tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/attach-cli.test.ts test/attach-server.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add packages/core/src/attach/options.ts packages/core/src/attach/server.ts packages/core/src/serve/http.ts packages/core/src/cli.ts packages/core/test/attach-cli.test.ts packages/core/test/attach-server.test.ts
-git commit -m "feat(core): serve remote mcp with attach"
-```
-
----
-
-## Task 5: Native Integration Cloud Mode
-
-**Files:**
-
-- Modify: `packages/core/src/native/options.ts`
-- Modify: `packages/core/src/native/service.ts`
-- Modify: `packages/core/src/native/remote.ts`
-- Modify: `packages/core/src/native.ts`
-- Modify: `packages/core/test/native-options.test.ts`
-- Modify: `packages/core/test/native-remote.test.ts`
-
-- [ ] **Step 1: Add failing native option tests**
-
-Append to `packages/core/test/native-options.test.ts`:
-
-```ts
-it("uses cloud mode in auto when CAPLETS_REMOTE_URL points at Caplets Cloud", () => {
-  expect(
-    resolveNativeCapletsServiceOptions(
-      {},
-      {
-        CAPLETS_REMOTE_URL: "https://cloud.caplets.dev",
-      },
-    ),
-  ).toMatchObject({
-    mode: "cloud",
-    remote: {
-      url: new URL("https://cloud.caplets.dev/mcp"),
-    },
-  });
-});
-
-it("uses cloud mode when CAPLETS_MODE=cloud is explicit", () => {
-  expect(
-    resolveNativeCapletsServiceOptions(
-      {},
-      {
-        CAPLETS_MODE: "cloud",
-        CAPLETS_REMOTE_URL: "https://cloud.caplets.dev",
-      },
-    ),
-  ).toMatchObject({ mode: "cloud" });
-});
-
-it("rejects CAPLETS_MODE=cloud with a self-hosted remote URL", () => {
-  expect(() =>
-    resolveNativeCapletsServiceOptions(
-      {},
-      {
-        CAPLETS_MODE: "cloud",
-        CAPLETS_REMOTE_URL: "https://caplets.example.com/caplets",
-      },
-    ),
-  ).toThrow(/Caplets Cloud/u);
-});
-```
-
-- [ ] **Step 2: Add failing native Cloud service tests**
-
-Append to `packages/core/test/native-remote.test.ts`:
-
-```ts
-it("starts Cloud Project Binding when native service runs in cloud mode", async () => {
-  const path = tempCloudAuthPath();
-  await new CloudAuthStore({ path }).save(hostedCredentials({ accessToken: "cloud-access" }));
-  const factory = vi.fn(() => client([{ name: "remote", description: "Remote" }]).api);
-
-  const service = createNativeCapletsService({
-    mode: "cloud",
-    server: { url: "https://cloud.caplets.dev" },
-    remoteClientFactory: factory,
-    projectConfigPath: tempProjectConfigWithTool("local"),
-  } as never);
-
-  await service.reload();
-  expect(service.listTools().map((tool) => tool.caplet)).toContain("remote");
-  await service.close();
-});
-```
-
-Use existing test helpers in this file for local overlay config, or add a small helper that writes `.caplets/config.json` into a temp directory and returns the path.
-
-- [ ] **Step 3: Run native tests to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/native-options.test.ts test/native-remote.test.ts
-```
-
-Expected: FAIL because native mode only supports `local | remote`.
-
-- [ ] **Step 4: Update native option types**
-
-In `packages/core/src/native/options.ts`:
-
-- Change `type CapletsMode = "auto" | "local" | "remote";` to include `"cloud"`.
-- Let `ResolvedNativeCapletsServiceOptions` use `mode: "remote" | "cloud"` for remote-backed services.
-- Call `resolveRemoteMode(...)` from Task 1.
-- For Cloud mode, return the MCP URL and request headers needed for Cloud Auth resolution but do not require `CAPLETS_CLOUD_TOKEN` env vars.
-
-The final union should be:
-
-```ts
-export type ResolvedNativeCapletsServiceOptions =
-  | { mode: "local" }
-  | {
-      mode: "remote" | "cloud";
-      remote: {
-        url: URL;
-        auth: NativeRemoteAuthOptions;
-        pollIntervalMs: number;
-        requestInit: RequestInit;
-        cloud?: ResolvedNativeCloudPresenceOptions;
-        fetch?: typeof fetch;
-      };
-    };
-```
-
-- [ ] **Step 5: Load saved Cloud Auth for native Cloud mode**
-
-In `packages/core/src/native/service.ts`, update `createNativeCapletsService(...)`:
-
-- Treat `resolved.mode === "cloud"` the same as remote-backed for composition.
-- Before creating the SDK remote client, use the shared selection helper or a native equivalent to load saved Cloud Auth credentials.
-- Populate `resolved.remote.requestInit` with `Authorization: Bearer <cloud access token>`.
-- Populate `resolved.remote.cloud` with Cloud Project Binding presence options.
-- Preserve existing behavior where explicit self-hosted remote mode fails hard, while auto Cloud fallback can warn and return local only when the remote setup cannot initialize.
-
-Keep local overlay precedence unchanged:
-
-```ts
-const localIds = new Set(localTools.map((tool) => tool.caplet));
-return [...remoteTools.filter((tool) => !localIds.has(tool.caplet)), ...localTools];
-```
-
-- [ ] **Step 6: Update remote auth error copy**
-
-In `packages/core/src/native/remote.ts`, make `remoteAuthError(...)` accept an auth kind:
-
-```ts
-function remoteAuthError(kind: "self_hosted_remote" | "hosted_cloud"): CapletsError {
-  return new CapletsError(
-    "AUTH_FAILED",
-    kind === "hosted_cloud"
-      ? "Caplets Cloud authentication failed; run caplets cloud auth login."
-      : "Remote Caplets authentication failed; check CAPLETS_REMOTE_TOKEN or CAPLETS_REMOTE_USER and CAPLETS_REMOTE_PASSWORD.",
-  );
-}
-```
-
-Thread the kind from native service creation into `RemoteNativeCapletsService`.
-
-- [ ] **Step 7: Run native tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/native-options.test.ts test/native-remote.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add packages/core/src/native/options.ts packages/core/src/native/service.ts packages/core/src/native/remote.ts packages/core/src/native.ts packages/core/test/native-options.test.ts packages/core/test/native-remote.test.ts
-git commit -m "feat(core): drive native integrations from cloud mode"
-```
-
----
-
-## Task 6: OpenCode And Pi Docs/Config Validation
-
-**Files:**
-
-- Modify: `packages/opencode/src/index.ts`
-- Modify: `packages/opencode/test/opencode.test.ts`
-- Modify: `packages/opencode/README.md`
-- Modify: `packages/pi/src/index.ts`
-- Modify: `packages/pi/test/pi.test.ts`
-- Modify: `packages/pi/README.md`
-- Modify: `docs/native-integrations.md`
-
-- [ ] **Step 1: Add integration config tests**
-
-In `packages/opencode/test/opencode.test.ts`, add:
-
-```ts
-it("passes cloud mode config into the native service", async () => {
-  vi.resetModules();
-  const nativeMocks = {
-    createNativeCapletsService: vi.fn(() => ({
-      listTools: () => [],
-      execute: vi.fn(async () => ({})),
-      reload: vi.fn(async () => true),
-      onToolsChanged: vi.fn(() => () => {}),
-      close: vi.fn(async () => {}),
-    })),
-    registerNativeCapletsProcessCleanup: vi.fn(),
-  };
-  vi.doMock("@caplets/core/native", () => nativeMocks);
-  const plugin = (await import("../src/index")).default;
-
-  await plugin(
-    {} as never,
-    { mode: "cloud", server: { url: "https://cloud.caplets.dev" } } as never,
-  );
-
-  expect(nativeMocks.createNativeCapletsService).toHaveBeenCalledWith({
-    mode: "cloud",
-    server: { url: "https://cloud.caplets.dev" },
-  });
-});
-```
-
-In `packages/pi/test/pi.test.ts`, add a settings extraction case:
-
-```ts
-it("loads cloud mode from Pi settings", async () => {
-  fsMocks.readFile.mockImplementation(async (path: string) =>
-    path.includes(".pi/agent/settings.json")
-      ? JSON.stringify({ caplets: { mode: "cloud", server: { url: "https://cloud.caplets.dev" } } })
-      : Promise.reject(Object.assign(new Error("missing"), { code: "ENOENT" })),
-  );
-
-  await capletsPiExtension(mockPiApi());
-
-  expect(nativeMocks.createNativeCapletsService).toHaveBeenCalledWith(
-    expect.objectContaining({
-      mode: "cloud",
-      server: { url: "https://cloud.caplets.dev" },
-    }),
-  );
-});
-```
-
-- [ ] **Step 2: Run package tests to verify red or confirm no code change needed**
-
-Run:
-
-```bash
-pnpm --filter @caplets/opencode test
-pnpm --filter @caplets/pi test
-```
-
-Expected: PASS if existing config plumbing already accepts `"cloud"` after Task 5 type changes; otherwise FAIL on narrow type validation and fix in Step 3.
-
-- [ ] **Step 3: Confirm config types accept cloud mode**
-
-In `packages/opencode/src/index.ts` and `packages/pi/src/index.ts`, keep the current config shape but ensure the imported `NativeCapletsServiceOptions` type includes `mode: "cloud"` after Task 5:
-
-```ts
-export type CapletsOpenCodeConfig = Pick<NativeCapletsServiceOptions, "mode" | "server" | "remote">;
-type PiNativeCapletsOptions = Pick<NativeCapletsServiceOptions, "mode" | "server" | "remote">;
-```
-
-No runtime special case should be added for Cloud.
-
-- [ ] **Step 4: Update native integration docs**
-
-In `docs/native-integrations.md`, add this contract:
-
-```md
-## Remote Selection
-
-OpenCode and Pi use the same resolver as `caplets attach`.
-
-- `CAPLETS_MODE=local` exposes local/user/project Caplets only.
-- `CAPLETS_MODE=remote` requires `CAPLETS_REMOTE_URL` and connects to a self-hosted Caplets service.
-- `CAPLETS_MODE=cloud` requires `CAPLETS_REMOTE_URL` pointing at Caplets Cloud and uses saved `caplets cloud auth login` credentials.
-- `CAPLETS_MODE=auto` treats Cloud URLs as Cloud, non-Cloud remote URLs as self-hosted, and no remote URL as local.
-
-Cloud mode starts Project Binding automatically for the current project and overlays local/project Caplets over the remote workspace.
-```
-
-In both integration READMEs, include the three copyable env examples:
-
-```bash
-CAPLETS_MODE=local opencode
-CAPLETS_MODE=remote CAPLETS_REMOTE_URL=https://caplets.example.com/caplets opencode
-CAPLETS_MODE=cloud CAPLETS_REMOTE_URL=https://cloud.caplets.dev opencode
-```
-
-Use `pi` in the Pi README examples.
-
-- [ ] **Step 5: Run package tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/opencode test
-pnpm --filter @caplets/pi test
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add packages/opencode/src/index.ts packages/opencode/test/opencode.test.ts packages/opencode/README.md packages/pi/src/index.ts packages/pi/test/pi.test.ts packages/pi/README.md docs/native-integrations.md
-git commit -m "docs(core): document native cloud mode"
-```
-
----
-
-## Task 7: Remove Codex And Claude Plugin Artifacts
-
-**Files:**
-
-- Delete: `plugins/caplets/.codex-plugin/plugin.json`
-- Delete: `plugins/caplets/.claude-plugin/plugin.json`
-- Delete: `plugins/caplets/mcp.json`
-- Delete: `plugins/caplets/skills/caplets/SKILL.md`
-- Delete: `plugins/caplets/assets/icon.png` or move it to a non-plugin asset path if still referenced
-- Delete: `.agents/plugins/marketplace.json`
-- Delete: `.claude-plugin/marketplace.json`
-- Delete: `scripts/sync-plugin-versions.ts`
-- Modify: `package.json`
-- Modify: `packages/core/test/agent-plugins.test.ts`
-
-- [ ] **Step 1: Invert plugin artifact tests**
-
-Replace `packages/core/test/agent-plugins.test.ts` with contract tests that assert absence:
-
-```ts
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { describe, expect, it } from "vitest";
-
-const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
-
-describe("Codex and Claude manual MCP setup", () => {
-  it("does not ship native Codex or Claude plugin artifacts", () => {
-    for (const removedPath of [
-      "plugins/caplets",
-      ".agents/plugins/marketplace.json",
-      ".claude-plugin/marketplace.json",
-      "scripts/sync-plugin-versions.ts",
-    ]) {
-      expect(existsSync(path.join(repoRoot, removedPath)), removedPath).toBe(false);
-    }
-  });
-
-  it("documents manual MCP config for Codex and Claude users", async () => {
-    const readme = await readFile(path.join(repoRoot, "README.md"), "utf8");
-    expect(readme).toContain('"command": "caplets"');
-    expect(readme).toContain('"args": ["serve"]');
-    expect(readme).toContain('"args": ["attach"]');
-    expect(readme).not.toMatch(/plugin marketplace add|plugin install caplets@caplets/u);
-  });
-
-  it("does not keep version-package plugin sync wiring", async () => {
-    const packageJson = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf8")) as {
-      scripts: Record<string, string>;
-    };
-    expect(packageJson.scripts["version-packages"] ?? "").not.toContain("sync-plugin-versions");
-  });
-});
-```
-
-- [ ] **Step 2: Run plugin tests to verify red**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/agent-plugins.test.ts
-```
-
-Expected: FAIL because plugin artifacts still exist and README still references plugin install flows.
-
-- [ ] **Step 3: Delete plugin artifacts**
-
-Delete these paths:
-
-```bash
-git rm -r plugins/caplets .agents/plugins/marketplace.json .claude-plugin/marketplace.json scripts/sync-plugin-versions.ts
-```
-
-If `git rm -r plugins/caplets` fails because the icon is referenced by `README.md`, move the image first:
-
-```bash
-mkdir -p docs/assets
-git mv plugins/caplets/assets/icon.png docs/assets/caplets-icon.png
-git rm -r plugins/caplets .agents/plugins/marketplace.json .claude-plugin/marketplace.json scripts/sync-plugin-versions.ts
-```
-
-Then update the README image path from `plugins/caplets/assets/icon.png` to `docs/assets/caplets-icon.png`.
-
-- [ ] **Step 4: Remove version sync wiring**
-
-In `package.json`, remove `scripts/sync-plugin-versions.ts` from the `version-packages` script. The final script must still run Changesets and formatting for remaining generated files:
-
-```json
-"version-packages": "changeset version && oxlint --fix --quiet && oxfmt --write ."
-```
-
-If the current script has additional non-plugin commands, preserve them and remove only the plugin sync command.
-
-- [ ] **Step 5: Run plugin tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/agent-plugins.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add package.json packages/core/test/agent-plugins.test.ts README.md docs/assets/caplets-icon.png
-git add -u plugins .agents .claude-plugin scripts
-git commit -m "refactor(core): remove codex and claude plugins"
-```
-
----
-
-## Task 8: Manual MCP Documentation
-
-**Files:**
-
-- Modify: `README.md`
-- Modify: `packages/cli/README.md`
-- Modify: `packages/core/test/agent-plugins.test.ts`
-
-- [ ] **Step 1: Add docs contract assertions**
-
-Extend `packages/core/test/agent-plugins.test.ts`:
-
-```ts
-it("documents serve for local MCP and attach for remote MCP", async () => {
-  const readme = await readFile(path.join(repoRoot, "README.md"), "utf8");
-  expect(readme).toContain("caplets serve");
-  expect(readme).toContain("caplets attach");
-  expect(readme).toContain("CAPLETS_MODE=cloud");
-  expect(readme).toContain("CAPLETS_REMOTE_URL=https://cloud.caplets.dev");
-  expect(readme).toContain("CAPLETS_MODE=remote");
-});
-```
-
-- [ ] **Step 2: Update top-level Core README integration table**
-
-In `README.md`, replace the existing agent integration table rows for Claude and Codex with:
-
-```md
-| Codex | Add `caplets serve` or `caplets attach` manually in MCP config | Local or remote/Cloud progressive-disclosure gateway |
-| Claude Code | Add `caplets serve` or `caplets attach` manually in MCP config | Local or remote/Cloud progressive-disclosure gateway |
-```
-
-Add the manual MCP examples exactly:
-
-```json
-{
-  "mcpServers": {
-    "caplets": {
-      "command": "caplets",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-```json
-{
-  "mcpServers": {
-    "caplets": {
-      "command": "caplets",
-      "args": ["attach"]
-    }
-  }
-}
-```
-
-Add Cloud env setup:
-
-```bash
-caplets cloud auth login
-export CAPLETS_MODE=cloud
-export CAPLETS_REMOTE_URL=https://cloud.caplets.dev
-```
-
-Add self-hosted env setup:
-
-```bash
-export CAPLETS_MODE=remote
-export CAPLETS_REMOTE_URL=https://caplets.example.com/caplets
-export CAPLETS_REMOTE_TOKEN=...
-```
-
-- [ ] **Step 3: Update CLI README**
-
-If `packages/cli/README.md` exists and references plugin installs, replace those paragraphs with the same manual MCP examples from Step 2. If it does not contain plugin guidance, add a short `Manual MCP setup` section with the two JSON examples.
-
-- [ ] **Step 4: Run docs contract tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/agent-plugins.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add README.md packages/cli/README.md packages/core/test/agent-plugins.test.ts
-git commit -m "docs(core): prefer manual mcp setup"
-```
-
----
-
-## Task 9: CLI Error Handling And Regression Matrix
-
-**Files:**
-
-- Modify: `packages/core/test/attach-cli.test.ts`
-- Modify: `packages/core/test/remote-options.test.ts`
-- Modify: `packages/core/test/native-options.test.ts`
-- Modify: `packages/core/src/cli.ts`
-- Modify: `packages/core/src/remote/selection.ts`
-
-- [ ] **Step 1: Add explicit error tests**
-
-Add these cases across the listed test files:
-
-```ts
-it("prints JSON error for attach --once when cloud auth is missing", async () => {
-  const out: string[] = [];
-  let exitCode = 0;
-  await runCli(["attach", "--once", "--json"], {
-    env: {
-      CAPLETS_MODE: "cloud",
-      CAPLETS_REMOTE_URL: "https://cloud.caplets.dev",
-    },
-    writeOut: (value) => out.push(value),
-    setExitCode: (code) => {
-      exitCode = code;
-    },
-  });
-
-  expect(exitCode).toBe(1);
-  expect(JSON.parse(out.join(""))).toMatchObject({
-    error: {
-      code: "cloud_auth_required",
-      recoveryCommand: "caplets cloud auth login",
-    },
-  });
-});
-
-it("references CAPLETS_REMOTE_TOKEN or Basic Auth vars for self-hosted auth failures", async () => {
-  await expect(
-    resolveCapletsRemote(
-      { user: "caplets" },
-      { CAPLETS_REMOTE_URL: "https://caplets.example.com/caplets" },
-    ),
-  ).toThrow(/CAPLETS_REMOTE_PASSWORD/u);
-});
-```
-
-- [ ] **Step 2: Run focused regression tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/attach-cli.test.ts test/remote-options.test.ts test/native-options.test.ts
-```
-
-Expected: FAIL for any missing structured error handling.
-
-- [ ] **Step 3: Normalize errors**
-
-In `packages/core/src/remote/selection.ts`, throw `CapletsError` or `ProjectBindingError` for every user-facing failure:
-
-- local mode for attach: `REQUEST_INVALID`
-- missing remote URL for attach: `REQUEST_INVALID`
-- missing Cloud Auth: existing `projectBindingError("cloud_auth_required")`
-- workspace mismatch: existing `projectBindingError("workspace_switch_required")`
-- Cloud URL mismatch: `REQUEST_INVALID`
-
-In `packages/core/src/cli.ts`, ensure the `--once --json` handler serializes these errors consistently with the existing Project Binding JSON branch.
-
-- [ ] **Step 4: Run regression tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/attach-cli.test.ts test/remote-options.test.ts test/native-options.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add packages/core/src/cli.ts packages/core/src/remote/selection.ts packages/core/test/attach-cli.test.ts packages/core/test/remote-options.test.ts packages/core/test/native-options.test.ts
-git commit -m "fix(core): clarify attach remote errors"
-```
-
----
-
-## Task 10: Changeset And Full Verification
-
-**Files:**
-
-- Add: `.changeset/<generated-name>.md`
-- Modify: any generated schema or docs files changed by package scripts
-
-- [ ] **Step 1: Add Changesets entry**
-
-Create a changeset:
-
-```bash
-pnpm changeset
-```
-
-Use this content:
-
-```md
----
-"@caplets/core": minor
-"caplets": minor
-"@caplets/opencode": minor
-"@caplets/pi": minor
----
-
-Make `caplets attach` the remote-backed MCP server command, add Cloud-aware `CAPLETS_MODE` resolution, keep OpenCode and Pi on the shared resolver, and remove Codex/Claude plugin artifacts in favor of manual MCP configuration.
-```
-
-- [ ] **Step 2: Run formatting**
-
-Run:
-
-```bash
-pnpm format:check
-```
-
-Expected: PASS. If it fails only on changed files, run `pnpm format` and re-run `pnpm format:check`.
-
-- [ ] **Step 3: Run Core focused tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/core test -- test/remote-options.test.ts test/remote-selection.test.ts test/attach-cli.test.ts test/attach-server.test.ts test/cloud-auth-refresh-attach.test.ts test/native-options.test.ts test/native-remote.test.ts test/agent-plugins.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 4: Run integration package tests**
-
-Run:
-
-```bash
-pnpm --filter @caplets/opencode test
-pnpm --filter @caplets/pi test
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Run Core verification**
-
-Run:
-
-```bash
-pnpm core:verify
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Run root coordination verification**
-
-Run:
-
-```bash
-pnpm verify
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Manual smoke commands**
-
-Build first:
-
-```bash
-pnpm core:build
-```
-
-Smoke local serve help:
-
-```bash
-node core/packages/cli/dist/index.js serve --help
-```
-
-Expected output includes `Serve configured Caplets as an MCP server.` and does not mention Cloud Auth.
-
-Smoke attach help:
-
-```bash
-node core/packages/cli/dist/index.js attach --help
-```
-
-Expected output includes `Start a remote-backed Caplets MCP server.`, `--transport <transport>`, `--once`, and `--remote-url <url>`.
-
-Smoke local-mode attach rejection:
-
-```bash
-CAPLETS_MODE=local node core/packages/cli/dist/index.js attach --transport stdio
-```
-
-Expected: exits non-zero with `use caplets serve for local-only MCP`.
-
-- [ ] **Step 8: Final commit**
-
-```bash
-git add .
-git commit -m "chore(core): verify remote attach integration"
-```
-
-If every previous task already committed all files and the working tree is clean, skip the final commit and record the verification commands in the final response.
-
----
-
-## Self-Review Checklist
-
-- [ ] `caplets serve` remains local-only for stdio and HTTP and does not consult Cloud Auth.
-- [ ] `caplets attach` starts an MCP server by default and supports stdio and HTTP transports.
-- [ ] `caplets attach --once` remains a finite Project Binding smoke path.
-- [ ] `CAPLETS_MODE=local` rejects attach and points users to `caplets serve`.
-- [ ] `CAPLETS_MODE=remote` requires `CAPLETS_REMOTE_URL` and uses self-hosted token or Basic Auth.
-- [ ] `CAPLETS_MODE=cloud` requires a Cloud URL and saved `caplets cloud auth login` credentials.
-- [ ] `CAPLETS_MODE=auto` detects Cloud from `CAPLETS_REMOTE_URL`, detects self-hosted remotes from non-Cloud URLs, and falls back to local only for native integrations with no remote URL.
-- [ ] Cloud mode ignores self-hosted `CAPLETS_REMOTE_TOKEN` and uses saved Cloud Auth.
-- [ ] Cloud mode refreshes expired saved credentials before attach/native remote use.
-- [ ] Cloud mode starts Project Binding automatically and preserves local/project overlay precedence.
-- [ ] OpenCode and Pi remain installed native integrations and require no Cloud-specific plugin manifest.
-- [ ] Codex and Claude plugin marketplace metadata, bundled MCP config, and shared plugin skill are removed.
-- [ ] Codex and Claude docs show manual MCP config for both `serve` and `attach`.
-- [ ] Focused tests, package tests, `pnpm core:verify`, and root `pnpm verify` pass.
diff --git a/docs/plans/2026-06-09-executor-pi-eval-competitor.md b/docs/plans/2026-06-09-executor-pi-eval-competitor.md
deleted file mode 100644
index 1d4f794e..00000000
--- a/docs/plans/2026-06-09-executor-pi-eval-competitor.md
+++ /dev/null
@@ -1,660 +0,0 @@
-# Executor Pi Eval Competitor Integration Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add Executor (`https://executor.sh`, npm package/binary `executor`) as a first-class competitor in the opt-in `@caplets/benchmarks` Pi live tool-surface eval, so we can compare Caplets modes against Executor using the same Pi agent, same benchmark task, same fixture tools, same scoring, and comparable token/tool-call metrics.
-
-**Primary comparison:** `executor-mcp` vs Caplets' strongest current modes, especially `caplets-code-mode` and `caplets-progressive-code-mode`.
-
-**Recommendation:** Implement the first version as an **Executor MCP gateway mode inside the existing Pi eval harness**, not as a separate benchmark runner. Executor itself is exposed to Pi through MCP (`executor mcp`), and Executor can ingest our existing benchmark fixture MCP servers. Because Pi does not natively support MCP, the Executor mode should load the `npm:pi-mcp-adapter` Pi extension as the MCP bridge and use the adapter's `directTools` exposure. This gives the fairest direct-tool product comparison: Pi + Caplets native extension versus Pi + `pi-mcp-adapter` direct Executor tools backed by the Executor MCP endpoint.
-
-**Tech Stack:** TypeScript, Commander, Vitest, Pi live eval harness, existing benchmark MCP fixture server, Executor CLI/MCP, `pnpm` checks.
-
----
-
-## Current Harness Findings
-
-The existing Pi eval harness lives under:
-
-- `packages/benchmarks/run-pi-eval.ts`
-- `packages/benchmarks/lib/pi-eval/config.ts`
-- `packages/benchmarks/lib/pi-eval/metrics.ts`
-- `packages/benchmarks/lib/pi-eval/report.ts`
-- tests in `packages/benchmarks/test/benchmark.test.ts`
-
-Current modes are:
-
-```ts
-export const PI_EVAL_MODES = [
-  "caplets-direct",
-  "caplets-progressive",
-  "caplets-code-mode",
-  "caplets-progressive-code-mode",
-] as const;
-```
-
-Current run setup:
-
-1. Creates isolated run dirs.
-2. Copies benchmark fixture MCP server into `support/mcp-server.ts`.
-3. Writes a Caplets config exposing `issues`, `ci`, `docs`, `api`, and `code-map` fixture servers.
-4. Runs Pi in JSON mode with:
-   - instrumentation extension
-   - Caplets Pi extension
-   - isolated `PI_CODING_AGENT_DIR`
-   - isolated session dir
-   - `CAPLETS_CONFIG`
-5. Scores the edited candidate workspace with visible and hidden validation.
-6. Requires external evidence coverage for `checkout-incident-retry-hardening`: issues, ci, docs, api.
-7. Summarizes token estimates, tool surface estimates, round trips, tool calls, domain coverage, hybrid choice, pass rate, and failures.
-
-The harness already measures the exact outcomes we want for a competitor comparison, but the type/config model currently assumes every mode is a Caplets exposure mode.
-
----
-
-## Executor Findings
-
-Executor public docs and repository state show:
-
-- Install: `npm install -g executor`.
-- Local runtime/UI: `executor web`, default UI/API at `http://127.0.0.1:4788` / `http://localhost:4788`.
-- MCP endpoint for agents: `executor mcp`.
-- CLI can call tools and auto-start a daemon for some commands: `executor call`, `executor tools search`, `executor tools describe`.
-- Executor stores data under `EXECUTOR_DATA_DIR` or `~/.executor`.
-- Executor supports a scoped workspace via `EXECUTOR_SCOPE_DIR`; scope defaults are cwd-sensitive in CLI code.
-- Executor supports MCP sources. SDK docs show a source can be added with:
-
-```ts
-await executor.mcp.addSource({
-  scope,
-  transport: "stdio",
-  name: "My Server",
-  command: "npx",
-  args: ["-y", "@my/mcp-server"],
-});
-```
-
-- README shows CLI-based source add pattern, e.g.:
-
-```bash
-executor call executor openapi addSource '{...}'
-```
-
-The exact current CLI path/payload for adding MCP stdio sources needs a local smoke check against the installed Executor version, but the integration plan should isolate that variability behind a small setup helper.
-
----
-
-## Benchmark Semantics
-
-### What We Should Compare
-
-Compare agent-facing integration strategies, not raw MCP servers:
-
-| Mode                            | Agent sees                                                                       | Setup owner                           | Intended measurement                          |
-| ------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------- |
-| `caplets-direct`                | flattened native Caplets tools                                                   | Caplets Pi extension                  | direct tool-surface baseline                  |
-| `caplets-progressive`           | Caplets progressive native tools                                                 | Caplets Pi extension                  | capability-card discovery/tool-call overhead  |
-| `caplets-code-mode`             | `caplets__code_mode` native tool                                                 | Caplets Pi extension                  | one-call typed discovery/retrieval efficiency |
-| `caplets-progressive-code-mode` | progressive + Code Mode                                                          | Caplets Pi extension                  | best hybrid Caplets UX                        |
-| `executor-mcp`                  | Executor MCP tools exposed as direct Pi tools via `pi-mcp-adapter` `directTools` | Executor CLI/runtime + Pi MCP adapter | competitor direct-tool gateway behavior       |
-
-### What We Should Not Compare In V1
-
-Do not compare Caplets Code Mode against Executor's private SDK/runtime directly from a custom benchmark harness in V1. That would be a useful future benchmark, but it would not reflect Executor's documented agent entrypoint (`executor mcp`) as clearly.
-
-Do not mutate the user's real Executor data directory. Every live run should use an isolated `EXECUTOR_DATA_DIR` and `EXECUTOR_SCOPE_DIR` under the run root.
-
-Do not make Executor a dependency of deterministic benchmark checks. This remains opt-in live benchmark functionality only.
-
----
-
-## Architecture
-
-### 1. Split Pi eval modes into products
-
-Extend mode metadata from string-only mode handling to a typed product/mode descriptor.
-
-Suggested shape:
-
-```ts
-export const PI_EVAL_MODES = [
-  "caplets-direct",
-  "caplets-progressive",
-  "caplets-code-mode",
-  "caplets-progressive-code-mode",
-  "executor-mcp",
-] as const;
-
-export type PiEvalMode = (typeof PI_EVAL_MODES)[number];
-export type PiEvalProduct = "caplets" | "executor";
-
-export function piEvalModeProduct(mode: PiEvalMode): PiEvalProduct {
-  return mode === "executor-mcp" ? "executor" : "caplets";
-}
-```
-
-Keep `PI_EVAL_MODES` complete by default so the standard live run compares all supported modes, but add CLI filtering patterns so users can run:
-
-```bash
-CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:pi-eval -- --mode executor-mcp,caplets-code-mode
-```
-
-### 2. Add product-specific run config builders
-
-Replace the single `createPiEvalRunConfig({ mode })` path with a dispatcher:
-
-```ts
-export async function createPiEvalRunConfig(input) {
-  validatePiEvalMode(input.mode);
-  if (input.mode === "executor-mcp") return createExecutorPiEvalRunConfig(input);
-  return createCapletsPiEvalRunConfig(input);
-}
-```
-
-Keep Caplets behavior unchanged by moving the current body into `createCapletsPiEvalRunConfig`.
-
-Add a new `createExecutorPiEvalRunConfig` that:
-
-- creates the same `runRoot`, `supportDir`, `sessionsDir`, `agentDir`, and instrumentation paths;
-- copies the same Pi auth files (`auth.json`, `models.json`) into the isolated Pi agent dir;
-- copies the fixture server into `support/mcp-server.ts`;
-- creates isolated Executor paths:
-  - `executorDataDir = join(runRoot, "executor-data")`
-  - `executorScopeDir = join(runRoot, "executor-scope")`
-- registers the benchmark fixture servers as Executor MCP sources;
-- starts/uses Executor MCP for Pi;
-- returns a common public run config shape with product metadata.
-
-### 3. Configure Executor with the same fixture sources
-
-Executor must ingest the same five fixture MCP servers used by Caplets:
-
-- `issues`
-- `ci`
-- `docs`
-- `api`
-- `code-map`
-
-Each source should launch the fixture server as stdio:
-
-```json
-{
-  "transport": "stdio",
-  "name": "issues",
-  "command": "tsx",
-  "args": ["/path/to/support/mcp-server.ts", "--server", "issues"]
-}
-```
-
-There are two practical implementation choices. Prefer A if the installed Executor CLI supports it reliably; otherwise use B.
-
-#### Option A: Configure via Executor CLI
-
-Use the documented CLI pattern:
-
-```bash
-executor call executor mcp addSource '{...}'
-```
-
-or the actual discovered path if current Executor exposes it differently. Encapsulate this in `addExecutorMcpSource()` so CLI path changes are localized.
-
-Pros:
-
-- Tests the product like a user would configure it.
-- No direct dependency on Executor SDK internals.
-
-Cons:
-
-- Requires smoke-discovering exact CLI tool path and payload.
-- CLI output and daemon autostart behavior may change.
-
-#### Option B: Configure by a generated setup script using Executor SDK/runtime
-
-Generate a small temporary setup script under the run root and execute it with the installed `executor` package's API or CLI runtime.
-
-Pros:
-
-- More deterministic setup if CLI add paths are unstable.
-
-Cons:
-
-- More coupled to Executor internals.
-- Less representative of documented user setup.
-
-### 4. Expose Executor to Pi through `pi-mcp-adapter`
-
-Pi does not natively support MCP. The Executor mode should therefore load the `npm:pi-mcp-adapter` Pi extension and configure that adapter to connect to Executor's MCP server.
-
-Concrete adapter contract from `pi-mcp-adapter@2.9.0`:
-
-- Pi extension install/load source: `npm:pi-mcp-adapter`; package manifest declares `pi.extensions: ["./index.ts"]`.
-- Runtime config override flag: `--mcp-config <path>`; the extension registers `mcp-config` and calls `loadMcpConfig(pi.getFlag("mcp-config"), ctx.cwd)`.
-- Default Pi-owned global config path without the flag: `$PI_CODING_AGENT_DIR/mcp.json`, falling back to `~/.pi/agent/mcp.json`.
-- Config lookup/merge order when using an override path is: `~/.config/mcp/mcp.json`, override/pi-global config, cwd `.mcp.json`, cwd `.pi/mcp.json`. Later sources override earlier servers/settings.
-- Config schema root: `{ "settings"?: {...}, "mcpServers": { [name]: ServerEntry }, "imports"?: [...] }`.
-- Stdio server fields: `command`, `args`, `env`, `cwd`, `lifecycle`, `idleTimeout`, `directTools`, `excludeTools`, `debug`, `exposeResources`.
-- HTTP server fields also exist (`url`, `headers`, `auth`, bearer/OAuth fields), but Executor should use stdio for the benchmark: `command: "executor", args: ["mcp"]`.
-- Tool exposure defaults to a single proxy tool named `mcp`; direct tools are registered when `settings.directTools`, per-server `directTools`, or `MCP_DIRECT_TOOLS` requests them.
-- `MCP_DIRECT_TOOLS=executor` requests all direct tools from the `executor` server.
-- Direct tools are resolved from the adapter metadata cache (`mcp-cache.json`) during extension module load. If the cache is missing or invalid, the adapter can bootstrap metadata during `session_start`, but those tools are not registered until a subsequent Pi process.
-- `disableProxyTool: true` removes the `mcp` proxy only when direct specs exist and no configured direct-tool server is missing from cache. This is why the measured benchmark run needs prewarmed metadata.
-
-Use the least invasive path:
-
-1. Create an isolated Pi agent dir (`PI_CODING_AGENT_DIR`) as the harness already does.
-2. Keep the instrumentation extension enabled for metrics.
-3. Add `npm:pi-mcp-adapter` to `extensionPaths` for `executor-mcp` runs.
-4. Do **not** load the Caplets Pi extension for `executor-mcp`.
-5. Write only the minimal adapter config required by `pi-mcp-adapter` under the isolated run root / agent dir. The adapter should receive one MCP server entry for Executor:
-
-```json
-{
-  "settings": {
-    "toolPrefix": "server",
-    "directTools": true,
-    "disableProxyTool": true,
-    "sampling": false,
-    "elicitation": false,
-    "idleTimeout": 0
-  },
-  "mcpServers": {
-    "executor": {
-      "command": "executor",
-      "args": ["mcp"],
-      "env": {
-        "EXECUTOR_DATA_DIR": "/tmp/.../executor-data",
-        "EXECUTOR_SCOPE_DIR": "/tmp/.../executor-scope"
-      },
-      "cwd": "/tmp/.../support",
-      "lifecycle": "eager",
-      "idleTimeout": 0,
-      "exposeResources": true,
-      "directTools": true,
-      "debug": false
-    }
-  }
-}
-```
-
-6. Pass the adapter config path with Pi's extension flag registered by the adapter: `--mcp-config <runRoot>/executor-mcp.json`. `pi-mcp-adapter` reads this via `pi.getFlag("mcp-config")` at session start and treats it as the Pi global MCP config path.
-7. Set `HOME=<runRoot>/home` and `PI_CODING_AGENT_DIR=<runRoot>/pi-agent` for the Pi process. This is required because the adapter still reads `~/.config/mcp/mcp.json` before the override path; `--mcp-config` alone is not enough to avoid user-global config leakage.
-8. Add `MCP_DIRECT_TOOLS=executor` to the run env and configure direct tools in the adapter config.
-9. Run an unmeasured prewarm Pi process with the same adapter config, same isolated `HOME`, and same isolated `PI_CODING_AGENT_DIR` before the measured candidate run. The prewarm process exists only to let `pi-mcp-adapter` connect to `executor mcp` and write `mcp-cache.json`; direct tools are then registered at module load in the measured process.
-10. Keep the prewarm run out of benchmark metrics and reports, except for a diagnostic field such as `adapterDirectToolsPrewarmed: true`.
-
-The important constraint is no leakage from the user's real Pi or Executor config. `executor-mcp` should load only:
-
-- benchmark instrumentation extension;
-- `npm:pi-mcp-adapter`;
-- `--mcp-config <runRoot>/executor-mcp.json`;
-- isolated `HOME` and `PI_CODING_AGENT_DIR`;
-- isolated adapter config pointing at isolated Executor state;
-- `MCP_DIRECT_TOOLS=executor` for direct Executor tool exposure.
-
-### 5. Add Executor detection
-
-Add `lib/pi-eval/executor.ts` or `lib/executor-runner.ts` with:
-
-```ts
-export async function detectExecutorCli({ env = process.env } = {}) {
-  // Run `executor --version` or equivalent with runProcess.
-}
-```
-
-Behavior:
-
-- Only required when `executor-mcp` is in the selected matrix.
-- Error clearly if unavailable:
-
-```text
-Executor CLI is required for executor-mcp mode. Install with `npm install -g executor` or pass --executor-command <path>.
-```
-
-Add CLI options:
-
-```bash
---executor-command <command>     # default: executor
---skip-missing-competitors       # optional; skip executor-mcp if unavailable instead of failing
-```
-
-Default should probably fail when explicitly requested and skip only if user asks.
-
-### 6. Prompt hints
-
-Add an Executor-specific prompt hint in `buildPiEvalPrompt`:
-
-```ts
-"executor-mcp":
-  "Executor is available through direct Pi tools registered by the MCP adapter. Use the `executor_...` tools to inspect current issue, CI, docs, API facts, and code-map hints before editing. Do not use Caplets tools."
-```
-
-Do not tell the model Caplets exists in the Executor mode. Keep benchmark prompts product-neutral except for tool-use guidance.
-
-### 7. Metrics and classification
-
-Extend `classifyHybridChoice()` to classify Executor usage:
-
-- If `mode === "executor-mcp"` and tool names include direct adapter tools with the `executor_` prefix, return `executor-only`.
-- If `mode === "executor-mcp"` and tool names include the adapter proxy tool `mcp`, flag the run as a direct-tools prewarm/cache failure unless it occurred only in the unmeasured prewarm run.
-- If tool names include `executor` or Executor MCP-emitted tool paths, return `executor-only`.
-- If mixed with Caplets somehow, classify `mixed-executor-caplets` and fail/flag the run because `executor-mcp` should not have Caplets extension loaded.
-
-Extend domain coverage patterns if Executor tool names/result wrappers obscure fixture server names. Keep existing content-based evidence checks, because result content includes benchmark IDs like `BENCH-451`, `CI-9182`, `/checkout/authorize`, and runbook text. Record an `adapterExposure: "direct-tools"` field so report consumers know Executor was evaluated through first-class direct adapter tools, not the proxy-only `mcp` tool.
-
-Add report columns/summary fields:
-
-- `product`: `caplets` or `executor`
-- `averageExecutorToolCalls` is not necessary if `averageToolCalls` works.
-- Keep existing token/round-trip metrics.
-
-Add explicit comparisons:
-
-- `executor-mcp vs caplets-direct`
-- `executor-mcp vs caplets-progressive`
-- `executor-mcp vs caplets-code-mode`
-- `executor-mcp vs caplets-progressive-code-mode`
-
-### 8. Report language
-
-Rename the report title from a Caplets-only framing to a competitor-neutral one:
-
-```md
-# Pi Live Tool Gateway Eval
-```
-
-Keep benchmark schema ID stable or bump schema version:
-
-```ts
-schemaVersion: 2,
-benchmark: "pi-live-tool-gateway-eval"
-```
-
-Add a compatibility note in the JSON/Markdown report:
-
-- live, local/model-dependent;
-- not deterministic product claims;
-- Executor version recorded;
-- Caplets package commit/version recorded where available.
-
----
-
-## Implementation Tasks
-
-## Task 1: Add mode metadata and failing tests
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/pi-eval/config.ts`
-- Modify: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Add `"executor-mcp"` to `PI_EVAL_MODES`.
-- [ ] Add `piEvalModeProduct(mode)` returning `"executor"` for `executor-mcp`, `"caplets"` otherwise.
-- [ ] Update mode validation tests to include `executor-mcp` in the default matrix.
-- [ ] Add prompt test asserting `buildPiEvalPrompt(task, "executor-mcp")` mentions Executor and does not mention Caplets-specific tool names.
-- [ ] Run focused tests and confirm expected failures before implementation updates:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts
-```
-
-## Task 2: Preserve Caplets config path via a renamed builder
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/pi-eval/config.ts`
-- Modify: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Rename current `createPiEvalRunConfig` internals to `createCapletsPiEvalRunConfig`.
-- [ ] Add dispatcher `createPiEvalRunConfig` that routes by mode.
-- [ ] Keep all existing Caplets tests passing unchanged.
-- [ ] Ensure `caplets-direct` still writes the same config and extension paths as before.
-
-## Task 3: Add Executor CLI detection
-
-**Files:**
-
-- Create: `packages/benchmarks/lib/pi-eval/executor.ts`
-- Modify: `packages/benchmarks/run-pi-eval.ts`
-- Modify: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Implement `detectExecutorCli({ command, env, processRunner })`.
-- [ ] Add `--executor-command <command>` CLI option, default `executor`.
-- [ ] Add detection only when the selected matrix contains `executor-mcp`.
-- [ ] Record Executor command/version in each `executor-mcp` result.
-- [ ] Add tests that:
-  - explicit `executor-mcp` fails with a clear message if Executor is unavailable;
-  - Caplets-only mode selections do not require Executor.
-
-## Task 4: Build isolated Executor run config
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/pi-eval/config.ts`
-- Create or modify: `packages/benchmarks/lib/pi-eval/executor.ts`
-- Modify: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Add `createExecutorPiEvalRunConfig`.
-- [ ] Create isolated dirs:
-  - `support/`
-  - `agent/`
-  - `sessions/`
-  - `extensions/`
-  - `executor-data/`
-  - `executor-scope/`
-- [ ] Copy fixture server and instrumentation extension.
-- [ ] Copy only Pi auth-bearing files (`auth.json`, `models.json`) into the isolated agent dir.
-- [ ] Return common fields:
-  - `runRoot`
-  - `mode`
-  - `product: "executor"`
-  - `metricsPath`
-  - `agentDir`
-  - `sessionsDir`
-  - `extensionPaths: [instrumentationPath, "npm:pi-mcp-adapter"]`
-  - `adapterConfigPath` or equivalent pointing at the generated `pi-mcp-adapter` MCP server config
-  - `adapterHomeDir` and `adapterAgentDir` for adapter/global config isolation
-  - `env` with isolated `HOME`, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, `MCP_DIRECT_TOOLS=executor`, `EXECUTOR_DATA_DIR`, `EXECUTOR_SCOPE_DIR`, isolated PATH, adapter config env, and live benchmark flags.
-- [ ] Add tests asserting Executor config includes `npm:pi-mcp-adapter`, does not include the Caplets Pi extension, and does not write `CAPLETS_CONFIG` unless needed by some setup helper.
-
-## Task 5: Register benchmark fixture MCP sources in Executor
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/pi-eval/executor.ts`
-- Modify: `packages/benchmarks/run-pi-eval.ts`
-- Add tests in: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Implement `setupExecutorFixtureSources({ executorCommand, fixtureServerPath, supportDir, env, processRunner })`.
-- [ ] Use the same selected server list as the Caplets checkout eval: `issues`, `ci`, `docs`, `api`, `code-map`.
-- [ ] For each server, configure a stdio MCP source launching:
-
-```bash
-tsx <fixtureServerPath> --server <server>
-```
-
-- [ ] Prefer CLI setup using Executor's `executor call ... addSource` path.
-- [ ] If CLI path is not stable, add a fallback setup script but keep it isolated and documented.
-- [ ] Add unit tests using an injected process runner to assert the exact source payloads and env isolation.
-- [ ] Add an opt-in local smoke command in docs/comments:
-
-```bash
-EXECUTOR_DATA_DIR=$(mktemp -d) EXECUTOR_SCOPE_DIR=$(mktemp -d) executor tools sources
-```
-
-## Task 6: Load `pi-mcp-adapter` direct tools for Executor MCP without user config leakage
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/pi-eval/config.ts`
-- Modify: `packages/benchmarks/lib/pi-eval/executor.ts`
-- Modify: `packages/benchmarks/run-pi-eval.ts`
-- Add tests in: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Write the adapter MCP config under `runRoot`, e.g. `join(runRoot, "executor-mcp.json")`.
-- [ ] Add `"npm:pi-mcp-adapter"` to `executor-mcp` `extensionPaths` after the instrumentation extension.
-- [ ] Pass adapter config to Pi with extra args: `--mcp-config <adapterConfigPath>`.
-- [ ] Configure the adapter config as:
-
-```json
-{
-  "settings": {
-    "toolPrefix": "server",
-    "directTools": true,
-    "disableProxyTool": true,
-    "sampling": false,
-    "elicitation": false
-  },
-  "mcpServers": {
-    "executor": {
-      "command": "executor",
-      "args": ["mcp"],
-      "env": {
-        "EXECUTOR_DATA_DIR": "/tmp/.../executor-data",
-        "EXECUTOR_SCOPE_DIR": "/tmp/.../executor-scope"
-      },
-      "cwd": "/tmp/.../support",
-      "lifecycle": "eager",
-      "idleTimeout": 0,
-      "exposeResources": true,
-      "directTools": true,
-      "debug": false
-    }
-  }
-}
-```
-
-- [ ] Add `MCP_DIRECT_TOOLS=executor` to the `executor-mcp` env to guarantee direct Executor tool exposure.
-- [ ] Set `HOME=<runRoot>/home` and `PI_CODING_AGENT_DIR=<runRoot>/pi-agent` to prevent adapter reads from real `~/.config/mcp/mcp.json` and real Pi agent config and to keep `mcp-cache.json` isolated.
-- [ ] Add an unmeasured direct-tools prewarm step that runs Pi once with the same adapter config/env/agent dir so `pi-mcp-adapter` writes a valid `mcp-cache.json` before the measured run starts.
-- [ ] Ensure the measured run starts only after cache prewarm succeeds and direct tool schemas are expected to be registered during extension module load.
-- [ ] Keep `--no-context-files`, `--no-skills`, `--no-prompt-templates`, and `--no-themes`; adapter config is supplied by `--mcp-config`, not project context files.
-- [ ] Add a test that `executor-mcp` command includes instrumentation, `npm:pi-mcp-adapter`, and `--mcp-config`, but not the Caplets Pi extension.
-- [ ] Add a test that `executor-mcp` command/env isolates `HOME`, `PI_CODING_AGENT_DIR`, `MCP_DIRECT_TOOLS=executor`, `EXECUTOR_DATA_DIR`, and `EXECUTOR_SCOPE_DIR`.
-- [ ] Add a test that the direct-tools prewarm command uses the same adapter config and isolated agent dir but writes to separate/unreported metrics/session artifacts.
-
-## Task 7: Extend metrics classification and reports
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/pi-eval/metrics.ts`
-- Modify: `packages/benchmarks/lib/pi-eval/report.ts`
-- Modify: `packages/benchmarks/run-pi-eval.ts`
-- Modify: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Classify Executor tool usage as `executor-only`.
-- [ ] Detect and flag mixed Caplets/Executor usage.
-- [ ] Add `product` to result rows and summary rows.
-- [ ] Add Executor comparison rows.
-- [ ] Rename Markdown title to `Pi Live Tool Gateway Eval`.
-- [ ] Bump JSON schema version to `2` if consumers might rely on title/shape.
-- [ ] Add tests for summary/report including `executor-mcp` and comparisons versus Caplets modes.
-
-## Task 8: Update docs and scripts
-
-**Files:**
-
-- Modify: `packages/benchmarks/package.json`
-- Modify: `package.json`
-- Modify: `docs/benchmarks/coding-agent.md` if generated/static live docs mention Pi eval
-- Possibly modify: `packages/benchmarks/lib/surface.ts` if it documents live commands
-
-- [ ] Add a convenience script if useful:
-
-```json
-"benchmark:live:pi-eval:competitors": "tsx run-pi-eval.ts --mode caplets-code-mode,caplets-progressive-code-mode,executor-mcp"
-```
-
-or keep the existing script and document the `--mode` invocation.
-
-- [ ] Document prerequisites:
-
-```bash
-npm install -g executor
-pnpm build
-CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:pi-eval -- --mode caplets-code-mode,caplets-progressive-code-mode,executor-mcp
-```
-
-- [ ] Document that all Executor state is isolated with `EXECUTOR_DATA_DIR` and `EXECUTOR_SCOPE_DIR`.
-- [ ] Document that live results are local/model-dependent and not deterministic product claims.
-
-## Task 9: Verification
-
-- [ ] Run focused tests:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts
-```
-
-- [ ] Run package typecheck:
-
-```bash
-pnpm --filter @caplets/benchmarks typecheck
-```
-
-- [ ] Run benchmark deterministic check if docs generated output changed:
-
-```bash
-pnpm --filter @caplets/benchmarks benchmark:check
-```
-
-- [ ] Run a live smoke test with one task/mode after `pnpm build` and Executor install:
-
-```bash
-CAPLETS_BENCH_LIVE=1 pnpm --filter @caplets/benchmarks benchmark:live:pi-eval -- --mode executor-mcp --tasks checkout-incident-retry-hardening --runs 1 --timeout-ms 600000 --preserve-artifacts
-```
-
-- [ ] Run the comparative smoke:
-
-```bash
-CAPLETS_BENCH_LIVE=1 pnpm --filter @caplets/benchmarks benchmark:live:pi-eval -- --mode caplets-code-mode,caplets-progressive-code-mode,executor-mcp --tasks checkout-incident-retry-hardening --runs 1 --timeout-ms 600000
-```
-
-- [ ] Confirm report includes:
-  - `executor-mcp` row;
-  - Executor version/command;
-  - same scoring/hidden validation as Caplets modes;
-  - required evidence coverage;
-  - token/round-trip/tool-call comparisons versus Caplets modes.
-
----
-
-## Risks and Mitigations
-
-### Risk: Executor CLI source registration path is unstable
-
-Mitigation: Hide it behind `setupExecutorFixtureSources` and write tests against our adapter. Add a local smoke check for current Executor before relying on it.
-
-### Risk: `pi-mcp-adapter` configuration conflicts with benchmark isolation
-
-Mitigation: Configure `pi-mcp-adapter` through an isolated run-root config and `--mcp-config`, and also set isolated `HOME` plus `PI_CODING_AGENT_DIR`. This matters because `pi-mcp-adapter@2.9.0` reads `~/.config/mcp/mcp.json` before the override path. The isolated `HOME`, `PI_CODING_AGENT_DIR`, `EXECUTOR_DATA_DIR`, and `EXECUTOR_SCOPE_DIR` prevent leakage. Direct tools make the isolated agent dir even more important because `mcp-cache.json` controls which direct tool schemas are registered at startup.
-
-### Risk: Executor daemon/process cleanup
-
-Mitigation: Use `EXECUTOR_DATA_DIR`/`EXECUTOR_SCOPE_DIR` under `runRoot`. Prefer foreground `executor mcp` spawned by Pi so process lifetime is owned by the MCP client. If setup starts a daemon, stop it explicitly in `finally` and remove `runRoot` unless artifacts are preserved.
-
-### Risk: Product unfairness from source setup differences
-
-Mitigation: Use exactly the same fixture server implementations and same five domains. Caplets config and Executor source setup should both point at copied `support/mcp-server.ts` with the same server names.
-
-### Risk: Tool-name/domain coverage misses Executor-wrapped output
-
-Mitigation: Existing content regexes should catch benchmark-specific IDs and text. Add Executor-specific patterns only where necessary, and keep scoring based on actual external facts observed rather than tool names alone.
-
-### Risk: Competitor version drift
-
-Mitigation: Capture `executor --version` in report results. Live reports are local artifacts, not committed deterministic benchmark claims.
-
----
-
-## Acceptance Criteria
-
-- `executor-mcp` is selectable with `--mode executor-mcp`.
-- Default matrix includes Executor or docs clearly state the competitor matrix command if we choose not to include it by default.
-- Caplets-only runs behave exactly as before.
-- Executor runs use isolated Executor, Pi, and adapter-global state directories, including isolated `HOME` and `PI_CODING_AGENT_DIR`; adapter direct-tool cache prewarm happens only inside that isolated agent dir.
-- Executor runs load `npm:pi-mcp-adapter`, pass `--mcp-config`, set `MCP_DIRECT_TOOLS=executor`, expose Executor through first-class direct adapter tools, and do not load the Caplets Pi extension.
-- Executor gets the same benchmark fixture domains as Caplets.
-- Measured Executor runs fail/flag if they only expose or call the adapter proxy `mcp` tool; `mcp` is acceptable only in the unmeasured prewarm step.
-- Reports compare Executor to Caplets modes on pass rate, duration, LLM round trips, estimated request tokens, non-surface tokens, tool surface tokens, and tool calls.
-- Tests cover mode parsing, run config isolation, command construction, metrics classification, and report comparisons.
-- Focused benchmark tests and typecheck pass.
diff --git a/docs/plans/2026-06-10-mcp-tool-use-pi-eval.md b/docs/plans/2026-06-10-mcp-tool-use-pi-eval.md
deleted file mode 100644
index 4abfa0b7..00000000
--- a/docs/plans/2026-06-10-mcp-tool-use-pi-eval.md
+++ /dev/null
@@ -1,1461 +0,0 @@
-# MCP Tool-Use Pi Eval Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Extend `benchmark:live:pi-eval` with a deterministic `mcp-tool-use` task suite that compares Caplets, vanilla MCP, and Executor on total provider tokens for realistic backend tool workflows.
-
-**Architecture:** Add suite metadata beside the Pi eval harness, so task loading, prompt construction, fixture server selection, and scoring are suite-owned while mode execution stays shared. Keep `coding` as the default suite and add `mcp-tool-use` as an opt-in suite with local MCP fixture servers and structured final-answer validation.
-
-**Tech Stack:** TypeScript, Node 24, pnpm, Vitest, Commander, local MCP fixture servers, Pi JSON-mode event capture.
-
----
-
-## File Structure
-
-- Create: `packages/benchmarks/lib/pi-eval/suites.ts`
-  - Owns suite IDs, suite resolution, suite-specific prompt builders, task metadata publication, and default task IDs.
-- Create: `packages/benchmarks/lib/pi-eval/mcp-tool-use-score.ts`
-  - Owns final JSON extraction, MCP tool-use fact validation, evidence validation, distractor rejection, and process scoring for the new suite.
-- Create: `packages/benchmarks/fixtures/mcp-tool-use/tasks.json`
-  - Defines the three deterministic MCP tool-use tasks and expected structured answers.
-- Create: `packages/benchmarks/fixtures/mcp-tool-use/mcp-server.ts`
-  - Exposes deterministic local MCP servers for `api_catalog`, `incidents`, `customers`, `deployments`, `quality`, and `policies`.
-- Modify: `packages/benchmarks/run-pi-eval.ts`
-  - Parses `--task-suite`, resolves suite metadata, uses optional workspaces, calls suite prompt/scoring hooks, passes suite fixture options into run config setup, and includes suite metadata in the report.
-- Modify: `packages/benchmarks/lib/pi-eval/config.ts`
-  - Accepts suite fixture server source path, fixture server IDs, server definitions, and direct-tools env values without changing current defaults.
-- Modify: `packages/benchmarks/lib/pi-eval/executor.ts`
-  - Allows Executor fixture source setup to use suite-specific server IDs.
-- Modify: `packages/benchmarks/lib/pi-eval/metrics.ts`
-  - Adds generic evidence coverage helpers while preserving existing coding domain coverage behavior.
-- Modify: `packages/benchmarks/lib/pi-eval/report.ts`
-  - Renders suite identity, total provider token comparisons, validator summaries, and existing coding-suite rows.
-- Modify: `packages/benchmarks/test/benchmark.test.ts`
-  - Adds focused tests for suite parsing, config routing, scoring, optional workspace behavior, coverage, and report rendering.
-
-## Task 1: Add Suite Registry And CLI Parsing
-
-**Files:**
-
-- Create: `packages/benchmarks/lib/pi-eval/suites.ts`
-- Modify: `packages/benchmarks/run-pi-eval.ts`
-- Test: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] **Step 1: Write failing tests for suite parsing and default behavior**
-
-Add these imports to `packages/benchmarks/test/benchmark.test.ts`:
-
-```ts
-import {
-  DEFAULT_PI_EVAL_SUITE_ID,
-  resolvePiEvalSuite,
-  validatePiEvalSuiteId,
-} from "../lib/pi-eval/suites";
-```
-
-Add this test in `describe("Pi live tool surface eval harness", () => { ... })` near the existing arg parsing test:
-
-```ts
-it("parses Pi eval task suites without changing the coding default", () => {
-  expect(DEFAULT_PI_EVAL_SUITE_ID).toBe("coding");
-  expect(parsePiEvalArgs([])).toMatchObject({
-    taskSuite: "coding",
-    tasks: ["checkout-incident-retry-hardening"],
-  });
-  expect(parsePiEvalArgs(["--task-suite", "mcp-tool-use"])).toMatchObject({
-    taskSuite: "mcp-tool-use",
-    tasks: [
-      "api-pagination-audit",
-      "incident-customer-impact-join",
-      "release-readiness-risk-report",
-    ],
-  });
-  expect(() => parsePiEvalArgs(["--task-suite", "missing-suite"])).toThrow(
-    /Unknown Pi eval task suite missing-suite/u,
-  );
-  expect(() => validatePiEvalSuiteId("missing-suite")).toThrow(
-    /Unknown Pi eval task suite missing-suite/u,
-  );
-  expect(resolvePiEvalSuite("coding")).toMatchObject({
-    id: "coding",
-    label: "Coding agent workspace",
-    workspaceRequired: true,
-  });
-  expect(resolvePiEvalSuite("mcp-tool-use")).toMatchObject({
-    id: "mcp-tool-use",
-    label: "MCP tool-use workflows",
-    workspaceRequired: false,
-  });
-});
-```
-
-- [ ] **Step 2: Run the focused test and verify failure**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "parses Pi eval task suites"
-```
-
-Expected: fails because `../lib/pi-eval/suites` does not exist and `parsePiEvalArgs` does not return `taskSuite`.
-
-- [ ] **Step 3: Create the suite registry**
-
-Create `packages/benchmarks/lib/pi-eval/suites.ts`:
-
-```ts
-import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { buildPiEvalPrompt } from "./config";
-import { scoreMcpToolUseRun } from "./mcp-tool-use-score";
-import { scoreTaskRun } from "../scoring";
-
-const packageRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));
-const defaultFixtureRoot = resolve(packageRoot, "fixtures");
-const codingFixtureRoot = defaultFixtureRoot;
-const mcpToolUseFixtureRoot = resolve(defaultFixtureRoot, "mcp-tool-use");
-
-export const PI_EVAL_SUITE_IDS = ["coding", "mcp-tool-use"] as const;
-export type PiEvalSuiteId = (typeof PI_EVAL_SUITE_IDS)[number];
-export const DEFAULT_PI_EVAL_SUITE_ID: PiEvalSuiteId = "coding";
-
-export type PiEvalSuite = {
-  id: PiEvalSuiteId;
-  label: string;
-  defaultTasks: string[];
-  fixtureRoot: string;
-  tasksPath: string;
-  workspaceRoot: string | null;
-  workspaceRequired: boolean;
-  fixtureServerSourcePath: string;
-  fixtureServers: string[];
-  directToolsEnv: string;
-  buildPrompt: (task: any, mode: string) => string;
-  scoreRun: (input: any) => Promise<any>;
-  publicTaskMetadata: (task: any) => Record<string, unknown>;
-};
-
-export function validatePiEvalSuiteId(value: string): asserts value is PiEvalSuiteId {
-  if (!(PI_EVAL_SUITE_IDS as readonly string[]).includes(value)) {
-    throw new Error(
-      `Unknown Pi eval task suite ${value}. Expected one of: ${PI_EVAL_SUITE_IDS.join(", ")}`,
-    );
-  }
-}
-
-export function resolvePiEvalSuite(value = DEFAULT_PI_EVAL_SUITE_ID): PiEvalSuite {
-  validatePiEvalSuiteId(value);
-  if (value === "mcp-tool-use") return mcpToolUseSuite;
-  return codingSuite;
-}
-
-function publicCodingTaskMetadata(task: any) {
-  return {
-    id: task.id,
-    prompt: task.prompt,
-    validationCommand: task.validationCommand,
-    expectedFiles: task.expectedFiles ?? [],
-    requiredFact: task.requiredFact ?? null,
-  };
-}
-
-function publicMcpToolUseTaskMetadata(task: any) {
-  return {
-    id: task.id,
-    title: task.title ?? null,
-    task_description: task.task_description ?? null,
-    fuzzy_description: task.fuzzy_description ?? null,
-    dependency_analysis: task.dependency_analysis ?? null,
-    expectedEvidence: task.expectedEvidence ?? null,
-    validator: task.validator ?? null,
-  };
-}
-
-const codingSuite: PiEvalSuite = {
-  id: "coding",
-  label: "Coding agent workspace",
-  defaultTasks: ["checkout-incident-retry-hardening"],
-  fixtureRoot: codingFixtureRoot,
-  tasksPath: resolve(codingFixtureRoot, "tasks.json"),
-  workspaceRoot: resolve(codingFixtureRoot, "coding-agent-workspace"),
-  workspaceRequired: true,
-  fixtureServerSourcePath: resolve(codingFixtureRoot, "mcp-server.ts"),
-  fixtureServers: ["issues", "ci", "docs", "api", "code-map"],
-  directToolsEnv: "issues,ci,docs,api,code-map",
-  buildPrompt: buildPiEvalPrompt,
-  scoreRun: scoreTaskRun,
-  publicTaskMetadata: publicCodingTaskMetadata,
-};
-
-const mcpToolUseSuite: PiEvalSuite = {
-  id: "mcp-tool-use",
-  label: "MCP tool-use workflows",
-  defaultTasks: [
-    "api-pagination-audit",
-    "incident-customer-impact-join",
-    "release-readiness-risk-report",
-  ],
-  fixtureRoot: mcpToolUseFixtureRoot,
-  tasksPath: resolve(mcpToolUseFixtureRoot, "tasks.json"),
-  workspaceRoot: null,
-  workspaceRequired: false,
-  fixtureServerSourcePath: resolve(mcpToolUseFixtureRoot, "mcp-server.ts"),
-  fixtureServers: ["api_catalog", "incidents", "customers", "deployments", "quality", "policies"],
-  directToolsEnv: "api_catalog,incidents,customers,deployments,quality,policies",
-  buildPrompt: buildMcpToolUsePrompt,
-  scoreRun: scoreMcpToolUseRun,
-  publicTaskMetadata: publicMcpToolUseTaskMetadata,
-};
-
-function buildMcpToolUsePrompt(task: any, mode: string): string {
-  const modeHint = buildPiEvalPrompt({ prompt: "" }, mode)
-    .split("\n")
-    .filter((line) => line && !line.includes("Complete the task in this workspace"))
-    .filter((line) => !line.includes("After editing"))
-    .join("\n");
-  return [
-    "You are running a benchmark. Complete the backend tool-use task using the configured MCP tools.",
-    "Do not inspect or edit repository files.",
-    "Use tool evidence for every material fact. Do not guess.",
-    "Return a concise final answer containing one JSON object with keys: taskId, decision, facts, summary.",
-    "Each facts entry must include key, value, and evidence.",
-    modeHint,
-    "",
-    `Task ID: ${task.id}`,
-    task.task_description ?? task.prompt,
-    task.fuzzy_description ? `Context: ${task.fuzzy_description}` : "",
-  ]
-    .filter(Boolean)
-    .join("\n");
-}
-```
-
-- [ ] **Step 4: Add `--task-suite` option and default tasks**
-
-In `packages/benchmarks/run-pi-eval.ts`, import the suite helpers:
-
-```ts
-import {
-  DEFAULT_PI_EVAL_SUITE_ID,
-  resolvePiEvalSuite,
-  validatePiEvalSuiteId,
-} from "./lib/pi-eval/suites";
-```
-
-Update `parsePiEvalArgs` to add:
-
-```ts
-.option("--task-suite <suite>", "task suite to run", DEFAULT_PI_EVAL_SUITE_ID)
-```
-
-Update `validatePiEvalOptions` to resolve the suite before tasks:
-
-```ts
-const taskSuite = options.taskSuite ?? DEFAULT_PI_EVAL_SUITE_ID;
-validatePiEvalSuiteId(taskSuite);
-const suite = resolvePiEvalSuite(taskSuite);
-```
-
-Return these fields from `validatePiEvalOptions`:
-
-```ts
-taskSuite,
-tasks: options.tasks?.length ? options.tasks : suite.defaultTasks,
-```
-
-- [ ] **Step 5: Run the focused test and commit**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "parses Pi eval task suites"
-```
-
-Expected: pass.
-
-Commit:
-
-```bash
-git add packages/benchmarks/lib/pi-eval/suites.ts packages/benchmarks/run-pi-eval.ts packages/benchmarks/test/benchmark.test.ts
-git commit -m "feat: add Pi eval suite selection"
-```
-
-## Task 2: Parameterize Fixture Config By Suite
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/config.ts`
-- Modify: `packages/benchmarks/lib/pi-eval/config.ts`
-- Modify: `packages/benchmarks/lib/pi-eval/executor.ts`
-- Modify: `packages/benchmarks/run-pi-eval.ts`
-- Test: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] **Step 1: Write failing tests for suite fixture routing**
-
-Add this test near the existing Pi eval config tests:
-
-```ts
-it("creates Pi eval configs from suite-specific fixture servers", async () => {
-  const root = await mkdtemp(join(tmpdir(), "caplets-pi-eval-suite-config-test-"));
-  const fixtureServerSourcePath = join(root, "suite-server.ts");
-  const sourceAgentDir = join(root, "source-agent");
-  try {
-    await mkdir(sourceAgentDir, { recursive: true });
-    await writeFile(fixtureServerSourcePath, "console.log('suite server')\n");
-    await writeFile(join(sourceAgentDir, "auth.json"), '{"token":"secret"}\n');
-
-    const capletsConfig = await createPiEvalRunConfig({
-      rootDir: join(root, "caplets"),
-      mode: "caplets-progressive",
-      piAgentSourceDir: sourceAgentDir,
-      fixtureServerSourcePath,
-      fixtureServers: ["api_catalog", "incidents"],
-      directToolsEnv: "api_catalog,incidents",
-    });
-    expect(Object.keys(capletsConfig.config.mcpServers).sort()).toEqual([
-      "api_catalog",
-      "incidents",
-    ]);
-    expect(await readFile(capletsConfig.fixtureServerPath, "utf8")).toContain("suite server");
-
-    const vanillaConfig = await createPiEvalRunConfig({
-      rootDir: join(root, "vanilla"),
-      mode: "vanilla-mcp",
-      piAgentSourceDir: sourceAgentDir,
-      fixtureServerSourcePath,
-      fixtureServers: ["api_catalog", "incidents"],
-      directToolsEnv: "api_catalog,incidents",
-    });
-    expect(Object.keys(vanillaConfig.adapterConfig.mcpServers).sort()).toEqual([
-      "api_catalog",
-      "incidents",
-    ]);
-    expect(vanillaConfig.env.MCP_DIRECT_TOOLS).toBe("api_catalog,incidents");
-  } finally {
-    await rm(root, { recursive: true, force: true });
-  }
-});
-```
-
-Add this test for Executor payloads:
-
-```ts
-it("creates Executor fixture source payloads for suite-specific servers", () => {
-  expect(
-    createExecutorFixtureSourcePayloads({
-      fixtureServerPath: "/tmp/server.ts",
-      supportDir: "/tmp/support",
-      servers: ["api_catalog", "incidents"],
-    }).map((payload) => payload.name),
-  ).toEqual(["api_catalog", "incidents"]);
-});
-```
-
-- [ ] **Step 2: Run tests and verify failure**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "suite-specific fixture"
-```
-
-Expected: config test fails because `fixtureServerSourcePath`, `fixtureServers`, and `directToolsEnv` are not honored.
-
-- [ ] **Step 3: Allow arbitrary benchmark fixture server definitions**
-
-In `packages/benchmarks/lib/config.ts`, add:
-
-```ts
-export function createNamedFixtureMcpServers({
-  fixtureServerPath,
-  cwd,
-  servers,
-  command = "tsx",
-  extra = {},
-}: any = {}) {
-  if (!Array.isArray(servers) || servers.length === 0) {
-    throw new TypeError("createNamedFixtureMcpServers requires at least one server.");
-  }
-  const serverPath = resolve(fixtureServerPath);
-  const serverCwd = resolve(cwd);
-  return Object.fromEntries(
-    servers.map((server: string) => [
-      server,
-      {
-        name: server.replaceAll("_", " "),
-        description: `Deterministic ${server.replaceAll("_", " ")} fixture server.`,
-        ...extra,
-        command,
-        args: [serverPath, "--server", server],
-        cwd: serverCwd,
-      },
-    ]),
-  );
-}
-```
-
-Update `createBenchmarkFixtureMcpServers` to call `createNamedFixtureMcpServers` after selecting existing server IDs:
-
-```ts
-export function createBenchmarkFixtureMcpServers({
-  repoRoot = REPO_ROOT,
-  fixtureServerPath,
-  cwd,
-  extra = {},
-  servers,
-  command = "tsx",
-  ...inlineExtra
-}: any = {}) {
-  const paths = getBenchmarkPaths({ repoRoot });
-  const selectedServers = servers ?? DEFAULT_BENCHMARK_SERVERS;
-  const definitions = benchmarkServerDefinitions();
-  const unknown = selectedServers.filter((server: string) => !definitions[server]);
-  if (unknown.length > 0) {
-    return createNamedFixtureMcpServers({
-      fixtureServerPath: fixtureServerPath ?? paths.fixtureServerPath,
-      cwd: cwd ?? paths.repoRoot,
-      servers: selectedServers,
-      command,
-      extra: { ...inlineExtra, ...extra },
-    });
-  }
-  return Object.fromEntries(
-    Object.entries(definitions)
-      .filter(([server]) => selectedServers.includes(server))
-      .map(([server, definition]) => [
-        server,
-        {
-          ...definition,
-          ...inlineExtra,
-          ...extra,
-          command,
-          args: [resolve(fixtureServerPath ?? paths.fixtureServerPath), "--server", server],
-          cwd: resolve(cwd ?? paths.repoRoot),
-        },
-      ]),
-  );
-}
-```
-
-- [ ] **Step 4: Parameterize Pi eval run config**
-
-In `packages/benchmarks/lib/pi-eval/config.ts`, thread these input fields through `createPiEvalRunConfig`, `createCapletsPiEvalRunConfig`, and `createVanillaMcpPiEvalRunConfig`:
-
-```ts
-fixtureServerSourcePath,
-fixtureServers = [...PI_EVAL_FIXTURE_SERVERS],
-directToolsEnv = VANILLA_MCP_DIRECT_TOOLS_ENV,
-```
-
-Use `fixtureServerSourcePath ?? paths.fixtureServerPath` in the `copyFile` calls.
-
-Use `fixtureServers` in `createBenchmarkFixtureMcpServers`.
-
-Use `directToolsEnv` for vanilla MCP:
-
-```ts
-env: {
-  CAPLETS_PI_EVAL_METRICS: metricsPath,
-  PI_CODING_AGENT_DIR: agentDir,
-  PI_CODING_AGENT_SESSION_DIR: sessionsDir,
-  XDG_CONFIG_HOME: xdgConfigHome,
-  MCP_DIRECT_TOOLS: directToolsEnv,
-  PATH: envPath,
-},
-```
-
-- [ ] **Step 5: Pass suite fixture config from the runner**
-
-In `packages/benchmarks/run-pi-eval.ts`, resolve the suite in `runPiEvalBenchmark` and pass these fields into `runConfigFactory`:
-
-```ts
-runConfig = await runConfigFactory({
-  mode: entry.mode,
-  requireBuild: true,
-  executorCommand: evalOptions.executorCommand,
-  fixtureServerSourcePath: suite.fixtureServerSourcePath,
-  fixtureServers: suite.fixtureServers,
-  directToolsEnv: suite.directToolsEnv,
-});
-```
-
-When calling `setupExecutorFixtureSources`, pass:
-
-```ts
-servers: suite.fixtureServers,
-```
-
-- [ ] **Step 6: Run focused tests and commit**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "suite-specific fixture|Executor fixture source payloads"
-```
-
-Expected: pass.
-
-Commit:
-
-```bash
-git add packages/benchmarks/lib/config.ts packages/benchmarks/lib/pi-eval/config.ts packages/benchmarks/lib/pi-eval/executor.ts packages/benchmarks/run-pi-eval.ts packages/benchmarks/test/benchmark.test.ts
-git commit -m "feat: route Pi eval fixtures by suite"
-```
-
-## Task 3: Add MCP Tool-Use Fixture Server And Tasks
-
-**Files:**
-
-- Create: `packages/benchmarks/fixtures/mcp-tool-use/tasks.json`
-- Create: `packages/benchmarks/fixtures/mcp-tool-use/mcp-server.ts`
-- Test: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] **Step 1: Write failing tests for task loading and server metadata**
-
-Add this test:
-
-```ts
-it("loads MCP tool-use suite tasks with expected dependency metadata", async () => {
-  const suite = resolvePiEvalSuite("mcp-tool-use");
-  const tasks = await loadTasks(suite.tasksPath);
-  expect(tasks.map((task: any) => task.id)).toEqual([
-    "api-pagination-audit",
-    "incident-customer-impact-join",
-    "release-readiness-risk-report",
-  ]);
-  expect(tasks[0]).toMatchObject({
-    dependency_analysis: { servers: ["api_catalog"] },
-    expectedEvidence: { servers: ["api_catalog"] },
-  });
-  expect(tasks[1].dependency_analysis.servers).toEqual(["incidents", "customers"]);
-  expect(tasks[2].dependency_analysis.servers).toEqual(["deployments", "quality", "policies"]);
-});
-```
-
-Add a fixture smoke test:
-
-```ts
-it("exposes MCP tool-use fixture server metadata", async () => {
-  const suite = resolvePiEvalSuite("mcp-tool-use");
-  const config = createNamedFixtureMcpServers({
-    fixtureServerPath: suite.fixtureServerSourcePath,
-    cwd: suite.fixtureRoot,
-    servers: suite.fixtureServers,
-  });
-  expect(Object.keys(config).sort()).toEqual([
-    "api_catalog",
-    "customers",
-    "deployments",
-    "incidents",
-    "policies",
-    "quality",
-  ]);
-  expect(config.api_catalog.args).toEqual([
-    suite.fixtureServerSourcePath,
-    "--server",
-    "api_catalog",
-  ]);
-});
-```
-
-- [ ] **Step 2: Run tests and verify failure**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "MCP tool-use suite tasks|MCP tool-use fixture server"
-```
-
-Expected: fails because the fixture files do not exist.
-
-- [ ] **Step 3: Create `tasks.json`**
-
-Create `packages/benchmarks/fixtures/mcp-tool-use/tasks.json` with exact task IDs and expected answers:
-
-```json
-[
-  {
-    "id": "api-pagination-audit",
-    "title": "API pagination audit",
-    "prompt": "Audit the API catalog for pagination behavior across product, customer, and audit APIs. Return only the requested JSON final answer.",
-    "task_description": "Compare search/list endpoints across three product APIs and identify which operations are paginated, how pagination works, and the required parameter names.",
-    "fuzzy_description": "The agent must inspect operation details, distinguish paginated endpoints from lookalikes, and ignore a fallback list endpoint that is not paginated.",
-    "dependency_analysis": {
-      "servers": ["api_catalog"],
-      "requires": ["search catalog", "inspect operation details", "compare pagination parameters"]
-    },
-    "expectedEvidence": {
-      "servers": ["api_catalog"],
-      "tools": [
-        "api_catalog.search_apis",
-        "api_catalog.list_operations",
-        "api_catalog.get_operation"
-      ]
-    },
-    "expectedFacts": {
-      "paginatedOperations": ["products.search", "customers.list", "audit.events"],
-      "paginationStyles": {
-        "products.search": "cursor",
-        "customers.list": "offset",
-        "audit.events": "time_window"
-      },
-      "requiredParameters": {
-        "products.search": ["query", "page_size", "cursor"],
-        "customers.list": ["limit", "offset"],
-        "audit.events": ["start_time", "end_time", "next_token"]
-      },
-      "notPaginated": ["products.list_legacy"]
-    },
-    "distractorFacts": ["products.list_legacy is paginated", "orders.export is required"],
-    "validator": "api-pagination-audit"
-  },
-  {
-    "id": "incident-customer-impact-join",
-    "title": "Incident customer impact join",
-    "prompt": "Find the active incident and join affected account IDs to customer records. Return only the requested JSON final answer.",
-    "task_description": "Find the active incident, fetch affected account IDs, join customer details, and return the customer impact summary.",
-    "fuzzy_description": "The agent must discover which incident and customer tools matter, ignore unrelated records, and combine results across servers.",
-    "dependency_analysis": {
-      "servers": ["incidents", "customers"],
-      "requires": [
-        "find active incident",
-        "read affected account IDs",
-        "join account tiers, regions, and escalation contacts"
-      ]
-    },
-    "expectedEvidence": {
-      "servers": ["incidents", "customers"],
-      "tools": ["incidents.search_incidents", "incidents.get_incident", "customers.get_accounts"]
-    },
-    "expectedFacts": {
-      "activeIncidentId": "INC-2026-0610-2",
-      "affectedAccountCount": 4,
-      "tierBreakdown": { "enterprise": 2, "growth": 1, "startup": 1 },
-      "regionBreakdown": { "na": 2, "eu": 1, "apac": 1 },
-      "escalationTargets": ["atlas-oncall", "beacon-csm", "crane-support"]
-    },
-    "distractorFacts": ["INC-2026-0610-1", "acme-retail"],
-    "validator": "incident-customer-impact-join"
-  },
-  {
-    "id": "release-readiness-risk-report",
-    "title": "Release readiness risk report",
-    "prompt": "Decide whether the release can proceed by combining deployment, quality, and policy evidence. Return only the requested JSON final answer.",
-    "task_description": "Decide whether a release can proceed from deploy status, failing checks, policy exceptions, and risk thresholds.",
-    "fuzzy_description": "The agent must inspect the current release, failing quality checks, policy thresholds, and exception scope before deciding go or no-go.",
-    "dependency_analysis": {
-      "servers": ["deployments", "quality", "policies"],
-      "requires": [
-        "find current release",
-        "inspect quality checks",
-        "apply policy thresholds",
-        "validate exceptions"
-      ]
-    },
-    "expectedEvidence": {
-      "servers": ["deployments", "quality", "policies"],
-      "tools": [
-        "deployments.get_release",
-        "quality.list_checks",
-        "policies.get_release_policy",
-        "policies.list_exceptions"
-      ]
-    },
-    "expectedFacts": {
-      "releaseId": "REL-2026-06-10-payments",
-      "decision": "no-go",
-      "blockers": ["contract-tests", "rollback-plan"],
-      "validExceptions": ["EXC-442"],
-      "invalidExceptions": ["EXC-410", "EXC-499"]
-    },
-    "distractorFacts": ["go", "REL-2026-06-10-search", "EXC-410 is valid"],
-    "validator": "release-readiness-risk-report"
-  }
-]
-```
-
-- [ ] **Step 4: Create the MCP fixture server**
-
-Create `packages/benchmarks/fixtures/mcp-tool-use/mcp-server.ts` by reusing the server pattern from `packages/benchmarks/fixtures/mcp-server.ts`:
-
-```ts
-import { realpathSync } from "node:fs";
-import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-export const SERVER_NAMES = [
-  "api_catalog",
-  "incidents",
-  "customers",
-  "deployments",
-  "quality",
-  "policies",
-];
-
-const emptySchema = { type: "object", properties: {}, additionalProperties: false };
-const querySchema = {
-  type: "object",
-  properties: { query: { type: "string" } },
-  additionalProperties: false,
-};
-const idSchema = {
-  type: "object",
-  properties: { id: { type: "string" } },
-  required: ["id"],
-  additionalProperties: false,
-};
-const idsSchema = {
-  type: "object",
-  properties: { ids: { type: "array", items: { type: "string" } } },
-  required: ["ids"],
-  additionalProperties: false,
-};
-
-const readOnlyAnnotations = { readOnlyHint: true, idempotentHint: true };
-
-const asResult = (summary: string, data: unknown) => ({
-  content: [{ type: "text", text: `${summary}\n${JSON.stringify(data, null, 2)}` }],
-  structuredContent: data,
-});
-```
-
-Add records and tools for each server using these exact values from `tasks.json`: `INC-2026-0610-2`, `REL-2026-06-10-payments`, `EXC-442`, `EXC-410`, and `EXC-499`.
-
-Export:
-
-```ts
-export function listToolMetadata(serverName: string) {
-  return toolsForServer(serverName).map((tool) => ({
-    name: tool.name,
-    title: tool.title,
-    description: tool.description,
-    inputSchema: tool.inputSchema,
-    annotations: readOnlyAnnotations,
-    server: serverName,
-  }));
-}
-```
-
-Keep the stdio MCP bootstrap consistent with the existing fixture server: parse `--server`, validate against `SERVER_NAMES`, register tools, call handlers, and return `structuredContent`.
-
-- [ ] **Step 5: Run tests and commit**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "MCP tool-use suite tasks|MCP tool-use fixture server"
-```
-
-Expected: pass.
-
-Commit:
-
-```bash
-git add packages/benchmarks/fixtures/mcp-tool-use packages/benchmarks/test/benchmark.test.ts
-git commit -m "feat: add MCP tool-use Pi eval fixtures"
-```
-
-## Task 4: Add MCP Tool-Use Scoring
-
-**Files:**
-
-- Create: `packages/benchmarks/lib/pi-eval/mcp-tool-use-score.ts`
-- Modify: `packages/benchmarks/lib/pi-eval/metrics.ts`
-- Test: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] **Step 1: Write failing tests for final JSON extraction and scoring**
-
-Add imports:
-
-```ts
-import { extractMcpToolUseFinalJson, scoreMcpToolUseRun } from "../lib/pi-eval/mcp-tool-use-score";
-```
-
-Add tests:
-
-````ts
-it("extracts MCP tool-use final JSON from assistant text", () => {
-  const parsed = extractMcpToolUseFinalJson([
-    {
-      type: "message",
-      message: {
-        role: "assistant",
-        content: [
-          {
-            type: "text",
-            text: 'Done\n```json\n{"taskId":"x","decision":"ok","facts":[],"summary":"ok"}\n```',
-          },
-        ],
-      },
-    },
-  ]);
-  expect(parsed).toEqual({ taskId: "x", decision: "ok", facts: [], summary: "ok" });
-});
-
-it("scores MCP tool-use runs from expected facts and tool evidence", async () => {
-  const task = {
-    id: "incident-customer-impact-join",
-    expectedEvidence: {
-      servers: ["incidents", "customers"],
-      tools: ["incidents.get_incident", "customers.get_accounts"],
-    },
-    expectedFacts: {
-      activeIncidentId: "INC-2026-0610-2",
-      affectedAccountCount: 4,
-      tierBreakdown: { enterprise: 2, growth: 1, startup: 1 },
-    },
-    distractorFacts: ["INC-2026-0610-1"],
-  };
-  const agentResult = emptyProcessResult({
-    command: "pi-test",
-    args: [],
-    stdout: JSON.stringify({
-      taskId: "incident-customer-impact-join",
-      decision: "summary",
-      facts: [
-        { key: "activeIncidentId", value: "INC-2026-0610-2", evidence: ["incidents.get_incident"] },
-        { key: "affectedAccountCount", value: 4, evidence: ["customers.get_accounts"] },
-        {
-          key: "tierBreakdown",
-          value: { enterprise: 2, growth: 1, startup: 1 },
-          evidence: ["customers.get_accounts"],
-        },
-      ],
-      summary: "Four accounts affected.",
-    }),
-    jsonEvents: [
-      { type: "tool_execution_start", toolName: "incidents.get_incident" },
-      { type: "tool_execution_start", toolName: "customers.get_accounts" },
-    ],
-  });
-  await expect(scoreMcpToolUseRun({ task, agentResult })).resolves.toMatchObject({
-    success: true,
-    processSuccess: true,
-    validation: { success: true },
-  });
-});
-
-it("fails MCP tool-use scoring when distractor facts appear", async () => {
-  const task = {
-    id: "incident-customer-impact-join",
-    expectedEvidence: { tools: ["incidents.get_incident"] },
-    expectedFacts: { activeIncidentId: "INC-2026-0610-2" },
-    distractorFacts: ["INC-2026-0610-1"],
-  };
-  const agentResult = emptyProcessResult({
-    command: "pi-test",
-    args: [],
-    stdout:
-      '{"taskId":"incident-customer-impact-join","decision":"summary","facts":[{"key":"activeIncidentId","value":"INC-2026-0610-1","evidence":["incidents.get_incident"]}],"summary":"wrong incident"}',
-    jsonEvents: [{ type: "tool_execution_start", toolName: "incidents.get_incident" }],
-  });
-  const score = await scoreMcpToolUseRun({ task, agentResult });
-  expect(score.success).toBe(false);
-  expect(score.validation.stdout).toContain("distractor fact appeared: INC-2026-0610-1");
-});
-````
-
-- [ ] **Step 2: Run tests and verify failure**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "MCP tool-use"
-```
-
-Expected: fails because scoring module does not exist.
-
-- [ ] **Step 3: Implement MCP tool-use scoring**
-
-Create `packages/benchmarks/lib/pi-eval/mcp-tool-use-score.ts`:
-
-````ts
-import { toolNameFromEvent } from "./metrics";
-
-export function extractMcpToolUseFinalJson(events: any[] = [], stdout = "") {
-  const candidates = [stdout, ...assistantTexts(events)].filter(Boolean);
-  for (const candidate of candidates.reverse()) {
-    const parsed = parseJsonObject(candidate);
-    if (parsed) return parsed;
-  }
-  return null;
-}
-
-export async function scoreMcpToolUseRun({ task, agentResult }: any = {}) {
-  if (!task) throw new TypeError("scoreMcpToolUseRun requires a task.");
-  const processFailureReason = agentProcessFailureReason(agentResult);
-  const processSuccess = !processFailureReason;
-  const parsed = extractMcpToolUseFinalJson(
-    agentResult?.jsonEvents ?? [],
-    agentResult?.stdout ?? "",
-  );
-  const validation = validateMcpToolUseAnswer({
-    task,
-    parsed,
-    events: agentResult?.jsonEvents ?? [],
-  });
-  return {
-    taskId: task.id,
-    success: processSuccess && validation.success,
-    finalStateValid: validation.success,
-    processSuccess,
-    processFailureReason,
-    validation,
-    hiddenValidation: { success: true, skipped: true, command: undefined },
-    process: agentResult
-      ? {
-          exitCode: agentResult.exitCode,
-          signal: agentResult.signal,
-          timedOut: agentResult.timedOut,
-          durationMs: agentResult.durationMs,
-          command: agentResult.command,
-          args: agentResult.args,
-          envKeys: agentResult.envKeys,
-          skipped: agentResult.skipped,
-          unavailable: agentResult.unavailable,
-          configConflict: agentResult.configConflict,
-        }
-      : undefined,
-    parsedFinalAnswer: parsed,
-  };
-}
-
-function validateMcpToolUseAnswer({ task, parsed, events }: any) {
-  const failures: string[] = [];
-  if (!parsed || typeof parsed !== "object") {
-    failures.push("final JSON object was not found");
-  } else {
-    if (parsed.taskId !== task.id) failures.push(`taskId mismatch: ${String(parsed.taskId)}`);
-    const answerText = JSON.stringify(parsed);
-    for (const [key, expected] of Object.entries(task.expectedFacts ?? {})) {
-      if (!answerContainsExpectedFact(parsed, key, expected)) {
-        failures.push(`missing expected fact: ${key}`);
-      }
-    }
-    for (const distractor of task.distractorFacts ?? []) {
-      if (answerText.includes(String(distractor))) {
-        failures.push(`distractor fact appeared: ${distractor}`);
-      }
-    }
-  }
-
-  const observedTools = new Set(events.map(toolNameFromEvent).filter(Boolean));
-  for (const expectedTool of task.expectedEvidence?.tools ?? []) {
-    if (!observedTools.has(expectedTool) && !toolEvidenceText(parsed).includes(expectedTool)) {
-      failures.push(`missing expected tool evidence: ${expectedTool}`);
-    }
-  }
-
-  return {
-    success: failures.length === 0,
-    command: "mcp-tool-use-final-answer-validator",
-    args: [task.id],
-    exitCode: failures.length === 0 ? 0 : 1,
-    signal: null,
-    timedOut: false,
-    durationMs: 0,
-    stdout: failures.join("\n"),
-    stderr: "",
-    stdoutBytes: Buffer.byteLength(failures.join("\n"), "utf8"),
-    stderrBytes: 0,
-    stdoutTruncated: false,
-    stderrTruncated: false,
-  };
-}
-
-function answerContainsExpectedFact(parsed: any, key: string, expected: unknown) {
-  const facts = Array.isArray(parsed?.facts) ? parsed.facts : [];
-  return facts.some((fact: any) => fact?.key === key && deepEqual(fact.value, expected));
-}
-
-function toolEvidenceText(parsed: any) {
-  const facts = Array.isArray(parsed?.facts) ? parsed.facts : [];
-  return JSON.stringify(facts.flatMap((fact: any) => fact?.evidence ?? []));
-}
-
-function assistantTexts(events: any[]) {
-  return events.flatMap((event) => {
-    const message = event?.message;
-    if (message?.role !== "assistant") return [];
-    const content = message.content;
-    if (typeof content === "string") return [content];
-    if (!Array.isArray(content)) return [];
-    return content.map((part: any) => part?.text ?? "").filter(Boolean);
-  });
-}
-
-function parseJsonObject(text: string) {
-  const trimmed = String(text ?? "").trim();
-  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/u)?.[1];
-  for (const candidate of [fenced, trimmed, trimmed.match(/\{[\s\S]*\}/u)?.[0]].filter(Boolean)) {
-    try {
-      const parsed = JSON.parse(candidate as string);
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
-    } catch {
-      continue;
-    }
-  }
-  return null;
-}
-
-function deepEqual(a: unknown, b: unknown) {
-  return JSON.stringify(sortJson(a)) === JSON.stringify(sortJson(b));
-}
-
-function sortJson(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(sortJson);
-  if (!value || typeof value !== "object") return value;
-  return Object.fromEntries(
-    Object.entries(value as Record<string, unknown>)
-      .sort(([a], [b]) => a.localeCompare(b))
-      .map(([key, entry]) => [key, sortJson(entry)]),
-  );
-}
-
-function agentProcessFailureReason(agentResult: any) {
-  if (!agentResult) return "agent result missing";
-  if (agentResult.timedOut) return "agent timed out";
-  if (agentResult.signal) return `agent exited with signal ${agentResult.signal}`;
-  if (agentResult.exitCode != null && agentResult.exitCode !== 0) {
-    return `agent exited with code ${agentResult.exitCode}`;
-  }
-  return undefined;
-}
-````
-
-- [ ] **Step 4: Run tests and commit**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "MCP tool-use"
-```
-
-Expected: pass.
-
-Commit:
-
-```bash
-git add packages/benchmarks/lib/pi-eval/mcp-tool-use-score.ts packages/benchmarks/test/benchmark.test.ts
-git commit -m "feat: score MCP tool-use Pi eval answers"
-```
-
-## Task 5: Integrate Suites Into The Runner
-
-**Files:**
-
-- Modify: `packages/benchmarks/run-pi-eval.ts`
-- Modify: `packages/benchmarks/lib/pi-eval/metrics.ts`
-- Test: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] **Step 1: Write failing runner integration tests**
-
-Add a no-workspace suite run test:
-
-```ts
-it("runs MCP tool-use suite jobs without copying a coding workspace", async () => {
-  const root = await mkdtemp(join(tmpdir(), "caplets-pi-eval-mcp-suite-run-test-"));
-  const outputDir = join(root, "reports");
-  const runRoots: string[] = [];
-  try {
-    const result = await runPiEvalBenchmark({
-      options: {
-        outputDir,
-        taskSuite: "mcp-tool-use",
-        modes: ["caplets-code-mode"],
-        tasks: ["incident-customer-impact-join"],
-        runs: 1,
-        timeoutMs: 10_000,
-      },
-      env: { CAPLETS_BENCH_LIVE: "1" },
-      piDetector: async () => ({ available: true, command: "pi-test", version: "pi-test 1" }),
-      runConfigFactory: async ({ mode, fixtureServers }: any) => {
-        const runRoot = await mkdtemp(join(root, "run-"));
-        runRoots.push(runRoot);
-        expect(fixtureServers).toEqual([
-          "api_catalog",
-          "incidents",
-          "customers",
-          "deployments",
-          "quality",
-          "policies",
-        ]);
-        return {
-          runRoot,
-          mode,
-          product: "caplets",
-          adapterExposure: null,
-          configPath: null,
-          adapterConfigPath: null,
-          xdgConfigHome: null,
-          xdgCapletsConfigPath: null,
-          supportDir: runRoot,
-          fixtureServerPath: null,
-          metricsPath: join(runRoot, "metrics.jsonl"),
-          prewarmMetricsPath: null,
-          sessionsDir: join(runRoot, "sessions"),
-          prewarmSessionsDir: null,
-          agentDir: join(runRoot, "agent"),
-          copiedPiAuthFiles: [],
-          extensionPaths: [],
-          extraArgs: [],
-          env: { PI_CODING_AGENT_DIR: join(runRoot, "agent") },
-        };
-      },
-      processRunner: async (call: any) =>
-        emptyProcessResult({
-          command: call.command,
-          args: call.args,
-          stdout: JSON.stringify({
-            taskId: "incident-customer-impact-join",
-            decision: "summary",
-            facts: [
-              {
-                key: "activeIncidentId",
-                value: "INC-2026-0610-2",
-                evidence: ["incidents.get_incident"],
-              },
-              { key: "affectedAccountCount", value: 4, evidence: ["customers.get_accounts"] },
-              {
-                key: "tierBreakdown",
-                value: { enterprise: 2, growth: 1, startup: 1 },
-                evidence: ["customers.get_accounts"],
-              },
-              {
-                key: "regionBreakdown",
-                value: { na: 2, eu: 1, apac: 1 },
-                evidence: ["customers.get_accounts"],
-              },
-              {
-                key: "escalationTargets",
-                value: ["atlas-oncall", "beacon-csm", "crane-support"],
-                evidence: ["customers.get_accounts"],
-              },
-            ],
-            summary: "Four accounts affected.",
-          }),
-          jsonEvents: [
-            { type: "tool_execution_start", toolName: "incidents.search_incidents" },
-            { type: "tool_execution_start", toolName: "incidents.get_incident" },
-            { type: "tool_execution_start", toolName: "customers.get_accounts" },
-          ],
-        }),
-    });
-
-    expect(result.report.suite).toMatchObject({
-      id: "mcp-tool-use",
-      label: "MCP tool-use workflows",
-    });
-    expect(result.report.results[0].score.success).toBe(true);
-    expect(result.report.results[0].candidateWorkspace).toBeNull();
-    expect(await readFile(result.markdownPath, "utf8")).toContain("Suite: MCP tool-use workflows");
-  } finally {
-    await rm(root, { recursive: true, force: true });
-  }
-});
-```
-
-- [ ] **Step 2: Run test and verify failure**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "runs MCP tool-use suite"
-```
-
-Expected: fails because runner still always copies a workspace and uses coding scorer.
-
-- [ ] **Step 3: Integrate suite in `runPiEvalBenchmark`**
-
-In `packages/benchmarks/run-pi-eval.ts`:
-
-- Resolve `const suite = resolvePiEvalSuite(evalOptions.taskSuite);`.
-- Default `fixtureRoot`, `fixtureWorkspaceRoot`, and `tasksPath` from `suite` when caller does not inject values.
-- Use `suite.buildPrompt(task, entry.mode)` instead of `buildPiEvalPrompt(task, entry.mode)`.
-- Create an empty temp workspace for suites without a workspace root:
-
-```ts
-async function createPiEvalWorkspace(suite: any, fixtureWorkspaceRoot?: string | null) {
-  if (suite.workspaceRequired) {
-    return await createTempWorkspaceFromFixture(fixtureWorkspaceRoot);
-  }
-  return await mkdtemp(join(tmpdir(), "caplets-pi-eval-workspace-"));
-}
-```
-
-- Score with:
-
-```ts
-const score = await suite.scoreRun({
-  task,
-  candidateWorkspace,
-  fixtureRoot,
-  agentResult,
-});
-```
-
-- Add suite metadata to report:
-
-```ts
-suite: {
-  id: suite.id,
-  label: suite.label,
-  workspaceRequired: suite.workspaceRequired,
-  fixtureServers: suite.fixtureServers,
-},
-```
-
-- Use `suite.publicTaskMetadata` for `report.tasks`.
-
-- [ ] **Step 4: Keep evidence scoring compatible**
-
-In `packages/benchmarks/lib/pi-eval/metrics.ts`, keep `requiredEvidenceScore` returning the current coding coverage for `checkout-incident-retry-hardening`.
-
-For `mcp-tool-use`, return required tool evidence from metrics:
-
-```ts
-if (task?.expectedEvidence?.tools?.length) {
-  const observedTools = new Set(metrics?.toolNames ?? []);
-  const missingTools = task.expectedEvidence.tools.filter(
-    (tool: string) => !observedTools.has(tool),
-  );
-  return {
-    required: true,
-    success: missingTools.length === 0,
-    missingDomains: missingTools,
-    coverage: {
-      tools: Object.fromEntries(
-        task.expectedEvidence.tools.map((tool: string) => [tool, observedTools.has(tool)]),
-      ),
-    },
-  };
-}
-```
-
-- [ ] **Step 5: Run focused tests and commit**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "runs MCP tool-use suite|scores required checkout evidence"
-```
-
-Expected: pass.
-
-Commit:
-
-```bash
-git add packages/benchmarks/run-pi-eval.ts packages/benchmarks/lib/pi-eval/metrics.ts packages/benchmarks/test/benchmark.test.ts
-git commit -m "feat: run Pi eval suites through shared harness"
-```
-
-## Task 6: Report Suite-Level Token And Validator Results
-
-**Files:**
-
-- Modify: `packages/benchmarks/lib/pi-eval/report.ts`
-- Test: `packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] **Step 1: Write failing report tests**
-
-Extend the existing report test with suite metadata and provider-token comparison text:
-
-```ts
-const markdown = renderPiEvalMarkdownReport({
-  suite: { id: "mcp-tool-use", label: "MCP tool-use workflows" },
-  completedAt: "2026-06-09T00:00:00.000Z",
-  options: { model: "test-model", runs: 1, timeoutMs: 1000, concurrency: 2 },
-  summary,
-  results: [result, executorResult],
-});
-
-expect(markdown).toContain("Suite: MCP tool-use workflows");
-expect(markdown).toContain("Avg provider tokens");
-expect(markdown).toContain("Validator Summary");
-```
-
-- [ ] **Step 2: Run test and verify failure**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "summarizes Pi eval reports"
-```
-
-Expected: fails on suite and validator summary text.
-
-- [ ] **Step 3: Update report rendering**
-
-In `renderPiEvalMarkdownReport`, add after model:
-
-```ts
-`Suite: ${report.suite?.label ?? "Coding agent workspace"}`,
-```
-
-Change comparison rows to include total provider tokens:
-
-```ts
-`- ${comparison.label}: duration ${formatPercent(comparison.durationReduction)}, LLM round trips ${formatPercent(comparison.providerRequestReduction)}, estimated request tokens ${formatPercent(comparison.requestTokenReduction)}, provider tokens ${formatPercent(comparison.providerTokenReduction)}`,
-```
-
-In `compareRows`, add:
-
-```ts
-providerTokenReduction: reduction(b.averageProviderTokens, a.averageProviderTokens),
-```
-
-Add validator summaries:
-
-```ts
-const validatorRows = report.results.map(
-  (result: any) =>
-    `| ${result.mode} | ${result.taskId} | ${result.run} | ${result.score?.validation?.success ? "pass" : "fail"} | ${
-      String(result.score?.validation?.stdout ?? "")
-        .replace(/\s+/gu, " ")
-        .slice(0, 160) || "n/a"
-    } |`,
-);
-```
-
-Render:
-
-```ts
-"## Validator Summary",
-"",
-"| Mode | Task | Run | Validator | Notes |",
-"| --- | --- | ---: | --- | --- |",
-...validatorRows,
-"",
-```
-
-- [ ] **Step 4: Run report tests and commit**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts -t "summarizes Pi eval reports"
-```
-
-Expected: pass.
-
-Commit:
-
-```bash
-git add packages/benchmarks/lib/pi-eval/report.ts packages/benchmarks/test/benchmark.test.ts
-git commit -m "feat: report Pi eval suite validator results"
-```
-
-## Task 7: Run Full Benchmark Package Tests And Build
-
-**Files:**
-
-- Validate current implementation files only.
-
-- [ ] **Step 1: Run benchmark package tests**
-
-Run from `core/`:
-
-```bash
-pnpm --filter @caplets/benchmarks test
-```
-
-Expected: all benchmark package tests pass.
-
-- [ ] **Step 2: Run Core build**
-
-Run from `caplets-mono` root:
-
-```bash
-pnpm --dir ./core run build
-```
-
-Expected: build passes and writes fresh `dist` artifacts consumed by live Pi eval.
-
-- [ ] **Step 3: Commit any test/build fixes**
-
-If the previous steps required fixes, commit them:
-
-```bash
-git add packages/benchmarks
-git commit -m "test: cover MCP tool-use Pi eval suite"
-```
-
-If there were no fixes after the last feature commit, do not create an empty commit.
-
-## Task 8: Run Live Smoke And Full Eval
-
-**Files:**
-
-- Local output only under `packages/benchmark-results/live/pi-eval/`.
-
-- [ ] **Step 1: Run a small live smoke**
-
-Run from `caplets-mono` root:
-
-```bash
-pnpm --dir ./core run build &&
-CAPLETS_BENCH_LIVE=1 pnpm --dir ./core run benchmark:live:pi-eval -- \
-  --task-suite mcp-tool-use \
-  --mode caplets-code-mode,vanilla-mcp \
-  --tasks incident-customer-impact-join \
-  --model openai-codex/gpt-5.5 \
-  --runs 1 \
-  --concurrency 2
-```
-
-Expected:
-
-- one report JSON and one markdown report are written
-- both modes complete without timeout
-- both runs pass validator scoring
-- no `--preserve-artifacts` disk growth
-
-- [ ] **Step 2: Inspect the report for total-token comparison**
-
-Open the generated markdown path printed by the command and check:
-
-- `Suite: MCP tool-use workflows`
-- `Avg provider tokens` is present
-- validator summary has no failures
-- total provider tokens are visible for both modes
-
-- [ ] **Step 3: Run the full live eval**
-
-Run from `caplets-mono` root:
-
-```bash
-pnpm --dir ./core run build &&
-CAPLETS_BENCH_LIVE=1 pnpm --dir ./core run benchmark:live:pi-eval -- \
-  --task-suite mcp-tool-use \
-  --model openai-codex/gpt-5.5 \
-  --runs 4 \
-  --concurrency 8
-```
-
-Expected:
-
-- all selected modes run across all three MCP tool-use tasks
-- no preserved temp roots are left by routine execution
-- `caplets-progressive`, `caplets-code-mode`, and `caplets-progressive-code-mode` have successful runs
-- comparisons use total provider tokens, not request tokens alone
-
-- [ ] **Step 4: Summarize results**
-
-Record in the final implementation handoff:
-
-- report JSON path
-- report markdown path
-- pass counts by mode
-- average provider tokens by mode
-- whether Caplets progressive/code-mode variants beat `vanilla-mcp` and `executor-mcp`
-- any environment failures separated from product failures
-
-## Self-Review Checklist
-
-- The plan keeps `coding` as the default suite and does not change current benchmark behavior unless `--task-suite mcp-tool-use` is passed.
-- The plan uses local deterministic MCP fixtures and does not depend on MCP-Bench runtime services, external API keys, or judge models.
-- The plan validates final answer facts, evidence, and distractor rejection for the new suite.
-- The plan keeps total provider tokens as the primary efficiency signal and adds provider-token comparison output.
-- The plan runs `pnpm --dir ./core run build` before live eval measurement.
-- The plan avoids `--preserve-artifacts` for routine live eval iteration.
-- The plan commits after each independently testable implementation stage.
diff --git a/docs/plans/2026-06-11-real-world-large-mcp-pi-eval.md b/docs/plans/2026-06-11-real-world-large-mcp-pi-eval.md
deleted file mode 100644
index 79e83876..00000000
--- a/docs/plans/2026-06-11-real-world-large-mcp-pi-eval.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# Real World Large MCP Pi Eval Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a `mcp-real-world-large` Pi eval suite that compares Caplets against vanilla MCP with a large stack of real MCP servers instead of benchmark MCP fixture servers.
-
-**Architecture:** Keep the existing `benchmark:live:pi-eval` command and mode matrix. Add a suite-level real-server profile that builds the same MCP server map for Caplets and `pi-mcp-adapter`, with a seeded temporary workspace for local servers and clear env preflight for authenticated services.
-
-**Tech Stack:** TypeScript, Vitest, Pi eval harness, Caplets MCP config, `pi-mcp-adapter`, real MCP servers for GitHub, Context7, DeepWiki, Git, Filesystem, Playwright, ast-grep, language-server, and DuckDuckGo.
-
----
-
-### Task 1: Add Real MCP Suite Metadata
-
-**Files:**
-
-- Modify: `core/packages/benchmarks/lib/pi-eval/suites.ts`
-- Modify: `core/packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Add `mcp-real-world-large` to `PI_EVAL_SUITE_IDS`.
-- [ ] Extend `PiEvalSuite` with optional `requiredEnv` and `realMcpServers`.
-- [ ] Define `realWorldLargeServers = ["github", "context7", "deepwiki", "git", "filesystem", "playwright", "ast_grep", "language_server", "duckduckgo"]`.
-- [ ] Set `requiredEnv: ["GH_TOKEN", "CONTEXT7_API_KEY"]`.
-- [ ] Add tests that `parsePiEvalArgs(["--task-suite", "mcp-real-world-large"])` selects the new default tasks and `resolvePiEvalSuite("mcp-real-world-large")` exposes the real-server metadata.
-
-### Task 2: Generate Real MCP Configs For Caplets And Vanilla
-
-**Files:**
-
-- Modify: `core/packages/benchmarks/lib/pi-eval/config.ts`
-- Modify: `core/packages/benchmarks/run-pi-eval.ts`
-- Modify: `core/packages/benchmarks/test/benchmark.test.ts`
-
-- [ ] Add an optional `mcpServers` input to `createCapletsPiEvalRunConfig`, `createVanillaMcpPiEvalRunConfig`, and `createVanillaMcpAdapterConfig`.
-- [ ] When `mcpServers` is supplied, do not copy a fixture server and do not call `createBenchmarkFixtureMcpServers`.
-- [ ] Pass `candidateWorkspace` and `suite.realMcpServers` into `createPiEvalRunConfig`.
-- [ ] Validate `suite.requiredEnv` before starting jobs.
-- [ ] Include `realMcpServers` in the report suite metadata.
-- [ ] Add tests proving the same real server map is used by Caplets and vanilla, and missing required env fails clearly.
-
-### Task 3: Add Real World Workspace And Tasks
-
-**Files:**
-
-- Create: `core/packages/benchmarks/fixtures/mcp-real-world-large-workspace/package.json`
-- Create: `core/packages/benchmarks/fixtures/mcp-real-world-large-workspace/tsconfig.json`
-- Create: `core/packages/benchmarks/fixtures/mcp-real-world-large-workspace/src/release-risk.ts`
-- Create: `core/packages/benchmarks/fixtures/mcp-real-world-large-workspace/src/feature-flags.ts`
-- Create: `core/packages/benchmarks/fixtures/mcp-real-world-large-workspace/docs/runbook.md`
-- Create: `core/packages/benchmarks/fixtures/mcp-real-world-large-workspace/docs/dependency-upgrade.md`
-- Create: `core/packages/benchmarks/fixtures/mcp-real-world-large-workspace/web/index.html`
-- Create: `core/packages/benchmarks/fixtures/mcp-real-world-large-workspace/.lsp-mcp.jsonc`
-- Create: `core/packages/benchmarks/fixtures/mcp-real-world-large/tasks.json`
-
-- [ ] Seed a small but realistic TypeScript workspace for local Git, Filesystem, ast-grep, LSP, and Playwright.
-- [ ] Add five tasks that require cross-server evidence:
-  - `real-release-risk-brief`
-  - `dependency-docs-migration-check`
-  - `code-navigation-impact-brief`
-  - `browser-runbook-verification`
-  - `public-repo-architecture-scout`
-- [ ] Keep prompts read-only and require the same final JSON shape as the existing MCP tool-use suites.
-
-### Task 4: Verify
-
-**Files:**
-
-- Modify as needed from prior tasks.
-
-- [ ] Run `pnpm --filter @caplets/benchmarks test -- test/benchmark.test.ts`.
-- [ ] Run `pnpm --filter @caplets/benchmarks typecheck`.
-- [ ] Run `pnpm --filter @caplets/benchmarks benchmark:check` if the focused checks pass.
diff --git a/docs/product/caplets-code-mode-prd.md b/docs/product/caplets-code-mode-prd.md
new file mode 100644
index 00000000..0755719d
--- /dev/null
+++ b/docs/product/caplets-code-mode-prd.md
@@ -0,0 +1,131 @@
+# Caplets Code Mode PRD
+
+## Summary
+
+Caplets gives coding agents a compact Code Mode surface for MCP servers, APIs, and commands. Each configured backend becomes a typed `caplets.<id>` handle that an agent can inspect, search, call, filter, join, and summarize inside one TypeScript workflow.
+
+Progressive discovery remains available for clients or workflows that need visible wrapper tools, and direct exposure remains available for selected MCP resources, prompts, and tools. Code Mode is the default backend exposure because it keeps discovery, execution, filtering, and synthesis in one bounded agent call.
+
+Source code is the source of truth. This PRD captures product intent and should be updated or deleted when it no longer matches `packages/core`, generated schemas, tests, and benchmark code.
+
+## Problem
+
+Large MCP and API setups give agents too much surface area too early:
+
+- Flat tool lists inflate initial context and create duplicate names.
+- Agents choose tools before they understand the capability domain.
+- Multi-step discovery produces repeated model/tool round trips.
+- Schema-less or generic outputs make agents over-carry raw payloads.
+- Local, remote, Cloud, and native agent integrations need the same capability model.
+
+Caplets should make backends usable as capability domains without hiding the exact operations, schemas, resources, prompts, results, or errors that agents need to complete work.
+
+## Goals
+
+- Make Code Mode the primary agent surface for configured backends.
+- Preserve progressive discovery for clients and workflows that benefit from visible wrapper tools.
+- Preserve direct MCP access for explicitly exposed tools, resources, resource templates, and prompts.
+- Keep downstream calls lossless enough for agents to cite evidence and recover from errors.
+- Keep secrets redacted while exposing enough auth and status detail for debugging.
+- Support local, self-hosted remote, and hosted Cloud routes through the same capability semantics.
+- Keep benchmark claims reproducible, with live results clearly marked as environment-dependent.
+
+## Non-Goals
+
+- Do not claim Code Mode is a sandbox security boundary.
+- Do not flatten every downstream tool into the initial tool list by default.
+- Do not make progressive discovery the product frame; it is one supported exposure mode.
+- Do not require hosted Cloud for local Caplets usage.
+- Do not expose arbitrary shell access through CLI-backed Caplets.
+- Do not treat live benchmark runs as deterministic product claims.
+
+## User Surfaces
+
+### CLI
+
+The `caplets` package installs the CLI. Important commands include:
+
+- `caplets setup` for Codex, Claude Code, OpenCode, Pi, or generic MCP client setup.
+- `caplets serve` for a local MCP server.
+- `caplets attach` for a remote-backed MCP server and Project Binding session.
+- `caplets install` for shared Caplet files.
+- `caplets add` for MCP, OpenAPI, GraphQL, HTTP, and CLI-backed Caplets.
+- `caplets code-mode` and `caplets code-mode types` for Code Mode inspection and debugging.
+- `caplets doctor` for config, auth, exposure, Code Mode, and Project Binding diagnostics.
+
+### MCP Clients
+
+`caplets serve` registers a `code_mode` MCP tool when any configured backend resolves to Code Mode exposure. Progressive wrapper tools and direct tools are registered only for Caplets whose exposure policy enables those surfaces.
+
+### Native Integrations
+
+OpenCode and Pi use the native service from `@caplets/core/native`. They expose `caplets__code_mode` for Code Mode, `caplets__<id>` tools for progressive exposure, and operation-level `caplets__<id>__<operation>` tools for direct exposure. Native integrations share the same local, remote, and Cloud selection rules as the CLI.
+
+### Remote And Cloud
+
+Self-hosted remotes use `CAPLETS_MODE=remote` with `CAPLETS_REMOTE_URL` and token or Basic Auth credentials. Hosted Cloud uses `CAPLETS_MODE=cloud`, `CAPLETS_REMOTE_URL`, and saved `caplets cloud auth login` credentials. Project Binding connects a local project root to a remote runtime when Cloud or remote workflows need project-local files.
+
+## Capability Model
+
+Caplets load backends from user config, project config, and Markdown Caplet files. Backends currently include:
+
+- MCP servers.
+- OpenAPI endpoints.
+- GraphQL endpoints.
+- Explicit HTTP APIs.
+- Curated CLI tools.
+- Nested Caplet sets.
+
+Each Caplet has stable identity, name, description, optional hints, source metadata, auth posture, and an exposure policy. Source precedence favors project-local Caplets over user/global Caplets, and inspection surfaces expose source and shadowing information.
+
+## Code Mode Contract
+
+Code Mode runs TypeScript with generated `caplets.<id>` handles. Handles expose:
+
+- `inspect()` and `check()` for capability and readiness.
+- `tools()` and `searchTools()` for discovery.
+- `describeTool()` for exact schemas, call signatures, examples, and observed output shapes.
+- `callTool()` for execution.
+- MCP-only resource, template, prompt, and completion methods where supported.
+- `caplets.debug.readLogs()` for stored Code Mode log inspection when available.
+
+Agents should keep bulky discovery and raw payload handling inside the Code Mode script, then return compact decision-ready JSON with the evidence fields needed by the user.
+
+## Exposure Modes
+
+The global default is `code_mode`. Per-Caplet exposure can override the default.
+
+Supported exposure values are:
+
+- `code_mode`
+- `progressive`
+- `direct`
+- `progressive_and_code_mode`
+- `direct_and_code_mode`
+
+Progressive exposure registers one wrapper tool per Caplet and supports scoped operations such as `inspect`, `tools`, `search_tools`, `describe_tool`, and `call_tool`. Direct exposure registers downstream MCP tools, resources, resource templates, and prompts directly when discovery can resolve them safely.
+
+## Trust And Safety
+
+- Config and Caplet files are schema-validated.
+- Backends enforce timeouts and bounded response sizes.
+- CLI-backed Caplets spawn declared commands without shell interpolation.
+- HTTP-like backends reject unsafe base URLs and redact configured secrets from errors.
+- OAuth/OIDC tokens are stored outside config and loaded lazily.
+- Project Binding sync filters deny dangerous directories, private keys, unsafe env files, caches, build outputs, and ignored files.
+- Progressive discovery and Code Mode are context-management tools, not permission boundaries.
+
+## Evidence
+
+The deterministic benchmark in `docs/benchmarks/coding-agent.md` remains the reproducible context-surface claim. It compares flat MCP exposure against Caplets capability exposure over local mock MCP metadata.
+
+The same report includes a deterministic Code Mode workflow fixture showing fewer model/tool round trips than equivalent progressive sequences, with required evidence fields preserved.
+
+Live Pi evals compare Caplets modes against vanilla MCP and Executor in opt-in, model-dependent runs. They are useful for product direction and regression discovery, but they are not deterministic release claims.
+
+## Current Open Questions
+
+- Which Code Mode result-shaping hints should become stable public contract versus internal prompt guidance?
+- How much direct exposure should be enabled by default for clients that support resources and prompts well?
+- Which Cloud runtime and Project Binding semantics should move from implementation detail to public product contract?
+- Which historical benchmark suites should remain supported as long-term regression tests versus local research harnesses?
diff --git a/docs/product/caplets-progressive-mcp-disclosure-prd.md b/docs/product/caplets-progressive-mcp-disclosure-prd.md
deleted file mode 100644
index 2827489d..00000000
--- a/docs/product/caplets-progressive-mcp-disclosure-prd.md
+++ /dev/null
@@ -1,669 +0,0 @@
-# Caplets Progressive MCP Disclosure PRD
-
-## 1. Executive Summary
-
-**Problem Statement**: MCP clients that connect directly to many servers receive a large, flat tool surface up front. This creates context bloat, weak tool selection, name-collision risk, and poor discoverability when an agent only needs to know which capability domain to inspect next.
-
-**Proposed Solution**: Caplets is a local MCP server that reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, explicit HTTP API action definitions, and explicit CLI tool/action definitions from `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows, user-owned Markdown Caplet files from the user Caplets root, project config from `./.caplets/config.json`, and project Markdown Caplet files from `./.caplets`. Project sources load by default and override global/user sources with the same Caplet ID, while inspection commands expose source metadata and shadow warnings. It exposes each enabled Caplet as one top-level, skill-like MCP tool. Each generated Caplet tool uses the Caplet ID as the tool name and the configured `name`/`description` as its compact capability card, then progressively discloses the full Caplet card and the backing MCP tools, OpenAPI operations, GraphQL operations, HTTP actions, or CLI tools/actions through operations such as `inspect`, `search_tools`, `tools`, `describe_tool`, and `call_tool`.
-
-**Success Criteria**:
-
-- Initial Caplets `tools/list` response exposes one tool per enabled downstream server and is at least 70% smaller than direct aggregation for a fixture containing 5 downstream servers and 50 total downstream tools.
-- Agents can discover and invoke the correct downstream tool in <= 3 Caplets tool calls for at least 90% of benchmark tasks.
-- Caplets preserves downstream MCP tool results without lossy transformation in 100% of protocol-compatible test fixtures.
-- Misconfigured, unavailable, or failing downstream servers return structured Caplets errors within configured timeouts and never expose secrets.
-- MVP passes regression coverage for config validation, discovery, search, duplicate tool names, forwarding, downstream failures, and secret redaction.
-
-## 2. User Experience & Functionality
-
-### User Personas
-
-- **Agent power user**: Runs multiple MCP servers locally and wants less tool flooding in agent clients.
-- **AI tool builder**: Wants to expose curated capability domains without writing custom MCP proxy code for every downstream server.
-- **MCP server author**: Wants their server to remain available through standard MCP semantics while benefiting from better capability-level discovery.
-
-### Primary User Flow
-
-1. User installs and configures Caplets as an MCP server in their MCP client.
-2. User creates either `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows with downstream server, OpenAPI endpoint, GraphQL endpoint, HTTP API action, or CLI tool/action definitions and Caplets options, or Markdown Caplet files with exactly one executable backend.
-3. Each downstream MCP server, OpenAPI endpoint, GraphQL endpoint, HTTP API, CLI tool/action set, or Caplet file uses the supported backend configuration shape plus a required `description`.
-4. Client calls Caplets `tools/list` and sees one top-level tool per enabled downstream server, for example `linear`, `chrome-devtools`, and `context7`.
-5. Agent chooses the relevant Caplet tool based on its skill-like tool name and description.
-6. Agent calls that Caplet tool with an operation such as `inspect`, `search_tools`, `tools`, or `describe_tool`.
-7. Agent calls the same Caplet tool with `operation: "call_tool"`, an exact downstream `name`, and a JSON object of `args`.
-8. Caplets forwards the request to that server's downstream MCP process or executes the selected OpenAPI, GraphQL, explicit HTTP action, or explicit CLI action and returns the result.
-
-### User Stories
-
-**Story 1**: As an agent power user, I want Caplets to show my MCP servers by name and description first so that agents choose a capability domain before seeing every tool.
-
-Acceptance Criteria:
-
-- Caplets reads `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows by default.
-- Caplets reads user-owned Markdown Caplet files from `${XDG_CONFIG_HOME:-~/.config}/caplets` on Unix-like platforms or `%APPDATA%\caplets` on Windows by default.
-- Caplets reads project Markdown Caplet files from `./.caplets` by default.
-- Project config and project Markdown Caplet files override global/user sources with the same Caplet ID.
-- `caplets list` and source inspection output expose the winning source and warn when a project source shadows a global/user source.
-- Caplets supports `mcpServers` for MCP backends, `openapiEndpoints` for native OpenAPI backends, `graphqlEndpoints` for native GraphQL backends, `httpApis` for explicitly configured HTTP actions, and `cliTools` for explicitly configured CLI tools.
-- Generated top-level tool names are unique across `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, `httpApis`, `cliTools`, and Markdown Caplet files; duplicate IDs reject with `CONFIG_INVALID`.
-- Every configured server requires a stable server key and non-empty `description`.
-- Caplets `tools/list` returns one generated top-level MCP tool per enabled server.
-- Each generated Caplet tool uses the configured server ID as the MCP tool name.
-- Each generated Caplet tool description includes the configured display `name` and Markdown-capable `description`.
-- Disabled servers are omitted from `tools/list`.
-- Caplets `tools/list` never exposes raw command arguments, env values, headers, tokens, full raw config, or downstream Caplet tools directly.
-- Caplets process startup validates config but does not block on starting every downstream server.
-- The first live operation against a generated Caplet tool starts or connects to the relevant downstream server.
-- Successfully started stdio servers stay running alongside Caplets until Caplets exits or the downstream process dies.
-- If a downstream stdio process dies, Caplets marks cached status unavailable and the next relevant operation may attempt one restart with backoff.
-- Remote HTTP/SSE servers are connected lazily and reused when supported by the MCP SDK transport.
-
-**Story 2**: As an agent, I want to list and search tools for a selected server so that I can inspect only the relevant tool surface.
-
-Acceptance Criteria:
-
-- Each generated Caplet tool supports `operation: "tools"` and returns a compact list of that server's MCP tools.
-- Each generated Caplet tool supports `operation: "describe_tool"` and returns one downstream tool's full metadata by exact downstream tool name.
-- `describe_tool` refreshes stale downstream tool metadata according to `toolCacheTtlMs` before resolving the exact downstream tool name.
-- Tool results preserve downstream `name`, `description`, `inputSchema`, and annotations when available.
-- `tools` and `search_tools` flatten downstream safety annotations into compact `readOnlyHint` and `destructiveHint` fields when present; `describe_tool` preserves full downstream metadata.
-- `operation: "search_tools"` supports deterministic case-insensitive lexical search across that server's downstream tool names and descriptions.
-- `search_tools` is scoped to the selected generated Caplet tool; MVP does not provide cross-Caplet tool search because `tools/list` is already the server discovery layer.
-- `search_tools` supports an optional `limit`, defaults to 20 results, and rejects values above 50.
-- `search_tools` uses fresh cached tool metadata from that server's managed downstream process and starts that server if needed.
-- Duplicate downstream tool names across different servers are supported because tool names are only resolved inside a generated Caplet tool.
-
-**Story 3**: As an agent, I want to call an underlying tool through Caplets so that I can use downstream MCP capabilities without connecting to each server directly.
-
-Acceptance Criteria:
-
-- `operation: "call_tool"` requires exact downstream `name` and a JSON object `args`.
-- For OpenAPI-backed Caplets, `call_tool.args` uses grouped HTTP inputs: `path`, `query`, `header`, and `body`.
-- For GraphQL-backed Caplets, configured operation `call_tool.args` is the GraphQL variables object directly; auto-generated operation `call_tool.args` is the root field arguments object directly.
-- For HTTP action Caplets, `call_tool.args` is the action input object directly; path placeholders read top-level argument fields and configured request mappings can reference `$input.field` or `$input`.
-- For CLI-backed Caplets, `call_tool.args` is the configured CLI action input object directly; Caplets maps those fields into configured argv, environment, stdin, or working-directory templates without shell interpolation.
-- `call_tool` requires the exact downstream tool name; Caplets does not use fuzzy matching, aliases, or auto-correction for execution.
-- The selected generated Caplet tool is the server namespace, so `call_tool` does not accept a `server` argument in MVP.
-- Caplets preserves downstream tool names exactly and does not support flattened namespaced identifiers such as `server.tool` in MVP.
-- Caplets forwards calls to downstream MCP `tools/call` using the selected server connection.
-- Before `call_tool` resolves the exact downstream tool name, Caplets refreshes stale downstream tool metadata according to `toolCacheTtlMs`.
-- `call_tool` requires the requested downstream tool to appear in fresh-enough cached `tools/list` metadata before forwarding; absent tools return `TOOL_NOT_FOUND` and are not forwarded.
-- Unknown operation, unknown tool, malformed Caplets request shape, startup timeout, call timeout, and downstream protocol failure return structured errors.
-- Malformed generated-server-tool payloads use `REQUEST_INVALID`, including missing required operation fields, invalid field types, invalid `call_tool.args`, and operation-specific extra fields.
-- Extra fields that do not belong to the selected operation are malformed Caplets request shapes and must be rejected rather than ignored.
-- Caplets does not perform heavy local validation of downstream tool arguments; once routing fields are valid, the selected downstream MCP server remains the source of truth for argument validation and tool semantics.
-- `TOOL_NOT_FOUND` may include nearby same-server suggestions for debugging, but suggestions are informational only and must never be invoked automatically.
-- Downstream tool results are returned without lossy transformation, including text, structured content, images, resource links, and `isError` when supported by the SDK/protocol.
-- Tool names are resolved only within the selected server namespace.
-
-**Story 4**: As a user, I want configuration failures to be obvious and safe so that I can fix setup issues without leaking credentials.
-
-Acceptance Criteria:
-
-- Caplets validates config with clear errors before serving discovery results.
-- Unsupported transports or unsupported config fields produce actionable validation messages.
-- Each generated Caplet tool supports `operation: "check"`, verifies or starts/connects to that managed downstream server if needed, calls downstream `tools/list`, refreshes cached status and tool metadata, and returns server availability status, tool count when available, safe error details when unavailable, and elapsed timing data.
-- `check` must not invoke any downstream tool.
-- Env values, tokens, headers, and secret-looking fields are redacted from errors and logs.
-- Downstream server startup has a default timeout of 10 seconds and can be overridden per server.
-- Tool calls have a default timeout of 60 seconds and can be overridden per server.
-
-**Story 5**: As a user, I want to authenticate remote HTTP/SSE MCP servers from the Caplets CLI so that OAuth-backed servers can be used without putting access tokens in config.
-
-Acceptance Criteria:
-
-- `caplets auth login <server>` performs OAuth setup for configured remote servers with `auth.type: "oauth2"`.
-- The command opens a browser-based authorization code flow with PKCE and receives the callback on a loopback URL.
-- `caplets auth login <server> --no-open` supports headless terminals and remote shells by printing the authorization URL and accepting manual completion input.
-- Successful auth writes a token bundle to `${XDG_STATE_HOME:-~/.local/state}/caplets/auth/<server>.json` on Unix-like platforms or `%LOCALAPPDATA%\caplets\auth\<server>.json` on Windows using owner-only file permissions where supported.
-- The Caplets MCP server uses stored OAuth tokens for subsequent HTTP/SSE requests without exposing tokens through MCP tools, generated descriptions, logs, or errors.
-- Auth failures are reported with structured, redacted errors.
-- Re-running `caplets auth login <server>` replaces the stored token bundle for that server atomically.
-- `caplets auth list` lists configured remote OAuth servers and safe token status without printing access tokens, refresh tokens, or raw token-store contents.
-- `caplets auth logout <server>` deletes the stored token bundle for a configured remote OAuth server.
-
-### MVP Tool Surface
-
-Caplets exposes dynamic MCP tools:
-
-- One top-level MCP tool per enabled configured server.
-- The generated MCP tool name is the configured server ID, for example `linear`, `chrome-devtools`, or `context7`.
-- Caplets does not prefix generated tool names in MVP; the server ID is the MCP tool name exactly.
-- The generated MCP tool description is the full server capability card, built from configured `name` and exact configured `description`.
-- Generated tool descriptions append a short standard protocol hint, roughly: `Use this tool to inspect and call tools from the {server} MCP server. Start with search_tools or tools; use describe_tool for schema; use call_tool to invoke.`
-- The standard protocol hint should stay under 35 words.
-- Disabled servers are omitted from Caplets `tools/list`.
-- Caplets does not expose every downstream tool directly in its own `tools/list`.
-
-Each generated Caplet tool supports these operations:
-
-- `inspect`: Returns the full configured capability card for the selected server without starting the downstream process.
-- `check`: Validates that the selected backend is available. For MCP it checks the downstream tool list; for OpenAPI it validates the spec and executable base URL without invoking an operation.
-- `check`: Validates that the selected downstream server can start, initialize, and return its tool list without invoking any downstream tool.
-- `tools`: Lists compact downstream tool entries for the selected server.
-- `search_tools`: Searches downstream tools for the selected server. Supports optional `limit`, defaults to 20 results, and rejects values above 50.
-- `describe_tool`: Returns full metadata for one exact downstream tool.
-- `call_tool`: Invokes one exact downstream tool with a JSON object of `args`.
-
-Generated Caplet tool input schema:
-
-- `operation` is required and must be one of `inspect`, `check`, `tools`, `search_tools`, `describe_tool`, or `call_tool`.
-- `inspect` accepts no extra fields.
-- `inspect` returns only configured capability-card data and does not start, initialize, or probe the downstream server.
-- `check` accepts no extra fields.
-- `check` accepts no extra fields.
-- `tools` accepts no extra fields.
-- `search_tools` requires `query` and accepts optional `limit`.
-- `describe_tool` requires `name`.
-- `call_tool` requires `name` and `args`; `args` must be a JSON object and is not optional.
-- `name` fields are plain strings, not enums of downstream tool names.
-- Generated Caplet tool schemas must remain stable even when downstream tool lists change.
-- Unknown operations return `UNKNOWN_OPERATION`.
-- Operation-specific request validation is strict: fields not defined for the selected `operation` are rejected as malformed Caplets request shapes.
-
-### Configuration
-
-MVP supports one documented user config file at `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows:
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplets-config.schema.json",
-  "version": 1,
-  "defaultSearchLimit": 20,
-  "maxSearchLimit": 50,
-  "mcpServers": {
-    "filesystem": {
-      "name": "Project Files",
-      "description": "Read, search, and edit local project files.",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/ianpascoe/code"],
-      "env": {
-        "EXAMPLE_TOKEN": "${EXAMPLE_TOKEN}"
-      },
-      "cwd": "/home/ianpascoe/code",
-      "startupTimeoutMs": 10000,
-      "callTimeoutMs": 60000,
-      "toolCacheTtlMs": 30000,
-      "disabled": false
-    },
-    "remote-docs": {
-      "name": "Remote Docs",
-      "description": "Search hosted documentation through a remote Streamable HTTP MCP server.",
-      "transport": "http",
-      "url": "https://mcp.example.com/mcp",
-      "auth": {
-        "type": "oauth2",
-        "clientId": "$env:REMOTE_DOCS_CLIENT_ID",
-        "authorizationUrl": "https://mcp.example.com/oauth/authorize",
-        "tokenUrl": "https://mcp.example.com/oauth/token",
-        "scopes": ["mcp:tools"]
-      },
-      "callTimeoutMs": 60000,
-      "toolCacheTtlMs": 30000
-    }
-  }
-}
-```
-
-Requirements:
-
-- `mcpServers` is optional when one or more valid Markdown Caplet files are present.
-- `$schema` is optional and exists only for JSON Schema-aware editor validation.
-- `version` is optional for MVP and defaults to 1 when omitted. If present, MVP accepts only `1` and rejects unsupported versions with `CONFIG_INVALID`.
-- Allowed top-level keys in MVP are `$schema`, `version`, `defaultSearchLimit`, `maxSearchLimit`, `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, `httpApis`, `cliTools`, and `capletSets`; unknown top-level keys are rejected with `CONFIG_INVALID`.
-- The committed JSON Schema lives at `schemas/caplets-config.schema.json`, is generated from the Zod runtime config schema, and CI must fail when the committed schema drifts from the generated output.
-- Unknown keys inside each server config are rejected with `CONFIG_INVALID`, except fields that belong to the tracked standard MCP server schema plus Caplets-owned additions documented here.
-- `mcpServers` is the only accepted top-level server configuration key for plain JSON downstream MCP servers in MVP.
-- `defaultSearchLimit` and `maxSearchLimit` are optional top-level Caplets options. Future Caplets options should remain top-level unless they are specific to one downstream server.
-- Caplets' native config shape follows the shared/standard `mcpServers` convention used by tools such as Pi's MCP adapter, with Caplets-specific metadata added per server.
-- Each server key is the stable server ID. It must match `^[a-zA-Z0-9_-]{1,64}$` and be unique within the file.
-- The server ID becomes the generated MCP tool name exactly.
-- Valid example IDs include `linear`, `chrome-devtools`, and `context7`. Spaces, dots, slashes, colons, and Unicode are rejected in MVP.
-- `name` is required, human-readable display text for discovery responses, and must be 1-80 characters.
-- Discovery responses must clearly distinguish `server` as the stable routing ID from `name` as display-only text.
-- `description` is required and must be at least 10 non-whitespace characters.
-- `description` must be at most 1500 characters and is returned exactly as configured.
-- `description` may contain Markdown syntax because the primary reader is an LLM, but MVP treats it as opaque text: Caplets does not render, sanitize, transform, or interpret Markdown.
-- Caplets should reuse or closely track existing MCP server config validation semantics where practical rather than inventing a new dialect.
-- Markdown Caplet files are executable configuration because they require exactly one backend among `mcpServer`, `openapiEndpoint`, `graphqlEndpoint`, `httpApi`, `cliTools`, or `capletSet`, and some backends can start downstream processes. User Caplet files are trusted by location, and project Caplet files load by default from the current project's `./.caplets` directory. When a project Caplet shadows a global/user Caplet, CLI inspection must make the winning project source and shadowed source visible.
-- Each server config must define exactly one connection shape:
-  - Stdio: `command` is required; optional `args`, `env`, and `cwd` are allowed.
-  - Remote: `url` is required and `transport` must be `http` or `sse`.
-- `transport` defaults to `stdio` when `command` is present. For remote servers, `http` means MCP Streamable HTTP and is preferred; `sse` means the legacy HTTP+SSE transport for compatibility.
-- Remote `url` must be `https://` except loopback development URLs such as `http://localhost`, `http://127.0.0.1`, and `http://[::1]`.
-- `startupTimeoutMs`, `callTimeoutMs`, `toolCacheTtlMs`, and `disabled` are optional for all transports.
-- `env` interpolation should align with existing MCP client practice where possible. MVP should support Pi-style `${VAR}` and `$env:VAR` references for config values that carry secrets, resolving from Caplets' process environment and redacting resolved values everywhere.
-- The same interpolation and redaction rules apply to remote `url`, auth tokens, auth headers, OAuth client credentials, and OAuth token fields.
-- Caplets must not support shell command substitution for MCP server config values in MVP.
-- Remote server auth supports `auth.type: "none" | "bearer" | "headers" | "oauth2"`:
-  - `none`: no additional auth material.
-  - `bearer`: requires `token`; Caplets sends `Authorization: Bearer <token>` on every HTTP/SSE request and never places tokens in query strings.
-  - `headers`: requires a `headers` object of static string headers, intended for non-standard API-key schemes. Caplets validates header names, rejects hop-by-hop or transport-controlled headers, interpolates values, and redacts values everywhere.
-  - `oauth2`: supports interactive OAuth for MCP-compliant HTTP/SSE servers through `caplets auth login <server>`. MVP accepts optional `authorizationUrl`, `tokenUrl`, `issuer`, `clientId`, `clientSecret`, `scopes`, and `redirectUri`; Caplets sends bearer access tokens on every HTTP/SSE request.
-- `caplets auth login <server>` is the required MVP user flow for OAuth-backed remote servers unless valid tokens already exist in the Caplets auth store.
-- `caplets auth login <server>` validates that `<server>` is a configured remote server with `auth.type: "oauth2"`, discovers or reads authorization metadata, starts an OAuth authorization code flow with PKCE, opens the user's browser, listens on a loopback callback URL, exchanges the code for tokens, and writes the token bundle to Caplets' local auth store.
-- `caplets auth login <server> --no-open` must print the authorization URL and allow the user to paste the final callback URL, authorization code, or provider-issued authorization token into the CLI. It may also continue listening on the loopback callback URL when practical.
-- Manual OAuth completion must validate `state`, apply the stored PKCE verifier, reject mismatched callback URLs or codes, and redact pasted secrets from logs and errors.
-- OAuth authorization requests must include a state parameter and PKCE challenge. OAuth token requests must verify state and include the PKCE verifier.
-- For MCP-compliant OAuth servers, Caplets must include the target server resource indicator in authorization and token requests when required by the MCP authorization specification.
-- The default OAuth token store is `${XDG_STATE_HOME:-~/.local/state}/caplets/auth/<server>.json` on Unix-like platforms or `%LOCALAPPDATA%\caplets\auth\<server>.json` on Windows; files must be created with owner-only permissions when the platform supports it.
-- Relative `XDG_CONFIG_HOME` and `XDG_STATE_HOME` values are ignored.
-- Token bundles are runtime auth state, not server description state. They must not be embedded in generated MCP tool descriptions, `inspect`, logs, or structured errors.
-- The Caplets MCP server reads OAuth tokens from the auth store lazily before remote operations. Updating tokens with `caplets auth login <server>` should not require editing config and should be designed to work without restarting Caplets when practical.
-- `caplets auth list` reports configured OAuth remote servers as missing, authenticated, or expired and must not enumerate arbitrary orphan token files outside the configured server set.
-- `caplets auth logout <server>` removes the local token bundle for a configured OAuth remote server and is allowed even when the server is currently disabled.
-- Caplets may refresh expired OAuth tokens when a refresh token and token endpoint are available, and should persist refreshed token bundles atomically back to the auth store.
-- If OAuth metadata is not fully configured, `caplets auth login <server>` should use MCP/OAuth discovery where available, including safe handling of `WWW-Authenticate` metadata from the remote server.
-- HTTP 401/403 responses from remote servers return structured auth errors with safe challenge metadata when available. Caplets must parse `WWW-Authenticate` enough to classify auth-required/auth-failed cases without leaking credentials.
-- Remote auth error payloads use safe fields only: `server`, `status`, `message`, `authType`, optional redacted `challenge`, and optional `nextAction: "run_caplets_auth_login"`.
-- Streamable HTTP clients must preserve MCP protocol-version and session semantics, including `MCP-Protocol-Version` and `Mcp-Session-Id` behavior, through the official SDK transport where possible.
-- `toolCacheTtlMs` defaults to 30000. `0` means refresh downstream `tools/list` on every metadata operation.
-- `describe_tool` and `call_tool` must ensure cached downstream tool metadata is fresh enough according to `toolCacheTtlMs` before exact downstream tool-name resolution.
-- `call_tool` must resolve against fresh-enough downstream `tools/list` metadata and must not forward a call for a tool absent from that metadata in MVP.
-- `disabled` defaults to false. Disabled servers are omitted from normal discovery, never appear in search results, are never started, and cannot be inspected or invoked until re-enabled and Caplets is restarted.
-- Disabled servers are omitted from generated `tools/list` to preserve the token-saving purpose of Caplets.
-- MCP backends support stdio, MCP Streamable HTTP, and legacy HTTP+SSE downstream servers. Streamable HTTP is preferred for remote servers; SSE exists for compatibility.
-- OpenAPI backends support local `specPath` or remote `specUrl`, explicit `auth`, optional `baseUrl`, and native HTTP execution for standard OpenAPI methods.
-- GraphQL backends support local `schemaPath`, remote `schemaUrl`, or endpoint introspection, configured operations, auto-generated query/mutation tools, explicit `auth`, and native GraphQL HTTP execution.
-- HTTP action backends support explicit `httpApis` config or Markdown `httpApi` frontmatter with `baseUrl`, `auth`, and one or more named actions. Each action defines `method`, `path`, optional `description`, optional `inputSchema`, and optional `query`, `headers`, and `jsonBody` mappings.
-- CLI backends support explicit `cliTools` config or Markdown `cliTools` frontmatter with one or more named actions. Each action defines a command, optional fixed args, optional description, optional inputSchema, optional argument/environment/stdin mappings, optional cwd, timeout, and output byte limits; execution must avoid shell evaluation unless explicitly modeled as a command executable.
-- Caplet set backends support explicit `capletSets` config or Markdown `capletSet` frontmatter with `configPath`, `capletsRoot`, or both. Each child Caplet is exposed as one downstream tool that accepts the normal Caplets operation schema; child collections are isolated from the parent, and recursive nesting must reject repeated source paths as cycles.
-- HTTP action `query` and `headers` mappings must resolve to object maps whose values are strings, numbers, or booleans. HTTP action `jsonBody` mappings support literal values, nested arrays/objects, `$input.field` references, and `$input` for the complete argument object. HTTP action paths may contain `{field}` placeholders resolved from top-level arguments.
-- HTTP action requests require HTTPS except loopback URLs, reject origin-changing paths and redirects, reject managed configured headers, enforce timeouts and response byte limits, and return structured `{ status, statusText, headers, body, elapsedMs }` content with `isError` set for non-2xx status.
-- OpenCode's `mcp` config shape is a compatibility reference, not Caplets' native MVP shape: OpenCode uses local/remote entries under `mcp`, local `command` as an array, `environment` instead of `env`, and `{env:NAME}`-style interpolation in its broader config system. Automatic OpenCode config import/normalization is deferred.
-
-### Non-Goals
-
-- No hosted service, SaaS registry, team sync, or remote management.
-- No GUI or config editor.
-- No attempt to standardize every MCP client config format.
-- No automatic import from other MCP clients.
-- No GUI OAuth onboarding in MVP; OAuth setup is CLI-driven through `caplets auth login <server>`.
-- No mandatory dynamic client registration in MVP. Caplets may use it when an MCP/OAuth server advertises support, but a configured `clientId` path must work.
-- No `tags` field in MVP; users can include tag-like Markdown in `description` when helpful.
-- No separate `whenToUse` or `avoidWhen` fields in MVP; users can include those sections in Markdown-formatted `description`.
-- No permissions engine, policy language, sandboxing, or general-purpose credential manager beyond the local OAuth token store required for remote MCP auth.
-- No semantic/vector search in MVP.
-- No MCP resources, prompts, sampling, elicitation, roots, or Apps support in MVP.
-- No cross-Caplet tool composition, planning, or result summarization.
-- No automatic trust scoring of downstream servers or tools.
-- No multi-user daemon mode.
-
-## 3. AI System Requirements
-
-### Tool Requirements
-
-Caplets is itself an MCP server and must implement the MCP Caplet tools surface using `@modelcontextprotocol/sdk`.
-
-Downstream interactions required for MVP:
-
-- Start stdio MCP servers from validated config on first relevant capability operation and keep successful processes running alongside the Caplets process.
-- Initialize downstream MCP clients over stdio, Streamable HTTP, or legacy HTTP+SSE with bounded concurrency and structured status for servers that fail to start or authenticate.
-- Resolve configured bearer/header auth and stored OAuth tokens before remote HTTP/SSE operations.
-- Call downstream `tools/list` for selected servers.
-- Call downstream `tools/call` for `operation: "call_tool"` inside a generated Caplet tool.
-- Execute selected OpenAPI operations, GraphQL operations, HTTP actions, and CLI actions for `operation: "call_tool"` inside a generated Caplet tool.
-- Refresh stale downstream tool metadata before `describe_tool` and `call_tool` exact-name resolution according to `toolCacheTtlMs`.
-- Require downstream tools to be present in fresh-enough `tools/list` metadata before forwarding `call_tool`.
-- Preserve downstream schemas and result content.
-- Normalize Caplets-owned errors while keeping downstream results protocol-compatible.
-
-### Progressive Disclosure Behavior
-
-Caplets must optimize the first cognitive layer for the agent:
-
-- Level 0: Caplets `tools/list` exposes only generated server/caplet tools, one per enabled downstream server.
-- Level 1: The agent selects a generated Caplet tool by server ID, display name, and description.
-- Level 2: The selected Caplet tool discloses its full capability card and downstream tool metadata through `inspect`, `tools`, `search_tools`, and `describe_tool`.
-- Level 3: The selected Caplet tool invokes one downstream tool through `operation: "call_tool"` with exact downstream `name` and a JSON object `args`.
-
-Progressive disclosure is not a security boundary. The PRD treats it as a context-management and tool-selection strategy.
-
-### Evaluation Strategy
-
-Create a benchmark fixture with at least:
-
-- 5 downstream server configs.
-- 50 total downstream tools.
-- 10 tasks that require selecting a server before tool inspection.
-- 10 tasks that require searching tools after server discovery.
-- 3 duplicate tool-name cases across different servers.
-- 1 unavailable or misconfigured server.
-
-Metrics:
-
-- Initial tool-list token reduction vs direct aggregation.
-- Tool selection accuracy.
-- Number of Caplets calls before correct invocation.
-- Timeout/error classification accuracy.
-- Secret redaction coverage.
-- Fidelity of forwarded downstream tool results.
-
-## 4. Technical Specifications
-
-### Architecture Overview
-
-Caplets runs as a local stdio MCP server.
-
-```mermaid
-flowchart LR
-  Client["MCP client / agent"] --> Caplets["Caplets MCP server"]
-  Caplets --> Config["user config"]
-  Caplets --> Registry["Server registry"]
-  Registry --> ClientManager["Lazy downstream client manager"]
-  ClientManager --> ServerA["Downstream MCP server A"]
-  ClientManager --> ServerB["Downstream MCP server B"]
-  ClientManager --> ServerC["Downstream MCP server C"]
-```
-
-Core modules:
-
-- `src/cli.ts`: CLI entrypoint, including `caplets auth login <server>` for OAuth setup.
-- `src/index.ts`: MCP server bootstrap and dynamic generated Caplet-tool registration.
-- `src/config.ts`: Config loading, schema validation, defaults, and redaction helpers.
-- `src/auth.ts`: Remote auth resolution, OAuth flow orchestration, token storage, token refresh, and auth redaction helpers.
-- `src/registry.ts`: Server metadata registry and search over server descriptions.
-- `src/downstream.ts`: Managed MCP client lifecycle, stdio process supervision, remote transport setup, timeouts, and connection reuse.
-- `src/tools.ts`: Generated server-tool operation handlers and response shaping.
-- `src/errors.ts`: Structured error codes and safe error serialization.
-
-### Data Model
-
-`CapletsConfig`:
-
-- `$schema?: string`
-- `version?: 1`
-- `defaultSearchLimit?: number`
-- `maxSearchLimit?: number`
-- `mcpServers: Record<string, CapletServerConfig>`
-- `openapiEndpoints: Record<string, OpenApiEndpointConfig>`
-- `graphqlEndpoints: Record<string, GraphQlEndpointConfig>`
-- `httpApis: Record<string, HttpApiConfig>`
-- `cliTools: Record<string, CliToolConfig>`
-- `capletSets: Record<string, CapletSetConfig>`
-
-`CapletServerConfig`:
-
-- `name: string`
-- `description: string`
-- `transport?: "stdio" | "http" | "sse"`
-- `command?: string`
-- `args?: string[]`
-- `env?: Record<string, string>`
-- `cwd?: string`
-- `url?: string`
-- `auth?: RemoteAuthConfig`
-- `startupTimeoutMs?: number`
-- `callTimeoutMs?: number`
-- `toolCacheTtlMs?: number`
-- `disabled?: boolean`
-
-`RemoteAuthConfig` and HTTP endpoint auth:
-
-- `{ type: "none" }`
-- `{ type: "bearer"; token: string }`
-- `{ type: "headers"; headers: Record<string, string> }`
-- `{ type: "oauth2"; authorizationUrl?: string; tokenUrl?: string; issuer?: string; resourceMetadataUrl?: string; authorizationServerMetadataUrl?: string; clientId?: string; clientSecret?: string; scopes?: string[]; redirectUri?: string }`
-- `{ type: "oidc"; issuer?: string; openidConfigurationUrl?: string; clientId?: string; clientSecret?: string; scopes?: string[]; redirectUri?: string }`
-
-`OpenApiEndpointConfig`:
-
-- `name: string`
-- `description: string`
-- `specPath?: string`
-- `specUrl?: string`
-- `baseUrl?: string`
-- `auth: { type: "none" } | { type: "bearer"; token: string } | { type: "headers"; headers: Record<string, string> }`
-- `requestTimeoutMs?: number`
-- `operationCacheTtlMs?: number`
-- `disabled?: boolean`
-
-`GraphQlEndpointConfig`:
-
-- `name: string`
-- `description: string`
-- `endpointUrl: string`
-- exactly one of `schemaPath?: string`, `schemaUrl?: string`, or `introspection?: true`
-- `operations?: Record<string, { document?: string; documentPath?: string; operationName?: string; description?: string }>`
-- `auth: { type: "none" } | { type: "bearer"; token: string } | { type: "headers"; headers: Record<string, string> } | { type: "oauth2" | "oidc"; ... }`
-- `requestTimeoutMs?: number`
-- `operationCacheTtlMs?: number`
-- `selectionDepth?: number`
-- `disabled?: boolean`
-
-`HttpApiConfig`:
-
-- `name: string`
-- `description: string`
-- `baseUrl: string`
-- `auth: { type: "none" } | { type: "bearer"; token: string } | { type: "headers"; headers: Record<string, string> } | { type: "oauth2" | "oidc"; ... }`
-- `actions: Record<string, { method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; path: string; description?: string; inputSchema?: Record<string, unknown>; query?: unknown; headers?: unknown; jsonBody?: unknown }>`
-- `requestTimeoutMs?: number`
-- `maxResponseBytes?: number`
-- `disabled?: boolean`
-
-`StoredOAuthTokenBundle`:
-
-- `server: string`
-- `accessToken: string`
-- `refreshToken?: string`
-- `tokenType?: string`
-- `expiresAt?: string`
-- `scope?: string`
-- `idToken?: string`
-- `issuer?: string`
-- `subject?: string`
-- `clientId?: string`
-- `metadata?: Record<string, unknown>`
-
-`CapletServerSummary`:
-
-- `server: string`
-- `name: string`
-- `description: string`
-- `disabled?: boolean`
-- `status: "disabled" | "not_started" | "starting" | "available" | "unavailable"`
-- `lastError?: SafeErrorSummary`
-
-`CapletServerDetail`:
-
-- `caplet: string`
-- `name: string`
-- `description: string`
-- `tags?: string[]`
-- `body?: string`
-- `backend: { type: "mcp"; transport: "stdio" | "http" | "sse"; disabled: boolean; startupTimeoutMs: number; callTimeoutMs: number; toolCacheTtlMs: number } | { type: "openapi"; disabled: boolean; requestTimeoutMs: number; operationCacheTtlMs: number; source: "specPath" | "specUrl" } | { type: "graphql"; disabled: boolean; requestTimeoutMs: number; operationCacheTtlMs: number; source: "schemaPath" | "schemaUrl" | "introspection"; configuredOperations: boolean } | { type: "http"; disabled: boolean; requestTimeoutMs: number; configuredActions: number } | { type: "cli"; disabled: boolean; executionTimeoutMs: number; configuredActions: number }`
-- `mcpServer?: { transport: "stdio" | "http" | "sse"; disabled: boolean; startupTimeoutMs: number; callTimeoutMs: number; toolCacheTtlMs: number }`
-
-`CapletToolRef`:
-
-- `server: string`
-- `tool: string`
-- `description?: string`
-- `inputSchema?: unknown`
-- `annotations?: unknown`
-
-`GeneratedServerToolRequest`:
-
-- `operation: "inspect" | "check" | "tools" | "search_tools" | "describe_tool" | "call_tool"`
-- `query?: string`
-- `limit?: number`
-- `name?: string`
-- `args: Record<string, unknown>`
-
-Requirements:
-
-- `name` is the exact downstream MCP tool name.
-- `call_tool.args` must be a JSON object. Missing arguments, arrays, strings, numbers, booleans, and null are malformed Caplets request shapes in MVP.
-- Operation-specific fields are exclusive to their operations. For example, `name` is invalid on `tools`, `query` is invalid on `describe_tool`, and `args` is invalid outside `call_tool`.
-- `server` is the exact configured Caplets server key and the generated top-level MCP tool name.
-- Caplets does not invent escaped, flattened, or globally unique tool names in MVP.
-- Caplets does not expose downstream tool names as enum values in generated Caplet tool input schemas.
-- `tools` returns compact downstream tool entries: `name`, `description`, `hasInputSchema`, `hasOutputSchema`, `supportsFields`, and flattened safety hints when available.
-- `describe_tool` returns full downstream metadata for one exact downstream tool in the selected server.
-- `describe_tool` and `call_tool` both use fresh-enough cached metadata for exact downstream tool-name resolution.
-- `call_tool` returns `TOOL_NOT_FOUND` without forwarding when the exact downstream tool name is absent from fresh-enough metadata.
-- `search_tools` returns compact matches by default: `name`, `description`, schema booleans, field-selection support, and flattened safety hints, but not full `inputSchema`.
-- `search_tools` results are scoped to the generated Caplet tool that was called.
-
-### Integration Points
-
-- File system: reads `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows.
-- MCP SDK server: exposes Caplets over stdio.
-- MCP SDK client: connects to downstream stdio, Streamable HTTP, and legacy HTTP+SSE servers.
-- Node child process runtime: launches configured downstream commands.
-- OpenAPI parser: loads and validates configured local or remote OpenAPI specs.
-- Native fetch: executes configured OpenAPI operations with explicit Caplets auth.
-- Native fetch: executes configured HTTP actions with explicit Caplets auth.
-- Caplets CLI: runs `caplets auth login <server>` for OAuth-backed remote servers.
-- Browser/loopback OAuth: opens the authorization URL and receives the OAuth callback on localhost for configured OAuth servers.
-- Local auth store: reads and writes OAuth token bundles under `${XDG_STATE_HOME:-~/.local/state}/caplets/auth` on Unix-like platforms or `%LOCALAPPDATA%\caplets\auth` on Windows.
-- Remote transport headers: preserves required MCP protocol-version and session headers for Streamable HTTP servers.
-
-### Error Codes
-
-Caplets errors should be structured and stable:
-
-- `CONFIG_NOT_FOUND`
-- `CONFIG_INVALID`
-- `REQUEST_INVALID`
-- `SERVER_NOT_FOUND`
-- `SERVER_UNAVAILABLE`
-- `SERVER_START_TIMEOUT`
-- `UNKNOWN_OPERATION`
-- `TOOL_NOT_FOUND`
-- `TOOL_CALL_TIMEOUT`
-- `AUTH_REQUIRED`
-- `AUTH_FAILED`
-- `AUTH_REFRESH_FAILED`
-- `DOWNSTREAM_PROTOCOL_ERROR`
-- `DOWNSTREAM_TOOL_ERROR`
-- `UNSUPPORTED_TRANSPORT`
-- `INTERNAL_ERROR`
-
-### Security & Privacy
-
-- Caplets must never expose raw env values or known credential fields in tool responses.
-- Caplets must redact secret-looking strings from logs and structured errors.
-- Caplets must never expose remote auth headers, bearer tokens, OAuth access tokens, refresh tokens, authorization codes, client secrets, or full token-store contents through MCP responses.
-- OAuth authorization codes and token responses must be handled only inside the CLI/auth layer and written only to the configured auth store.
-- OAuth access tokens must be sent to remote MCP servers only in the `Authorization` header, never in query strings.
-- Caplets must not pass through credentials received from the upstream MCP client to downstream remote MCP servers; downstream remote auth uses only the configured/stored credentials for that specific downstream server.
-- Caplets must treat downstream tool metadata and results as untrusted content.
-- Caplets must not claim that progressive disclosure prevents tool execution risk.
-- Caplets must not infer safety properties without backend evidence; compact summaries may only flatten explicit downstream/backend safety hints into `readOnlyHint` and `destructiveHint`.
-- Destructive downstream tools remain subject to the MCP client's own confirmation and trust model.
-- Downstream MCP servers remain authoritative for tool argument validation and execution semantics.
-- Caplets should avoid unnecessary restarts or repeated process churn once a downstream stdio server is successfully managed.
-- Caplets should terminate managed downstream stdio server processes when Caplets exits.
-- Caplets should cache each managed server's `tools/list` metadata for `toolCacheTtlMs` and refresh stale metadata on tool metadata operations.
-- `check` should always refresh downstream `tools/list` for the selected server and update cached metadata/status.
-
-### Testing Requirements
-
-Add automated tests for:
-
-- File system reads `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows.
-- Valid config loading from a temp home directory.
-- Optional config version defaulting to 1 and unsupported version rejection.
-- Unknown top-level and server config key rejection.
-- Server ID pattern validation.
-- Server ID validation covers allowed hyphens/underscores and rejects spaces, dots, slashes, colons, and Unicode.
-- Required display `name` validation.
-- Display name vs server ID routing behavior.
-- Generated Caplet tool operation discriminator validation.
-- Strict operation-specific request-shape validation, including rejection of extra fields on otherwise valid operations.
-- Missing config and invalid config.
-- Required `description` validation.
-- `description` maximum length validation and exact response preservation.
-- Secret redaction in validation and runtime errors.
-- Remote auth config validation for `none`, `bearer`, `headers`, and `oauth2`.
-- Header auth validation rejects hop-by-hop and transport-controlled headers.
-- OAuth token-store path derivation from server ID and owner-only file permission behavior where supported.
-- `caplets auth login <server>` success flow: loads config, validates OAuth server config, performs PKCE callback exchange against a mocked OAuth server, and stores a token bundle.
-- `caplets auth login <server> --no-open` prints the authorization URL and completes via pasted callback URL, pasted authorization code/token, or loopback callback when available.
-- Manual OAuth completion validates state/PKCE and rejects mismatched, expired, malformed, or already-used completion input.
-- `caplets auth login <server>` failure behavior for missing server, non-remote server, non-OAuth server, denied callback, token exchange failure, and secret redaction.
-- Remote HTTP/SSE clients use bearer/header/OAuth auth material without leaking it in responses or logs.
-- OAuth refresh success and failure behavior, including atomic token-store update on success and `AUTH_REFRESH_FAILED` on refresh failure.
-- Remote 401/403 classification into `AUTH_REQUIRED` or `AUTH_FAILED` with safe challenge metadata.
-- Remote auth error payload shape includes only `server`, `status`, `message`, `authType`, redacted `challenge`, and `nextAction` when relevant.
-- Streamable HTTP protocol-version and session-header behavior is covered by transport tests.
-- Generated `tools/list` exposes one safe capability card per enabled server and omits disabled servers.
-- `inspect` returns exact full server descriptions without starting, initializing, or probing downstream processes.
-- `tools` returns compact downstream tool metadata and `describe_tool` preserves full downstream tool metadata including `inputSchema`.
-- Server-scoped `search_tools` deterministic lexical matching.
-- Capped search result behavior: default `limit` 20, max `limit` 50, no pagination in MVP.
-- Server-scoped `search_tools` startup and failure behavior.
-- `check` success, unavailable server, timeout, and secret redaction behavior.
-- `toolCacheTtlMs` behavior, including default TTL, stale refresh, and `0` refresh-every-time mode.
-- `describe_tool` and `call_tool` refresh stale metadata before exact downstream tool-name resolution.
-- Disabled server behavior: omitted from generated `tools/list`, not callable, never returned by search, and never started.
-- Duplicate tool names across servers.
-- Successful `operation: "call_tool"` forwarding.
-- `call_tool` refuses to forward absent tools after fresh-enough metadata resolution and returns `TOOL_NOT_FOUND`.
-- Downstream server startup timeout.
-- Downstream process death and one-restart-with-backoff behavior.
-- Downstream tool call timeout.
-- Downstream protocol failure.
-- Unavailable server status reporting.
-
-Verification commands for implementation:
-
-```sh
-pnpm format:check
-pnpm lint
-pnpm typecheck
-pnpm test
-pnpm build
-```
-
-If no test runner exists yet, implementation must add one before claiming MVP completeness.
-
-## 5. Risks & Roadmap
-
-### Phased Rollout
-
-**MVP: Local progressive MCP gateway**
-
-- Read `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows.
-- Validate all supported backend config maps with required descriptions: `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, `httpApis`, `cliTools`, and `capletSets`.
-- Require restart after config changes while keeping config loading, registry construction, and downstream client lifecycle modular enough for later hot reload.
-- Expose one generated top-level MCP tool per enabled downstream server.
-- Support server-scoped diagnostics, tool listing, lexical search, tool metadata lookup, and explicit tool invocation through each generated Caplet tool.
-- Support managed downstream stdio server lifecycles, remote HTTP/SSE transports, startup/call timeouts, structured errors, and secret redaction.
-- Support bearer, static-header, and OAuth2 auth for remote HTTP/SSE servers.
-- Provide `caplets auth login <server>` for OAuth browser/PKCE setup and local token storage.
-- Start downstream stdio servers on first relevant capability operation rather than blocking Caplets process startup.
-- Support server-scoped tool search with fresh cached metadata and bounded startup for missing processes.
-- Add regression tests and benchmark fixture.
-
-**v1.1: Better discovery and operations**
-
-- Explicit config reload support, with `tools/list_changed` notification where appropriate.
-- Optional tags and structured usage guidance.
-- Better search ranking while remaining deterministic.
-- Health-check command for validating all configured servers.
-- Cache downstream `tools/list` results with invalidation controls.
-- OAuth device-code fallback and richer auth-store management commands such as status, refresh, and logout.
-- Optional downstream tool metadata change detection, with appropriate freshness signals or `tools/list_changed` behavior when generated top-level tool descriptions/schemas are affected.
-
-**v2.0: Broader MCP coverage**
-
-- Explore resources and prompts progressive disclosure.
-- Optional policy hooks for allow/deny decisions.
-- Optional import helpers for common MCP client config files.
-- Optional semantic search over server and tool metadata.
-
-### Technical Risks
-
-- **Config fragmentation**: MCP clients differ on config shape. MVP mitigates this by documenting and supporting exactly the configured backend keys, including `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, `httpApis`, `cliTools`, and `capletSets`.
-- **Client expectations**: Some clients may expect every downstream tool in `tools/list`. MVP intentionally exposes one generated server/caplet tool per downstream server instead.
-- **Lifecycle cost**: Keeping downstream stdio servers running improves freshness but consumes local resources and may surface startup failures earlier. MVP mitigates this with bounded startup, process reuse, status reporting, and partial failures.
-- **Unsafe downstream behavior**: Downstream tools may be destructive. MVP mitigates this by avoiding safety claims and preserving MCP client confirmation flows.
-- **Metadata quality**: Bad server descriptions weaken discovery. MVP mitigates this with required descriptions and minimum validation, then improves with tags/usage guidance in v1.1.
-- **Protocol drift**: MCP surfaces evolve. MVP constrains scope to tools and uses the official SDK to reduce compatibility risk.
-
-### Open Product Decisions
-
-- None currently unresolved for MVP scope.
diff --git a/docs/specs/2026-05-19-http-mcp-serving-design.md b/docs/specs/2026-05-19-http-mcp-serving-design.md
deleted file mode 100644
index 034652fd..00000000
--- a/docs/specs/2026-05-19-http-mcp-serving-design.md
+++ /dev/null
@@ -1,240 +0,0 @@
-# HTTP MCP Serving via `caplets serve`
-
-## Status
-
-Approved design from grilling session. Implementation plan included in this PR stack.
-
-## Goal
-
-Add opt-in HTTP MCP serving to `caplets serve` while preserving stdio serving as the default explicit serve transport. HTTP mode should expose Caplets over modern MCP Streamable HTTP using Hono and `@hono/mcp`, with optional Basic Auth, safe localhost defaults, and clean session/shutdown handling.
-
-## Non-goals
-
-- Do not make HTTP the default transport.
-- Do not support deprecated HTTP+SSE endpoints in v1.
-- Do not allow unauthenticated non-loopback HTTP serving unless the operator explicitly opts in.
-- Do not keep no-arg `caplets` as an implicit MCP stdio server.
-
-## CLI behavior
-
-```sh
-caplets
-# prints help and exits 0
-
-caplets serve
-# serves MCP over stdio
-
-caplets serve --transport stdio
-# same as above
-
-caplets serve --transport http
-# serves MCP over Streamable HTTP at http://127.0.0.1:5387/mcp
-```
-
-Serve options:
-
-```text
---transport <stdio/http>
---host <host>       # HTTP only, default 127.0.0.1
---port <port>       # HTTP only, default 5387
---path <path>       # HTTP only, default /mcp
---user <user>       # HTTP only, optional; defaults to env or caplets when password is set
---password <pass>   # HTTP only, optional; enables Basic Auth
---allow-unauthenticated-http  # HTTP only, required for unauthenticated non-loopback serving
-```
-
-Validation rules:
-
-- Unknown transport errors.
-- Port must be a valid TCP port.
-- Path must start with `/`, contain no query string or fragment, and normalize trailing slashes except for root.
-- `--host`, `--port`, `--path`, `--user`, `--password`, and `--allow-unauthenticated-http` are invalid with stdio transport.
-- `caplets` with no arguments prints help and exits successfully.
-- `caplets serve` remains quiet in stdio mode to preserve MCP framing.
-
-## HTTP serving behavior
-
-HTTP mode uses Hono, `@hono/node-server`, and `@hono/mcp` `StreamableHTTPTransport`.
-
-Required direct dependencies in `@caplets/core`:
-
-```json
-{
-  "@hono/mcp": "^0.3.0",
-  "@hono/node-server": "^1.19.9",
-  "hono": "^4.11.5"
-}
-```
-
-Endpoints:
-
-```text
-GET /                 -> info JSON, unauthenticated
-GET /healthz          -> health JSON, unauthenticated
-GET/POST/DELETE /mcp  -> MCP Streamable HTTP, Basic Auth protected when enabled
-```
-
-`GET /` returns informational JSON similar to:
-
-```json
-{
-  "name": "caplets",
-  "transport": "http",
-  "mcp": "/mcp",
-  "health": "/healthz",
-  "auth": { "type": "basic", "enabled": true }
-}
-```
-
-`GET /healthz` returns:
-
-```json
-{
-  "status": "ok",
-  "transport": "http",
-  "mcpPath": "/mcp"
-}
-```
-
-Only the exact normalized MCP path handles MCP requests. For example, when `--path /mcp`, `/mcp/foo` returns 404.
-
-## Basic Auth
-
-Basic Auth is optional and applies only to the MCP path.
-
-Credential resolution:
-
-- Effective user is `--user`, else `CAPLETS_SERVER_USER`, else `caplets`.
-- Effective password is `--password`, else `CAPLETS_SERVER_PASSWORD`.
-- Auth is enabled only when an effective password exists.
-- If an explicit user is provided via `--user` or `CAPLETS_SERVER_USER` but no password exists, fail fast with a clear error asking for `--password` or `CAPLETS_SERVER_PASSWORD`.
-- Never log the password.
-
-Non-loopback and wildcard hosts may run without authentication only when the operator explicitly passes `--allow-unauthenticated-http`; otherwise HTTP startup must fail fast. When explicit unauthenticated non-loopback serving is allowed, startup must still warn.
-
-## DNS rebinding protection
-
-The Hono MCP transport should enable DNS rebinding protection for loopback hosts: `127.0.0.1`, `localhost`, and `::1`.
-
-For loopback serving, configure `StreamableHTTPTransport` with:
-
-- `enableDnsRebindingProtection: true`
-- `allowedHosts` containing the expected loopback host and host-with-port values.
-- `allowedOrigins` for matching localhost origins when practical.
-
-For non-loopback hosts, do not enable strict host validation by default. Require Basic Auth unless `--allow-unauthenticated-http` is present, and warn when explicit unauthenticated non-loopback serving is used.
-
-## Session model
-
-Use modern Streamable HTTP only.
-
-- Initial `POST` to the MCP path without `Mcp-Session-Id` creates a session.
-- Each session gets a random ID from `crypto.randomUUID()`.
-- Each session owns one `@hono/mcp` `StreamableHTTPTransport` and one MCP server instance.
-- Later `GET`, `POST`, and `DELETE` requests with `Mcp-Session-Id` route to the matching session.
-- Missing or unknown session IDs return JSON-RPC-style errors consistent with MCP transport behavior.
-- `DELETE` closes the session, removes it from the session map, and closes its server/transport.
-- Global shutdown closes all active sessions.
-
-## Runtime architecture
-
-Refactor the current runtime shape into reusable pieces:
-
-1. **Shared engine owner**
-   - One `CapletsEngine` owns config loading, file watching, reload serialization, backend managers, auth dir, and last-known-good config.
-
-2. **MCP session wrapper**
-   - Creates an `McpServer`, registers Caplet tools from the shared engine's current config, and subscribes to engine reload events.
-   - Reconciles tools on reload.
-   - Connects to exactly one MCP transport.
-
-3. **Stdio serving**
-   - Creates one shared engine, one MCP session wrapper, and one `StdioServerTransport`.
-
-4. **HTTP serving**
-   - Creates one shared engine.
-   - Creates one MCP session wrapper per Hono MCP session.
-   - Shares tool registration and reload reconciliation logic with stdio.
-
-This respects the MCP SDK constraint that a protocol/server instance connects to only one transport, while avoiding duplicate config watchers and backend managers per HTTP client.
-
-## Startup and shutdown
-
-HTTP startup logs go to stderr, not stdout:
-
-```text
-Caplets MCP HTTP server listening on http://127.0.0.1:5387/mcp
-Health check: http://127.0.0.1:5387/healthz
-Basic Auth: enabled (user: caplets)
-```
-
-If HTTP listens on a non-loopback or wildcard host without auth, also print a warning to stderr.
-
-Shutdown behavior:
-
-- Handle `SIGINT` and `SIGTERM` in serve mode.
-- Stop accepting new HTTP connections.
-- Close all active MCP sessions.
-- Close the shared Caplets engine and downstream connections.
-- Exit `130` on `SIGINT` and `143` on `SIGTERM`.
-- If cleanup fails, log the error to stderr and still exit.
-
-## Implementation touchpoints
-
-Likely files:
-
-- `packages/cli/src/index.ts`
-  - Remove special-casing for no args and `serve`; always delegate to `runCli`.
-
-- `packages/core/src/cli.ts`
-  - Add Commander `serve` command.
-  - Add no-arg help behavior.
-  - Parse and validate serve options.
-  - Wire signal handling for serve mode.
-
-- New core serve modules, likely:
-  - `packages/core/src/serve/options.ts`
-  - `packages/core/src/serve/stdio.ts`
-  - `packages/core/src/serve/http.ts`
-  - `packages/core/src/serve/session.ts`
-
-- `packages/core/src/runtime.ts`
-  - Keep as compatibility wrapper or refactor to use the shared session helper.
-
-- `packages/core/package.json`
-  - Add Hono dependencies.
-
-## Testing plan
-
-CLI/options tests:
-
-- `caplets` with no args prints help and does not serve.
-- `serve` defaults to stdio.
-- `serve --transport http` parses defaults: host `127.0.0.1`, port `5387`, path `/mcp`.
-- Invalid transport, port, and path error.
-- HTTP-only options with stdio error.
-- Auth resolution from flags/env/default user works.
-
-HTTP integration tests:
-
-- `GET /` returns info JSON.
-- `GET /healthz` returns health JSON.
-- Basic Auth blocks MCP path when password is configured.
-- MCP initialize/list-tools works over Streamable HTTP.
-- Session cleanup works on `DELETE` or transport close.
-
-Verification commands:
-
-```sh
-pnpm --filter @caplets/core test -- test/<new-serve-tests>.test.ts
-pnpm --filter @caplets/core typecheck
-pnpm typecheck
-pnpm test
-pnpm verify
-```
-
-## References
-
-- Hono MCP README: <https://github.com/honojs/middleware/tree/main/packages/mcp>
-- Hono MCP docs: <https://honohub.dev/docs/hono-mcp>
-- Hono MCP stateful docs: <https://honohub.dev/docs/hono-mcp/stateful>
diff --git a/docs/specs/2026-05-19-remote-native-integrations-design.md b/docs/specs/2026-05-19-remote-native-integrations-design.md
deleted file mode 100644
index 8521d0e6..00000000
--- a/docs/specs/2026-05-19-remote-native-integrations-design.md
+++ /dev/null
@@ -1,243 +0,0 @@
-# Remote Caplets Service for Native Integrations Design
-
-## Goal
-
-Let Caplets integrations connect to a remote `caplets serve --transport http` service instead of always loading local Caplets config and backends. The first implementation should support all existing integration surfaces:
-
-- OpenCode native plugin (`@caplets/opencode`) keeps native `caplets_<id>` tools.
-- Pi native extension (`@caplets/pi`) keeps native `caplets_<id>` tools.
-- Codex and Claude Code plugin artifacts can point at a remote MCP HTTP service instead of spawning local `caplets serve`.
-
-The feature should build on the Hono Streamable HTTP server added for `caplets serve --transport http` and should not introduce a separate Caplets-specific HTTP API.
-
-## Non-goals
-
-- Do not add a hosted Caplets cloud service.
-- Do not add OAuth client flows for connecting to the Caplets service in v1. Basic Auth and unauthenticated loopback development are enough.
-- Do not remove local mode. Local mode remains the default unless remote configuration is present or explicitly selected.
-- Do not flatten remote downstream tools directly into Codex/Claude plugin manifests. Codex/Claude remain MCP-backed.
-
-## Configuration model
-
-Remote client settings have three conceptual fields:
-
-- `url`: full MCP endpoint URL, for example `http://127.0.0.1:5387/mcp` or `https://caplets.example.com/mcp`.
-- `user`: Basic Auth user. Defaults to `caplets` when a password is present.
-- `password`: Basic Auth password. If a user is explicitly provided without a password, configuration is invalid.
-
-Universal environment variables:
-
-- `CAPLETS_REMOTE_URL`
-- `CAPLETS_REMOTE_USER`
-- `CAPLETS_REMOTE_PASSWORD`
-- `CAPLETS_NATIVE_MODE` with values `auto`, `local`, or `remote`
-
-Resolution rules:
-
-1. Integration-specific config overrides environment variables.
-2. OpenCode integration-specific config is read from the plugin factory's second argument and translated into `NativeCapletsServiceOptions`.
-3. Pi integration-specific config is read from package/extension args passed through Pi settings. The implementation should consume args passed by Pi rather than parsing settings files directly; examples use Pi's current documented user settings path (`~/.pi/agent/settings.json`) and should be adjusted if the active runtime path is `~/.pi/agents/settings.json`.
-4. `CAPLETS_NATIVE_MODE=local` forces current local behavior and ignores remote URL variables.
-5. `CAPLETS_NATIVE_MODE=remote` requires a remote URL.
-6. `CAPLETS_NATIVE_MODE=auto` or unset uses remote mode when a remote URL is configured, otherwise local mode.
-7. Remote URLs must be `https:` except loopback `http://localhost`, `http://127.0.0.1`, and `http://[::1]` for development.
-8. Basic Auth is enabled only when a password is present. `user` without `password` fails fast with a clear error.
-
-## Core architecture
-
-Add a native service factory that chooses between local and remote implementations:
-
-```ts
-createNativeCapletsService(options?: NativeCapletsServiceOptions): NativeCapletsService
-```
-
-`NativeCapletsServiceOptions` gains:
-
-```ts
-type NativeCapletsServiceOptions = {
-  mode?: "auto" | "local" | "remote";
-  remote?: {
-    url?: string;
-    user?: string;
-    password?: string;
-    pollIntervalMs?: number;
-    fetch?: typeof fetch;
-  };
-  // existing local options stay unchanged
-};
-```
-
-The existing `DefaultNativeCapletsService` becomes the local implementation. A new `RemoteNativeCapletsService` uses MCP SDK client primitives:
-
-- `Client` from `@modelcontextprotocol/sdk/client/index.js`
-- `StreamableHTTPClientTransport` from `@modelcontextprotocol/sdk/client/streamableHttp.js`
-
-Remote mode connects once, initializes MCP, lists remote tools, maps them to `NativeCapletTool`, and calls tools through `client.callTool()`.
-
-## Tool mapping
-
-The remote Caplets HTTP server already exposes one MCP tool per Caplet, with the Caplet ID as the MCP tool name. The remote native service maps each remote MCP tool to the same native shape local mode uses:
-
-- `caplet`: remote MCP tool name
-- `toolName`: `nativeCapletToolName(remoteTool.name)`, preserving `caplets_<id>` names
-- `title`: remote MCP tool title when present, otherwise remote tool name
-- `description`: remote MCP tool description, wrapped with native Caplets guidance where useful
-- `promptGuidance`: generated guidance that says the tool is backed by the configured remote Caplets service
-
-Execution passes the existing generated Caplets input schema through unchanged. Native integrations continue to pass parameters directly to `service.execute(capletId, params)`.
-
-## Refresh and notifications
-
-Remote mode should prefer live MCP notifications but always have a polling fallback.
-
-1. On connect, call `listTools()` and notify listeners if the mapped tool list changed.
-2. Register an MCP client `listChanged.tools.onChanged` handler when the server advertises tool-list-change notifications. The handler refreshes tools and notifies native listeners.
-3. Also poll at a default interval, proposed `30_000ms`, to cover transports, proxies, or servers that do not deliver notifications reliably.
-4. `reload()` manually refreshes the remote tool list and reconnects once if the session is closed or invalid.
-5. `close()` stops polling, terminates the MCP session when possible, closes transport/client resources, and prevents further listener notifications.
-
-OpenCode still cannot dynamically add newly discovered native tools after plugin load because its plugin API snapshots tools at load time. The remote service should still keep its internal list fresh so executions use current remote state, and the README should document that OpenCode restart may be needed for newly added or renamed Caplets. Pi can continue registering newly discovered tools during the current session.
-
-## Error handling
-
-Remote service errors should be explicit and agent-friendly:
-
-- Missing remote URL in forced remote mode: configuration error before integration registration.
-- Invalid URL or disallowed non-HTTPS URL: configuration error.
-- User without password: configuration error.
-- 401/403: auth error mentioning `CAPLETS_REMOTE_USER` and `CAPLETS_REMOTE_PASSWORD`.
-- Connection failure: remote unavailable error including host and path but not credentials.
-- Tool removed between list and call: normal Caplets-style structured tool error where possible, otherwise a clear remote tool-not-found error.
-- Notification/poll refresh failure: keep last known-good tools, report through `writeErr`, and retry on the next poll/manual reload.
-
-No logs may include Basic Auth credentials or full `Authorization` headers.
-
-## Integration behavior
-
-### OpenCode
-
-`@caplets/opencode` should accept remote configuration through the plugin factory's second argument while preserving environment-variable fallback:
-
-```ts
-type CapletsOpenCodeConfig = {
-  mode?: "auto" | "local" | "remote";
-  remote?: {
-    url?: string;
-    user?: string;
-    password?: string;
-    pollIntervalMs?: number;
-  };
-};
-
-const plugin: Plugin = async (_ctx, config?: CapletsOpenCodeConfig) => {
-  const service = createNativeCapletsService(nativeOptionsFromOpenCodeConfig(config));
-  // existing hook registration continues
-};
-```
-
-OpenCode config values override environment variables. README examples should show both environment-variable configuration and second-argument/plugin configuration in whichever JSON/TypeScript shape OpenCode currently documents for plugin config. The second-argument config is the preferred non-secret location for `url`, `mode`, and `user`; `password` should still usually come from `CAPLETS_REMOTE_PASSWORD` unless OpenCode provides a secure secret mechanism.
-
-```sh
-CAPLETS_REMOTE_URL=http://127.0.0.1:5387/mcp opencode
-CAPLETS_REMOTE_URL=https://caplets.example.com/mcp \
-CAPLETS_REMOTE_USER=caplets \
-CAPLETS_REMOTE_PASSWORD=... \
-opencode
-```
-
-### Pi
-
-`@caplets/pi` continues to accept an injected `service` for tests and advanced users. It should also accept native service options from Pi package/extension args loaded from Pi settings, so users can configure remote mode in Pi user settings without relying only on environment variables.
-
-Example target shape:
-
-```json
-{
-  "packages": [
-    {
-      "source": "npm:@caplets/pi",
-      "args": {
-        "mode": "remote",
-        "remote": {
-          "url": "https://caplets.example.com/mcp",
-          "user": "caplets"
-        }
-      }
-    }
-  ]
-}
-```
-
-Pi args override environment variables. As with OpenCode, `password` should normally come from `CAPLETS_REMOTE_PASSWORD` unless Pi adds a secure secret surface. The extension API should keep the current test seam by accepting `{ service }`, and it should merge that with `{ native?: NativeCapletsServiceOptions }` or `{ args?: NativeCapletsServiceOptions }` without breaking existing callers.
-
-### Codex and Claude Code
-
-The plugin artifacts remain MCP-backed. The default bundled `plugins/caplets/mcp.json` should continue to use local stdio for zero-config installs:
-
-```json
-{
-  "mcpServers": {
-    "caplets": {
-      "command": "caplets",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-Add a documented remote variant users can copy into their agent config:
-
-```json
-{
-  "mcpServers": {
-    "caplets": {
-      "url": "https://caplets.example.com/mcp",
-      "headers": {
-        "Authorization": "Basic ${base64(CAPLETS_REMOTE_USER + ':' + CAPLETS_REMOTE_PASSWORD)}"
-      }
-    }
-  }
-}
-```
-
-Because Codex/Claude plugin manifest schemas may not support runtime environment interpolation in bundled MCP JSON consistently, v1 should document remote configuration rather than shipping secrets or a second remote-only plugin manifest. If both agents support local plugin config overrides, add examples there; otherwise keep the plugin artifact unchanged.
-
-## Security
-
-- Remote mode must never persist passwords unless the host integration explicitly provides secure storage later.
-- Do not put passwords in plugin manifests.
-- Prefer `https:` for non-loopback endpoints and reject non-loopback `http:`.
-- Basic Auth should be created in memory per request using `requestInit.headers.Authorization` for the MCP HTTP transport.
-- The default server remains loopback-only and unauthenticated unless explicitly configured otherwise.
-
-## Testing plan
-
-Core tests:
-
-- Option resolution: env/config precedence, mode selection, URL validation, Basic Auth validation.
-- Remote native service with a mocked MCP client/transport or local in-process Streamable HTTP test server:
-  - lists remote Caplets as native tools
-  - calls remote tools
-  - handles tool-list-change notifications
-  - polls as fallback
-  - keeps last known-good tools on refresh failure
-  - closes/terminates sessions cleanly
-
-Integration tests:
-
-- OpenCode passes second-argument plugin config into native service options, with config overriding env vars, and preserves native tool registration behavior.
-- Pi passes settings/package args into native service options, with args overriding env vars, and keeps existing dynamic registration behavior.
-- Codex/Claude plugin tests verify bundled local config remains valid and docs include remote config examples.
-
-Verification:
-
-- Focused package tests for core, opencode, pi, and plugin artifacts.
-- `pnpm typecheck`
-- `pnpm test`
-- `pnpm verify`
-
-## Implementation constraints
-
-- Environment variables are required in v1, but OpenCode second-argument config and Pi settings/package args are also required integration config surfaces.
-- Codex/Claude examples should avoid promising interpolation behavior that their current MCP config schemas do not support. Use agent-specific documented override mechanisms when available; otherwise document manual config edits.
-- Poll interval defaults to 30 seconds and is configurable through core options. Add an environment override only if implementation finds a clear cross-agent need.
diff --git a/docs/specs/2026-05-20-remote-cli-control-design.md b/docs/specs/2026-05-20-remote-cli-control-design.md
deleted file mode 100644
index 0cf4930e..00000000
--- a/docs/specs/2026-05-20-remote-cli-control-design.md
+++ /dev/null
@@ -1,292 +0,0 @@
-# Remote CLI Control Service Design
-
-## Goal
-
-Let the `caplets` CLI operate against a remote `caplets serve --transport http` service when configured, so the remote server becomes the source of truth for Caplets config, Caplet files, installed Caplets, downstream auth, and command execution.
-
-The feature should feel like a unified product surface rather than separate “native” and “remote” concepts. Users configure one mode and one server base URL, then the CLI, OpenCode integration, and Pi integration choose local or remote behavior consistently.
-
-## Non-goals
-
-- Do not expose CLI administration as ordinary MCP tools.
-- Do not run raw shell command strings on the server.
-- Do not preserve pre-1.0 compatibility for the current HTTP `--path` semantics.
-- Do not make `serve`, `config path`, or `config paths` remote-control commands.
-- Do not leak downstream OAuth tokens, Basic Auth credentials, or authorization headers through responses, logs, or errors.
-
-## Unified environment interface
-
-Use one environment variable interface for CLI and native integrations:
-
-```sh
-CAPLETS_MODE=auto      # auto, remote, or local
-CAPLETS_SERVER_URL=http://127.0.0.1:5387/caplets
-CAPLETS_SERVER_USER=caplets
-CAPLETS_SERVER_PASSWORD=...
-```
-
-`CAPLETS_SERVER_URL` is the service base URL, including any deployment prefix. It is not the MCP endpoint URL.
-
-Mode resolution:
-
-1. `CAPLETS_MODE=auto` or unset uses remote mode when `CAPLETS_SERVER_URL` is set; otherwise local mode.
-2. `CAPLETS_MODE=local` always uses local mode, even when server settings are present.
-3. `CAPLETS_MODE=remote` requires `CAPLETS_SERVER_URL` and fails fast if missing.
-
-Explicit host config/options still override environment config where integrations already support explicit options. The target model has no separate native-only mode namespace.
-
-## HTTP service URL contract
-
-`caplets serve --transport http` exposes a Caplets service rooted at `--path`.
-
-Defaults:
-
-```text
-host: 127.0.0.1
-port: 5387
-path: /
-```
-
-Routes under the service base:
-
-```text
-GET  {base}/healthz
-POST {base}/mcp
-POST {base}/control
-GET  {base}/control/auth/callback/:flowId   # browser OAuth callback for remote auth login
-```
-
-Examples:
-
-```sh
-caplets serve --transport http
-# service base:     http://127.0.0.1:5387
-# MCP endpoint:     http://127.0.0.1:5387/mcp
-# control endpoint: http://127.0.0.1:5387/control
-# health endpoint:  http://127.0.0.1:5387/healthz
-
-caplets serve --transport http --path /caplets
-# service base:     http://127.0.0.1:5387/caplets
-# MCP endpoint:     http://127.0.0.1:5387/caplets/mcp
-# control endpoint: http://127.0.0.1:5387/caplets/control
-# health endpoint:  http://127.0.0.1:5387/caplets/healthz
-```
-
-`CAPLETS_SERVER_URL` uses the same base URL shape:
-
-```text
-CAPLETS_SERVER_URL=https://example.com/caplets
-MCP endpoint:      https://example.com/caplets/mcp
-Control endpoint:  https://example.com/caplets/control
-Health endpoint:   https://example.com/caplets/healthz
-```
-
-`caplets serve --transport http` also reads the unified server variables as defaults:
-
-- `CAPLETS_SERVER_URL` provides default host, port, and base path.
-- `CAPLETS_SERVER_USER` provides the Basic Auth user.
-- `CAPLETS_SERVER_PASSWORD` enables Basic Auth and provides the password.
-
-Explicit `serve` flags override environment defaults.
-
-## Architecture
-
-Add a Remote CLI Control Service alongside the existing MCP HTTP service.
-
-```text
-Local shell
-  caplets list
-  caplets add mcp github ...
-  caplets call-tool github.search_repositories ...
-        │
-        ▼
-Remote CLI client
-        │ HTTPS + auth
-        ▼
-caplets serve --transport http
-  {base}/mcp      → agent-facing MCP tools
-  {base}/control  → CLI-facing control API
-        │
-        ▼
-Remote CapletsEngine + remote filesystem/config/auth store
-```
-
-The MCP endpoint remains agent-facing and only exposes configured Caplets. The control endpoint is authenticated and exposes structured CLI administration operations.
-
-## State ownership
-
-In remote mode, the server owns all Caplets state:
-
-- Caplets config
-- `.caplets` files
-- installed Caplets
-- downstream MCP/OpenAPI/GraphQL/HTTP/CLI backend definitions
-- OAuth/token auth store
-- reload/watch lifecycle
-
-A remote CLI mutation changes server-side state only. It must not partially mutate local files. Successful mutation messages must explicitly say `remote` so users do not confuse server writes with local filesystem writes.
-
-Examples:
-
-```text
-Installed github to remote /srv/caplets/.caplets/github
-Wrote remote MCP Caplet to /srv/caplets/.caplets/github.md
-Deleted remote OAuth credentials for `linear`.
-```
-
-## Remote control API
-
-The control API is command-semantic, not a raw command executor.
-
-```text
-POST {base}/control
-Authorization: Basic ...
-Content-Type: application/json
-```
-
-Request envelope:
-
-```ts
-type RemoteCliRequest = {
-  command:
-    | "list"
-    | "get_caplet"
-    | "check_backend"
-    | "list_tools"
-    | "search_tools"
-    | "get_tool"
-    | "call_tool"
-    | "init"
-    | "add"
-    | "install"
-    | "auth_login_start"
-    | "auth_login_complete"
-    | "auth_logout"
-    | "auth_list";
-  arguments: Record<string, unknown>;
-};
-```
-
-Response envelope:
-
-```ts
-type RemoteCliResponse =
-  | {
-      ok: true;
-      result: unknown;
-      warnings?: string[];
-    }
-  | {
-      ok: false;
-      error: {
-        code: string;
-        message: string;
-        nextAction?: string;
-      };
-      warnings?: string[];
-    };
-```
-
-The server dispatches to internal core functions such as `listCaplets`, `addMcpCaplet`, `installCaplets`, `CapletsEngine.execute`, and auth helpers. The server must not shell out to the `caplets` CLI.
-
-The local CLI remains responsible for output formatting, so existing `--json`, `--format plain`, and markdown summaries stay consistent across local and remote modes.
-
-## Command behavior
-
-Remote-capable commands:
-
-- `list`
-- `get-caplet`
-- `check-backend`
-- `list-tools`
-- `search-tools`
-- `get-tool`
-- `call-tool`
-- `auth login`
-- `auth logout`
-- `auth list`
-- `add cli|mcp|openapi|graphql|http`
-- `install`
-- `init` when remote mode is active or an explicit remote init flag is used
-
-Local-only commands:
-
-- `serve`
-- `config path`
-- `config paths`
-
-`config path` and `config paths` describe the local CLI process and should not become remote-control commands. Remote server filesystem paths may appear in mutation responses as diagnostics, clearly labeled as remote paths.
-
-## Auth behavior
-
-Remote control authentication and downstream provider authentication are separate concerns.
-
-- `CAPLETS_SERVER_USER` and `CAPLETS_SERVER_PASSWORD` authenticate the client to the remote Caplets control service.
-- Downstream OAuth/token credentials for GitHub, Linear, GraphQL endpoints, and other backends live on the server.
-
-Remote auth commands operate on the server-side auth store:
-
-- `caplets auth list` shows server-side credential status.
-- `caplets auth logout <server>` deletes server-side credentials.
-- `caplets auth login <server>` starts and completes login for the server-side auth store.
-
-Remote login should use a flow similar to:
-
-1. Client calls `auth_login_start`.
-2. Server creates the authorization flow, stores verifier/session state server-side, and returns an authorization URL plus flow ID.
-3. Client opens or prints the authorization URL and waits/polls.
-4. Callback or completion request reaches the remote server.
-5. Server exchanges code/token and stores credentials in its auth store.
-6. Client reports success without receiving tokens.
-
-No control API response may include raw access tokens, refresh tokens, Basic Auth passwords, or full authorization headers.
-
-## Security
-
-- Reject non-loopback `http:` `CAPLETS_SERVER_URL`; require HTTPS except for `localhost`, `127.0.0.1`, and `::1` development URLs.
-- Basic Auth over network deployments must be used only over HTTPS.
-- Protect `/control` at least as strongly as `/mcp`; `/control` can mutate server state.
-- Redact secrets in errors, warnings, logs, and test snapshots.
-- Do not expose control commands as MCP tools.
-- Do not accept raw shell command strings through the control API.
-
-## Error handling
-
-Remote CLI failures should be explicit and safe:
-
-- `CAPLETS_MODE=remote` without `CAPLETS_SERVER_URL`: configuration error.
-- Invalid server base URL: configuration error.
-- Non-loopback `http:` URL: configuration error requiring HTTPS.
-- Missing/invalid control credentials: “Remote Caplets control authentication failed.”
-- Server unreachable: “Remote Caplets server unavailable at <safe base URL>.”
-- Unknown or unsupported remote command: structured control error.
-- Remote mutation failure: no local mutation, and output clearly identifies the remote operation that failed.
-
-## Testing plan
-
-Core tests:
-
-- URL/base-path normalization for `CAPLETS_SERVER_URL`.
-- `serve --path /caplets` mounts `/caplets/mcp`, `/caplets/control`, and `/caplets/healthz`.
-- CLI mode resolution from `CAPLETS_MODE` and `CAPLETS_SERVER_URL`.
-- `serve` defaults from `CAPLETS_SERVER_URL`, `CAPLETS_SERVER_USER`, and `CAPLETS_SERVER_PASSWORD`.
-- Remote client command envelopes and Basic Auth headers.
-- Control endpoint dispatch for read, execute, mutation, and auth commands.
-- Server-side auth store behavior for remote `auth login`, `auth list`, and `auth logout`.
-- No secret leakage in logs, errors, warnings, or responses.
-
-End-to-end-style tests:
-
-- Start an in-process HTTP app.
-- Set `CAPLETS_MODE=remote` and `CAPLETS_SERVER_URL`.
-- Run `caplets list`, `caplets add mcp`, `caplets call-tool`, and `caplets auth list` through remote mode.
-- Assert server-side files/auth store change and local temp config remains unchanged.
-
-Verification commands for implementation:
-
-```sh
-pnpm --filter @caplets/core test -- test/serve-http.test.ts test/cli.test.ts test/auth.test.ts
-pnpm typecheck
-pnpm test
-pnpm verify
-```
diff --git a/docs/specs/2026-05-21-cli-completions-design.md b/docs/specs/2026-05-21-cli-completions-design.md
deleted file mode 100644
index 2618d981..00000000
--- a/docs/specs/2026-05-21-cli-completions-design.md
+++ /dev/null
@@ -1,166 +0,0 @@
-# CLI Completions for the Caplets npm Package
-
-## Status
-
-Planned design for implementation on `feat/cli-completions`.
-
-## Goal
-
-Add first-class shell completion support to the `caplets` npm CLI so users can install Bash, Zsh, or Fish completions and get useful static and config-aware suggestions without shell startup side effects.
-
-## Non-goals
-
-- Do not mutate `.bashrc`, `.zshrc`, Fish config, or system completion directories during `npm install`.
-- Do not add a `postinstall` script.
-- Do not run downstream MCP servers, OpenAPI clients, GraphQL introspection, HTTP requests, or user CLI tools during tab completion.
-- Do not complete secret values, token values, OAuth callback URLs, or raw environment variable contents.
-- Do not add raw remote shell command execution for remote completions.
-
-## User-facing commands
-
-Caplets should expose a public completion script generator:
-
-```sh
-caplets completion bash
-caplets completion zsh
-caplets completion fish
-```
-
-The command writes the requested shell script to stdout. Users install it using shell-native mechanisms:
-
-```sh
-# Bash
-mkdir -p ~/.local/share/bash-completion/completions
-caplets completion bash > ~/.local/share/bash-completion/completions/caplets
-
-# Zsh
-mkdir -p ~/.zsh/completions
-caplets completion zsh > ~/.zsh/completions/_caplets
-
-# Fish
-mkdir -p ~/.config/fish/completions
-caplets completion fish > ~/.config/fish/completions/caplets.fish
-```
-
-Caplets should also expose a hidden machine-facing command used only by generated scripts:
-
-```sh
-caplets __complete --shell bash -- get-caplet ""
-```
-
-`__complete` prints newline-separated candidates to stdout and remains quiet on recoverable errors. It should be hidden from normal help output.
-
-## Completion scope
-
-### Static completions
-
-Complete known command names, subcommands, options, and enum values:
-
-- Top-level commands: `serve`, `init`, `list`, `install`, `add`, direct operation commands, `config`, `auth`, and `completion`.
-- `add` subcommands: `cli`, `mcp`, `openapi`, `graphql`, `http`.
-- `config` subcommands: `path`, `paths`.
-- `auth` subcommands: `login`, `logout`, `list`.
-- Shells for `completion`: `bash`, `zsh`, `fish`.
-- Format values: `markdown`, `md`, `plain`, `json`.
-- Serve transports: `stdio`, `http`.
-- Remote MCP transports for `add mcp --transport`: `http`, `sse`.
-- CLI generator includes for `add cli --include`: `git`, `gh`, `package`.
-
-### Config-aware completions
-
-Complete enabled configured Caplet IDs from the active Caplets config for commands whose next positional argument is a Caplet ID:
-
-- `get-caplet`
-- `check-backend`
-- `list-tools`
-- `search-tools`
-- `list-resources`
-- `search-resources`
-- `list-resource-templates`
-- `read-resource`
-- `list-prompts`
-- `search-prompts`
-- `complete`
-
-Complete enabled configured Caplet IDs plus a trailing dot for commands whose next positional argument is a qualified target:
-
-- `get-tool`
-- `call-tool`
-- `get-prompt`
-
-Example:
-
-```sh
-caplets call-tool git<TAB>
-# suggests: github.
-```
-
-The first implementation intentionally does not complete downstream tool, prompt, or resource names because doing so would require probing downstream systems during tab completion. A future opt-in enhancement can complete cached downstream names if Caplets persists a safe metadata cache.
-
-Complete configured Caplet/server IDs for auth commands:
-
-- `auth login`
-- `auth logout`
-
-### Remote mode completions
-
-When CLI remote mode is active, completions must use the command-semantic remote control API, not raw CLI string execution. Add a remote control command such as `complete_cli` that accepts the completion words and returns newline-safe suggestions from the server-owned config.
-
-Remote completions must not expose secrets. They should return only public command names, option names, enum values, and configured Caplet IDs.
-
-## Architecture
-
-Add a focused completion module under `packages/core/src/cli/completion.ts`.
-
-Responsibilities:
-
-- Generate shell scripts for Bash, Zsh, and Fish.
-- Resolve newline-separated completion suggestions for `__complete`.
-- Load local config only when a command position needs config-aware suggestions.
-- Accept a remote completion callback so `__complete` can delegate to `/control` in remote mode.
-- Keep all completion errors quiet by returning no suggestions, except invalid explicit `caplets completion <shell>` invocations, which should fail with `REQUEST_INVALID`.
-
-`packages/core/src/cli.ts` wires public and hidden commands into the existing Commander program. The generated shell scripts call `caplets __complete`, not Commander internals.
-
-Remote control adds one structured command, `complete_cli`, which reuses the same resolver on the server side with server-owned config paths.
-
-## Output contract
-
-`__complete` output is newline-separated plain text:
-
-```text
-get-caplet
-list-tools
-call-tool
-```
-
-No descriptions are required in the first implementation. Shell-specific escaping belongs in the generated shell functions; suggestion values themselves should not contain newlines.
-
-## Error handling
-
-- `caplets completion <unknown-shell>` fails with `REQUEST_INVALID` and a clear message listing `bash`, `zsh`, and `fish`.
-- `caplets __complete ...` returns no suggestions for malformed words, unreadable config, remote failures, or unsupported command contexts.
-- Completion generation must not set process exit code on best-effort dynamic lookup failures.
-
-## Documentation
-
-Update the root README and CLI package README with:
-
-- Supported shells.
-- Install snippets for Bash, Zsh, and Fish.
-- Note that npm install does not modify shell startup files.
-- Note that completions are static plus config-aware and do not probe downstream services.
-
-## Release notes
-
-Add a changeset for the `caplets` package because this introduces a user-facing CLI command. If implementation touches exported core types, include `@caplets/core` in the same changeset.
-
-## Acceptance criteria
-
-- `caplets completion bash`, `zsh`, and `fish` emit shell-specific scripts that invoke `caplets __complete`.
-- `caplets __complete --shell bash -- ""` suggests top-level commands.
-- `caplets __complete --shell bash -- add ""` suggests add subcommands.
-- `caplets __complete --shell bash -- get-caplet ""` suggests enabled Caplet IDs from local config.
-- `caplets __complete --shell bash -- call-tool github` suggests `github.` when `github` is configured.
-- Remote mode routes `__complete` to `/control` with a structured `complete_cli` command.
-- `pnpm verify` passes.
diff --git a/docs/specs/2026-05-21-completion-discovery-refactor-design.md b/docs/specs/2026-05-21-completion-discovery-refactor-design.md
deleted file mode 100644
index 561fdc02..00000000
--- a/docs/specs/2026-05-21-completion-discovery-refactor-design.md
+++ /dev/null
@@ -1,235 +0,0 @@
-# Completion Discovery Refactor Design
-
-## Status
-
-Planned design for follow-up implementation on `feat/cli-completions`.
-
-## Goal
-
-Make Caplets CLI completions architecturally correct and more useful by replacing duplicated command lists with shared command metadata, adding persistent discovery caching, and completing qualified downstream targets such as `caplets call-tool <server>.<tool>`.
-
-## User intent
-
-The completion feature should not be a thin static helper that drifts from the real CLI. It should feel intelligent:
-
-- Top-level command completions must stay in sync with the Commander CLI.
-- Qualified targets should complete backend IDs and known downstream names.
-- Live downstream discovery is acceptable during completion when bounded by caching, timeouts, and quiet failure.
-- Remote mode must continue using structured `/control` requests and server-owned state.
-
-## Non-goals
-
-- Do not execute arbitrary raw CLI strings over remote control.
-- Do not add shell profile mutation, `postinstall`, or automatic shell startup edits.
-- Do not cache secrets, auth headers, token values, env values, prompt arguments, resource contents, or downstream response payloads.
-- Do not start browser/device login flows during completion.
-- Do not print diagnostics during normal generated shell completion scripts. Generated scripts suppress stderr; explicit/debug invocations may expose hints later.
-
-## Shared CLI command metadata
-
-Add a shared metadata module for command names and static completion behavior. This module becomes the source of truth for completion-visible commands and subcommands.
-
-Expected metadata shape:
-
-```ts
-export const cliCommandNames = [
-  "serve",
-  "init",
-  "list",
-  "install",
-  "add",
-  "get-caplet",
-  "check-backend",
-  "list-tools",
-  "search-tools",
-  "get-tool",
-  "call-tool",
-  "list-resources",
-  "search-resources",
-  "list-resource-templates",
-  "read-resource",
-  "list-prompts",
-  "search-prompts",
-  "get-prompt",
-  "complete",
-  "config",
-  "auth",
-  "completion",
-] as const;
-```
-
-`completion.ts` must consume this metadata instead of owning a hand-maintained `topLevelCommands` copy. The existing test that compares `createProgram().commands` to top-level completion output remains as a regression guard.
-
-## Completion configuration
-
-Add a top-level `completion` config section:
-
-```json
-{
-  "completion": {
-    "discoveryTimeoutMs": 750,
-    "overallTimeoutMs": 1500,
-    "cacheTtlMs": 300000,
-    "negativeCacheTtlMs": 30000
-  }
-}
-```
-
-Defaults:
-
-- `discoveryTimeoutMs`: `750`
-- `overallTimeoutMs`: `1500`
-- `cacheTtlMs`: `300000` (5 minutes)
-- `negativeCacheTtlMs`: `30000` (30 seconds)
-
-Normal config precedence applies: user config plus project config merge through the existing config loader. Invalid values fail normal config validation. Completion runtime still returns no suggestions if config loading itself fails.
-
-## Platform-native cache location
-
-Store completion discovery cache under the platform cache directory, not config or state:
-
-- Linux/Unix: `${XDG_CACHE_HOME}/caplets/completions` when `XDG_CACHE_HOME` is absolute, otherwise `~/.cache/caplets/completions`.
-- macOS: `~/Library/Caches/caplets/completions`.
-- Windows: `%LOCALAPPDATA%\caplets\cache\completions` when `LOCALAPPDATA` is absolute, otherwise `%USERPROFILE%\AppData\Local\caplets\cache\completions`.
-
-This should be implemented alongside existing path helpers in `packages/core/src/config/paths.ts`.
-
-## Cache contents and safety boundary
-
-Cache only public, secret-free discovery metadata needed for completions:
-
-- backend ID
-- backend type
-- kind: `tools`, `prompts`, `resources`, `resourceTemplates`
-- candidate value: tool name, prompt name, resource URI, or resource template URI template
-- optional public title/name/description if already returned by discovery and needed later
-- `fetchedAt`, `expiresAt`, and config fingerprint
-- negative-cache entries for auth-required, timeout, unavailable, or unsupported capability failures
-
-Never cache:
-
-- input arguments
-- prompt argument values
-- auth headers, bearer tokens, OAuth tokens, client secrets
-- environment variable values
-- command outputs
-- resource contents
-- arbitrary downstream response payloads
-
-## Cache invalidation
-
-Key cache entries by a stable secret-free completion fingerprint derived from:
-
-- backend ID
-- backend type
-- discovery kind
-- discovery-relevant backend config fields
-- completion settings that affect discovery/cache behavior
-
-Use secret-redacted fields only. Examples:
-
-- MCP: transport, command, args, cwd, URL, startup timeout; do not include env values or auth secrets.
-- OpenAPI: spec path/spec URL/base URL and configured auth type; do not include token/header values.
-- GraphQL: endpoint URL, schema source, configured operation names; do not include auth values.
-- HTTP: base URL and action names/paths/methods; do not include auth/header secrets.
-- CLI: action names and command/args/cwd shape; do not include env values.
-- Caplet sets: source path/repo/ref and nested config fingerprint when available.
-
-If the fingerprint changes, old entries are misses. Prune expired and mismatched entries opportunistically.
-
-## Discovery behavior
-
-Completion uses stale-while-refresh semantics without detached background workers:
-
-1. Fresh cache entry: return cached suggestions immediately.
-2. Stale cache entry: attempt refresh within the overall budget; return fresh suggestions if refresh succeeds, otherwise return stale suggestions.
-3. Missing cache entry: attempt live discovery within the budget; return discovered suggestions if it succeeds, otherwise return static/config fallback.
-4. Negative-cache entry: do not retry until `negativeCacheTtlMs` expires; return static/config fallback or stale positive data if available.
-
-All discovery failures are quiet for shell-facing completion. Generated shell scripts redirect stderr to null. A future explicit debug command may surface auth hints.
-
-Completion may start normal MCP stdio processes because MCP discovery requires it, but it must not initiate interactive login, open a browser, prompt for credentials, or write auth state. Auth-required failures should become negative-cache entries and should not clear still-valid positive cache data.
-
-## Qualified target completion contract
-
-### Tools
-
-For `call-tool` and `get-tool`:
-
-- `caplets call-tool <TAB>` suggests enabled backend IDs such as `github`, `repo`.
-- `caplets call-tool repo <TAB>` suggests unqualified tool names such as `status`, `build`.
-- `caplets call-tool repo.<TAB>` remains supported and suggests qualified tool names such as `repo.status`, `repo.build`.
-- CLI and HTTP backends can provide config-defined action names without live probing.
-- OpenAPI, GraphQL, MCP, and Caplet-set backends may use live discovery through the cache manager.
-- Failures/timeouts degrade to backend ID suggestions or no extra target names.
-
-### Prompts
-
-For `get-prompt`:
-
-- `caplets get-prompt <TAB>` suggests MCP backend IDs when prompts are possible.
-- `caplets get-prompt docs <TAB>` suggests unqualified prompt names such as `summarize`.
-- `caplets get-prompt docs.<TAB>` discovers/caches MCP prompt names and suggests `docs.promptName`.
-- Non-MCP backends should not suggest prompt names.
-
-### Resources and resource templates
-
-For `read-resource`:
-
-- The first positional argument remains the Caplet/backend ID and should complete enabled MCP backend IDs.
-- The second positional argument should complete known/discovered resource URIs for the selected MCP backend.
-
-For `complete`:
-
-- The first positional argument completes enabled MCP backend IDs.
-- When completing `--prompt`, suggest known/discovered prompt names for the selected backend.
-- When completing `--resource-template`, suggest known/discovered resource template URI templates for the selected backend.
-- Existing enum/static option completions continue to work.
-
-## Remote mode
-
-Remote mode keeps all Caplets state on the server. The local CLI must continue to call `/control` with `command: "complete_cli"`; it must not discover downstream backends locally when remote mode is active.
-
-The remote Caplets server owns:
-
-- config
-- auth store
-- downstream managers
-- persistent completion cache
-- live discovery and negative-cache decisions
-
-Remote control responses return completion candidates only. They must not return secrets, cache internals, auth tokens, or raw downstream errors.
-
-## Error handling
-
-- `caplets completion <unknown-shell>` remains a normal `REQUEST_INVALID` error.
-- `caplets __complete ...` remains best-effort and returns no candidates on malformed input, config load failure, cache failure, remote failure, downstream timeout, or unsupported context.
-- Auth-required discovery returns stale cached results if present; otherwise static/config fallback.
-- Normal generated shell completion suppresses stderr. If explicit/debug completion output is added later, auth-required diagnostics may recommend `caplets auth login <server>`.
-
-## Documentation and release notes
-
-Update README/package README to describe:
-
-- completion scripts remain explicit install only
-- completions may use cached live discovery
-- discovery is bounded by configurable timeouts/TTLs
-- cache location follows platform conventions
-- auth-required backends may need `caplets auth login <server>` for richer completions
-
-Update the existing completion changeset to mention command metadata, persistent cache, and downstream qualified target completions.
-
-## Acceptance criteria
-
-- Static top-level completion suggestions come from shared command metadata, not a private duplicate list in `completion.ts`.
-- A test fails if registered Commander commands drift from completion-visible command metadata.
-- `completion` config defaults parse and appear in generated schema.
-- Cache path helpers return XDG/macOS/Windows-appropriate cache directories.
-- Completion cache stores only secret-free candidate metadata and negative-cache state.
-- `call-tool` / `get-tool` complete backend IDs and tool names using config plus cache-backed live discovery.
-- `get-prompt` completes backend IDs and prompt names for MCP backends.
-- `read-resource` completes backend IDs and resource URIs for MCP backends.
-- `complete --prompt` and `complete --resource-template` complete prompt names and resource template URI templates.
-- Remote completions route through `complete_cli` and use server-owned cache/discovery.
-- Completion failures remain quiet under generated shell scripts.
-- `pnpm verify` passes.
diff --git a/docs/specs/2026-05-21-docker-self-hosting-design.md b/docs/specs/2026-05-21-docker-self-hosting-design.md
deleted file mode 100644
index f745ad81..00000000
--- a/docs/specs/2026-05-21-docker-self-hosting-design.md
+++ /dev/null
@@ -1,94 +0,0 @@
-# Docker self-hosting design
-
-## Goal
-
-Make the HTTP Caplets service easy to self-host from this repository by adding a source-build Docker image and a Docker Compose setup that preserves server-owned Caplets state.
-
-## Scope
-
-- Add a root `Dockerfile` that builds the monorepo with the pinned pnpm version and runs the built `caplets` CLI.
-- Add a root `docker-compose.yml` for local and self-hosted deployments.
-- Document Docker usage in the README.
-- Keep runtime configuration aligned with the unified Caplets environment variables: `CAPLETS_MODE`, `CAPLETS_SERVER_URL`, `CAPLETS_SERVER_USER`, and `CAPLETS_SERVER_PASSWORD`.
-
-## Non-goals
-
-- Do not publish or maintain a separate registry image in this change.
-- Do not add a second npm-install-only Dockerfile.
-- Do not change HTTP server behavior or remote control semantics.
-
-## Dockerfile design
-
-Use a multi-stage Node image:
-
-1. Build stage
-   - Start from an official Node image that satisfies `node >=22`.
-   - Enable Corepack and activate `pnpm@11.0.9`.
-   - Copy workspace manifests first for cache-friendly dependency installation.
-   - Run `pnpm install --frozen-lockfile`.
-   - Copy the full repository.
-   - Run `pnpm build`.
-
-2. Runtime stage
-   - Start from a smaller official Node runtime image.
-   - Enable Corepack and activate `pnpm@11.0.9` so workspace-linked runtime execution is predictable.
-   - Copy only the files needed to run the built CLI and its workspace dependencies.
-   - Set a durable Caplets home/config location under `/data`.
-   - Expose port `5387`.
-   - Default command: `caplets serve --transport http --host 0.0.0.0`.
-
-The image represents the checked-out source tree, which is better for this repo than installing the latest published `caplets` package from npm.
-
-## Compose design
-
-Add a single `caplets` service that builds from `.` and runs the Dockerfile.
-
-External network binding should be configurable:
-
-```yaml
-ports:
-  - "${CAPLETS_BIND_ADDRESS:-127.0.0.1}:${CAPLETS_PORT:-5387}:5387"
-```
-
-This gives safe local-only exposure by default while allowing self-hosters to set `CAPLETS_BIND_ADDRESS=0.0.0.0` for LAN or reverse-proxy deployments.
-
-Environment variables:
-
-- `CAPLETS_SERVER_URL` defaults to `http://127.0.0.1:5387` for local use.
-- `CAPLETS_SERVER_USER` and `CAPLETS_SERVER_PASSWORD` are passed through for Basic Auth.
-- Compose should not hard-code secrets.
-
-Persistence:
-
-- Default: Docker named volume mounted at `/data`.
-- Document alternative: replace the named volume with `./data:/data` for a host-visible bind mount.
-
-Health check:
-
-- Use the service health endpoint (`/healthz` for the default base path).
-- Keep the health check unauthenticated, matching the HTTP service design.
-
-## Documentation design
-
-Add a README section covering:
-
-- Building and starting with `docker compose up --build`.
-- Local URL and health endpoint.
-- Setting `CAPLETS_SERVER_PASSWORD` and optional `CAPLETS_SERVER_USER`.
-- Changing `CAPLETS_BIND_ADDRESS` for LAN/reverse proxy exposure.
-- Named volume default and bind-mount alternative.
-- Connecting clients with `CAPLETS_MODE=remote` and `CAPLETS_SERVER_URL`.
-
-## Security considerations
-
-- Default host binding should remain loopback-only.
-- LAN/public exposure should require an explicit bind-address change and should strongly recommend `CAPLETS_SERVER_PASSWORD`.
-- Remote downstream auth and Caplets state remain server-owned inside the mounted `/data` location.
-- Remote control Basic Auth is separate from downstream provider credentials.
-
-## Testing and verification
-
-- `docker compose config` validates the Compose file.
-- `docker build .` validates the Dockerfile.
-- If Docker can run containers locally, start Compose and verify `GET /healthz` returns success.
-- Run relevant repo checks after editing, at minimum formatting and type/build checks affected by docs/config changes.
diff --git a/docs/specs/2026-05-21-ghcr-release-publishing-design.md b/docs/specs/2026-05-21-ghcr-release-publishing-design.md
deleted file mode 100644
index ee9cd4a8..00000000
--- a/docs/specs/2026-05-21-ghcr-release-publishing-design.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# GHCR Release Publishing Design
-
-## Goal
-
-Publish the source-build Caplets Docker image to GitHub Container Registry as part of the existing Changesets release pipeline, only when a real package release is published.
-
-## Current release flow
-
-The existing `.github/workflows/release.yml` workflow runs on pushes to `main` and manual dispatch. It installs dependencies, runs `pnpm verify`, then uses `changesets/action@v1` to either create/update the version PR or publish npm packages with `pnpm release`.
-
-## Design
-
-Use the existing release job and add GHCR publishing steps after the Changesets action. The Docker image publish steps are gated on both `steps.changesets.outputs.published == 'true'` and `steps.cli-package.outputs.published == 'true'`, so they do not run while the workflow is merely creating or updating a version PR or when only non-CLI packages are published.
-
-The release job will grant `packages: write`, log in to `ghcr.io` using `GITHUB_TOKEN`, register QEMU for multi-platform builds, generate image metadata, and push the existing root `Dockerfile` image to:
-
-- `ghcr.io/spiritledsoftware/caplets:latest`
-- `ghcr.io/spiritledsoftware/caplets:v<package-version>`
-- `ghcr.io/spiritledsoftware/caplets:<package-version>`
-- `ghcr.io/spiritledsoftware/caplets:sha-<short-sha>`
-
-The package version is read from `packages/cli/package.json` after Changesets has published, because the Docker image represents the CLI service runtime.
-
-## Security and permissions
-
-The workflow uses the repository-scoped `GITHUB_TOKEN` and GitHub Actions package permissions. No new long-lived registry token is required. The release job adds only `packages: write`; existing `contents`, `pull-requests`, and `id-token` permissions remain unchanged.
-
-## Validation
-
-Validation should cover YAML formatting, workflow syntax sanity, QEMU/Buildx setup ordering, and Docker metadata behavior where practical. Full GHCR push verification can only happen in GitHub Actions on a release publish. Local verification should include `pnpm format:check .github/workflows/release.yml` and a Docker build of the existing image.
diff --git a/docs/specs/2026-05-21-mcp-resources-prompts-design.md b/docs/specs/2026-05-21-mcp-resources-prompts-design.md
deleted file mode 100644
index 1231db56..00000000
--- a/docs/specs/2026-05-21-mcp-resources-prompts-design.md
+++ /dev/null
@@ -1,411 +0,0 @@
-# MCP Resources and Prompts in Caplets
-
-## Status
-
-Approved design direction from brainstorming. Implementation plan not yet written.
-
-## Goal
-
-Expand MCP-backed Caplets from a tool-only gateway into an MCP capability gateway that lets agents discover and use downstream tools, resources, resource templates, prompts, and completions while preserving Caplets' progressive-disclosure UX.
-
-The design must keep non-MCP backends clean: OpenAPI, GraphQL, HTTP, CLI, and non-MCP Caplet set surfaces must not advertise MCP-specific resource, prompt, or completion operations.
-
-## Non-goals
-
-- Do not flatten downstream resources, prompts, or templates into Caplets' top-level `tools/list` response.
-- Do not expose MCP-specific operations on OpenAPI, GraphQL, HTTP, or CLI-backed Caplets.
-- Do not convert OpenAPI, GraphQL, HTTP, or CLI actions into synthetic MCP resources or prompts in this iteration.
-- Do not implement a faithful raw MCP proxy mode in this iteration.
-- Do not subscribe to resource content updates in the first implementation unless needed by the SDK cache-invalidation mechanism.
-- Do not add roots, sampling, elicitation, logging, or task support in this iteration.
-
-## Current state
-
-Caplets currently exposes one generated top-level tool per enabled Caplet. Each generated tool uses a shared input schema with these operations:
-
-- `get_caplet`
-- `check_backend`
-- `list_tools`
-- `search_tools`
-- `get_tool`
-- `call_tool`
-
-For MCP-backed Caplets, `DownstreamManager` connects through the MCP SDK and uses `listTools` and `callTool`. It caches only downstream tool metadata. It does not currently expose:
-
-- `resources/list`
-- `resources/templates/list`
-- `resources/read`
-- `prompts/list`
-- `prompts/get`
-- `completion/complete`
-- downstream server instructions/version/capability metadata beyond what connection handling needs internally
-
-## Design principles
-
-1. **Progressive disclosure stays intact.** Caplets still exposes one top-level capability card per Caplet, not every downstream primitive.
-2. **Schemas should teach the agent what is possible.** MCP-specific operations should appear only on MCP-backed Caplets.
-3. **Downstream MCP remains the source of truth.** Caplets forwards resource, prompt, and completion semantics without inventing validation rules beyond request routing and strict wrapper-shape validation.
-4. **Results should be preserved.** `read_resource`, `get_prompt`, and `complete` should return downstream-compatible result shapes with Caplets metadata added in `_meta.caplets`, mirroring `call_tool` behavior where practical.
-5. **Capability absence should be explicit.** If an MCP server does not advertise resources, prompts, or completions, the corresponding operation returns a structured `UNSUPPORTED_CAPABILITY` error.
-
-## Agent-facing operation surfaces
-
-### Non-MCP-backed Caplets
-
-OpenAPI, GraphQL, HTTP, CLI, and non-MCP Caplet surfaces keep the current operation set:
-
-```ts
-operation:
-  | "get_caplet"
-  | "check_backend"
-  | "list_tools"
-  | "search_tools"
-  | "get_tool"
-  | "call_tool";
-```
-
-Their generated input schema must not mention `list_resources`, `read_resource`, `list_prompts`, `get_prompt`, or `complete`.
-
-### MCP-backed Caplets
-
-MCP-backed Caplets expose the current tool operations plus MCP-native discovery and use operations:
-
-```ts
-operation:
-  | "get_caplet"
-  | "check_backend"
-  | "list_tools"
-  | "search_tools"
-  | "get_tool"
-  | "call_tool"
-  | "list_resources"
-  | "search_resources"
-  | "list_resource_templates"
-  | "read_resource"
-  | "list_prompts"
-  | "search_prompts"
-  | "get_prompt"
-  | "complete";
-```
-
-The generated tool description should mention this broader MCP capability only for MCP-backed Caplets. Non-MCP descriptions should continue to use the existing tool/action wording.
-
-## Request schema
-
-The current universal schema should become backend-aware schema generation.
-
-Common fields remain:
-
-- `operation`: required enum, generated per backend.
-- `query`: required for search operations only.
-- `limit`: optional for list/search operations where accepted.
-- `tool`: exact downstream tool name for `get_tool` and `call_tool`.
-- `arguments`: JSON object for `call_tool` and `get_prompt` arguments.
-- `fields`: optional field selection for `call_tool` where currently supported.
-
-New MCP-only fields:
-
-- `uri`: exact resource URI for `read_resource`.
-- `prompt`: exact downstream prompt name for `get_prompt`.
-- `ref`: completion reference for `complete`; either a prompt reference or resource-template reference.
-- `argument`: completion argument object for `complete`, with `name` and `value`.
-
-Validation rules:
-
-- Request validation remains strict: operation-specific extra fields are rejected.
-- `list_resources`, `list_resource_templates`, and `list_prompts` accept optional `limit` only.
-- `search_resources` and `search_prompts` require `query` and accept optional `limit`.
-- `read_resource` requires `uri`.
-- `get_prompt` requires `prompt`; `arguments` is optional and defaults to `{}`.
-- `complete` requires `ref` and `argument`.
-- Search/list limits reuse `maxSearchLimit` and `defaultSearchLimit`.
-- `fields` remains valid only for `call_tool`.
-
-## Resource operations
-
-### `list_resources`
-
-Calls downstream `resources/list`, paginating as needed until the requested limit is satisfied or no cursor remains. Returns compact resource metadata:
-
-```json
-{
-  "id": "docs",
-  "name": "Docs",
-  "resources": [
-    {
-      "id": "docs",
-      "uri": "file:///repo/README.md",
-      "name": "README",
-      "description": "Project README",
-      "mimeType": "text/markdown"
-    }
-  ],
-  "nextCursor": "..."
-}
-```
-
-If `limit` truncates a page before consuming all downstream items, Caplets may omit `nextCursor` unless it can safely preserve downstream cursor semantics. The first implementation should prefer fetching full pages and slicing only the final result set for deterministic agent output.
-
-### `search_resources`
-
-Searches listed resources and resource templates with deterministic case-insensitive lexical matching over:
-
-- `uri`
-- `name`
-- `description`
-- `mimeType`
-
-The result should identify whether each match is a concrete resource or a template.
-
-### `list_resource_templates`
-
-Calls downstream `resources/templates/list` and returns compact template metadata:
-
-```json
-{
-  "id": "docs",
-  "name": "Docs",
-  "resourceTemplates": [
-    {
-      "id": "docs",
-      "uriTemplate": "file:///repo/{path}",
-      "name": "Repository file",
-      "description": "Read a file by repository path",
-      "mimeType": "text/plain"
-    }
-  ]
-}
-```
-
-### `read_resource`
-
-Calls downstream `resources/read` with the exact URI and returns the downstream result contents without lossy transformation. Caplets adds `_meta.caplets` with server ID, backend, operation, URI, status, and elapsed timing.
-
-## Prompt operations
-
-### `list_prompts`
-
-Calls downstream `prompts/list`, paginating as needed until the requested limit is satisfied or no cursor remains. Returns compact prompt metadata:
-
-```json
-{
-  "id": "linear",
-  "name": "Linear",
-  "prompts": [
-    {
-      "id": "linear",
-      "prompt": "review_issue",
-      "description": "Review a Linear issue before implementation",
-      "arguments": [{ "name": "issueId", "description": "Linear issue ID", "required": true }]
-    }
-  ]
-}
-```
-
-### `search_prompts`
-
-Searches listed prompts with deterministic case-insensitive lexical matching over:
-
-- prompt name
-- prompt description
-- argument names
-- argument descriptions
-
-### `get_prompt`
-
-Calls downstream `prompts/get` with exact prompt name and optional arguments. Returns downstream prompt messages without lossy transformation and adds `_meta.caplets` with server ID, backend, operation, prompt name, status, and elapsed timing.
-
-## Completion operation
-
-### `complete`
-
-For MCP-backed Caplets whose downstream server advertises completions, Caplets forwards `completion/complete`.
-
-Example prompt completion request:
-
-```json
-{
-  "operation": "complete",
-  "ref": { "type": "prompt", "name": "review_issue" },
-  "argument": { "name": "issueId", "value": "CAP-" }
-}
-```
-
-Example resource-template completion request:
-
-```json
-{
-  "operation": "complete",
-  "ref": { "type": "resourceTemplate", "uri": "file:///repo/{path}" },
-  "argument": { "name": "path", "value": "src/" }
-}
-```
-
-Caplets returns the downstream completion result unchanged except for `_meta.caplets` metadata.
-
-## Capability discovery and `get_caplet`
-
-`get_caplet` should remain cheap and must not start the downstream server. It can report configured backend type and static Caplets metadata only.
-
-After a backend has been checked or used, Caplets may include last-known observed MCP capability metadata in registry status or operation results, but it must not make `get_caplet` perform live probing.
-
-For MCP-backed Caplets, `check_backend` should connect and report observed capabilities:
-
-```json
-{
-  "id": "docs",
-  "status": "available",
-  "capabilities": {
-    "tools": true,
-    "resources": true,
-    "resourceTemplates": true,
-    "prompts": true,
-    "completions": true
-  },
-  "toolCount": 12,
-  "resourceCount": 4,
-  "resourceTemplateCount": 2,
-  "promptCount": 3,
-  "elapsedMs": 42
-}
-```
-
-Counts are best-effort. If a capability exists but counting fails, `check_backend` should still report the capability and include safe structured error details for the failed count.
-
-## Caching and invalidation
-
-Extend managed MCP connections to cache each list independently:
-
-- tools
-- resources
-- resource templates
-- prompts
-
-Each cache entry should track `fetchedAt` and use the existing `toolCacheTtlMs` initially. A later config option may rename this to `metadataCacheTtlMs`; this design intentionally avoids a config migration in the first implementation.
-
-When the SDK exposes list-changed callbacks or notifications, wire them to invalidate the relevant cache:
-
-- `notifications/resources/list_changed` invalidates resource and resource-template caches.
-- `notifications/prompts/list_changed` invalidates prompt caches.
-- Existing or future tool-list notifications invalidate the tool cache.
-
-If the server does not advertise list-changed support, rely on TTL.
-
-## Backend abstraction
-
-The existing backend adapter shape should split common tool operations from MCP-only operations.
-
-Suggested internal types:
-
-```ts
-type ToolBackend = {
-  check(config: never): Promise<unknown>;
-  listTools(config: never): Promise<Tool[]>;
-  getTool(config: never, toolName: string): Promise<Tool>;
-  callTool(config: never, toolName: string, args: Record<string, unknown>): Promise<unknown>;
-  compact(config: never, tool: Tool): unknown;
-  search(config: never, tools: Tool[], query: string, limit: number): unknown[];
-};
-
-type McpCapabilityBackend = ToolBackend & {
-  listResources(config: never, limit?: number): Promise<unknown>;
-  searchResources(config: never, query: string, limit: number): Promise<unknown>;
-  listResourceTemplates(config: never, limit?: number): Promise<unknown>;
-  readResource(config: never, uri: string): Promise<unknown>;
-  listPrompts(config: never, limit?: number): Promise<unknown>;
-  searchPrompts(config: never, query: string, limit: number): Promise<unknown>;
-  getPrompt(config: never, prompt: string, args: Record<string, unknown>): Promise<unknown>;
-  complete(config: never, request: CompletionRequest): Promise<unknown>;
-};
-```
-
-Only MCP-backed Caplets should resolve to `McpCapabilityBackend` for MCP-specific operations. Non-MCP backends should not need stub implementations for resources or prompts.
-
-## Error handling
-
-New structured errors:
-
-- `UNSUPPORTED_OPERATION`: operation is not valid for command-semantic CLI/remote-control routing or for a stale client using an operation that the generated Caplet schema no longer advertises.
-- `UNSUPPORTED_CAPABILITY`: backend is MCP, but the downstream server does not advertise the requested MCP capability.
-- `RESOURCE_NOT_FOUND`: downstream resource read reports an absent URI or Caplets cannot resolve a listed resource when resolution is required.
-- `PROMPT_NOT_FOUND`: requested prompt name is absent from fresh-enough prompt metadata.
-- `DOWNSTREAM_RESOURCE_ERROR`: downstream `resources/read` fails.
-- `DOWNSTREAM_PROMPT_ERROR`: downstream `prompts/get` fails.
-- `DOWNSTREAM_COMPLETION_ERROR`: downstream `completion/complete` fails.
-
-Timeouts use the existing startup timeout for list/check style operations and call timeout for read/get/complete style operations unless implementation discovers a stronger SDK convention.
-
-All errors must pass through existing safe-error redaction before being surfaced.
-
-## CLI behavior
-
-Add direct CLI operation commands mirroring the agent-facing API:
-
-```sh
-caplets list-resources docs
-caplets list-resource-templates docs
-caplets read-resource docs file:///repo/README.md
-caplets list-prompts linear
-caplets get-prompt linear.review_issue --args '{"issueId":"CAP-123"}'
-caplets complete linear --prompt review_issue --argument issueId --value CAP-
-```
-
-Remote mode should route these commands through the existing command-semantic remote control API, preserving server-owned state and never exposing downstream auth secrets.
-
-Non-MCP backends should fail fast with a clear message if a user explicitly invokes one of these MCP-specific CLI commands against them.
-
-## Native integrations
-
-Pi and OpenCode native integrations should receive backend-specific schemas just like MCP clients. A native tool generated for an MCP-backed Caplet includes MCP resource/prompt/completion operations; a native tool generated for a non-MCP Caplet does not.
-
-Prompt guidance should nudge agents toward the right primitive:
-
-- Use tools for actions and side effects.
-- Use resources for readable context and artifacts.
-- Use prompts for reusable downstream workflows or prompt templates.
-- Use completions when filling prompt or resource-template arguments.
-
-## Testing strategy
-
-Add deterministic fixtures for MCP servers that expose:
-
-- tools only
-- resources only
-- resource templates only
-- prompts only
-- completions only
-- tools, resources, templates, prompts, and completions together
-- advertised capability with failing downstream request
-- no advertised capability for requested MCP operation
-
-Regression coverage should verify:
-
-- Non-MCP generated schemas do not include MCP-specific operations.
-- MCP generated schemas include resource, prompt, template, and completion operations.
-- Strict operation-specific validation rejects extra fields.
-- Resource and prompt list/search output is compact and deterministic.
-- `read_resource`, `get_prompt`, and `complete` preserve downstream result shape and add Caplets metadata.
-- Unsupported downstream capabilities return `UNSUPPORTED_CAPABILITY`.
-- Missing prompt/resource cases return structured errors without forwarding unsafe guesses.
-- Caches refresh according to TTL and invalidate on list-changed notifications where available.
-- CLI commands work locally and through remote mode.
-- Initial Caplets `tools/list` remains one top-level tool per enabled Caplet.
-
-## Documentation updates
-
-Update:
-
-- `README.md`: explain MCP-backed Caplets can expose tools, resources, prompts, and completions behind one capability card.
-- CLI help and examples for resource/prompt/completion commands.
-- Native integration README files for Pi and OpenCode schema differences.
-- Benchmark documentation only if the serialized initial tool schema size materially changes.
-
-## Rollout plan
-
-1. Introduce backend-aware generated operation schemas while preserving current behavior for all backends.
-2. Add MCP resource and prompt list/read/get support in `DownstreamManager`.
-3. Add search and compact metadata helpers for resources, templates, and prompts.
-4. Add completion forwarding.
-5. Add CLI and remote-control operation support.
-6. Update native integrations to consume backend-specific schemas and descriptions.
-7. Update documentation and benchmark expectations if needed.
diff --git a/docs/specs/2026-05-26-lsp-registry-caplet-design.md b/docs/specs/2026-05-26-lsp-registry-caplet-design.md
deleted file mode 100644
index 7b8b4ea1..00000000
--- a/docs/specs/2026-05-26-lsp-registry-caplet-design.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# LSP Registry Caplet Design
-
-## Goal
-
-Make `caplets/lsp` a polished, first-class registry example that wraps `language-server-mcp` through Caplets' MCP backend and is discoverable in the repository examples, tests, and coding-agent toolkit.
-
-## Context
-
-The repository already has `caplets/lsp/CAPLET.md` with a valid minimal MCP manifest:
-
-```yaml
-name: lsp
-description: Language Server Protocol
-tags:
-  - mcp
-  - code
-  - lsp
-mcpServer:
-  command: npx
-  args: [-y, language-server-mcp]
-```
-
-The published `language-server-mcp` package exposes LSP capabilities over stdio, starts local language servers lazily, and supports tools such as hover, definitions, references, diagnostics, symbols, formatting, code actions, and workspace edits.
-
-## Scope
-
-In scope:
-
-- Expand `caplets/lsp/CAPLET.md` from a stub into a polished Caplet card.
-- Keep the backend as `npx -y language-server-mcp`.
-- Improve the manifest description and tags for search and discovery.
-- Add usage guidance for project configuration, server selection, file-targeted inputs, and safety defaults.
-- Add `lsp` to the README example list.
-- Add `lsp` to the `coding-agent-toolkit` CapletSet via a symlink to the canonical top-level example.
-- Extend repository example tests so `lsp` is loaded and validated with the other showcase Caplets.
-- Add a changeset for the user-facing registry/example update.
-
-Out of scope:
-
-- Creating a new `@caplets/lsp` package in the monorepo.
-- Implementing new LSP functionality inside Caplets core.
-- Replacing `language-server-mcp` or forking its tool surface.
-- Adding project-specific `.lsp-mcp.jsonc` files to this repository.
-
-## Architecture
-
-`caplets/lsp` remains a directory-style Markdown Caplet with a single MCP backend. Caplets launches `language-server-mcp` over stdio with `npx`, then exposes it through the same progressive MCP operations as other MCP-backed Caplets: `check_backend`, `list_tools`, `search_tools`, `get_tool`, `call_tool`, resources, prompts, templates, and completion when supported by the downstream server.
-
-The `coding-agent-toolkit` entry should include `lsp` as a source-tree symlink under `caplets/coding-agent-toolkit/caplets/lsp`. Existing install behavior materializes symlinked child Caplets as self-contained files/directories, so installed toolkit copies should not depend on the source repository symlink layout.
-
-## Caplet content design
-
-The `CAPLET.md` body should include these sections:
-
-1. **Overview** — explain that the Caplet gives agents project-aware language intelligence through LSP without exposing every LSP tool directly up front.
-2. **Good Fits** — hover/type info, go-to definition/declaration/implementation, references, diagnostics, symbols, formatting, code actions, rename/workspace edits, and language-server-backed code review/planning.
-3. **Setup** — describe `.lsp-mcp.jsonc`, built-in registry IDs and aliases, optional `serverId`, `workspaceRoot`, `filePath`, `line`, and `character` inputs.
-4. **Safety** — document edit-producing tools returning edits by default, explicit `apply: true`, workspace-root restrictions, multi-server `serverId` requirements for applied edits, `workspace/executeCommand` controls, lazy startup, idle shutdown, and managed download controls.
-5. **Examples** — include concise JSON examples for hover and diagnostics/code actions that show the expected path-based inputs without hardcoding this repository's absolute paths.
-
-## README design
-
-Add `lsp` to the polished working examples list near the other code-focused MCP examples. The entry should make clear that it wraps `language-server-mcp` for LSP-backed code intelligence.
-
-## Test design
-
-Extend the existing showcase Caplets test in `packages/core/test/config.test.ts` so it asserts `config.mcpServers.lsp` loads with:
-
-- `server: "lsp"`
-- `name: "LSP"` or another intentionally chosen display name from the manifest
-- `command: "npx"`
-- `args: ["-y", "language-server-mcp"]`
-
-The existing `validateCapletFile` and reference-file tests should continue to validate the expanded Caplet automatically. No network or live LSP server startup should be required for this test; it should only validate config loading from repository Caplet files.
-
-## Release notes
-
-Add a changeset for `caplets` because this changes the user-facing registry examples and the installable toolkit contents. The changeset should describe the new polished LSP example and toolkit inclusion.
-
-## Risks and mitigations
-
-- **Risk: users expect a package named `@caplets/lsp`.** Mitigation: documentation should describe this as a registry Caplet wrapping `language-server-mcp`, not as a monorepo package.
-- **Risk: live LSP behavior depends on project configuration and installed language servers.** Mitigation: setup docs should point users to `.lsp-mcp.jsonc`, built-ins, aliases, and managed-download controls.
-- **Risk: edit-producing tools can modify files.** Mitigation: safety docs must clearly state default return-edits behavior and the explicit requirements for applying edits.
-- **Risk: toolkit symlink breaks installation.** Mitigation: rely on existing symlink materialization behavior and keep the symlink inside the `caplets/coding-agent-toolkit/caplets` tree.
-
-## Verification
-
-Run focused checks after implementation:
-
-```sh
-pnpm --filter @caplets/core test -- test/config.test.ts
-pnpm format:check
-pnpm lint
-```
-
-Run the full repository gate if focused checks pass:
-
-```sh
-pnpm verify
-```
diff --git a/docs/specs/2026-05-27-agent-card-setup-tabs-design.md b/docs/specs/2026-05-27-agent-card-setup-tabs-design.md
deleted file mode 100644
index 87d11daa..00000000
--- a/docs/specs/2026-05-27-agent-card-setup-tabs-design.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# Agent card setup tabs design
-
-## Context
-
-The landing page has an agents/integrations card that currently uses agent pills to show supported agent integrations. The desired change is to keep the card's current layout and visual model, but make each agent pill act as a tab that reveals setup instructions for that specific agent.
-
-## Goals
-
-- Preserve the existing agents card structure and overall visual treatment.
-- Turn each existing agent pill into a tab trigger.
-- Show the selected agent's install command and configuration snippet in the card.
-- Keep setup content copy-pasteable and easy to scan.
-- Make the data model extensible for additional agents.
-
-## Non-goals
-
-- Do not redesign the entire integrations section.
-- Do not add a modal, accordion, or separate setup page.
-- Do not change the core Caplets runtime behavior.
-
-## UX design
-
-The agents card remains visually recognizable. The current agent pills become tab controls. One pill is selected by default, and its setup content appears in a shared detail area inside the same card. Selecting another pill swaps the detail content without navigating away.
-
-The active pill should use the existing pill style with a clear selected state. The inactive pills should remain lightweight. The detail area should contain a short label, the install command, and the configuration snippet. Commands and snippets should be styled as code blocks and fit the existing landing page aesthetic.
-
-## Data model
-
-Represent each agent as structured data with fields similar to:
-
-```ts
-{
-  name: string;
-  summary: string;
-  installCommand: string;
-  configSnippet: string;
-  note?: string;
-}
-```
-
-Rendering should map over this data rather than hardcoding per-agent markup. That keeps future agent additions localized to the data list.
-
-## Interaction and accessibility
-
-Use tab semantics where practical: each pill should behave like a tab, the selected setup area should behave like a tab panel, and keyboard navigation should not regress from the current page. If the page remains mostly static Astro output, the tab behavior can be implemented with minimal client-side JavaScript scoped to this card.
-
-## Testing
-
-Add focused coverage for the landing page source or component behavior where the repo's current test setup supports it:
-
-- Agent tab labels render.
-- The default selected agent's install command and configuration snippet render.
-- Selecting another pill reveals the matching command/configuration.
-- Agent setup data remains centralized rather than duplicated in separate markup blocks.
-
-## Implementation notes
-
-The likely implementation target is `apps/landing/src/pages/index.astro` plus any supporting CSS in `apps/landing/src/styles/global.css`. The change should respect the current landing page style and avoid unrelated cleanup.
diff --git a/docs/specs/2026-05-29-landing-proof-led-activation-design.md b/docs/specs/2026-05-29-landing-proof-led-activation-design.md
deleted file mode 100644
index 8a6bfd4e..00000000
--- a/docs/specs/2026-05-29-landing-proof-led-activation-design.md
+++ /dev/null
@@ -1,123 +0,0 @@
-# Landing page proof-led activation design
-
-## Goal
-
-Revise the Caplets landing page so it matches the product promise: reveal one clear capability story first, then provide deeper evidence and setup details only when useful. The page should drive agent power users and MCP server builders toward installing the right agent plugin, integration, or MCP client setup with Context7 as the first capability source. Preserve the campaign headline: “Caplets: Give your agents capabilities, not giant tool walls”.
-
-## Current problems to fix
-
-1. The page explains progressive disclosure but currently presents many equal-weight sections, cards, tabs, trust details, and install steps.
-2. The activation path appears too late for power users who want proof quickly.
-3. Numbered nav markers, repeated eyebrow labels, wide shadows, and repeated bordered card patterns create AI-generated landing-page residue.
-4. The install path overemphasizes manually running `caplets serve`. The primary activation path should be agent-native: plugin install, integration setup, or MCP client configuration.
-5. The hero trace is conceptually strong but visually too close to a polished SaaS card.
-
-## Proposed direction
-
-Use a proof-led activation structure:
-
-1. Hero claim and flattened trace artifact.
-2. Compact benchmark proof strip immediately after hero.
-3. “Add Caplets to your agent” activation section near the top, using Context7 as the first source.
-4. Compressed explanation of problem, capability model, and safety mechanics.
-5. Detailed integrations as a supporting section after the primary activation path.
-
-This keeps the page focused on the launch campaign and avoids a full visual reset.
-
-## Detailed design
-
-### 1. Hero
-
-- Keep the primary headline: “Give your agents capabilities, not giant tool walls.”
-- Keep the current progressive disclosure trace because it explains the product better than a decorative illustration.
-- Remove numbered top navigation markers. Nav labels should be plain section names such as “Trace”, “Proof”, and “Install”.
-- Reduce the trace artifact’s wide shadow and overly rounded card feel. It should read as a technical artifact: flatter, sharper, and more inspectable.
-- Keep the primary CTA focused on adding Caplets to the user's agent, not on manually running the server. The page must surface a fast Context7 trial path near the top.
-
-### 2. Benchmark proof strip
-
-- Move deterministic proof close to the hero.
-- Show the three proof facts compactly:
-  - 106 flat tools
-  - 3 capability cards
-  - 87.9% smaller initial payload
-- Link the proof strip to `docs/benchmarks/coding-agent.md` or an equivalent public benchmark URL if available in the site routing.
-- Avoid the hero-metric template. The proof should feel like a benchmark note or evidence row, not a celebratory stats block.
-
-### 3. Agent-native Context7 activation section
-
-- Place the activation section before the long explanatory material.
-- Lead with agent-native setup choices, not a manual `caplets serve` workflow.
-- Recommended primary paths:
-  - Claude Code: install the Caplets plugin from the marketplace.
-  - Codex: add the Caplets plugin marketplace and install the plugin.
-  - OpenCode: install `caplets` and use the native `@caplets/opencode` plugin.
-  - Pi: install `caplets` and add `npm:@caplets/pi`.
-  - Any MCP client: configure the client to launch `caplets serve` as its MCP server command.
-- Use Context7 as the first capability source after the agent integration is in place:
-  - `caplets init`
-  - `caplets add mcp context7 --command npx --arg -y --arg @upstash/context7-mcp`
-- Show expected result inside the agent:
-  - The agent starts with a `context7` capability.
-  - The next path is `inspect`, `search_tools`, `get_tool`, `call_tool`.
-- Add a concise troubleshooting line for common activation blockers: Node version, `npx`, plugin installation, and MCP client configuration.
-- Preserve copy buttons and keyboard accessibility.
-
-### 4. Compressed explanation
-
-Replace the current repeated middle sections with a tighter explanation. It should cover:
-
-- Flat tool walls force agents to choose before they understand.
-- Caplets exposes one capability first, then scoped search and schema inspection.
-- Trust is visible before invocation through source, auth state, timeout boundary, and safe error recovery.
-
-The section should not become another identical card grid. Prefer a single structured comparison, a compact checklist, or a source-manifest style artifact.
-
-### 5. Integrations
-
-- Keep integration tabs because they are now part of the primary activation story: where can Caplets run, and what should the user install for their agent?
-- Surface the most common integrations near the activation path. The full tabbed setup can remain lower on the page as the expanded reference.
-- For MCP clients, present `caplets serve` as the configured command the client launches, not as the main thing the user runs manually.
-- Preserve tab semantics, keyboard navigation, copy buttons, and mobile behavior.
-
-## Copy and visual constraints
-
-- No em dashes in prose.
-- Avoid `--` in visible body copy except command-line flags inside code.
-- No gradient text.
-- No side-stripe card accents.
-- No glassmorphism.
-- Avoid hero-metric styling.
-- Avoid repeated numbered section markers.
-- Reduce repeated eyebrow cadence. Use labels sparingly where they add orientation.
-- Preserve existing OKLCH token system and brand colors unless a local contrast fix is required.
-- Keep display heading letter spacing at or above `-0.04em`.
-- Keep body copy line length under roughly 75ch.
-
-## Accessibility and interaction requirements
-
-- No horizontal overflow at desktop or mobile widths.
-- All buttons and links must remain keyboard reachable.
-- Tab controls must retain `role="tablist"`, `role="tab"`, `role="tabpanel"`, selected state, and arrow-key behavior.
-- Copy buttons must preserve success feedback and fallback text selection behavior.
-- Reveal motion must preserve visible defaults and support `prefers-reduced-motion: reduce`.
-- Mobile touch targets should remain at least 44px high.
-
-## Verification plan
-
-Run these checks before claiming completion:
-
-1. Browser inspection on the user dev server at desktop and mobile widths.
-2. Confirm no horizontal overflow.
-3. Confirm no browser console errors or warnings.
-4. Run the campaign copy assertion or equivalent source assertion for the key headline, proof facts, agent integration activation paths, and Context7 source setup.
-5. Run `pnpm --filter @caplets/landing typecheck`.
-6. Run `pnpm --filter @caplets/landing build`.
-7. Run `git diff --check`.
-
-## Out of scope
-
-- Changing package manager versions.
-- Modifying unrelated `.brv/` memory files.
-- Rebuilding the entire brand identity.
-- Adding new dependencies unless the implementation cannot meet the design without them.
diff --git a/docs/specs/2026-06-10-mcp-tool-use-pi-eval-design.md b/docs/specs/2026-06-10-mcp-tool-use-pi-eval-design.md
deleted file mode 100644
index 8fb0f199..00000000
--- a/docs/specs/2026-06-10-mcp-tool-use-pi-eval-design.md
+++ /dev/null
@@ -1,429 +0,0 @@
-# MCP Tool-Use Pi Eval Suite
-
-## Status
-
-Approved design direction from brainstorming. Implementation plan not yet written.
-
-## Goal
-
-Extend the existing live Pi eval harness with a deterministic MCP tool-use suite that measures whether Caplets improves total-token efficiency for realistic multi-tool backend workflows while preserving successful runs.
-
-The suite should exercise the kind of work Caplets is meant to improve:
-
-- discovering the right backend capability without flattening every downstream tool into the prompt
-- making dependent MCP tool calls across one or more servers
-- reading noisy tool results without carrying unnecessary detail forward
-- producing a concise final answer backed by tool evidence
-
-## User Intent
-
-The current coding-agent Pi eval is useful for comparing coding workflow surfaces, but it is too workspace-editing-specific to prove that Caplets creates durable token-efficiency gains for MCP backend use. The new suite should focus directly on MCP server usage and the Caplets progressive-disclosure advantage.
-
-This must not become benchmark-specific prompt tuning. The fixture servers and tasks should be generic enough that an agent could encounter the same shapes in a real user config: API catalogs, incident systems, customer records, deployment status, quality checks, and policy documents.
-
-## Non-Goals
-
-- Do not replace the existing coding-agent Pi eval suite.
-- Do not import MCP-Bench as an external validation benchmark.
-- Do not depend on live external services, API keys, cloud accounts, or mutable remote datasets.
-- Do not modify Caplets runtime behavior as part of this design-only step.
-- Do not add task-specific special cases to Caplets, the Pi integration, or benchmark scoring.
-- Do not optimize for request-token reduction alone. The primary efficiency metric is total provider tokens: request plus response.
-- Do not require workspace edits for this suite.
-
-## MCP-Bench Shape, Not Dependency
-
-MCP-Bench is useful as a reference shape because its tasks model realistic MCP use through task descriptions, fuzzy descriptions, dependency analysis, multi-server workflows, and judge-backed validation.
-
-This suite should borrow those structural ideas, not the benchmark itself. MCP-Bench relies on external servers, API keys, live services, configured model providers, and judge-model stability checks. Those dependencies make it a poor fit for this local Caplets comparison, where we need repeatable fixture behavior and direct attribution of token deltas to MCP surface design.
-
-Reference shape:
-
-- task record fields inspired by `task_description`, `fuzzy_description`, and `dependency_analysis`
-- single-server, two-server, and three-server workflows
-- tasks that require dependent tool calls rather than one independent lookup
-- validation against final answer facts and tool evidence
-
-## Command Surface
-
-Extend the existing command rather than adding a parallel benchmark:
-
-From the `caplets-mono` root:
-
-```bash
-CAPLETS_BENCH_LIVE=1 pnpm --dir ./core run benchmark:live:pi-eval -- \
-  --task-suite mcp-tool-use \
-  --model openai-codex/gpt-5.5 \
-  --runs 4 \
-  --concurrency 8
-```
-
-The default remains the current coding-agent behavior:
-
-From the `caplets-mono` root:
-
-```bash
-CAPLETS_BENCH_LIVE=1 pnpm --dir ./core run benchmark:live:pi-eval
-```
-
-Before authoritative runs, build Core first:
-
-From the `caplets-mono` root:
-
-```bash
-pnpm --dir ./core run build &&
-CAPLETS_BENCH_LIVE=1 pnpm --dir ./core run benchmark:live:pi-eval -- \
-  --task-suite mcp-tool-use \
-  --model openai-codex/gpt-5.5 \
-  --runs 4 \
-  --concurrency 8
-```
-
-Routine iteration should not pass `--preserve-artifacts`; preserved artifacts are reserved for debugging specific failures.
-
-## Suite Registry
-
-Add a Pi eval suite registry, likely in `packages/benchmarks/lib/pi-eval/suites.ts`.
-
-Initial suites:
-
-- `coding`: current default behavior
-- `mcp-tool-use`: deterministic local MCP tool-use tasks
-
-Each suite defines:
-
-```ts
-type PiEvalSuite = {
-  id: "coding" | "mcp-tool-use";
-  label: string;
-  fixtureRoot: string;
-  tasksPath: string;
-  workspaceRoot: string | null;
-  buildPrompt: (task: PiEvalTask) => string;
-  scoreRun: (input: PiEvalScoreInput) => PiEvalScore;
-  coverage: PiEvalCoverageSpec;
-};
-```
-
-The registry keeps shared mode execution intact:
-
-- `caplets-direct`
-- `caplets-progressive`
-- `caplets-code-mode`
-- `caplets-progressive-code-mode`
-- `vanilla-mcp`
-- `executor-mcp`
-
-Mode setup, concurrency, token accounting, report output, Executor detection, and Pi invocation should stay shared.
-
-## Fixture Layout
-
-Add the new suite under a dedicated fixture root:
-
-```text
-packages/benchmarks/fixtures/mcp-tool-use/
-  tasks.json
-  mcp-server.ts
-  validators/
-    api-pagination-audit-validator.ts
-    incident-customer-impact-join-validator.ts
-    release-readiness-risk-report-validator.ts
-```
-
-The suite does not need a candidate workspace. If shared runner plumbing requires a workspace path, use an empty deterministic temp workspace and keep scoring independent from file mutations.
-
-## Task Record Shape
-
-`tasks.json` should support fields that are useful to humans, prompts, and validators:
-
-```json
-{
-  "id": "incident-customer-impact-join",
-  "title": "Incident customer impact join",
-  "task_description": "Find the active incident, join affected accounts to customer details, and return the customer impact summary.",
-  "fuzzy_description": "The agent must discover which incident and customer tools matter, ignore unrelated records, and combine results across servers.",
-  "dependency_analysis": {
-    "servers": ["incidents", "customers"],
-    "requires": [
-      "find active incident",
-      "read affected account IDs",
-      "join account tiers, regions, and escalation contacts"
-    ]
-  },
-  "expectedEvidence": {
-    "servers": ["incidents", "customers"],
-    "tools": ["incidents.search_incidents", "incidents.get_incident", "customers.get_accounts"]
-  },
-  "validator": "incident-customer-impact-join"
-}
-```
-
-Task prompts should ask for a JSON final answer with a known schema. The prompt should not reveal expected tool names, exact IDs, or scoring facts beyond the user-facing task.
-
-## Final Answer Contract
-
-For `mcp-tool-use`, the final assistant answer should contain extractable JSON:
-
-```json
-{
-  "taskId": "incident-customer-impact-join",
-  "decision": "summary_or_go_no_go_value",
-  "facts": [
-    {
-      "key": "activeIncidentId",
-      "value": "INC-2026-0610-2",
-      "evidence": ["incidents.get_incident"]
-    }
-  ],
-  "summary": "Concise user-facing answer."
-}
-```
-
-Validators may accept surrounding prose if the JSON block can be extracted. The scoring contract should prefer strict, stable keys over free-form natural-language matching.
-
-## Initial Tasks
-
-### `api-pagination-audit`
-
-Single-server deep discovery.
-
-Server: `api_catalog`
-
-The agent compares search/list endpoints across three product APIs and identifies which operations are paginated, how pagination works, and the required parameter names.
-
-Fixture properties:
-
-- noisy catalog list with unrelated endpoints
-- detailed endpoint descriptions behind per-operation lookups
-- at least one fallback list endpoint that looks relevant but lacks required pagination behavior
-- nested input schema for endpoint detail lookup
-
-Validator checks:
-
-- required operation IDs are present
-- pagination styles are correct
-- required parameter names are correct
-- fallback/non-paginated endpoint is not misclassified
-- final facts cite tool-backed evidence
-
-### `incident-customer-impact-join`
-
-Two-server dependent workflow.
-
-Servers: `incidents`, `customers`
-
-The agent finds the active incident, fetches affected account IDs, joins customer details, and reports the impact summary by tier and region with escalation targets.
-
-Fixture properties:
-
-- multiple incidents with similar names and statuses
-- affected account IDs are available only after fetching incident details
-- customer records are fetched in batches
-- distractor accounts and stale incidents exist
-
-Validator checks:
-
-- active incident ID is correct
-- affected account count is correct
-- tier and region breakdowns are correct
-- escalation contacts are correct
-- stale incident and unrelated customer facts are excluded
-
-### `release-readiness-risk-report`
-
-Three-server bulky evidence join.
-
-Servers: `deployments`, `quality`, `policies`
-
-The agent decides whether a release can proceed by combining deployment state, failing quality checks, policy exceptions, and risk thresholds.
-
-Fixture properties:
-
-- deployment records with similar versions and environments
-- quality checks with pass, fail, warning, and skipped states
-- policy thresholds requiring interpretation rather than direct copy
-- exception records where some are expired or scoped to another service
-
-Validator checks:
-
-- final go/no-go decision is correct
-- blocking checks are identified
-- policy threshold interpretation is correct
-- valid exceptions are applied and invalid ones ignored
-- cited evidence spans all three servers
-
-## Fixture Server Design
-
-The local MCP fixture should expose realistic tool-use shapes:
-
-- compact obvious discovery tools
-- schema-requiring detail tools with nested arguments
-- noisy list/search responses with distractor records
-- deterministic stable IDs
-- batch tools where appropriate
-- result sizes large enough to make progressive discovery meaningful
-
-Example server groups:
-
-```text
-api_catalog
-  search_apis
-  list_operations
-  get_operation
-  compare_operations
-
-incidents
-  search_incidents
-  get_incident
-  list_affected_accounts
-
-customers
-  get_accounts
-  summarize_accounts
-
-deployments
-  list_releases
-  get_release
-
-quality
-  list_checks
-  get_check_details
-
-policies
-  get_release_policy
-  list_exceptions
-```
-
-Tool descriptions and schemas should be realistic, but they must not contain benchmark-specific hints such as "this is the correct tool for the eval."
-
-## Scoring
-
-Success requires:
-
-- Pi process exits successfully and does not time out
-- final answer JSON can be extracted
-- required facts match deterministic expected values
-- required server/tool evidence appears in captured events or final citations
-- distractor trap facts are not selected
-
-Primary efficiency metric:
-
-- total provider tokens, request plus response
-
-Secondary metrics:
-
-- provider request tokens
-- provider response tokens
-- provider request count
-- MCP tool call count
-- tool-result message tokens
-- pass rate
-- suite-specific coverage score
-
-The existing total-token gap penalty should remain the main comparison signal. A mode that uses fewer request tokens but causes larger response output should not be counted as an efficiency win.
-
-## Reporting
-
-The existing markdown report should include suite identity and preserve current coding-suite output by default.
-
-For `mcp-tool-use`, add task-level rows for:
-
-- mode
-- task
-- run index
-- success/failure
-- total provider tokens
-- request tokens
-- response tokens
-- request count
-- tool calls
-- coverage score
-- validator summary
-
-Aggregate comparison should still answer the same product question: whether `caplets-progressive`, `caplets-code-mode`, and `caplets-progressive-code-mode` consistently beat `vanilla-mcp` and `executor-mcp` on total-token efficiency while maintaining successful runs.
-
-## Implementation Boundaries
-
-### `packages/benchmarks/run-pi-eval.ts`
-
-- Add `--task-suite <suite>` with default `coding`.
-- Select suite config before loading tasks.
-- Use suite-specific prompt builder and scorer.
-- Use workspace setup only when the suite has a workspace root.
-- Keep shared run matrix, concurrency, reports, and token accounting.
-
-### `packages/benchmarks/lib/pi-eval/config.ts`
-
-- Make fixture server path configurable per suite.
-- Keep Caplets, vanilla MCP, and Executor config generation shared.
-- Preserve current mode semantics.
-
-### `packages/benchmarks/lib/pi-eval/metrics.ts`
-
-- Generalize hardcoded coding domain coverage into suite-specific coverage specs.
-- Preserve current coding coverage behavior exactly for `task-suite=coding`.
-
-### `packages/benchmarks/lib/pi-eval/report.ts`
-
-- Include suite label in report metadata.
-- Render validator summaries for non-coding suites.
-- Preserve current report shape where possible so historical coding reports remain comparable.
-
-## Tests
-
-Add focused tests for:
-
-- `--task-suite` parsing and validation
-- default `coding` suite preserving existing behavior
-- unknown suite error message
-- suite registry task path and fixture path resolution
-- MCP tool-use prompt generation
-- successful final JSON extraction
-- validator failure for missing facts
-- validator failure for distractor facts
-- suite-specific coverage calculation
-- config generation using the MCP tool-use fixture server
-- report rendering with suite metadata
-
-Run the local gate relevant to the implementation:
-
-From the `caplets-mono` root:
-
-```bash
-pnpm --dir ./core run build
-pnpm --dir ./core --filter @caplets/benchmarks test
-```
-
-Before treating live results as authoritative:
-
-From the `caplets-mono` root:
-
-```bash
-pnpm --dir ./core run build &&
-CAPLETS_BENCH_LIVE=1 pnpm --dir ./core run benchmark:live:pi-eval -- \
-  --task-suite mcp-tool-use \
-  --model openai-codex/gpt-5.5 \
-  --runs 4 \
-  --concurrency 8
-```
-
-## Rollout
-
-1. Land suite-selection plumbing with `coding` as the default and no behavior change.
-2. Add deterministic MCP tool-use fixtures and validators.
-3. Add `mcp-tool-use` reporting and coverage fields.
-4. Run local tests and a small live smoke with one task and one run.
-5. Run the full live suite with build-first command and no preserved artifacts.
-6. Compare modes on total provider tokens and pass rate.
-
-## Risks
-
-- **Prompt overfitting:** avoid naming exact expected tools or facts in prompts.
-- **Validator brittleness:** validate structured final JSON and captured tool evidence instead of relying only on natural-language matching.
-- **Fixture unreality:** keep tool schemas and records generic business/backend shapes, not benchmark puzzles.
-- **Metric drift:** keep total provider tokens as the primary metric and report request/response split for diagnosis.
-- **Regression risk:** default suite must remain `coding`, with existing coding scoring and coverage unchanged.
-
-## Review Gate
-
-After this spec is reviewed, write a separate implementation plan before code changes. The implementation plan should break the work into suite plumbing, fixture server, validators, reporting, tests, and live-eval verification.
diff --git a/output/playwright/cloud-ui-critique.png b/output/playwright/cloud-ui-critique.png
deleted file mode 100644
index a398c92d..00000000
Binary files a/output/playwright/cloud-ui-critique.png and /dev/null differ
diff --git a/packages/core/src/auth.ts b/packages/core/src/auth.ts
index 3d33d9eb..9c84f3c4 100644
--- a/packages/core/src/auth.ts
+++ b/packages/core/src/auth.ts
@@ -65,19 +65,46 @@ export function staticRemoteHeaders(server: CapletServerConfig): Record<string,
   return {};
 }
 
-export function oauthHeaders(server: CapletServerConfig, authDir?: string): Record<string, string> {
+export async function oauthHeaders(
+  server: CapletServerConfig,
+  authDir?: string,
+): Promise<Record<string, string>> {
   if (server.auth?.type !== "oauth2" && server.auth?.type !== "oidc") {
     return {};
   }
-  const bundle = readTokenBundle(server.server, authDir);
-  if (!bundle?.accessToken) {
+  let bundle = readTokenBundle(server.server, authDir);
+  if (!bundle?.accessToken && !bundle?.refreshToken) {
     throw new CapletsError("AUTH_REQUIRED", `OAuth credentials required for ${server.server}`, {
       server: server.server,
       authType: server.auth.type,
       nextAction: "run_caplets_auth_login",
     });
   }
-  if (bundle.expiresAt && Date.parse(bundle.expiresAt) <= Date.now()) {
+  if (!bundle.accessToken || isTokenBundleExpired(bundle)) {
+    if (!server.url) {
+      throw new CapletsError("CONFIG_INVALID", `${server.server} is missing url`);
+    }
+    bundle = await refreshGenericOAuthBundle(
+      {
+        server: server.server,
+        backend: "http",
+        url: server.url,
+        auth: server.auth,
+      },
+      server.auth,
+      {
+        ...bundle,
+        server: server.server,
+        authType: bundle.authType ?? server.auth.type,
+        clientId: bundle.clientId ?? server.auth.clientId ?? server.auth.clientMetadataUrl,
+        clientSecret: bundle.clientSecret ?? server.auth.clientSecret,
+        protectedResourceOrigin:
+          bundle.protectedResourceOrigin ?? (server.url ? new URL(server.url).origin : undefined),
+      },
+      authDir,
+    );
+  }
+  if (!bundle.accessToken || isTokenBundleExpired(bundle)) {
     throw new CapletsError("AUTH_REFRESH_FAILED", `OAuth token for ${server.server} is expired`, {
       server: server.server,
       authType: server.auth.type,
@@ -87,16 +114,16 @@ export function oauthHeaders(server: CapletServerConfig, authDir?: string): Reco
   return { authorization: `${bundle.tokenType ?? "Bearer"} ${bundle.accessToken}` };
 }
 
-export function genericOAuthHeaders(
+export async function genericOAuthHeaders(
   target: GenericAuthTarget,
   authDir?: string,
-): Record<string, string> {
+): Promise<Record<string, string>> {
   if (target.auth?.type !== "oauth2" && target.auth?.type !== "oidc") {
     return {};
   }
   const authConfig = target.auth as OAuthLikeAuthConfig;
-  const bundle = readTokenBundle(target.server, authDir);
-  if (!bundle?.accessToken) {
+  let bundle = readTokenBundle(target.server, authDir);
+  if (!bundle?.accessToken && !bundle?.refreshToken) {
     throw new CapletsError("AUTH_REQUIRED", `OAuth credentials required for ${target.server}`, {
       server: target.server,
       backend: target.backend,
@@ -104,7 +131,11 @@ export function genericOAuthHeaders(
       nextAction: "run_caplets_auth_login",
     });
   }
-  if (isTokenBundleExpired(bundle)) {
+  assertTokenBundleMatchesTarget(bundle, target, authConfig);
+  if (!bundle.accessToken || isTokenBundleExpired(bundle)) {
+    bundle = await refreshGenericOAuthBundle(target, authConfig, bundle, authDir);
+  }
+  if (!bundle.accessToken || isTokenBundleExpired(bundle)) {
     throw new CapletsError("AUTH_REFRESH_FAILED", `OAuth token for ${target.server} is expired`, {
       server: target.server,
       backend: target.backend,
@@ -112,7 +143,6 @@ export function genericOAuthHeaders(
       nextAction: "run_caplets_auth_login",
     });
   }
-  assertTokenBundleMatchesTarget(bundle, target, authConfig);
   return { authorization: `${bundle.tokenType ?? "Bearer"} ${bundle.accessToken}` };
 }
 
@@ -867,6 +897,116 @@ async function resolveGenericClient(
   };
 }
 
+async function refreshGenericOAuthBundle(
+  target: GenericAuthTarget,
+  authConfig: OAuthLikeAuthConfig,
+  bundle: StoredOAuthTokenBundle,
+  authDir?: string,
+): Promise<StoredOAuthTokenBundle> {
+  if (!bundle.refreshToken) {
+    throw new CapletsError("AUTH_REFRESH_FAILED", `OAuth token for ${target.server} is expired`, {
+      server: target.server,
+      backend: target.backend,
+      authType: authConfig.type,
+      nextAction: "run_caplets_auth_login",
+    });
+  }
+  const allowLoopbackHttp = isLoopbackDevelopmentTarget(target, authConfig);
+  let metadata: AuthorizationServerMetadata = {};
+  let tokenEndpoint = authConfig.tokenUrl;
+  if (!tokenEndpoint) {
+    metadata = await discoverAuthorizationServer(target, authConfig, allowLoopbackHttp);
+    tokenEndpoint = metadata.token_endpoint;
+  }
+  if (!tokenEndpoint) {
+    throw new CapletsError("AUTH_REFRESH_FAILED", "OAuth metadata is missing token endpoint", {
+      server: target.server,
+      backend: target.backend,
+      authType: authConfig.type,
+      nextAction: "run_caplets_auth_login",
+    });
+  }
+  assertAllowedAuthUrl(tokenEndpoint, "token endpoint", allowLoopbackHttp);
+  const clientId = authConfig.clientId ?? authConfig.clientMetadataUrl ?? bundle.clientId;
+  if (!clientId) {
+    throw new CapletsError("AUTH_REFRESH_FAILED", "OAuth clientId is required to refresh tokens", {
+      server: target.server,
+      backend: target.backend,
+      authType: authConfig.type,
+      nextAction: "run_caplets_auth_login",
+    });
+  }
+  const clientSecret = authConfig.clientSecret ?? bundle.clientSecret;
+  const params = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: bundle.refreshToken,
+    client_id: clientId,
+  });
+  if (clientSecret) {
+    params.set("client_secret", clientSecret);
+  }
+  let tokenResponse: Record<string, unknown>;
+  try {
+    tokenResponse = await fetchJson(
+      tokenEndpoint,
+      target.requestTimeoutMs,
+      {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+      },
+      allowLoopbackHttp,
+    );
+  } catch (error) {
+    if (error instanceof CapletsError) {
+      throw new CapletsError("AUTH_REFRESH_FAILED", `OAuth token refresh failed`, {
+        server: target.server,
+        backend: target.backend,
+        authType: authConfig.type,
+        nextAction: "run_caplets_auth_login",
+        cause: error.details,
+      });
+    }
+    throw error;
+  }
+  const idToken = asString(tokenResponse.id_token);
+  const idClaims = parseJwtPayload(idToken);
+  if (idToken) {
+    if (!metadata.issuer && !authConfig.issuer) {
+      metadata = await discoverAuthorizationServer(target, authConfig, allowLoopbackHttp);
+    }
+    validateOidcToken(authConfig, metadata, idToken, idClaims, clientId);
+  }
+  const refreshed = stripUndefined({
+    ...bundle,
+    server: target.server,
+    authType: authConfig.type,
+    accessToken: requireString(tokenResponse.access_token, "access_token"),
+    refreshToken: asString(tokenResponse.refresh_token) ?? bundle.refreshToken,
+    tokenType: asString(tokenResponse.token_type) ?? bundle.tokenType,
+    expiresAt: refreshedExpiresAt(tokenResponse.expires_in, bundle.expiresAt),
+    scope: asString(tokenResponse.scope) ?? bundle.scope ?? scopesFor(authConfig),
+    idToken: idToken ?? bundle.idToken,
+    issuer: asString(idClaims?.iss) ?? bundle.issuer ?? metadata.issuer ?? authConfig.issuer,
+    subject: asString(idClaims?.sub) ?? bundle.subject,
+    clientId,
+    clientSecret,
+    protectedResourceOrigin: protectedResourceOrigin(target, authConfig),
+  });
+  writeTokenBundle(refreshed, authDir);
+  return refreshed;
+}
+
+function refreshedExpiresAt(expiresIn: unknown, fallback?: string): string | undefined {
+  if (typeof expiresIn === "number") {
+    return new Date(Date.now() + expiresIn * 1000).toISOString();
+  }
+  if (fallback && Date.parse(fallback) > Date.now()) {
+    return fallback;
+  }
+  return undefined;
+}
+
 async function fetchOptionalJson(
   url: string,
   timeoutMs?: number,
diff --git a/packages/core/src/graphql.ts b/packages/core/src/graphql.ts
index e2fe6f65..73121c79 100644
--- a/packages/core/src/graphql.ts
+++ b/packages/core/src/graphql.ts
@@ -138,7 +138,7 @@ export class GraphQLManager {
       const headers = new Headers({
         "content-type": "application/json",
         ...staticHeaders(endpoint),
-        ...genericOAuthHeaders(
+        ...(await genericOAuthHeaders(
           {
             server: endpoint.server,
             backend: "graphql",
@@ -147,7 +147,7 @@ export class GraphQLManager {
             requestTimeoutMs: endpoint.requestTimeoutMs,
           },
           this.options.authDir,
-        ),
+        )),
       });
       const response = await fetch(endpoint.endpointUrl, {
         method: GRAPHQL_METHOD,
@@ -623,7 +623,7 @@ async function postGraphQl(
       headers: {
         "content-type": "application/json",
         ...staticHeaders(endpoint),
-        ...genericOAuthHeaders(
+        ...(await genericOAuthHeaders(
           {
             server: endpoint.server,
             backend: "graphql",
@@ -632,7 +632,7 @@ async function postGraphQl(
             requestTimeoutMs: endpoint.requestTimeoutMs,
           },
           authDir,
-        ),
+        )),
       },
       body: JSON.stringify(payload),
     });
@@ -660,7 +660,7 @@ async function fetchGraphQlText(
       redirect: "manual",
       signal: controller.signal,
       headers: {
-        ...(sendAuth ? schemaAuthHeaders(endpoint, authDir) : {}),
+        ...(sendAuth ? await schemaAuthHeaders(endpoint, authDir) : {}),
       },
     });
   } catch (error) {
@@ -685,13 +685,13 @@ async function fetchGraphQlText(
   return readGraphQlText(response);
 }
 
-function schemaAuthHeaders(
+async function schemaAuthHeaders(
   endpoint: GraphQlEndpointConfig,
   authDir?: string,
-): Record<string, string> {
+): Promise<Record<string, string>> {
   return {
     ...staticHeaders(endpoint),
-    ...genericOAuthHeaders(
+    ...(await genericOAuthHeaders(
       {
         server: endpoint.server,
         backend: "graphql",
@@ -700,7 +700,7 @@ function schemaAuthHeaders(
         requestTimeoutMs: endpoint.requestTimeoutMs,
       },
       authDir,
-    ),
+    )),
   };
 }
 
diff --git a/packages/core/src/http-actions.ts b/packages/core/src/http-actions.ts
index ece14434..854c8d86 100644
--- a/packages/core/src/http-actions.ts
+++ b/packages/core/src/http-actions.ts
@@ -40,7 +40,7 @@ export class HttpActionManager {
     try {
       const operations = operationsFor(api);
       validateBaseUrl(api);
-      authHeaders(api, this.options.authDir);
+      await authHeaders(api, this.options.authDir);
       for (const operation of operations) {
         validateAction(api, operation);
       }
@@ -78,7 +78,7 @@ export class HttpActionManager {
   ): Promise<CompatibilityCallToolResult> {
     const operation = getOperation(api, toolName);
     const startedAt = Date.now();
-    const request = buildRequest(api, operation, args, this.options.authDir);
+    const request = await buildRequest(api, operation, args, this.options.authDir);
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), api.requestTimeoutMs);
     try {
@@ -188,12 +188,12 @@ function getOperation(api: HttpApiConfig, toolName: string): HttpActionOperation
   return operation;
 }
 
-function buildRequest(
+async function buildRequest(
   api: HttpApiConfig,
   operation: HttpActionOperation,
   args: Record<string, unknown>,
   authDir?: string,
-): { url: URL; headers: Headers; body?: string } {
+): Promise<{ url: URL; headers: Headers; body?: string }> {
   validateBaseUrl(api);
   validateAction(api, operation);
   const url = buildActionUrl(api.baseUrl, substitutePath(operation.path, args, operation), {
@@ -206,7 +206,7 @@ function buildRequest(
     }
   }
   const headers = new Headers();
-  applyAuth(headers, api, authDir);
+  await applyAuth(headers, api, authDir);
   const resolvedHeaders = resolveMappingToRecord(operation.headers, args, "headers");
   for (const [key, value] of Object.entries(resolvedHeaders)) {
     if (value !== undefined && value !== null) {
@@ -342,13 +342,13 @@ function serializeHttpValue(
   }
 }
 
-function applyAuth(headers: Headers, api: HttpApiConfig, authDir?: string): void {
-  for (const [key, value] of Object.entries(authHeaders(api, authDir))) {
+async function applyAuth(headers: Headers, api: HttpApiConfig, authDir?: string): Promise<void> {
+  for (const [key, value] of Object.entries(await authHeaders(api, authDir))) {
     headers.set(key, value);
   }
 }
 
-function authHeaders(api: HttpApiConfig, authDir?: string): Record<string, string> {
+async function authHeaders(api: HttpApiConfig, authDir?: string): Promise<Record<string, string>> {
   switch (api.auth.type) {
     case "none":
       return {};
@@ -358,7 +358,7 @@ function authHeaders(api: HttpApiConfig, authDir?: string): Record<string, strin
       return api.auth.headers;
     case "oauth2":
     case "oidc":
-      return genericOAuthHeaders(
+      return await genericOAuthHeaders(
         {
           server: api.server,
           backend: "http",
diff --git a/packages/core/src/openapi.ts b/packages/core/src/openapi.ts
index aaba7385..86d828db 100644
--- a/packages/core/src/openapi.ts
+++ b/packages/core/src/openapi.ts
@@ -116,7 +116,7 @@ export class OpenApiManager {
     args: Record<string, unknown>,
   ): Promise<CompatibilityCallToolResult> {
     const operation = await this.getOperation(endpoint, toolName);
-    const request = buildRequest(endpoint, operation, args, this.options.authDir);
+    const request = await buildRequest(endpoint, operation, args, this.options.authDir);
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), endpoint.requestTimeoutMs);
     try {
@@ -313,7 +313,7 @@ async function loadOpenApiSource(
   const response = await fetchWithLimit(
     endpoint.specUrl,
     endpoint.requestTimeoutMs,
-    shouldSendSpecAuth(endpoint) ? authHeaders(endpoint, authDir) : {},
+    shouldSendSpecAuth(endpoint) ? await authHeaders(endpoint, authDir) : {},
   );
   return parseOpenApiSourceText(response);
 }
@@ -580,12 +580,12 @@ function rejectExternalRefs(value: unknown): void {
   }
 }
 
-function buildRequest(
+async function buildRequest(
   endpoint: OpenApiEndpointConfig,
   operation: OpenApiOperation,
   args: Record<string, unknown>,
   authDir?: string,
-): { url: URL; headers: Headers; body?: string } {
+): Promise<{ url: URL; headers: Headers; body?: string }> {
   const base = endpoint.baseUrl ?? operation.baseUrl;
   validateOperationBaseUrl(endpoint, base);
   const url = buildOperationUrl(
@@ -598,7 +598,7 @@ function buildRequest(
     }
   }
   const headers = new Headers();
-  applyAuth(headers, endpoint, authDir);
+  await applyAuth(headers, endpoint, authDir);
   const configuredHeaderNames = configuredAuthHeaderNames(endpoint);
   for (const [key, value] of Object.entries(operation.staticHeaders ?? {})) {
     if (!headers.has(key) && !configuredHeaderNames.has(key.toLowerCase())) {
@@ -676,8 +676,12 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
-function applyAuth(headers: Headers, endpoint: OpenApiEndpointConfig, authDir?: string): void {
-  for (const [key, value] of Object.entries(authHeaders(endpoint, authDir))) {
+async function applyAuth(
+  headers: Headers,
+  endpoint: OpenApiEndpointConfig,
+  authDir?: string,
+): Promise<void> {
+  for (const [key, value] of Object.entries(await authHeaders(endpoint, authDir))) {
     headers.set(key, value);
   }
 }
@@ -688,7 +692,10 @@ function configuredAuthHeaderNames(endpoint: OpenApiEndpointConfig): Set<string>
     : new Set<string>();
 }
 
-function authHeaders(endpoint: OpenApiEndpointConfig, authDir?: string): Record<string, string> {
+async function authHeaders(
+  endpoint: OpenApiEndpointConfig,
+  authDir?: string,
+): Promise<Record<string, string>> {
   switch (endpoint.auth.type) {
     case "none":
       return {};
@@ -698,7 +705,7 @@ function authHeaders(endpoint: OpenApiEndpointConfig, authDir?: string): Record<
       return endpoint.auth.headers;
     case "oauth2":
     case "oidc":
-      return genericOAuthHeaders(endpoint, authDir);
+      return await genericOAuthHeaders(endpoint, authDir);
   }
 }
 
diff --git a/packages/core/test/auth.test.ts b/packages/core/test/auth.test.ts
index 49e749b1..6f9558df 100644
--- a/packages/core/test/auth.test.ts
+++ b/packages/core/test/auth.test.ts
@@ -64,7 +64,7 @@ describe("auth helpers", () => {
     });
   });
 
-  it("requires stored OAuth tokens before remote operations", () => {
+  it("requires stored OAuth tokens before remote operations", async () => {
     const server = parseConfig({
       mcpServers: {
         remote: {
@@ -77,12 +77,12 @@ describe("auth helpers", () => {
       },
     }).mcpServers.remote!;
 
-    expect(() => oauthHeaders(server, "/tmp/does-not-exist")).toThrow(
-      expect.objectContaining({ code: "AUTH_REQUIRED" }),
-    );
+    await expect(oauthHeaders(server, "/tmp/does-not-exist")).rejects.toMatchObject({
+      code: "AUTH_REQUIRED",
+    });
   });
 
-  it("uses stored OIDC tokens for remote MCP headers", () => {
+  it("uses stored OIDC tokens for remote MCP headers", async () => {
     const dir = mkdtempSync(join(tmpdir(), "caplets-auth-"));
     try {
       const server = parseConfig({
@@ -98,12 +98,90 @@ describe("auth helpers", () => {
       }).mcpServers.remote!;
       writeTokenBundle({ server: "remote", accessToken: "secret-token" }, dir);
 
-      expect(oauthHeaders(server, dir)).toEqual({ authorization: "Bearer secret-token" });
+      await expect(oauthHeaders(server, dir)).resolves.toEqual({
+        authorization: "Bearer secret-token",
+      });
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
 
+  it("refreshes expired remote MCP OAuth tokens before building headers", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "caplets-auth-mcp-refresh-"));
+    const requests: Array<{ url?: string; body: string }> = [];
+    const server = createServer((request: IncomingMessage, response: ServerResponse) => {
+      let body = "";
+      request.setEncoding("utf8");
+      request.on("data", (chunk) => {
+        body += chunk;
+      });
+      request.on("end", () => {
+        requests.push({ ...(request.url ? { url: request.url } : {}), body });
+        response.setHeader("content-type", "application/json");
+        response.end(
+          JSON.stringify({
+            access_token: "new-mcp-access-token",
+            refresh_token: "new-mcp-refresh-token",
+            token_type: "Bearer",
+            expires_in: 3600,
+          }),
+        );
+      });
+    });
+    try {
+      await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        throw new Error("test server did not bind");
+      }
+      const baseUrl = `http://127.0.0.1:${address.port}`;
+      const config = parseConfig({
+        mcpServers: {
+          remote: {
+            name: "Remote",
+            description: "A useful remote OAuth server.",
+            transport: "http",
+            url: `${baseUrl}/mcp`,
+            auth: {
+              type: "oauth2",
+              clientId: "client",
+              tokenUrl: `${baseUrl}/token`,
+            },
+          },
+        },
+      });
+      writeTokenBundle(
+        {
+          server: "remote",
+          accessToken: "old-mcp-access-token",
+          refreshToken: "old-mcp-refresh-token",
+          tokenType: "Bearer",
+          expiresAt: "2000-01-01T00:00:00.000Z",
+        },
+        dir,
+      );
+
+      const headers = await oauthHeaders(config.mcpServers.remote!, dir);
+
+      expect(headers).toEqual({ authorization: "Bearer new-mcp-access-token" });
+      expect(requests).toHaveLength(1);
+      expect(requests[0]?.url).toBe("/token");
+      expect(new URLSearchParams(requests[0]?.body).get("grant_type")).toBe("refresh_token");
+      expect(new URLSearchParams(requests[0]?.body).get("refresh_token")).toBe(
+        "old-mcp-refresh-token",
+      );
+      expect(readTokenBundle("remote", dir)).toMatchObject({
+        accessToken: "new-mcp-access-token",
+        refreshToken: "new-mcp-refresh-token",
+        clientId: "client",
+        protectedResourceOrigin: baseUrl,
+      });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   it("ignores corrupt token bundle files", () => {
     const dir = mkdtempSync(join(tmpdir(), "caplets-auth-"));
     try {
@@ -145,7 +223,7 @@ describe("auth helpers", () => {
     expect(authStorePath("remote", root)).toBe(join(root, "remote.json"));
   });
 
-  it("builds generic OAuth headers for OpenAPI and GraphQL auth targets", () => {
+  it("builds generic OAuth headers for OpenAPI and GraphQL auth targets", async () => {
     const dir = mkdtempSync(join(tmpdir(), "caplets-auth-"));
     try {
       writeTokenBundle(
@@ -163,7 +241,7 @@ describe("auth helpers", () => {
       );
 
       expect(
-        genericOAuthHeaders(
+        await genericOAuthHeaders(
           {
             server: "users",
             backend: "openapi",
@@ -177,6 +255,196 @@ describe("auth helpers", () => {
     }
   });
 
+  it("refreshes expired generic OAuth tokens before building headers", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "caplets-auth-refresh-"));
+    const requests: Array<{ url?: string; body: string }> = [];
+    const server = createServer((request: IncomingMessage, response: ServerResponse) => {
+      let body = "";
+      request.setEncoding("utf8");
+      request.on("data", (chunk) => {
+        body += chunk;
+      });
+      request.on("end", () => {
+        requests.push({ ...(request.url ? { url: request.url } : {}), body });
+        response.setHeader("content-type", "application/json");
+        response.end(
+          JSON.stringify({
+            access_token: "new-access-token",
+            refresh_token: "rotated-refresh-token",
+            token_type: "Bearer",
+            expires_in: 3600,
+            scope: "api:read",
+          }),
+        );
+      });
+    });
+    try {
+      await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        throw new Error("test server did not bind");
+      }
+      const baseUrl = `http://127.0.0.1:${address.port}`;
+      writeTokenBundle(
+        {
+          server: "users",
+          authType: "oauth2",
+          accessToken: "old-access-token",
+          refreshToken: "old-refresh-token",
+          tokenType: "Bearer",
+          expiresAt: "2000-01-01T00:00:00.000Z",
+          scope: "api:read",
+          clientId: "client",
+          protectedResourceOrigin: baseUrl,
+        },
+        dir,
+      );
+
+      const headers = await genericOAuthHeaders(
+        {
+          server: "users",
+          backend: "http",
+          baseUrl,
+          auth: {
+            type: "oauth2",
+            clientId: "client",
+            tokenUrl: `${baseUrl}/token`,
+          },
+        },
+        dir,
+      );
+
+      expect(headers).toEqual({ authorization: "Bearer new-access-token" });
+      expect(requests).toHaveLength(1);
+      expect(requests[0]?.url).toBe("/token");
+      expect(new URLSearchParams(requests[0]?.body).get("grant_type")).toBe("refresh_token");
+      expect(new URLSearchParams(requests[0]?.body).get("refresh_token")).toBe("old-refresh-token");
+      expect(new URLSearchParams(requests[0]?.body).get("client_id")).toBe("client");
+      expect(readTokenBundle("users", dir)).toMatchObject({
+        accessToken: "new-access-token",
+        refreshToken: "rotated-refresh-token",
+        tokenType: "Bearer",
+        scope: "api:read",
+        clientId: "client",
+        protectedResourceOrigin: baseUrl,
+      });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects generic OAuth headers when refresh returns an expired token", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "caplets-auth-refresh-expired-"));
+    const server = createServer((_request: IncomingMessage, response: ServerResponse) => {
+      response.setHeader("content-type", "application/json");
+      response.end(
+        JSON.stringify({
+          access_token: "already-expired-token",
+          token_type: "Bearer",
+          expires_in: -1,
+        }),
+      );
+    });
+    try {
+      await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        throw new Error("test server did not bind");
+      }
+      const baseUrl = `http://127.0.0.1:${address.port}`;
+      writeTokenBundle(
+        {
+          server: "users",
+          authType: "oauth2",
+          accessToken: "old-access-token",
+          refreshToken: "old-refresh-token",
+          expiresAt: "2000-01-01T00:00:00.000Z",
+          clientId: "client",
+          protectedResourceOrigin: baseUrl,
+        },
+        dir,
+      );
+
+      await expect(
+        genericOAuthHeaders(
+          {
+            server: "users",
+            backend: "http",
+            baseUrl,
+            auth: {
+              type: "oauth2",
+              clientId: "client",
+              tokenUrl: `${baseUrl}/token`,
+            },
+          },
+          dir,
+        ),
+      ).rejects.toMatchObject({ code: "AUTH_REFRESH_FAILED" });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("preserves usable generic OAuth expiry metadata when refresh omits expires_in", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "caplets-auth-refresh-expiry-"));
+    const server = createServer((_request: IncomingMessage, response: ServerResponse) => {
+      response.setHeader("content-type", "application/json");
+      response.end(
+        JSON.stringify({
+          access_token: "new-access-token",
+          token_type: "Bearer",
+        }),
+      );
+    });
+    try {
+      await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        throw new Error("test server did not bind");
+      }
+      const baseUrl = `http://127.0.0.1:${address.port}`;
+      const expiresAt = "2999-01-01T00:00:00.000Z";
+      writeTokenBundle(
+        {
+          server: "users",
+          authType: "oauth2",
+          accessToken: "",
+          refreshToken: "old-refresh-token",
+          expiresAt,
+          clientId: "client",
+          protectedResourceOrigin: baseUrl,
+        },
+        dir,
+      );
+
+      await expect(
+        genericOAuthHeaders(
+          {
+            server: "users",
+            backend: "http",
+            baseUrl,
+            auth: {
+              type: "oauth2",
+              clientId: "client",
+              tokenUrl: `${baseUrl}/token`,
+            },
+          },
+          dir,
+        ),
+      ).resolves.toEqual({ authorization: "Bearer new-access-token" });
+
+      expect(readTokenBundle("users", dir)).toMatchObject({
+        accessToken: "new-access-token",
+        expiresAt,
+      });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   it("includes HTTP APIs in OAuth auth target listing", () => {
     const dir = mkdtempSync(join(tmpdir(), "caplets-auth-config-"));
     try {
@@ -657,7 +925,7 @@ describe("auth helpers", () => {
       expect(requests.find((request) => request.url === "/token")?.body).toContain(
         "client_id=dynamic-client",
       );
-      const bundle = genericOAuthHeaders(
+      const bundle = await genericOAuthHeaders(
         { server: "users", backend: "openapi", auth: { type: "oidc" } },
         dir,
       );
@@ -759,7 +1027,7 @@ describe("auth helpers", () => {
     }
   });
 
-  it("matches generic OAuth token bundles against configured client metadata URLs", () => {
+  it("matches generic OAuth token bundles against configured client metadata URLs", async () => {
     const dir = mkdtempSync(join(tmpdir(), "caplets-auth-"));
     try {
       writeTokenBundle(
@@ -774,7 +1042,7 @@ describe("auth helpers", () => {
       );
 
       expect(
-        genericOAuthHeaders(
+        await genericOAuthHeaders(
           {
             server: "users",
             backend: "openapi",
@@ -788,7 +1056,7 @@ describe("auth helpers", () => {
         ),
       ).toEqual({ authorization: "Bearer metadata-url-token" });
 
-      expect(() =>
+      await expect(
         genericOAuthHeaders(
           {
             server: "users",
@@ -801,7 +1069,7 @@ describe("auth helpers", () => {
           },
           dir,
         ),
-      ).toThrow(expect.objectContaining({ code: "AUTH_REQUIRED" }));
+      ).rejects.toMatchObject({ code: "AUTH_REQUIRED" });
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
diff --git a/packages/opencode/README.md b/packages/opencode/README.md
index 11e07e0b..a7fad2d4 100644
--- a/packages/opencode/README.md
+++ b/packages/opencode/README.md
@@ -2,7 +2,7 @@
 
 Native OpenCode plugin for Caplets.
 
-This package exposes configured Caplets as native OpenCode tools named `caplets__<id>` plus `caplets__code_mode` for Caplets Code Mode. It does not start the Caplets MCP server and does not edit `opencode.json`; prompt guidance is injected through OpenCode plugin hooks.
+This package exposes `caplets__code_mode` for Caplets Code Mode. Progressive exposure adds native OpenCode tools named `caplets__<id>`, and direct exposure adds operation-level tools named `caplets__<id>__<operation>`. It does not start the Caplets MCP server and does not edit `opencode.json`; prompt guidance is injected through OpenCode plugin hooks.
 
 MCP-backed Caplets advertise resource, prompt, template, and completion operations in their generated schema; OpenAPI, GraphQL, HTTP, CLI, and Caplet-set backends remain tool/action-only.
 
diff --git a/packages/pi/README.md b/packages/pi/README.md
index 31812cb4..77dee480 100644
--- a/packages/pi/README.md
+++ b/packages/pi/README.md
@@ -2,7 +2,7 @@
 
 Native Pi extension for Caplets.
 
-This package exposes configured Caplets as native Pi tools named `caplets__<id>`. It does not start the Caplets MCP server. Pi prompt guidance is provided through `promptSnippet` and `promptGuidelines`.
+This package exposes `caplets__code_mode` for Caplets Code Mode. Progressive exposure adds native Pi tools named `caplets__<id>`, and direct exposure adds operation-level tools named `caplets__<id>__<operation>`. It does not start the Caplets MCP server. Pi prompt guidance is provided through `promptSnippet` and `promptGuidelines`.
 
 MCP-backed Caplets advertise resource, prompt, template, and completion operations in their generated schema; OpenAPI, GraphQL, HTTP, CLI, and Caplet-set backends remain tool/action-only.