@rafinery/cli 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# @rafinery/cli — changelog
+
+The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.mjs) — the
+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.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:** `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
+  (agents, capabilities) are preserved — a changed one is written as `<file>.new` for you to
+  merge — while tools + contract move in lockstep. Required permissions are **merged** into
+  `.claude/settings.json` (union into `permissions.allow`; every other key preserved; a file
+  we can't parse is left untouched).
+- **Secrets guardrail.** The scan reads env var **names from source only** — never opens
+  `.env*` or captures a value.
+- **`rafa leverage`.** Inspects your agent toolbox (permissions, skills, MCP, config) and
+  prints prioritized, advisory tips. Modular behind a `ToolchainAdapter` seam (Claude Code
+  today; Codex/Cursor slot in later).
+- **Version-aware updates.** `init`/`update` notify you when a newer rafinery is published;
+  `update` shows what changed since your version and whether a re-scan or migration is needed.
+- **`rafa migrate`.** Brings structured files (plans, config) up to the schema the installed
+  CLI ships. Idempotent; a no-op until a release changes a shape — the seam is in place.
+- A `rafa.json` version stamp records the contract/plans versions this repo was provisioned
+  at (the anchor `update`/`migrate` diff against).
+
+## 0.1.0
+
+- Deterministic contract + `manifest.json` ingest.
+- `@rafinery/cli` — `init` (vendor blueprint + wire brain remote), `update`, `compile`, `push`.

package/bin/rafa.mjs

@@ -5,6 +5,8 @@
 //   rafa update               re-sync the blueprint into this repo (shadcn-style)
 //   rafa compile              run the contract gate → .rafa/manifest.json
 //   rafa push                 compile + push .rafa/ to the brain remote
+//   rafa leverage             inspect your agent toolbox → proactive tips
+//   rafa migrate              bring structured files (plans/config) up to the current schema
 //
 // The LLM work (scan / improve / plan) runs inside Claude Code via /rafa.
 
@@ -15,7 +17,7 @@ import { fileURLToPath } from "node:url";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8"));
 
-const COMMANDS = ["init", "update", "compile", "push"];
+const COMMANDS = ["init", "update", "compile", "push", "leverage", "migrate"];
 const [cmd, ...rest] = process.argv.slice(2);
 
 function help() {
@@ -29,6 +31,10 @@ Commands:
   update               Re-sync the blueprint into this repo (you own your copy; opt-in updates).
   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
+                       prioritized tips for getting more out of it. Advisory — changes nothing.
+  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
 

package/blueprint/.claude/agents/atlas.md

@@ -72,6 +72,10 @@ Never act cold; never over-load.
 - **Capture the trace, not the tool.** Knowledge is tool-agnostic — record the decision, the
   cited code, and the *why*, never which (possibly personal) skill produced it. Committed
   `.claude/` is org config (mappable); the dev's personal `~/.claude/` is private (never indexed).
+- **Secrets are off-limits.** Record env var **names and where they're read** (from source only);
+  **never open `.env`/`.env.*` or any secret store, and never read or copy a value.** A key's
+  *name* is a contract; its *value* is a secret. If a note genuinely needs a value, stop and ask
+  the dev — don't harvest it. (Enforced in [scan](../../.rafa/capabilities/scan.md) step 4.)
 - **Orchestrate, don't bury.** At work-time, ride the host + the dev's existing skills/tools/MCP
   and recommend the best-fit one; never reinvent a capability that already exists. rafa conducts
   what's present.

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. Usage: /rafa <init|scan|improve|push|leverage|migrate|update> [--brain-only]
 ---
 
 You are the **conductor** of the rafa agent loop, running in the **main session**.
@@ -56,8 +56,57 @@ 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.
 
+## `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.
+
 ## (no argument, or unrecognized)
-Print usage and stop: `/rafa init` · `/rafa scan [--brain-only]` · `/rafa improve` · `/rafa push`.
+`/rafa` runs the in-editor passes: `init` · `scan [--brain-only]` · `improve` · `push` ·
+`leverage` · `migrate` · `update`.
+
+`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.
 
 ---
 Token discipline: glob/grep/AST before reading; scoped reads; deterministic extraction

package/blueprint/.rafa/capabilities/leverage.md

@@ -0,0 +1,77 @@
+# leverage — get more out of the toolbox you already have  (capability #3)
+
+rafa's third mission: **make the dev's agent toolchain pull its full weight.** rafa already
+reads your *code* to build a brain; leverage turns the same lens on your *toolbox* — the
+config layer (permissions, skills, MCP servers, hooks, commands) that decides how effective
+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.**
+
+**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.
+
+---
+
+## Prime directives
+
+1. **Leverage, don't replace** — always prefer the dev's existing capability (a skill, an MCP
+   server, a host feature) over hand-rolling one. The best tip points at something already
+   installed but unwired.
+2. **Signal, not noise** — emit a tip only from a clear, checkable signal (a missing permission,
+   an un-ignored `.env`, a stack with no matching MCP). A false or obvious tip mutes the whole
+   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. **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.
+
+---
+
+## Architecture — the ToolchainAdapter seam
+
+The engine ([`lib/leverage/engine.mjs`](../../packages/cli/lib/leverage/engine.mjs)) gathers
+light, tool-agnostic repo signals (`repoContext`: stack deps, `.env` files + whether they're
+ignored, declared MCP servers), then runs every **detected** adapter and ranks the tips.
+
+Each adapter implements one contract ([`lib/leverage/adapters/index.mjs`](../../packages/cli/lib/leverage/adapters/index.mjs)):
+
+| Member | Shape | Job |
+|---|---|---|
+| `id` / `name` | string | identity + human label |
+| `detect(cwd)` | → boolean | is this toolchain present in the repo? |
+| `inspect(cwd)` | → Capabilities | normalized view: `{ permissions, skills, agents, commands, … }` |
+| `recommend(cwd, ctx)` | → Tip[] | proactive tips `{ id, priority, title, detail, fix }` |
+
+**Implemented:** `claude-code` — reads `.claude/settings.json`, `skills/`, `agents/`,
+`commands/`, and `.mcp.json`. **Declared, not yet built:** `codex`, `cursor` (the `PLANNED`
+list) — the seam is real, the adapters are added when a user actually runs on that toolchain.
+*Don't build an adapter ahead of the phase that consumes it.*
+
+### What the Claude Code adapter checks today
+- **Secrets** — `.env*` present but not gitignored → `P1` (protect the keys before a scan or a commit).
+- **Permissions** — `.rafa/bin` vendored but its tools aren't allow-listed / no `settings.json`
+  → `P2`, fix = `rafa init`/`update` (which *merge*, never clobber — see the CLI).
+- **MCP** — a stack with no matching server wired (e.g. Convex repo, no `convex` MCP) → `P2`.
+- **Skills** — no project skills captured → `P3`.
+
+Adding a check = one entry in an adapter's `recommend`. Adding a toolchain = one new adapter
+behind the same contract. The engine and the `rafa leverage` command never change.
+
+---
+
+## Boundaries
+
+- **Committed config only.** Read the repo's `.claude/` (org config). The dev's personal
+  `~/.claude/` is private — never inspected. (Mirrors [scan](scan.md)'s privacy line.)
+- **Secrets are off-limits.** Detect that an `.env` is unprotected; **never open it or read a
+  value.** Same hard line as the scan guardrail.
+- **Read-only.** leverage itself mutates nothing. The only writes are `rafa init`/`update`
+  merging permissions, run explicitly by the dev.

package/blueprint/.rafa/capabilities/scan.md

@@ -138,8 +138,13 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
    data-op shape, naming).
    **One `convention` note minimum per domain** — this guarantees breadth. For the
    **external-integrations** domain, produce an **env-and-integrations** note: every
-   required env var and the `file:line` where each is read (so "what keys does this repo
-   need, and where?" is answerable at work-time). A domain marked `mapped` must have a note.
+   required env var **name** and the `file:line` in **source** where each is read (so "what keys
+   does this repo need, and where?" is answerable at work-time). A domain marked `mapped` must
+   have a note.
+   **Secrets guardrail (hard):** record env var **names only, read from code**. **Never open
+   `.env`, `.env.*`, or any secret file, and never read, log, or copy a value** — a name is a
+   contract, a value is a secret. If a note truly needs a value, **stop and ask the dev**; never
+   harvest it. (`.env*` is excluded from every read/grep in this step.)
    **Flag exceptions as non-exemplars.** When a convention has a grandfathered/legacy file
    that *violates* it — often the **most salient** example — the note MUST name that file and
    mark it *"exception, not the model — don't pattern-match it."* Salience gets copied; an
@@ -150,8 +155,8 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
 
 5. **Seam detection** [grep + LLM judge] — anchor tokens (agent/graph names, tool names,
    env vars, route strings, exported state/types, table names). For each, run
-   `git grep -n <token>` repo-wide and record **every** hit as a site (site list == grep
-   hit list; never infer or sample). Any token in ≥2 boundary-crossing files = a
+   `git grep -n <token> -- ':!.env*'` repo-wide (env files excluded — see the secrets guardrail
+   above) and record **every** hit as a site (site list == grep hit list; never infer or sample). Any token in ≥2 boundary-crossing files = a
    `contract`. Judge *what must stay in sync* and *does it fail silently*. State-shape
    contracts count too (e.g. a frontend `AgentState` type that must match a backend graph
    state). **Composition/ordering contracts count too** — provider nesting, middleware

package/lib/blueprint.mjs

@@ -7,25 +7,31 @@ import {
   existsSync,
   mkdirSync,
   cpSync,
+  readFileSync,
   readdirSync,
   statSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// Files a client owns + tunes (agents, SOPs). Tools + contract move in lockstep.
+// Two classes of blueprint file:
+//  - owned    → the client tunes these (agents, SOPs). We NEVER clobber a modified copy;
+//               a changed file is written alongside as `<file>.new` so the dev merges by hand.
+//  - lockstep → tools + contract. These move with the CLI version, so they overwrite.
 export const BLUEPRINT = {
-  files: [
+  owned: [
     ".claude/agents/atlas.md",
     ".claude/agents/prism.md",
     ".claude/agents/bloom.md",
     ".claude/commands/rafa.md",
+  ],
+  ownedDirs: [".rafa/capabilities"],
+  lockstep: [
     ".rafa/contract.md",
     ".rafa/bin/verify-citations.mjs",
     ".rafa/bin/rafa-compile.mjs",
     ".rafa/bin/rafa-push.mjs",
   ],
-  dirs: [".rafa/capabilities"],
 };
 
 const HERE = dirname(fileURLToPath(import.meta.url)); // …/packages/cli/lib
@@ -60,27 +66,70 @@ export function repoRoot() {
   return root;
 }
 
-// Copy every blueprint file/dir from `from` into `to`. Returns the relative paths written.
-export function copyBlueprint(from, to) {
-  const written = [];
-  for (const rel of BLUEPRINT.files) {
-    const src = join(from, rel);
-    if (!existsSync(src)) continue;
-    const dst = join(to, rel);
-    mkdirSync(dirname(dst), { recursive: true });
-    cpSync(src, dst);
-    written.push(rel);
+// Expand a blueprint dir into its flat list of relative file paths.
+function filesUnder(from, relDir) {
+  const out = [];
+  const abs = join(from, relDir);
+  if (!existsSync(abs)) return out;
+  for (const e of readdirSync(abs)) {
+    const p = join(abs, e);
+    if (statSync(p).isDirectory()) out.push(...filesUnder(from, join(relDir, e)));
+    else out.push(join(relDir, e));
+  }
+  return out;
+}
+
+// The resolved owned/lockstep file lists (dirs expanded), for a given source root.
+export function blueprintFiles(from) {
+  const owned = [
+    ...BLUEPRINT.owned,
+    ...BLUEPRINT.ownedDirs.flatMap((d) => filesUnder(from, d)),
+  ];
+  return { owned, lockstep: [...BLUEPRINT.lockstep] };
+}
+
+function sameBytes(a, b) {
+  try {
+    return readFileSync(a).equals(readFileSync(b));
+  } catch {
+    return false;
   }
-  for (const rel of BLUEPRINT.dirs) {
+}
+
+// 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 "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" } = {}) {
+  const { owned, lockstep } = blueprintFiles(from);
+  const report = { created: [], updated: [], unchanged: [], preserved: [] };
+
+  const put = (rel, isOwned) => {
     const src = join(from, rel);
-    if (!existsSync(src)) continue;
+    if (!existsSync(src)) return;
     const dst = join(to, rel);
-    mkdirSync(dst, { recursive: true });
-    cpSync(src, dst, { recursive: true });
-    // list the .md files copied, for a useful summary
-    for (const e of readdirSync(src)) {
-      if (statSync(join(src, e)).isFile()) written.push(join(rel, e));
+    mkdirSync(dirname(dst), { recursive: true });
+    if (!existsSync(dst)) {
+      cpSync(src, dst);
+      report.created.push(rel);
+      return;
     }
-  }
-  return written;
+    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);
+    }
+  };
+
+  for (const rel of lockstep) put(rel, false);
+  for (const rel of owned) put(rel, true);
+  return report;
 }

package/lib/claude-config.mjs

@@ -0,0 +1,57 @@
+// Non-destructive reads/writes of the host's Claude Code config. rafa augments the
+// dev's toolbox; it must never clear or overwrite what's already there.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// The permissions rafa's installed tooling needs to run without a prompt each time.
+// Kept minimal + specific to what `rafa init` actually vendors into `.rafa/bin`.
+export const RAFA_PERMISSIONS = [
+  "Read(.rafa/**)",
+  "Bash(node .rafa/bin/rafa-compile.mjs:*)",
+  "Bash(node .rafa/bin/rafa-push.mjs:*)",
+  "Bash(node .rafa/bin/verify-citations.mjs:*)",
+];
+
+export function settingsPath(targetDir) {
+  return join(targetDir, ".claude", "settings.json");
+}
+
+// Read + parse .claude/settings.json. Returns null if absent, `{ error }` if it exists
+// but can't be parsed (so callers can refuse to touch a file they can't understand).
+export function readClaudeSettings(targetDir) {
+  const file = settingsPath(targetDir);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+// Merge rafa's required permissions into .claude/settings.json WITHOUT clobbering the
+// dev's config — union into `permissions.allow`, preserve every other key untouched.
+// Never overwrites a file it can't parse. Returns:
+//   { added: [...] }        entries newly written (empty = already present)
+//   { skipped: "reason" }   we declined to touch the file (e.g. unparseable)
+export function mergeClaudeSettings(targetDir, perms = RAFA_PERMISSIONS) {
+  const file = settingsPath(targetDir);
+  const existing = readClaudeSettings(targetDir);
+  if (existing && existing.error) {
+    return { skipped: `.claude/settings.json is not valid JSON (${existing.error})` };
+  }
+
+  const settings = existing ?? {};
+  const permissions = { ...(settings.permissions ?? {}) };
+  const allow = Array.isArray(permissions.allow) ? [...permissions.allow] : [];
+  const have = new Set(allow);
+  const added = perms.filter((p) => !have.has(p));
+
+  if (added.length === 0 && existing) return { added: [] };
+
+  permissions.allow = [...allow, ...added];
+  const next = { ...settings, permissions };
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return { added };
+}

package/lib/init.mjs

@@ -10,6 +10,32 @@ import {
 import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
+import { mergeClaudeSettings } from "./claude-config.mjs";
+import { stampCurrent } from "./stamp.mjs";
+import { notifyIfBehind } from "./version-check.mjs";
+
+// One-line summary of a copyBlueprint report; notes preserved (un-clobbered) 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`,
+  );
+  for (const rel of r.preserved)
+    console.log(`    • kept your ${rel} — latest written to ${rel}.new (merge by hand)`);
+}
+
+// Union rafa's required permissions into .claude/settings.json without clobbering it.
+export function reportSettings(target) {
+  const res = mergeClaudeSettings(target);
+  if (res.skipped) {
+    console.log(`  ! settings untouched — ${res.skipped}`);
+  } else if (res.added.length) {
+    console.log(`  ✓ merged ${res.added.length} permission(s) into .claude/settings.json`);
+  } else {
+    console.log("  ✓ .claude/settings.json already grants rafa's tools");
+  }
+}
 
 const die = (m) => {
   console.error(`✗ ${m}`);
@@ -42,11 +68,13 @@ 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).
-  const written = copyBlueprint(blueprintSource(), TARGET);
+  // 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));
   if (!existsSync(join(TARGET, ".rafa", "active.md")))
     writeFileSync(join(TARGET, ".rafa", "active.md"), "# No active plan\n");
-  console.log(`  ✓ vendored ${written.length} blueprint files → .claude/ + .rafa/`);
+  // 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");
@@ -56,21 +84,22 @@ export default async function init(args) {
     console.log("  ✓ .rafa/ → .gitignore");
   }
 
-  if (p) {
-    writeFileSync(
-      join(TARGET, "rafa.json"),
-      JSON.stringify(
-        {
+  // Stamp the versions this repo was provisioned at — the compat anchor `update`/`migrate`
+  // diff against. Carries platform identity too when provisioned via a setup URL.
+  stampCurrent(
+    TARGET,
+    p
+      ? {
           name: p.repoName,
           repoId: p.repoId,
           codeRepo: p.codeRepoUrl ?? null,
           brainRepo: p.brainRepoUrl,
           provisionedFor: p.owner ?? null,
-        },
-        null,
-        2,
-      ) + "\n",
-    );
+        }
+      : {},
+  );
+
+  if (p) {
     const rafaDir = join(TARGET, ".rafa");
     if (!existsSync(join(rafaDir, ".git"))) run("git init -b main", rafaDir);
     try {
@@ -88,4 +117,6 @@ export default async function init(args) {
       "  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.",
   );
+
+  await notifyIfBehind();
 }

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

@@ -0,0 +1,103 @@
+// Claude Code toolchain adapter. Normalizes the host's `.claude/` + `.mcp.json` config
+// and emits proactive tips for getting more out of it. Implements the ToolchainAdapter
+// contract in ../index.mjs.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { readClaudeSettings, RAFA_PERMISSIONS } from "../../claude-config.mjs";
+
+const P1 = "P1", P2 = "P2", P3 = "P3";
+
+function count(dir) {
+  return existsSync(dir) ? readdirSync(dir).length : 0;
+}
+
+const adapter = {
+  id: "claude-code",
+  name: "Claude Code",
+
+  // Present if the repo carries Claude Code config.
+  detect(cwd) {
+    return existsSync(join(cwd, ".claude")) || existsSync(join(cwd, ".mcp.json"));
+  },
+
+  // Normalized capability view — the shape every adapter reports in.
+  inspect(cwd) {
+    const settings = readClaudeSettings(cwd);
+    const ok = settings && !settings.error;
+    return {
+      permissions: ok ? (settings.permissions?.allow ?? []) : [],
+      settingsState: !settings ? "missing" : settings.error ? "unparseable" : "ok",
+      skills: count(join(cwd, ".claude", "skills")),
+      agents: count(join(cwd, ".claude", "agents")),
+      commands: count(join(cwd, ".claude", "commands")),
+    };
+  },
+
+  // Proactive tips, from clear signals only (no noise).
+  recommend(cwd, ctx) {
+    const tips = [];
+    const cap = this.inspect(cwd);
+
+    // Secrets: .env present but not ignored — leverage the toolbox to protect them.
+    if (ctx.envFiles.length && !ctx.envGitignored) {
+      tips.push({
+        id: "env-not-ignored",
+        priority: P1,
+        title: "`.env` files aren't gitignored",
+        detail: `Found ${ctx.envFiles.join(", ")} untracked-by-ignore — secrets can be committed or read into a scan.`,
+        fix: "add `.env*` to .gitignore (keep `!.env.example`)",
+      });
+    }
+
+    // rafa's own tools should run without a prompt each time.
+    if (existsSync(join(cwd, ".rafa", "bin"))) {
+      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.",
+          fix: "run `rafa init` (or `rafa update`) — it merges the permissions in",
+        });
+      } else if (cap.settingsState === "ok") {
+        const missing = RAFA_PERMISSIONS.filter((p) => !cap.permissions.includes(p));
+        if (missing.length) {
+          tips.push({
+            id: "perms-missing",
+            priority: P2,
+            title: `${missing.length} rafa tool permission(s) not allow-listed`,
+            detail: "the vendored gates will prompt until granted.",
+            fix: "run `rafa update` — it unions them into settings.json without clobbering yours",
+          });
+        }
+      }
+    }
+
+    // MCP leverage: a Convex repo with no Convex MCP server wired.
+    if (ctx.stack.convex && !ctx.mcp.servers.has("convex")) {
+      tips.push({
+        id: "mcp-convex",
+        priority: P2,
+        title: "Convex in the stack, but no Convex MCP server",
+        detail: "wiring it gives agents schema-aware queries + function specs instead of guessing.",
+        fix: "add a `convex` entry to .mcp.json",
+      });
+    }
+
+    // Skills: package repeatable procedures so agents reuse them.
+    if (cap.skills === 0) {
+      tips.push({
+        id: "no-skills",
+        priority: P3,
+        title: "No project skills in `.claude/skills`",
+        detail: "recurring procedures (deploy, scaffold, review) reused across sessions belong here.",
+        fix: "capture one repeatable flow as a skill",
+      });
+    }
+
+    return tips;
+  },
+};
+
+export default adapter;

package/lib/leverage/adapters/index.mjs

@@ -0,0 +1,23 @@
+// Toolchain adapter registry. Every adapter implements the same contract so the
+// leverage engine stays tool-agnostic:
+//
+//   id       string
+//   name     string                       human label
+//   detect   (cwd) => boolean             is this toolchain present in the repo?
+//   inspect  (cwd) => Capabilities        normalized view { permissions, skills, ... }
+//   recommend(cwd, ctx) => Tip[]          proactive tips { id, priority, title, detail, fix }
+//
+// This is the seam that makes "leverage what's available" true beyond Claude Code:
+// Codex, Cursor, and any other agent toolchain slot in here behind the same interface.
+// They're declared, not yet built — we add each adapter when a user actually runs on it
+// (don't build ahead of the phase that consumes it).
+
+import claudeCode from "./claude-code.mjs";
+
+export const adapters = [claudeCode];
+
+// Declared-but-unimplemented toolchains — the shape they'll fill.
+export const PLANNED = [
+  { id: "codex", name: "Codex" },
+  { id: "cursor", name: "Cursor" },
+];

package/lib/leverage/engine.mjs

@@ -0,0 +1,82 @@
+// The leverage advisor — tool-agnostic. It reads light signals about the repo, runs
+// every detected toolchain adapter, and returns prioritized tips for getting more out
+// of the dev's existing setup. The adapters (Claude Code today; Codex/Cursor behind the
+// same seam) do the tool-specific work; this engine only orchestrates + ranks.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { adapters } from "./adapters/index.mjs";
+
+// Merge dependencies from the cwd package.json and any apps/*/package.json (monorepo).
+function readDeps(cwd) {
+  const deps = new Set();
+  const add = (file) => {
+    if (!existsSync(file)) return;
+    try {
+      const p = JSON.parse(readFileSync(file, "utf8"));
+      for (const k of Object.keys({ ...p.dependencies, ...p.devDependencies })) deps.add(k);
+    } catch {
+      /* ignore unparseable package.json */
+    }
+  };
+  add(join(cwd, "package.json"));
+  const appsDir = join(cwd, "apps");
+  if (existsSync(appsDir)) {
+    for (const app of readdirSync(appsDir)) add(join(appsDir, app, "package.json"));
+  }
+  return deps;
+}
+
+// Env files present in the repo root (excluding the committed example).
+function listEnvFiles(cwd) {
+  return readdirSync(cwd).filter((f) => /^\.env(\.|$)/.test(f) && f !== ".env.example");
+}
+
+// Does .gitignore actually cover .env files?
+function envIgnored(cwd) {
+  const gi = join(cwd, ".gitignore");
+  if (!existsSync(gi)) return false;
+  return /^\s*\.env/m.test(readFileSync(gi, "utf8"));
+}
+
+// Server names declared in .mcp.json.
+function readMcp(cwd) {
+  const file = join(cwd, ".mcp.json");
+  if (!existsSync(file)) return { present: false, servers: new Set() };
+  try {
+    const j = JSON.parse(readFileSync(file, "utf8"));
+    return { present: true, servers: new Set(Object.keys(j.mcpServers ?? j.servers ?? {})) };
+  } catch {
+    return { present: true, servers: new Set() };
+  }
+}
+
+// Light, tool-agnostic view of the repo so adapters can tailor tips to the real stack.
+export function repoContext(cwd) {
+  const deps = readDeps(cwd);
+  const has = (n) => deps.has(n);
+  const envFiles = listEnvFiles(cwd);
+  return {
+    stack: {
+      next: has("next"),
+      convex: has("convex") || existsSync(join(cwd, "convex")) || existsSync(join(cwd, "apps", "web", "convex")),
+      langgraph: has("@langchain/langgraph"),
+      clerk: [...deps].some((d) => d.startsWith("@clerk/")),
+    },
+    envFiles,
+    envGitignored: envFiles.length === 0 || envIgnored(cwd),
+    mcp: readMcp(cwd),
+  };
+}
+
+const RANK = { P1: 0, P2: 1, P3: 2 };
+
+// Run every detected adapter, tag tips with their tool, and rank by priority.
+export function advise(cwd) {
+  const ctx = repoContext(cwd);
+  const active = adapters.filter((a) => a.detect(cwd));
+  const tips = active
+    .flatMap((a) => a.recommend(cwd, ctx).map((t) => ({ ...t, tool: a.name })))
+    .sort((x, y) => (RANK[x.priority] ?? 9) - (RANK[y.priority] ?? 9));
+  return { ctx, detected: active.map((a) => a.name), tips };
+}

package/lib/leverage.mjs

@@ -0,0 +1,38 @@
+// rafa leverage — inspect the dev's agent toolbox (permissions, skills, MCP, config)
+// and print prioritized tips for getting more out of what's already installed. Advisory
+// only: it reads, ranks, and reports — it changes nothing. Run from your repo root.
+
+import { advise } from "./leverage/engine.mjs";
+import { PLANNED } from "./leverage/adapters/index.mjs";
+
+export default async function leverage() {
+  const cwd = process.cwd();
+  const { detected, tips } = advise(cwd);
+
+  if (detected.length === 0) {
+    console.log(
+      "No supported agent toolchain detected here.\n" +
+        `  Supported now: Claude Code.  Planned: ${PLANNED.map((p) => p.name).join(", ")}.`,
+    );
+    return;
+  }
+
+  console.log(`rafa leverage — inspecting your toolbox (${detected.join(", ")})\n`);
+
+  if (tips.length === 0) {
+    console.log("✓ Nothing to tune — your toolbox is set up well.");
+    return;
+  }
+
+  for (const t of tips) {
+    console.log(`  [${t.priority}] ${t.title}  · ${t.tool}`);
+    console.log(`        ${t.detail}`);
+    if (t.fix) console.log(`        fix: ${t.fix}`);
+    console.log("");
+  }
+  console.log(
+    `${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

@@ -0,0 +1,53 @@
+// rafa migrate — bring a repo's structured files (plans, config) up to the schema the
+// installed CLI ships. Reads the version stamp to know where the repo is coming FROM,
+// runs the applicable migrations idempotently, and re-stamps. Advisory + reversible:
+// it only rewrites files you can review in `git diff` (and re-run safely).
+
+import { CURRENT, releaseOf } from "./releases.mjs";
+import { stampedVersions, stampCurrent } from "./stamp.mjs";
+import { pendingMigrations } from "./migrations/index.mjs";
+
+export default async function migrate() {
+  const cwd = process.cwd();
+  const from = stampedVersions(cwd);
+  const pending = pendingMigrations(from, CURRENT);
+
+  if (pending.length === 0) {
+    console.log(
+      `✓ 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;
+  }
+
+  console.log(`rafa migrate — applying ${pending.length} migration(s) → ${CURRENT.version}\n`);
+  for (const m of pending) {
+    console.log(`  • ${m.id} [${m.kind}] — ${m.summary}`);
+    let r;
+    try {
+      r = m.run(cwd);
+    } catch (e) {
+      console.error(`    ✗ failed: ${e instanceof Error ? e.message : e}`);
+      console.error("    Stamp left unchanged — fix the error and re-run `rafa migrate`.");
+      process.exit(1);
+    }
+    console.log(`    ✓ ${r.changed.length} file(s) updated`);
+    for (const n of r.notes) console.log(`      ${n}`);
+  }
+
+  stampCurrent(cwd);
+  const rescan = releaseOf(CURRENT.version)?.requires === "rescan";
+  console.log(
+    `\n✓ Migrated to ${CURRENT.version}. Review the diff` +
+      (rescan ? ", then run `/rafa scan` (the brain contract changed)" : "") +
+      ", then `rafa push` if this is a connected repo.",
+  );
+}

package/lib/migrations/index.mjs

@@ -0,0 +1,38 @@
+// Migration registry. When a release changes the SHAPE of a structured file (a plan's
+// frontmatter, the contract, vendored config), it adds a migration here so clients move
+// forward with one `rafa migrate` instead of hand-editing. Migrations are idempotent and
+// run in order; each transforms the client's on-disk files from one schema to the next.
+//
+// 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):
+//
+//   const plans_v1_to_v2 = {
+//     id: "plans-add-owner-field",
+//     kind: "plans",
+//     summary: "plan frontmatter gains a required `owner` field (default: repo owner).",
+//     appliesTo: (from, to) => from.plans < 2 && to.plans >= 2,
+//     run: (cwd) => backfillPlanField(cwd, "owner", ownerOf(cwd)),
+//   };
+
+export const MIGRATIONS = [];
+
+// The migrations that apply to a given move (stamped `from` → shipped `to`), in order.
+export function pendingMigrations(from, to) {
+  return MIGRATIONS.filter((m) => m.appliesTo(from, to));
+}

package/lib/releases.mjs

@@ -0,0 +1,78 @@
+// The release ledger — the CLI's machine-readable source of truth for "what does moving
+// to version X require?" Every published release adds one entry here (in lockstep with
+// 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" | "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:
+// the release notes since their version, and exactly which actions the upgrade needs.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const RELEASES = [
+  {
+    version: "0.1.0",
+    contract: 1,
+    plans: 1,
+    requires: "update",
+    summary:
+      "Deterministic contract + manifest ingest; @rafinery/cli (init/update/compile/push).",
+  },
+  {
+    version: "0.2.0",
+    contract: 1,
+    plans: 1,
+    requires: "update",
+    summary:
+      "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.",
+  },
+];
+
+// The release this CLI build ships (last entry).
+export const CURRENT = RELEASES[RELEASES.length - 1];
+
+// The installed CLI version, read from package.json (the single numeric source of truth).
+const HERE = dirname(fileURLToPath(import.meta.url)); // …/packages/cli/lib
+export const CLI_VERSION = JSON.parse(
+  readFileSync(join(HERE, "..", "package.json"), "utf8"),
+).version;
+
+// Compare two x.y.z strings → -1 | 0 | 1.
+export function cmpSemver(a, b) {
+  const pa = String(a).split(".").map(Number);
+  const pb = String(b).split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+export function releaseOf(version) {
+  return RELEASES.find((r) => r.version === version) ?? null;
+}
+
+// Releases strictly newer than `fromVersion`, oldest-first — the changelog to show on update.
+export function releasesAfter(fromVersion) {
+  return RELEASES.filter((r) => cmpSemver(r.version, fromVersion) > 0);
+}

package/lib/stamp.mjs

@@ -0,0 +1,63 @@
+// The version stamp — `rafa.json` at the repo root records what versions this repo was
+// last provisioned/updated at. It is the compat anchor: `update` and `migrate` diff the
+// stamp against what the running CLI ships to know what changed and what to migrate FROM.
+// (Also holds platform identity fields when the repo was provisioned via a setup URL.)
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CURRENT, CLI_VERSION, RELEASES } from "./releases.mjs";
+
+export function stampPath(cwd) {
+  return join(cwd, "rafa.json");
+}
+
+export function readStamp(cwd) {
+  const f = stampPath(cwd);
+  if (!existsSync(f)) return {};
+  try {
+    return JSON.parse(readFileSync(f, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// Merge a patch into rafa.json without dropping existing keys (platform fields survive
+// a version bump; the `rafa` version block merges field-by-field).
+export function writeStamp(cwd, patch = {}) {
+  const cur = readStamp(cwd);
+  const next = {
+    ...cur,
+    ...patch,
+    rafa: { ...(cur.rafa ?? {}), ...(patch.rafa ?? {}) },
+  };
+  writeFileSync(stampPath(cwd), JSON.stringify(next, null, 2) + "\n");
+  return next;
+}
+
+// The versions this repo was last stamped at. Un-stamped repos predate the stamp (added in
+// 0.2.0), so default to the FIRST release's schema — never raise a false migration alarm.
+export function stampedVersions(cwd) {
+  const base = RELEASES[0];
+  const s = readStamp(cwd).rafa ?? {};
+  return {
+    cli: s.cli ?? base.version,
+    contract: s.contract ?? base.contract,
+    plans: s.plans ?? base.plans,
+  };
+}
+
+// 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

@@ -1,10 +1,18 @@
-// rafa update — re-sync the blueprint into this repo. shadcn-style: you own your
-// copies, so this is an opt-in refresh (run it to pull the latest agents,
-// capabilities, contract, and gates after upgrading the CLI).
+// rafa update — re-sync the blueprint into this repo. shadcn-style: you own your copies,
+// so this is non-destructive — tools + contract move to the latest, but your tuned
+// agents/capabilities are never clobbered (a changed one is written as `<file>.new`).
+//
+// It also makes the upgrade TRANSPARENT: it shows what changed since your last version,
+// and whether the change needs a re-scan (brain contract) or a `rafa migrate` (plan shape).
 
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
+import { reportBlueprint, reportSettings } 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() {
   const TARGET = process.cwd();
@@ -12,11 +20,64 @@ export default async function update() {
     console.error("✗ This repo isn't provisioned yet — run `rafa init` first.");
     process.exit(1);
   }
-  const written = copyBlueprint(blueprintSource(), TARGET);
-  console.log(`✓ rafa update — synced ${written.length} blueprint files:`);
-  for (const f of written) console.log(`    ${f}`);
+
+  // Where this repo is coming from (before we re-stamp).
+  const from = stampedVersions(TARGET);
+
+  await notifyIfBehind();
+
+  console.log("rafa update — syncing the blueprint (non-destructive)");
+  reportBlueprint(copyBlueprint(blueprintSource(), TARGET));
+  reportSettings(TARGET);
+
+  // ── 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  Release notes  (${from.cli} → ${CLI_VERSION}):`);
+    for (const r of news) console.log(`    ${r.version} — ${r.summary}`);
+  }
+
+  // ── 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 (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})`);
+  }
+
+  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);
+  }
+
+  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. " +
-      "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

@@ -0,0 +1,33 @@
+// Version awareness — tell the client, gently, when a newer rafinery is published. Fail
+// SILENT: a network hiccup or offline machine must never break `init`/`update`.
+
+import { cmpSemver, CLI_VERSION } from "./releases.mjs";
+
+const REGISTRY = "https://registry.npmjs.org/@rafinery/cli/latest";
+
+// The latest published version on npm, or null if it can't be determined quickly.
+export async function latestOnNpm(timeoutMs = 2500) {
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    const res = await fetch(REGISTRY, { signal: ctrl.signal });
+    clearTimeout(t);
+    if (!res.ok) return null;
+    const j = await res.json();
+    return typeof j.version === "string" ? j.version : null;
+  } catch {
+    return null;
+  }
+}
+
+// Print an upgrade nudge iff a strictly-newer version is published. Returns the latest
+// version (or null) so callers can decide whether to say more.
+export async function notifyIfBehind(installed = CLI_VERSION) {
+  const latest = await latestOnNpm();
+  if (!latest || cmpSemver(latest, installed) <= 0) return latest;
+  console.log(
+    `\n  ⬆ rafinery ${latest} is available (you're on ${installed}).\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.1.0",
+  "version": "0.2.1",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin",
     "lib",
-    "blueprint"
+    "blueprint",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"