ruvnet-brain 3.4.21-dev → 3.5.1-dev

package/README.md

@@ -4,10 +4,26 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 3.4.21-dev — updated 2026-07-20 03:20 EDT](https://img.shields.io/badge/version_3.4.21--dev-updated_2026--07--20_03:20_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 3.5.1-dev — updated 2026-07-21 06:00 EDT](https://img.shields.io/badge/version_3.5.1--dev-updated_2026--07--21_06:00_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 
+</div>
+
+> ## 🧭 North Star
+>
+> **rUv has built dozens of genuinely powerful capabilities that are effectively invisible — not undocumented, but _undiscovered_.** Ruflo's own docs call cross-project IPFS pattern transfer *"the substrate plugin's most underused capability."* The author knows people can't find his own work.
+>
+> **This project exists to close that gap** — a CTO on your shoulder that says *"you have this, it's off, here's what turning it on buys you."*
+>
+> **Retrieval was never the product. Proactive capability advocacy is the product.**
+>
+> The test we hold ourselves to: a developer who solves a hard problem with this tool and later learns they'd been sitting on a capability that would have made it trivial — that is a **failure of this project**, not of the user. Knowing which question to ask is the scarce thing; supplying that question is the job.
+>
+> Every feature is judged against this. If a surface can detect something useful and doesn't volunteer it, it is broken — see [ADR-027](docs/adr/0027-capability-advocacy-and-active-signals.md) and [DDD-0004](docs/ddd/0004-advocacy-context.md).
+
+<div align="center">
+
 [![plugin version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstuinfla%2Fruvnet-brain%2Fmain%2Fplugin%2F.claude-plugin%2Fplugin.json&query=%24.version&label=plugin&color=e8a13a&style=flat-square)](plugin/.claude-plugin/plugin.json)
 [![installer version](https://img.shields.io/npm/v/ruvnet-brain?label=installer%20%28npm%29&color=2e7d32&style=flat-square)](https://www.npmjs.com/package/ruvnet-brain)
 [![download](https://img.shields.io/badge/download-latest%20brain-2e7d32?style=flat-square)](https://github.com/stuinfla/ruvnet-brain/releases/latest)
@@ -40,7 +56,28 @@
 
 ---
 
-## What's new in 3.4 — the invisible work, made visible (and readable)
+## What's new in 3.5 — it stopped waiting to be asked
+
+**Shipped 2026-07-22.** For three weeks this thing had indexed rUv's entire learning stack — ReasoningBank, SONA, MoE, the ADR-174 distillation pipeline — and could have answered any question about any of it. It never once said the only sentence that mattered:
+
+> *"Your learning system is installed, and it is switched off."*
+
+Stuart found it himself. The measurement: **1,884 captured events sat undelivered** while the learner held 5 trajectories and hadn't trained in six days. Draining the queue took it to 412 in one command. Three weeks of learning had been sitting there, available for the asking, and nobody knew to ask.
+
+**That gap is the product.** A brain that waits to be asked is a search box with good manners. 3.5 is the version where it speaks first.
+
+- **It now tells you what you own and aren't using.** On the author's machine, unprompted, from a real scan: *"36 project stores are embedded but have never been distilled — 6,858 memories sitting in those stores, teaching nothing."* Every recommendation is built from what was actually **observed on your machine** — never a hardcoded list of cool features, which would rot the week rUv ships again.
+- **Detection without a remedy is now structurally impossible.** The console used to detect a corrupt memory store, score it 49/100, render it into a card, and offer nothing. Stuart's verdict: *"the fact that it didn't recommend a fix is unconscionable."* Every recommendation now carries evidence, a cost, a plain-English impact, and a **real, tested undo** — enforced by a factory that throws, not by a code review that can be skipped.
+- **It stopped lying in four specific ways.** It claimed `ruflo` wasn't installed to anyone whose npm prefix wasn't the author's. It answered *"nothing to undo"* about a database repair for which it held a backup. It reported a distillation that wrote 684 patterns as having done nothing (the check used a read-only connection that can't see another process's WAL). And its installer threw away the stderr that explained every crash — so a missing module and a slow download looked identical. All four found by running the thing rather than trusting it.
+- **Every offered fix is provably runnable and reversible.** The remedy registry makes the id→executor→inverse binding a single value, and a closure test drives the real builders to prove nothing can be *offered* that cannot be *run* and *undone*. It found that this ADR's own headline recommendation had **no executor at all** — it rendered as a button that answered "Unknown recommendation id." Proven to fail on both known-bad cases before being trusted.
+- **It stopped writing into your repos** ([#36](https://github.com/stuinfla/ruvnet-brain/issues/36)) and **stopped hiding the error that explains a failure** ([#37](https://github.com/stuinfla/ruvnet-brain/issues/37)) — both reported by users, both fixed at root cause, with an upstream report filed to rUv for the two bugs that turned out to be his.
+
+The honest limit: this is **3.5, not 4.0**. The advocacy surface is live and the engine behind it is proven, but score-delta alarms aren't built and ADR-027 has not yet survived its own required adversarial review. A major version marks the release where the product becomes a different thing to the person using it. This is the release where it starts talking.
+
+<details>
+<summary><b>Earlier &#8212; what 3.4 shipped</b> &#183; the invisible work, made visible and readable. <i>Expand for the receipts.</i></summary>
+
+## 3.4 — the invisible work, made visible (and readable)
 
 **Shipped 2026-07-17.** 3.3 made every card lead with a point. Then Stuart looked at the two pages meant to *teach* the stack and scored them 55/100: the graphics were mediocre, the one page that should show how the pieces fit was a wall of text, and two diagrams were literally unreadable. 3.4 is the fix — the harness's invisible work, finally drawn, and drawn so you can actually read it.
 
@@ -230,6 +267,7 @@ claude plugin install ruvnet-brain@ruvnet-brain --scope user
 
 Registers the `search_ruvnet` MCP tool, the grounding skill, and the `UserPromptSubmit` enforcement hook — globally, at user scope. The plugin expects the brain at `~/.cache/ruvnet-brain/kb` (or point `RUVNET_BRAIN_KB` at your own copy). The first install may show a one-time trust prompt for the hook.
 
+</details>
 </details>
 
 **Then just ask.** _“How does Ruflo orchestrate agent swarms, and what implements it?”_ The hook grounds the turn, Claude calls `search_ruvnet`, and it answers from cited source — down to the function body.
@@ -271,7 +309,7 @@ Plus: the **“take the wheel” behavioral pipeline** (below), a **4-level beha
 
 ## How it works
 
-The expensive work happens **once, at build time**: every covered repo is deep-walked (whole files, full function bodies, plus a symbol index), embedded into **two** vector variants (MiniLM-384 for edge/portability, bge-768 for depth) stored on-disk in **RVF / HNSW**, and distilled into a concepts + capability layer of per-repo primers and cards. That's **149,664 source chunks**. At **query time**, `search_ruvnet` searches every repo's store at once, pools the hits, and runs them through **one cross-encoder rerank** on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.
+The expensive work happens **once, at build time**: every covered repo is deep-walked (whole files, full function bodies, plus a symbol index), embedded into **two** vector variants (MiniLM-384 for edge/portability, bge-768 for depth) stored on-disk in **RVF / HNSW**, and distilled into a concepts + capability layer of per-repo primers and cards. That's **149,720 source chunks**. At **query time**, `search_ruvnet` searches every repo's store at once, pools the hits, and runs them through **one cross-encoder rerank** on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.
 
 ![RuvNet Brain architecture pipeline](assets/diagrams/architecture-pipeline.svg)
 
@@ -381,7 +419,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 54 public stores · 149,664 public source chunks (57 built stores incl. private), dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 54 public stores · 149,720 public source chunks (57 built stores incl. private), dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L4 all pass; private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/bin/install.mjs

@@ -73,6 +73,11 @@ const FLAG_ENABLE_NIGHTLY = argv.includes('--enable-nightly'); // schedule that
 const FLAG_DISABLE_NIGHTLY = argv.includes('--disable-nightly'); // remove the nightly schedule
 const FLAG_NO_NIGHTLY_PROMPT = argv.includes('--no-nightly-prompt'); // don't offer nightly auto-updates at the end of an install
 const FLAG_NO_TELEMETRY = argv.includes('--no-telemetry'); // decline anonymous usage counts without being asked
+// High-impact, so it needs its OWN flag — `-y` cannot install a launchd job (see ask()'s note).
+const FLAG_ENABLE_SPEND_GUARD = argv.includes('--enable-spend-guard');
+const FLAG_DISABLE_SPEND_GUARD = argv.includes('--disable-spend-guard'); // the missing undo
+const FLAG_UNINSTALL = argv.includes('--uninstall'); // reverse everything, in one command
+const FLAG_WHAT_CHANGED = argv.includes('--what-changed'); // show our footprint on this machine
 // ── onboarding-experience flags (all optional; every offer is safe to decline) ──
 const FLAG_YES = argv.includes('--yes') || argv.includes('-y'); // accept every optional offer non-interactively
 const FLAG_WITH_STACK = argv.includes('--with-stack'); // add missing Ruflo/RuVector without prompting
@@ -459,6 +464,28 @@ function installReader(cacheDir) {
   ok('reader installed');
 }
 
+// ── plugin presence: the ONLY reliable proof the slash commands will exist ───────────────────────
+// Reported by a user on 3.4.21-dev whose install was otherwise healthy: `/rvbc` returned
+// "Unknown command: /rvbc. Did you mean /rvf?". search_ruvnet worked, the KB was current — the
+// plugin had simply never landed, and the installer had said everything was fine.
+//
+// The brain ships as TWO independent artifacts and this is the one people lose:
+//   • KB + search_ruvnet  — installed by this script into ~/.cache/ruvnet-brain
+//   • the Claude Code plugin — slash commands, the Console, the grounding hook
+// Checking the commands directory on disk is what distinguishes them; a `claude plugin install`
+// exit code does not.
+/** @returns {string|null} the commands dir if the plugin is really installed, else null */
+function pluginCommandsDir() {
+  const candidates = [
+    path.join(os.homedir(), '.claude', 'plugins', 'marketplaces', 'ruvnet-brain', 'plugin', 'commands'),
+    path.join(os.homedir(), '.claude', 'plugins', 'ruvnet-brain', 'commands'),
+  ];
+  for (const dir of candidates) {
+    try { if (fs.existsSync(path.join(dir, 'rvbc.md'))) return dir; } catch { /* unreadable — treat as absent */ }
+  }
+  return null;
+}
+
 // ── step: wire the Claude Code plugin ────────────────────────────────────────────────────────────
 function wirePlugin() {
   step(
@@ -480,15 +507,30 @@ function wirePlugin() {
   }
 
   const addedMarket = tryRun('claude', ['plugin', 'marketplace', 'add', 'stuinfla/ruvnet-brain']);
-  if (!addedMarket) warn(`couldn't add the marketplace automatically (it may already be added — that's fine).`);
-
-  const installed = tryRun('claude', ['plugin', 'install', 'ruvnet-brain@ruvnet-brain', '--scope', 'user']);
-  if (installed) {
+  // Deliberately NOT reassuring here. This used to say "it may already be added — that's fine",
+  // which is a GUESS about someone else's machine, and when it was wrong the user finished the
+  // install with a working search_ruvnet, no slash commands, and a message telling them all was
+  // well. The real state is checked below; nothing is declared fine until it has been looked at.
+  if (!addedMarket) info(`marketplace add didn't report success — checking what actually landed…`);
+
+  tryRun('claude', ['plugin', 'install', 'ruvnet-brain@ruvnet-brain', '--scope', 'user']);
+
+  // NEVER take "installed" on faith — same discipline verifyInstall() applies to the KB. An exit
+  // code says the command ran, not that the plugin is usable; the commands either exist on disk or
+  // they do not. This is the difference between `/rvbc` working and "Unknown command: /rvbc".
+  const commandsDir = pluginCommandsDir();
+  if (commandsDir) {
     ok('plugin installed at user scope (global, alongside Ruflo / RuVector)');
+    info(`  commands available after a restart: ${c.bold('/rvbc')}, ${c.bold('/ruvnet-brain:configure')}`);
     return { wired: true, manualMarketplace, manualInstall };
   }
 
-  warn(`couldn't install the plugin automatically. Run these two commands yourself:`);
+  // The honest failure. The brain still WORKS — this is the difference between a broken install and
+  // a partial one, and the user is told exactly which they have instead of being congratulated.
+  warn(`the plugin did NOT land — so slash commands like ${c.bold('/rvbc')} will not exist yet.`);
+  info(`${c.green('Your brain still works')}: search_ruvnet is wired and Claude will ground answers with it.`);
+  info(`Only the plugin extras (slash commands, the Console, the grounding hook) are missing.`);
+  info(`Run these two yourself to finish:`);
   info(`  ${c.bold(manualMarketplace)}`);
   info(`  ${c.bold(manualInstall)}`);
   return { wired: false, manualMarketplace, manualInstall };
@@ -532,7 +574,10 @@ function verifyInstall(cacheDir) {
   if (mcp) ok('search_ruvnet server present (this is what Claude calls to ground answers)');
   else warn('forge-mcp-all.mjs missing — the brain unpacked incompletely');
 
-  return { repos, reader, mcp };
+  // Plugin presence is part of "what is really on disk" — it is the difference between `/rvbc`
+  // working and "Unknown command". A user whose plugin never landed had no way to see that.
+  const plugin = pluginCommandsDir() !== null;
+  return { repos, reader, mcp, plugin };
 }
 
 // ── step: warm the model + prove grounding with one real question (best-effort, never fatal) ──────
@@ -598,7 +643,26 @@ async function smokeQuery(cacheDir) {
   const out = `${r.stdout || ''}`;
   if (r.status !== 0 || !out.trim()) {
     warn('no answer came back (first-run model download or offline) — the brain is installed; it\'ll warm on your first real question');
-    return { ran: true, grounded: false, reason: 'no-answer' };
+    // SHOW THE ACTUAL ERROR (issue #37 bug 2, Agentist-Elder, 2026-07-21).
+    //
+    // This captured stderr and then threw it away, so every hard failure — a crash, a missing
+    // module, a bad model path — arrived looking identical to a slow first-run download. That is
+    // exactly how a total grounding outage (a static import of a module missing from the bundle,
+    // crashing before any model code ran) presented as the reassuring line above and cost the
+    // reporter a full debugging session to attribute. Their words, and they are right: this
+    // wrapper "will hide the *next* breakage too, whatever it is."
+    //
+    // A diagnostic that discards the diagnosis is worse than no diagnostic, because it reads as
+    // information. Print it. Truncated, because a stack trace is not a friendly install screen —
+    // but never hidden.
+    const err = `${r.stderr || ''}`.trim();
+    if (err) {
+      const lines = err.split('\n');
+      info(c.dim('  the reader reported:'));
+      for (const line of lines.slice(0, 12)) info(c.dim(`    ${line.slice(0, 200)}`));
+      if (lines.length > 12) info(c.dim(`    … ${lines.length - 12} more line(s)`));
+    }
+    return { ran: true, grounded: false, reason: 'no-answer', stderr: err.slice(0, 4000) };
   }
 
   const verifier = await loadCitationVerifier(cacheDir);
@@ -664,6 +728,12 @@ function runDemo() {
     const out = `${r.stdout || ''}`.trim();
     if (r.status !== 0 || !out) {
       warn(`no answer came back — the local model may still be warming up (run this again in a moment)`);
+      // Same discarded-diagnosis bug as smokeQuery() — see the note there (issue #37 bug 2).
+      const err = `${r.stderr || ''}`.trim();
+      if (err) {
+        info(c.dim('  the reader reported:'));
+        for (const line of err.split('\n').slice(0, 8)) info(c.dim(`    ${line.slice(0, 200)}`));
+      }
       continue;
     }
     // Show the top hit's actual citation (repo/path/title + the start of its real cited text) —
@@ -687,14 +757,20 @@ function runDemo() {
 }
 
 // ── token meter one-liner for --doctor (ADR-0011 token_cost_efficiency) ──────────────────────────
-// The hooks + MCP server append one JSON line per fire to .ruvnet-brain/token-ledger.jsonl in the
-// project they run in (see scripts/token-report.mjs for the full breakdown). This summarizes what
-// was MEASURED yesterday+today in the cwd --doctor is run from — measured bytes, estimated tokens
-// (bytes/4, stated as an estimate). Fail-silent by design: a meter problem never reddens a checkup.
+// The hooks + MCP server append one JSON line per fire to a SINGLE user-level ledger at
+// ~/.cache/ruvnet-brain/token-ledger.jsonl (see scripts/token-report.mjs for the full breakdown).
+// It used to be written per-CWD, which scattered hidden .ruvnet-brain/ directories through users'
+// project trees and dirtied their git status — issue #36. Each line now carries a `cwd` field, so
+// the per-project view survives without writing anything into a project.
+// Fail-silent by design: a meter problem never reddens a checkup.
 function meterSummaryLine() {
   try {
-    const ledger = path.join(process.cwd(), '.ruvnet-brain', 'token-ledger.jsonl');
-    if (!fs.existsSync(ledger)) return 'meter: no data yet (this project has no .ruvnet-brain/token-ledger.jsonl — it appears after the first hook/MCP fire)';
+    const canonical = path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'ruvnet-brain', 'token-ledger.jsonl');
+    const legacy = path.join(process.cwd(), '.ruvnet-brain', 'token-ledger.jsonl');
+    // Read the legacy per-project ledger only if it exists and the canonical one does not — an
+    // existing user's measurements should not disappear the day the location changes.
+    const ledger = fs.existsSync(canonical) || !fs.existsSync(legacy) ? canonical : legacy;
+    if (!fs.existsSync(ledger)) return 'meter: no data yet (appears after the first hook/MCP fire)';
     const since = new Date();
     since.setHours(0, 0, 0, 0);
     since.setDate(since.getDate() - 1); // start of yesterday, local time
@@ -727,6 +803,9 @@ async function doctor() {
   have('node') ? ok('node present') : warn('node missing');
   have('npm') ? ok('npm present') : warn('npm missing');
   have('claude') ? ok('claude CLI present') : warn('claude CLI missing (plugin wiring needs it)');
+  // Two independent version streams (KB bundle vs plugin wrapper) — see checkVersionDrift()'s
+  // header comment for the full story. Silent unless they've genuinely diverged.
+  reportVersionDrift(cacheDir);
   have('unzip') || have('pwsh') || have('powershell')
     ? ok('zip extraction available (unzip or PowerShell Expand-Archive)')
     : warn('no zip tool found — unzip or PowerShell needed for re-install');
@@ -802,6 +881,33 @@ async function doctor() {
 // no env — every field is generic. The user still writes and posts the actual feedback themselves.
 const DISCUSSIONS_URL = `https://github.com/${REPO}/discussions`;
 
+/**
+ * Compare two release tags. Returns >0 if a is newer, <0 if older, 0 if equal.
+ *
+ * Local to this file on purpose: bin/install.mjs is the ONLY file that runs before anything is
+ * installed, so it may not import from scripts/ (which isn't in the npm `files` list). Duplicating
+ * ~10 lines is the correct trade against an installer that cannot run.
+ *
+ * Prerelease handling matters here because every tag this project ships is `X.Y.Z-dev`. Numeric
+ * parts compare numerically (so 3.10.0 > 3.9.0, which a string compare gets backwards), and a
+ * release WITHOUT a prerelease suffix outranks the same numbers WITH one, per semver.
+ */
+function cmpTag(a, b) {
+  const parse = (v) => {
+    const [core, pre = ''] = String(v).replace(/^v/, '').split('-');
+    return { nums: core.split('.').map((n) => parseInt(n, 10) || 0), pre };
+  };
+  const A = parse(a), B = parse(b);
+  for (let i = 0; i < Math.max(A.nums.length, B.nums.length); i++) {
+    const d = (A.nums[i] || 0) - (B.nums[i] || 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;   // 3.5.0 is newer than 3.5.0-dev
+  if (!B.pre) return -1;
+  return A.pre > B.pre ? 1 : -1;
+}
+
 function installedBrainVersion(cacheDir) {
   // Same read the telemetry ping uses: the bundle stamps its Release tag into SOURCE.json.
   // "unknown" is honest for a locally-built or pre-stamping bundle — never guess a tag.
@@ -813,6 +919,79 @@ function installedBrainVersion(cacheDir) {
   return 'unknown';
 }
 
+// ── the OTHER version: the plugin WRAPPER's own plugin.json ──────────────────────────────────────
+// installedBrainVersion() above answers "what KB is on disk". This answers "what PLUGIN WRAPPER is
+// on disk" — a genuinely different artifact (hooks, skills, slash commands), updated on a genuinely
+// different schedule (see the drift note at checkVersionDrift() below). Reuses pluginCommandsDir()
+// — the ONE locator for "is the plugin really here" — instead of growing a second one: plugin.json
+// always lives one directory above commands/, in both layouts that function checks.
+function wrapperVersion() {
+  const commandsDir = pluginCommandsDir();
+  if (!commandsDir) return null; // plugin not installed — nothing to read, nothing to compare
+  try {
+    const p = path.join(path.dirname(commandsDir), '.claude-plugin', 'plugin.json');
+    const v = String(JSON.parse(fs.readFileSync(p, 'utf8')).version || '');
+    return /^[A-Za-z0-9._-]{1,32}$/.test(v) ? v : null; // present-but-unparsable = "don't know"
+  } catch { return null; }
+}
+
+/**
+ * The brain ships as TWO independently-versioned artifacts: the KB content bundle (self-updates
+ * nightly via forge-update.mjs + GitHub Releases) and the Claude Code PLUGIN WRAPPER (hooks,
+ * skills, slash commands), which updates ONLY when Claude Code itself pulls the marketplace git
+ * clone at ~/.claude/plugins/marketplaces/ruvnet-brain — NOT AT ALL if a user's
+ * ~/.claude/settings.json has "autoUpdate": false for that marketplace. They drift silently, and —
+ * this is the damaging part — the version a user is SHOWN always comes from the frozen wrapper,
+ * never the brain. Verified live on this machine 2026-07-20: KB SOURCE.json built today, wrapper
+ * plugin.json still 3.4.18-dev, nine commits behind origin/main, because autoUpdate was false. A
+ * user (Dr. Mark Allen) hit exactly this: KB current, wrapper still the June v0.5.0-dev build, and
+ * nothing anywhere told him the two had diverged.
+ *
+ * NEVER invent or guess a version — this project's hardest rule. Either side unresolved → null, and
+ * null is NEVER treated as drift: a locally-built or pre-stamping KB legitimately has no releaseTag
+ * (see installedBrainVersion's own comment above), and a plugin that simply isn't installed yet is
+ * a DIFFERENT, already-reported situation (wirePlugin / verifyInstall), not a version mismatch.
+ * Drift is reported ONLY when BOTH sides resolved to a real value AND those values differ.
+ *
+ * @returns {{wrapper: string|null, kb: string|null, drift: boolean}}
+ */
+function checkVersionDrift(cacheDir) {
+  const wrapper = wrapperVersion();
+  const kbRaw = installedBrainVersion(cacheDir); // already honest — 'unknown' rather than a guess
+  const kb = kbRaw === 'unknown' ? null : kbRaw;
+  // COMPARE NUMBERS, NOT NAMESPACES. The two sides are written by different writers in different
+  // formats: build-bundle stamps SOURCE.json.releaseTag as a git TAG (v-prefixed) while
+  // sync-version writes plugin.json.version as a bare SEMVER (no prefix). A raw !== is therefore
+  // ALWAYS true, so the first version of this check told every perfectly healthy user their install
+  // had drifted, and handed them a fix command that could never clear it. Caught by adversarial
+  // review, not by the tests — the test fixture used a v-prefixed plugin version that sync-version
+  // never produces, so an impossible input was green-lighting a false claim.
+  // Duplicated deliberately from scripts/version.mjs's stripTag(): this installer ships standalone
+  // on npm (package.json `files` excludes scripts/version.mjs) and imports node builtins ONLY, so
+  // it cannot import the canonical one. Same one-line rule, kept identical on purpose.
+  const stripV = (v) => String(v).replace(/^v/, '');
+  const drift = Boolean(wrapper && kb && stripV(wrapper) !== stripV(kb));
+  return { wrapper, kb, drift };
+}
+
+/**
+ * Shared narration for --doctor and --what-changed (via printFootprint). Silent whenever there is
+ * nothing actionable to say — matched versions, or either side not comparable — so this never adds
+ * noise to a healthy machine or a not-yet-fully-installed one. Speaks up only when the two
+ * artifacts have genuinely diverged, in plain, warm, non-alarming language (neither artifact is
+ * broken — they just update on different schedules), and always hands over the exact command to
+ * fix it — verified live against `claude plugin marketplace --help` (2026-07-20) before ever being
+ * printed here.
+ */
+function reportVersionDrift(cacheDir) {
+  const state = checkVersionDrift(cacheDir);
+  if (!state.drift) return state;
+  warn(`the brain (${c.bold(state.kb)}) and the Claude Code plugin (${c.bold(state.wrapper)}) have drifted apart —`);
+  info(`that's normal (they update on separate schedules) and neither one is broken. To bring the`);
+  info(`plugin up to date:  ${c.bold('claude plugin marketplace update ruvnet-brain')}  ${c.dim('(then restart Claude Code)')}`);
+  return state;
+}
+
 function installAgeLine(cacheDir) {
   // SOURCE.json's mtime is when the bundle last landed here (install or self-update) — say which.
   for (const f of ['SOURCE.json', 'forge-mcp-all.mjs']) {
@@ -831,7 +1010,7 @@ function feedbackHealthLines(cacheDir) {
   const env = detectEnvironment();
   const allGreen = s.repos > 0 && s.reader && s.mcp;
   return [
-    `${s.repos} repo stores on disk · reader ${s.reader ? 'ok' : 'MISSING'} · search_ruvnet ${s.mcp ? 'ok' : 'MISSING'}`,
+    `${s.repos} repo stores on disk · reader ${s.reader ? 'ok' : 'MISSING'} · search_ruvnet ${s.mcp ? 'ok' : 'MISSING'} · plugin ${s.plugin ? 'ok' : 'NOT INSTALLED (no /rvbc)'}`,
     `toolkit: Ruflo ${env.ruflo ? 'present' : 'not found'} · RuVector ${env.ruvector ? 'present' : 'not found'} · claude CLI ${env.claude ? 'present' : 'not found'}`,
     allGreen ? 'verdict: Healthy — installed and reachable' : 'verdict: Needs attention — re-run npx ruvnet-brain',
   ];
@@ -1132,6 +1311,247 @@ function enableSpendGuard() {
   return 'enabled';
 }
 
+/**
+ * Remove the spend watchdog. Mirrors disableNightly() exactly.
+ *
+ * This did not exist until 2026-07-20, which meant the watchdog was the one thing this installer
+ * could put on a machine with no supported way to take it back off. "Reversible" has to be a
+ * command someone can run, not a paragraph telling them which files to delete by hand — a user
+ * asking how to undo our changes should never need us to answer.
+ */
+function disableSpendGuard() {
+  printBanner('disable spend watchdog');
+  if (process.platform !== 'darwin') {
+    info('The spend-watchdog LaunchAgent is macOS-only, so nothing was scheduled here by this tool.');
+    return;
+  }
+  const plistPath = spendGuardPlistPath();
+  const scriptPath = spendGuardScriptPath();
+  const existed = fs.existsSync(plistPath);
+  if (TEST_MODE) {
+    warn('RUVNET_BRAIN_TEST=1 — skipping launchctl bootout (plist removal only)');
+  } else {
+    // Ignore failure: "not loaded" is the state we want anyway.
+    spawnSync('launchctl', ['bootout', `gui/${process.getuid()}/${SPEND_GUARD_LABEL}`], { stdio: 'ignore' });
+  }
+  let failed = false;
+  for (const p of [plistPath, scriptPath]) {
+    if (!fs.existsSync(p)) continue;
+    try { fs.rmSync(p); } catch (e) {
+      failed = true;
+      console.error(`\n${c.red("✗ couldn't remove:")} ${p} — ${e.message}`);
+      console.error(`  Remove it yourself:  rm ${p}`);
+    }
+  }
+  if (failed) process.exit(1);
+  if (existed) ok(`spend watchdog disabled — removed ${plistPath}`);
+  else ok('spend watchdog was already off — nothing to remove (safe to run any time)');
+}
+
+/**
+ * Everything this installer can leave on a machine, DERIVED from disk — never asserted.
+ *
+ * A user who wants out should not have to ask us which files to delete. That was the actual
+ * position the corporate-machine report left someone in: they had to reverse-engineer our
+ * footprint from a bug report. Anything listed here has a real undo next to it.
+ *
+ * @returns {{label:string, path:string, undo:string}[]}
+ */
+export function machineFootprint() {
+  const items = [];
+  const add = (label, p, undo) => { try { if (p && fs.existsSync(p)) items.push({ label, path: p, undo }); } catch { /* unreadable → not ours to claim */ } };
+
+  add('Brain bundle (knowledge base)', resolvedKbDir(), 'npx ruvnet-brain --uninstall');
+  if (process.platform === 'darwin') {
+    add('Nightly updater (LaunchAgent)', nightlyPlistPath(), 'npx ruvnet-brain --disable-nightly');
+    add('Spend watchdog (LaunchAgent)', spendGuardPlistPath(), 'npx ruvnet-brain --disable-spend-guard');
+    add('Spend watchdog script', spendGuardScriptPath(), 'npx ruvnet-brain --disable-spend-guard');
+  }
+  const cmds = pluginCommandsDir();
+  if (cmds) items.push({
+    label: 'Claude Code plugin',
+    path: path.dirname(cmds),
+    undo: 'claude plugin uninstall ruvnet-brain@ruvnet-brain',
+  });
+  const cmdPath = path.join(os.homedir(), '.claude', 'CLAUDE.md');
+  try {
+    if (fs.existsSync(cmdPath) && fs.readFileSync(cmdPath, 'utf8').includes(CLAUDE_MD_START)) {
+      items.push({ label: 'CLAUDE.md block (6 lines, between markers)', path: cmdPath, undo: 'npx ruvnet-brain --uninstall' });
+    }
+  } catch { /* unreadable */ }
+  add('Usage-counts preference', telemetryConsentPath(), 'delete this file');
+
+  // EVERYTHING ELSE THIS INSTALLER WRITES. The first version of this listed the KB bundle and
+  // little else — one artifact out of six — while the help text promised "exactly what RuvNet Brain
+  // has put on this machine" and uninstallAll() went on to print "Verified clean". That is the same
+  // position the corporate-machine reporter was left in, reproduced by the very feature written to
+  // prevent it. It also explains a user seeing ~5 GB used for a ~2 GB knowledge base: most of the
+  // footprint was never reported. Anything this installer can create belongs here, or the summary
+  // is a comfortable fiction.
+  add('Status-bar version script', path.join(os.homedir(), '.cache', 'ruvnet-brain', 'ruvnet-brain-statusline.cjs'),
+      'remove the statusLine entry in ~/.claude/settings.json, then delete this file');
+  add('Status-bar preference', path.join(telemetryStateDir(), '.statusline-pref'), 'delete this file');
+  add('Model-router files', path.join(os.homedir(), '.claude', 'model-router'),
+      'rm -rf ~/.claude/model-router');
+  // Config entries live INSIDE files the user owns, so they are reported as edits to review rather
+  // than as paths to delete — deleting someone's settings.json over one key would be indefensible.
+  try {
+    const settings = path.join(os.homedir(), '.claude', 'settings.json');
+    if (fs.existsSync(settings) && fs.readFileSync(settings, 'utf8').includes('ruvnet-brain')) {
+      items.push({ label: 'A statusLine entry in your settings.json', path: settings, undo: 'remove the "statusLine" entry that points at ruvnet-brain' });
+    }
+  } catch { /* unreadable — do not claim it */ }
+  try {
+    const claudeJson = path.join(os.homedir(), '.claude.json');
+    if (fs.existsSync(claudeJson) && fs.readFileSync(claudeJson, 'utf8').includes('ruvnet-brain')) {
+      items.push({ label: 'The search_ruvnet MCP server registration', path: claudeJson, undo: 'claude mcp remove ruvnet-brain --scope user' });
+    }
+  } catch { /* unreadable — do not claim it */ }
+
+  return items;
+}
+
+/** Print the footprint. Called at the end of an install so nobody is ever surprised later. */
+function printFootprint({ heading = 'What this put on your machine' } = {}) {
+  const items = machineFootprint();
+  if (!items.length) { info('Nothing from RuvNet Brain is currently installed.'); return items; }
+  console.log(`\n  ${c.bold(heading)}`);
+  for (const it of items) {
+    console.log(`    • ${it.label}`);
+    console.log(`      ${c.dim(it.path.replace(os.homedir(), '~'))}`);
+    console.log(`      ${c.dim(`undo: ${it.undo}`)}`);
+  }
+  console.log(`\n  ${c.dim('Remove all of it at once:')}  ${c.bold('npx ruvnet-brain --uninstall')}`);
+  // Same "two artifacts, one machine" story as --doctor — surfaced here too, since a footprint
+  // listing is exactly where a user would otherwise reasonably assume one version covers both.
+  // Silent unless they've genuinely diverged.
+  reportVersionDrift(resolvedKbDir());
+  return items;
+}
+
+/**
+ * Surgically remove ONLY our block from CLAUDE.md, leaving every other line exactly as it was.
+ * Backed up and written atomically, same as when it was added — taking something away is at least
+ * as sensitive as putting it there.
+ */
+function removeClaudeMdBlock() {
+  const p = path.join(os.homedir(), '.claude', 'CLAUDE.md');
+  let src = '';
+  try { src = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : ''; } catch { return 'unreadable'; }
+  // PAIR THE MARKERS PROPERLY. The first version took the FIRST start and the FIRST end, unpaired.
+  // Adversarial review proved that eats the user's file: a CLAUDE.md that merely MENTIONS the start
+  // marker in prose (entirely plausible — we print both marker strings to the console when adding
+  // the block) above a real installed block causes everything between the prose mention and the real
+  // block's end marker to be deleted. Their rules, silently gone, under a message saying "your
+  // content untouched".
+  //
+  // Take the LAST start that has an end after it, and the FIRST end after that start — the real
+  // block is the innermost well-formed pair. Anything we cannot pair confidently is left alone:
+  // refusing to edit is always better than removing the wrong span from a file we do not own.
+  const end = src.indexOf(CLAUDE_MD_END);
+  if (end === -1) return 'absent';
+  const start = src.lastIndexOf(CLAUDE_MD_START, end);
+  if (start === -1) return 'absent';
+
+  // Splice ONLY the block. The previous version also ran .replace(/\n{3,}/g,'\n\n') and stripped
+  // leading whitespace across the WHOLE document, which silently reformatted unrelated content —
+  // including collapsing blank lines inside fenced code blocks — while the docstring promised
+  // "every other line exactly as it was". Normalize only at the seam we actually cut.
+  const before = src.slice(0, start).replace(/\n{3,}$/, '\n\n');
+  const after = src.slice(end + CLAUDE_MD_END.length).replace(/^\n{3,}/, '\n\n');
+  const next = `${before}${after}`;
+  try {
+    const backup = `${p}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    fs.copyFileSync(p, backup);
+    const tmp = `${p}.ruvnet-tmp`;
+    fs.writeFileSync(tmp, next);
+    fs.renameSync(tmp, p);
+    return 'removed';
+  } catch { return 'failed'; }
+}
+
+/** Reverse everything, and PROVE it rather than claiming it. */
+function uninstallAll() {
+  printBanner('uninstall RuvNet Brain');
+  const before = machineFootprint();
+  if (!before.length) { ok('Nothing to remove — RuvNet Brain is not installed here.'); return; }
+
+  // SPLIT WHAT WE REMOVE FROM WHAT WE CANNOT. The first version printed one flat "This will remove:"
+  // list built from the whole footprint — including the Claude Code plugin and edits inside files
+  // the user owns, none of which this function touches. It then closed by admitting those same
+  // items still needed a manual step. One command contradicting itself inside a single run is
+  // exactly the sloppiness that makes people stop believing any of our output, so the promise is now
+  // scoped to what actually happens.
+  // Ours-by-construction directories and files are removed; things that live INSIDE a file the user
+  // owns (settings.json entries, the MCP registration) and the Claude Code plugin itself are not
+  // ours to delete, so they are handed over as commands.
+  const AUTO = new Set(['Brain bundle (knowledge base)', 'Nightly updater (LaunchAgent)',
+    'Spend watchdog (LaunchAgent)', 'Spend watchdog script', 'CLAUDE.md block (6 lines, between markers)',
+    'Model-router files', 'Status-bar version script', 'Status-bar preference', 'Usage-counts preference']);
+  const willRemove = before.filter((it) => AUTO.has(it.label));
+  const manual = before.filter((it) => !AUTO.has(it.label));
+
+  console.log(`  This will remove:`);
+  for (const it of willRemove) console.log(`    • ${it.label}  ${c.dim(it.path.replace(os.homedir(), '~'))}`);
+  if (!willRemove.length) console.log(`    ${c.dim('(nothing that this command removes automatically)')}`);
+  if (manual.length) {
+    console.log(`\n  ${c.bold('It will NOT remove these')} — they are not ours to delete, so you get the command instead:`);
+    for (const it of manual) console.log(`    • ${it.label}\n      ${c.dim(it.undo)}`);
+  }
+  console.log(`\n  ${c.dim('Your own CLAUDE.md content is preserved — only our marked block is taken out,')}`);
+  console.log(`  ${c.dim('and the file is backed up first.')}\n`);
+
+  if (process.platform === 'darwin') { disableNightly(); disableSpendGuard(); }
+
+  const claudeMd = removeClaudeMdBlock();
+  if (claudeMd === 'removed') ok('removed our block from ~/.claude/CLAUDE.md (your content untouched, backup saved)');
+
+  // NEVER rm -rf A PATH WE HAVE NOT PROVEN IS OURS. resolvedKbDir() honours $RUVNET_BRAIN_KB, which
+  // the docs encourage for custom install locations — so `RUVNET_BRAIN_KB=$HOME npx ruvnet-brain
+  // --uninstall` would have recursively deleted the user's home directory. Found by adversarial
+  // review. The asymmetry was already visible in this same file: runUpdate() refuses to act unless
+  // forge-update.mjs is present, precisely so it can never surprise someone. Uninstall skipped it.
+  //
+  // Proof-of-ownership: the directory must actually contain the reader we install. That is cheap,
+  // unspoofable in practice, and fails CLOSED — if we cannot prove it is a brain, we do not touch it
+  // and we say why.
+  const kb = resolvedKbDir();
+  const looksLikeBrain = kb && ['forge-ask.mjs', 'forge-mcp.mjs', 'SOURCE.json']
+    .some((marker) => { try { return fs.existsSync(path.join(kb, marker)); } catch { return false; } });
+  if (kb && fs.existsSync(kb) && !looksLikeBrain) {
+    warn(`refusing to delete ${kb.replace(os.homedir(), '~')} — it does not look like a brain bundle.`);
+    info(`  (no forge-ask.mjs / forge-mcp.mjs / SOURCE.json found there). Nothing was removed.`);
+    info(`  If that really is your brain, remove it yourself:  rm -rf ${kb.replace(os.homedir(), '~')}`);
+  } else if (kb && fs.existsSync(kb)) {
+    try { fs.rmSync(kb, { recursive: true, force: true }); ok(`removed the brain bundle (${kb.replace(os.homedir(), '~')})`); }
+    catch (e) { warn(`couldn't remove ${kb}: ${e.message}`); }
+  }
+
+  // The rest of what is ours by construction. Leaving these behind is how an "uninstalled" machine
+  // still shows gigabytes of us — 8 executables under ~/.claude/model-router, a statusline script
+  // that settings.json is still pointing at, and preference files. Each is removed only if it is
+  // inside a directory this installer creates, never a path the user chose.
+  for (const [label, target] of [
+    ['model-router files', path.join(os.homedir(), '.claude', 'model-router')],
+    ['status-bar script', path.join(os.homedir(), '.cache', 'ruvnet-brain', 'ruvnet-brain-statusline.cjs')],
+    ['status-bar preference', path.join(telemetryStateDir(), '.statusline-pref')],
+    ['usage-counts preference', telemetryConsentPath()],
+  ]) {
+    if (!fs.existsSync(target)) continue;
+    try { fs.rmSync(target, { recursive: true, force: true }); ok(`removed the ${label}`); }
+    catch (e) { warn(`couldn't remove ${target.replace(os.homedir(), '~')}: ${e.message}`); }
+  }
+
+  // PROOF, not a claim — re-derive the footprint and show what (if anything) survived.
+  const after = machineFootprint();
+  console.log('');
+  if (!after.length) { ok('Verified clean — nothing from RuvNet Brain remains.'); }
+  else {
+    warn('These need one more step (they are not ours to remove automatically):');
+    for (const it of after) console.log(`    • ${it.label} — ${c.bold(it.undo)}`);
+  }
+}
+
 // Exported (testable under RUVNET_BRAIN_IMPORT_ONLY=1, like offerNightly). Never throws — the caller
 // also guards, because a finished install must never be broken by an optional safety offer.
 export async function offerSpendGuard() {
@@ -1143,12 +1563,16 @@ export async function offerSpendGuard() {
     'One more safety net — a spend watchdog',
     'agentic tools can bill the paid API in the background; this alarm catches a runaway before it drains your card',
   );
-  info(`${c.bold('Strongly recommended:')} an hourly check that alerts you the moment an automated agent`);
-  info('fleet floods a project — the pattern that has quietly burned real money. Alert-only, never spends.');
-
-  if (!process.stdin.isTTY && !FLAG_YES) { info(`No terminal to prompt on — install it any time by re-running  ${c.bold('npx ruvnet-brain')}`); return 'recommended'; }
+  info(`${c.green('Recommended')} — an hourly check that alerts you the moment an automated agent fleet`);
+  info(`floods a project. That pattern has quietly burned real money. ${c.bold('Your call, and easy to undo.')}`);
+  info(`${c.dim('What it sets up:')} a small background job (a macOS LaunchAgent) that watches for the burst`);
+  info(`${c.dim('                 ')} pattern. ${c.bold('Alert-only — it never spends, and never changes your billing.')}`);
+  info(`${c.dim('If you skip:')}     nothing changes; add it later with  ${c.bold('npx ruvnet-brain --enable-spend-guard')}`);
+
+  // NOT gated on FLAG_YES — second launchd job, same rule as the nightly updater above.
+  if (!process.stdin.isTTY && !FLAG_ENABLE_SPEND_GUARD) { info(`No terminal to prompt on — install it any time with  ${c.bold('npx ruvnet-brain --enable-spend-guard')}`); return 'recommended'; }
   let yes = true;
-  if (!FLAG_YES) {
+  if (!FLAG_ENABLE_SPEND_GUARD) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const answer = await new Promise((resolve) => rl.question(`    ${c.cyan('?')} Install the spend watchdog? ${c.dim('[Y/n]')} `, resolve));
     rl.close();
@@ -1293,15 +1717,28 @@ export async function offerNightly() {
 
   info(`${c.bold('Recommended:')} your brain updates itself while you sleep — new repos, new gists, zero effort.`);
 
-  if (!process.stdin.isTTY && !FLAG_YES) {
+  // Recommend it, mean it, and still make declining feel completely fine. The goal is a user who
+  // understands what they're agreeing to — not one who is either scared off by a wall of caveats or
+  // nudged past a decision they'd have made differently. Both failures cost trust; only one is loud.
+  info(`${c.green('Recommended')} — rUv ships constantly, and this is how fixes reach you without you`);
+  info(`thinking about it. ${c.bold('Entirely your call, though')}, and easy to undo.`);
+  info(`${c.dim('What it sets up:')} a small background job (a macOS LaunchAgent) that checks each night`);
+  info(`${c.dim('                 ')} and downloads a fresher brain — signature-verified before anything is applied.`);
+  info(`${c.dim('If you skip:')}     nothing changes; update whenever you like with  ${c.bold('npx ruvnet-brain --update')}`);
+  info(`${c.dim('Turn it off:')}     ${c.bold('npx ruvnet-brain --disable-nightly')}  ${c.dim('(any time, no reinstall)')}`);
+
+  // NOT gated on FLAG_YES — see the high-impact consent note on ask(). A blanket `-y` means nobody is
+  // present to READ the explanation above, and an explanation nobody read is not consent. It takes the
+  // explicit --enable-nightly, or a human answering in a terminal.
+  if (!process.stdin.isTTY && !FLAG_ENABLE_NIGHTLY) {
     // No terminal to ask on (CI / piped install) — recommend clearly instead of prompting.
     info(`No interactive terminal here, so I won't prompt. Enable it any time with one command:`);
     info(`  ${c.bold('npx ruvnet-brain --enable-nightly')}`);
     return 'recommended';
   }
 
-  let yes = true; // --yes accepts every optional offer, this one included
-  if (!FLAG_YES) {
+  let yes = true;
+  if (!FLAG_ENABLE_NIGHTLY) {
     // Not ask(): its parser treats anything but y/yes as no. Here the DEFAULT is yes — only an
     // explicit n/no declines (parseNightlyAnswer holds that contract, and the tests hold it there).
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -1411,8 +1848,28 @@ export async function offerTelemetry(cacheDir) {
 }
 
 // ── tiny interactive yes/no — SAFE in non-TTY (returns the default; never blocks a piped install) ──
-function ask(question, def = false) {
-  if (FLAG_YES) return Promise.resolve(true);
+/**
+ * @param {string} question
+ * @param {boolean} def answer used when there is no terminal to ask on
+ * @param {{blanketYes?: boolean}} opts blanketYes:false means --yes does NOT answer this one
+ *
+ * HIGH-IMPACT CONSENT (2026-07-20). `--yes` is documented as "accept every optional offer", and it
+ * used to include the two changes nobody would call optional: installing a persistent LaunchAgent
+ * that pulls code from GitHub on a schedule, and editing a global config file. Reported by a user on
+ * a CORPORATE machine whose enterprise policy correctly blocked the plugin/MCP install but had no
+ * rule covering a launchd job — so the one thing that survived was the background daemon.
+ *
+ * It almost certainly arrived via an AI agent: hit an interactive prompt, cannot answer it, re-run
+ * with `-y`. Entirely reasonable behaviour, and with blanket consent it silently authorizes a
+ * daemon. rUv's own ADR-302 already says why this is wrong — "accepting the enrollment screen is
+ * not blanket authorization... four distinct decisions, each with its own consent, its own prompt
+ * moment, and its own record." We were violating his design inside our own installer.
+ *
+ * So: persistent background jobs and global-config edits require their OWN explicit flag. There is
+ * no combination of `-y` alone that installs a daemon.
+ */
+function ask(question, def = false, { blanketYes = true } = {}) {
+  if (FLAG_YES && blanketYes) return Promise.resolve(true);
   if (!process.stdin.isTTY) return Promise.resolve(def);
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const suffix = def ? c.dim('[Y/n]') : c.dim('[y/N]');
@@ -1552,31 +2009,65 @@ Prefer rUv-native primitives (RVF over Pinecone/pgvector, Ruflo over LangChain,
 Not sure it's active? Run \`npx ruvnet-brain --doctor\`.
 ${CLAUDE_MD_END}`;
 
-async function offerClaudeMd() {
+export async function offerClaudeMd() {
   if (FLAG_NO_ENHANCE) return;
   const p = path.join(os.homedir(), '.claude', 'CLAUDE.md');
   let existing = '';
   try { existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : ''; } catch { /* ignore */ }
-  if (existing.includes(CLAUDE_MD_START)) { return; } // already enhanced — idempotent, stay silent
+  if (existing.includes(CLAUDE_MD_START)) { return; } // already there — idempotent, stay silent
+
+  // DON'T ASK WHEN IT ADDS NOTHING. If the plugin is installed, its hooks already enforce grounding
+  // on every turn and this block is pure duplication — the old skip-branch message said exactly that
+  // out loud. Asking to edit the most sensitive file we touch, for a benefit the user already has,
+  // is how a helpful tool starts feeling invasive. So the question is only worth someone's attention
+  // when the plugin is absent, which is a real population (see the "Unknown command: /rvbc" report)
+  // but not the common one.
+  if (pluginCommandsDir()) return;
 
   step(
-    'Teaching your Claude to lean on the brain',
-    'a short note in your global CLAUDE.md so every session — in any project — knows to use it',
+    'Optional — a note in your global CLAUDE.md',
+    "so Claude leans on the brain in projects where the plugin's hooks aren't running",
   );
+  // Say precisely what changes on their disk, in their words, BEFORE asking. "Enhance your CLAUDE.md"
+  // is the kind of phrasing that makes a careful person assume the worst — and on a managed machine
+  // that file may be governed. Six lines at the bottom, markers, reversible, backed up: all of that
+  // is far less alarming than the vague version, and it happens to be the whole truth.
+  info(`Adds ${c.bold('6 lines to the BOTTOM')} of ${c.bold('~/.claude/CLAUDE.md')}, wrapped in`);
+  info(`  ${c.dim('<!-- ruvnet-brain:start -->')} … ${c.dim('<!-- ruvnet-brain:end -->')}`);
+  info(`Nothing already in the file is changed or removed. Delete the block any time.`);
+  info(`${c.green("We back the file up first")}, and re-running never adds it twice.`);
+  info(c.dim(`Honestly: if you install the plugin, you don't need this — its hooks already do it.`));
+
   const yes =
     FLAG_ENHANCE_CLAUDE_MD ||
-    (await ask(`Add a short RuvNet-Brain section to ${existing ? 'your' : 'a new'} ~/.claude/CLAUDE.md?`, false));
+    // blanketYes:false — editing a file THEY own is not something a blanket `-y` gets to decide.
+    (await ask('Add it?', false, { blanketYes: false }));
   if (!yes) {
-    info('skipped — the plugin hooks already enforce grounding every turn; this was just extra reinforcement');
+    info(`No problem, skipped — add it any time with  ${c.bold('npx ruvnet-brain --enhance-claude-md')}`);
     return;
   }
   try {
     fs.mkdirSync(path.dirname(p), { recursive: true });
+    // Back up before touching it — the same courtesy this installer already extends to settings.json,
+    // and this is the more sensitive file of the two.
+    let backup = null;
+    if (existing) {
+      backup = `${p}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+      fs.copyFileSync(p, backup);
+    }
     const next = existing ? `${existing.replace(/\s*$/, '')}\n\n${CLAUDE_MD_BLOCK}\n` : `${CLAUDE_MD_BLOCK}\n`;
-    fs.writeFileSync(p, next);
-    ok(`added a RuvNet-Brain section to ${p} ${c.dim('(marker-guarded — safe to re-run)')}`);
+    // ATOMIC write — temp sibling then rename. The content was always a pure append, but the old
+    // code rewrote the whole file in place, so an interruption (disk full, power loss) could leave
+    // a TRUNCATED CLAUDE.md. Fine 999 times out of 1000 and unforgivable the other time. This is the
+    // discipline rUv already applies to credential files (cognitum-seed cloud_key.rs: tmp → rename).
+    const tmp = `${p}.ruvnet-tmp`;
+    fs.writeFileSync(tmp, next);
+    fs.renameSync(tmp, p);
+    ok(`added 6 lines to the bottom of ${p}`);
+    if (backup) info(c.dim(`  your original is saved at ${backup}`));
+    info(c.dim(`  to remove: delete the block between the two ruvnet-brain markers`));
   } catch (e) {
-    warn(`couldn't update CLAUDE.md (${e.message}) — not important; the plugin hooks still enforce grounding`);
+    warn(`couldn't update CLAUDE.md (${e.message}) — your file is untouched, and this was optional anyway`);
   }
 }
 
@@ -1728,7 +2219,14 @@ export async function offerStatusline() {
   info(`Adds a small ${c.bold('"RuvNet Brain vX.Y.Z"')} segment, read live from your installed brain — it`);
   info(`updates itself the moment the brain updates. ${c.bold('Never overwrites an existing status line.')}`);
 
-  const interactive = process.stdin.isTTY || FLAG_YES || FLAG_STATUSLINE;
+  // FLAG_YES deliberately does NOT appear here. This writes ~/.claude/settings.json — a file the
+  // USER owns — and installs a script Claude Code then executes on EVERY PROMPT. An adversarial
+  // review caught that a blanket `-y` on a non-TTY still did both, which made the security fix in
+  // 9ad02f5 ("`-y` can no longer install a daemon or edit a global config file") FALSE as written:
+  // the two functions that commit gated were the two I happened to be thinking about, and this
+  // third one — higher-frequency persistent execution than the LaunchAgent — was never checked.
+  // Same footprint rule as everywhere else: their config, their explicit yes.
+  const interactive = process.stdin.isTTY || FLAG_STATUSLINE;
   if (!interactive) {
     // No terminal to ask on, and no explicit flag either — skip WITHOUT recording an answer, so a
     // future interactive (or flagged) run still gets a real chance to ask.
@@ -1737,7 +2235,7 @@ export async function offerStatusline() {
     return 'not-asked';
   }
 
-  const yes = FLAG_STATUSLINE || (await ask('Add a RuvNet Brain version segment to your Claude Code status bar?', false));
+  const yes = FLAG_STATUSLINE || (await ask('Add a RuvNet Brain version segment to your Claude Code status bar?', false, { blanketYes: false }));
 
   try {
     fs.mkdirSync(telemetryStateDir(), { recursive: true });
@@ -1853,6 +2351,14 @@ Usage:
   npx ruvnet-brain --enable-nightly    Schedule that update nightly at 03:47 — macOS LaunchAgent;
                               other platforms get the documented cron line. OFF by default.
   npx ruvnet-brain --disable-nightly   Remove the nightly schedule (safe to run any time)
+  npx ruvnet-brain --what-changed     Show exactly what RuvNet Brain has put on this machine,
+                              with the undo command for each piece
+  npx ruvnet-brain --uninstall        Remove all of it (bundle, LaunchAgents, and our CLAUDE.md
+                              block only — your own CLAUDE.md content is preserved and backed up)
+  npx ruvnet-brain --enable-spend-guard   Install the hourly runaway-agent spend alarm (alert-only)
+  npx ruvnet-brain --disable-spend-guard  Remove it (safe to run any time)
+  npx ruvnet-brain --enhance-claude-md    Add the 6-line RuvNet-Brain block to ~/.claude/CLAUDE.md
+                              (appended at the bottom between markers; your file is backed up first)
                               (a default install RECOMMENDS nightly and asks, defaulting to yes)
   node bin/install.mjs --no-nightly-prompt Don't offer nightly auto-updates at the end of the install
   node bin/install.mjs --no-telemetry      Decline anonymous usage counts without being asked
@@ -1891,6 +2397,14 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   if (FLAG_UPDATE) return runUpdate();
   if (FLAG_ENABLE_NIGHTLY) return enableNightly();
   if (FLAG_DISABLE_NIGHTLY) return disableNightly();
+  // Standalone, like the nightly pair above. Without these, the flags existed only as a way to
+  // pre-answer a prompt DURING a full install — so the copy telling someone to "add it later with
+  // npx ruvnet-brain --enable-spend-guard" would have kicked off an entire reinstall instead of the
+  // small targeted action they asked for. Promised in the UI, therefore real here.
+  if (FLAG_ENABLE_SPEND_GUARD) { enableSpendGuard(); return; }
+  if (FLAG_DISABLE_SPEND_GUARD) { disableSpendGuard(); return; }
+  if (FLAG_UNINSTALL) { uninstallAll(); return; }
+  if (FLAG_WHAT_CHANGED) { printBanner('what RuvNet Brain put on this machine'); printFootprint(); return; }
 
   printBanner('installer');
   console.log(c.dim("I'll set up the brain and the Claude Code plugin, explaining each step as I go.\n"));
@@ -1915,19 +2429,83 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
 
   const { cacheDir, isCustom } = resolveCacheDir();
 
+  // ── "ALREADY PRESENT" IS THE WRONG QUESTION — ask "already CURRENT" ──────────────────────────
+  //
+  // THE STALE-INSTALL TRAP, and the root cause of "users are still on 0.5". This used to skip the
+  // download whenever forge-mcp-all.mjs merely EXISTED — a pure file-existence check, no version
+  // anywhere in it. So a June v0.5 brain made `alreadyInstalled` true, the download was skipped,
+  // and the installer went on to print its success banner. Re-running the installer — the fix we
+  // ADVERTISE in recovery messages — refreshed the reader and the plugin wiring and left the actual
+  // brain untouched, forever. A closed trap: the advertised escape hatch was the thing that failed.
+  //
+  // The honest question is whether the installed brain is CURRENT, so that is what we now ask.
+  // Fail-safe by design: if the version cannot be resolved (offline, API rate limit) we keep the
+  // old skip behaviour rather than force a 2 GB download on someone with no network — but we SAY
+  // that is what happened, instead of implying everything is up to date.
   const alreadyInstalled = fs.existsSync(path.join(cacheDir, 'forge-mcp-all.mjs'));
+  let staleSkip = false;
+  let ahead = false;
+  let installedTag = null;
+  let latestTag = null;
+  let resolvedRelease = null;   // reused below so the release is resolved at most once
   if (alreadyInstalled && !FLAG_FORCE) {
-    step(
-      'Brain already present — skipping the download',
-      "it's already unpacked here; I'll just make sure the reader and plugin are wired (use --force to refetch)",
-    );
-    ok(`found an existing brain at ${cacheDir}`);
+    installedTag = installedBrainVersion(cacheDir); // 'unknown' when SOURCE.json has no releaseTag
+    try {
+      resolvedRelease = await resolveRelease();
+      // ONLY a genuine `latest` lookup counts as "what current means". resolveRelease() does NOT
+      // throw when the GitHub API fails — it returns the hardcoded known-good pin with
+      // source:'fallback'. Treating that as latest inverts this whole fix: a rate-limited lookup
+      // would report installed v3.4.21-dev "→ latest v2.9.0" and DOWNGRADE a perfectly current
+      // machine. (Caught by exercising the failure path against a 404 repo — the first version of
+      // this fix did exactly that.) A pinned/forced resolution is likewise the operator's explicit
+      // choice, not a staleness verdict, so neither drives this comparison.
+      latestTag = resolvedRelease && resolvedRelease.source === 'latest'
+        ? (resolvedRelease.tag_name || resolvedRelease.tag || null)
+        : null;
+    } catch { latestTag = null; }
+    const norm = (v) => (v == null || v === 'unknown' ? null : String(v).replace(/^v/, ''));
+    const a = norm(installedTag), b = norm(latestTag);
+    // BEHIND => download. SAME => skip. AHEAD => skip, and say so honestly.
+    //
+    // This was a bare `a !== b`, which treats "newer than the latest release" as staleness. Anyone
+    // running a pre-release or dev build — or who simply updated in the window before a release was
+    // cut — was told "Brain is out of date" and pushed through a 2 GB download that would DOWNGRADE
+    // them. Found 2026-07-22 the moment this repo's own version moved to 3.5.0-dev ahead of the
+    // 3.4.22-dev release: the installer immediately declared its own newest brain stale.
+    //
+    // stack-sync.mjs has modelled AHEAD as legal from the start ("AHEAD is legal and produces NO
+    // recommendation — that modelling choice is what makes the alpha-vs-latest downgrade war
+    // structurally impossible"). The installer never learned the same lesson. It has now.
+    ahead = Boolean(a && b && cmpTag(a, b) > 0);
+    staleSkip = Boolean(b && (a === null || (a !== b && !ahead)));
+  }
+
+  if (alreadyInstalled && !FLAG_FORCE && !staleSkip) {
+    if (latestTag && ahead) {
+      // Never silently imply equality when the user is AHEAD — that would be a small lie, and it is
+      // the one that hides a downgrade. Skipping is right; misdescribing why is not.
+      step('Brain already current — skipping the download', `installed ${installedTag} is NEWER than the latest release (${latestTag})`);
+      ok(`found an up-to-date brain at ${cacheDir} — nothing to download, and we will never downgrade you`);
+    } else if (latestTag) {
+      step('Brain already current — skipping the download', `installed ${installedTag} matches the latest release`);
+      ok(`found an up-to-date brain at ${cacheDir}`);
+    } else {
+      // Could not check. Say so plainly rather than letting silence imply "current".
+      step('Brain present — could not check for a newer one', 'the release lookup failed (offline or rate-limited)');
+      warn(`skipping the download WITHOUT verifying it is current. Installed: ${installedTag || 'unknown'}.`);
+      info(`When you have a connection:  ${c.bold('npx ruvnet-brain --update')}   ${c.dim('(or --force to refetch now)')}`);
+    }
   } else {
+    if (staleSkip) {
+      step('Brain is out of date — fetching the current release', `installed ${installedTag || 'unknown'} → latest ${latestTag}`);
+      info(`${c.dim('(the old installer skipped this whenever any brain was present, which is why stale installs never moved)')}`);
+    }
     // Resolve which Release to fetch BEFORE downloading. Skipped entirely on the --local path
     // (obtainBundle short-circuits to the repo's dist/ zip and never touches the network).
     const localZipPresent =
       FLAG_LOCAL || fs.existsSync(path.join(REPO_ROOT, 'dist', 'ruvnet-brain.zip'));
-    const release = localZipPresent ? null : await resolveRelease();
+    // Reuse the staleness check's resolution when it already ran — one network round-trip, not two.
+    const release = localZipPresent ? null : (resolvedRelease || await resolveRelease());
     const { zipPath, tmpDir, downloaded } = await obtainBundle(release);
     // Verify the Ed25519 signature BEFORE extracting a downloaded bundle into the user's config
     // (SEC-0010 #6 — trust root = keys/ruvnet-brain-signing.pub.pem shipped inside this package).
@@ -1986,6 +2564,12 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   try { await offerStatusline(); } catch { /* non-fatal — a status-bar nicety must never break the install */ }
 
   success({ cacheDir, isCustom, plugin, env, nightly });
+
+  // Close every install by stating, in one place, exactly what is now on their machine and how to
+  // take each piece back off. Someone reading this should never have to file a bug report to find
+  // out what we did — which is precisely the position the 2026-07-20 corporate-machine reporter was
+  // left in. Derived from disk, so it can only ever describe what is actually there.
+  try { printFootprint(); } catch { /* a summary must never break a finished install */ }
 })().catch((e) => {
   die(e && e.message ? e.message : String(e));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "3.4.21-dev",
+  "version": "3.5.1-dev",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {