ruvnet-brain 4.0.1 → 4.0.2

package/.claude-plugin/marketplace.json

@@ -1,5 +1,6 @@
 {
   "name": "ruvnet-brain",
+  "description": "Source-grounded RuvNet Brain integrations for Claude Code and Codex.",
   "owner": {
     "name": "Stuart Kerr"
   },

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.0.1 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.1-updated_2026--07--30_03:24_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 4.0.2 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.2-updated_2026--07--30_03:24_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.**
 
@@ -30,7 +30,7 @@
 [![explainer](https://img.shields.io/badge/▶%20see%20it%20live-isovision.ai%2Fruvnet--brain-e8a13a?style=flat-square)](https://isovision.ai/ruvnet-brain/)
 [![license](https://img.shields.io/badge/license-MIT-8ecae6?style=flat-square)](LICENSE)
 [![grounded](https://img.shields.io/badge/answers-cited%20rUv%20source-333?style=flat-square)](#testing--proof)
-[![coverage](https://img.shields.io/badge/coverage-32%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
+[![coverage](https://img.shields.io/badge/coverage-34%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
 
 > **One Brain generation everywhere.** npm, the GitHub tag/release, bundle manifests, source metadata, and checksum-bound RVF generations must share the same product version. Headline claims are regenerated and checked by the claims ledger (`scripts/claims-verify.mjs`); other numbers below are hand-stamped and dated:
 > - **`plugin`** (badge above) — the Claude Code plugin itself: SKILL.md, the grounding hooks, the MCP server. Read live from [`plugin/.claude-plugin/plugin.json`](plugin/.claude-plugin/plugin.json). Updates often — this is where behavior fixes land.
@@ -485,7 +485,7 @@ node plugin/test/run-tests.mjs                    # full plugin QA over real JSO
 | **L4 "orchestrate"** | **downgraded — measures speech, not obedience** | L4 asserts the hook's own injected prose contains required words (`must: ['take the wheel','SPARC','swarm',…]`). That proves **the brain spoke**. It cannot fail when the advice is read and ignored — which is the failure this product exists to prevent. Counterfactual replay against a brain-off control (ADR-058 §D4) is what will earn this row back |
 | **Plugin QA** | **60 / 60** | manifests, hook firing, MCP `initialize`/`tools/list`, capability battery |
 | **Clean-room install** | **3 / 3** | download the published bundle fresh → unzip → query → grounded, cited answers |
-| **Unit tests** | **2,327 passing, 169 todo** · 32% of ALL source covered | `npm run test:cov` regenerates both — the coverage floor fails CI if it slips (`claims:verify` re-derives the %, it is not a hand-typed badge). 32% is the honest number over every shipped file; the previous "75%" measured a hand-picked 8-file subset |
+| **Unit tests** | **2,327 passing, 169 todo** · 34% of ALL source covered | `npm run test:cov` regenerates both — the coverage floor fails CI if it slips (`claims:verify` re-derives the %, it is not a hand-typed badge). 34% is the honest number over every shipped file; the previous "75%" measured a hand-picked 8-file subset |
 | **Grounding proof** | `npx ruvnet-brain --doctor` | asks a real question, then checks the cited path really exists in the on-disk store; a citation that doesn't resolve is reported as **NOT grounded** |
 | **Held-out eval** | **grounded 100/100** · routed 63/80 | `npm run eval` — 120 frozen, hash-pinned questions across 5 strata, never used for tuning, graded on ground truth, never by a model |
 
@@ -522,7 +522,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** — 62 public stores · 151,033 public source chunks (69 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** — 63 public stores · 153,369 public source chunks (70 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–L3 all pass (**L4 downgraded — it measures that the brain spoke, not that anything listened**); private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/bin/install.mjs

@@ -95,6 +95,7 @@ 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
+const FLAG_WHATS_NEW = argv.includes('--whats-new'); // show curated major-release highlights
 // ── 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_PLAN = argv.includes('--plan') || argv.includes('--dry-run'); // show the interactive checklist, then exit — install NOTHING
@@ -598,6 +599,50 @@ function installReader(cacheDir) {
   ok('reader installed');
 }
 
+// The Console must survive the temporary npm/npx extraction directory. Before 4.0.2 its skills
+// searched a developer checkout, so `/rvbc` worked for maintainers and failed for clean users even
+// though installation was green. Persist the exact runtime shipped by the installer underneath the
+// installed KB: Node then resolves optional reader dependencies from `<cacheDir>/node_modules`, and
+// both Claude Code and Codex get one stable path with no source clone or second package install.
+export function installConsoleRuntime(cacheDir, sourceRoot = REPO_ROOT) {
+  const runtime = path.join(cacheDir, '.console-runtime');
+  const staged = `${runtime}.tmp-${process.pid}`;
+  const prior = `${runtime}.prior-${process.pid}`;
+  fs.rmSync(staged, { recursive: true, force: true });
+  fs.rmSync(prior, { recursive: true, force: true });
+  fs.mkdirSync(staged, { recursive: true, mode: 0o700 });
+
+  const required = [
+    ['console', 'console'],
+    ['scripts', 'scripts'],
+    ['plugin/scripts', 'plugin/scripts'],
+    ['kb/brain-profile.mjs', 'kb/brain-profile.mjs'],
+    ['bin/install.mjs', 'bin/install.mjs'],
+    ['package.json', 'package.json'],
+  ];
+  for (const [from, to] of required) {
+    const source = path.join(sourceRoot, from);
+    if (!fs.existsSync(source)) {
+      fs.rmSync(staged, { recursive: true, force: true });
+      throw new Error(`console runtime is incomplete: missing ${from}`);
+    }
+    const target = path.join(staged, to);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.cpSync(source, target, { recursive: true, force: true, preserveTimestamps: true });
+  }
+
+  if (fs.existsSync(runtime)) fs.renameSync(runtime, prior);
+  try {
+    fs.renameSync(staged, runtime);
+    fs.rmSync(prior, { recursive: true, force: true });
+  } catch (error) {
+    if (fs.existsSync(prior) && !fs.existsSync(runtime)) fs.renameSync(prior, runtime);
+    fs.rmSync(staged, { recursive: true, force: true });
+    throw error;
+  }
+  return path.join(runtime, 'scripts', 'onboarding-console.mjs');
+}
+
 // ── 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
@@ -856,6 +901,7 @@ export function wireCodexHost({
   serverDir = codexServerDir(),
   source = path.join(__dirname, '..', 'plugin', 'mcp', 'server.mjs'),
   hookWrapperSource = path.join(__dirname, '..', 'plugin', 'scripts', 'codex-hook-wrapper.mjs'),
+  runtimePreferencesSource = path.join(__dirname, '..', 'plugin', 'scripts', 'runtime-preferences.mjs'),
   hookWrapperPath = codexHookWrapperPath(codexDir),
   announce = true,
 } = {}) {
@@ -876,14 +922,21 @@ export function wireCodexHost({
     if (announce) warn('MCP structured-interface module missing from this bundle — Codex left untouched (non-fatal)');
     return { host: true, action: 'no-source' };
   }
+  if (!fs.existsSync(runtimePreferencesSource)) {
+    if (announce) warn('MCP runtime-preferences module missing from this bundle — Codex left untouched (non-fatal)');
+    return { host: true, action: 'no-source' };
+  }
   const serverPath = path.join(serverDir, 'server.mjs');
   const managedCliPath = path.join(serverDir, 'managed-cli-interface.mjs');
+  const runtimePreferencesPath = path.join(path.dirname(serverDir), 'scripts', 'runtime-preferences.mjs');
   fs.mkdirSync(serverDir, { recursive: true });
   // Write-beside-then-rename, both here and for the config below (issue #43): an interrupted plain
   // copy leaves a TORN server.mjs at the exact path a prior install's config already points at, so
   // Codex spawns half a file. rename() over the target is atomic; a failure leaves the old bytes.
   // Copy the dependency first. If the later server swap fails, the previously registered server
   // remains byte-intact and continues to import a backward-compatible module at the same path.
+  fs.mkdirSync(path.dirname(runtimePreferencesPath), { recursive: true });
+  atomicReplace(runtimePreferencesPath, (tmp) => fs.copyFileSync(runtimePreferencesSource, tmp));
   atomicReplace(managedCliPath, (tmp) => fs.copyFileSync(managedCliSource, tmp));
   atomicReplace(serverPath, (tmp) => fs.copyFileSync(source, tmp));
   if (fs.existsSync(hookWrapperSource)) {
@@ -899,7 +952,7 @@ export function wireCodexHost({
       ok('Codex already declares ruvnet-brain in your own config — left exactly as you wrote it');
       info(`  to hand it to us instead, delete that ${c.bold('[mcp_servers.ruvnet-brain]')} block and re-run this installer`);
     }
-    return { host: true, action, serverPath, managedCliPath, hookWrapperPath };
+    return { host: true, action, serverPath, managedCliPath, runtimePreferencesPath, hookWrapperPath };
   }
   if (text !== before) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
@@ -910,7 +963,7 @@ export function wireCodexHost({
     info(`  server: ${serverPath} ${c.dim('(persistent copy — the npx dir vanishes)')}`);
     info(`  ${c.dim('only our marked block is written; every other section is byte-preserved')}`);
   }
-  return { host: true, action, serverPath, managedCliPath, hookWrapperPath, changed: text !== before };
+  return { host: true, action, serverPath, managedCliPath, runtimePreferencesPath, hookWrapperPath, changed: text !== before };
 }
 
 const CODEX_PLUGIN_ID = 'ruvnet-brain@ruvnet-brain';
@@ -1553,7 +1606,9 @@ async function doctor() {
   if (env.ruflo) {
     rufloOperational = probeRufloOperationalHealth();
     if (rufloOperational.healthy) {
-      ok('Ruflo operational — runtime, memory, and learning signals agree');
+      ok(rufloOperational.directMode
+        ? 'Ruflo direct mode ready — daemon/swarm is stopped by design; AgentDB remains CLI-backed'
+        : 'Ruflo operational — runtime, memory, and learning signals agree');
     } else {
       warn('Ruflo CLI is present, but operational learning is DEGRADED — availability is not enforcement.');
       if (rufloOperational.stopped) warn('  live status reports STOPPED / swarm not running');
@@ -2421,6 +2476,18 @@ function printFootprint({ heading = 'What this put on your machine' } = {}) {
   return items;
 }
 
+function showWhatsNew() {
+  const notes = path.join(REPO_ROOT, 'docs', 'RELEASE-NOTES-4.0.md');
+  if (!fs.existsSync(notes)) {
+    console.error('RuvNet Brain release notes are missing from this artifact.');
+    process.exitCode = 1;
+    return;
+  }
+  const text = fs.readFileSync(notes, 'utf8');
+  process.stdout.write(text);
+  if (!text.endsWith('\n')) process.stdout.write('\n');
+}
+
 /**
  * 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
@@ -3070,8 +3137,15 @@ export function classifyRufloOperationalHealth({ status = '', memory = '', metri
     && /Total Routes\s*[|:]?\s*0\b/i.test(metrics)
     && /Total Executed\s*[|:]?\s*0\b/i.test(metrics);
   const memoryContradiction = statusSaysNoMemory && memoryEntries > 0;
+  // Brain 4 is explicitly zero-daemon: `ruflo memory store/search` open the per-project
+  // AgentDB directly. A stopped orchestration daemon therefore makes daemon-owned status
+  // and metrics non-authoritative; treating that intentional state as degraded made Doctor
+  // exit 1 immediately after proving source-grounded retrieval worked. Keep the strict
+  // contradiction/learning checks when a daemon is actually running.
+  const directMode = stopped;
   return {
-    healthy: !stopped && !memoryContradiction && !zeroLearning,
+    healthy: directMode || (!memoryContradiction && !zeroLearning),
+    directMode,
     stopped,
     zeroLearning,
     memoryContradiction,
@@ -3653,6 +3727,7 @@ Usage:
   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 --whats-new        Show the curated v3 → v4 capabilities and honest limits
   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)
@@ -3692,7 +3767,17 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
 
 // ── main ─────────────────────────────────────────────────────────────────────────────────────────
 (async () => {
-  if (IMPORT_ONLY) return; // imported for its exports (tests) — never run the installer as a side effect
+  // Importing an executable module for its exported policy helpers must never install software.
+  // The old contract required every caller to remember RUVNET_BRAIN_IMPORT_ONLY=1; one missed flag
+  // in a unit test ran a real install against the maintainer's HOME. Direct argv identity is the
+  // authority boundary. The old IMPORT_ONLY flag may still be present in a long-lived test worker;
+  // it must never suppress a genuinely direct CLI execution.
+  const canonical = (value) => {
+    try { return fs.realpathSync(value); } catch { return path.resolve(value); }
+  };
+  const invokedDirectly = Boolean(process.argv[1])
+    && canonical(process.argv[1]) === canonical(fileURLToPath(import.meta.url));
+  if (!invokedDirectly) return;
   if (FLAG_HELP) return showHelp();
   // `process.exitCode`, not `return` — doctor()'s verdict is the whole point of running it in a
   // script. A bare `return await doctor()` discarded the number, which is how "! Needs attention"
@@ -3711,6 +3796,7 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   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; }
+  if (FLAG_WHATS_NEW) { showWhatsNew(); return; }
 
   printBanner('installer');
   console.log(c.dim("I'll set up the brain for Claude Code and Codex, explaining each step as I go.\n"));
@@ -3856,6 +3942,15 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   }
 
   installReader(cacheDir);
+  try {
+    const consoleEntry = installConsoleRuntime(cacheDir);
+    ok(`Brain Console installed at ${consoleEntry}`);
+  } catch (error) {
+    die(
+      `the Brain Console runtime could not be installed (${error.message})`,
+      `The knowledge base is present, but /rvbc would be broken. Re-run the installer from a complete package.`,
+    );
+  }
   const plugin = wirePlugin();
   // Codex hosts got nothing before this (issue #42): shipped, never registered. Non-fatal like every
   // other wiring step — a second host we cannot reach must never break the one we can.

package/console/CONTRACT.md

@@ -0,0 +1,172 @@
+# Onboarding Console — API + data contract (v1)
+
+Updated: 2026-07-17
+Created: 2026-07-15
+
+The single source of truth both the backend (`scripts/onboarding-console.mjs`) and the
+frontend (`console/index.html` + `app.js` + `style.css`) build against. Implements ADR-0013
+and DDD-0002. **The ordering is the design: Mirror → Explain → Recommend → (consent) Apply → Undo.**
+
+The server binds `127.0.0.1` only and mints a random `token` per launch. Every mutating request
+must echo the token. The page receives the token inlined at render time (`window.__CONSOLE_TOKEN__`).
+A GET with a wrong/absent token still serves read-only state; a POST with a wrong token is `403`.
+
+---
+
+## GET `/api/state` — fast sections (no network)
+
+Returns in well under a second. `memory.fleet` is **`null` here by design** — scanning every memory
+store on the machine costs ~90ms each and a real machine has 100+, which is far too slow to sit in
+front of the page's first paint. The fleet arrives separately from `GET /api/memory`.
+
+`GET /api/state?fast=1` replays the last good gather from disk (~3ms) so a repeat load paints
+instantly, then the live call replaces it. The cached copy never contains `token` — that is minted
+per server run and spliced in on read.
+
+```jsonc
+{
+  "token": "…",
+  "generatedAt": "2026-07-14T…Z",
+  "host": { "user": "stuartkerr", "platform": "darwin", "node": "v22…", "npmPrefix": "~/.npm-global" },
+  "sections": {
+    "wiring": {
+      "summary": { "npx": 190, "global": 12, "mcp": 6, "plugin": 5, "projectsWithNpx": 16 },
+      "sites": [
+        { "scope": "project", "project": "ruvnet-brain", "file": ".claude/settings.json",
+          "event": "PreToolUse", "matcher": "Bash", "spec": "npx @claude-flow/cli@latest hooks …",
+          "mechanism": "NPX" }
+      ]
+    },
+    "memory": {
+      "fleet": [
+        { "name": "ruvnet-brain", "total": 1023, "embedded": 1021, "coverPct": 99.8,
+          "patterns": 456, "learns": true, "findings": [] }
+      ],
+      "health": {
+        "project": "ruvnet-brain", "score": 92, "summary": "learns; recall-quality not probed",
+        "dimensions": [
+          { "key": "liveness", "label": "Liveness", "status": "ok",
+            "detail": "store→search round-trip works on the live path", "deduction": 0 },
+          { "key": "coverage", "label": "Coverage", "status": "ok", "detail": "checkpoint present, <1d old", "deduction": 0 },
+          { "key": "recallQuality", "label": "Recall quality", "status": "notTested",
+            "detail": "no embedding round-trip run this session", "deduction": 0 },
+          { "key": "compactionSurvival", "label": "Compaction survival", "status": "ok",
+            "detail": "PreCompact snapshot present", "deduction": 0 },
+          { "key": "sessionSurfacing", "label": "Session surfacing", "status": "ok",
+            "detail": "SessionStart hook surfaces state", "deduction": 0 }
+        ],
+        "notTested": ["recallQuality"]
+      }
+    },
+    "savings": {
+      "totals": { "count": 3, "usdSaved": 0.42, "msSaved": 18400 },   // null ⇒ render "nothing measured yet"
+      "note": "receipts only — no modelled or projected savings",
+      "receipts": [
+        { "at": "2026-07-13T…Z", "capability": "model-routing", "task": "…",
+          "chosenTier": "haiku", "baselineTier": "opus", "measuredMs": 4200, "measuredUsd": 0.14 }
+      ]
+    },
+    "config": {
+      "path": "~/.claude/ruvnet-brain/config.json",
+      "exists": true,
+      "values": { "openrouterKey": true, "nightly": true, "routing": "auto", "qeFleet": false },
+      "schema": [
+        { "key": "openrouterKey", "label": "OpenRouter API key", "type": "secret",
+          "help": "Unlocks cheap-model routing + the self-improvement loop", "secret": true },
+        { "key": "nightly", "label": "Nightly brain refresh", "type": "bool",
+          "help": "Rebuild the KB from pinned SHAs overnight" },
+        { "key": "routing", "label": "Token-smart routing", "type": "enum",
+          "options": ["auto", "off"], "help": "Route cheap tasks to smaller models" },
+        { "key": "qeFleet", "label": "On-demand QE fleet", "type": "bool",
+          "help": "Agentic-QE test fleet, spun up on request" }
+      ]
+    },
+    "recommendations": [ /* Recommendation[] — non-stack, e.g. de-npx a project */ ]
+  }
+}
+```
+
+## GET `/api/memory` — the across-your-projects fleet scan (slow, ~7–10s)
+
+```jsonc
+{ "fleet": [ { "name": "ruvnet-brain", "total": 1023, "embedded": 1021, "coverPct": 99.8, … } ] }
+```
+
+Split out of `/api/state` so it cannot block first paint. The page renders memory health immediately
+and merges this list into the same card once it lands.
+
+## GET `/api/stack` — the network audit (slow, ~5–20s; page loads a skeleton first)
+
+```jsonc
+{
+  "packages": [
+    { "name": "ruflo", "installed": "3.30.2", "target": "3.30.2", "tag": "alpha", "state": "CURRENT" }
+    // state ∈ CURRENT | BEHIND | AHEAD | BROKEN | UNRESOLVED
+  ],
+  "shadows": [
+    { "name": "@ruvector/rvf", "version": "0.1.9", "global": "0.2.3", "dir": "~/.npm/_npx/…", "stale": true }
+  ],
+  "summary": { "total": 40, "behind": 0, "broken": 1, "ahead": 0, "current": 38, "shadows": 15, "stale": 15 },
+  "recommendations": [ /* Recommendation[] — sync BEHIND, purge stale shadows */ ]
+}
+```
+
+## Recommendation — the aggregate the whole page is built around
+
+**A Recommendation CANNOT exist without non-empty `evidence`, a `cost`, and an `undo`.** The
+backend factory throws otherwise (DDD invariant, schema-enforced). The UI must render all four.
+
+```jsonc
+{
+  "id": "sync-stack",
+  "title": "Sync 1 stale shadow of @ruvector/rvf",
+  "rationale": "A second copy in the npx cache preempts your global binary and quietly serves 0.1.9.",
+  "severity": "IMPORTANT",                       // INFO | SUGGESTED | IMPORTANT
+  "touchesMachine": true,                        // ⇐ if true, the UI MUST show plainImpact + require an explicit confirm
+  "plainImpact": "This removes an extra, out-of-date copy of a tool sitting in a temporary folder on your computer. Your main copy is newer and stays untouched. Nothing you use will stop working — the temporary copy rebuilds itself automatically the next time it's needed. Fully reversible.",
+  "evidence": [ { "observed": "@ruvector/rvf@0.1.9 in ~/.npm/_npx while global is 0.2.3", "source": "stack-sync findShadows" } ],
+  "cost": { "time": "~0s", "latency": "none", "usd": 0, "risk": "low" },
+  "change": { "kind": "run-script", "human": "purge the stale npx shadow", "cmd": "node scripts/stack-sync.mjs --sync" },
+  "undo":   { "kind": "restore-dir", "human": "npx re-resolves on next use; backup kept at <dir>.bak-<ts>" }
+}
+```
+
+**`touchesMachine` and `plainImpact` are load-bearing.** `touchesMachine: false` means the action
+only writes RuvNet-Brain's own settings file in your user folder and changes nothing about how your
+computer runs other software (e.g. Save Settings). `touchesMachine: true` means it installs, removes,
+or rewires something the rest of your system uses — those **must** render `plainImpact` (jargon-free,
+says what happens + why it's safe + that it's reversible) and a distinct "this changes your computer"
+confirm step before Apply is allowed. Write `plainImpact` for a smart person who has never heard of npx.
+
+## POST `/api/apply` — the ONLY writer (consent-gated)
+
+Request: `{ "token", "ids": ["sync-stack", …], "preStateHash": "…" }`
+Behavior (DDD Change Plan invariants): **re-read the world**, abort with `worldMoved` if `preStateHash`
+no longer matches, **record the inverse first**, back up every mutated file to `<file>.bak-<ts>`, then run.
+Response: `{ "results": [ { "id", "ok", "undoToken", "log" } ] }`
+
+## POST `/api/save-config` — save Settings at user level
+
+Request: `{ "token", "values": { … } }` → writes `~/.claude/ruvnet-brain/config.json`
+(backup first, undo recorded). Response: `{ "ok", "backup", "undoToken" }`
+
+## POST `/api/undo` — reverse a prior apply/save
+
+Request: `{ "token", "undoToken" }` → Response: `{ "ok" }`
+
+---
+
+## Section order on the page (progressive disclosure — each collapsible, each independently useful)
+
+1. **Your stack** — installed / current / duplicated / broken (from `/api/stack`)
+2. **How it's wired** — npx vs global, where (from wiring)
+3. **What we'd suggest** — the Recommendation cards (evidence · cost · undo · Apply/Skip)
+4. **Is your memory actually working?** — the 0–100 health score with named deductions
+5. **MetaHarness / Agentic-QE savings** — receipts only, or an honest "nothing measured yet"
+6. **Settings** — the editable form, one **Save** button, writes at user level
+
+## Design law (from ADR-0013)
+- Read-only by default. Opening the page changes nothing.
+- Existing choices are data, not errors. `AHEAD` is legal. `NPX` is shown with its tradeoff, never labelled "wrong".
+- Every number traces to a receipt or an observation. No "up to 90%". No estimates.
+- Nothing above `SUGGESTED` severity for anything not measured on THIS machine.