diff --git a/11-Features.md b/11-Features.md
index 3851586..73a4ea9 100644
--- a/11-Features.md
+++ b/11-Features.md
@@ -29,6 +29,7 @@ six weeks, and the table alone will not carry it.
 | [Session lifecycle caps](#session-lifecycle-caps) | `lifecycle:` | CB-303 | `session/SessionManager` |
 | [Durable reply inbox](#durable-reply-inbox) | `broker:` | CB-307 | `msg/AmqpReplyInbox` |
 | [Pin an opencode endpoint](#pin-an-opencode-endpoint) | profile `baseUrl:` | CB-508 | `worker/OpenCodeLauncher` |
+| [Onboard a project with the plugin](#onboard-a-project-with-the-plugin) | `/plugin install claude-bridge` → `/claude-bridge:setup` | CB-527 | `plugin/` |
 
 Nearly every knob above lives in one file, on one profile:
 
@@ -201,6 +202,31 @@ the session is still BUSY currently discards the later completion rather than pa
 **Gotcha.** Because it bypasses `SubscriptionGuard`, the guard's allowlist does not protect this
 path — the endpoint you name is the endpoint it uses.
 
+## Onboard a project with the plugin
+
+**What.** A Claude Code plugin that makes any project bridge-ready: it mounts the `bridged` MCP
+gateway and ships a `/claude-bridge:setup` skill that runs preflight, applies standard project
+settings, names the environment variables the operator must export, and verifies the session
+resolves as the primary.
+
+**On.** `/plugin marketplace add ltms/claude-bridge` then `/plugin install
+claude-bridge@claude-bridge`; run `/claude-bridge:setup` inside the project to onboard. Develop it
+locally with `claude --plugin-dir ./plugin`.
+
+**Why.** The orchestration contract had no distributable form. Every consuming project had to
+hand-copy a block of `CLAUDE.md` and hand-write an `.mcp.json`, and we maintained a script purely to
+detect the copies drifting apart. A plugin is versioned, installed once, and updates in place — the
+contract stops being something each project re-derives. It ships **no credentials** by design, so
+the artifact is public-safe: every secret is referenced by environment-variable name and the value
+never enters a file.
+
+**Gotcha.** The plugin is client-side setup only — it mounts a daemon, it does not install one.
+`bridged` and `herdr` remain separate services, and the setup skill deliberately refuses to install
+them (guessing at a system-service install is how you get two daemons on one socket). Note also the
+plugin root is `plugin/`, **not** the repo root: an installed plugin's `.mcp.json` is a committed
+file, while this repo's root `.mcp.json` is local-only and `--skip-worktree`, so rooting the plugin
+at the repo would collide with the very isolation CB-525 exists to enforce.
+
 ---
 
 ## Backfill status