Merge branch 'main' into test

Author: plind-junior

README.md

@@ -127,6 +127,8 @@ vouch install-mcp claude-code       # creates .vouch/ (if missing) + wires Claud
 
 > **Why the extra registration?** A committed `.mcp.json` is a *project*-scope server, and Claude Code only loads one after a per-user approval — which the **VS Code extension never prompts for**, so `.mcp.json` alone leaves the `kb_*` tools invisible in the extension (they sit at "pending approval", while the hooks quietly work — easy to misread as "connected"). The local-scope entry `install-mcp` writes is trusted on sight, so a fresh install just connects. Verify with `claude mcp list` (`vouch … ✔ Connected`). Pass `--no-approve` to skip it and approve `.mcp.json` yourself.
 
+> **One-time approval.** Claude Code only loads a project's `.mcp.json` servers after a per-user approval. The terminal CLI prompts for it on the next `claude` launch — but the **VS Code extension never shows this prompt**, so the `kb.*` tools stay unavailable there while the hooks keep working (which makes it easy to think vouch is connected when it isn't). If `claude mcp list` run inside the project shows `vouch … ⏸ Pending approval`, either run `claude` in the project folder from any terminal and accept the prompt, or create `.claude/settings.local.json` (user-local, not committed) with `{"enabledMcpjsonServers": ["vouch"]}`. The same key in the committed `.claude/settings.json` is deliberately ignored — a repo can't approve its own servers — which is why `install-mcp` can't do this step for you. Verify with `claude mcp list` (`✔ Connected`), then reload the VS Code window.
+
 **2. Point `compile` at an LLM** — the only step that needs a model. In `.vouch/config.yaml`:
 
 ```yaml

adapters/claude-code/README.md

@@ -40,19 +40,21 @@ contains `.vouch/` — created by `vouch init` if you're wiring by hand):
 }
 ```
 
-A `.mcp.json` server is *project*-scope: the terminal CLI prompts once to
-approve it, but **the VS Code extension never surfaces that prompt**, so on
-its own it sits at "pending approval" and the `kb_*` tools never appear (the
-hooks, which need no approval, keep working — easy to misread as connected).
-To load it in the extension, register the same server at *local* scope, which
-is trusted on sight:
-
-```bash
-claude mcp add vouch --env VOUCH_AGENT=claude-code -- vouch serve
-```
-
-(the one-command `install-mcp` above does this for you). Then reload the
-editor window. Confirm with `claude mcp list` — `vouch … ✔ Connected`.
+Claude Code will pick it up the next time you open the project — after a
+one-time, per-user approval. The terminal CLI prompts for it on the next
+`claude` launch; the VS Code extension does **not** surface the prompt,
+so the server sits at "Pending approval" and the `kb.*` tools never
+appear (the hooks, which need no approval, keep working — easy to
+misread as "vouch is connected"). Approve either way:
+
+* run `claude` in the project folder from any terminal and accept the
+  MCP server prompt, or
+* create `.claude/settings.local.json` (user-local, keep it out of git)
+  containing `{"enabledMcpjsonServers": ["vouch"]}`.
+
+The same key in the committed `.claude/settings.json` is ignored — a
+repo can't approve its own servers. Reload the VS Code window
+afterwards.
 
 ## 3. Teach Claude about the gate
 
@@ -75,10 +77,10 @@ In a fresh session, ask Claude:
 > What knowledge-base tools do you have?
 
 It should enumerate `kb_search`, `kb_propose_claim`, etc. If not, check
-`claude mcp list` first: `vouch … ⏸ Pending approval` means the local-scope
-registration from step 2 hasn't happened (`✔ Connected` once it has), and a
-running editor window needs a reload to pick it up. For anything else, run
-`claude --debug-mcp` to see why the server isn't loading.
+`claude mcp list` first: `vouch: vouch serve - ⏸ Pending approval` means
+the one-time approval from step 2 hasn't happened yet (`✔ Connected`
+once it has). For anything else, run `claude --debug-mcp` to see why
+the server isn't loading.
 
 ## Session Capture & Auto-Proposal