@ken-jo/agent-connector 0.4.95 → 0.4.97

package/README.md

@@ -1,611 +1,617 @@
-<p align="center">
-  <img src="site/public/mascot.png" alt="agent-connector mascot — a pixel-art lobster worker in a tool belt" width="160" />
-</p>
-
-# agent-connector
-
-### Deploy one MCP to every agent CLI.
-
-Write your server + hooks once with `defineConnector()`, then `install` it into
-the native config — or `package` it as a real plugin — across every detected agent CLI
-(Claude Code, Codex, Cursor, Copilot, Gemini, OpenCode, Warp, Zed…).
-
-[![npm](https://img.shields.io/npm/v/@ken-jo/agent-connector?color=cb3837&logo=npm)](https://www.npmjs.com/package/@ken-jo/agent-connector)
-[![license](https://img.shields.io/npm/l/@ken-jo/agent-connector?color=22c55e)](LICENSE)
-[![platform coverage](https://img.shields.io/badge/platform%20coverage-see%20%2Fcoverage-2563eb)](https://agent-connector.ai/coverage)
-![surfaces](https://img.shields.io/badge/surfaces-MCP%20%7C%20hooks%20%7C%20commands%20%7C%20tools%20%7C%20memory%20%7C%20status%20line-2563eb)
-![hook paradigms](https://img.shields.io/badge/hook%20paradigms-3-2563eb)
-[![install verified](https://img.shields.io/badge/install%20verified-registry%20harness-22c55e)](https://agent-connector.ai/coverage)
-[![headless runtime](https://img.shields.io/badge/headless%20runtime-verified%20matrix-22c55e)](https://agent-connector.ai/coverage)
-![marketplace](https://img.shields.io/badge/package-10%20marketplace%20formats-2563eb)
-![tests](https://img.shields.io/badge/tests-passing-22c55e)
-
-**Two audiences:** connector developers start at [Quick start](#quick-start);
-if you already run an agent CLI and just want token totals, jump straight to
-[`usage`](#token-telemetry--usage).
-
-- [Quick start](#quick-start) — depend on the SDK, declare a connector, install it
-- [Ship it](#ship-it-direct-install-or-a-marketplace-plugin) — direct install or a marketplace plugin
-- [What you define once](#what-you-define-once) — server, hooks, and the other surfaces
-- [How it works](#how-it-works) — single home binary, per-project data, hook paradigms
-- [CLI](#cli) — every command at a glance
-- [Token telemetry & usage](#token-telemetry--usage) — per-tool telemetry vs. connector-free `usage`
-- [Publish to the MCP ecosystem](#publish-to-the-mcp-ecosystem) — emit the official MCP standard artifacts
-- [Verification](#verification) — how the platform coverage contract is proven
-
-<p align="center">
-  <a href="examples/showcase-demo/">
-    <img src="examples/showcase-demo/demo.gif" width="820"
-         alt="agent-connector showcase: define a connector once, ship it as your own branded CLI, install it via each host's native marketplace, and drive every CLI with one command." />
-  </a>
-</p>
-
-<p align="center"><sub>
-  Define once → ship it as your own branded CLI → users install via their host's native marketplace → one command drives every CLI.
-  <a href="examples/showcase-demo/">Regenerate this demo.</a>
-</sub></p>
-
-## Quick start
-
-agent-connector is an **SDK connector developers depend on**. Add it to the
-package that holds your connector, declare the connector once, then ship a
-branded MCP package/bin such as `npx @acme/acme-db-mcp install` — it deploys to
-every detected agent CLI in that host's own native config. Installing
-`@ken-jo/agent-connector` globally is not the branded MCP lifecycle path; reserve
-the global CLI guidance for connector-free token usage reports. Framework
-artifact tooling stays developer-facing and normally runs through
-`npx @ken-jo/agent-connector ... --connector`. The linear path is:
-**get a server → declare it → install through your branded package**.
-
-**0. You need an MCP server file first.** The config below points at
-`./my-mcp-server.mjs`, so that file must exist before you install. Don't have an
-MCP server yet? Copy
-[`examples/acme-db/acme-db-mcp-server.mjs`](examples/acme-db/acme-db-mcp-server.mjs)
-(a self-contained ~35-line stub) as `./my-mcp-server.mjs`, or follow the
-[official MCP SDK quickstart](https://modelcontextprotocol.io/quickstart/server).
-
-```bash
-# 1. add agent-connector as a DEPENDENCY of your connector package
-npm install @ken-jo/agent-connector
-```
-
-```jsonc
-// 2. package.json — this is the user-facing package identity
-{
-  "name": "@acme/acme-db-mcp",
-  "mcpName": "io.github.acme/acme-db",
-  "bin": { "acme-db": "./bin.mjs" },
-  "dependencies": { "@ken-jo/agent-connector": "^0.4.94" }
-}
-```
-
-```js
-// 3. agent-connector.config.mjs — declare your server + hooks once
-import { fileURLToPath } from "node:url";
-import { defineConnector } from "@ken-jo/agent-connector/sdk";
-
-const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));
-
-export default defineConnector({
-  // package.json / npm metadata is the source of truth. The host alias/runtime
-  // id and connector version are derived from name/mcpName/bin/version unless
-  // you need a legacy or multi-instance alias. Host-native ids are generated
-  // during install, so do not copy them back into defineConnector({ id }).
-  server: {
-    transport: "stdio",
-    command: "node",
-    args: [serverPath],
-  },
-  // hooks, telemetry, and more surfaces — see "What you define once" below
-});
-```
-
-The wiring contract is:
-
-1. `package.json` defines the public product identity (`name`, `mcpName`, `bin`,
-   `version`).
-2. `bin.mjs` calls `createConnectorCli({ packageJson, connector })` so every
-   install/doctor/upgrade/uninstall command runs under the developer's brand.
-3. `agent-connector.config.*` uses `defineConnector({ server, ...surfaces })` to
-   describe the real MCP launch shape or remote endpoint.
-4. `install` renders that single declaration into each detected host's native
-   MCP config. For stdio processes, the host points at the stable
-   agent-connector home binary, which launches the real command and can measure
-   per-tool traffic. For remote HTTP servers, the host receives the URL where
-   supported; there is no stdio process to wrap.
-
-### Command boundary
-
-Keep the two command layers separate:
-
-| Layer | Who runs it | Examples | Purpose |
-| --- | --- | --- | --- |
-| Branded MCP lifecycle | Users of your MCP package | `npx @acme/acme-db-mcp install`, `acme-db doctor --probe`, `acme-db upgrade`, `acme-db uninstall`, `acme-db telemetry report --by tool` | Install, verify, update, remove, and inspect telemetry for **your MCP**. |
-| Framework tooling | MCP package developers | `npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs` | Emit host plugin bundles and MCP distribution artifacts from a connector config. |
-| Connector-free user telemetry | Agent-CLI users with no MCP package | `npx @ken-jo/agent-connector usage report --by platform` | Read host CLI logs read-only for whole-conversation token totals. |
-
-If a command operates the MCP after it is authored, prefer the branded package/bin.
-If a command builds framework distribution artifacts, use the framework CLI.
-
-### MCP server launch examples
-
-Pick the `server` shape that matches the MCP you are building. The wrapper
-package identity still comes from `package.json`; these examples only describe
-how to start or connect to the actual MCP server.
-
-| Shape | Use when | Minimal launch |
-| --- | --- | --- |
-| Package-runner MCP | The MCP is published as a package. | `npx -y @acme/acme-db-mcp` |
-| Local server-process MCP | The MCP server ships inside your package. | `node ./my-mcp-server.mjs` |
-| Python MCP | The MCP server is Python and should resolve runtime deps at launch. | `uv run --with mcp ./my_mcp_server.py` |
-| CLI-based MCP | An existing executable exposes an MCP serving mode. | `local-tools mcp serve` |
-| Remote server MCP | The MCP is hosted behind an HTTP endpoint. | `https://mcp.example.com/mcp` |
-
-Each snippet below is the `server` field for `defineConnector({ ... })`; only
-the local server-process example needs the `serverPath` helper shown inline.
-
-**Package-runner MCP** — a published package that should be launched with `npx`:
-
-```js
-server: {
-  transport: "stdio",
-  command: "npx",
-  args: ["-y", "@acme/acme-db-mcp"],
-}
-```
-
-**Local server-process MCP** — a bundled server file or binary:
-
-```js
-import { fileURLToPath } from "node:url";
-
-const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));
-
-server: {
-  transport: "stdio",
-  command: "node",
-  args: [serverPath],
-}
-```
-
-**Python MCP** — usually run through `uv` so dependencies are resolved with the
-server:
-
-```js
-server: {
-  transport: "stdio",
-  command: "uv",
-  args: ["run", "--with", "mcp", "./my_mcp_server.py"],
-}
-```
-
-Use direct `python ./my_mcp_server.py` only when the runtime environment is
-already managed by your package or deployment wrapper.
-
-**CLI-based MCP** — an existing executable exposes an MCP mode:
-
-```js
-server: {
-  transport: "stdio",
-  command: "local-tools",
-  args: ["mcp", "serve"],
-}
-```
-
-**Remote server MCP** — a hosted MCP endpoint:
-
-```js
-server: {
-  transport: "http",
-  url: "https://mcp.example.com/mcp",
-}
-```
-
-```bash
+<p align="center">
+  <img src="site/public/mascot.png" alt="agent-connector mascot — a pixel-art lobster worker in a tool belt" width="160" />
+</p>
+
+# agent-connector
+
+### Deploy one MCP to every agent CLI.
+
+Write your server + hooks once with `defineConnector()`, then `install` it into
+the native config — or `package` it as a real plugin — across every detected agent CLI
+(Claude Code, Codex, Cursor, Copilot, Gemini, OpenCode, Warp, Zed…).
+
+[![npm](https://img.shields.io/npm/v/@ken-jo/agent-connector?color=cb3837&logo=npm)](https://www.npmjs.com/package/@ken-jo/agent-connector)
+[![license](https://img.shields.io/npm/l/@ken-jo/agent-connector?color=22c55e)](LICENSE)
+[![platform coverage](https://img.shields.io/badge/platform%20coverage-see%20%2Fcoverage-2563eb)](https://agent-connector.ai/coverage)
+![surfaces](https://img.shields.io/badge/surfaces-MCP%20%7C%20hooks%20%7C%20commands%20%7C%20tools%20%7C%20memory%20%7C%20status%20line-2563eb)
+![hook paradigms](https://img.shields.io/badge/hook%20paradigms-3-2563eb)
+[![install verified](https://img.shields.io/badge/install%20verified-registry%20harness-22c55e)](https://agent-connector.ai/coverage)
+[![headless runtime](https://img.shields.io/badge/headless%20runtime-verified%20matrix-22c55e)](https://agent-connector.ai/coverage)
+![marketplace](https://img.shields.io/badge/package-10%20marketplace%20formats-2563eb)
+![tests](https://img.shields.io/badge/tests-passing-22c55e)
+
+**Two audiences:** connector developers start at [Quick start](#quick-start);
+if you already run an agent CLI and just want token totals, jump straight to
+[`usage`](#token-telemetry--usage).
+
+- [Quick start](#quick-start) — depend on the SDK, declare a connector, install it
+- [Ship it](#ship-it-direct-install-or-a-marketplace-plugin) — direct install or a marketplace plugin
+- [What you define once](#what-you-define-once) — server, hooks, and the other surfaces
+- [How it works](#how-it-works) — single home binary, per-project data, hook paradigms
+- [CLI](#cli) — every command at a glance
+- [Token telemetry & usage](#token-telemetry--usage) — per-tool telemetry vs. connector-free `usage`
+- [Publish to the MCP ecosystem](#publish-to-the-mcp-ecosystem) — emit the official MCP standard artifacts
+- [Verification](#verification) — how the platform coverage contract is proven
+
+<p align="center">
+  <a href="examples/showcase-demo/">
+    <img src="examples/showcase-demo/demo.gif" width="820"
+         alt="agent-connector showcase: define a connector once, ship it as your own branded CLI, install it via each host's native marketplace, and drive every CLI with one command." />
+  </a>
+</p>
+
+<p align="center"><sub>
+  Define once → ship it as your own branded CLI → users install via their host's native marketplace → one command drives every CLI.
+  <a href="examples/showcase-demo/">Regenerate this demo.</a>
+</sub></p>
+
+## Quick start
+
+agent-connector is an **SDK connector developers depend on**. Add it to the
+package that holds your connector, declare the connector once, then ship a
+branded MCP package/bin such as `npx @acme/acme-db-mcp install` — it deploys to
+every detected agent CLI in that host's own native config. Installing
+`@ken-jo/agent-connector` globally is not the branded MCP lifecycle path; reserve
+the global CLI guidance for connector-free token usage reports. Framework
+artifact tooling stays developer-facing and normally runs through
+`npx @ken-jo/agent-connector ... --connector`. The linear path is:
+**get a server → declare it → install through your branded package**.
+
+**0. You need an MCP server file first.** The config below points at
+`./my-mcp-server.mjs`, so that file must exist before you install. Don't have an
+MCP server yet? Copy
+[`examples/acme-db/acme-db-mcp-server.mjs`](examples/acme-db/acme-db-mcp-server.mjs)
+(a self-contained ~35-line stub) as `./my-mcp-server.mjs`, or follow the
+[official MCP SDK quickstart](https://modelcontextprotocol.io/quickstart/server).
+
+```bash
+# 1. add agent-connector as a DEPENDENCY of your connector package
+npm install @ken-jo/agent-connector
+```
+
+```jsonc
+// 2. package.json — this is the user-facing package identity
+{
+  "name": "@acme/acme-db-mcp",
+  "mcpName": "io.github.acme/acme-db",
+  "bin": { "acme-db": "./bin.mjs" },
+  "dependencies": { "@ken-jo/agent-connector": "^0.4.97" }
+}
+```
+
+```js
+// 3. agent-connector.config.mjs — declare your server + hooks once
+import { fileURLToPath } from "node:url";
+import { defineConnector } from "@ken-jo/agent-connector/sdk";
+
+const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));
+
+export default defineConnector({
+  // package.json / npm metadata is the source of truth. The host alias/runtime
+  // id and connector version are derived from name/mcpName/bin/version unless
+  // you need a legacy or multi-instance alias. Host-native ids are generated
+  // during install, so do not copy them back into defineConnector({ id }).
+  server: {
+    transport: "stdio",
+    command: "node",
+    args: [serverPath],
+  },
+  // hooks, telemetry, and more surfaces — see "What you define once" below
+});
+```
+
+The wiring contract is:
+
+1. `package.json` defines the public product identity (`name`, `mcpName`, `bin`,
+   `version`).
+2. `bin.mjs` calls `createConnectorCli({ packageJson, connector })` so every
+   install/doctor/upgrade/uninstall command runs under the developer's brand.
+3. `agent-connector.config.*` uses `defineConnector({ server, ...surfaces })` to
+   describe the real MCP launch shape or remote endpoint.
+4. `install` renders that single declaration into each detected host's native
+   MCP config. For stdio processes, the host points at the stable
+   agent-connector home binary, which launches the real command and can measure
+   per-tool traffic. For remote HTTP servers, the host receives the URL where
+   supported; there is no stdio process to wrap.
+
+### Command boundary
+
+Keep the two command layers separate:
+
+| Layer | Who runs it | Examples | Purpose |
+| --- | --- | --- | --- |
+| Branded MCP lifecycle | Users of your MCP package | `npx @acme/acme-db-mcp install`, `acme-db doctor --probe`, `acme-db upgrade`, `acme-db uninstall`, `acme-db telemetry report --by tool` | Install, verify, update, remove, and inspect telemetry for **your MCP**. |
+| Framework tooling | MCP package developers | `npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs` | Emit host plugin bundles and MCP distribution artifacts from a connector config. |
+| Connector-free user telemetry | Agent-CLI users with no MCP package | `npx @ken-jo/agent-connector usage report --by platform` | Read host CLI logs read-only for whole-conversation token totals. |
+
+If a command operates the MCP after it is authored, prefer the branded package/bin.
+If a command builds framework distribution artifacts, use the framework CLI.
+
+### MCP server launch examples
+
+Pick the `server` shape that matches the MCP you are building. The wrapper
+package identity still comes from `package.json`; these examples only describe
+how to start or connect to the actual MCP server.
+
+| Shape | Use when | Minimal launch |
+| --- | --- | --- |
+| Package-runner MCP | The MCP is published as a package. | `npx -y @acme/acme-db-mcp` |
+| Local server-process MCP | The MCP server ships inside your package. | `node ./my-mcp-server.mjs` |
+| Python MCP | The MCP server is Python and should resolve runtime deps at launch. | `uv run --with mcp ./my_mcp_server.py` |
+| CLI-based MCP | An existing executable exposes an MCP serving mode. | `local-tools mcp serve` |
+| Remote server MCP | The MCP is hosted behind an HTTP endpoint. | `https://mcp.example.com/mcp` |
+
+Each snippet below is the `server` field for `defineConnector({ ... })`; only
+the local server-process example needs the `serverPath` helper shown inline.
+
+**Package-runner MCP** — a published package that should be launched with `npx`:
+
+```js
+server: {
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@acme/acme-db-mcp"],
+}
+```
+
+**Local server-process MCP** — a bundled server file or binary:
+
+```js
+import { fileURLToPath } from "node:url";
+
+const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));
+
+server: {
+  transport: "stdio",
+  command: "node",
+  args: [serverPath],
+}
+```
+
+**Python MCP** — usually run through `uv` so dependencies are resolved with the
+server:
+
+```js
+server: {
+  transport: "stdio",
+  command: "uv",
+  args: ["run", "--with", "mcp", "./my_mcp_server.py"],
+}
+```
+
+Use direct `python ./my_mcp_server.py` only when the runtime environment is
+already managed by your package or deployment wrapper.
+
+**CLI-based MCP** — an existing executable exposes an MCP mode:
+
+```js
+server: {
+  transport: "stdio",
+  command: "local-tools",
+  args: ["mcp", "serve"],
+}
+```
+
+**Remote server MCP** — a hosted MCP endpoint:
+
+```js
+server: {
+  transport: "http",
+  url: "https://mcp.example.com/mcp",
+}
+```
+
+```bash
 # 4. deploy under your branded MCP package/bin
 npx @acme/acme-db-mcp detect            # which platforms are installed here?
+npx @acme/acme-db-mcp audit             # catch package/bin/connector identity drift
 npx @acme/acme-db-mcp install --dry-run # preview every change first
 npx @acme/acme-db-mcp install           # write native config in each host
-```
-
-> `install` targets only the hosts actually **detected** on this machine (or an
-> explicit `--targets` / `connector.targets` list), intersected with the
-> current adapter registry shown on [`/coverage`](https://agent-connector.ai/coverage)
-> — there is no "install to every host unconditionally" path.
-> `@ken-jo/agent-connector` is the framework dependency underneath; use it
-> directly for framework packaging/debugging or connector-free token telemetry,
-> not as the foreground install brand for your users.
-
-## Ship it: direct install or a marketplace plugin
-
-Same one definition, your choice of distribution.
-
+```
+
+> `install` targets only the hosts actually **detected** on this machine (or an
+> explicit `--targets` / `connector.targets` list), intersected with the
+> current adapter registry shown on [`/coverage`](https://agent-connector.ai/coverage)
+> — there is no "install to every host unconditionally" path.
+> `@ken-jo/agent-connector` is the framework dependency underneath; use it
+> directly for framework packaging/debugging or connector-free token telemetry,
+> not as the foreground install brand for your users.
+
+## Ship it: direct install or a marketplace plugin
+
+Same one definition, your choice of distribution.
+
 **Direct install** — your branded command (`acme-db install`,
 `npx @acme/acme-db-mcp install`) writes each host's native MCP + hook +
 content-surface config in place, with no per-platform marketplace submission or
 review. This is the Quick start path above.
 
-**Marketplace plugin** — the framework `package` command turns the connector
-into a real plugin/extension bundle (manifest + bundled commands, agents,
-skills, hooks, MCP) from one definition. This is framework tooling, so run it
-with `npx @ken-jo/agent-connector package --connector ...`. If you already keep
-the framework CLI installed globally, `agent-connector package --connector ...`
-is only the shorter equivalent. Hooks + MCP keep the
-telemetry serve-wrapper, so a marketplace-installed connector still reports
-per-tool tokens for its stdio server. `--format all` emits **10 host formats**:
-
-| Format | Hosts |
-|---|---|
-| `claude-plugin` | Claude Code · Codex · VS Code Copilot · OpenClaw · OMP |
-| `codex-plugin` | Codex (`.codex-plugin/` manifest variant) |
-| `copilot-plugin` | GitHub Copilot CLI |
-| `factory-plugin` | Droid |
-| `gemini-extension` | Gemini CLI |
-| `qwen-extension` | Qwen Code |
-| `agy-plugin` | Antigravity (CLI + IDE) |
-| `cursor-plugin` | Cursor |
-| `kimi-plugin` | Kimi CLI |
-| `npm-plugin` | OpenCode · Kilo CLI · Pi |
-
-Two official **MCP standard artifacts** are opt-in (they need a `publish` block,
-so they're excluded from `--format all`) — `mcp-server-json` (an MCP Registry
-`server.json`) and `mcpb` (a one-click MCPB bundle); see
-[Publish to the MCP ecosystem](#publish-to-the-mcp-ecosystem).
-
-```bash
-# emit every host format (mcp-server-json + mcpb are opt-in by name)
-npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin
-npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format gemini-extension --out ./ext   # or just one
-
-# if you already keep the framework CLI globally installed, the same command is:
-agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin
-
-# e.g. Claude Code:  /plugin marketplace add ./dist-plugin/claude-plugin
-#                    /plugin install <connector-id>@agent-connector
-# e.g. Gemini CLI:   gemini extensions install ./dist-plugin/gemini-extension/<id>
-```
-
-> **Embedded-path caveat.** Most host bundles bake in the absolute home-bin
-> launcher path of the machine that ran `package`, so they're valid for a
-> **local install on that same machine/home**. For shared distribution use
-> `npm-plugin` or the MCP standard artifacts, or re-run `package` per machine.
-
-**Let your branded MCP package drive the host's own install flow** with
-`install --method marketplace`:
-
-```bash
-acme-db install --method marketplace
-
-# framework fallback for local framework development/debugging only
-npx @ken-jo/agent-connector install --method marketplace --connector ./agent-connector.config.mjs
-```
-
-- **What it does** — stages the bundle, registers a local marketplace where the
-  host has one, then runs the host's plugin-install verb (or, for npm-plugin
-  hosts, writes a local `file://` entry); headless and idempotent. Other
-  marketplace-format hosts print the exact manual commands.
-- **Host coverage** — live-verified for Claude Code, Codex, OpenCode, Kilo
-  (CLI + ext), and Antigravity (CLI + IDE) on Linux, Windows, and macOS; Droid
-  and Qwen Code have the driver shipped but pending a live host; Gemini CLI is
-  legacy (sunsetting toward Antigravity — driver kept for existing installs).
-- **Safety + reversal** — a guard refuses installing the same connector by BOTH
-  methods, `uninstall --method auto` reverses whichever method is installed, and
-  `doctor` checks registration drift.
-
-### Ship a branded CLI
-
-A connector developer can ship their **own** bin instead of having users type
-`agent-connector`. `createConnectorCli({ packageJson, connector })` (from the
-`@ken-jo/agent-connector/cli` export) derives the bin name/version from
-`package.json` and exposes **every** subcommand under your brand, fully
-delegated and **auto-scoped** to your connector — so your users do not need a
-framework global install or `--connector` for branded MCP install/doctor/uninstall. See
-[`examples/branded-cli`](examples/branded-cli) for the full, runnable package.
-
-```js
-#!/usr/bin/env node
-// bin.mjs — every agent-connector subcommand, branded as `acme-db`
-import { createConnectorCli } from "@ken-jo/agent-connector/cli";
-
-// run() resolves to the exit code and never calls process.exit
-process.exitCode = await createConnectorCli({
-  // packageJson supplies public identity: name, mcpName, bin, version.
-  packageJson: new URL("./package.json", import.meta.url),
-  // connector supplies behavior: server, hooks, skills, telemetry.
-  // These are two layers, not duplicate id/display-name inputs.
-  connector: new URL("./agent-connector.config.mjs", import.meta.url),
-}).run();
-```
-
-After a consumer installs **your** package, the `acme-db` bin is on their PATH
-and every command is scoped to your connector (`acme-db install` ≈
-`agent-connector install --connector ./agent-connector.config.mjs`). Auto-scoping
-is pure argument injection over the SAME single home binary; `serve` and `hook`
-still route through the one `~/.agent-connector` home binary every host config
-points back to. An explicit `--connector` / `--connector-id` always overrides
-the injected default.
-
-## What you define once
-
-A single `defineConnector({...})` declares your MCP **server** + lifecycle
-**hooks**, and optionally the additional surfaces — **commands**, **skills**,
-**subagents**, **memory**, **statusline**, **actions**, plus host-native escape
-hatches. agent-connector renders each surface into every detected host's native
-format, or *skip-warns* (never silently drops) where a host can't support it.
-
-```ts
-import { fileURLToPath } from "node:url";
-import { defineConnector } from "@ken-jo/agent-connector/sdk";
-
-// Resolve your server to an absolute path — host CLIs spawn it from their own CWD.
-const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));
-
-export default defineConnector({
-  server: {
-    transport: "stdio",
-    command: "node",           // or "npx", "python", etc. — whatever starts your server
-    args: [serverPath],        // replace with your real server entrypoint
-    env: { ACME_DB_DSN: "${env:ACME_DB_DSN}" },
-  },
-  hooks: {
-    PreToolUse: {
-      matcher: "acme_write",
-      async handler(evt) {
-        return evt.toolName === "acme_write"
-          ? { decision: "ask", reason: "Confirm write" }
-          : { decision: "allow" };
-      },
-    },
-  },
-  // telemetry is on by default
-});
-```
-
-`npx @acme/acme-db-mcp install` turns that into, e.g.:
-
-| Host | What gets written |
-|---|---|
-| **Claude Code** | `~/.claude.json` → `mcpServers.acme-db` (+ hooks in `~/.claude/settings.json`) |
-| **Codex CLI** | `~/.codex/config.toml` → `[mcp_servers.acme-db]` (+ `~/.codex/hooks.json`) |
-| **Cursor** | `~/.cursor/mcp.json` → `mcpServers.acme-db` (+ `~/.cursor/hooks.json`) |
-
-…each pointing hooks at a **single stable home binary**, so one update propagates
-everywhere.
-
-**Secret env-refs (`${env:VAR}`).** Write `"${env:VAR}"` (or `"${env:VAR:-default}"`) anywhere in `command` / `args` / `env` / `url` / `headers` to reference an environment variable.
-
-<details>
-<summary>Native interpolation vs. literal-at-install resolution</summary>
-
-> On hosts with **native** interpolation (Claude Code, Cursor, VS Code Copilot,
-> amp, codebuff) the token is written through to the host config and resolved at
-> runtime. Every other host has **no** native interpolation, so the value is
-> resolved to a **literal at install time**; an unset variable with no default
-> resolves to an **empty string**, and `install` emits a `warn` for it on a
-> literal-resolving host.
-
-</details>
-
-**Native hooks escape hatch.** The normalized `hooks` API covers the 13 cross-platform events; for host-only events (Claude Code alone ships 30) declare `platforms: { "claude-code": { nativeHooks: { TaskCompleted: { handler } } } }`.
-
-<details>
-<summary>Raw-payload semantics and the ~14 passthrough hosts</summary>
-
-> The handler receives the host's **raw** payload and whatever it returns is the
-> **verbatim** JSON reply (exit 0 only — exit-2 blocking isn't modeled). Hosts
-> supporting host-native passthrough: `amp`, `claude-code`, `continue`,
-> `copilot-cli`, `cursor`, `gemini-cli`, `hermes`, `jetbrains-copilot`, `kimi`,
-> `nemoclaw`, `omp`, `openclaw`, `opencode`, `qwen-code`. Others skip-warn.
-
-</details>
-
-**Host-config key patches.** For host-exclusive *settings keys* no other surface reaches, declare `platforms: { "claude-code": { configPatch: [{ key, value, reason }] } }` (Claude Code only for now; other hosts skip-warn with the exact manual edit).
-
-<details>
-<summary>Set-if-absent + refcount + denylist semantics</summary>
-
-> Semantics are fixed: **set-if-absent + skip-warn on any conflict** — never
-> overwrite, never deep-merge. Ownership is refcounted in a persisted ledger;
-> security-relevant keys and keys agent-connector models as first-class surfaces
-> are hard-refused.
-
-</details>
-
-### Memory, statusline, actions, and the SDK
-
-- **`memory`** (aligned with the [AGENTS.md](https://agents.md) standard) — ship
-  standing guidance into the memory/rules file each host actually reads.
-  AGENTS.md adopters get the standard file; host-specific exceptions such as
-  Claude Code → `CLAUDE.md` and Gemini CLI → `GEMINI.md` are wired per their own
-  official docs. Writes are surgical marker-fenced, hash-stamped managed blocks
-  — multiple connectors coexist, bytes outside your markers are never touched,
-  and uninstall excises exactly your blocks.
-- **`statusline`** (`defineStatusline`) — a live HUD render function the host
-  calls on every status refresh. v1 registers Claude Code's `settings.json.statusLine`
-  or Qwen Code's `settings.json.ui.statusLine` (set-if-absent, refcounted,
-  reversible); other hosts skip-warn. The runtime is **fail-safe**: any error
-  exits 0 with empty stdout so a HUD never wedges the host.
-- **`actions`** (`defineAction`) — named, user-invocable operations dispatched by
-  the universal verb `agent-connector action <platform> <id> --connector <id>`.
-  `install` emits host-side affordances on `droid`, `hermes`, `nemoclaw`, `omp`,
-  `openclaw`, and `warp`; other hosts skip-warn. Error semantics are
-  user-triggered (unknown id or throw exits 1).
-- **The Connector SDK** (`@ken-jo/agent-connector/sdk`, `/sdk/test`) — the
-  consolidated authoring surface re-exports `defineConnector`, the full `define*`
-  family (`defineHook`, `defineCommand`, `defineSkill`, `defineSubagent`,
-  `defineMemory`, `defineStatusline`, `defineAction`, `defineConfigPatch`,
-  `defineNativeHook`), introspection helpers (`hostsSupporting`,
-  `capabilitiesOf`, `surfaceSupport`), and an **offline harness**
-  (`simulate`, `explain`, `explainHooks`) that runs the real adapter
-  parse→handler→format chain to answer *"does my handler actually work on host
-  X?"* before you touch a real host. Agent-facing guidance is intentionally
-  split into a small router skill plus focused references under
-  [`skills/agent-connector/references`](skills/agent-connector/references). See
-  [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
-
-## How it works
-
-- **Home-dir, single binary.** The runtime installs once under
-  `~/.agent-connector` (override `AGENT_CONNECTOR_DATA_DIR`). Every host config we
-  write is a thin pointer back to that one binary. Updates are
-  **explicit/managed** (`agent-connector upgrade`), never silent auto-update.
-- **Per-project data, kept.** Telemetry/state is keyed by a stable project
-  identity (git remote or normalized path), partitioned per project, stored under
-  the home data-root — surviving `git clean`, shared across hosts opening the same
-  project.
-- **Native config stays native.** We never relocate a host's own settings files;
-  only framework-owned state lives under the data-root.
-- **Windows-first correctness.** No symlinks, no POSIX-only assumptions.
-
-**Three hook paradigms**, all install-verified across the registered platform
-set (see [`/coverage`](https://agent-connector.ai/coverage) and
-[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)):
-
-| Paradigm | Platforms |
-|---|---|
-| `json-stdio` (full hook dispatch) | CodeBuddy · Claude Code · Codex CLI · Cursor · VS Code Copilot · JetBrains Copilot · GitHub Copilot CLI · Gemini CLI · Qwen CLI · Kiro · Kimi CLI · Crush · Goose · Hermes · Droid (Factory) · OpenHands · Antigravity · Antigravity CLI · Continue · Amazon Q · Grok CLI · Devin CLI |
-| `mcp-only` (MCP registration only) | Warp · Roo Code · Cline · Trae · Zed · Codebuff · Mux · Pi · Windsurf · Open Interpreter · Junie · Mistral Vibe |
-| `ts-plugin` (generated bridge module) | OpenCode · MiMoCode · Kilo CLI · Kilo · OMP · NemoClaw · OpenClaw · Amp |
-
-Adding a platform = **one registry entry + one adapter**.
-
-## CLI
-
-| Command | Purpose |
-|---|---|
-| `detect` | List installed platforms, scopes, capabilities, hook paradigm. |
-| `install [--scope …] [--targets …] [--method …] [--dry-run] [--force]` | Render + write MCP + hooks + content surfaces across targets. |
-| `uninstall [--targets …] [--purge] [--method …]` | Full inverse — removes everything we wrote; `--purge` also clears framework state. |
-| `upgrade [--channel …]` | Re-render host config + heal stale pointers + refresh the home binary (alias: `update`, `sync`); never a silent self-update. |
-| `doctor [--probe] [--explain]` | Per-platform health checks with fixes; `--probe` runs a live MCP handshake, `--explain` prints the per-`(host, event)` hook honor matrix. |
+Framework fallback can also install a connector source directly when you are
+testing distribution intake: `github:owner/repo`, `npm:@scope/package@version`,
+or an `archive:` / direct `.tgz` source. Every fetched source is cached under
+`~/.agent-connector/sources/` and must contain `agent-connector.config.*`.
+
+**Marketplace plugin** — the framework `package` command turns the connector
+into a real plugin/extension bundle (manifest + bundled commands, agents,
+skills, hooks, MCP) from one definition. This is framework tooling, so run it
+with `npx @ken-jo/agent-connector package --connector ...`. If you already keep
+the framework CLI installed globally, `agent-connector package --connector ...`
+is only the shorter equivalent. Hooks + MCP keep the
+telemetry serve-wrapper, so a marketplace-installed connector still reports
+per-tool tokens for its stdio server. `--format all` emits **10 host formats**:
+
+| Format | Hosts |
+|---|---|
+| `claude-plugin` | Claude Code · Codex · VS Code Copilot · OpenClaw · OMP |
+| `codex-plugin` | Codex (`.codex-plugin/` manifest variant) |
+| `copilot-plugin` | GitHub Copilot CLI |
+| `factory-plugin` | Droid |
+| `gemini-extension` | Gemini CLI |
+| `qwen-extension` | Qwen Code |
+| `agy-plugin` | Antigravity (CLI + IDE) |
+| `cursor-plugin` | Cursor |
+| `kimi-plugin` | Kimi CLI |
+| `npm-plugin` | OpenCode · Kilo CLI · Pi |
+
+Two official **MCP standard artifacts** are opt-in (they need a `publish` block,
+so they're excluded from `--format all`) — `mcp-server-json` (an MCP Registry
+`server.json`) and `mcpb` (a one-click MCPB bundle); see
+[Publish to the MCP ecosystem](#publish-to-the-mcp-ecosystem).
+
+```bash
+# emit every host format (mcp-server-json + mcpb are opt-in by name)
+npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin
+npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format gemini-extension --out ./ext   # or just one
+
+# if you already keep the framework CLI globally installed, the same command is:
+agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin
+
+# e.g. Claude Code:  /plugin marketplace add ./dist-plugin/claude-plugin
+#                    /plugin install <connector-id>@agent-connector
+# e.g. Gemini CLI:   gemini extensions install ./dist-plugin/gemini-extension/<id>
+```
+
+> **Embedded-path caveat.** Most host bundles bake in the absolute home-bin
+> launcher path of the machine that ran `package`, so they're valid for a
+> **local install on that same machine/home**. For shared distribution use
+> `npm-plugin` or the MCP standard artifacts, or re-run `package` per machine.
+
+**Let your branded MCP package drive the host's own install flow** with
+`install --method marketplace`:
+
+```bash
+acme-db install --method marketplace
+
+# framework fallback for local framework development/debugging only
+npx @ken-jo/agent-connector install --method marketplace --connector ./agent-connector.config.mjs
+```
+
+- **What it does** — stages the bundle, registers a local marketplace where the
+  host has one, then runs the host's plugin-install verb (or, for npm-plugin
+  hosts, writes a local `file://` entry); headless and idempotent. Other
+  marketplace-format hosts print the exact manual commands.
+- **Host coverage** — live-verified for Claude Code, Codex, OpenCode, Kilo
+  (CLI + ext), and Antigravity (CLI + IDE) on Linux, Windows, and macOS; Droid
+  and Qwen Code have the driver shipped but pending a live host; Gemini CLI is
+  legacy (sunsetting toward Antigravity — driver kept for existing installs).
+- **Safety + reversal** — a guard refuses installing the same connector by BOTH
+  methods, `uninstall --method auto` reverses whichever method is installed, and
+  `doctor` checks registration drift.
+
+### Ship a branded CLI
+
+A connector developer can ship their **own** bin instead of having users type
+`agent-connector`. `createConnectorCli({ packageJson, connector })` (from the
+`@ken-jo/agent-connector/cli` export) derives the bin name/version from
+`package.json` and exposes **every** subcommand under your brand, fully
+delegated and **auto-scoped** to your connector — so your users do not need a
+framework global install or `--connector` for branded MCP install/doctor/uninstall. See
+[`examples/branded-cli`](examples/branded-cli) for the full, runnable package.
+
+```js
+#!/usr/bin/env node
+// bin.mjs — every agent-connector subcommand, branded as `acme-db`
+import { createConnectorCli } from "@ken-jo/agent-connector/cli";
+
+// run() resolves to the exit code and never calls process.exit
+process.exitCode = await createConnectorCli({
+  // packageJson supplies public identity: name, mcpName, bin, version.
+  packageJson: new URL("./package.json", import.meta.url),
+  // connector supplies behavior: server, hooks, skills, telemetry.
+  // These are two layers, not duplicate id/display-name inputs.
+  connector: new URL("./agent-connector.config.mjs", import.meta.url),
+}).run();
+```
+
+After a consumer installs **your** package, the `acme-db` bin is on their PATH
+and every command is scoped to your connector (`acme-db install` ≈
+`agent-connector install --connector ./agent-connector.config.mjs`). Auto-scoping
+is pure argument injection over the SAME single home binary; `serve` and `hook`
+still route through the one `~/.agent-connector` home binary every host config
+points back to. An explicit `--connector` / `--connector-id` always overrides
+the injected default.
+
+## What you define once
+
+A single `defineConnector({...})` declares your MCP **server** + lifecycle
+**hooks**, and optionally the additional surfaces — **commands**, **skills**,
+**subagents**, **memory**, **statusline**, **actions**, plus host-native escape
+hatches. agent-connector renders each surface into every detected host's native
+format, or *skip-warns* (never silently drops) where a host can't support it.
+
+```ts
+import { fileURLToPath } from "node:url";
+import { defineConnector } from "@ken-jo/agent-connector/sdk";
+
+// Resolve your server to an absolute path — host CLIs spawn it from their own CWD.
+const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));
+
+export default defineConnector({
+  server: {
+    transport: "stdio",
+    command: "node",           // or "npx", "python", etc. — whatever starts your server
+    args: [serverPath],        // replace with your real server entrypoint
+    env: { ACME_DB_DSN: "${env:ACME_DB_DSN}" },
+  },
+  hooks: {
+    PreToolUse: {
+      matcher: "acme_write",
+      async handler(evt) {
+        return evt.toolName === "acme_write"
+          ? { decision: "ask", reason: "Confirm write" }
+          : { decision: "allow" };
+      },
+    },
+  },
+  // telemetry is on by default
+});
+```
+
+`npx @acme/acme-db-mcp install` turns that into, e.g.:
+
+| Host | What gets written |
+|---|---|
+| **Claude Code** | `~/.claude.json` → `mcpServers.acme-db` (+ hooks in `~/.claude/settings.json`) |
+| **Codex CLI** | `~/.codex/config.toml` → `[mcp_servers.acme-db]` (+ `~/.codex/hooks.json`) |
+| **Cursor** | `~/.cursor/mcp.json` → `mcpServers.acme-db` (+ `~/.cursor/hooks.json`) |
+
+…each pointing hooks at a **single stable home binary**, so one update propagates
+everywhere.
+
+**Secret env-refs (`${env:VAR}`).** Write `"${env:VAR}"` (or `"${env:VAR:-default}"`) anywhere in `command` / `args` / `env` / `url` / `headers` to reference an environment variable.
+
+<details>
+<summary>Native interpolation vs. literal-at-install resolution</summary>
+
+> On hosts with **native** interpolation (Claude Code, Cursor, VS Code Copilot,
+> amp, codebuff) the token is written through to the host config and resolved at
+> runtime. Every other host has **no** native interpolation, so the value is
+> resolved to a **literal at install time**; an unset variable with no default
+> resolves to an **empty string**, and `install` emits a `warn` for it on a
+> literal-resolving host.
+
+</details>
+
+**Native hooks escape hatch.** The normalized `hooks` API covers the 13 cross-platform events; for host-only events (Claude Code alone ships 30) declare `platforms: { "claude-code": { nativeHooks: { TaskCompleted: { handler } } } }`.
+
+<details>
+<summary>Raw-payload semantics and the ~14 passthrough hosts</summary>
+
+> The handler receives the host's **raw** payload and whatever it returns is the
+> **verbatim** JSON reply (exit 0 only — exit-2 blocking isn't modeled). Hosts
+> supporting host-native passthrough: `amp`, `claude-code`, `continue`,
+> `copilot-cli`, `cursor`, `gemini-cli`, `hermes`, `jetbrains-copilot`, `kimi`,
+> `nemoclaw`, `omp`, `openclaw`, `opencode`, `qwen-code`. Others skip-warn.
+
+</details>
+
+**Host-config key patches.** For host-exclusive *settings keys* no other surface reaches, declare `platforms: { "claude-code": { configPatch: [{ key, value, reason }] } }` (Claude Code only for now; other hosts skip-warn with the exact manual edit).
+
+<details>
+<summary>Set-if-absent + refcount + denylist semantics</summary>
+
+> Semantics are fixed: **set-if-absent + skip-warn on any conflict** — never
+> overwrite, never deep-merge. Ownership is refcounted in a persisted ledger;
+> security-relevant keys and keys agent-connector models as first-class surfaces
+> are hard-refused.
+
+</details>
+
+### Memory, statusline, actions, and the SDK
+
+- **`memory`** (aligned with the [AGENTS.md](https://agents.md) standard) — ship
+  standing guidance into the memory/rules file each host actually reads.
+  AGENTS.md adopters get the standard file; host-specific exceptions such as
+  Claude Code → `CLAUDE.md` and Gemini CLI → `GEMINI.md` are wired per their own
+  official docs. Writes are surgical marker-fenced, hash-stamped managed blocks
+  — multiple connectors coexist, bytes outside your markers are never touched,
+  and uninstall excises exactly your blocks.
+- **`statusline`** (`defineStatusline`) — a live HUD render function the host
+  calls on every status refresh. v1 registers Claude Code's `settings.json.statusLine`
+  or Qwen Code's `settings.json.ui.statusLine` (set-if-absent, refcounted,
+  reversible); other hosts skip-warn. The runtime is **fail-safe**: any error
+  exits 0 with empty stdout so a HUD never wedges the host.
+- **`actions`** (`defineAction`) — named, user-invocable operations dispatched by
+  the universal verb `agent-connector action <platform> <id> --connector <id>`.
+  `install` emits host-side affordances on `droid`, `hermes`, `nemoclaw`, `omp`,
+  `openclaw`, and `warp`; other hosts skip-warn. Error semantics are
+  user-triggered (unknown id or throw exits 1).
+- **The Connector SDK** (`@ken-jo/agent-connector/sdk`, `/sdk/test`) — the
+  consolidated authoring surface re-exports `defineConnector`, the full `define*`
+  family (`defineHook`, `defineCommand`, `defineSkill`, `defineSubagent`,
+  `defineMemory`, `defineStatusline`, `defineAction`, `defineConfigPatch`,
+  `defineNativeHook`), introspection helpers (`hostsSupporting`,
+  `capabilitiesOf`, `surfaceSupport`), and an **offline harness**
+  (`simulate`, `explain`, `explainHooks`) that runs the real adapter
+  parse→handler→format chain to answer *"does my handler actually work on host
+  X?"* before you touch a real host. Agent-facing guidance is intentionally
+  split into a small router skill plus focused references under
+  [`skills/agent-connector/references`](skills/agent-connector/references). See
+  [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## How it works
+
+- **Home-dir, single binary.** The runtime installs once under
+  `~/.agent-connector` (override `AGENT_CONNECTOR_DATA_DIR`). Every host config we
+  write is a thin pointer back to that one binary. Updates are
+  **explicit/managed** (`agent-connector upgrade`), never silent auto-update.
+- **Per-project data, kept.** Telemetry/state is keyed by a stable project
+  identity (git remote or normalized path), partitioned per project, stored under
+  the home data-root — surviving `git clean`, shared across hosts opening the same
+  project.
+- **Native config stays native.** We never relocate a host's own settings files;
+  only framework-owned state lives under the data-root.
+- **Windows-first correctness.** No symlinks, no POSIX-only assumptions.
+
+**Three hook paradigms**, all install-verified across the registered platform
+set (see [`/coverage`](https://agent-connector.ai/coverage) and
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)):
+
+| Paradigm | Platforms |
+|---|---|
+| `json-stdio` (full hook dispatch) | CodeBuddy · Claude Code · Codex CLI · Cursor · VS Code Copilot · JetBrains Copilot · GitHub Copilot CLI · Gemini CLI · Qwen CLI · Kiro · Kimi CLI · Crush · Goose · Hermes · Droid (Factory) · OpenHands · Antigravity · Antigravity CLI · Continue · Amazon Q · Grok CLI · Devin CLI |
+| `mcp-only` (MCP registration only) | Warp · Roo Code · Cline · Trae · Zed · Codebuff · Mux · Pi · Windsurf · Open Interpreter · Junie · Mistral Vibe |
+| `ts-plugin` (generated bridge module) | OpenCode · MiMoCode · Kilo CLI · Kilo · OMP · NemoClaw · OpenClaw · Amp |
+
+Adding a platform = **one registry entry + one adapter**.
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `detect` | List installed platforms, scopes, capabilities, hook paradigm. |
+| `install [<source>] [--scope …] [--targets …] [--method …] [--dry-run] [--force]` | Render + write MCP + hooks + content surfaces. `<source>` may be local, GitHub/git, `npm:<package>[@version]`, or `.tgz`/`archive:`. |
+| `uninstall [--targets …] [--purge] [--method …]` | Full inverse — removes everything we wrote; `--purge` also clears framework state. |
+| `upgrade [--channel …]` | Re-render host config + heal stale pointers + refresh the home binary (alias: `update`, `sync`); never a silent self-update. |
+| `doctor [--probe] [--explain]` | Per-platform health checks with fixes; `--probe` runs a live MCP handshake, `--explain` prints the per-`(host, event)` hook honor matrix. |
 | `status` | Light install-state: which connectors are present on which hosts (always exits 0). |
 | `package [--format <fmt>\|all]` | Emit a host plugin bundle, or an OFFICIAL standard artifact: `mcp-server-json` (registry) · `mcpb` (one-click bundle). |
+| `audit [--strict]` | Pre-install package identity lint: package name/version/bin, runtime dependency, connector id/version drift, and publish `files` coverage. |
 | `action <platform> <id> [--connector <id>]` | Run a declared action from the shell. |
-| `telemetry report [--by …] [--since …] [--connector <id>]` | Per-tool token footprint of **your connector's own wrapped server**. Stdio servers only. |
-| `telemetry export [--format …] [--connector <id>]` | Raw aggregate records for your wrapped server. |
-| `usage report\|export\|leaderboard [--by …]` | **No connector needed.** Host-native whole-conversation token totals parsed read-only from each agent CLI's own logs. Does NOT break down by individual MCP or tool. |
-| `leaderboard [--since …] [--connector <id>] [--scope …]` | Three origin-labeled boards with **different prerequisites** (🔌 MCP/plugin · 🛰️ host-native turns · 🖥️ host/user); counts are never summed across them. |
-
-> `hook` and `serve` also exist — internal entrypoints the written host configs
-> point at; you never run them by hand. Full flag-level reference: the
-> [docs site `/docs/dev/cli`](https://agent-connector.ai/docs/dev/cli) · `llms-full.txt` §3 (canonical, drift-guarded by tests).
-
-## Token telemetry & usage
-
-Two independent, never-summed views of token cost:
-
-- **Per-tool telemetry for *your own* server** (the MCP-developer path). No host
-  reports per-tool usage back to an MCP server, so agent-connector measures your
-  server's *own* bytes (args in, results out, tool schemas) and tokenizes them
-  locally — **aggregate counts only, stored locally, zero egress by default.**
-  Per-tool telemetry is automatic for **stdio** servers; remote (`http`/`sse`/`ws`)
-  servers are registered but not wrapped (the proxy can't intercept remote
-  transports). Read it with `agent-connector telemetry report --by tool`.
-- **Connector-free usage** (`agent-connector usage`). Already run Claude Code /
-  Codex / Cursor and just want totals? `usage` reads your local agent-CLI session
-  logs **read-only** and never writes any host config — no connector, no install:
-
-  ```bash
-  npx @ken-jo/agent-connector usage report --by platform        # CLI/model/project/session/day
-  npx @ken-jo/agent-connector usage leaderboard --by platform   # or --by model
-  npx @ken-jo/agent-connector usage export --format csv --out usage.csv
-  ```
-
-  It reports **whole-conversation totals** per agent CLI / model / project /
-  session / day. It does **not** itemize cost by individual MCP server or tool —
-  agent CLIs don't log per-tool attribution.
-
-**Privacy & tokenizer.** Default tokenizer is `gpt-tokenizer` (pure-JS, no native
-build) — `o200k_base` for OpenAI/Codex-family, a documented approximation for
-Anthropic; falls back to a `chars/4` heuristic if it can't load. Every record
-carries a confidence tag. Raw tool arguments and results are never stored or
-transmitted. Off switch: `AGENT_CONNECTOR_TELEMETRY=0`, or
-`telemetry: { enabled: false }`.
-
-## Publish to the MCP ecosystem
-
-Where the MCP standard already covers your server's functionality,
-agent-connector **emits the standard exactly** so your already-standard work is
-portable:
-
-- **`package --format mcp-server-json`** → an official **MCP Registry**
-  `server.json` (schema `2025-12-11`). It describes your **real upstream server**
-  (what a registry installer runs), not our telemetry wrapper. Publish it with
-  the official `mcp-publisher` CLI.
-- **`package --format mcpb`** → an official **MCPB** (`.mcpb`, formerly DXT)
-  bundle `manifest.json` (`manifest_version 0.3`) for one-click local install in
-  Claude Desktop and any MCPB host, with secrets routed through the host keychain
-  (`user_config`).
-
-Both read a `publish` block on your connector (the namespace you own + your
-published package + author):
-
-```ts
-defineConnector({
-  server: { transport: "stdio", command: "npx", args: ["-y", "@acme/acme-db-mcp"] },
-  publish: {
-    registryNamespace: "io.github.acme", // a namespace YOU proved ownership of
-    packageName: "@acme/acme-db-mcp",     // your REAL published package
-    author: { name: "Acme Inc" },
-  },
-});
-```
-
-> **Config we write is the standard.** `install` writes each host's native MCP
-> config in the de-facto canonical `mcpServers` shape — `{ command, args, env }`
-> for stdio, `{ url, headers }` for remote. The spec transport slug for
-> streamable HTTP is `streamable-http` (registry `server.json`); host configs
-> canonically use `http`. WebSocket (`ws`) is **not** an MCP spec transport and
-> the standard artifacts reject it.
-
-> **Forward-compatible by transport.** The `serve` proxy is **byte-transparent**:
-> it forwards every JSON-RPC message verbatim and only tees a copy to count
-> `tools/call` round-trips. So newer MCP features ride through untouched —
-> **MCP Apps** (the official `io.modelcontextprotocol/ui` extension) and **any
-> reverse-DNS extension** negotiated at `initialize`. A connector whose server
-> already speaks these deploys across every host and keeps its telemetry today,
-> no agent-connector change required.
-
-## Verification
-
-The full single-API contract is **install-verified across the current platform
-registry** by a committed registry-driven install-roundtrip harness that, for
-every adapter, drives the real install → uninstall into an isolated HOME and
-asserts on-disk placement + zero residue. A separate committed
-`scripts/verify-host.mjs` driver installs real host CLIs from the verification
-matrix and checks install → placement → clean-uninstall; live hook dispatch +
-telemetry are proven end-to-end where the host can run headlessly. IDE
-extensions / GUI editors with no headless CLI stay covered by the
-install-roundtrip harness.
-
-**Dogfood result:** porting the real multi-host context-mode plugin to
-`defineConnector` collapsed **~20,322 lines of hand-maintained per-host code down
-to ~76 lines** (a 99.63% reduction). See the reports under
-[`docs/research/`](docs/research/) and [`CHANGELOG.md`](CHANGELOG.md).
-
-## Development
-
-```bash
-npm install
-npm run typecheck
-npm run build
-npm run dev -- detect     # run the CLI from source via tsx
-
-# Tests: scope + single-fork (NOT bare `npm test` — it OOMs low-RAM machines).
-npx vitest run --pool=forks --poolOptions.forks.singleFork=true --poolOptions.forks.maxForks=1 \
-  tests/adapters/<host>.test.ts
-```
-
-## Contributing
-
-PRs welcome — especially new host adapters and fixes verified against a host's
-primary source. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the dev workflow,
-the single-fork test discipline, the **verify-first** rule for adapters, and the
-new-host checklist. Want a new agent CLI supported? Open a
-[host adapter request](https://github.com/ken-jo/agent-connector/issues/new?template=host_adapter_request.yml).
-
-Security reports: see [SECURITY.md](SECURITY.md).
-
-## License
-
-Apache-2.0 © 2026 KenJo
+| `telemetry report [--by …] [--since …] [--connector <id>]` | Per-tool token footprint of **your connector's own wrapped server**. Stdio servers only. |
+| `telemetry export [--format …] [--connector <id>]` | Raw aggregate records for your wrapped server. |
+| `usage report\|export\|leaderboard [--by …]` | **No connector needed.** Host-native whole-conversation token totals parsed read-only from each agent CLI's own logs. Does NOT break down by individual MCP or tool. |
+| `leaderboard [--since …] [--connector <id>] [--scope …]` | Three origin-labeled boards with **different prerequisites** (🔌 MCP/plugin · 🛰️ host-native turns · 🖥️ host/user); counts are never summed across them. |
+
+> `hook` and `serve` also exist — internal entrypoints the written host configs
+> point at; you never run them by hand. Full flag-level reference: the
+> [docs site `/docs/dev/cli`](https://agent-connector.ai/docs/dev/cli) · `llms-full.txt` §3 (canonical, drift-guarded by tests).
+
+## Token telemetry & usage
+
+Two independent, never-summed views of token cost:
+
+- **Per-tool telemetry for *your own* server** (the MCP-developer path). No host
+  reports per-tool usage back to an MCP server, so agent-connector measures your
+  server's *own* bytes (args in, results out, tool schemas) and tokenizes them
+  locally — **aggregate counts only, stored locally, zero egress by default.**
+  Per-tool telemetry is automatic for **stdio** servers; remote (`http`/`sse`/`ws`)
+  servers are registered but not wrapped (the proxy can't intercept remote
+  transports). Read it with `agent-connector telemetry report --by tool`.
+- **Connector-free usage** (`agent-connector usage`). Already run Claude Code /
+  Codex / Cursor and just want totals? `usage` reads your local agent-CLI session
+  logs **read-only** and never writes any host config — no connector, no install:
+
+  ```bash
+  npx @ken-jo/agent-connector usage report --by platform        # CLI/model/project/session/day
+  npx @ken-jo/agent-connector usage leaderboard --by platform   # or --by model
+  npx @ken-jo/agent-connector usage export --format csv --out usage.csv
+  ```
+
+  It reports **whole-conversation totals** per agent CLI / model / project /
+  session / day. It does **not** itemize cost by individual MCP server or tool —
+  agent CLIs don't log per-tool attribution.
+
+**Privacy & tokenizer.** Default tokenizer is `gpt-tokenizer` (pure-JS, no native
+build) — `o200k_base` for OpenAI/Codex-family, a documented approximation for
+Anthropic; falls back to a `chars/4` heuristic if it can't load. Every record
+carries a confidence tag. Raw tool arguments and results are never stored or
+transmitted. Off switch: `AGENT_CONNECTOR_TELEMETRY=0`, or
+`telemetry: { enabled: false }`.
+
+## Publish to the MCP ecosystem
+
+Where the MCP standard already covers your server's functionality,
+agent-connector **emits the standard exactly** so your already-standard work is
+portable:
+
+- **`package --format mcp-server-json`** → an official **MCP Registry**
+  `server.json` (schema `2025-12-11`). It describes your **real upstream server**
+  (what a registry installer runs), not our telemetry wrapper. Publish it with
+  the official `mcp-publisher` CLI.
+- **`package --format mcpb`** → an official **MCPB** (`.mcpb`, formerly DXT)
+  bundle `manifest.json` (`manifest_version 0.3`) for one-click local install in
+  Claude Desktop and any MCPB host, with secrets routed through the host keychain
+  (`user_config`).
+
+Both read a `publish` block on your connector (the namespace you own + your
+published package + author):
+
+```ts
+defineConnector({
+  server: { transport: "stdio", command: "npx", args: ["-y", "@acme/acme-db-mcp"] },
+  publish: {
+    registryNamespace: "io.github.acme", // a namespace YOU proved ownership of
+    packageName: "@acme/acme-db-mcp",     // your REAL published package
+    author: { name: "Acme Inc" },
+  },
+});
+```
+
+> **Config we write is the standard.** `install` writes each host's native MCP
+> config in the de-facto canonical `mcpServers` shape — `{ command, args, env }`
+> for stdio, `{ url, headers }` for remote. The spec transport slug for
+> streamable HTTP is `streamable-http` (registry `server.json`); host configs
+> canonically use `http`. WebSocket (`ws`) is **not** an MCP spec transport and
+> the standard artifacts reject it.
+
+> **Forward-compatible by transport.** The `serve` proxy is **byte-transparent**:
+> it forwards every JSON-RPC message verbatim and only tees a copy to count
+> `tools/call` round-trips. So newer MCP features ride through untouched —
+> **MCP Apps** (the official `io.modelcontextprotocol/ui` extension) and **any
+> reverse-DNS extension** negotiated at `initialize`. A connector whose server
+> already speaks these deploys across every host and keeps its telemetry today,
+> no agent-connector change required.
+
+## Verification
+
+The full single-API contract is **install-verified across the current platform
+registry** by a committed registry-driven install-roundtrip harness that, for
+every adapter, drives the real install → uninstall into an isolated HOME and
+asserts on-disk placement + zero residue. A separate committed
+`scripts/verify-host.mjs` driver installs real host CLIs from the verification
+matrix and checks install → placement → clean-uninstall; live hook dispatch +
+telemetry are proven end-to-end where the host can run headlessly. IDE
+extensions / GUI editors with no headless CLI stay covered by the
+install-roundtrip harness.
+
+**Dogfood result:** porting the real multi-host context-mode plugin to
+`defineConnector` collapsed **~20,322 lines of hand-maintained per-host code down
+to ~76 lines** (a 99.63% reduction). See the reports under
+[`docs/research/`](docs/research/) and [`CHANGELOG.md`](CHANGELOG.md).
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm run dev -- detect     # run the CLI from source via tsx
+
+# Tests: scope + single-fork (useful on low-RAM machines).
+npm run test:single -- tests/adapters/<host>.test.ts
+```
+
+## Contributing
+
+PRs welcome — especially new host adapters and fixes verified against a host's
+primary source. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the dev workflow,
+the single-fork test discipline, the **verify-first** rule for adapters, and the
+new-host checklist. Want a new agent CLI supported? Open a
+[host adapter request](https://github.com/ken-jo/agent-connector/issues/new?template=host_adapter_request.yml).
+
+Security reports: see [SECURITY.md](SECURITY.md).
+
+## License
+
+Apache-2.0 © 2026 KenJo