code-ai-installer 4.0.1 → 4.3.0

package/README.md

@@ -48,7 +48,7 @@ Every domain also carries a meta **Auditor** beside the pipeline. Each skill dec
 
 ## 🚪 The MCP Gate Pipeline
 
-When you install for **Claude**, the installer registers `code-ai-mcp` in your global (user-scope) Claude config via `claude mcp add --scope user` (idempotent — a server already present in user scope is left untouched). From then on, the agents drive the work *through the server*, not by free-form prompting:
+When you install for **Claude**, the installer registers `code-ai-mcp` in your global (user-scope) Claude config — it adds an entry to the `mcpServers` object of `~/.claude.json` (idempotent — a server already present is left untouched, so an existing global `mempalace` is never duplicated). From then on, the agents drive the work *through the server*, not by free-form prompting:
 
 1. **`current_gate` / `classify_gate`** — the conductor reads where the run is and classifies the gate outcome (`auto_resolve` / `fork` / `exception`).
 2. **`get_skill`** — the active role fetches the skills it owns at this gate (the fetch is logged as telemetry for the Auditor).
@@ -151,14 +151,16 @@ Depending on `--target`, `code-ai` restructures your project:
 1. **Orchestration entry** — `AGENTS.md` (plus tool aliases like `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `QWEN.md`, `KIMI.md`).
 2. **Agents** — roles copied into the target's layout (e.g. `.claude/agents/<role>.md`, `.github/copilot-instructions.md`).
 3. **Skills & workflows** — the execution skillsets, with per-tool metadata sidecars.
-4. **MCP wiring (Claude only)** — registers `code-ai-mcp` (run as `npx -p code-ai-installer code-ai-mcp`) in your global (user-scope) Claude config via `claude mcp add --scope user`, plus an optional [MemPalace](https://www.npmjs.com/package/mempalace) memory server when present, and a project-local `.code-ai/config.json` that records the active domain and decision-store backend. If the `claude` CLI isn't on PATH, the installer prints the exact commands to run instead of editing your config by hand.
+4. **MCP wiring (Claude only)** — registers `code-ai-mcp` (run as `npx -p code-ai-installer code-ai-mcp`) in your global (user-scope) Claude config by adding it to the `mcpServers` object of `~/.claude.json` (backed up first, written atomically, idempotent), plus an optional [MemPalace](https://www.npmjs.com/package/mempalace) memory server when present, and a project-local `.code-ai/config.json` that records the active domain and decision-store backend. If `~/.claude.json` can't be read or written, the installer prints the exact JSON entries to add by hand instead of guessing.
 
 ---
 
 ## 🧬 Versions & migration
 
-`code-ai-installer` is on **v4.0.0**.
+`code-ai-installer` is on **v4.3.0**.
 
+- **v4.3.0** — `render_diff` MCP tool (unified diff → a standalone HTML review page); MCP gate-flow + stop-at-user-gate sections added to the content / analytics / product conductors; Auditor trigger — a `/audit` command plus a Release-Gate nudge that surfaces after every 3rd completed run (development pilot).
+- **v4.1.0** — MCP servers now register in your **global (user-scope)** config via a direct, idempotent `~/.claude.json` merge (no dependency on the `claude` CLI); the conductor halts at each user gate — one at a time, no batching, no auto-pass on green.
 - **v4.0.0** — consolidated the previously separate `code-ai-mcp` and types packages into this single package with **two bins** (`code-ai` + `code-ai-mcp`). Installing the CLI now also delivers the MCP server; for Claude it is auto-registered in your global (user-scope) MCP config. Existing 3.x CLI behavior is unchanged.
 - **v3.0.0 (breaking)** — removed the legacy flat root layout (`AGENTS.md` + `agents/` + `.agents/` at package root); the CLI now reads exclusively from `domains/<id>/`. **Migrating from v2.x:** add `--domain <development|content|analytics|product>` to every CLI call. If you used a custom `--project-dir`, restructure it to `domains/<id>/` instead of a flat layout.
 

package/dist/mcp/audit_ledger.d.ts

@@ -10,3 +10,13 @@ export declare function readLedger(): Promise<RunScorecard[]>;
  * break a sign-off (telemetry is never load-bearing for the gate).
  */
 export declare function recordRunScorecard(state: TaskState): Promise<void>;
+/** Number of COMPLETED (RG-signed) runs in the ledger. */
+export declare function countCompletedRuns(): Promise<number>;
+/**
+ * A1 cadence (Variant A1): surface an Auditor nudge on every 3rd completed run
+ * (3, 6, 9, …). Stateless — no last-audit marker — so it re-reminds until the
+ * user runs /audit. Surfacing only; returns undefined when no nudge is due.
+ */
+export declare function auditNudgeFor(completedRuns: number): {
+    runs_total: number;
+} | undefined;

package/dist/mcp/audit_ledger.js

@@ -80,3 +80,18 @@ export async function recordRunScorecard(state) {
     const extras = await readSideCounts(state.task_id);
     await appendScorecard(buildScorecard(state, extras));
 }
+/** Number of COMPLETED (RG-signed) runs in the ledger. */
+export async function countCompletedRuns() {
+    const cards = await readLedger();
+    return cards.filter((c) => c.completed).length;
+}
+/**
+ * A1 cadence (Variant A1): surface an Auditor nudge on every 3rd completed run
+ * (3, 6, 9, …). Stateless — no last-audit marker — so it re-reminds until the
+ * user runs /audit. Surfacing only; returns undefined when no nudge is due.
+ */
+export function auditNudgeFor(completedRuns) {
+    return completedRuns >= 3 && completedRuns % 3 === 0
+        ? { runs_total: completedRuns }
+        : undefined;
+}

package/dist/mcp/cli.js

@@ -56,6 +56,7 @@ const TOOL_DESCRIPTIONS = {
     dependency_supply_chain: "[stub] Check supply chain (npm audit, Socket integration, license check).",
     docker_compose: "[stub] Run docker compose up/down for a target.",
     e2e_playwright: "[stub] Run Playwright end-to-end suite.",
+    render_diff: "Render a unified diff (e.g. `git diff`) into a colored, per-file, line-numbered HTML review page written to the OS temp dir. Returns the path + a file:// URL the user opens in a browser. Use at the REV gate to present code changes for review. Informational only — the file lives in temp (cleared on reboot), never in the project.",
 };
 function buildServer() {
     const dispatch = new CodeAiMcpServer();

package/dist/mcp/tools/render_diff.d.ts

@@ -0,0 +1,25 @@
+import { type RenderDiffInput, type RenderDiffOutput } from "../../shared/index.js";
+type RowKind = "hunk" | "add" | "del" | "ctx";
+interface DiffRow {
+    kind: RowKind;
+    text: string;
+    o: number | "";
+    n: number | "";
+}
+export interface DiffFile {
+    name: string;
+    added: number;
+    removed: number;
+    rows: DiffRow[];
+}
+/** Parse a unified diff into per-file rows with old/new line numbers. Pure. */
+export declare function parseUnifiedDiff(raw: string): DiffFile[];
+/** Render parsed diff files into a self-contained HTML page. Pure. */
+export declare function renderDiffHtml(diff: string, title: string): {
+    html: string;
+    files: number;
+    added: number;
+    removed: number;
+};
+export declare function renderDiff(input: RenderDiffInput): Promise<RenderDiffOutput>;
+export {};

package/dist/mcp/tools/render_diff.js

@@ -0,0 +1,138 @@
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createHash } from "node:crypto";
+/**
+ * render_diff — turn a unified diff into a colored, per-file, line-numbered HTML
+ * review page and write it to the OS temp dir.
+ *
+ * Why a tool (not a loose script): code reviews in the pipeline are presented as
+ * an HTML diff the user opens via a file:// link. Shipping it as an MCP tool keeps
+ * it version-controlled, testable, and reachable wherever the server runs.
+ *
+ * The output is INFORMATIONAL only — it lives in the system temp dir (cleared on
+ * reboot), never in the project, so it pollutes nothing and needs no cleanup.
+ * Self-contained: no deps, no network.
+ */
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/** Parse a unified diff into per-file rows with old/new line numbers. Pure. */
+export function parseUnifiedDiff(raw) {
+    const blocks = raw.split(/^diff --git /m).filter(Boolean);
+    const files = [];
+    for (const b of blocks) {
+        const lines = ("diff --git " + b).split("\n");
+        const header = lines[0];
+        const m = header.match(/a\/(.+?) b\/(.+)$/);
+        const name = m ? m[2] : header;
+        let added = 0;
+        let removed = 0;
+        const rows = [];
+        let oldLn = 0;
+        let newLn = 0;
+        for (const ln of lines) {
+            if (ln.startsWith("diff --git") ||
+                ln.startsWith("index ") ||
+                ln.startsWith("--- ") ||
+                ln.startsWith("+++ "))
+                continue;
+            const hunk = ln.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+            if (hunk) {
+                oldLn = Number(hunk[1]);
+                newLn = Number(hunk[2]);
+                rows.push({ kind: "hunk", text: ln, o: "", n: "" });
+                continue;
+            }
+            if (ln.startsWith("+")) {
+                added++;
+                rows.push({ kind: "add", text: ln.slice(1), o: "", n: newLn++ });
+            }
+            else if (ln.startsWith("-")) {
+                removed++;
+                rows.push({ kind: "del", text: ln.slice(1), o: oldLn++, n: "" });
+            }
+            else if (ln.startsWith("\\")) {
+                // "" — skip
+            }
+            else {
+                rows.push({ kind: "ctx", text: ln.slice(1), o: oldLn++, n: newLn++ });
+            }
+        }
+        files.push({ name, added, removed, rows });
+    }
+    return files;
+}
+/** Render parsed diff files into a self-contained HTML page. Pure. */
+export function renderDiffHtml(diff, title) {
+    const files = parseUnifiedDiff(diff);
+    const fileSections = files
+        .map((f, i) => {
+        const rowsHtml = f.rows
+            .map((r) => {
+            if (r.kind === "hunk")
+                return `<tr class="hunk"><td class="ln"></td><td class="ln"></td><td class="code">${esc(r.text)}</td></tr>`;
+            const sign = r.kind === "add" ? "+" : r.kind === "del" ? "-" : " ";
+            return `<tr class="${r.kind}"><td class="ln">${r.o}</td><td class="ln">${r.n}</td><td class="code"><span class="sign">${sign}</span>${esc(r.text)}</td></tr>`;
+        })
+            .join("\n");
+        return `<section id="f${i}">
+  <h2>${esc(f.name)} <span class="stat"><span class="plus">+${f.added}</span> <span class="minus">-${f.removed}</span></span></h2>
+  <table>${rowsHtml}</table>
+</section>`;
+    })
+        .join("\n");
+    const added = files.reduce((s, f) => s + f.added, 0);
+    const removed = files.reduce((s, f) => s + f.removed, 0);
+    const nav = files
+        .map((f, i) => `<a href="#f${i}">${esc(f.name.split("/").pop() ?? f.name)}</a>`)
+        .join("");
+    const html = `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<title>${esc(title)}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 13px/1.5 ui-monospace, "Cascadia Code", Consolas, monospace; margin: 0; background:#0d1117; color:#c9d1d9; }
+  header { padding: 16px 24px; border-bottom: 1px solid #30363d; position: sticky; top:0; background:#0d1117; }
+  header h1 { font: 600 16px system-ui, sans-serif; margin: 0 0 4px; }
+  header .summary { font: 13px system-ui, sans-serif; color:#8b949e; }
+  .plus { color:#3fb950; } .minus { color:#f85149; }
+  section { margin: 20px 24px; border: 1px solid #30363d; border-radius: 8px; overflow:hidden; }
+  section h2 { font: 600 13px ui-monospace, monospace; margin:0; padding:10px 14px; background:#161b22; border-bottom:1px solid #30363d; }
+  .stat { float:right; font-weight:400; }
+  table { border-collapse: collapse; width:100%; }
+  td { padding: 0 6px; white-space: pre-wrap; word-break: break-word; vertical-align: top; }
+  td.ln { width:1%; text-align:right; color:#6e7681; user-select:none; border-right:1px solid #21262d; padding:0 8px; }
+  td.code { width:100%; }
+  .sign { display:inline-block; width:1ch; color:#6e7681; }
+  tr.add { background: rgba(63,185,80,.15); } tr.add .sign { color:#3fb950; }
+  tr.del { background: rgba(248,81,73,.15); } tr.del .sign { color:#f85149; }
+  tr.hunk td { background:#161b22; color:#8b949e; padding:4px 14px; }
+  nav { padding: 0 24px; font: 13px system-ui, sans-serif; }
+  nav a { color:#58a6ff; text-decoration:none; display:inline-block; margin:2px 12px 2px 0; }
+</style></head><body>
+<header>
+  <h1>${esc(title)}</h1>
+  <div class="summary">${files.length} files · <span class="plus">+${added}</span> <span class="minus">-${removed}</span></div>
+</header>
+<nav>${nav}</nav>
+${fileSections}
+</body></html>`;
+    return { html, files: files.length, added, removed };
+}
+/** Slugify a label for use in a temp filename. */
+function slug(s) {
+    return (s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40) || "review");
+}
+export async function renderDiff(input) {
+    const title = input.title ?? "Diff review";
+    const { html, files, added, removed } = renderDiffHtml(input.diff, title);
+    // Content-hashed name → same diff reuses one file; lands in the OS temp dir
+    // (cleared on reboot), never in the project.
+    const hash = createHash("sha1").update(input.diff).digest("hex").slice(0, 8);
+    const path = join(tmpdir(), `code-ai-diff-${slug(input.task_id ?? title)}-${hash}.html`);
+    await writeFile(path, html, "utf8");
+    return { path, file_url: pathToFileURL(path).href, files, added, removed };
+}

package/dist/mcp/tools/sign_off.js

@@ -1,6 +1,6 @@
 import { getGateConfig, loadPipeline } from "../pipeline.js";
 import { readTaskState, writeTaskState } from "../task_state.js";
-import { recordRunScorecard } from "../audit_ledger.js";
+import { recordRunScorecard, countCompletedRuns, auditNudgeFor } from "../audit_ledger.js";
 import { resolveActiveDomain } from "../config.js";
 /**
  * Records a sign-off event for the task's current gate. Validates that:
@@ -27,7 +27,9 @@ export async function signOff(input) {
     switch (gateCfg.sign_off_policy) {
         case "user":
             if (input.signer !== "user") {
-                throw new Error(`sign_off: gate ${input.gate} requires signer 'user' (policy=user), got '${input.signer}'`);
+                throw new Error(`sign_off: gate ${input.gate} requires signer 'user' (policy=user), got '${input.signer}'. ` +
+                    `This is a USER gate — HALT: present the ${input.gate} artifact and request the user's sign_off(signer='user') for THIS gate. ` +
+                    `Do not auto-pass it, do not batch it with other gates, and do not begin any downstream-gate work until it is signed.`);
             }
             break;
         case "mcp_auto_pass":
@@ -56,15 +58,18 @@ export async function signOff(input) {
     });
     await writeTaskState(state);
     // Auditor telemetry: when the terminal gate is signed, the run is complete —
-    // append a scorecard to the local ledger. Best-effort: a ledger failure must
-    // NEVER break a sign-off (telemetry is not load-bearing for the gate).
+    // append a scorecard to the local ledger, then compute the /audit nudge.
+    // Best-effort: a ledger failure (or nudge failure) must NEVER break a
+    // sign-off (telemetry is not load-bearing for the gate).
+    let audit_nudge;
     if (input.gate === "RG") {
         try {
             await recordRunScorecard(state);
+            audit_nudge = auditNudgeFor(await countCompletedRuns());
         }
         catch {
             /* swallow — see contract in audit_ledger.recordRunScorecard */
         }
     }
-    return { signed: true, signer: input.signer, timestamp };
+    return { signed: true, signer: input.signer, timestamp, ...(audit_nudge ? { audit_nudge } : {}) };
 }

package/dist/mcp/tools/stubs.js

@@ -31,6 +31,7 @@ import { reviewProposal } from "./review_proposal.js";
 import { e2ePlaywright } from "./e2e_playwright.js";
 import { dockerCompose } from "./docker_compose.js";
 import { dependencySupplyChain } from "./dependency_supply_chain.js";
+import { renderDiff } from "./render_diff.js";
 /** Thrown by every stub until the real implementation lands. */
 export class NotImplementedError extends Error {
     constructor(tool) {
@@ -83,4 +84,5 @@ export const DEFAULT_HANDLERS = {
     dependency_supply_chain: dependencySupplyChain,
     docker_compose: dockerCompose,
     e2e_playwright: e2ePlaywright,
+    render_diff: renderDiff,
 };

package/dist/mcp_setup.d.ts

@@ -5,23 +5,33 @@ import type { DomainId } from "./shared/index.js";
  * Responsibilities:
  *   1. Detect / install MemPalace as an opt-in mirror for decision storage.
  *   2. Register `code-ai-mcp` (always) and `mempalace` (when accepted) in
- *      Claude Code's USER (global) scope via `claude mcp add --scope user`,
- *      so the servers are available across all the user's projects.
+ *      Claude Code's USER (global) config so the servers are available across
+ *      all the user's projects.
  *   3. Write `.code-ai/config.json` so `code-ai-mcp` knows which backend +
  *      domain to use. This stays PROJECT-local — the global server reads it
  *      from the project cwd at runtime.
  *
+ * Why direct edit of `~/.claude.json` (not `claude mcp add --scope user`):
+ * earlier versions registered via the CLI, but `claude mcp add` in current
+ * Claude Code rejects the `-s/--scope` flag whenever a stdio passthrough
+ * (`-- <command> ...`) is present — a commander parsing quirk — so a stdio
+ * server like `code-ai-mcp` can never be added to user scope through the CLI.
+ * The CLI is also version-unstable here. User-scope servers live as plain
+ * entries in the top-level `mcpServers` object of `~/.claude.json` (exactly
+ * where `mempalace`, `figma`, etc. already sit), so we merge there directly.
+ *
  * Why user scope (not a project `.mcp.json`): MCP servers are tools the user
- * wants everywhere, not per-project copies. Writing a project `.mcp.json` both
+ * wants everywhere, not per-project copies. A project `.mcp.json` both
  * scattered `code-ai-mcp` per-project and duplicated an already-global
- * `mempalace` into the project. Registration is idempotent — a server already
- * present in user scope is left untouched.
+ * `mempalace`. Registration is idempotent — a server already present in the
+ * user config is left untouched (so a pre-existing global `mempalace` is never
+ * duplicated or rewritten).
  *
  * Non-Claude targets skip this whole flow — MCP is Claude-specific.
  *
- * Graceful degradation: every step is best-effort. If the `claude` CLI is not
- * on PATH we never touch the user's config by hand — we print the exact
- * `claude mcp add` commands to run manually instead.
+ * Graceful degradation: every step is best-effort. If `~/.claude.json` cannot
+ * be read or written we never guess — we print the exact JSON entries to add by
+ * hand. Writes are atomic (temp file + rename) and back up the original first.
  */
 export type PythonRuntimeTool = "uv" | "pipx" | "pip";
 export interface PythonRuntime {
@@ -35,17 +45,6 @@ export interface McpServerEntry {
     args: string[];
     env?: Record<string, string>;
 }
-/**
- * Minimal `claude` CLI surface this module needs. Injectable so tests can
- * assert the constructed argv without spawning the real CLI.
- */
-export interface ClaudeCli {
-    /** Run `claude <args>`; resolve { ok, output } (combined stdout+stderr). */
-    run(args: string[]): Promise<{
-        ok: boolean;
-        output: string;
-    }>;
-}
 export interface McpSetupOptions {
     destinationDir: string;
     /** User's answer to the MemPalace prompt (true = wants it). */
@@ -64,15 +63,15 @@ export interface McpSetupReport {
     mempalaceInstallAttempted: boolean;
     mempalaceInstallSucceeded: boolean;
     pythonRuntime: PythonRuntime | null;
-    /** Was the `claude` CLI found on PATH? When false, registration falls back to manual instructions. */
-    claudeCliAvailable: boolean;
+    /** Absolute path of the Claude user config we register servers into. */
+    userConfigPath: string;
     /** How servers were registered. */
     registration: "user-scope" | "manual-fallback";
-    /** Server names freshly added to user scope this run. */
+    /** Server names freshly added to the user config this run. */
     serversRegistered: string[];
-    /** Server names already present in user scope (left untouched). */
+    /** Server names already present in the user config (left untouched). */
     serversAlreadyPresent: string[];
-    /** Server names whose registration failed. */
+    /** Server names whose registration failed (config unwritable). */
     serversFailed: string[];
     configPath: string;
     notices: string[];
@@ -85,8 +84,6 @@ export interface McpSetupReport {
  * instead of registering a config that can't launch.
  */
 export declare function detectMemPalace(): Promise<boolean>;
-/** True when the `claude` CLI is on PATH (probed via `claude --version`). */
-export declare function detectClaudeCli(cli?: ClaudeCli): Promise<boolean>;
 /**
  * Find the first available Python install runtime, in preference order:
  * uv → pipx → pip. Returns null if none available.
@@ -102,20 +99,54 @@ export declare function installMemPalace(runtime: PythonRuntime): Promise<{
     output: string;
 }>;
 /**
- * Build the argv for `claude mcp add --scope user <name> -- <command> [args]`.
- * Pure — exported for testing. Env vars become `-e KEY=VALUE` flags placed
- * before the server name (as `claude mcp add` expects options first).
+ * The Claude user config holds user-scope MCP servers in a top-level
+ * `mcpServers` object. We only ever read it, merge our entries, and write it
+ * back — preserving every other key.
+ */
+export interface UserConfigIO {
+    /** Absolute path of the config file. */
+    readonly configPath: string;
+    /** Read + parse the config. `ok:false` when missing or not a JSON object. */
+    read(): Promise<{
+        ok: boolean;
+        data?: Record<string, unknown>;
+        error?: string;
+    }>;
+    /** Back up the original then atomically write `data`. */
+    writeWithBackup(data: Record<string, unknown>): Promise<{
+        ok: boolean;
+        backupPath?: string;
+        error?: string;
+    }>;
+}
+/**
+ * Resolve the Claude user config path. Honours `CLAUDE_CONFIG_DIR` when set,
+ * else `~/.claude.json`.
+ */
+export declare function userConfigPath(): string;
+/** Real filesystem-backed UserConfigIO. Factory so tests can target a temp file. */
+export declare function createUserConfigIO(configPath: string): UserConfigIO;
+/**
+ * Idempotently merge `servers` into the config's top-level `mcpServers`. Pure —
+ * returns a new config object plus which names were freshly added vs already
+ * present. An existing key is NEVER overwritten (so a pre-existing global
+ * `mempalace` is preserved untouched). Exported for unit testing.
  */
-export declare function buildClaudeAddArgs(name: string, entry: McpServerEntry): string[];
-/** Build the argv for `claude mcp remove --scope user <name>`. Pure — exported for testing. */
-export declare function buildClaudeRemoveArgs(name: string): string[];
+export declare function mergeUserScopeServers(config: Record<string, unknown>, servers: Record<string, McpServerEntry>): {
+    config: Record<string, unknown>;
+    registered: string[];
+    alreadyPresent: string[];
+};
 /**
- * Is `name` already registered in Claude's USER scope? Uses `claude mcp get`,
- * whose output prints `Scope: User config` for user-scope servers. A server in
- * a different scope (local/project) returns false here — we still want it in
- * user scope.
+ * Idempotently remove `names` from the config's `mcpServers`. Pure — returns a
+ * new config object plus which names were removed vs were not present. Exported
+ * for unit testing.
  */
-export declare function isRegisteredInUserScope(cli: ClaudeCli, name: string): Promise<boolean>;
+export declare function removeUserScopeServers(config: Record<string, unknown>, names: string[]): {
+    config: Record<string, unknown>;
+    removed: string[];
+    notPresent: string[];
+};
 /**
  * Write `<destinationDir>/.code-ai/config.json` with the chosen backend.
  * Idempotent — re-running overwrites with the same content if backend unchanged.
@@ -133,17 +164,17 @@ export declare function writeCodeAiConfig(destinationDir: string, config: {
  * Order:
  *   1. If user wants MemPalace: detect → install if absent → fall back if install fails.
  *   2. Build server entries (code-ai-mcp always; mempalace only when usable).
- *   3. Register them in Claude USER scope via `claude mcp add --scope user`
- *      (idempotent; skip if already present). If `claude` CLI is absent, emit
- *      manual commands instead of touching the config by hand.
+ *   3. Merge them into the Claude user config's `mcpServers` (idempotent; skip
+ *      already-present). If the config can't be read/written, print the exact
+ *      JSON to add by hand instead of guessing.
  *   4. Write project-local `.code-ai/config.json` with the backend choice.
  *
  * Reports all decisions in `McpSetupReport.notices` so callers can surface
- * them to the user verbatim. `cli` is injectable for testing.
+ * them to the user verbatim. `io` is injectable for testing.
  */
-export declare function setupMcp(opts: McpSetupOptions, cli?: ClaudeCli): Promise<McpSetupReport>;
+export declare function setupMcp(opts: McpSetupOptions, io?: UserConfigIO): Promise<McpSetupReport>;
 export interface McpTeardownReport {
-    claudeCliAvailable: boolean;
+    userConfigPath: string;
     removal: "user-scope" | "manual-fallback";
     serversRemoved: string[];
     serversNotPresent: string[];
@@ -151,10 +182,10 @@ export interface McpTeardownReport {
     notices: string[];
 }
 /**
- * Remove the installer-owned MCP server(s) from Claude's USER scope via
- * `claude mcp remove --scope user`. Idempotent — a server that isn't registered
- * is reported as "nothing to remove". If the `claude` CLI is absent, prints the
- * manual commands instead of touching the config. `cli` is injectable for tests.
+ * Remove the installer-owned MCP server(s) from the Claude user config's
+ * `mcpServers`. Idempotent — a server that isn't present is reported as
+ * "nothing to remove". If the config can't be read/written, prints guidance
+ * instead of guessing. `mempalace` is never touched. `io` is injectable.
  *
  * NOTE: the registration is global (shared across all projects), so this removes
  * code-ai-mcp for every project. That is the chosen behaviour (symmetric with
@@ -162,4 +193,4 @@ export interface McpTeardownReport {
  */
 export declare function teardownMcp(opts: {
     dryRun: boolean;
-}, cli?: ClaudeCli): Promise<McpTeardownReport>;
+}, io?: UserConfigIO): Promise<McpTeardownReport>;