caplets 0.17.8 → 0.18.0

package/README.md

@@ -1,18 +1,22 @@
 <div align="center">
-  <img src="plugins/caplets/assets/icon.png" alt="Caplets logo" width="140" height="140" />
+  <img src="docs/assets/caplets-icon.png" alt="Caplets logo" width="140" height="140" />
 
   <h1>Caplets</h1>
 
   <p>
-    <strong>Capability cards for coding agents.</strong><br />
-    Wrap sprawling tool stacks behind focused, progressive-disclosure interfaces.
+    <strong>Give your agent capabilities, not tools.</strong><br />
+    Turn MCP servers, APIs, and commands into focused agent capabilities.
   </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 22+" src="https://img.shields.io/badge/node-%3E%3D22-F6E8C8?style=flat-square&labelColor=1F2018" />
+    <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>
@@ -22,38 +26,33 @@
 
 ---
 
-Caplets turns sprawling tool setups into focused capability cards for coding agents.
-Connect MCP servers, OpenAPI specs, GraphQL endpoints, HTTP actions, and curated CLI
-commands without flooding the model with every downstream operation up front.
+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.
 
-Instead of exposing a flat wall of tools, Caplets shows one top-level tool per capability.
-The agent chooses a domain first, then uses scoped operations like `search_tools`,
-`get_tool`, and `call_tool` only when it needs more detail.
+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`, `get_tool`, and `call_tool` only when it needs more detail.
 
-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.
+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.
 
-## Quick Start
+## Try the aha moment
 
-Caplets requires Node.js 22 or newer.
+Install Caplets, add Context7, and watch your agent see one capability before it searches downstream tools.
 
 ```sh
-pnpm add -g caplets
+npm install -g caplets
 caplets init
+caplets add mcp context7 --command npx --arg -y --arg @upstash/context7-mcp
+caplets serve
 ```
 
-Add a capability from an existing system:
+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`, `get_tool`, and `call_tool` only when needed.
 
-```sh
-# Wrap an MCP server
-caplets add mcp docs --command npx --arg -y --arg @upstash/context7-mcp
+## Quick Start
 
-# Convert useful repository commands into curated tools
-caplets add cli repo-tools --repo . --include git,gh,package
+Caplets requires Node.js 24 or newer.
 
-# Install ready-made Caplets from a repository
-caplets install spiritledsoftware/caplets github linear context7
+```sh
+npm install -g caplets
+caplets init
+caplets serve
 ```
 
 Connect Caplets to any MCP client:
@@ -69,13 +68,25 @@ 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.
+Ask your agent to use Caplets. It will see a compact capability list first, then inspect only the backend it needs.
 
-You can also invoke configured Caplets directly from the CLI for agent-friendly scripts and smoke tests:
+Add capabilities from existing systems when you are ready to give agents a focused tool surface:
 
 ```sh
-caplets get-caplet context7
+# 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 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:
+
+```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"}'
@@ -123,33 +134,85 @@ Completions include command names, options, common enum values, configured Caple
 
 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 Plugins
+## 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` as a stdio MCP server                                                           | Universal progressive-disclosure gateway                           |
-| Claude Code    | `claude plugin marketplace add spiritledsoftware/caplets && claude plugin install caplets@caplets`  | Claude Code plugin metadata, MCP config, and shared skill guidance |
-| Codex          | `codex plugin marketplace add spiritledsoftware/caplets`, then install `caplets` from Codex plugins | Codex plugin metadata, MCP config, and shared skill guidance       |
-| 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     |
+| Agent          | Install                                                        | What It Provides                                               |
+| -------------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
+| Any MCP client | Add `caplets serve` or `caplets attach` manually in MCP config | Universal progressive-disclosure gateway                       |
+| Claude Code    | Add `caplets serve` or `caplets attach` manually in MCP config | Local or remote/Cloud progressive-disclosure gateway           |
+| Codex          | Add `caplets serve` or `caplets attach` manually in MCP config | Local or remote/Cloud progressive-disclosure 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 and Claude Code plugins are plugin-native but MCP-backed. The installable plugin
-lives under `plugins/caplets/`, with agent-specific manifests in `.codex-plugin/` and
-`.claude-plugin/`, a shared `skills/` directory, and shared `mcp.json` config. The
-repo-level `.agents/plugins/marketplace.json` and `.claude-plugin/marketplace.json`
-files only advertise that installable plugin root.
+Manual local MCP config:
 
-The Claude Code and Codex commands install from this GitHub repository through each agent's
-plugin marketplace flow; users do not need to clone the repository manually. Plugin MCP
-configs run `caplets serve` directly, so install the Caplets CLI globally first.
+```json
+{
+  "mcpServers": {
+    "caplets": {
+      "command": "caplets",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Manual remote or Cloud MCP config:
+
+```json
+{
+  "mcpServers": {
+    "caplets": {
+      "command": "caplets",
+      "args": ["attach"]
+    }
+  }
+}
+```
+
+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
+```
+
+For a self-hosted remote:
+
+```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:
 
@@ -244,12 +307,16 @@ version, and customize them with the project.
 
 ## Why It Matters
 
-Large MCP setups can make agents harder to steer. If every downstream server exposes
-every tool up front, the model starts with a noisy flat list, duplicate tool names, and
-a larger context surface before it knows which capability 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 tool wall into progressive disclosure: one capability card first,
-then scoped discovery only after the agent chooses the relevant domain.
+Caplets turns that flat wall into a staged path:
+
+1. **Choose** a capability, such as `GitHub`.
+2. **Inspect** matching operations with `search_tools` or `list_tools`.
+3. **Resolve** the exact schema with `get_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
 
@@ -290,18 +357,30 @@ CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:opencode -- --model openai/gpt-5.5-fast
 
 ## Design Model
 
-Caplets combines two ideas that work well separately but leave a gap together: agent
-skills and MCP servers.
+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.
 
-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.
+## Trust Before Invocation
 
-Caplets borrows the skill-shaped discovery model and applies it to MCP. Each downstream
-server becomes a skill-like capability card first; its actual MCP tools stay hidden until
-the agent chooses that server and asks to search, list, inspect, or call them.
+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
 
@@ -464,8 +543,11 @@ tags:
   - code
   - review
 mcpServer:
-  command: npx
-  args: ["-y", "github-mcp-server"]
+  transport: http
+  url: https://api.githubcopilot.com/mcp
+  auth:
+    type: bearer
+    token: $env:GH_TOKEN
 ---
 
 # GitHub
@@ -559,7 +641,7 @@ normal Markdown links from `CAPLET.md`.
 
 This repository includes polished working examples under [`caplets/`](caplets/):
 
-- `github`: GitHub's official MCP server container, using `GITHUB_PERSONAL_ACCESS_TOKEN`.
+- `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.
@@ -857,7 +939,7 @@ 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: `get_caplet`, `check_backend`,
+as one downstream tool and supports the full Caplets operation set: `inspect`, `check_backend`,
 `list_tools`, `search_tools`, `get_tool`, and `call_tool`.
 
 ```json
@@ -997,6 +1079,34 @@ top-level MCP tool list without restarting Caplets. When an MCP-backed Caplet ch
 removed, Caplets closes only that affected downstream connection; unrelated Caplets and
 their downstream connections keep running.
 
+## 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 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 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`.
+
 ## Additional Native Integrations
 
 OpenCode and Pi support true native tool registration. Those integrations expose one
@@ -1062,7 +1172,7 @@ Call one exact downstream tool:
 
 Available operations:
 
-- `get_caplet`: return the configured capability card without starting the downstream server.
+- `inspect`: return the configured capability card without starting the downstream server.
 - `check_backend`: verify the selected backend, whether MCP, OpenAPI, GraphQL, HTTP, CLI, or nested Caplets.
 - `list_tools`: return compact downstream tool metadata.
 - `search_tools`: search downstream tool names and descriptions within this Caplet.
@@ -1072,7 +1182,7 @@ Available operations:
 Requests are strict: operation-specific extra fields are rejected, and `call_tool` requires
 `arguments` to be a JSON object.
 
-Discovery operations (`get_caplet`, `check_backend`, `list_tools`, `search_tools`, and
+Discovery operations (`inspect`, `check_backend`, `list_tools`, `search_tools`, and
 `get_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