@rafinery/cli 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -4,9 +4,39 @@ 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.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,
+no migration. Recommended: `/rafa leverage` to tune your toolbox.
+
+- **Intelligence where it belongs.** `leverage` and `migrate` are now `/rafa` commands: the CLI
+  *detects* (deterministic), the LLM *acts* — `/rafa leverage` edits your config exactly (merges
+  settings, wires the MCP, scaffolds a skill, on approval); `/rafa migrate` rewrites plans to a new
+  schema preserving meaning, then compile-gates them.
+- **Two-layer update — one job each, no double work.**
+  - `rafa update` (CLI) = the **blueprint side**: pulls the latest blueprint into your repo and runs
+    the blueprint/mechanical migrations. It prints the **release notes** since your version and
+    **exactly what the brain needs** next (computed from the contract/plans schema deltas).
+  - `/rafa update` (Claude Code) = the **brain side**: runs the migrations that need intelligence
+    (re-scan a stale brain, rewrite plans to a new shape). It does **not** re-run the CLI.
+- `/rafa` redirects the terminal-only `compile` instead of erroring on it.
+
 ## 0.2.0
 
-**Adopt with:** `npm i -g @rafinery/cli@latest && rafa update` — no re-scan, no migration.
+**Adopt with:** `npx @rafinery/cli@latest update` — no re-scan, no migration.
 Your brain data is still valid (contract v1, plans v1 unchanged).
 
 - **Non-destructive vendoring.** `init`/`update` never clobber tuned files: owned files

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

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

@@ -1,5 +1,5 @@
 ---
-description: rafa — init/scan (know + improve) · improve · push. Usage: /rafa <init|scan|improve|push> [--brain-only]
+description: rafa — init · scan · improve · push · leverage · migrate · update · help. Usage: /rafa <init|scan|improve|push|leverage|migrate|update|help> [--brain-only]
 ---
 
 You are the **conductor** of the rafa agent loop, running in the **main session**.
@@ -56,8 +56,80 @@ high-leverage P0/P1s — don't nag; the dev triages.**
 `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.
 
-## (no argument, or unrecognized)
-Print usage and stop: `/rafa init` · `/rafa scan [--brain-only]` · `/rafa improve` · `/rafa push`.
+## `leverage` — tune the dev's toolbox (rafa's 3rd mission; intelligence + exact edits)
+Detection is cheap and deterministic; **acting needs intelligence — that's why this is a
+`/rafa` command, not just the `rafa leverage` CLI.** The CLI *reports*; you *fix*.
+1. **Inspect** the committed toolbox: `.claude/settings.json`, `.mcp.json`, `.claude/skills/`,
+   `.claude/commands/`, and the stack (`package.json` / dirs). (`rafa leverage` gives the fast
+   deterministic signal; here you reason over the real files.)
+2. **Reason** per [`.rafa/capabilities/leverage.md`](../../.rafa/capabilities/leverage.md): what's
+   missing / misconfigured / unused — permission gaps, an MCP the stack needs but isn't wired, a
+   repeatable flow worth capturing as a skill, the best-fit *existing* skill for THIS repo. P1→P3.
+3. **Act — on the dev's approval, edit exactly.** Merge the precise permission entries, write the
+   correct `.mcp.json` server block, scaffold the skill. **Merge, never clobber** the dev's config;
+   show the diff. Propose, don't force. Never open `.env*` or read a secret value (scan's guardrail).
+
+## `migrate` — bring structured files to the current schema (the intelligent half)
+Two channels. **Mechanical** changes (field rename, path move) run deterministically via the
+terminal `rafa migrate`. **Semantic** changes — a plan's *shape* changed and each file must be
+understood to be rewritten correctly — need intelligence, and that's this command.
+1. Read the target schema in [`.rafa/contract.md`](../../.rafa/contract.md) (§6/§7 for plans) and
+   the `from` versions in `rafa.json`.
+2. For each affected file under `.rafa/plans/` (and any other structured dir), **rewrite it to
+   conform** — preserve meaning, remap fields, fill new required fields sensibly.
+3. Run `node .rafa/bin/rafa-compile.mjs` until it **exits 0** (validate-and-correct loop), surface
+   the diff for approval, then offer `rafa push` if this is a connected repo.
+
+## `update` — the BRAIN-side of an upgrade (the CLI already did the blueprint side)
+**Two layers, two actors — don't re-run the CLI here.**
+- The terminal **`npx @rafinery/cli@latest update`** already pulled the latest blueprint and ran
+  the **blueprint-side** (mechanical/structural) migrations. It also *reported* what the brain needs.
+- **`/rafa update` (this command)** does the **brain-side** migrations — the part that needs
+  intelligence — against the blueprint the CLI just installed. It does **not** pull the blueprint
+  or re-run the CLI.
+1. **Find the gap.** The brain/plans conform to a *data* version; the blueprint just moved to a
+   newer one. Compare `.rafa/manifest.json`'s `schemaVersion` (and `rafa.json`'s `contract`/`plans`)
+   to the current `.rafa/contract.md`. That gap is exactly what the CLI update flagged. (If the CLI
+   update hasn't run yet, tell the dev to run `npx @rafinery/cli@latest update` first, then return.)
+2. **Migrate the brain side:**
+   - **Contract bumped → the brain is a stale cache:** re-scan (`## scan`) to regenerate it, or for
+     a targeted change, intelligently rewrite the affected notes to the new schema and re-validate.
+   - **Plans shape changed:** rewrite each plan per `## migrate` (preserve meaning), compile to exit 0.
+3. **Record + summarize.** Run `node .rafa/bin/rafa-compile.mjs` to exit 0, then advance the data
+   version in `rafa.json` (`contract`/`plans` → the versions you migrated to). Summarize what changed;
+   on the dev's approval, `rafa push` if this is a connected repo.
+Never hand-edit around a migration or discard tuned files.
+
+## `help` (also: no argument, or an unrecognized command)
+Print this reference verbatim and stop.
+
+**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 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. |
+
+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/capabilities/leverage.md

@@ -6,8 +6,13 @@ config layer (permissions, skills, MCP servers, hooks, commands) that decides ho
 the AI engineer actually is. It surfaces what's missing, misconfigured, or unused, and points
 at the fix. This is platform DNA: **leverage what's present; never reinvent it.**
 
-Invoke via `rafa leverage` (CLI, reads the repo — no brain required). Advisory only: it reads,
-ranks, and reports; it **changes nothing**.
+**Two layers — detection is deterministic, action needs intelligence:**
+- **`rafa leverage`** (CLI) — the cheap **detector**. Reads the repo, ranks, and *reports*; it
+  **changes nothing**. Good for a notify/CI signal, and as structured input to the LLM.
+- **`/rafa leverage`** (in Claude Code) — the **actor**. rafa reasons over the real config and,
+  on the dev's approval, **applies the fix exactly** — merges the precise permission entries,
+  writes the correct `.mcp.json` block, scaffolds the skill. The CLI can't do this; only the
+  intelligence can edit correctly. The detector finds the gap; the LLM closes it.
 
 ---
 
@@ -21,8 +26,9 @@ ranks, and reports; it **changes nothing**.
    advisor. Few, relevant, dismissible.
 3. **Leverage-ranked** — `P1` security/correctness → `P2` friction/leverage → `P3` nice-to-have.
    Lead with impact × ease. Never dump an unranked wall.
-4. **Advisory, never authoritarian** — the dev owns their setup. Propose + show the fix; never
-   auto-apply. (`rafa init`/`update` apply the *permission* fixes, and only because the dev ran them.)
+4. **Approval-gated, never authoritarian** — the dev owns their setup. `rafa leverage` (CLI) only
+   proposes. `/rafa leverage` *applies*, but **only on the dev's approval and always as a merge** —
+   show the diff, never clobber, propose don't force.
 5. **Tool-agnostic by construction** — the advice engine knows nothing about any specific tool;
    all tool knowledge lives in an **adapter**. This is what makes "leverage what's available"
    true for Codex, Cursor, or any other toolchain, not just Claude Code.

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

@@ -13,16 +13,46 @@ import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
 import { mergeClaudeSettings } from "./claude-config.mjs";
 import { stampCurrent } from "./stamp.mjs";
 import { notifyIfBehind } from "./version-check.mjs";
+import { isInteractive, ask } from "./prompt.mjs";
 
-// One-line summary of a copyBlueprint report; notes preserved (un-clobbered) files.
+// 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 + 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,8 +99,10 @@ 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).

package/lib/leverage.mjs

@@ -31,6 +31,8 @@ export default async function leverage() {
     console.log("");
   }
   console.log(
-    `${tips.length} suggestion(s), most impactful first. These adjust your setup — nothing was changed.`,
+    `${tips.length} suggestion(s), most impactful first. This is the detector — it changed nothing.\n` +
+      "To have rafa apply these exactly (merge settings, wire the MCP, scaffold a skill), run\n" +
+      "  /rafa leverage   in Claude Code — it edits with your approval.",
   );
 }

package/lib/migrate.mjs

@@ -14,9 +14,15 @@ export default async function migrate() {
 
   if (pending.length === 0) {
     console.log(
-      `✓ Nothing to migrate — plans v${from.plans}, contract v${from.contract} ` +
+      `✓ Nothing mechanical to migrate — plans v${from.plans}, contract v${from.contract} ` +
         `already match ${CURRENT.version}.`,
     );
+    if (CURRENT.plans > from.plans || CURRENT.contract > from.contract) {
+      console.log(
+        "  ↳ but the schema version advanced. If a plan/brain SHAPE changed and files need\n" +
+          "    rewriting, that's a semantic migration — run  /rafa migrate  in Claude Code.",
+      );
+    }
     // Still advance the stamp so the recorded CLI version reflects reality.
     stampCurrent(cwd);
     return;

package/lib/migrations/index.mjs

@@ -6,10 +6,18 @@
 // Contract:
 //   id          string                       stable identifier, shown in the log
 //   kind        "plans" | "contract" | "config"
+//   mode        "mechanical" | "assisted"    default "mechanical"
 //   summary     string                       one line: what it changes + why
 //   appliesTo(from, to) => boolean           from = stampedVersions(cwd), to = CURRENT
 //   run(cwd)    => { changed: string[], notes: string[] }   idempotent; report what it touched
 //
+// mode distinguishes the two migration channels:
+//   "mechanical" — a deterministic transform (field rename, path move, add-default). `run` does
+//                  it here in the CLI, no LLM needed.
+//   "assisted"   — the shape changed and each file must be UNDERSTOOD to be rewritten. The CLI
+//                  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):

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

@@ -3,11 +3,14 @@
 // package.json). It declares the contract + plans schema versions that release ships and
 // the strongest action a client must take to adopt it:
 //
-//   requires: "update"   → re-sync the blueprint (`rafa update`); no data change
-//             "migrate"  → run `rafa migrate` (a structured file changed shape)
-//             "rescan"   → the brain contract changed incompatibly; regenerate via `/rafa scan`
+//   requires:   "update" | "migrate" | "rescan"   the strongest structural action
+//               ("update" → just re-sync files; "migrate"/"rescan" are also computed
+//                deterministically from the contract/plans version deltas below).
+//   recommends: string[]   soft follow-ups this release suggests (e.g. ["leverage"]) — shown
+//               by `update` as recommended, not required.
 //
-// `update` reads this to tell the client — transparently — what an upgrade means for them.
+// `update` reads this to tell the client — transparently — what an upgrade means for them:
+// the release notes since their version, and exactly which actions the upgrade needs.
 
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -31,6 +34,28 @@ export const RELEASES = [
       "Non-destructive vendoring (merge settings, never clobber tuned agents); secrets " +
       "guardrail in scan; `rafa leverage` toolbox advisor; version-aware updates + `rafa migrate`.",
   },
+  {
+    version: "0.2.1",
+    contract: 1,
+    plans: 1,
+    requires: "update",
+    recommends: ["leverage"],
+    summary:
+      "leverage & migrate are now intelligent `/rafa` commands — the LLM applies toolbox fixes " +
+      "and rewrites plans exactly. Two-layer update: `rafa update` (CLI) does the blueprint side + " +
+      "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.)",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/stamp.mjs

@@ -46,10 +46,18 @@ export function stampedVersions(cwd) {
   };
 }
 
-// Re-stamp to the versions this CLI build ships (called after init/update/migrate).
+// Re-stamp to the versions this CLI build ships (called after init, or after update when NO
+// brain-side migration remains — i.e. blueprint AND data are current together).
 export function stampCurrent(cwd, extra = {}) {
   return writeStamp(cwd, {
     ...extra,
     rafa: { cli: CLI_VERSION, contract: CURRENT.contract, plans: CURRENT.plans },
   });
 }
+
+// Advance ONLY the blueprint/CLI version — the data (brain/plans) version is left where it is,
+// so `/rafa update` can still see the gap and run the brain-side migrations. Use after
+// `rafa update` when brain-side work remains.
+export function stampCli(cwd) {
+  return writeStamp(cwd, { rafa: { cli: CLI_VERSION } });
+}

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 { CURRENT, releasesAfter } from "./releases.mjs";
-import { stampedVersions, stampCurrent } from "./stamp.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,42 +27,59 @@ 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);
 
-  // What changed since the client's last version — the transparent part.
+  // ── Blueprint-side migrations: mechanical/deterministic, run here in the CLI. ──
+  // (Anything needing intelligence is left for the brain-side pass — /rafa update.)
+  const pending = pendingMigrations(from, CURRENT);
+  const mechanical = pending.filter((m) => (m.mode ?? "mechanical") !== "assisted");
+  for (const m of mechanical) {
+    try {
+      const r = m.run(TARGET);
+      console.log(`  ✓ migrated ${m.id}: ${r.changed.length} file(s)`);
+    } catch (e) {
+      console.log(`  ! migration ${m.id} failed: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+
+  // ── Release notes: what changed since the client's version. ──
   const news = releasesAfter(from.cli);
   if (news.length) {
-    console.log(`\n  Changes since ${from.cli}:`);
-    for (const r of news) console.log(`    • ${r.version} — ${r.summary}`);
+    console.log(`\n  Release notes  (${from.cli} → ${CLI_VERSION}):`);
+    for (const r of news) console.log(`    ${r.version} — ${r.summary}`);
   }
 
-  // Does the upgrade require action beyond re-syncing files?
-  const rescan = CURRENT.contract > from.contract;
-  const migrate = CURRENT.plans > from.plans || pendingMigrations(from, CURRENT).length > 0;
-
-  console.log("");
-  if (rescan) {
-    console.log(
-      `  ⚠ Brain contract v${from.contract} → v${CURRENT.contract}: your brain is now stale.\n` +
-        "    Run  /rafa scan  to regenerate it, then  rafa push.",
+  // ── Brain-side follow-ups: the CLI can't do these — they need intelligence. Route to /rafa update. ──
+  // The gap is measured against the DATA version (from.contract/plans), which only advances when the
+  // brain/plans are actually regenerated — not by this blueprint sync.
+  const brain = [];
+  if (CURRENT.contract > from.contract) {
+    brain.push(
+      `Re-scan the brain  (contract v${from.contract} → v${CURRENT.contract}; the brain is a stale cache)`,
     );
   }
-  if (migrate) {
-    console.log(
-      `  ⚠ Plan/structure schema changed (plans v${from.plans} → v${CURRENT.plans}).\n` +
-        "    Run  rafa migrate  to bring your files forward.",
-    );
+  if (CURRENT.plans > from.plans || pending.some((m) => m.mode === "assisted")) {
+    brain.push(`Rewrite plans to the new shape  (plans v${from.plans} → v${CURRENT.plans})`);
   }
-  if (!rescan && !migrate) {
-    console.log("  ✓ No re-scan or migration needed — your brain data is still valid.");
+
+  console.log("");
+  if (brain.length) {
+    console.log("  Brain-side follow-ups — run  /rafa update  in Claude Code (needs intelligence):");
+    for (const b of brain) console.log(`    • ${b}`);
+    // Blueprint is current, but the data still lags — keep the gap visible for /rafa update.
+    stampCli(TARGET);
+  } else {
+    console.log("  ✓ No brain migration needed — your brain data is still valid.");
+    stampCurrent(TARGET);
   }
 
-  // Advance the stamp to what we just installed.
-  stampCurrent(TARGET);
+  const recs = new Set(news.flatMap((r) => r.recommends ?? []));
+  if (recs.has("leverage")) console.log("  ↳ recommended: /rafa leverage (tune your toolbox).");
 
   console.log(
-    "\n  Your brain data (.rafa/brain, .rafa/improve) was untouched. " +
-      "Review any `.new` files, then restart Claude Code to reload the agents.",
+    "\n  Owned files you tuned were preserved (review any `.new`). Restart Claude Code to reload the agents.",
   );
 }

package/lib/version-check.mjs

@@ -27,7 +27,7 @@ export async function notifyIfBehind(installed = CLI_VERSION) {
   if (!latest || cmpSemver(latest, installed) <= 0) return latest;
   console.log(
     `\n  ⬆ rafinery ${latest} is available (you're on ${installed}).\n` +
-      `     Update:  npm i -g @rafinery/cli@latest  &&  rafa update\n`,
+      `     Update:  npx @rafinery/cli@latest update   (fetches the latest CLI + vendors it into your repo)\n`,
   );
   return latest;
 }

package/package.json

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