@rafinery/cli 0.2.2 → 0.4.0

package/lib/gate/verify-citations.mjs

@@ -0,0 +1,156 @@
+// Deterministic citation checker for the atlas scan output. Lives INSIDE
+// @rafinery/cli (blueprint split, 0.4.0) — run as `rafa verify-citations`.
+// Three gates:
+//
+//  RESOLUTION (B1)   — every cite `- <file>:<line>[-<end>] :: <token>` points at a line
+//                      that actually contains <token>. Catches off-by-N / wrong-file.
+//  COMPLETENESS (B2) — a note may declare `anchor: <token>`; the checker greps it repo-wide
+//                      (code only, docs excluded) and asserts EVERY hit is a cited site.
+//                      Catches the "3-place vs 5-place" omission bug.
+//  POLICY            — every `type: contract` MUST declare `anchor:` — a greppable token,
+//                      or `anchor: none` for composition/ordering contracts that don't grep
+//                      as one token. So completeness can't be silently skipped (closes F1:
+//                      the guarantee is mandatory, not opt-in; exemptions are explicit).
+//
+// Writes a generated report to <root>/citation-check.md (don't hand-paste it).
+// Returns exit code 1 on any failure. Run from repo root:  rafa verify-citations
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const CITE = /^\s*-\s+(.+?):(\d+)(?:-(\d+))?\s*::\s*(.+?)\s*$/; // - file:start[-end] :: token
+const ANCHOR = /^anchor:\s*(.+?)\s*$/;
+const TYPE = /^type:\s*(.+?)\s*$/;
+
+function walk(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).flatMap((e) => {
+    const p = join(dir, e);
+    return statSync(p).isDirectory() ? walk(p) : (e.endsWith(".md") && !e.startsWith("_")) ? [p] : []; // ignore _*.md scratch
+  });
+}
+
+function gitGrep(token) {
+  try {
+    const out = execSync(`git grep -nF -e ${JSON.stringify(token)}`, { encoding: "utf8" });
+    return out.split("\n").filter(Boolean).map((l) => {
+      const m = l.match(/^(.+?):(\d+):/);
+      return m ? { file: m[1], line: +m[2] } : null;
+    }).filter(Boolean);
+  } catch (e) {
+    if (e.status === 1) return []; // git grep: no matches
+    throw e;
+  }
+}
+
+function citeResolves(file, start, end, token) {
+  if (!existsSync(file)) return { ok: false, reason: "file missing" };
+  const src = readFileSync(file, "utf8").split("\n");
+  if (start < 1 || end > src.length) return { ok: false, reason: `lines ${start}-${end} out of range (${src.length})` };
+  if (src.slice(start - 1, end).some((l) => l.includes(token))) return { ok: true, reason: "" };
+  return { ok: false, reason: `token not on ${start}${end !== start ? "-" + end : ""}` };
+}
+
+export function runVerifyCitations(argv = []) {
+  const arg = (k, d) => { const m = argv.find((a) => a.startsWith(`--${k}=`)); return m ? m.slice(k.length + 3) : d; };
+  const ROOT = arg("root", ".rafa/brain");                                      // --root=.rafa/improve for the improve ledger
+  const NOTE_DIRS = arg("dirs", "rules,playbooks").split(",").filter(Boolean);  // --dirs=improvements
+
+  // --selftest: prove the resolution logic fails on a bad cite and passes a good one, on a
+  // throwaway temp file (no brain/repo pollution). prism runs this as its mutation probe —
+  // re-running the checker is not proof it still works; this is.
+  if (argv.includes("--selftest")) {
+    const dir = mkdtempSync(join(tmpdir(), "vc-selftest-"));
+    const f = join(dir, "sample.txt");
+    writeFileSync(f, "alpha\nTOKEN beta\ngamma\n");
+    const good = citeResolves(f, 2, 2, "TOKEN").ok; // expect true
+    const bad = citeResolves(f, 1, 1, "TOKEN").ok;  // expect false (off-by-one)
+    rmSync(dir, { recursive: true, force: true });
+    const sane = good === true && bad === false;
+    console.log(`checker self-test: ${sane ? "PASS" : "FAIL"} — good cite=${good} (expect true), bad cite=${bad} (expect false)`);
+    return sane ? 0 : 1;
+  }
+
+  const notes = NOTE_DIRS.flatMap((d) => walk(join(ROOT, d)));
+  if (notes.length === 0) {
+    console.log(`No notes under ${ROOT}/{${NOTE_DIRS.join(",")}}/ — run a scan first.`);
+    return 0;
+  }
+
+  const resolution = []; // { note, loc, token, ok, reason }
+  const completeness = []; // { note, anchor, site, ok, reason }
+  const policy = []; // { note, ok, reason }
+
+  for (const note of notes) {
+    const rel = note.replace(ROOT + "/", "");
+    const lines = readFileSync(note, "utf8").split("\n");
+    const cites = [];
+    const anchors = [];
+    let noteType = "";
+    let fence = 0;
+    for (const line of lines) {
+      if (line.trim() === "---") { fence++; if (fence >= 2) break; continue; }
+      if (fence !== 1) continue;
+      const c = line.match(CITE);
+      if (c) { cites.push({ file: c[1], start: +c[2], end: c[3] ? +c[3] : +c[2], token: c[4] }); continue; }
+      const a = line.match(ANCHOR);
+      if (a) { anchors.push(a[1].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "").trim()); continue; }
+      const t = line.match(TYPE);
+      if (t) noteType = t[1].replace(/\s+#.*$/, "").trim();
+    }
+
+    // POLICY — every contract must declare an anchor (token or explicit `none`)
+    if (noteType === "contract") {
+      const ok = anchors.length > 0;
+      policy.push({ note: rel, ok, reason: ok ? "" : "type: contract must declare `anchor: <token>` (or `anchor: none` for composition/ordering contracts)" });
+    }
+
+    // RESOLUTION
+    for (const ct of cites) {
+      const { ok, reason } = citeResolves(ct.file, ct.start, ct.end, ct.token);
+      resolution.push({ note: rel, loc: `${ct.file}:${ct.start}${ct.end !== ct.start ? "-" + ct.end : ""}`, token: ct.token, ok, reason });
+    }
+
+    // COMPLETENESS
+    for (const anchor of anchors) {
+      if (anchor.toLowerCase() === "none") continue; // explicit, visible exemption
+      const hits = gitGrep(anchor).filter((h) => !h.file.endsWith(".md")); // docs excluded
+      if (hits.length === 0) {
+        completeness.push({ note: rel, anchor, site: "(none)", ok: false, reason: "anchor found nowhere in code — wrong token?" });
+        continue;
+      }
+      for (const h of hits) {
+        const covered = cites.some((ct) => ct.file === h.file && h.line >= ct.start && h.line <= ct.end);
+        completeness.push({ note: rel, anchor, site: `${h.file}:${h.line}`, ok: covered, reason: covered ? "" : "grep hit not cited — site omitted" });
+      }
+    }
+  }
+
+  const rFail = resolution.filter((r) => !r.ok);
+  const cFail = completeness.filter((r) => !r.ok);
+  const pFail = policy.filter((r) => !r.ok);
+  const fail = rFail.length + cFail.length + pFail.length;
+
+  const md = [
+    "# Citation check (generated — do not hand-edit)",
+    "",
+    `## Resolution (B1): ${resolution.length - rFail.length}/${resolution.length} ✓`,
+    ...resolution.map((r) => `${r.ok ? "✓" : "✗"} ${r.loc} :: ${r.token}${r.ok ? "" : "  — " + r.reason + " [" + r.note + "]"}`),
+    "",
+    `## Completeness (B2): ${completeness.length - cFail.length}/${completeness.length} ✓  (${new Set(completeness.map((c) => c.anchor)).size} anchors)`,
+    ...completeness.map((r) => `${r.ok ? "✓" : "✗"} anchor '${r.anchor}' → ${r.site}${r.ok ? "" : "  — " + r.reason + " [" + r.note + "]"}`),
+    "",
+    `## Policy (contract → anchor declared): ${policy.length - pFail.length}/${policy.length} ✓`,
+    ...policy.map((r) => `${r.ok ? "✓" : "✗"} ${r.note}${r.ok ? "" : "  — " + r.reason}`),
+    "",
+    fail ? `**${fail} FAILED.**` : "**All pass.**",
+    "",
+  ].join("\n");
+  writeFileSync(join(ROOT, "citation-check.md"), md);
+
+  console.log(md);
+  console.log(`resolution ${resolution.length - rFail.length}/${resolution.length} · completeness ${completeness.length - cFail.length}/${completeness.length} · policy ${policy.length - pFail.length}/${policy.length}` + (fail ? ` · ${fail} FAILED` : " · all pass"));
+  return fail ? 1 : 0;
+}

package/lib/hydrate.mjs

@@ -0,0 +1,96 @@
+// rafa hydrate — fault knowledge INTO the lazy .rafa/ instance (working-set
+// architecture, ratified 2026-07-10). Two sources, one bookkeeping rule:
+//
+//   rafa hydrate rule <id>        one org-brain note → .rafa/brain/rules/<id>.md
+//   rafa hydrate playbook <id>    one org-brain note → .rafa/brain/playbooks/<id>.md
+//       Stamped in the sidecar with its main-brain base version (envelope
+//       brainForSha) + content hash — an UNEDITED hydration is a disposable
+//       cache `rafa checkpoint` will never push; editing it makes it working set.
+//
+//   rafa hydrate --working-set    this branch's working set (teammates' synced
+//       files) → .rafa/brain/** with sidecar sync records, so a fresh session
+//       starts exactly where the branch's knowledge stands.
+//
+// Hydration reconstructs note files from served fields (the MCP serves fields,
+// not raw files). `anchor:` is not served — a contract note edited after
+// hydration must re-declare it before distillation; the policy gate is loud.
+
+import { execSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { callTool } from "./mcp-client.mjs";
+import {
+  hashOf,
+  materializeNote,
+  readSidecar,
+  writeSidecar,
+} from "./working-set.mjs";
+
+const die = (m) => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+
+export default async function hydrate(args = []) {
+  const ROOT = process.cwd();
+
+  if (args.includes("--working-set")) {
+    let branch = "";
+    try {
+      branch = execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd: ROOT,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      die("not a git repo — run from your code repo root");
+    }
+    let payload;
+    try {
+      payload = await callTool(ROOT, "get_working_set", { branch, status: "active" });
+    } catch (e) {
+      die(e instanceof Error ? e.message : String(e));
+    }
+    const files = payload.files ?? [];
+    if (files.length === 0) {
+      console.log(`✓ no active working set on ${branch} — nothing to hydrate`);
+      return;
+    }
+    const sidecar = readSidecar(ROOT);
+    const syncBranch = (sidecar.sync[branch] = sidecar.sync[branch] ?? {});
+    for (const f of files) {
+      const abs = join(ROOT, ".rafa", f.path);
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, f.content);
+      syncBranch[f.path] = { version: f.version, hash: hashOf(f.content) };
+      if (f.baseBrainSha)
+        sidecar.files[f.path] = {
+          baseBrainSha: f.baseBrainSha,
+          hash: sidecar.files[f.path]?.hash ?? "",
+        };
+      console.log(`  ✓ ${f.path}  (v${f.version} · ${f.lastAuthor})`);
+    }
+    writeSidecar(ROOT, sidecar);
+    console.log(`✓ hydrated ${files.length} working-set file(s) on ${branch}`);
+    return;
+  }
+
+  const [kind, id] = args.filter((a) => !a.startsWith("-"));
+  if ((kind !== "rule" && kind !== "playbook") || !id)
+    die("usage: rafa hydrate <rule|playbook> <id>   ·   rafa hydrate --working-set");
+
+  let payload;
+  try {
+    payload = await callTool(ROOT, kind === "rule" ? "get_rule" : "get_playbook", { id });
+  } catch (e) {
+    die(e instanceof Error ? e.message : String(e));
+  }
+  const brainForSha = payload.envelope?.brainForSha ?? null;
+  const rel = materializeNote(ROOT, kind, payload, brainForSha);
+  console.log(
+    `✓ hydrated ${kind} "${id}" → .rafa/${rel}` +
+      (brainForSha ? `  (base: ${String(brainForSha).slice(0, 7)})` : "") +
+      "\n  Unedited = disposable cache (never pushed). Edit it and it becomes working set" +
+      "\n  — `rafa checkpoint` syncs it. Contract notes: re-declare `anchor:` before distilling an edit.",
+  );
+}

package/lib/init.mjs

@@ -1,16 +1,16 @@
 // rafa init — provision a repo: vendor the blueprint, and (with a platform setup
 // URL) wire the brain remote. Run inside your code repo's root.
 
-import {
-  existsSync,
-  writeFileSync,
-  readFileSync,
-  appendFileSync,
-} from "node:fs";
-import { execSync } from "node:child_process";
+import { existsSync, readFileSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
 import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
 import { mergeClaudeSettings } from "./claude-config.mjs";
+import {
+  credentialsPath,
+  mergeLocalEnv,
+  mergeMcpJson,
+  saveCredentials,
+} from "./mcp-config.mjs";
 import { stampCurrent } from "./stamp.mjs";
 import { notifyIfBehind } from "./version-check.mjs";
 import { isInteractive, ask } from "./prompt.mjs";
@@ -71,8 +71,6 @@ const die = (m) => {
   console.error(`✗ ${m}`);
   process.exit(1);
 };
-const run = (cmd, cwd) =>
-  execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" }).trim();
 
 export default async function init(args) {
   const url = args.find((a) => !a.startsWith("-"));
@@ -98,22 +96,59 @@ export default async function init(args) {
     console.log("rafa init — vendoring the blueprint (no setup URL)");
   }
 
-  // Vendor the blueprint into .claude/ + .rafa/ (you own these copies) — non-destructive:
-  // tools/contract move in lockstep; owned files (agents, capabilities) prompt before overwrite.
+  // Vendor the blueprint into .claude/ (you own these copies) — non-destructive:
+  // the contract moves in lockstep; owned files (agents, command, skills) prompt
+  // before overwrite. `.rafa/` itself is NOT created here — it is lazy, gitignored
+  // knowledge+state that bootstraps from rafa.json on first `rafa pull`/`push`.
   reportBlueprint(
     await copyBlueprint(blueprintSource(), TARGET, { onConflict: makeConflictResolver(args) }),
   );
-  if (!existsSync(join(TARGET, ".rafa", "active.md")))
-    writeFileSync(join(TARGET, ".rafa", "active.md"), "# No active plan\n");
-  // Grant rafa's vendored tools their permissions (merge, never overwrite).
+  // Grant rafa's tools their permissions (merge, never overwrite).
   reportSettings(TARGET);
 
-  // Keep the brain out of the code repo's diffs.
-  const gi = join(TARGET, ".gitignore");
-  const body = existsSync(gi) ? readFileSync(gi, "utf8") : "";
-  if (!/^\.rafa\/?\s*$/m.test(body)) {
-    appendFileSync(gi, `${body.endsWith("\n") || body === "" ? "" : "\n"}.rafa/\n`);
-    console.log("  ✓ .rafa/ → .gitignore");
+  // Keep the brain out of the code repo's diffs; keep the per-dev MCP key out of git.
+  const ensureIgnored = (line, label) => {
+    const gi = join(TARGET, ".gitignore");
+    const body = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+    const re = new RegExp(`^${line.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\/?\\s*$`, "m");
+    if (!re.test(body)) {
+      appendFileSync(gi, `${body.endsWith("\n") || body === "" ? "" : "\n"}${line}\n`);
+      console.log(`  ✓ ${label} → .gitignore`);
+    }
+  };
+  ensureIgnored(".rafa/", ".rafa/");
+
+  // Wire the platform's knowledge MCP (contract §9): committed .mcp.json entry
+  // (secret-free, ${RAFA_MCP_KEY} expansion) + the key in gitignored local config
+  // + the per-machine canonical copy. The key was minted at setup generation and
+  // is consume-once: a re-fetched setup arrives keyless and we say so loudly.
+  if (p?.mcpUrl) {
+    if (p.agentKey) {
+      const cred = saveCredentials(p.repoId, p.agentKey, p.mcpUrl);
+      console.log(
+        cred.skipped
+          ? `  ! MCP key NOT saved to ${credentialsPath()} — ${cred.skipped}`
+          : `  ✓ MCP key → ${cred.file} (0600)`,
+      );
+      const env = mergeLocalEnv(TARGET, p.agentKey);
+      console.log(
+        env.skipped
+          ? `  ! ${env.skipped} — export RAFA_MCP_KEY yourself (key is in ${credentialsPath()})`
+          : "  ✓ RAFA_MCP_KEY → .claude/settings.local.json (gitignored)",
+      );
+      ensureIgnored(".claude/settings.local.json", ".claude/settings.local.json");
+    } else {
+      console.log(
+        `  ! this setup's MCP key was already consumed${p.agentKeyConsumed ? "" : " or absent"} — ` +
+          "mint one on the platform (repo → Agent access) and set RAFA_MCP_KEY in .claude/settings.local.json",
+      );
+    }
+    const mcp = mergeMcpJson(TARGET, p.mcpUrl);
+    console.log(
+      mcp.skipped
+        ? `  ! ${mcp.skipped} — add the "rafinery" server pointing at ${p.mcpUrl} yourself`
+        : `  ✓ knowledge MCP → .mcp.json (rafinery · ${p.mcpUrl})`,
+    );
   }
 
   // Stamp the versions this repo was provisioned at — the compat anchor `update`/`migrate`
@@ -131,23 +166,22 @@ export default async function init(args) {
       : {},
   );
 
-  if (p) {
-    const rafaDir = join(TARGET, ".rafa");
-    if (!existsSync(join(rafaDir, ".git"))) run("git init -b main", rafaDir);
-    try {
-      run("git remote get-url origin", rafaDir);
-      run(`git remote set-url origin ${p.brainRepoUrl}`, rafaDir);
-    } catch {
-      run(`git remote add origin ${p.brainRepoUrl}`, rafaDir);
-    }
-    console.log("  ✓ .rafa/ is its own git repo → origin = brain remote");
-  }
-
   console.log(
     `\n✓ Provisioned.\n\nNext steps:\n` +
-      "  1. Restart Claude Code in this repo (reload the /rafa command + agents).\n" +
-      "  2. Run  /rafa scan  — build + validate the brain, then  rafa push  to sync it.\n" +
-      "  3. Open the repo on the rafinery platform — its Overview shows the brain once pushed.",
+      "  1. Commit the vendored files (agents, /rafa command, skills, contract, rafa.json)\n" +
+      "     — protected-main teams: via a normal MR. The brain remote lives in rafa.json,\n" +
+      "     so any teammate's clone bootstraps with  npx rafa pull  (no init needed).\n" +
+      "  2. Restart Claude Code in this repo (reload the /rafa command + agents + skills" +
+      (p?.mcpUrl ? " + the rafinery MCP server" : "") +
+      ").\n" +
+      "  3. First machine on this repo: run  /rafa scan  then  rafa push  (from a main\n" +
+      "     checkout — rafa push only touches the BRAIN repo, never the code repo).\n" +
+      "     Joining an ALREADY-scanned repo: run  rafa pull  — never re-scan for existing knowledge.\n" +
+      "  4. Open the repo on the rafinery platform — its Overview shows the brain once pushed." +
+      (p?.mcpUrl
+        ? "\n  5. After the first push, any MCP client with a key can query this repo's knowledge\n" +
+          `     (endpoint: ${p.mcpUrl} · keys: repo → Agent access on the platform).`
+        : ""),
   );
 
   await notifyIfBehind();

package/lib/leverage/adapters/claude-code.mjs

@@ -50,14 +50,15 @@ const adapter = {
       });
     }
 
-    // rafa's own tools should run without a prompt each time.
-    if (existsSync(join(cwd, ".rafa", "bin"))) {
+    // rafa's own tools should run without a prompt each time. Provisioned =
+    // the /rafa command is vendored (the gates live inside the CLI since 0.4.0).
+    if (existsSync(join(cwd, ".claude", "commands", "rafa.md"))) {
       if (cap.settingsState === "missing") {
         tips.push({
           id: "no-settings",
           priority: P2,
           title: "No `.claude/settings.json` — every rafa tool call prompts",
-          detail: "rafa vendored gates into .rafa/bin but nothing grants them.",
+          detail: "rafa is provisioned but nothing grants its CLI commands.",
           fix: "run `rafa init` (or `rafa update`) — it merges the permissions in",
         });
       } else if (cap.settingsState === "ok") {
@@ -67,7 +68,7 @@ const adapter = {
             id: "perms-missing",
             priority: P2,
             title: `${missing.length} rafa tool permission(s) not allow-listed`,
-            detail: "the vendored gates will prompt until granted.",
+            detail: "the rafa CLI commands will prompt until granted.",
             fix: "run `rafa update` — it unions them into settings.json without clobbering yours",
           });
         }

package/lib/mcp-client.mjs

@@ -0,0 +1,97 @@
+// Minimal MCP-over-HTTP client for the platform's knowledge/state endpoint
+// (JSON-RPC 2.0 tools/call — the same surface any MCP client speaks).
+//
+// Auth + endpoint resolution, in order of truth:
+//   key    — $RAFA_MCP_KEY, else ~/.config/rafinery/credentials.json (repos[repoId].key)
+//   mcpUrl — $RAFA_MCP_URL, else credentials.json, else the committed .mcp.json
+//            "rafinery" entry (secret-free)
+//   repoId — the committed rafa.json (stamped at init)
+//
+// Errors are LOUD: a missing key/url/repoId names exactly what to do; a tool
+// error is thrown with the server's message, never swallowed.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { credentialsPath } from "./mcp-config.mjs";
+import { readStamp } from "./stamp.mjs";
+
+const readJson = (file) => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+// The platform repo id this working copy is provisioned for.
+export function repoIdOf(cwd) {
+  const stamp = readStamp(cwd);
+  return typeof stamp.repoId === "string" && stamp.repoId !== "" ? stamp.repoId : null;
+}
+
+export function resolveMcp(cwd) {
+  const repoId = repoIdOf(cwd);
+  if (!repoId)
+    throw new Error(
+      "no repoId in rafa.json — this repo isn't platform-provisioned (run `rafa init <setup-url>`)",
+    );
+
+  const creds = readJson(credentialsPath());
+  const repoCreds = creds?.repos?.[repoId] ?? null;
+
+  const key = process.env.RAFA_MCP_KEY || repoCreds?.key || null;
+  if (!key)
+    throw new Error(
+      `no agent key — set RAFA_MCP_KEY, or mint one on the platform (repo → Agent access) ` +
+        `and save it to ${credentialsPath()} (rafa init does this automatically)`,
+    );
+
+  let mcpUrl = process.env.RAFA_MCP_URL || repoCreds?.mcpUrl || null;
+  if (!mcpUrl) {
+    const mcpJson = readJson(join(cwd, ".mcp.json"));
+    const url = mcpJson?.mcpServers?.rafinery?.url;
+    if (typeof url === "string" && url !== "") mcpUrl = url;
+  }
+  if (!mcpUrl)
+    throw new Error(
+      "no MCP endpoint — set RAFA_MCP_URL, or ensure .mcp.json carries the `rafinery` server entry",
+    );
+
+  return { repoId, key, mcpUrl };
+}
+
+let rpcId = 0;
+
+// Call one tool; returns the structured payload. Throws with the server's
+// message on transport or tool errors.
+export async function callTool(cwd, tool, args = {}) {
+  const { repoId, key, mcpUrl } = resolveMcp(cwd);
+  const res = await fetch(mcpUrl, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${key}`,
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: ++rpcId,
+      method: "tools/call",
+      params: { name: tool, arguments: { repo: repoId, ...args } },
+    }),
+  });
+  if (res.status === 401)
+    throw new Error("agent key rejected (401) — revoked or wrong platform; mint a new one (repo → Agent access)");
+  if (res.status === 429)
+    throw new Error("rate limited (429) — back off and retry");
+  if (!res.ok) throw new Error(`MCP endpoint returned HTTP ${res.status}`);
+  const body = await res.json();
+  if (body.error) throw new Error(`MCP error: ${body.error.message ?? JSON.stringify(body.error)}`);
+  const result = body.result ?? {};
+  const payload = result.structuredContent ?? null;
+  if (result.isError) {
+    const msg = payload?.error ?? result.content?.[0]?.text ?? "tool error";
+    throw new Error(`${tool}: ${msg}`);
+  }
+  if (payload === null) throw new Error(`${tool}: empty response`);
+  return payload;
+}

package/lib/mcp-config.mjs

@@ -0,0 +1,93 @@
+// MCP wiring for `rafa init` — connect the client repo to the platform's
+// knowledge MCP (.claude/rafa/contract.md §9) with zero secrets in committed files:
+//
+//   .mcp.json                     committed · server entry, key via ${RAFA_MCP_KEY}
+//   .claude/settings.local.json   gitignored · env.RAFA_MCP_KEY = the raw key
+//   ~/.config/rafinery/credentials.json   per-machine canonical copy (0600)
+//
+// Merge, never clobber: unparseable files are left alone (reported), other
+// servers/env keys are preserved; only the `rafinery` entry is ours to replace.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+const readJson = (file) => {
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+};
+const writeJson = (file, data) => {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+};
+
+export function credentialsPath() {
+  return join(homedir(), ".config", "rafinery", "credentials.json");
+}
+
+// Canonical per-machine store: { repos: { <repoId>: { key, mcpUrl, savedAt } } }.
+// Never inside the code repo or the brain repo — nothing to gitignore, nothing
+// for `rafa push` to publish.
+export function saveCredentials(repoId, key, mcpUrl) {
+  const file = credentialsPath();
+  const existing = readJson(file);
+  if (existing?.error)
+    return { skipped: `credentials.json is not valid JSON (${existing.error})` };
+  const data = existing ?? {};
+  data.repos = { ...(data.repos ?? {}) };
+  data.repos[repoId] = { key, mcpUrl, savedAt: new Date().toISOString() };
+  writeJson(file, data);
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    /* best-effort on non-POSIX */
+  }
+  return { file };
+}
+
+// .mcp.json — the committed, shareable server registration. The Authorization
+// header uses ${RAFA_MCP_KEY} env expansion, so the file carries NO secret; each
+// teammate's key comes from their own settings.local.json / shell env.
+export function mergeMcpJson(targetDir, mcpUrl) {
+  const file = join(targetDir, ".mcp.json");
+  const existing = readJson(file);
+  if (existing?.error)
+    return { skipped: `.mcp.json is not valid JSON (${existing.error})` };
+  const data = existing ?? {};
+  data.mcpServers = { ...(data.mcpServers ?? {}) };
+  const entry = {
+    type: "http",
+    url: mcpUrl,
+    headers: { Authorization: "Bearer ${RAFA_MCP_KEY}" },
+  };
+  const same = JSON.stringify(data.mcpServers.rafinery) === JSON.stringify(entry);
+  data.mcpServers.rafinery = entry;
+  if (!same) writeJson(file, data);
+  return { file, changed: !same };
+}
+
+// .claude/settings.local.json — Claude Code's gitignored per-checkout settings;
+// its `env` map is applied to the session, which is exactly where a per-dev
+// secret belongs. Everything else in the file is preserved.
+export function mergeLocalEnv(targetDir, key) {
+  const file = join(targetDir, ".claude", "settings.local.json");
+  const existing = readJson(file);
+  if (existing?.error)
+    return {
+      skipped: `.claude/settings.local.json is not valid JSON (${existing.error})`,
+    };
+  const data = existing ?? {};
+  data.env = { ...(data.env ?? {}), RAFA_MCP_KEY: key };
+  writeJson(file, data);
+  return { file };
+}

package/lib/migrations/index.mjs

@@ -18,8 +18,6 @@
 //                  can't do this correctly; `run` is a no-op that flags it, and `/rafa migrate`
 //                  (the LLM) rewrites the files against the contract. Intelligence lives there.
 //
-// Empty by design until a release actually changes a shape — the SEAM is what matters,
-// so the first breaking change ships its migration here and `rafa migrate` just works.
 // Example (kept as a reference, not registered):
 //
 //   const plans_v1_to_v2 = {
@@ -30,7 +28,45 @@
 //     run: (cwd) => backfillPlanField(cwd, "owner", ownerOf(cwd)),
 //   };
 
-export const MIGRATIONS = [];
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { cmpSemver } from "../releases.mjs";
+
+// 0.4.0 blueprint split: gate tools moved INSIDE the CLI, capabilities became
+// committed skills (.claude/skills/rafa-*), the contract went canonical in the
+// code repo (.claude/rafa/contract.md). The old vendored copies under .rafa/
+// were LOCKSTEP files (always overwritten by us, never dev-tuned), so removing
+// them mechanically is safe — the update that runs this has already vendored
+// the new locations.
+const blueprint_split_0_4_0 = {
+  id: "blueprint-split-0.4.0",
+  kind: "config",
+  mode: "mechanical",
+  summary:
+    "remove the pre-0.4.0 vendored gate tools + capabilities + contract from .rafa/ " +
+    "(tools now live inside @rafinery/cli; capabilities are .claude/skills/rafa-*; " +
+    "contract is .claude/rafa/contract.md)",
+  appliesTo: (from, to) =>
+    cmpSemver(from.cli, "0.4.0") < 0 && cmpSemver(to.version, "0.4.0") >= 0,
+  run: (cwd) => {
+    const changed = [];
+    for (const rel of [".rafa/bin", ".rafa/capabilities", ".rafa/contract.md"]) {
+      const p = join(cwd, rel);
+      if (existsSync(p)) {
+        rmSync(p, { recursive: true, force: true });
+        changed.push(rel);
+      }
+    }
+    return {
+      changed,
+      notes: changed.length
+        ? ["gate tools: `npx rafa <cmd>` · SOPs: .claude/skills/rafa-* · contract: .claude/rafa/contract.md"]
+        : ["nothing to clean — repo already on the split layout"],
+    };
+  },
+};
+
+export const MIGRATIONS = [blueprint_split_0_4_0];
 
 // The migrations that apply to a given move (stamped `from` → shipped `to`), in order.
 export function pendingMigrations(from, to) {