ruvnet-brain 1.16.0-dev → 2.0.0

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 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)
+### 🧠 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.**
 
@@ -36,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.
@@ -110,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.)
 
@@ -118,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 |
@@ -134,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)
 
@@ -168,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)
 
@@ -207,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** | **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 |
+| **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.
@@ -226,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):**
 
@@ -242,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

@@ -69,13 +69,14 @@ const FLAG_DEMO = argv.includes('--demo'); // guided, real (non-fabricated) walk
 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('-')
@@ -314,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}`);
@@ -667,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');
@@ -714,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`);
@@ -743,6 +772,12 @@ const nightlyPlistPath = () =>
 // 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.
@@ -886,6 +921,77 @@ function disableNightly() {
   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);
@@ -1057,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`,
@@ -1113,11 +1219,18 @@ function success({ cacheDir, isCustom, plugin, env }) {
   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.')}`);
+  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('');
@@ -1140,7 +1253,9 @@ Usage:
   npx ruvnet-brain --enable-nightly    Schedule that update nightly at 03:47 — macOS LaunchAgent;
                               other platforms get the documented cron line. OFF by default.
   npx ruvnet-brain --disable-nightly   Remove the nightly schedule (safe to run any time)
-  node bin/install.mjs --version <tag>     Install a specific Release tag (e.g. --version v0.4.0-dev)
+                              (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
@@ -1160,6 +1275,7 @@ 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();
@@ -1242,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.16.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": {