ruvnet-brain 1.6.2-dev → 1.16.0-dev

package/README.md

@@ -4,29 +4,33 @@
 
 # 🧠 RuvNet Brain
 
-### RuvNet Brain version 1.6.2-dev — updated 2026-07-05
+### 🧠 RuvNet Brain — [![RuvNet Brain version 1.16.0-dev — updated 2026-07-09 04:53 EDT](https://img.shields.io/badge/version_1.16.0--dev-updated_2026--07--09_04:53_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.**
 
 [![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-512MB%20brain-2e7d32?style=flat-square)](https://github.com/stuinfla/ruvnet-brain/releases/latest)
-[![explainer](https://img.shields.io/badge/▶%20see%20it%20live-ruvnet--brain.vercel.app-e8a13a?style=flat-square)](https://ruvnet-brain.vercel.app)
+[![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-10%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
 
 > **Three independent things version separately here — by design, not drift. Every number below is live (read straight from its real source, never hand-typed), so none of them can go stale:**
 > - **`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.
 > - **`installer (npm)`** (badge above) — the `npx ruvnet-brain` setup script. Read live from the [npm registry](https://www.npmjs.com/package/ruvnet-brain). Only moves when the installer script itself changes — rare.
 > - **Brain Release** (the downloadable 512MB knowledge bundle, linked from the "download" badge above) — always resolves to [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest), currently `v0.5.0-dev`. Only moves when the underlying knowledge base is rebuilt — separate again from the two above.
+> - **Update an installed brain once:** `npx ruvnet-brain --update` — runs the bundle's own self-updater (backs up first, re-verifies, fails loud instead of half-applying).
+> - **Nightly auto-update is OFF by default:** `npx ruvnet-brain --enable-nightly` schedules it (macOS LaunchAgent, 03:47); `npx ruvnet-brain --disable-nightly` removes it; Linux/Windows get the cron line documented in the bundle's `forge-update.mjs`.
+> - **Either way, your copy only advances when a new Release is published** — the updater pulls `releases/latest`, so running it between releases is a safe no-op.
 
 <sub>Built by **[Stuart Kerr](https://isovision.ai)** at [Isovision.ai](https://isovision.ai) · free & fair use, to help everyone leverage the high end of agentic coding.</sub>
 
-### [▶ Come see it visually explained](https://ruvnet-brain.vercel.app)
+### [▶ Come see it visually explained](https://isovision.ai/ruvnet-brain/)
 
 <sub>An interactive, animated walkthrough of what you can actually build — **click the preview** to open it.</sub>
 
-[![The RuvNet Brain interactive explainer — click to open the visual walkthrough](assets/explainer-preview.png)](https://ruvnet-brain.vercel.app)
+[![The RuvNet Brain interactive explainer — click to open the visual walkthrough](assets/explainer-preview.png)](https://isovision.ai/ruvnet-brain/)
 
 </div>
 
@@ -40,7 +44,7 @@ But **Claude was trained on _classical_ software development.** Point it at rUv'
 
 > **RuvNet Brain is the missing instruction manual.** It reads rUv's real source, hands Claude the _answer key_, and removes Claude's permission to make things up about the stack. Install it once, aim it at any repo, and a newcomer can build ~9 months ahead — without being rUv.
 
-The novelty is **enforcement, not retrieval.** Plain RAG only decides what to _add_ to context; it never stops a model from overriding good context with a stronger prior. This ships a `UserPromptSubmit` hook that injects a grounding directive on every RuvNet-relevant turn, consumed structurally by the harness — so grounding is **non-optional**. **RAG decides what to add; this decides what the model isn't allowed to make up.**
+The novelty is **structural grounding, not plain retrieval.** Plain RAG only decides what to _add_ to context. This ships a `UserPromptSubmit` hook that injects a grounding directive on **every** RuvNet-relevant turn — the harness consumes that stdout structurally, so the directive is _always present_, not a decline-able suggestion. It's a **strong, always-on nudge** — Claude is pointed at the real source and told to ground before asserting on every relevant turn — not a hard block on the model's output. **RAG decides what to add; this makes grounding the default the model has to actively argue its way out of.**
 
 ---
 
@@ -79,7 +83,7 @@ WITHOUT the brain — drift          |   WITH RuvNet Brain — grounded
 npx ruvnet-brain
 ```
 
-That single command runs the whole setup, narrating _what it's doing and why_ at each step: it downloads the brain (~512 MB) from the [latest GitHub Release](https://github.com/stuinfla/ruvnet-brain/releases/latest), unpacks it to `~/.cache/ruvnet-brain/kb`, installs its local reader (no cloud calls, no API keys), and wires the Claude Code plugin — the `search_ruvnet` MCP tool + the `UserPromptSubmit` grounding hook — at user scope. Works the same on **macOS, Linux, and Windows**. It's safe to re-run, and the brain itself always fetches the current Release regardless of which install path you use — you install once; you don't keep re-downloading.
+That single command runs the whole setup, narrating _what it's doing and why_ at each step: it downloads the brain (~512 MB) from the [latest GitHub Release](https://github.com/stuinfla/ruvnet-brain/releases/latest), unpacks it to `~/.cache/ruvnet-brain/kb`, installs its local reader (no cloud calls, no API keys), and wires the Claude Code plugin — the `search_ruvnet` MCP tool + the `UserPromptSubmit` grounding hook — at user scope. The installer and the `search_ruvnet` tool run on **macOS, Linux, and Windows**; the grounding/enforcement **hooks are POSIX shell**, so they fire on macOS, Linux, and Windows-via-WSL/Git-Bash (on native Windows without WSL the search tool still works, but the auto-grounding hooks don't fire — a Node port of the hooks is on the roadmap). It's safe to re-run, and the brain itself always fetches the current Release regardless of which install path you use — you install once; you don't keep re-downloading.
 
 > Want the bleeding-edge installer, even ahead of the last npm publish? `npx github:stuinfla/ruvnet-brain` always runs straight off the latest GitHub commit.
 
@@ -100,9 +104,21 @@ Registers the `search_ruvnet` MCP tool, the grounding skill, and the `UserPrompt
 
 ---
 
-## ✨ What's new in v0.5.0-dev — it now knows the stack _down to the code_
+## Staying current — how updates work
 
-Earlier versions knew the **docs and architecture**. v0.5.0-dev re-indexes the code-rich repos to **full function bodies**, against each repo's real source layout — so “how is this actually implemented?” returns the implementation, not a summary:
+You install once. After that, three mechanisms keep you on the current brain without you having to remember an update command.
+
+- **Consent-gated auto-update heartbeat** (the `SessionStart` hook, `plugin/scripts/session-start.sh`). The **first** time the plugin runs on a machine it asks you **once** whether it may keep itself updated in the background — a security-conscious opt-in, because self-update can change the model's own instructions. Your answer is remembered (`~/.cache/ruvnet-brain/.auto-update-pref`) and never asked again. On each session start it does a rate-limited (~15 min) 3s-capped check of the live GitHub `plugin.json`. If a newer plugin version exists **and** you opted in, it downloads it in the background through Claude Code's own trusted marketplace path — but the new version is **staged, not active**: Claude Code only loads plugins at process start, so **this session keeps running the version it started with** until you restart (`claude --continue` brings your conversation right back on the new version). If you declined, it just tells you the command to run. The 512 MB knowledge bundle is handled more conservatively — **detect + notify only**, never auto-applied, because the bundle isn't cryptographically signed yet and applying it would overwrite executable tool files (SEC-0010 #6).
+
+- **Stack watchdog status footer** (the `UserPromptSubmit` hook's always-on Gate 0, `plugin/scripts/ground-ruvnet.sh`). Every response ends with one dim status line — e.g. `🧠 RuvNet Brain v1.11.0-dev · Ruflo: yes · AgentDB memory: on` — read from **filesystem ground truth**, not impressions. The version shown is always the one **actually loaded in memory** for this session; if a newer version is staged awaiting a restart, the line says so plainly (`… vX staged, restart to load`). So you never have to wonder whether the brain is on, which version is acting, or whether project memory is wired.
+
+- **Nightly publish → `releases/latest` chain** (`scripts/self-update.mjs --publish`, run by the `deploy/com.ruvnet.brain-nightly.plist` LaunchAgent at 03:15). The nightly rebuilds only the repos whose upstream changed, and **if anything was rebuilt** it bumps the product version, cuts a GitHub Release, and advances [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest). Plugin and knowledge bundle move under **one** version number, so the heartbeat above picks up both automatically. (The LaunchAgent is not auto-installed — enabling a system scheduler needs explicit owner approval.)
+
+---
+
+## ✨ What the knowledge bundle knows — the stack _down to the code_
+
+Earlier bundles knew the **docs and architecture**. The current bundle re-indexes the code-rich repos to **full function bodies**, against each repo's real source layout — so “how is this actually implemented?” returns the implementation, not a summary:
 
 | Repo | Full-body code passages | |
 |---|---:|---|
@@ -130,7 +146,7 @@ The expensive work happens **once, at build time**: every covered repo is deep-w
 
 ## How it changes Claude's behavior — it takes the wheel
 
-Grounding is **enforced, not suggested.** On a RuvNet-relevant prompt the `UserPromptSubmit` hook injects a directive into context; Claude calls `search_ruvnet`, gets whole source files labeled by repo and path, and answers _from_ them. Because the hook's stdout is consumed by the harness every turn, it's structural — Claude can't quietly skip it.
+Grounding is **injected every turn, not left to chance.** On a RuvNet-relevant prompt the `UserPromptSubmit` hook injects a directive into context; Claude calls `search_ruvnet`, gets whole source files labeled by repo and path, and answers _from_ them. Because the hook's stdout is consumed by the harness every turn, the directive is _always there_ — a strong grounding nudge on every relevant turn. (It's a nudge, not a hard gate: the hook can't rewrite Claude's output, so it steers rather than blocks — see [ADR-0005](docs/adr/0005-behavioral-grounding-not-lock.md) for exactly what ships.)
 
 ![The grounding flow: prompt to cited answer](assets/diagrams/grounding-flow.svg)
 
@@ -191,9 +207,27 @@ node plugin/test/run-tests.mjs                    # full plugin QA over real JSO
 | **L1–L4 behavioral harness** | **all pass** | route · deep-recall (returns _code_) · implement (cites the API) · orchestrate (the hook drives the full pipeline) |
 | **Plugin QA** | **26 / 26** | manifests, hook firing, MCP `initialize`/`tools/list`, capability battery |
 | **Clean-room install** | **3 / 3** | download the published 512 MB bundle fresh → unzip → query → grounded, cited answers |
+| **Unit tests** | **208 passing** · 10% of ALL source covered | `npm run test:cov` — the floor fails CI if it slips. 10% 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 12/12** · routed 10/12 | `npm run eval` — 12 frozen questions never used for tuning, graded on ground truth, never by a model |
+
+<sub>The suite also carries **181 `it.todo` stubs** — a written backlog, each naming an untested behavior and what it would take to cover. They are deliberately **not** counted as tests: a stub proves nothing, and a number that flatters is worse than no number.</sub>
 
 Two honest residuals, not hidden: one described question (_“route to cheaper models to cut cost”_) still leans `ruflo` over `agentic-flow` (orchestration/cost overlap); one unnamed _“methodology”_ question routes to `synthlang` instead of `sparc`. Proof reports land in [`PROOF.md`](PROOF.md), [`DESCRIBED-PROOF.md`](DESCRIBED-PROOF.md), and [`HELIX-DEMO-NOHELIX.md`](HELIX-DEMO-NOHELIX.md).
 
+### The eval flywheel
+
+Most of the numbers above were tuned against. [`evals/held-out.json`](evals/held-out.json) was not: twelve questions phrased the way a newcomer would ask, each with the owning repo chosen **from first principles before the brain ever saw them**. `npm run eval` scores two things, both without asking a model's opinion:
+
+- **grounded** — the cited passage genuinely exists in the on-disk store. A path that doesn't resolve is a *fabricated* citation, and is counted as a failure however plausible it reads.
+- **routed** — the citation came from a repo that actually owns the capability.
+
+`npm run eval:gate` fails the build (exit 1) if either score drops below [`evals/baseline.json`](evals/baseline.json) — and also if there is **no baseline at all**, since you cannot promote against nothing. Baselines are only ever written deliberately, with `npm run eval:record`; a baseline that silently follows the code is a ratchet with no teeth.
+
+**Why not let an LLM grade it?** Because on this very repo an LLM panel scored a **zero-citation answer 98/100**. Model-as-judge is blind to the one failure that matters here.
+
+Current: **grounded 12/12, routed 10/12.** The two routing misses are recorded, not tuned away — `"generate tests and find coverage gaps"` cites agentic-qe's real test generator, which lives *vendored inside the ruflo repo*, so the answer is right and the repo label is a corpus-attribution artifact; `"spend less money on model calls"` cites a genuine `agentic-qe/docs/guides/cheaper-model-eval-lanes.md`, the same cost/orchestration overlap noted above.
+
 **Query it directly (CLI):**
 
 ```bash
@@ -208,7 +242,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 ## Honest status
 
-This is **`v0.5.0-dev`** — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
+This is a **`-dev`** project (see the live version 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** — ~21 building-block repos, 90,842 chunks, 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).
@@ -225,7 +259,7 @@ This is **`v0.5.0-dev`** — we don't claim “done,” “complete,” or “ze
 - `plugin/` — the Claude Code plugin (MCP server, grounding skill, `UserPromptSubmit` enforcement hook, marketplace manifest, test suite).
 - `scripts/` — `gate.sh` (routing gate), `behavioral-l1-l4.mjs` (behavioral harness), `prove.mjs`, `build-bundle.mjs`, `brain-stamp.mjs`.
 - `docs/` — [`VISION.md`](docs/VISION.md) (the why), [`adr/`](docs/adr/) (locked decisions incl. ADR-0008), [`DDD.md`](docs/DDD.md).
-- `explainer/` — the source of the [live explainer](https://ruvnet-brain.vercel.app).
+- `explainer/` — the source of the [live explainer](https://isovision.ai/ruvnet-brain/).
 - `SPEC.md` · `PROGRESS.md` — the master spec and the living, timestamped build log.
 
 The brain binaries ship via the [Release](https://github.com/stuinfla/ruvnet-brain/releases/tag/v0.5.0-dev), not git — a fresh clone is lightweight; `npx` fetches the 512 MB bundle.
@@ -234,7 +268,7 @@ The brain binaries ship via the [Release](https://github.com/stuinfla/ruvnet-bra
 
 ## Links
 
-- **▶ Live explainer:** https://ruvnet-brain.vercel.app
+- **▶ Live explainer:** https://isovision.ai/ruvnet-brain/
 - **Download / Release:** https://github.com/stuinfla/ruvnet-brain/releases/tag/v0.5.0-dev
 - **rUv's RuvNet org:** https://github.com/ruvnet
 - **Built by:** [Stuart Kerr — Isovision.ai](https://isovision.ai)

package/bin/install.mjs

@@ -16,8 +16,27 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import readline from 'node:readline';
+import crypto from 'node:crypto';
+
+// SEC-0010 #6 — the Ed25519 PUBLIC key is EMBEDDED here (not a separate file) so the installer's
+// trust root travels with the installer code itself: an attacker who swaps the downloaded bundle
+// cannot also swap the key the installer checks it against. Rotate via `node scripts/sign-bundle.mjs
+// --gen-key` and paste the new keys/…pub.pem here. Verify logic mirrors scripts/verify-bundle.mjs.
+const SIGNING_PUBKEY_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAgse9TAtehXUvUfTrJFY2CCHiCbmelR8yCgS//sen5/w=
+-----END PUBLIC KEY-----`;
+function verifyBundle(bundlePath, sigPath) {
+  try {
+    if (!fs.existsSync(bundlePath)) return { ok: false, reason: `bundle not found: ${bundlePath}` };
+    if (!fs.existsSync(sigPath)) return { ok: false, reason: `signature missing (fail-closed)` };
+    const digest = crypto.createHash('sha256').update(fs.readFileSync(bundlePath)).digest('hex');
+    const pub = crypto.createPublicKey(SIGNING_PUBKEY_PEM);
+    const ok = crypto.verify(null, Buffer.from(digest, 'hex'), pub, fs.readFileSync(sigPath));
+    return ok ? { ok: true, reason: `signature valid (sha256 ${digest.slice(0, 12)}…)` } : { ok: false, reason: 'signature does NOT match — bundle may be tampered' };
+  } catch (e) { return { ok: false, reason: `verify error: ${e.message}` }; }
+}
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..');
@@ -25,9 +44,16 @@ const REPO_ROOT = path.resolve(__dirname, '..');
 const REPO = 'stuinfla/ruvnet-brain';
 const RELEASE_API = `https://api.github.com/repos/${REPO}/releases/latest`;
 const ASSET_NAME = 'ruvnet-brain.zip';
-// Known-good fallback used when we can't reach GitHub (offline / rate-limited / no releases).
-// Default behavior is "get the latest"; this is only the safety net.
-const RELEASE_VERSION = 'v0.5.0-dev';
+// Known-good BUNDLE tag, used when we can't reach GitHub (offline / rate-limited / no releases),
+// and by --pin. Default behavior is "get the latest Release"; this is only the safety net.
+//
+// This MUST NOT be derived from this package's own version. The installer and the brain bundle are
+// two independent version streams (README: "Three independent things version separately here — by
+// design"). Reading it from package.json produced a tag that has never existed — installer 1.14.0-dev
+// asking for releases/download/v1.14.0-dev/ruvnet-brain.zip, which 404s, while the newest bundle
+// Release is v0.5.0-dev. Verified live: v1.14.0-dev → HTTP 404, v0.5.0-dev → HTTP 200. The safety net
+// was broken in exactly the situation it exists for. Bump this by hand when a new bundle ships.
+const RELEASE_VERSION = 'v0.5.0-dev'; // sync-version-ignore: the BUNDLE Release tag, not this package's version
 const fallbackUrl = (tag) => `https://github.com/${REPO}/releases/download/${tag}/${ASSET_NAME}`;
 const APPROX_SIZE = '~512MB';
 
@@ -39,6 +65,10 @@ const FLAG_DOCTOR = argv.includes('--doctor');
 const FLAG_NO_VERIFY = argv.includes('--no-verify');
 const FLAG_PIN = argv.includes('--pin'); // skip the latest-check, use the bundled default
 const FLAG_DEMO = argv.includes('--demo'); // guided, real (non-fabricated) walkthrough of the brain in action
+// ── freshness flags — invoke/schedule the SELF-UPDATER the bundle already ships (kb/forge-update.mjs) ──
+const FLAG_UPDATE = argv.includes('--update'); // one-shot: pull the latest Release bundle into the installed brain now
+const FLAG_ENABLE_NIGHTLY = argv.includes('--enable-nightly'); // schedule that update nightly (macOS LaunchAgent)
+const FLAG_DISABLE_NIGHTLY = argv.includes('--disable-nightly'); // remove the nightly schedule
 // ── 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
@@ -288,19 +318,31 @@ async function obtainBundle(release) {
   );
   info(`version: ${c.bold((release && release.tag) || RELEASE_VERSION)}`);
   info(`from: ${downloadUrl}`);
-  const tmp = path.join(os.tmpdir(), `ruvnet-brain-${process.pid}.zip`);
+  // Download into a PRIVATE, per-run temp DIR — never a predictable os.tmpdir()/ruvnet-brain-<pid>.zip
+  // filename (CWE-377: a guessable path invites a pre-created or symlinked file at that location to be
+  // clobbered, or the extraction target to be hijacked). mkdtempSync creates a fresh, unguessable,
+  // owner-only (0700) directory; we write the zip inside it. The exit handler guarantees the whole dir
+  // is removed on ANY exit — success, thrown error, or die()→process.exit — and the caller also removes
+  // it immediately on success so ~512MB isn't held for the rest of the install.
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-brain-'));
+  process.on('exit', () => { try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ } });
+  const tmp = path.join(tmpDir, ASSET_NAME);
   try {
     console.log(`    downloading the brain (${APPROX_SIZE})…`);
     await download(downloadUrl, tmp);
   } catch (e) {
-    try { fs.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
     die(
       `couldn't download the brain (${e.message}).`,
       `Check your connection, then re-run. Or, if you have a repo clone, build the bundle locally\n(${c.bold('node scripts/build-bundle.mjs')}) and run ${c.bold('node bin/install.mjs --local')}.`,
     );
   }
   ok(`downloaded to ${tmp}`);
-  return { zipPath: tmp, downloaded: true };
+  // Best-effort fetch of the detached Ed25519 signature published alongside the asset (SEC-0010 #6).
+  // If present we verify it before extracting; if absent (a pre-signing release) we warn but proceed
+  // (transitional — see SIGNING_REQUIRED at the verify gate).
+  try { await download(`${downloadUrl}.sig`, `${tmp}.sig`); } catch { /* no published sig yet */ }
+  return { zipPath: tmp, tmpDir, downloaded: true };
 }
 
 // ── step: unzip into the cache dir (flattening the top-level ruvnet-brain/ folder) ───────────────
@@ -379,14 +421,34 @@ function installReader(cacheDir) {
     die(`\`npm\` isn't available, but the brain needs it for its reader.`, `Install Node.js (which includes npm) and re-run.`);
   }
   info('installing the local reader…');
+  // Prefer `npm ci` for a PINNED, reproducible install when the bundle shipped its lockfile
+  // (SEC-0010 #8 — otherwise every install did a fully unpinned resolve). Fall back to `npm i`
+  // for older bundles that predate the shipped lockfile.
+  const hasLock = fs.existsSync(path.join(cacheDir, 'package-lock.json'));
+  const npmArgs = hasLock
+    ? ['ci', '--no-audit', '--no-fund', '--loglevel=error']
+    : ['i', '--no-audit', '--no-fund', '--loglevel=error'];
   try {
-    run('npm', ['i', '--no-audit', '--no-fund', '--loglevel=error'], {
+    run('npm', npmArgs, {
       cwd: cacheDir,
       // silence npm's "new version available" update-notifier so the narration stays clean
       env: { ...process.env, npm_config_update_notifier: 'false', npm_config_fund: 'false' },
     });
   } catch (e) {
-    die(`the reader install failed (${e.message}).`, `Re-run after checking your network / npm setup.`);
+    // `npm ci` is strict (fails if lock and package.json disagree); fall back to `npm i` once
+    // rather than hard-failing a user's install on a lockfile mismatch.
+    if (hasLock) {
+      warn(`pinned install (npm ci) failed (${e.message}); retrying with npm i`);
+      try {
+        run('npm', ['i', '--no-audit', '--no-fund', '--loglevel=error'], {
+          cwd: cacheDir, env: { ...process.env, npm_config_update_notifier: 'false', npm_config_fund: 'false' },
+        });
+      } catch (e2) {
+        die(`the reader install failed (${e2.message}).`, `Re-run after checking your network / npm setup.`);
+      }
+    } else {
+      die(`the reader install failed (${e.message}).`, `Re-run after checking your network / npm setup.`);
+    }
   }
   ok('reader installed');
 }
@@ -455,7 +517,37 @@ function verifyInstall(cacheDir) {
 }
 
 // ── step: warm the model + prove grounding with one real question (best-effort, never fatal) ──────
-function smokeQuery(cacheDir) {
+// ── BEGIN GENERATED: verify-citation.mjs (node scripts/embed-verifier.mjs) ──
+const VERIFY_CITATION_B64 = 'IyEvdXNyL2Jpbi9lbnYgbm9kZQovLyB2ZXJpZnktY2l0YXRpb24ubWpzIOKAlCBkZWNpZGUgd2hldGhlciBhbiBhbnN3ZXIgaXMgR1JPVU5ERUQsIGJ5IGdyb3VuZCB0cnV0aCByYXRoZXIgdGhhbiBieSB2aWJlcy4KLy8KLy8gV0hZIFRISVMgRVhJU1RTCi8vIC0tLS0tLS0tLS0tLS0tLQovLyBUaGUgb2xkIGdyb3VuZGluZyBjaGVjayBhc2tlZDogZG9lcyB0aGUgYW5zd2VyIGNvbnRhaW4gdGhlIHN0cmluZyAicnZmIiBvciAicnV2ZWN0b3IiPyBBIG1vZGVsCi8vIHRoYXQgaGFsbHVjaW5hdGVkICJqdXN0IHVzZSBSVkYhIiB3aXRoIHplcm8gc291cmNlcyBwYXNzZWQuIFNvIGRpZCBhbiBhbnN3ZXIgY2l0aW5nIGEgZmlsZSB0aGF0Ci8vIGRvZXMgbm90IGV4aXN0LiBLZXl3b3JkIHByZXNlbmNlIGlzIG5vdCBldmlkZW5jZSDigJQgYW4gTExNIHBhbmVsIG9uY2Ugc2NvcmVkIGEgemVyby1jaXRhdGlvbgovLyBhbnN3ZXIgOTgvMTAwIG9uIHRoaXMgcmVwby4KLy8KLy8gQSBjaXRhdGlvbiBpcyBvbmx5IHJlYWwgaWYgaXQgUkVTT0xWRVM6IHRoZSByZXBvIG11c3QgYmUgYW4gaW5kZXhlZCBzdG9yZSBvbiBkaXNrLCBhbmQgdGhlIGNpdGVkCi8vIGRvY3VtZW50IHBhdGggbXVzdCBhcHBlYXIgYXMgdGhlIGBwYXRoYCBvZiBhbiBhY3R1YWwgcGFzc2FnZSBpbnNpZGUgdGhhdCBzdG9yZSdzIHBhc3NhZ2VzIGZpbGUuCi8vIFRoYXQgaXMgY2hlY2thYmxlIHdpdGhvdXQgYSBtb2RlbCwgd2l0aG91dCB0aGUgbmV0d29yaywgYW5kIHdpdGhvdXQgdHJ1c3RpbmcgYW55dGhpbmcgdGhlIG1vZGVsCi8vIHNhaWQuIFRoaXMgbW9kdWxlIGRvZXMgZXhhY3RseSB0aGF0IGFuZCBub3RoaW5nIGVsc2UuCi8vCi8vIFRoZSByZWFkZXIgKGBmb3JnZS1hc2stYWxsLm1qc2ApIHByaW50cyBlYWNoIGhpdCBhczoKLy8gICAgICMxICByZXBvPWNvbmNlcHRzICBjZT0wLjIwMSAgdmVjPTAuODY4NiAga2luZD1kb2MKLy8gICAgIHBhdGggOiBjb25jZXB0cy9ydXZlY3Rvci9DQVJEL3J1dmVjdG9yLWNhcmQKLy8gICAgIHRpdGxlOiBydXZlY3RvciDigJQgQ2FwYWJpbGl0eQovLyBOb3RlIHRoZSBwcmludGVkIHBhdGggaXMgYDxyZXBvPi88ZG9jUGF0aD5gOyBpbnNpZGUgYGNvbmNlcHRzLnBhc3NhZ2VzLmpzb25sYCB0aGUgc3RvcmVkIGBwYXRoYAovLyBpcyBqdXN0IGBydXZlY3Rvci9DQVJEL3J1dmVjdG9yLWNhcmRgIChvcHRpb25hbGx5IHN1ZmZpeGVkIGAjMGAsIGAjMWAsIOKApiB3aGVuIGNodW5rZWQpLgoKaW1wb3J0IGZzIGZyb20gJ25vZGU6ZnMnOwppbXBvcnQgcGF0aCBmcm9tICdub2RlOnBhdGgnOwppbXBvcnQgcmVhZGxpbmUgZnJvbSAnbm9kZTpyZWFkbGluZSc7CgovKiogUGFyc2UgdGhlIHJlYWRlcidzIHN0ZG91dCBpbnRvIHN0cnVjdHVyZWQgY2l0YXRpb25zLiBOZXZlciB0aHJvd3M7IHVucGFyc2VhYmxlIGlucHV0IOKGkiBbXS4gKi8KZXhwb3J0IGZ1bmN0aW9uIHBhcnNlQ2l0YXRpb25zKHN0ZG91dCkgewogIGNvbnN0IG91dCA9IFtdOwogIGNvbnN0IHRleHQgPSBTdHJpbmcoc3Rkb3V0ID8/ICcnKTsKICBjb25zdCBibG9ja1JlID0gL14jKFxkKylccytyZXBvPShcUyspKD86XHMrY2U9KC0/W1xkLl0rKSk/KD86XHMrdmVjPSgtP1tcZC5dKykpPyg/OlxzK2tpbmQ9KFxTKykpPy9nbTsKICBsZXQgbTsKICB3aGlsZSAoKG0gPSBibG9ja1JlLmV4ZWModGV4dCkpICE9PSBudWxsKSB7CiAgICBjb25zdCByZXN0ID0gdGV4dC5zbGljZShtLmluZGV4KTsKICAgIGNvbnN0IHBhdGhNID0gL15wYXRoXHMqOlxzKiguKykkL20uZXhlYyhyZXN0KTsKICAgIGNvbnN0IHRpdGxlTSA9IC9edGl0bGVccyo6XHMqKC4rKSQvbS5leGVjKHJlc3QpOwogICAgaWYgKCFwYXRoTSkgY29udGludWU7CiAgICBjb25zdCByZXBvID0gbVsyXTsKICAgIGNvbnN0IGZ1bGxQYXRoID0gcGF0aE1bMV0udHJpbSgpOwogICAgLy8gU3RyaXAgdGhlIHJlcG8gcHJlZml4IHRoZSByZWFkZXIgYWRkcywgc28gdGhlIHJlbWFpbmRlciBjYW4gYmUgbWF0Y2hlZCBhZ2FpbnN0IHRoZSBzdG9yZS4KICAgIGNvbnN0IGRvY1BhdGggPSBmdWxsUGF0aC5zdGFydHNXaXRoKGAke3JlcG99L2ApID8gZnVsbFBhdGguc2xpY2UocmVwby5sZW5ndGggKyAxKSA6IGZ1bGxQYXRoOwogICAgb3V0LnB1c2goewogICAgICByYW5rOiBOdW1iZXIobVsxXSksCiAgICAgIHJlcG8sCiAgICAgIGNlOiBtWzNdICE9PSB1bmRlZmluZWQgPyBOdW1iZXIobVszXSkgOiBudWxsLAogICAgICB2ZWM6IG1bNF0gIT09IHVuZGVmaW5lZCA/IE51bWJlcihtWzRdKSA6IG51bGwsCiAgICAgIGtpbmQ6IG1bNV0gPz8gbnVsbCwKICAgICAgZnVsbFBhdGgsCiAgICAgIGRvY1BhdGgsCiAgICAgIHRpdGxlOiB0aXRsZU0gPyB0aXRsZU1bMV0udHJpbSgpIDogbnVsbCwKICAgIH0pOwogIH0KICByZXR1cm4gb3V0Owp9CgovKiogVGhlIHBhc3NhZ2VzIGZpbGVzIHRoYXQgY291bGQgaG9sZCBhIHJlcG8ncyBkb2N1bWVudHMg4oCUIHRoZSBzbGltIHN0b3JlIGFuZCB0aGUgZGVlcCBgLmJpZ2Agb25lLiAqLwpleHBvcnQgZnVuY3Rpb24gcGFzc2FnZXNGaWxlc0ZvcihyZXBvLCBrYkRpcikgewogIHJldHVybiBbcGF0aC5qb2luKGtiRGlyLCBgJHtyZXBvfS5wYXNzYWdlcy5qc29ubGApLCBwYXRoLmpvaW4oa2JEaXIsIGAke3JlcG99LmJpZy5wYXNzYWdlcy5qc29ubGApXQogICAgLmZpbHRlcigocCkgPT4gZnMuZXhpc3RzU3luYyhwKSk7Cn0KCi8qKiBUcnVlIHdoZW4gYHN0b3JlZGAgaXMgdGhlIGNpdGVkIGRvYywgYWxsb3dpbmcgZm9yIHRoZSBgI05gIGNodW5rIHN1ZmZpeCB0aGUgYnVpbGRlciBhcHBlbmRzLiAqLwpmdW5jdGlvbiBzYW1lUGF0aChzdG9yZWQsIGRvY1BhdGgpIHsKICByZXR1cm4gc3RvcmVkID09PSBkb2NQYXRoIHx8IHN0b3JlZC5zdGFydHNXaXRoKGAke2RvY1BhdGh9I2ApOwp9CgovKioKICogRG9lcyB0aGlzIGNpdGF0aW9uIHBvaW50IGF0IGEgcGFzc2FnZSB0aGF0IHJlYWxseSBleGlzdHMgb24gZGlzaz8KICogU3RyZWFtcyB0aGUgZmlsZSBhbmQgc3RvcHMgYXQgdGhlIGZpcnN0IG1hdGNoLCBzbyBhIDUwME1CIGAuYmlnYCBzdG9yZSBjb3N0cyBvbmx5IGFzIG11Y2ggYXMgaXQKICogdGFrZXMgdG8gcmVhY2ggdGhlIGhpdC4gQSBtYWxmb3JtZWQgSlNPTiBsaW5lIGlzIHNraXBwZWQsIG5ldmVyIGZhdGFsLgogKi8KZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGNpdGF0aW9uUmVzb2x2ZXMoY2l0YXRpb24sIGtiRGlyKSB7CiAgY29uc3QgZmlsZXMgPSBwYXNzYWdlc0ZpbGVzRm9yKGNpdGF0aW9uLnJlcG8sIGtiRGlyKTsKICBpZiAoIWZpbGVzLmxlbmd0aCkgcmV0dXJuIHsgcmVzb2x2ZWQ6IGZhbHNlLCByZWFzb246ICduby1zdG9yZScsIGZpbGU6IG51bGwsIHN0b3JlZFBhdGg6IG51bGwgfTsKICBmb3IgKGNvbnN0IGZpbGUgb2YgZmlsZXMpIHsKICAgIGNvbnN0IHJsID0gcmVhZGxpbmUuY3JlYXRlSW50ZXJmYWNlKHsgaW5wdXQ6IGZzLmNyZWF0ZVJlYWRTdHJlYW0oZmlsZSksIGNybGZEZWxheTogSW5maW5pdHkgfSk7CiAgICB0cnkgewogICAgICBmb3IgYXdhaXQgKGNvbnN0IGxpbmUgb2YgcmwpIHsKICAgICAgICBpZiAoIWxpbmUpIGNvbnRpbnVlOwogICAgICAgIGxldCByZWM7CiAgICAgICAgdHJ5IHsgcmVjID0gSlNPTi5wYXJzZShsaW5lKTsgfSBjYXRjaCB7IGNvbnRpbnVlOyB9CiAgICAgICAgaWYgKHR5cGVvZiByZWM/LnBhdGggPT09ICdzdHJpbmcnICYmIHNhbWVQYXRoKHJlYy5wYXRoLCBjaXRhdGlvbi5kb2NQYXRoKSkgewogICAgICAgICAgcmV0dXJuIHsgcmVzb2x2ZWQ6IHRydWUsIHJlYXNvbjogJ29rJywgZmlsZTogcGF0aC5iYXNlbmFtZShmaWxlKSwgc3RvcmVkUGF0aDogcmVjLnBhdGggfTsKICAgICAgICB9CiAgICAgIH0KICAgIH0gZmluYWxseSB7CiAgICAgIHJsLmNsb3NlKCk7CiAgICB9CiAgfQogIHJldHVybiB7IHJlc29sdmVkOiBmYWxzZSwgcmVhc29uOiAncGF0aC1ub3QtaW4tc3RvcmUnLCBmaWxlOiBudWxsLCBzdG9yZWRQYXRoOiBudWxsIH07Cn0KCi8qKgogKiBUaGUgZ2F0ZS4gQW4gYW5zd2VyIGlzIGdyb3VuZGVkIG9ubHkgd2hlbiBpdCBjaXRlcyBhdCBsZWFzdCBvbmUgcGFzc2FnZSB0aGF0IHJlc29sdmVzIG9uIGRpc2suCiAqIFJldHVybnMgdGhlIHJlY2VpcHQgc28gYSBjYWxsZXIgY2FuIFBSSU5UIHRoZSBldmlkZW5jZSBpbnN0ZWFkIG9mIGFzc2VydGluZyBhIGNvbmNsdXNpb24uCiAqLwpleHBvcnQgYXN5bmMgZnVuY3Rpb24gdmVyaWZ5R3JvdW5kaW5nKHN0ZG91dCwga2JEaXIpIHsKICBjb25zdCBjaXRhdGlvbnMgPSBwYXJzZUNpdGF0aW9ucyhzdGRvdXQpOwogIGlmICghY2l0YXRpb25zLmxlbmd0aCkgewogICAgcmV0dXJuIHsgZ3JvdW5kZWQ6IGZhbHNlLCByZWFzb246ICduby1jaXRhdGlvbnMnLCBjaXRhdGlvbnM6IFtdLCByZWNlaXB0OiBudWxsIH07CiAgfQogIGZvciAoY29uc3QgY2l0YXRpb24gb2YgY2l0YXRpb25zKSB7CiAgICBjb25zdCByID0gYXdhaXQgY2l0YXRpb25SZXNvbHZlcyhjaXRhdGlvbiwga2JEaXIpOwogICAgaWYgKHIucmVzb2x2ZWQpIHsKICAgICAgcmV0dXJuIHsKICAgICAgICBncm91bmRlZDogdHJ1ZSwKICAgICAgICByZWFzb246ICdvaycsCiAgICAgICAgY2l0YXRpb25zLAogICAgICAgIHJlY2VpcHQ6IHsgcmVwbzogY2l0YXRpb24ucmVwbywgcGF0aDogY2l0YXRpb24uZnVsbFBhdGgsIHRpdGxlOiBjaXRhdGlvbi50aXRsZSwgZmlsZTogci5maWxlLCBzdG9yZWRQYXRoOiByLnN0b3JlZFBhdGggfSwKICAgICAgfTsKICAgIH0KICB9CiAgcmV0dXJuIHsgZ3JvdW5kZWQ6IGZhbHNlLCByZWFzb246ICdjaXRhdGlvbnMtZG8tbm90LXJlc29sdmUnLCBjaXRhdGlvbnMsIHJlY2VpcHQ6IG51bGwgfTsKfQo=';
+// ── END GENERATED ──
+
+// The verifier belongs next to the data it verifies, so it lives in the KB. But every bundle
+// published before 2026-07-09 predates it, and telling those users "grounding not verifiable —
+// re-run the installer" would send them in a circle, because re-running fetches the same bundle.
+// So the installer CARRIES the verifier and writes it in when it's missing. A newer bundle's copy
+// always wins: we never overwrite a file the bundle shipped.
+function ensureVerifier(cacheDir) {
+  const p = path.join(cacheDir, 'verify-citation.mjs');
+  if (fs.existsSync(p)) return 'from-bundle';
+  if (!VERIFY_CITATION_B64) return 'unavailable';
+  try {
+    fs.writeFileSync(p, Buffer.from(VERIFY_CITATION_B64, 'base64').toString('utf8'), 'utf8');
+    return 'installed';
+  } catch { return 'unavailable'; }
+}
+
+async function loadCitationVerifier(cacheDir) {
+  ensureVerifier(cacheDir);
+  const p = path.join(cacheDir, 'verify-citation.mjs');
+  if (!fs.existsSync(p)) return null;
+  try { return await import(pathToFileURL(p).href); } catch { return null; }
+}
+
+// Proving grounding means proving the answer's CITATION RESOLVES — that the file it points at is a
+// real, indexed passage on this disk. The old check here tested `/rvf|ruvector|hnsw/` against the
+// answer text, which a hallucinated "just use RVF!" passes with zero sources. Keyword presence is
+// not evidence. We now print the cited path as a receipt, so you can go look at it yourself.
+async function smokeQuery(cacheDir) {
   const ask = path.join(cacheDir, 'forge-ask-all.mjs');
   if (!fs.existsSync(ask)) return { ran: false };
   step(
@@ -465,6 +557,7 @@ function smokeQuery(cacheDir) {
   const Q = 'How should I store embeddings in this project without running a server?';
   info(`Q: ${c.cyan(`"${Q}"`)}`);
   info(c.dim('(first run downloads a small local model once — this can take a minute)'));
+  const started = Date.now();
   let r;
   try {
     // Relative filename + matching cwd (NOT the absolute `ask` path) — forge-ask-all.mjs only runs
@@ -472,7 +565,7 @@ function smokeQuery(cacheDir) {
     // absolute path via spawnSync (no shell involved) that identity check silently fails on this
     // machine, so main() never runs — exit 0, zero stdout, zero stderr, no exception. Looks like a
     // clean success; is actually a total no-op. Verified: switching to a relative name + cwd fixes it.
-    r = spawnSync('node', ['forge-ask-all.mjs', '--dir', cacheDir, '--q', Q, '--k', '1'], {
+    r = spawnSync('node', ['forge-ask-all.mjs', '--dir', cacheDir, '--q', Q, '--k', '3'], {
       cwd: cacheDir,
       encoding: 'utf8',
       timeout: 240000,
@@ -482,15 +575,34 @@ function smokeQuery(cacheDir) {
     warn("skipped the live test (couldn't launch the reader) — it'll warm on your first real question");
     return { ran: false };
   }
+  const secs = ((Date.now() - started) / 1000).toFixed(1);
   const out = `${r.stdout || ''}`;
-  if (r.status === 0 && /\brvf\b|ruvector|hnsw|single[- ]file|no server/i.test(out)) {
-    ok("the brain answered from rUv's real source — grounding confirmed ✦");
-    return { ran: true, grounded: true };
+  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' };
+  }
+
+  const verifier = await loadCitationVerifier(cacheDir);
+  if (!verifier) {
+    info(`the brain answered in ${secs}s, but this bundle predates the citation verifier —`);
+    info(c.dim('  re-run `npx ruvnet-brain` to refresh it, and grounding will be PROVEN, not assumed'));
+    return { ran: true, grounded: null, reason: 'verifier-missing' };
+  }
+
+  const v = await verifier.verifyGrounding(out, cacheDir);
+  if (v.grounded) {
+    ok(`grounded in rUv's real source — verified in ${secs}s, not guessed ✦`);
+    console.log(`      ${c.dim('cited:')}    ${c.bold(v.receipt.path)}`);
+    if (v.receipt.title) console.log(`      ${c.dim('title:')}    ${v.receipt.title}`);
+    console.log(`      ${c.dim('verified:')} that passage really exists in ${c.bold(v.receipt.file)}`);
+    return { ran: true, grounded: true, receipt: v.receipt, secs };
   }
   warn(
-    "skipped the live test (first-run model download or offline) — the brain is installed; it'll warm on your first real question",
+    v.reason === 'no-citations'
+      ? 'the answer cited no source at all — NOT grounded (re-run the installer to repair the KB)'
+      : "the answer's citations don't resolve to any indexed passage — NOT grounded (KB may be corrupt; re-run the installer)",
   );
-  return { ran: true, grounded: false };
+  return { ran: true, grounded: false, reason: v.reason };
 }
 
 // ── `--demo`: a guided, REAL walkthrough — proves grounding live, never fabricates output ─────────
@@ -556,7 +668,7 @@ function runDemo() {
 }
 
 // ── `--doctor`: a standalone health check the user can run any time ───────────────────────────────
-function doctor() {
+async function doctor() {
   printBanner('doctor');
   console.log(c.dim('Checking every part of the install and reporting green/red.\n'));
   const cacheDir = process.env.RUVNET_BRAIN_KB || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'kb');
@@ -583,13 +695,25 @@ function doctor() {
     ? ok('RuVector present — vector CLI / MCP available')
     : warn('RuVector not found — answers still work. To add: claude mcp add ruvector --scope user -- npx -y ruvector mcp start');
   const v = verifyInstall(cacheDir);
-  smokeQuery(cacheDir);
+  const smoke = await smokeQuery(cacheDir);
   const allGreen = v.repos > 0 && v.reader && v.mcp;
   console.log(
     `\n  ${allGreen ? c.green('✓ Healthy.') : c.yellow('! Needs attention.')} ${
       allGreen ? 'The brain is installed and reachable.' : 'Re-run the installer to fix the warnings above.'
     }`,
   );
+  // Installed-and-reachable and actually-grounded are different claims. Keep them separate, so a
+  // healthy install can never be mistaken for proven grounding.
+  if (smoke.grounded === true) {
+    console.log(`  ${c.green('✓ Grounding PROVEN.')} It answered from ${c.bold(smoke.receipt.path)} — a passage that`);
+    console.log(`    really exists in your local KB. Checked in ${smoke.secs}s, no cloud, no API key.`);
+  } else if (smoke.grounded === false) {
+    console.log(`  ${c.yellow('! Grounding NOT proven')} (${smoke.reason}). The install is present but the brain did not`);
+    console.log('    answer from a verifiable source. Re-run  npx ruvnet-brain  to repair the KB.');
+  } else if (smoke.grounded === null) {
+    console.log(`  ${c.yellow('! Grounding not verifiable')} on this bundle — it predates the citation verifier.`);
+    console.log('    Re-run  npx ruvnet-brain  to refresh, then --doctor will prove it.');
+  }
   if (allGreen) {
     console.log(`\n  ${c.bold('What this means for you:')}`);
     console.log(`    • ${c.bold('It works in EVERY project')} — user-level (global). Open Claude Code in any repo or VS Code`);
@@ -605,6 +729,163 @@ function doctor() {
   );
 }
 
+// ── `--update` / `--enable-nightly` / `--disable-nightly`: end-user freshness controls ────────────
+// The brain bundle SHIPS its own self-updater (forge-update.mjs, right in the KB dir): it pulls the
+// canonical Release bundle, backs the current copy up, extracts, and re-verifies with forge-guard —
+// failing loud with no partial clobber. These flags never reimplement any of that; they only INVOKE
+// it once (--update) or SCHEDULE it per-user (--enable-nightly). Nothing here ever publishes.
+const NIGHTLY_LABEL = 'com.ruvnet.brain-update';
+const resolvedKbDir = () =>
+  process.env.RUVNET_BRAIN_KB || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'kb');
+const nightlyPlistPath = () =>
+  path.join(os.homedir(), 'Library', 'LaunchAgents', `${NIGHTLY_LABEL}.plist`);
+// RUVNET_BRAIN_TEST=1 → write/remove the plist but NEVER call launchctl. Tests point HOME at a temp
+// dir; bootstrapping a temp-dir plist into the user's real gui domain would mutate exactly the
+// system state the tests promise not to touch.
+const TEST_MODE = process.env.RUVNET_BRAIN_TEST === '1';
+const xmlEscape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// The same nightly command, cron-flavored — the pattern forge-update.mjs documents in its header.
+// 03:47 on purpose: an off-hour minute, so it never piles onto the :00 cron rush.
+const cronExample = (kbDir) =>
+  `47 3 * * *  cd ${kbDir} && ${process.execPath} forge-update.mjs --apply >> ${kbDir}/update.log 2>&1`;
+
+function missingUpdaterHelp(kbDir) {
+  console.error(`\n${c.red('✗ can\'t update:')} ${c.bold('forge-update.mjs')} is missing from ${kbDir}.`);
+  console.error(`  Either no brain is installed there, or the bundle predates the self-updater.`);
+  console.error(`  Fix: re-run the installer —  ${c.bold('npx ruvnet-brain')}  ${c.dim('(add --force if a brain is already present)')}`);
+  console.error(`  — the current bundle ships forge-update.mjs; then this command will work.`);
+}
+
+function runUpdate() {
+  printBanner('update');
+  const kbDir = resolvedKbDir();
+  info(`brain dir: ${c.bold(kbDir)}`);
+  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
+    missingUpdaterHelp(kbDir);
+    process.exit(1);
+  }
+  info(c.dim("running the bundle's own self-updater (backs up first, re-verifies, never half-applies)…\n"));
+  // Relative filename + matching cwd — same launch convention as smokeQuery(); stdio:'inherit'
+  // streams the updater's narration live and unedited.
+  const r = spawnSync(process.execPath, ['forge-update.mjs', '--apply'], { cwd: kbDir, stdio: 'inherit' });
+  if (r.error) {
+    console.error(`\n${c.red('✗ update failed to launch:')} ${r.error.message}`);
+    process.exit(1);
+  }
+  process.exit(r.status === null ? 1 : r.status); // exit with the updater's own verdict
+}
+
+function enableNightly() {
+  printBanner('enable nightly updates');
+  const kbDir = resolvedKbDir();
+
+  if (process.platform !== 'darwin') {
+    info('The LaunchAgent scheduler is macOS-only (for now).');
+    info("On this platform, schedule the bundle's self-updater with cron — the pattern");
+    info('forge-update.mjs itself documents:');
+    console.log(`\n    ${c.bold(cronExample(kbDir))}\n`);
+    info(`(${c.bold('crontab -e')}, paste the line, save. Remove the line to disable.)`);
+    return; // exit 0 — the user got the working recipe
+  }
+
+  info(`brain dir: ${c.bold(kbDir)}`);
+  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
+    // Refuse to schedule a job that is guaranteed to fail every night — fail loud NOW instead.
+    missingUpdaterHelp(kbDir);
+    process.exit(1);
+  }
+
+  // Template the plist to THIS user's kb dir + node binary. Quotes guard paths with spaces;
+  // xmlEscape guards the XML (>> and && must survive as shell operators after plist parsing).
+  const logPath = path.join(kbDir, 'update.log');
+  const shellCmd = `cd "${kbDir}" && "${process.execPath}" forge-update.mjs --apply >> "${logPath}" 2>&1`;
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${NIGHTLY_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>-c</string>
+    <string>${xmlEscape(shellCmd)}</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key>
+    <integer>3</integer>
+    <key>Minute</key>
+    <integer>47</integer>
+  </dict>
+  <key>RunAtLoad</key>
+  <false/>
+</dict>
+</plist>
+`;
+  const plistPath = nightlyPlistPath();
+  try {
+    fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+    fs.writeFileSync(plistPath, plist);
+  } catch (e) {
+    console.error(`\n${c.red('✗ couldn\'t write the LaunchAgent:')} ${e.message}`);
+    process.exit(1);
+  }
+  ok(`wrote ${c.bold(plistPath)}`);
+  info(c.dim('runs nightly at 03:47 — an off-hour minute, so it never lands on the :00 rush'));
+
+  if (TEST_MODE) {
+    warn('RUVNET_BRAIN_TEST=1 — skipping launchctl bootout/bootstrap (plist written only)');
+  } else {
+    const uid = process.getuid();
+    // bootout first so re-running replaces the loaded job cleanly; failure just means "wasn't loaded".
+    spawnSync('launchctl', ['bootout', `gui/${uid}/${NIGHTLY_LABEL}`], { stdio: 'ignore' });
+    const boot = spawnSync('launchctl', ['bootstrap', `gui/${uid}`, plistPath], { encoding: 'utf8' });
+    if (boot.status === 0) ok('LaunchAgent loaded — your brain now updates while you sleep');
+    else {
+      warn(`launchctl bootstrap failed (${(boot.stderr || '').trim() || `exit ${boot.status}`}) — the plist is in place;`);
+      info(`load it yourself:  ${c.bold(`launchctl bootstrap gui/${uid} ${plistPath}`)}`);
+    }
+  }
+
+  console.log(`\n  ${c.bold('Verify it:')}   launchctl list | grep ${NIGHTLY_LABEL}`);
+  console.log(`  ${c.bold('Watch it:')}    tail ${logPath}   ${c.dim('(appears after the first nightly run)')}`);
+  console.log(`  ${c.bold('Disable it:')}  npx ruvnet-brain --disable-nightly`);
+  console.log(`\n  ${c.dim('It only ever PULLS the published Release bundle (backup + re-verify built in) — it never publishes,')}`);
+  console.log(`  ${c.dim('and a night with no new Release is a clean no-op.')}\n`);
+}
+
+function disableNightly() {
+  printBanner('disable nightly updates');
+  if (process.platform !== 'darwin') {
+    info('The LaunchAgent nightly is macOS-only, so nothing was scheduled here by this tool.');
+    info(`If you added the cron line yourself, remove it with:  ${c.bold('crontab -e')}`);
+    return;
+  }
+  const plistPath = nightlyPlistPath();
+  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 exactly the state we want anyway.
+    spawnSync('launchctl', ['bootout', `gui/${process.getuid()}/${NIGHTLY_LABEL}`], { stdio: 'ignore' });
+  }
+  if (existed) {
+    try {
+      fs.rmSync(plistPath);
+    } catch (e) {
+      console.error(`\n${c.red('✗ couldn\'t remove the LaunchAgent:')} ${e.message}`);
+      console.error(`  Remove it yourself:  rm ${plistPath}`);
+      process.exit(1);
+    }
+    ok(`nightly updates disabled — removed ${plistPath}`);
+  } else {
+    ok('nightly updates were already off — nothing to remove (safe to run any time)');
+  }
+  info(`re-enable any time:  ${c.bold('npx ruvnet-brain --enable-nightly')}`);
+}
+
 // ── 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);
@@ -829,9 +1110,14 @@ function success({ cacheDir, isCustom, plugin, env }) {
     • Want to see it answer, live, right now?  ${c.bold('npx ruvnet-brain --demo')}  — 2 real questions, real cited answers.`);
 
   console.log(`\n  ${c.bold('Set it up your way:')} this default is ${c.bold('global')} — live in every VS Code project automatically,`);
-  console.log(`    which is what most people want. Want it different (project-only, moved, with the build stack added,`);
-  console.log(`    auto-updating nightly)? ${c.bold('Just tell Claude')} once it's on — the brain is smart enough to reconfigure`);
-  console.log(`    itself. You never have to learn its internals.`);
+  console.log(`    which is what most people want. Want it different (project-only, moved, with the build stack`);
+  console.log(`    added)? ${c.bold('Just tell Claude')} once it's on. You never have to learn its internals.`);
+
+  console.log(`\n  ${c.bold('Staying current:')} nightly updates are ${c.bold('OFF by default')} — nothing runs on your machine unasked.`);
+  console.log(`    • one-shot check + update now:   ${c.bold('npx ruvnet-brain --update')}`);
+  console.log(`    • nightly at 03:47 (macOS):      ${c.bold('npx ruvnet-brain --enable-nightly')}   ${c.dim('· off again: --disable-nightly')}`);
+  console.log(`    • Linux/Windows: the cron line documented in the brain's own ${c.bold('forge-update.mjs')}`);
+  console.log(`    ${c.dim('Either way, your copy only advances when a new Release is actually published.')}`);
 
   console.log(`\n  ${c.dim('You can\'t break anything — the plugin is disable-able and only acts on RuvNet-shaped work.')}`);
   console.log('');
@@ -849,6 +1135,11 @@ Usage:
   npx github:stuinfla/ruvnet-brain         Same, but from the bleeding-edge GitHub commit
   npx ruvnet-brain --doctor   Health-check an existing install (green/red per part)
   npx ruvnet-brain --demo     Guided walkthrough — 2 real questions, real cited answers
+  npx ruvnet-brain --update   One-shot: pull the latest Release bundle into your installed brain
+                              (runs the bundle's own forge-update.mjs --apply: backup + re-verify)
+  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)
   node bin/install.mjs --version <tag>     Install a specific Release tag (e.g. --version v0.4.0-dev)
   node bin/install.mjs --pin               Skip the latest-check; use the bundled known-good version
   node bin/install.mjs --local             Install from a repo clone's dist/ruvnet-brain.zip
@@ -870,8 +1161,11 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
 // ── main ─────────────────────────────────────────────────────────────────────────────────────────
 (async () => {
   if (FLAG_HELP) return showHelp();
-  if (FLAG_DOCTOR) return doctor();
+  if (FLAG_DOCTOR) return await doctor();
   if (FLAG_DEMO) return runDemo();
+  if (FLAG_UPDATE) return runUpdate();
+  if (FLAG_ENABLE_NIGHTLY) return enableNightly();
+  if (FLAG_DISABLE_NIGHTLY) return disableNightly();
 
   printBanner('installer');
   console.log(c.dim("I'll set up the brain and the Claude Code plugin, explaining each step as I go.\n"));
@@ -909,10 +1203,31 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
     const localZipPresent =
       FLAG_LOCAL || fs.existsSync(path.join(REPO_ROOT, 'dist', 'ruvnet-brain.zip'));
     const release = localZipPresent ? null : await resolveRelease();
-    const { zipPath, downloaded } = await obtainBundle(release);
+    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).
+    // SIGNING_REQUIRED is transitional: while releases predate signing, a MISSING sig warns-and-proceeds
+    // but a PRESENT-but-INVALID sig ALWAYS fails closed. Flip to true once every release is signed.
+    const SIGNING_REQUIRED = false;
+    if (downloaded && !FLAG_NO_VERIFY) {
+      const sigPath = `${zipPath}.sig`;
+      const hasSig = fs.existsSync(sigPath);
+      if (!hasSig && !SIGNING_REQUIRED) {
+        warn('this release is not signed yet — proceeding (bundle integrity not cryptographically verified)');
+      } else {
+        step('Verifying the bundle signature', 'so a tampered or MITM-swapped download can never be extracted');
+        const { ok: valid, reason } = verifyBundle(zipPath, sigPath);
+        if (!valid) {
+          try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
+          die(`bundle signature check FAILED — ${reason}`,
+              `Refusing to extract an unverified bundle. Re-run to fetch a fresh copy; if it persists, the\nrelease may be tampered — report it. (Override at your own risk with ${c.bold('--no-verify')}.)`);
+        }
+        ok(reason);
+      }
+    }
     unzipInto(zipPath, cacheDir);
-    if (downloaded) {
-      try { fs.rmSync(zipPath, { force: true }); } catch { /* leave temp behind, not fatal */ }
+    if (downloaded && tmpDir) {
+      try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* leave temp behind, not fatal */ }
     }
   }
 
@@ -920,7 +1235,7 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   const plugin = wirePlugin();
   if (!FLAG_NO_VERIFY) {
     verifyInstall(cacheDir);
-    smokeQuery(cacheDir);
+    await smokeQuery(cacheDir);
   }
 
   // ── onboarding: detect the toolkit + make offers (all optional, all non-fatal) ──

package/package.json

@@ -1,11 +1,30 @@
 {
   "name": "ruvnet-brain",
-  "version": "1.6.2-dev",
-  "description": "One-command installer for RuvNet Brain \u2014 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.",
+  "version": "1.16.0-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": {
     "ruvnet-brain": "bin/install.mjs"
   },
+  "scripts": {
+    "test": "node plugin/test/run-tests.mjs",
+    "version:check": "node scripts/sync-version.mjs --check",
+    "claims:verify": "node scripts/claims-verify.mjs",
+    "version:sync": "node scripts/sync-version.mjs",
+    "test:unit": "vitest run tests/unit",
+    "test:cov": "vitest run tests/unit --coverage",
+    "test:all": "npm run test:unit && npm run test:integration && npm test",
+    "metaharness:fix": "node scripts/fix-metaharness-memretrieve.mjs --apply",
+    "metaharness:check": "node scripts/fix-metaharness-memretrieve.mjs --check",
+    "eval": "node scripts/eval-brain.mjs",
+    "eval:gate": "node scripts/eval-brain.mjs --gate",
+    "eval:record": "node scripts/eval-brain.mjs --record",
+    "embed:verifier": "node scripts/embed-verifier.mjs",
+    "embed:check": "node scripts/embed-verifier.mjs --check",
+    "gists:index": "node scripts/ingest-gists.mjs --index-only",
+    "gists:sync": "node scripts/ingest-gists.mjs && node kb/forge-big.mjs both --dir kb --name ruv-gists",
+    "test:integration": "vitest run tests/integration"
+  },
   "files": [
     "bin/install.mjs",
     "README.md",
@@ -34,5 +53,10 @@
   },
   "homepage": "https://github.com/stuinfla/ruvnet-brain#readme",
   "bugs": "https://github.com/stuinfla/ruvnet-brain/issues",
-  "author": "Stuart Kerr"
+  "author": "Stuart Kerr",
+  "devDependencies": {
+    "@metaharness/darwin": "~0.8.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "vitest": "^4.1.10"
+  }
 }