caplets 0.17.9 → 0.18.0

package/README.md

@@ -1,5 +1,5 @@
 <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>
 
@@ -12,7 +12,7 @@
     <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>
@@ -47,7 +47,7 @@ In the deterministic benchmark, 106 flat tools became 3 top-level capabilities w
 
 ## Quick Start
 
-Caplets requires Node.js 22 or newer.
+Caplets requires Node.js 24 or newer.
 
 ```sh
 npm install -g caplets
@@ -134,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: