@rafinery/cli 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.
 CLI reads it to tell a client, on `rafa update`, exactly what an upgrade requires (nothing,
 a re-scan, or a `rafa migrate`).
 
+## 0.3.0
+
+**Adopt with:** `npx @rafinery/cli@latest update` — no re-scan, no migration required.
+Recommended: re-run `/rafa scan` (or a `rafa push`) so your manifest picks up the new `plans[]`.
+
+The read side lands — your brain is now queryable by any MCP client.
+
+- **`init` wires the knowledge MCP (secret-free where committed).** With a platform setup URL,
+  `init` now registers the platform's read-only knowledge MCP:
+  - `.mcp.json` (committed) — a `rafinery` HTTP server with `Authorization: Bearer ${RAFA_MCP_KEY}`
+    env expansion, so **no secret is committed**.
+  - `.claude/settings.local.json` `env` (gitignored) + `~/.config/rafinery/credentials.json` (0600) —
+    where the raw per-dev key lives. The key is minted at setup generation and delivered
+    **consume-once** through the setup fetch; a re-fetched (keyless) setup is reported loudly, with
+    instructions to mint one on the platform (repo → Agent access).
+  - Merge, never clobber: unparseable files are left alone and reported; other servers/env keys are
+    preserved; only the `rafinery` entry is ours.
+- **Contract §9 — the read-side twin.** Documents the platform-served knowledge MCP: the mandatory
+  response envelope (`source`/`brainForSha`/`ingestedAt`), loud error semantics (no assumed values),
+  and the read-only tool set (`get_brain_status`, `search_knowledge`, `get_rule/playbook/improvement`,
+  `list_improvements`, `get_plan`, `get_active_plan`, `get_coverage`).
+- **§7 plans wired; compile emits `plans[]` + `activePlanId`.** Plan files are no longer "Slice 4" —
+  compile now parses `plans/**/*.md`, enforces global-id uniqueness, parent/child integrity, and
+  the no-stored-progress rule, resolves `active.md` → `activePlanId`, and emits them into
+  `manifest.json`. Progress stays **derived**, never stored.
+
+## 0.2.2
+
+**Adopt with:** `npx @rafinery/cli@latest update` — no re-scan, no migration.
+
+Completes 0.2.1 (which was published before these two landed):
+
+- **shadcn-style overwrite, no more `.new` clutter.** When a vendored file the dev owns already
+  exists and differs, `init`/`update` **ask** "overwrite? [y/N/a/q]" and act on the answer —
+  instead of silently writing `<file>.new`. Flags `--overwrite` / `--keep` skip the prompt; a
+  non-TTY (CI / agent shell) safely keeps files. Stale `.new` files from older CLIs are cleaned up.
+- **`/rafa help`** — a full command reference for both surfaces (in-editor `/rafa` vs terminal
+  `rafa` CLI), also shown on no argument or an unrecognized command.
+
 ## 0.2.1
 
 **Adopt with:** `npx @rafinery/cli@latest update` (or `/rafa update` in Claude Code) — no re-scan,

package/bin/rafa.mjs

@@ -29,6 +29,10 @@ Commands:
   init [<setup-url>]   Provision this repo — vendor the blueprint (agents, capabilities,
                        contract, gates) and, with a platform setup URL, wire the brain remote.
   update               Re-sync the blueprint into this repo (you own your copy; opt-in updates).
+
+  Flags (init/update):  --overwrite  replace changed owned files without asking
+                        --keep       keep all changed owned files without asking
+                        (default: ask per file; in a non-TTY it keeps them)
   compile              Validate the brain against the contract → .rafa/manifest.json.
   push                 Compile, then push .rafa/ to your brain remote.
   leverage             Inspect your agent toolbox (permissions, skills, MCP) and print
@@ -36,7 +40,29 @@ Commands:
   migrate              Bring this repo's structured files (plans, config) up to the schema
                        the installed CLI ships. Idempotent; review the diff after.
 
-Then, inside Claude Code:  /rafa scan · /rafa improve · /rafa plan
+End to end — from zero to a queryable, working brain:
+
+  1. PLATFORM   Sign in → add a GitHub token → add your brain repo + code repo →
+                connect them → "Generate setup command" (URL expires in 15 min;
+                it carries a one-time MCP agent key).
+  2. INSTALL    In your code repo:  npx @rafinery/cli init '<setup-url>'
+                → vendors the blueprint (.rafa/ + .claude/), wires the brain remote,
+                  registers the knowledge MCP in .mcp.json (secret-free) and puts the
+                  key in .claude/settings.local.json + ~/.config/rafinery/credentials.json.
+  3. SCAN       Restart Claude Code, run  /rafa scan  — atlas maps the codebase into
+                cited rules/playbooks, prism validates, bloom writes the improvement
+                ledger. Then  rafa push  → webhook → the platform ingests it.
+  4. SEE IT     Open the repo on the platform: Overview (health), Brain (files),
+                Improvements (kanban), Plans. "Agent access" mints keys for more
+                clients (Slack, incident.io, CI — anything that speaks MCP).
+  5. WORK       /rafa plan "<intent>"  — a prism-validated plan, grounded in the brain.
+                /rafa build            — execute it; progress syncs on every push, so
+                any teammate or session resumes where you stopped.
+  6. QUERY      Any MCP client with a key can read the brain at <platform>/api/mcp:
+                get_brain_status · search_knowledge · get_rule/playbook/improvement ·
+                get_plan · get_active_plan. Read-only, cited, per-repo scoped.
+
+Then, inside Claude Code:  /rafa scan · /rafa improve · /rafa plan · /rafa build
 
 Docs: ${pkg.homepage ?? "https://github.com/rafinery-ai/rafinery"}`);
 }

package/blueprint/.claude/commands/rafa.md

@@ -1,5 +1,5 @@
 ---
-description: rafa — init · scan · improve · push · leverage · migrate · update. Usage: /rafa <init|scan|improve|push|leverage|migrate|update> [--brain-only]
+description: rafa — init · scan · improve · plan · build · push · leverage · migrate · update · help. Usage: /rafa <init|scan|improve|plan|build|push|leverage|migrate|update|help> [--brain-only]
 ---
 
 You are the **conductor** of the rafa agent loop, running in the **main session**.
@@ -52,6 +52,38 @@ cite-check them (`--root=.rafa/improve --dirs=improvements`, drop unresolved), r
 `ledger.md` + debt trend."* When it returns, read `ledger.md` and **surface only the top few
 high-leverage P0/P1s — don't nag; the dev triages.**
 
+## `plan <intent>` — brain-grounded, prism-validated decomposition
+Per [`.rafa/capabilities/plan.md`](../../.rafa/capabilities/plan.md). The trio at plan time —
+atlas drafts, bloom pulls, prism validates the plan itself:
+1. **Staleness check** — if this repo is platform-connected, compare the MCP envelope's
+   `brainForSha` to the local brain stamp; if the platform is behind, surface "run `rafa push`"
+   (never proceed silently, never block).
+2. **Spawn `atlas`** context-isolated: *"Draft a plan for `<intent>` per
+   `.rafa/capabilities/plan.md`: RECALL the brain slice for the touched domains (coverage →
+   search → rules/playbooks, honor non-exemplars), name the blast radius, decompose into
+   contract §7 files — one parent + child-owned tasks, globally-unique prefixed ids, each child
+   body carrying a `## Done-check`. Return the draft file contents."*
+3. **Spawn `bloom`**: *"List open improvements in the blast radius `<domains>`; return the
+   top-leverage few as optional child tasks."* Fold them in, marked optional.
+4. **Spawn `prism`** context-isolated: *"Validate this DRAFT plan against the brain + code per
+   `.rafa/capabilities/plan.md`: every task grounded (not hallucinated), every child has a
+   `## Done-check`. REJECT with reasons or PASS."* Fix-and-revalidate until PASS (max 3; then
+   surface and stop).
+5. **Approval gate** (ExitPlanMode / the dev). On approval: write `plans/<plan>/*.md`, set
+   `active.md` = `# <plan-id>`, run `node .rafa/bin/rafa-compile.mjs` to exit 0, offer
+   `rafa push` (the plan becomes resumable from any session/machine via the platform).
+
+## `build` — execute the active plan, trio-choreographed
+Per [`.rafa/capabilities/build.md`](../../.rafa/capabilities/build.md). Resume from `active.md`
+(or the platform's `get_active_plan` when connected) — never re-derive context.
+Per task: **atlas** recalls + implements → **prism** validates against the child's
+`## Done-check` (**`status: done` only on prism PASS**; FAIL → atlas corrects) → **bloom**
+sweeps (new opportunities → ledger files; fixed-in-passing → `status: fixed`; one opt-in
+nudge max) → update the child file's `status` → periodically compile + push so the platform
+reflects live progress. If execution invalidates/creates brain knowledge, run a **full
+`## scan`** (v1 rule — never hand-edit brain files around the gate). When all children are
+done: prism-style final verify, set `active.md` = `# No active plan`, compile + push.
+
 ## `push` — (re-)push the brain to the brain remote
 `node .rafa/bin/rafa-push.mjs` — commit `.rafa/` and push to `origin` (the brain repo) with the
 dev's own git auth. Use after a scan, or to re-sync a brain that changed.
@@ -100,13 +132,56 @@ understood to be rewritten correctly — need intelligence, and that's this comm
    on the dev's approval, `rafa push` if this is a connected repo.
 Never hand-edit around a migration or discard tuned files.
 
-## (no argument, or unrecognized)
-`/rafa` runs the in-editor passes: `init` · `scan [--brain-only]` · `improve` · `push` ·
-`leverage` · `migrate` · `update`.
+## `help` (also: no argument, or an unrecognized command)
+Print this reference verbatim and stop.
+
+**End to end — from zero to a queryable, working brain:**
+
+1. **Platform** — sign in → add a GitHub token → add brain repo + code repo → connect →
+   *Generate setup command* (15-min URL carrying a one-time MCP agent key).
+2. **Install** — in the code repo: `npx @rafinery/cli init '<setup-url>'` — vendors the
+   blueprint, wires the brain remote, registers the knowledge MCP in `.mcp.json`
+   (secret-free) + puts the key in `.claude/settings.local.json` (gitignored).
+3. **Scan** — restart Claude Code → `/rafa scan` (atlas maps → prism validates → bloom
+   ledgers) → `rafa push` → webhook → the platform ingests the manifest.
+4. **See it** — platform repo pages: Overview · Brain · Improvements · Plans; *Agent
+   access* mints keys for more MCP clients (Slack, incident.io, CI).
+5. **Work** — `/rafa plan "<intent>"` (prism-validated, brain-grounded) → `/rafa build`
+   (atlas executes, prism gates each Done-check, bloom sweeps); every push syncs
+   progress so any session/teammate resumes exactly where work stopped.
+6. **Query** — any MCP client with a key reads the brain at `<platform>/api/mcp`:
+   `get_brain_status` · `search_knowledge` · `get_rule/playbook/improvement` ·
+   `get_plan` · `get_active_plan`. Read-only, cited, per-repo scoped.
+
+**rafa has two surfaces.** `/rafa <cmd>` runs the intelligent, in-editor passes; the terminal
+`rafa` CLI (run via `npx @rafinery/cli@latest <cmd>`) does the deterministic plumbing. Several
+names exist on both — the CLI does the mechanical half, `/rafa` the intelligent half.
+
+**`/rafa` — in the editor (LLM does the work):**
+| Command | What it does |
+|---|---|
+| `/rafa init` | First run: ensure structure, then run the full scan pass. |
+| `/rafa scan [--brain-only]` | The full pass: know → verify → improve → push. `--brain-only` stops after the brain is validated (a cheap knowledge refresh). |
+| `/rafa improve` | The improvement pass — bloom writes a cited, prioritized (P0–P3) ledger. |
+| `/rafa plan <intent>` | Trio planning: atlas drafts (brain-grounded, contract §7 files, Done-checks), bloom pulls blast-radius improvements, prism validates the plan — then approval, compile, push. |
+| `/rafa build` | Execute the active plan: per task atlas implements → prism gates `done` on the Done-check → bloom sweeps the ledger; compile + push progress as you go. |
+| `/rafa push` | (Re-)push the brain to the brain remote (your git auth). |
+| `/rafa leverage` | Tune your toolbox: reason over config and, on approval, apply fixes exactly — merge settings, wire an MCP, scaffold a skill. |
+| `/rafa migrate` | Semantic migration — rewrite plans to a new schema preserving meaning, then compile-gate. |
+| `/rafa update` | The brain-side of an upgrade: after the CLI syncs the blueprint, run the migrations that need intelligence (re-scan a stale brain / rewrite plans). |
+
+**`rafa` — in the terminal (`npx @rafinery/cli@latest <cmd>`; deterministic):**
+| Command | What it does |
+|---|---|
+| `init [<setup-url>]` | Vendor the blueprint into the repo (+ wire the brain remote from a platform setup URL). |
+| `update [--overwrite\|--keep]` | Blueprint-side of an upgrade: re-sync the blueprint (asks before overwriting files you tuned), run mechanical migrations, and report what the brain needs next. |
+| `compile` | Run the contract gate → `.rafa/manifest.json`. |
+| `push` | Compile, then push `.rafa/` to the brain remote. |
+| `leverage` | Detect toolbox gaps (deterministic) and print prioritized tips — the detector for `/rafa leverage`. |
+| `migrate` | Run the mechanical (deterministic) migrations. |
 
-`compile` is a **terminal** command on the `rafa` CLI (`@rafinery/cli`) — not a slash command.
-If the dev typed it, don't error out; point them to the shell (`rafa compile`) and stop. For
-anything else unrecognized, print this usage line and stop.
+If the dev typed a **terminal-only** command (`compile`) as a slash command, point them to the
+shell (`rafa compile`) as well. Then stop.
 
 ---
 Token discipline: glob/grep/AST before reading; scoped reads; deterministic extraction

package/blueprint/.rafa/bin/rafa-compile.mjs

@@ -324,6 +324,90 @@ function compileCoverage() {
   return { domains };
 }
 
+// Plans (contract §7): parent+child files under plans/**. Global id uniqueness,
+// parent/child cross-checks, progress never stored, active.md → activePlanId.
+function compilePlans() {
+  const plans = [];
+  const seen = new Map(); // id → path (global uniqueness across plans/**)
+  for (const path of walk(join(ROOT, "plans"))) {
+    const name = path.split("/").pop();
+    const { data, error } = parseFrontmatter(read(path));
+    if (error) {
+      fail(path, "frontmatter", error);
+      continue;
+    }
+    checkVersion(data, path);
+    const id = checkId(data, path, name);
+    if (seen.has(id))
+      fail(path, "id", `duplicate plan id "${id}" (also ${seen.get(id)}) · ids are globally unique across plans/**`);
+    seen.set(id, path);
+    if ("progress" in data)
+      fail(path, "progress", "never stored · parent progress is derived by counting children");
+    const kind = reqEnum(data, "kind", ["parent", "child"], path);
+    const plan = reqStr(data, "plan", path);
+    const status = data.status;
+    if (kind === "child") {
+      if (!isEnum(status, ["todo", "in-progress", "done", "blocked"]))
+        fail(path, "status", "required (child) · todo|in-progress|done|blocked");
+      if (data.parent !== plan)
+        fail(path, "parent", `must equal plan "${plan}" for a child (flat v1)`);
+    } else {
+      if (data.parent !== null && data.parent !== "null")
+        fail(path, "parent", "must be null for kind: parent");
+      if (plan !== id) fail(path, "plan", `must equal id "${id}" for kind: parent`);
+      if (
+        status !== undefined &&
+        !isEnum(status, ["todo", "in-progress", "done", "blocked"])
+      )
+        fail(path, "status", "optional (parent) · todo|in-progress|done|blocked");
+    }
+    plans.push({
+      id,
+      plan,
+      parent: kind === "parent" ? null : plan,
+      kind,
+      title: reqStr(data, "title", path),
+      ...(isEnum(status, ["todo", "in-progress", "done", "blocked"])
+        ? { status }
+        : {}),
+      ...(typeof data.branch === "string" && data.branch !== ""
+        ? { branch: data.branch }
+        : {}),
+      ...(typeof data.baseSha === "string" && data.baseSha !== ""
+        ? { baseSha: String(data.baseSha) }
+        : {}),
+      path: rel(path),
+    });
+  }
+  // Cross-check: every child's plan resolves to a kind:parent in this compile.
+  const parents = new Set(plans.filter((p) => p.kind === "parent").map((p) => p.id));
+  for (const p of plans)
+    if (p.kind === "child" && !parents.has(p.plan))
+      fail(p.path, "plan", `no parent plan "${p.plan}" in this compile (dangling child)`);
+  return plans;
+}
+
+// active.md (generated pointer) → activePlanId. First line `# <plan-id>` must
+// resolve to a kind:parent plan; `# No active plan` or a missing file → null
+// (documented default: the pointer is generated, absence means "none").
+function compileActivePlanId(plans) {
+  const path = join(ROOT, "active.md");
+  if (!existsSync(path)) return null;
+  const first = read(path).split("\n")[0].trim();
+  const m = first.match(/^#\s+(.+)$/);
+  if (!m) {
+    fail(path, "pointer", 'first line must be "# <plan-id>" or "# No active plan"');
+    return null;
+  }
+  const val = m[1].trim();
+  if (/^no active plan$/i.test(val)) return null;
+  if (!plans.some((p) => p.kind === "parent" && p.id === val)) {
+    fail(path, "pointer", `active plan "${val}" is not a kind:parent plan in this compile`);
+    return null;
+  }
+  return val;
+}
+
 // ── assemble ─────────────────────────────────────────────────────────────────
 const gitOpts = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }; // no stderr leak
 function gitSha() {
@@ -349,6 +433,8 @@ const improvements = compileImprovements(join(ROOT, "improve", "improvements"));
 const health = compileHealth();
 const ledger = compileLedger();
 const coverage = compileCoverage();
+const plans = compilePlans();
+const activePlanId = compileActivePlanId(plans);
 
 // Cross-check: ledger.open / by_priority must match the actual open improvements.
 if (ledger) {
@@ -380,11 +466,13 @@ const manifest = {
   coverage,
   notes,
   improvements,
-  plans: [],
+  activePlanId,
+  plans,
 };
 writeFileSync(join(ROOT, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
 console.log(
   `✓ rafa compile: ${notes.length} notes · ${improvements.length} improvements · ` +
+    `${plans.length} plans${activePlanId ? ` (active: ${activePlanId})` : ""} · ` +
     `health ${health ? "ok" : "—"} · ledger ${ledger ? "ok" : "—"} · ` +
     `coverage ${coverage ? `${coverage.domains.length} domains` : "—"} → .rafa/manifest.json`,
 );

package/blueprint/.rafa/capabilities/build.md

@@ -1,38 +1,39 @@
-# build — execute, brain-aware, compounding  (DRAFT · capability #4)
+# build — execute the plan, trio-choreographed, compounding  (capability #4)
 
-> Status: **draft / spec.** The work-time loop where **recall + nudge + capture-back** all
-> fire — the mission payoff. Depends on: plan (#3), brain (#1), ledger (#2). Built last.
+> Status: **active.** The work-time loop where recall + validation + improvement all
+> fire — the mission payoff. Depends on: plan (#3), brain (#1), ledger (#2).
+> Invoke via `/rafa build`.
 
-Execute the approved plan with both stores in the loop. Invoke via `/build`.
+Execute the approved plan with all three agents in the loop, knowledge served by the
+platform MCP (one read path — the same surface any third-party agent uses).
 
-## Why build fits the mission (the flywheel closes here)
+## The trio at build time
 
-Each task both **spends** the stores and **feeds** them — the compounding made real:
+| Role | Agent | Job per task |
+|---|---|---|
+| **Executor** | atlas | RECALL the task's brain slice via MCP (`search_knowledge` + `get_rule`/`get_playbook`; honor non-exemplars) → implement, convention-adherent |
+| **Validator** | prism | validate the execution against the child's `## Done-check` — strict, unbiased, against code + brain, never against atlas's claims. **`status: done` only on prism PASS**; FAIL → atlas corrects (validate-and-correct at work time). This gate is conductor-flow SOP — deterministic enforcement is the deferred capture-engine's job |
+| **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed`. **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
 
-- **RECALL** — per task, load the brain slice for the touched domains: follow
-  conventions/contracts; honor **non-exemplars** (don't pattern-match the salient-but-wrong
-  example — the audit showed a cold agent paying a 100K-token correction loop for exactly this).
-- **NUDGE** — surface the top-leverage open improvement in the task's blast radius: *"10-min fix
-  while you're here?"* Dismissible, never blocking. (bloom's deferred nudge, finally firing.)
-- **LEVERAGE (orchestrate, don't bury)** — before hand-rolling a task, surface the best-fit
-  existing capability (skill/tool/MCP — committed or the dev's personal) to the host, and any
-  config that would help it fire. Recommend; the host orchestrates. Never reinvent what's present.
-- **CAPTURE-BACK** — as work lands:
-  - decisions / scars → propose brain notes (**prism-validated** before they enter the brain),
-    **tool-agnostic** — capture *what + why + cited code*, never which (possibly personal) skill produced it,
-  - improvements fixed in passing → improve ledger **auto-close** (`status: fixed`),
-  - touched code → **incremental re-scan** of that domain so the brain stays fresh.
+## Procedure
 
-## Procedure (draft)
-1. Resume from `active.md` (plan + active task).
-2. Per task: **recall** brain slice → implement (convention-adherent) → **nudge** a
-   blast-radius fix (opt-in) → done-check.
-3. **Capture-back**: distill decisions/scars (prism-validated); auto-close fixed improvements;
-   re-scan the touched domain.
-4. Verify (prism-style) before declaring done. Update `active.md`.
+1. **Resume** — `get_active_plan` (platform) or local `active.md`; staleness check
+   (envelope `brainForSha` vs local stamp → prompt `rafa push` if behind).
+2. **Per task:** atlas recalls → implements → prism validates vs `## Done-check` →
+   bloom sweeps (push new / close fixed / nudge) → update the child file's `status`
+   → periodic `rafa compile` + `rafa push` so the platform (and every MCP consumer)
+   reflects live progress.
+3. **Brain changes mid-build** — execution may invalidate rules or teach new ones.
+   v1: run a full `/rafa scan` (regenerate → prism → compile → push); the whole
+   brain re-stamps at the new sha, so `brain = f(code@sha)` stays exact. NEVER
+   hand-edit brain files around the gate.
+4. **Verify** (prism-style) before declaring the plan done; final compile + push.
 
 ## Deferred / open
-- **The capture engine** — `Stop`/`PostToolUse` hooks to make capture-back *automatic*, not
-  model-discretion (the deterministic-enforcement lesson, applied to capture).
-- **Incremental re-scan** — changed files + seam-neighbors only (keep it cheap).
+- **The capture engine** — `Stop`/`PostToolUse` hooks making the gates + capture
+  automatic rather than conductor-driven SOP (deterministic-enforcement lesson).
+- **Incremental re-scan** — cite-graph invalidation (diff → invalidate notes citing
+  changed files → re-verify/regenerate only those). Needs: partial-brain cache-key
+  semantics + the seam-neighbor scope rule. Designed (see
+  .fable/sessions/2026-07-07-brain-versioning-and-incremental.md); first post-loop item.
 - Show-thinking + pivot protocol from the atlas character.

package/blueprint/.rafa/capabilities/plan.md

@@ -1,38 +1,47 @@
-# plan — brain-grounded ADR decomposition  (DRAFT · capability #3)
-
-> Status: **draft / spec.** The first *consumer* of the stores — where the brain starts to pay
-> off. Depends on: brain (#1), ledger (#2). Built after the stores are proven in real use.
-
-Turn an intent into an approval-gated **ADR plan**, *grounded* in the brain (don't re-derive)
-and *aware* of the ledger (fold improvement into the work). Invoke via `/plan <intent>`.
-
-## Why plan fits the mission (the integration)
-
-plan is the first place knowledge + improvement meet real work, all keyed on **domain**:
-
-- **RECALL** — load the brain slice for the domains the intent touches: conventions,
-  contracts, flows, and **non-exemplars** (don't copy the grandfathered demo — the audit's
-  exact lesson). The plan starts from known ground, not a cold read. *This is the 100×.*
-- **BLAST RADIUS** — name the domains/nodes the change touches (from the brain's map), so risk
-  is known up front and `build` can recall/nudge per task.
-- **NUDGE** — query the improve ledger for open improvements in that blast radius; surface the
-  **top-leverage** ones as optional *"while-you're-here"* tasks (leverage-ranked, dismissible).
-- **LEVERAGE (orchestrate, don't bury)** — match the intent against available capabilities
-  (committed skills/agents/MCP **+** the dev's personal ones, discovered live) and recommend the
-  best-fit to the host: *"there's a `tdd-workflow` skill for this — use it."* Never plan to
-  hand-roll what a capability already does; flag config that would help. Recommend; the host
-  orchestrates (a hook can't auto-invoke).
-
-## Procedure (draft)
-1. **Recall** the brain slice for the intent's domains (notes + contracts + non-exemplars).
-2. **Decompose** ADR: decision + rationale + alternatives + tradeoffs + risk surface + non-goals.
-3. **Tasks** — each bound to domains/nodes (so `build` can recall + nudge per task) with a done-check.
-4. **Ledger nudge** — surface open improvements in the blast radius as optional, leverage-ranked tasks.
-4b. **Leverage-match** — recommend the existing skills/tools/MCP that fit the tasks; flag tooling-fit
-    improvements. Don't plan to reinvent a present capability.
-5. **Approval gate** (ExitPlanMode). Materialize `.rafa/plans/<id>.md` + `active.md → {plan, task:1}`.
+# plan — brain-grounded, prism-validated decomposition  (capability #3)
+
+> Status: **active.** The first *consumer* of the stores — where the brain starts to
+> pay off. Depends on: brain (#1), ledger (#2). Invoke via `/rafa plan <intent>`.
+
+Turn an intent into an approval-gated plan (contract §7 files), *grounded* in the
+brain (don't re-derive), *aware* of the ledger (fold improvement into the work), and
+**validated by prism before the owner ever sees it**.
+
+## The trio at plan time
+
+Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
+
+- **atlas drafts** — RECALL the brain slice for the intent's domains through the
+  knowledge MCP (`get_coverage` to navigate → `search_knowledge` → `get_rule` /
+  `get_playbook`, including non-exemplars), name the BLAST RADIUS from coverage,
+  decompose into parent + child plan files.
+- **bloom pulls** — `list_improvements` in the blast radius; surface the
+  top-leverage open items as optional *"while-you're-here"* child tasks
+  (leverage-ranked, dismissible, never blocking).
+- **prism validates the plan itself** — before the approval gate: is every task
+  grounded in real brain/code (not hallucinated ground)? does every child carry a
+  `## Done-check` (the expected outcome prism will validate execution against)?
+  A plan whose children lack Done-checks is REJECTED here — compile never parses
+  bodies (invariant #3); this gate is prism's.
+
+## Procedure
+
+1. **Staleness check** — compare the platform envelope's `brainForSha` against the
+   local brain stamp; if the platform is behind, surface "run `rafa push`" (never
+   proceed silently on knowledge you know is stale — never block either).
+2. **Recall** (atlas, via MCP) → **decompose** ADR-style: decision + rationale +
+   alternatives + risk surface + non-goals; tasks bound to domains with a
+   `## Done-check` each.
+3. **Ledger pull** (bloom) → optional leverage tasks in the blast radius.
+4. **Leverage-match** — recommend existing skills/tools/MCP that fit the tasks;
+   never plan to hand-roll what a capability already does.
+5. **prism plan-validation** → REJECT/fix loop until clean.
+6. **Approval gate** (owner). Then materialize `plans/<plan>/*.md` per contract §7
+   (parent + child-owned files, globally-unique prefixed ids) + `active.md` pointer
+   → `rafa compile` → `rafa push` (the plan is now resumable from ANY session,
+   machine, or teammate via `get_active_plan`).
 
 ## Deferred / open
-- Capture-back of plan-time decisions → brain (prism-validated) — needs the capture engine (hooks).
-- Pivot detection (conversation-as-steering; mark superseded, the path is data).
-- Plan lifecycle + tiering (cap, archive→remote, restore) — designed in `.arohi/architecture.md`.
+- Capture-back of plan-time decisions → brain (needs the capture engine).
+- Pivot detection (mark superseded; the path is data).
+- Plan lifecycle + tiering (cap, archive→remote, restore).

package/blueprint/.rafa/contract.md

@@ -37,10 +37,10 @@ doesn't validate, compile fails.
 | coverage | `brain/coverage.md` | **structured** | §6 | atlas |
 | improvement | `improve/improvements/*.md` | **structured** | §3 | bloom |
 | ledger | `improve/ledger.md` | **structured** | §5 | bloom |
-| plan | `plans/**/*.md` | **structured** | §7 *(wired: Slice 4)* | plan/build |
+| plan | `plans/**/*.md` | **structured** | §7 | plan/build |
 | log | `brain/log.md` | **verbatim** | — (prose trail) | conductor |
 | citation-check | `**/citation-check.md` | **generated** | — (by `verify-citations`) | tool |
-| active pointer | `active.md` | **generated** | — (`# <plan-id>` or "No active plan") | conductor |
+| active pointer | `active.md` | **generated** | — (`# <plan-id>` or "No active plan"; compile emits it as `activePlanId`, §7) | conductor |
 | blueprint | `capabilities/*`, `bin/*`, `contract.md` | **verbatim** | — (shipped SOPs/tools) | rafa |
 
 `structured` types are compiled into `manifest.json` (§1) — that JSON is the ONLY thing the
@@ -157,7 +157,20 @@ JSON. This is the exact shape the platform binds to.
     }
   ],
 
-  "plans": []                               // v1: may be empty; shape in §6
+  "activePlanId": null,                     // from active.md: plan id, or null
+  "plans": [
+    {
+      "id": "multitenant",                  // == filename stem, globally unique
+      "plan": "multitenant",                // the parent plan id
+      "parent": null,                       // parent plan id, or null for the root
+      "kind": "parent",                     // "parent" | "child"
+      "title": "…",
+      "status": "in-progress",              // omitted when absent (parent may omit)
+      "branch": "feat/mt-c1",               // omitted when absent
+      "baseSha": "abc123",                  // omitted when absent
+      "path": "plans/multitenant/multitenant.md"   // prose body (lazy fetch)
+    }
+  ]
 }
 ```
 
@@ -265,7 +278,7 @@ domains: { design-system: mapped, components: mapped, api: thin, external-integr
 
 ---
 
-## 7. Plan files — `plans/**/*.md` (Slice 4)
+## 7. Plan files — `plans/**/*.md`
 
 Each child owns exactly one file (so merges never conflict; parent progress is
 derived by counting).
@@ -273,19 +286,36 @@ derived by counting).
 ```yaml
 ---
 schemaVersion: 1
-id: c1-schema                    # required · == filename stem
+id: multitenant-c1-schema        # required · == filename stem · GLOBALLY unique across plans/**
 plan: multitenant                # required · the parent plan id
-parent: null                     # required · parent plan id, or null for the root
+parent: multitenant              # required · parent plan id (child), or null (root)
 kind: parent | child             # required
 title: …                         # required
 status: todo | in-progress | done | blocked   # required (child); parent may omit
 branch: feat/mt-c1               # optional · the branch this executes on
 baseSha: abc123                  # optional · commit it was cut from
 ---
+（prose body — for a child it MUST contain a `## Done-check` section: the expected
+outcome prism validates execution against. Compile never parses bodies; a missing
+Done-check is rejected by prism's PLAN validation, not by compile.）
 ```
 
-Parent progress is `count(children where status == done) / count(children)` —
-derived, never stored.
+Rules (all compile-enforced unless noted):
+
+- **Global id uniqueness.** `plans/**` is nested, so stems could collide; a duplicate
+  plan id anywhere under `plans/` is a compile error. Convention: prefix children
+  with the plan id (`<plan>-c1-….md`).
+- **`kind: parent`** → `parent` MUST be `null` and `plan` MUST equal `id`.
+- **`kind: child`** → `plan` MUST resolve to a `kind: parent` file in the same
+  compile, and `parent` MUST equal `plan` (flat parent→children in v1). A dangling
+  child is a loud error; a parent with zero children is valid (a plan just created).
+- **Progress is never stored.** A `progress` key in plan frontmatter is a compile
+  error. Parent progress is `count(children where status == done) / count(children)`
+  — derived at read time, everywhere (compile, platform, MCP).
+- **`active.md` → `activePlanId`.** Compile reads the generated pointer: a first line
+  `# <plan-id>` must resolve to a `kind: parent` plan (else compile error);
+  `# No active plan` or a missing `active.md` → `activePlanId: null` (documented
+  default — the pointer is generated, absence means "none", never a guess of one).
 
 ---
 
@@ -300,4 +330,67 @@ derived, never stored.
   blocks the push (better than a silently-wrong brain).
 - The validator **reports, never auto-fills** a required value.
 
+---
+
+## 9. The read side — knowledge MCP (platform-served)
+
+The platform serves the **ingested** brain to any MCP client (the build agent, a
+teammate's session, Slack/incident.io agents) — the read-side twin of this contract.
+One backend: the platform. Local files are the *authoring* surface; the platform is
+the *serving* surface, and it serves only what passed compile + ingest.
+
+**Envelope — mandatory on every tool response:**
+
+```jsonc
+{
+  "source": "platform",
+  "brainForSha": "<snapshot codeSha>",   // the ingested manifest's codeSha — one source
+  "ingestedAt": "<ISO time of ingest>",
+  "schemaVersion": 1,
+  "synthesized": false                   // raw tools: always false
+}
+```
+
+**Error semantics (no assumed values, outward):** snapshot has an `ingestError` →
+every tool returns that error loudly, never partial data. Repo connected but never
+pushed (no snapshot) → `"no brain ingested — run rafa push"`. Invalid/mismatched key
+→ loud auth error, never a fallback. Empty search → empty result, never a stretched
+match.
+
+**Tools (read-only — ALL writes flow files → compile → push → ingest):**
+
+| Tool | Args | Returns |
+|---|---|---|
+| `get_brain_status` | `repo` | envelope + per-type counts, health, coverage summary, `activePlanId`, `ingestError?` |
+| `get_coverage` | `repo` | coverage rows (the domain map — how an agent navigates) |
+| `search_knowledge` | `q`, `types?`, `domain?`, `limit?` | ranked candidates (fields per type below) |
+| `get_rule` / `get_playbook` / `get_improvement` | `repo`, `id` | full frontmatter + lazy-fetched body + cites as objects |
+| `list_improvements` | `repo`, `status?`, `priority?`, `domain?` | ledger rows |
+| `get_plan` | `repo`, `id` (parent or child) | parent + all children + **derived** progress; a child id resolves the whole plan with `requestedChild` set |
+| `get_active_plan` | `repo` | resolves manifest `activePlanId` → `get_plan`, or "no active plan" |
+
+`repo` must match the key's scope exactly; `branch` is reserved (branch-keyed
+instances land in Slice 2 — third-party clients default to the production brain,
+i.e. the default branch's instance).
+
+**Search = deterministic lexical retrieval; the server retrieves, the agent decides.**
+Fields searched per type — rule/playbook: `title, summary, domain, type` ·
+improvement: `title, summary, lens, blast_radius` · plan: `title, plan, parent`.
+Score = Σ over matched case-folded query tokens of field weight (`title` 3 ·
+`domain`/`lens`/`blast_radius`/`type`/`plan`/`parent` 2 · `summary` 1); tie-break
+score desc then id asc; fields a type lacks are omitted, never defaulted. Candidates
+carry `matchKind: "lexical"` (`"semantic"` reserved). `ask_knowledge` is a reserved
+tool id for the synthesis layer (responses will carry `synthesized: true`).
+
+**Auth:** per-repo machine keys, minted on the platform, sent as
+`Authorization: Bearer`. Keys are stored hashed platform-side and live client-side in
+`~/.config/rafinery/credentials.json` — never inside the code repo or this brain repo.
+
+**Client wiring (written by `rafa init`, secret-free where committed):** a key is
+minted at setup generation and delivered consume-once through the setup fetch;
+`.mcp.json` (committed) registers the `rafinery` server with
+`Authorization: Bearer ${RAFA_MCP_KEY}` env expansion; the raw key lands in
+`.claude/settings.local.json` `env` (gitignored) and `~/.config/rafinery/credentials.json`
+(0600). Teammates mint their own key on the platform (repo → Agent access).
+
 This contract is the thing to test against.

package/lib/blueprint.mjs

@@ -10,6 +10,7 @@ import {
   readFileSync,
   readdirSync,
   statSync,
+  rmSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -97,39 +98,67 @@ function sameBytes(a, b) {
 }
 
 // Copy the blueprint from `from` into `to`.
-//  - mode "vendor" (default): non-destructive. lockstep files overwrite; owned files are
-//    created if absent, left untouched if identical, and preserved (writing `<file>.new`)
-//    if the dev has changed them — we never clobber tuning.
+//  - mode "vendor" (default): non-destructive. lockstep files (tools + contract) overwrite;
+//    owned files are created if absent, left untouched if identical, and — if the dev has
+//    changed them — resolved via `onConflict(rel)` which returns "overwrite" | "keep"
+//    (shadcn-style: ask before clobbering). No `.new` files; any stale `.new` left by an older
+//    CLI is cleaned up.
 //  - mode "bundle": force-copy everything (building the package tarball into a scratch dir).
-// Returns { created, updated, unchanged, preserved } — arrays of relative paths.
-export function copyBlueprint(from, to, { mode = "vendor" } = {}) {
+// Returns { created, updated, unchanged, kept, cleaned, errors } — arrays of relative paths.
+export async function copyBlueprint(from, to, { mode = "vendor", onConflict } = {}) {
   const { owned, lockstep } = blueprintFiles(from);
-  const report = { created: [], updated: [], unchanged: [], preserved: [] };
+  const report = { created: [], updated: [], unchanged: [], kept: [], cleaned: [], errors: [] };
 
-  const put = (rel, isOwned) => {
+  // Remove a stale `<dst>.new` written by an older CLI — it's our own debris, now obsolete.
+  const dropStaleNew = (rel, dst) => {
+    const stale = `${dst}.new`;
+    if (existsSync(stale)) {
+      try {
+        rmSync(stale);
+        report.cleaned.push(`${rel}.new`);
+      } catch {
+        /* leave it; not worth failing the update over */
+      }
+    }
+  };
+
+  const put = async (rel, isOwned) => {
     const src = join(from, rel);
     if (!existsSync(src)) return;
     const dst = join(to, rel);
-    mkdirSync(dirname(dst), { recursive: true });
-    if (!existsSync(dst)) {
-      cpSync(src, dst);
-      report.created.push(rel);
-      return;
-    }
-    if (sameBytes(src, dst)) {
-      report.unchanged.push(rel);
-      return;
-    }
-    if (mode === "bundle" || !isOwned) {
-      cpSync(src, dst); // lockstep, or a scratch bundle: safe to overwrite
-      report.updated.push(rel);
-    } else {
-      cpSync(src, `${dst}.new`); // owned + modified: keep the dev's copy, offer .new
-      report.preserved.push(rel);
+    try {
+      mkdirSync(dirname(dst), { recursive: true });
+      if (!existsSync(dst)) {
+        cpSync(src, dst);
+        report.created.push(rel);
+        return;
+      }
+      if (sameBytes(src, dst)) {
+        dropStaleNew(rel, dst);
+        report.unchanged.push(rel);
+        return;
+      }
+      // exists AND differs
+      if (mode === "bundle" || !isOwned) {
+        cpSync(src, dst); // lockstep, or a scratch bundle: moves with the CLI
+        report.updated.push(rel);
+      } else {
+        // owned + modified: ask before clobbering the dev's tuning (default: keep).
+        const decision = onConflict ? await onConflict(rel) : "keep";
+        if (decision === "overwrite") {
+          cpSync(src, dst);
+          report.updated.push(rel);
+        } else {
+          report.kept.push(rel);
+        }
+      }
+      dropStaleNew(rel, dst);
+    } catch (e) {
+      report.errors.push(`${rel}: ${e instanceof Error ? e.message : e}`);
     }
   };
 
-  for (const rel of lockstep) put(rel, false);
-  for (const rel of owned) put(rel, true);
+  for (const rel of lockstep) await put(rel, false);
+  for (const rel of owned) await put(rel, true);
   return report;
 }

package/lib/init.mjs

@@ -11,18 +11,54 @@ import { execSync } from "node:child_process";
 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";
+
+// Decide what to do when an owned file the dev may have tuned already exists and differs.
+// shadcn-style: ask before clobbering. Honors `--overwrite`/`-o` (yes to all) and `--keep`
+// (no to all); in a non-TTY (CI / agent shell) it defaults to KEEP so it never blocks or clobbers.
+export function makeConflictResolver(args = []) {
+  const force = args.includes("--overwrite") || args.includes("-o");
+  const keepAll = args.includes("--keep");
+  const interactive = isInteractive();
+  let all = false; // overwrite everything remaining
+  let quit = false; // keep everything remaining
+  return async (rel) => {
+    if (force || all) return "overwrite";
+    if (keepAll || quit || !interactive) return "keep";
+    const a = await ask(
+      `  • ${rel} exists and differs — overwrite? [y = yes · N = keep · a = all · q = keep rest] `,
+    );
+    if (a === "a") {
+      all = true;
+      return "overwrite";
+    }
+    if (a === "q") {
+      quit = true;
+      return "keep";
+    }
+    return a === "y" || a === "yes" ? "overwrite" : "keep";
+  };
+}
 
-// One-line summary of a copyBlueprint report; notes preserved (un-clobbered) files.
+// One-line summary of a copyBlueprint report + per-file notes for kept/cleaned/errored files.
 export function reportBlueprint(r) {
   const n = (a) => a.length;
   console.log(
     `  ✓ blueprint: ${n(r.created)} new · ${n(r.updated)} updated · ` +
-      `${n(r.unchanged)} unchanged · ${n(r.preserved)} preserved`,
+      `${n(r.unchanged)} unchanged · ${n(r.kept)} kept`,
   );
-  for (const rel of r.preserved)
-    console.log(`    • kept your ${rel} — latest written to ${rel}.new (merge by hand)`);
+  for (const rel of r.kept)
+    console.log(`    • kept your ${rel}  (re-run with --overwrite to replace, or /rafa update to merge)`);
+  for (const rel of r.cleaned) console.log(`    • removed stale ${rel}`);
+  for (const err of r.errors) console.log(`    ! ${err}`);
 }
 
 // Union rafa's required permissions into .claude/settings.json without clobbering it.
@@ -69,19 +105,58 @@ export default async function init(args) {
   }
 
   // Vendor the blueprint into .claude/ + .rafa/ (you own these copies) — non-destructive:
-  // owned files (agents, capabilities) are never clobbered, tools/contract move in lockstep.
-  reportBlueprint(copyBlueprint(blueprintSource(), TARGET));
+  // tools/contract move in lockstep; owned files (agents, capabilities) prompt before overwrite.
+  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).
   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`
@@ -113,9 +188,15 @@ export default async function init(args) {
 
   console.log(
     `\n✓ Provisioned.\n\nNext steps:\n` +
-      "  1. Restart Claude Code in this repo (reload the /rafa command + agents).\n" +
+      "  1. Restart Claude Code in this repo (reload the /rafa command + agents" +
+      (p?.mcpUrl ? " + the rafinery MCP server" : "") +
+      ").\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.",
+      "  3. Open the repo on the rafinery platform — its Overview shows the brain once pushed." +
+      (p?.mcpUrl
+        ? "\n  4. 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/mcp-config.mjs

@@ -0,0 +1,93 @@
+// MCP wiring for `rafa init` — connect the client repo to the platform's
+// knowledge MCP (.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/prompt.mjs

@@ -0,0 +1,21 @@
+// Minimal interactive prompt helpers. Used to ask before overwriting a file the dev owns —
+// shadcn-style — instead of silently writing `.new` clutter.
+
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+// True only when we can actually prompt (both ends are a TTY). In a pipe / CI / an
+// agent-spawned shell we must NOT block on input — callers fall back to a safe default.
+export function isInteractive() {
+  return Boolean(stdin.isTTY && stdout.isTTY);
+}
+
+// Ask a free-form question, return the trimmed lowercased answer ("" if the dev just hits enter).
+export async function ask(question) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    return (await rl.question(question)).trim().toLowerCase();
+  } finally {
+    rl.close();
+  }
+}

package/lib/releases.mjs

@@ -46,6 +46,29 @@ export const RELEASES = [
       "blueprint migrations and reports what the brain needs; new `/rafa update` does the brain-side " +
       "migrations (re-scan / rewrite). `rafa update` now prints release notes + required actions.",
   },
+  {
+    version: "0.2.2",
+    contract: 1,
+    plans: 1,
+    requires: "update",
+    summary:
+      "shadcn-style overwrite prompt on init/update — asks before replacing files you tuned " +
+      "(no more `.new` clutter; stale `.new` cleaned up; --overwrite/--keep flags). New `/rafa help` " +
+      "with a full command reference for both surfaces. (Completes 0.2.1, published before these landed.)",
+  },
+  {
+    version: "0.3.0",
+    contract: 1,
+    plans: 1,
+    requires: "update",
+    summary:
+      "Knowledge MCP — the read side. `init` now wires the platform's read-only knowledge MCP: " +
+      "a secret-free `.mcp.json` entry (Bearer ${RAFA_MCP_KEY}), the per-dev key into gitignored " +
+      "`.claude/settings.local.json` + `~/.config/rafinery/credentials.json` (0600), delivered " +
+      "consume-once via the setup URL. Contract §9 (read-side tools + envelope) and §7 plans are " +
+      "wired: compile now emits `plans[]` + `activePlanId` with global-id/parent/progress rules. " +
+      "Re-run `/rafa scan` (or push) to surface plans in your manifest; no re-scan required to adopt.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/update.mjs

@@ -8,13 +8,13 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
-import { reportBlueprint, reportSettings } from "./init.mjs";
+import { reportBlueprint, reportSettings, makeConflictResolver } from "./init.mjs";
 import { CURRENT, CLI_VERSION, releasesAfter } from "./releases.mjs";
 import { stampedVersions, stampCurrent, stampCli } from "./stamp.mjs";
 import { pendingMigrations } from "./migrations/index.mjs";
 import { notifyIfBehind } from "./version-check.mjs";
 
-export default async function update() {
+export default async function update(args = []) {
   const TARGET = process.cwd();
   if (!existsSync(join(TARGET, ".rafa")) && !existsSync(join(TARGET, ".claude"))) {
     console.error("✗ This repo isn't provisioned yet — run `rafa init` first.");
@@ -27,7 +27,9 @@ export default async function update() {
   await notifyIfBehind();
 
   console.log("rafa update — syncing the blueprint (non-destructive)");
-  reportBlueprint(copyBlueprint(blueprintSource(), TARGET));
+  reportBlueprint(
+    await copyBlueprint(blueprintSource(), TARGET, { onConflict: makeConflictResolver(args) }),
+  );
   reportSettings(TARGET);
 
   // ── Blueprint-side migrations: mechanical/deterministic, run here in the CLI. ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {