ruvnet-brain 1.14.0-dev → 2.0.0

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 1.14.0-dev — updated 2026-07-08 07:21 EDT](https://img.shields.io/badge/version_1.14.0--dev-updated_2026--07--08_07:21_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 2.0.0 — updated 2026-07-10 08:15 EDT](https://img.shields.io/badge/version_2.0.0-updated_2026--07--10_08:15_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.**
 
@@ -14,12 +14,15 @@
 [![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-75%25%20lines%20·%2072%25%20stmts-2e7d32?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>
 
@@ -33,6 +36,45 @@
 
 ---
 
+## What's new in 2.0
+
+**2.0 is the release where the brain got bigger — and, more importantly, stopped taking its own word for anything.** Every number below regenerates from an artifact on disk; the claims ledger (`node scripts/claims-verify.mjs`) re-checks the advertised ones in CI:
+
+| | v1 (0.x–1.x) | v2.0 |
+|---|---|---|
+| **Corpus** | 24 repos built | **32 repos** built (of 197 live ruvnet repos), each verified by a live retrieval query |
+| **Depth** (flagship `ruvector`) | 18,491 passages · **0** full source bodies | **28,018 passages · 2,996 full bodies** — depth also restored to `agent-harness-generator` (8,896/715), `ruview` (7,434/765), `open-claude-code` (195/69) |
+| **Corpus QA gate** | none | every store must prove *embeds correctly + reads correctly* — vector count == passage count, depth floors, a 3-passage self-retrieval round-trip per store — **72/72 store-variants PASS**, wired fail-closed into the nightly publish |
+| **Retrieval eval** | 12 frozen questions | **120 frozen, hash-pinned questions** across 5 strata; promotion gated on Wilson lower bounds, fail-closed — it blocked a real release this morning, which is the feature working |
+| **Token cost** | 6,183 bytes injected per hook turn · zero self-measurement | **684 bytes (~90% cut)** with an eval-PASS proving zero quality loss · a live token meter measuring real bytes/tokens per prompt class · ~27% faster repeat queries via the KB cache |
+| **rUv's gists** | not indexed | **437 gists** indexed with per-chunk freshness/provenance banners, refreshed nightly with cost-disciplined skip |
+| **Reliability** | claims were prose | **claims ledger** (5 marketing claims mechanically re-verified in CI) · integration tests in CI incl. Linux · a Windows CI job · an honest coverage denominator (all source files) |
+| **Autonomy** | hooks asked questions to an empty room — the #1 real-user complaint | **`/loop` contract** — checkpoint / resume / done-criteria; hooks detect autonomous mode and stop asking — 10 mutation-verified tests |
+| **Publishing** | manual npm token · a nightly release PATH bug | **self-renewing npm token** (launchd daemon, proven end-to-end) · PATH bug root-caused and cured |
+| **Memory layer** | silent SQLite corruption · searches returning 0 · invisible flywheel patterns | **3 root-caused fixes** (an ABI-mismatched binary falling back to WAL-blind whole-file overwrites; keys that were never scored; a split-store display bug) — plus **6 exact patches queued upstream to ruflo** |
+
+The depth jump wasn't tuning — it was two pipeline root-causes fixed for good: missing `--full` hints, and a day-one `v2/` skip-dir bug that had made two repos undepthable since the first build.
+
+### The scorecard — 8 dimensions, self-scored /100, every deduction evidenced — 2026-07-10 (evening re-score)
+
+| Dimension | v1 (2026-07-09) | v2.0 (current) | Δ | What moved it |
+|---|---:|---:|---:|---|
+| End-user experience | 54 | 83 | +29 | One-command install now offers nightly self-updates (default yes); the page lives on isovision.ai; publishing renews itself |
+| Knowledge corpus | 71 | 88 | +17 | 24→32 verified repos; a 72/72 embeds-and-reads QA gate; full source depth restored — flagship went 0→2,996 source bodies |
+| Effectiveness (eval-proven retrieval) | 58 | 88 | +30 | 120-question Wilson-bound gate — it blocked a bad release, then passed the fix *above* the old baseline |
+| Acting like rUv | 38 | 72 | +34 | Memory layer root-caused and fixed with proofs; 6 exact patches queued upstream; real multi-agent swarm operations |
+| Developer smarter | 62 | 84 | +22 | `/brain-score` runs this same scorecard on any repo; honest tool announcements; per-answer source receipts |
+| Token cost efficiency | 41 | 82 | +41 | ~90% smaller per-turn injection, eval-proven free; a live token meter — measured, not guessed |
+| Engineering reliability | 61 | 86 | +25 | 312 tests green; a claims ledger re-verifies marketing claims in CI; fail-closed publishing; Windows CI added |
+| Safety & privacy | 74 | 82 | +8 | Private-store fence held under full rebuild; secrets never transit chat; autonomy hard fence |
+| **Overall** | **55** | **83** | **+28** | — |
+
+These are self-scores under a hard rule: **every deduction requires specific evidence, and a known architectural flaw caps a dimension at ≤70 until the flaw is fixed** — *acting like rUv* spent the morning capped for its memory-layer flaw; the flaw was root-caused and fixed with proofs, the cap lifted, and it re-scored 72. Overall **55 → 83 in two days**, each number regenerating from a stored receipt — and the same scoring that produced these blocked a release mid-day. **That's why they're credible: scores you can trust beat scores that flatter.**
+
+**The honest small print, kept visible:** warm query is ~21 s on the large corpus (it grew with depth; candidate dedup/pruning is the next optimization) · the 8 newest repos are findable by name but don't yet have primers/capability cards for described-need routing (coming) · the Windows CI job is new and unproven until its first green run.
+
+---
+
 ## The one thing to understand first
 
 **Reuven Cohen (rUv) builds about nine months ahead of the state of the art.** His RuvNet building blocks — Ruflo, RuVector, AgentDB, agentic-flow, SPARC and ~20 more — are the working prototypes of what becomes mainstream AI tooling three quarters later. This is the actual front edge.
@@ -107,7 +149,7 @@ You install once. After that, three mechanisms keep you on the current brain wit
 
 - **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.
+- **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 v2.0.0 · 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.)
 
@@ -115,9 +157,9 @@ You install once. After that, three mechanisms keep you on the current brain wit
 
 ## ✨ 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:
+Earlier bundles knew only the **docs and architecture**. v0.5 began re-indexing 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. The table below is that v0.5 depth jump, kept as the before/after receipt; **2.0 went further still** — flagship `ruvector` alone now carries 28,018 passages and 2,996 full bodies (see [What's new in 2.0](#whats-new-in-20)):
 
-| Repo | Full-body code passages | |
+| Repo | Full-body code passages (v0.5) | |
 |---|---:|---|
 | `agentic-flow` | 296 → **984** | model-routing, ReasoningBank |
 | `ruv-fann` | 52 → **779** | ruv-swarm, cuda-wasm, neuro-divergent |
@@ -131,7 +173,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 **90,842 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 **128,994 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)
 
@@ -165,7 +207,7 @@ The brain answers **both** kinds of questions. **Name the repo or ask something
 
 ## What it covers
 
-~21 of rUv's **building-block** repos in the [ruvnet](https://github.com/ruvnet) org — the reusable pieces you'd actually compose into a system — each deep-walked, embedded in both variants, symbol-indexed, and given a capability card.
+32 of rUv's repos in the [ruvnet](https://github.com/ruvnet) org — the reusable **building blocks** you'd actually compose into a system — each deep-walked and embedded in both variants. The core blocks below also carry symbol indexes and capability cards (the 8 newest repos are findable by name; their capability cards are coming).
 
 ![The RuvNet stack the brain covers](primer/assets/diagrams/ruvnet-stack.svg)
 
@@ -204,17 +246,17 @@ 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** | **154 passing** · 75% lines | `npm run test:cov` — a CI floor fails the build if coverage slips |
+| **Unit tests** | **257 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 |
+| **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 |
 
-<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>
+<sub>The suite also carries **169 `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:
+Most of the numbers above were tuned against. [`evals/held-out.json`](evals/held-out.json) was not: **120 frozen, hash-pinned questions across 5 strata** (named, described, scenario, adversarial, provenance), 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, among other things, two claims — 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.
@@ -223,7 +265,7 @@ Most of the numbers above were tuned against. [`evals/held-out.json`](evals/held
 
 **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.
+Current baseline (n=120, [`evals/baseline.json`](evals/baseline.json)): **grounded 100/100 · routed 63/80 · abstain 18/20 · banner 20/20**, promotion gated on Wilson lower bounds. The routing misses are recorded, not tuned away — the recurring shapes: `"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):**
 
@@ -239,9 +281,9 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 ## Honest status
 
-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:
+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** — ~21 building-block repos, 90,842 chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 32 repos, 128,994 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).
 - ✅ **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

@@ -65,13 +65,18 @@ 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
+const FLAG_NO_NIGHTLY_PROMPT = argv.includes('--no-nightly-prompt'); // don't offer nightly auto-updates at the end of an install
 // ── 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
 const FLAG_NO_STACK = argv.includes('--no-stack'); // skip the toolkit offer entirely
 const FLAG_ENHANCE_CLAUDE_MD = argv.includes('--enhance-claude-md'); // add the CLAUDE.md section without prompting
 const FLAG_NO_ENHANCE = argv.includes('--no-enhance'); // skip the CLAUDE.md offer entirely
-// --version <tag> forces a specific Release tag (e.g. --version v0.4.0-dev)
+// --version <tag> forces a specific Release tag (e.g. --version v0.5.0-dev)
 const versionIdx = argv.indexOf('--version');
 const FORCED_VERSION =
   versionIdx !== -1 && argv[versionIdx + 1] && !argv[versionIdx + 1].startsWith('-')
@@ -310,7 +315,7 @@ async function obtainBundle(release) {
   const downloadUrl = (release && release.url) || fallbackUrl(RELEASE_VERSION);
   step(
     `Downloading the brain (${APPROX_SIZE})`,
-    'the brain is the embedded source of ~18 RuvNet repos — too big for git, so it ships as a Release',
+    'the brain is the embedded source of 20+ RuvNet repos — too big for git, so it ships as a Release',
   );
   info(`version: ${c.bold((release && release.tag) || RELEASE_VERSION)}`);
   info(`from: ${downloadUrl}`);
@@ -663,6 +668,33 @@ function runDemo() {
   console.log(`  Full health check:              ${c.bold('npx ruvnet-brain --doctor')}\n`);
 }
 
+// ── 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.
+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 since = new Date();
+    since.setHours(0, 0, 0, 0);
+    since.setDate(since.getDate() - 1); // start of yesterday, local time
+    let count = 0;
+    let bytes = 0;
+    for (const line of fs.readFileSync(ledger, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      let e;
+      try { e = JSON.parse(line); } catch { continue; }
+      if (!e?.ts || new Date(e.ts) < since) continue;
+      count++;
+      bytes += Number(e.bytes) || 0;
+    }
+    if (count === 0) return 'meter: no data yet (nothing measured in this project yesterday/today)';
+    return `meter: ${count} injections measured here yesterday+today — ${bytes} bytes ≈ ${Math.round(bytes / 4)} tokens (full breakdown: node scripts/token-report.mjs)`;
+  } catch { return 'meter: ledger unreadable'; }
+}
+
 // ── `--doctor`: a standalone health check the user can run any time ───────────────────────────────
 async function doctor() {
   printBanner('doctor');
@@ -710,6 +742,7 @@ async function doctor() {
     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.');
   }
+  console.log(`  ${c.dim(meterSummaryLine())}`);
   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`);
@@ -725,6 +758,240 @@ async 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';
+// RUVNET_BRAIN_IMPORT_ONLY=1 → import this file for its EXPORTS (parseNightlyAnswer, offerNightly)
+// without running the installer as an import side effect. An EXPLICIT env var, not an argv[1]
+// path-identity check, because this repo has already watched a path-identity check fail silently
+// (see smokeQuery's launch note) — and a silently-skipped installer main is the worst possible
+// failure mode for a stranger's first contact. With the variable unset, behavior is unchanged.
+const IMPORT_ONLY = process.env.RUVNET_BRAIN_IMPORT_ONLY === '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')}`);
+}
+
+// ── step: offer nightly auto-updates at the end of a successful install (recommended, default YES) ──
+// Requirement: a default `npx ruvnet-brain` run must never leave the user unaware of nightly
+// auto-updates — it VERY CLEARLY recommends them, asks, and DEFAULTS TO YES. Before this, the
+// nightly LaunchAgent only ever installed via the explicit --enable-nightly flag.
+//
+// The answer parsing is exported so the default-yes contract is unit-testable without a TTY:
+// ENTER (empty) and y/yes (any case) accept; ONLY an explicit n/no declines.
+export function parseNightlyAnswer(answer) {
+  const s = String(answer ?? '').trim().toLowerCase();
+  return s !== 'n' && s !== 'no';
+}
+
+// Exported for the same reason: the decision matrix (TTY/non-TTY × platform × already-enabled ×
+// suppression flags) is testable in-process under RUVNET_BRAIN_IMPORT_ONLY=1 without a real install.
+// Returns a status string; never throws (the caller also guards — a finished install must never
+// be broken by an optional offer).
+export async function offerNightly() {
+  // Suppressed outright: --no-nightly-prompt (the user said don't ask) and RUVNET_BRAIN_TEST=1
+  // (tests must stay non-interactive and must never schedule anything).
+  if (FLAG_NO_NIGHTLY_PROMPT || TEST_MODE) return 'suppressed';
+  const kbDir = resolvedKbDir();
+  // A bundle that predates the self-updater has nothing to run nightly — don't offer a job that
+  // is guaranteed to fail (enableNightly would refuse it anyway).
+  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) return 'no-updater';
+
+  step(
+    'One last thing — keeping the brain fresh',
+    'rUv ships constantly; a brain that updates itself stays current with zero effort from you',
+  );
+
+  if (process.platform !== 'darwin') {
+    info('The LaunchAgent scheduler is macOS-only (for now).');
+    info(`Update manually any time with:  ${c.bold('npx ruvnet-brain --update')}`);
+    info(`(or schedule it yourself with the cron line documented in the brain's own forge-update.mjs)`);
+    return 'unsupported';
+  }
+
+  if (fs.existsSync(nightlyPlistPath())) {
+    ok('nightly auto-updates are already on — new repos and gists arrive while you sleep');
+    return 'already-on';
+  }
+
+  info(`${c.bold('Recommended:')} your brain updates itself while you sleep — new repos, new gists, zero effort.`);
+
+  if (!process.stdin.isTTY && !FLAG_YES) {
+    // 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) {
+    // 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 });
+    const answer = await new Promise((resolve) =>
+      rl.question(`    ${c.cyan('?')} Enable nightly auto-updates? ${c.dim('[Y/n]')} `, resolve),
+    );
+    rl.close();
+    yes = parseNightlyAnswer(answer);
+  }
+
+  if (!yes) {
+    info(`No problem — enable it any time with:  ${c.bold('npx ruvnet-brain --enable-nightly')}`);
+    return 'declined';
+  }
+  enableNightly(); // prints its own real verification output (plist path, launchctl result, how to check)
+  return 'enabled';
+}
+
 // ── 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);
@@ -896,13 +1163,13 @@ async function offerClaudeMd() {
 }
 
 // ── final success block ──────────────────────────────────────────────────────────────────────────
-function success({ cacheDir, isCustom, plugin, env }) {
+function success({ cacheDir, isCustom, plugin, env, nightly }) {
   const line = '─'.repeat(64);
   console.log(`\n${c.green(line)}`);
   console.log(`${c.green(c.bold('  RuvNet Brain is installed.'))}`);
   console.log(`${c.green(line)}`);
   console.log(`\n  What you now have:`);
-  console.log(`    • the brain (embedded source of ~18 RuvNet repos) at:`);
+  console.log(`    • the brain (embedded source of 20+ RuvNet repos) at:`);
   console.log(`        ${c.bold(cacheDir)}`);
   console.log(
     `    • the Claude Code plugin ${plugin.wired ? c.green('wired at user scope') : c.yellow('(finish the 2 commands above)')} — search_ruvnet + grounding hook`,
@@ -949,9 +1216,21 @@ 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.`);
+
+  if (nightly === 'enabled' || nightly === 'already-on') {
+    // The offer just above turned nightly on (or found it on) — don't contradict that here.
+    console.log(`\n  ${c.bold('Staying current:')} nightly auto-updates are ${c.green(c.bold('ON'))} — your brain refreshes itself at 03:47.`);
+    console.log(`    • update right now anyway:  ${c.bold('npx ruvnet-brain --update')}   ${c.dim('· turn nightly off: --disable-nightly')}`);
+    console.log(`    ${c.dim('It only advances when a new Release is actually published — a quiet night is a clean no-op.')}`);
+  } else {
+    console.log(`\n  ${c.bold('Staying current:')} nightly updates are ${c.bold('OFF right now')} — 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('');
@@ -969,7 +1248,14 @@ 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
-  node bin/install.mjs --version <tag>     Install a specific Release tag (e.g. --version v0.4.0-dev)
+  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)
+                              (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 --version <tag>     Install a specific Release tag (e.g. --version v0.5.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
   node bin/install.mjs --force             Re-fetch and reinstall even if already present
@@ -989,9 +1275,13 @@ 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
   if (FLAG_HELP) return showHelp();
   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"));
@@ -1068,8 +1358,12 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   const env = detectEnvironment();
   try { await offerStack(env); } catch (e) { warn(`(toolkit check skipped: ${e && e.message})`); }
   try { await offerClaudeMd(); } catch { /* non-fatal — never let an offer break the install */ }
+  // Stuart's requirement: a default install must end by clearly recommending nightly auto-updates
+  // and asking, DEFAULTING TO YES (TTY + macOS + not already on). Non-fatal like every other offer.
+  let nightly = 'skipped';
+  try { nightly = await offerNightly(); } catch { /* never let the offer break a finished install */ }
 
-  success({ cacheDir, isCustom, plugin, env });
+  success({ cacheDir, isCustom, plugin, env, nightly });
 })().catch((e) => {
   die(e && e.message ? e.message : String(e));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "1.14.0-dev",
+  "version": "2.0.0",
   "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": {
@@ -9,16 +9,21 @@
   "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",
-    "test:cov": "vitest run --coverage",
+    "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"
+    "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",
@@ -50,6 +55,7 @@
   "bugs": "https://github.com/stuinfla/ruvnet-brain/issues",
   "author": "Stuart Kerr",
   "devDependencies": {
+    "@metaharness/darwin": "~0.8.0",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }