ruvnet-brain 3.9.134-dev → 4.0.2

package/console/tips.js

@@ -0,0 +1,128 @@
+/* RuvNet Brain — How to use it (page two).
+   Two behaviors, both progressive enhancement — with JS off the page reads exactly as before:
+   1. The same theme toggle as the console (same 'rbc-theme' key, same data-theme mechanism).
+   2. Collapsible sections (owner, 2026-07-24: the page "gets too overwhelming as a wall of
+      text"). Every .depth.card collapses behind its own header; only the inventory — the
+      section that IS the page — starts open. Open state persists per browser; a #hash
+      deep-link always opens its target. */
+(function () {
+  'use strict';
+
+  /* ── theme toggle (unchanged) ─────────────────────────────────────────────── */
+  var KEY = 'rbc-theme';
+  var btn = document.getElementById('theme-toggle');
+  function applyTheme(t) {
+    document.documentElement.dataset.theme = t;
+    try { localStorage.setItem(KEY, t); } catch (e) { /* private mode is fine */ }
+  }
+  if (btn) {
+    btn.addEventListener('click', function () {
+      applyTheme(document.documentElement.dataset.theme === 'light' ? 'dark' : 'light');
+    });
+  }
+
+  /* ── collapsible sections ─────────────────────────────────────────────────── */
+  var OPEN_KEY = 'rbc-tips-open';
+  var DEFAULT_OPEN = ['inventory']; // the lead section IS the page; everything else waits
+  var sections = Array.prototype.slice.call(document.querySelectorAll('section.depth.card'));
+  if (!sections.length) return;
+
+  function savedOpen() {
+    try {
+      var raw = localStorage.getItem(OPEN_KEY);
+      return raw ? JSON.parse(raw) : null;
+    } catch (e) { return null; }
+  }
+  function persist() {
+    try {
+      var open = sections.filter(function (s) { return !s.classList.contains('is-collapsed'); })
+        .map(function (s) { return s.id; });
+      localStorage.setItem(OPEN_KEY, JSON.stringify(open));
+    } catch (e) { /* private mode is fine */ }
+  }
+
+  function setOpen(sec, open) {
+    sec.classList.toggle('is-collapsed', !open);
+    var head = sec.querySelector(':scope > .depth-head');
+    if (head) head.setAttribute('aria-expanded', open ? 'true' : 'false');
+  }
+
+  var open = savedOpen() || DEFAULT_OPEN;
+  sections.forEach(function (sec) {
+    var head = sec.querySelector(':scope > .depth-head');
+    if (!head || !sec.id) return;
+
+    // Wrap EVERYTHING after the header — several sections carry an art <figure> as a sibling of
+    // .depth-body, and a collapsed section that still shows its full-bleed art has not collapsed.
+    // grid-template-rows animates the height without measuring it (no reflow jank).
+    var dc = document.createElement('div'); dc.className = 'dc';
+    var dci = document.createElement('div'); dci.className = 'dci';
+    var after = [];
+    var walk = head.nextElementSibling;
+    while (walk) { after.push(walk); walk = walk.nextElementSibling; }
+    if (!after.length) return;
+    sec.appendChild(dc); dc.appendChild(dci);
+    after.forEach(function (n) { dci.appendChild(n); });
+
+    // The header is the disclosure control: chevron, ARIA, keyboard.
+    var chev = document.createElement('span');
+    chev.className = 'dc-chev';
+    chev.setAttribute('aria-hidden', 'true');
+    var svgNS = 'http://www.w3.org/2000/svg';
+    var csvg = document.createElementNS(svgNS, 'svg'); csvg.setAttribute('viewBox', '0 0 24 24');
+    var cpath = document.createElementNS(svgNS, 'path'); cpath.setAttribute('d', 'M6 9l6 6 6-6');
+    csvg.appendChild(cpath); chev.appendChild(csvg);
+    head.appendChild(chev);
+    head.setAttribute('role', 'button');
+    head.setAttribute('tabindex', '0');
+    head.setAttribute('aria-controls', sec.id + '-body');
+    dc.id = sec.id + '-body';
+    sec.classList.add('dc-ready');
+
+    function toggle() { setOpen(sec, sec.classList.contains('is-collapsed')); persist(); }
+    head.addEventListener('click', function (e) {
+      if (e.target.closest && e.target.closest('a, button')) return; // links in headers stay links
+      toggle();
+    });
+    head.addEventListener('keydown', function (e) {
+      if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); toggle(); }
+    });
+
+    setOpen(sec, open.indexOf(sec.id) !== -1);
+  });
+
+  // One small master switch, right-aligned above the first section.
+  var all = document.createElement('p');
+  all.className = 'dc-all';
+  var allBtn = document.createElement('button');
+  allBtn.type = 'button';
+  function anyCollapsed() {
+    return sections.some(function (s) { return s.classList.contains('is-collapsed'); });
+  }
+  function labelAll() { allBtn.textContent = anyCollapsed() ? 'expand all' : 'collapse all'; }
+  allBtn.addEventListener('click', function () {
+    var opening = anyCollapsed();
+    sections.forEach(function (s) { setOpen(s, opening); });
+    persist(); labelAll();
+  });
+  all.appendChild(allBtn);
+  sections[0].parentNode.insertBefore(all, sections[0]);
+  labelAll();
+  sections.forEach(function (s) {
+    var h = s.querySelector(':scope > .depth-head');
+    if (!h) return;
+    h.addEventListener('click', function () { setTimeout(labelAll, 0); });
+    h.addEventListener('keydown', function () { setTimeout(labelAll, 0); });
+  });
+
+  // A #hash deep-link must always land on an OPEN section — from the console's cards, the
+  // metaharness cross-reference, or a shared URL.
+  function openHashTarget() {
+    var id = (location.hash || '').replace(/^#/, '');
+    if (!id) return;
+    var sec = document.getElementById(id);
+    if (sec && sec.classList.contains('depth')) { setOpen(sec, true); persist(); labelAll(); }
+  }
+  window.addEventListener('hashchange', openHashTarget);
+  openHashTarget();
+}());

package/docs/RELEASE-NOTES-4.0.md

@@ -0,0 +1,88 @@
+# RuvNet-Brain 4.0 line — what's new (the major-release highlights)
+
+Updated: 2026-07-30
+
+> **Source of truth** for the `/whats-new` command and the first-run upgrade message. Curated, honest,
+> major-only — not the point-release churn. If a claim here isn't true of the shipping build, it does not
+> belong here. The self-measurement claims are deliberately hedged: they are *new and filling*, not
+> *proven*.
+>
+> **VERSION STATUS:** the public release line is now 4.x. Publication does not erase the remaining
+> acceptance obligations: the exact public artifact must still pass the fail-closed release contract
+> through fresh Claude Code and Codex hosts. Anything not proven through that boundary is listed as a
+> limitation, never converted into a capability claim.
+
+**One line:** the 4.0 line is where the brain got **honest, legible, fast, and self-measuring** — and
+it's landing now.
+
+## The big things
+
+### Release proof is fail-closed
+The 4.0 release path now separates a clean candidate seal from a post-publication seal. Dirty
+lineage, zero/skipped/todo tests, open issues, red or pending exact-SHA workflows, a missing
+`ruvnet-brain` self-RVF store, weak query-deadline margin, missing independent graders,
+host/artifact mismatches, and public-byte drift are release failures rather than warnings.
+`npm run release:proof -- --status --quick` shows the current live blockers.
+
+### 1. The Console is the front door
+Type `/rvbc` and your whole RuvNet stack is on one live local page: what's installed, what the AI has
+actually learned from *your* projects (real memories + distilled lessons, drill-down to the verbatim
+cards), which subscription pays for what, and one-click **reversible** fixes for anything stale. New in
+4.0:
+- a plain-English **explainer on every card** (no more guessing what "trust & provenance" means),
+- every suggestion carries its **blast radius** — *just this project* vs *every project · this machine*,
+- **safe on/off checkboxes** that appear *only* where the undo is proven,
+- a **terminal-first install** — the granular "here's exactly what I'll do, uncheck any of it" flow runs
+  in your terminal, where an `npx` user expects it.
+
+### 2. It will not lie about your machine
+Every number is measured live from your setup. **"We couldn't check" never renders as "off."** One
+project's state can never leak into another project's view (a real bug 4.0 fixed in the console itself).
+Empty-first, honest-always.
+
+### 3. Fast — and it tells you when it's ready
+The console and tips page paint in **well under a second** (measured, with a QE suite that runs every
+time). On a first scan it shows a **countdown** and then says *"it's live — take a look at your page,"*
+so you're never staring at a blank screen wondering if it hung.
+
+### 4. It measures itself now
+The brain records when it offered help and whether you acted on it — so over time it can **prove** it's
+improving instead of asserting it. **Honest caveat:** this instrumentation is *new* and has only just
+started collecting. 4.0 is not a claim of "proven better in the field" — it is the release that makes
+that proof *possible*, and the evidence accrues as you use it.
+
+### 5. It learns across your projects
+A lesson proven in one project can be **promoted to your global brain** and applied everywhere — and it
+now **survives an update** (tested against the real updater, not argued).
+
+### 6. Runs on your account, cheapest capable model
+The QE suite and model routing use **your Claude account, not an API key**, at the least-powerful model
+that does the job. Nothing bills silently.
+
+### 7. Claude Code and Codex share one active runtime
+Both hosts are wired to the same Stable Spine generation: the MCP search shell, lifecycle hooks,
+skills and update behavior advance as one versioned runtime instead of being installed as unrelated
+copies.
+
+### 8. Source grounding is an RVF-native product surface
+The Brain searches per-repository RuVector RVF stores, joins hits to their source passages, and
+returns cited repository paths. Model memory is not accepted as evidence for rUv-stack claims.
+
+### 9. Quality and harness workflows are explicit
+Agentic-QE is the testing fleet. Harness scoring evaluates the orchestration layer, and cost-aware
+routing can select cheaper capable models when the required provider access is configured. These are
+named workflows a user can request, not silent substitutes.
+
+## What 4.0 deliberately does NOT claim
+Stated up front because overclaiming is the one thing this product cannot do:
+- **Not** "proven X% better" — the outcome ledger is still filling (see #4).
+- **Not** "fully proactive / anticipatory" — the brain still mostly speaks when you open the console or
+  ask; the in-session, unprompted surface is the next frontier, not a shipped 4.0 guarantee.
+- **Not** independently graded ≥95 on the exact public artifact. A score is not a release substitute.
+- **Not** fully accepted while any critical exact-artifact, host, retrieval, version-convergence or
+  recovery invariant is FAIL, UNKNOWN, skipped or mocked-only.
+
+## For upgraders
+On the first real major-version transition, the installer/session experience presents the concise
+highlights once. Run `npx ruvnet-brain --whats-new` at any time to read this full list again, or
+`npx ruvnet-brain --what-changed` to inspect the exact machine footprint and undo path for each piece.

package/kb/model-requirements.mjs

@@ -19,19 +19,50 @@ export function modelCacheReady(modelCache, model, revision = null) {
   ].every((file) => fs.existsSync(file));
 }
 
+function acquireMaterializeLock(destination, timeoutMs = 30_000) {
+  const lock = `${destination}.materialize-lock`;
+  const started = Date.now();
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  while (true) {
+    try {
+      fs.mkdirSync(lock);
+      return () => fs.rmSync(lock, { recursive: true, force: true });
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        const ageMs = Date.now() - fs.statSync(lock).mtimeMs;
+        if (ageMs > timeoutMs) {
+          fs.rmSync(lock, { recursive: true, force: true });
+          continue;
+        }
+      } catch { /* another process released it between checks */ }
+      if (Date.now() - started >= timeoutMs) {
+        throw new Error(`timed out waiting to materialize model cache: ${destination}`);
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+}
+
 // Revision-pinned downloads live below <model>/<revision>/, while strict offline reads resolve
 // <model>/ directly. Promote only the exact pinned files into that canonical offline location.
 export function materializeModelRevision(modelCache, model, revision) {
   if (!revision || !modelCacheReady(modelCache, model, revision)) return false;
   const source = path.join(modelPath(modelCache, model), revision);
   const destination = modelPath(modelCache, model);
-  for (const entry of fs.readdirSync(source)) {
-    fs.cpSync(path.join(source, entry), path.join(destination, entry), {
-      recursive: true,
-      force: true,
-    });
+  const release = acquireMaterializeLock(destination);
+  try {
+    if (modelCacheReady(modelCache, model)) return true;
+    for (const entry of fs.readdirSync(source)) {
+      fs.cpSync(path.join(source, entry), path.join(destination, entry), {
+        recursive: true,
+        force: true,
+      });
+    }
+    return modelCacheReady(modelCache, model);
+  } finally {
+    release();
   }
-  return modelCacheReady(modelCache, model);
 }
 
 // The RVF sidecar is the source of truth for the query embedder. Only sidecars with a matching

package/kb/zip-extract.mjs

@@ -47,15 +47,28 @@ const SIG_EOCD64_LOC = 0x07064b50;
 const SIG_CENTRAL = 0x02014b50;
 const SIG_LOCAL = 0x04034b50;
 
+export const ZIP_LIMITS = Object.freeze({
+  archiveBytes: 2 * 1024 ** 3,
+  entries: 100_000,
+  centralDirectoryBytes: 128 * 1024 ** 2,
+  entryBytes: 2 * 1024 ** 3,
+  totalBytes: 8 * 1024 ** 3,
+  compressionRatio: 1_000,
+});
+
 // zlib.crc32 landed in Node 20.15.0 / 22.2.0. package.json engines allow >=18, so it is OPTIONAL —
 // present it is used, absent the size check still stands and the caller is told which happened.
 // Reimplementing CRC-32 here would be hand-rolling something the runtime ships.
 const crc32 = typeof zlib.crc32 === 'function' ? zlib.crc32 : null;
 
 class Tally extends Transform {
-  constructor() { super(); this.bytes = 0; this.crc = 0; }
+  constructor(maxBytes) { super(); this.bytes = 0; this.crc = 0; this.maxBytes = maxBytes; }
   _transform(chunk, _enc, cb) {
     this.bytes += chunk.length;
+    if (this.bytes > this.maxBytes) {
+      cb(new Error(`uncompressed entry exceeded the ${this.maxBytes}-byte safety limit`));
+      return;
+    }
     if (crc32) this.crc = crc32(chunk, this.crc);
     this.push(chunk);
     cb();
@@ -181,10 +194,40 @@ export async function extractZip(zipPath, destDir) {
   try {
     const size = fs.fstatSync(fd).size;
     if (size === 0) throw new Error('archive is empty (0 bytes)');
+    if (size > ZIP_LIMITS.archiveBytes) {
+      throw new Error(`archive is ${size} bytes, above the ${ZIP_LIMITS.archiveBytes}-byte safety limit`);
+    }
     const { cdSize, cdOffset } = centralDirectoryLocation(fd, size);
+    if (cdSize > ZIP_LIMITS.centralDirectoryBytes) {
+      throw new Error(`central directory is ${cdSize} bytes, above the ${ZIP_LIMITS.centralDirectoryBytes}-byte safety limit`);
+    }
     if (cdOffset + cdSize > size) throw new Error(`central directory runs past end of file (offset ${cdOffset} + ${cdSize} > ${size})`);
     const entries = parseCentralDirectory(readAt(fd, cdSize, cdOffset));
     if (entries.length === 0) throw new Error('central directory contains no entries');
+    if (entries.length > ZIP_LIMITS.entries) {
+      throw new Error(`archive has ${entries.length} entries, above the ${ZIP_LIMITS.entries}-entry safety limit`);
+    }
+    let declaredTotal = 0;
+    for (const entry of entries) {
+      const unixType = (entry.externalAttrs >>> 16) & 0xf000;
+      if ((entry.versionMadeBy >> 8) === 3 && unixType === 0xa000) {
+        throw new Error(`entry "${entry.name}" is a symbolic link — downloaded bundles may contain regular files and directories only`);
+      }
+      if (!Number.isSafeInteger(entry.uncompSize) || entry.uncompSize < 0) {
+        throw new Error(`entry "${entry.name}" has an unsafe uncompressed size`);
+      }
+      if (entry.uncompSize > ZIP_LIMITS.entryBytes) {
+        throw new Error(`entry "${entry.name}" claims ${entry.uncompSize} bytes, above the ${ZIP_LIMITS.entryBytes}-byte safety limit`);
+      }
+      declaredTotal += entry.uncompSize;
+      if (!Number.isSafeInteger(declaredTotal) || declaredTotal > ZIP_LIMITS.totalBytes) {
+        throw new Error(`archive claims ${declaredTotal} uncompressed bytes, above the ${ZIP_LIMITS.totalBytes}-byte safety limit`);
+      }
+      const ratio = entry.uncompSize / Math.max(entry.compSize, 1);
+      if (ratio > ZIP_LIMITS.compressionRatio) {
+        throw new Error(`entry "${entry.name}" has compression ratio ${ratio.toFixed(1)}, above the ${ZIP_LIMITS.compressionRatio}:1 safety limit`);
+      }
+    }
 
     fs.mkdirSync(destDir, { recursive: true });
     let files = 0;
@@ -234,17 +277,6 @@ export async function extractZip(zipPath, destDir) {
         throw new Error(`entry "${e.name}" uses unsupported compression method ${e.method} (only stored=0 and deflate=8 are implemented)`);
       }
 
-      const isSymlink = (e.versionMadeBy >> 8) === 3 && ((e.externalAttrs >>> 16) & 0xf000) === 0xa000;
-      if (isSymlink) {
-        // A symlink's payload is its target path — always tiny, so it is read whole rather than streamed.
-        const comp = e.compSize === 0 ? Buffer.alloc(0) : readAt(fd, e.compSize, dataStart);
-        const linkTarget = (e.method === 8 ? zlib.inflateRawSync(comp) : comp).toString('utf8');
-        fs.rmSync(target, { recursive: true, force: true });
-        fs.symlinkSync(linkTarget, target);
-        files++;
-        continue;
-      }
-
       // A zero-length entry has no data range to stream (start > end would be a nonsense read), so
       // it is written directly. Its size/CRC assertions below still apply.
       if (e.compSize === 0) {
@@ -254,25 +286,32 @@ export async function extractZip(zipPath, destDir) {
         continue;
       }
 
-      const tally = new Tally();
+      const tally = new Tally(Math.min(e.uncompSize, ZIP_LIMITS.entryBytes));
+      const partial = path.join(path.dirname(target), `.ruvnet-extract-${process.pid}-${entryIndex}.tmp`);
+      try { fs.rmSync(partial, { force: true }); } catch { /* absent */ }
       const stages = [fs.createReadStream(zipPath, { start: dataStart, end: dataStart + e.compSize - 1 })];
       if (e.method === 8) stages.push(zlib.createInflateRaw());
-      stages.push(tally, fs.createWriteStream(target));
+      stages.push(tally, fs.createWriteStream(partial, { flags: 'wx' }));
 
       try {
         await pipeline(...stages);
       } catch (err) {
+        try { fs.rmSync(partial, { force: true }); } catch { /* best effort */ }
         throw new Error(`entry "${e.name}" failed to inflate (${err && err.code ? err.code : ''}${err && err.message ? ` ${err.message}` : ''}) — the archive is corrupt or truncated`);
       }
       if (tally.bytes !== e.uncompSize) {
+        fs.rmSync(partial, { force: true });
         throw new Error(`entry "${e.name}" is corrupt: expected ${e.uncompSize} bytes, extracted ${tally.bytes}`);
       }
       if (crc32 && (tally.crc >>> 0) !== (e.crc >>> 0)) {
+        fs.rmSync(partial, { force: true });
         // Zero-padded to 8 hex digits so the value is directly comparable to the one Info-ZIP's
         // own `unzip` prints for the same damaged entry ("bad CRC 811e0dd1 (should be 0f6994e4)").
         const hex = (n) => (n >>> 0).toString(16).padStart(8, '0');
         throw new Error(`entry "${e.name}" failed its CRC-32 check (expected ${hex(e.crc)}, got ${hex(tally.crc)}) — the archive is corrupt`);
       }
+      if (process.platform === 'win32') fs.rmSync(target, { recursive: true, force: true });
+      fs.renameSync(partial, target);
 
       // Unix permission bits, when the archive carries them. Skipped on Windows, which has no
       // POSIX mode and where chmod is a no-op at best.

package/keys/ruvnet-brain-signing.pub.pem

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAgse9TAtehXUvUfTrJFY2CCHiCbmelR8yCgS//sen5/w=
+-----END PUBLIC KEY-----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "3.9.134-dev",
+  "version": "4.0.2",
   "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": {
@@ -8,6 +8,9 @@
   },
   "scripts": {
     "test": "node plugin/test/run-tests.mjs",
+    "release:proof": "node scripts/release-proof.mjs",
+    "benchmark:brain50": "node scripts/brain-latency-50.mjs",
+    "benchmark:novice50": "node scripts/brain-novice-50.mjs",
     "version:check": "node scripts/sync-version.mjs --check",
     "claims:verify": "node scripts/claims-verify.mjs",
     "claims:fix": "node scripts/claims-verify.mjs --fix",
@@ -49,39 +52,28 @@
     "cap:ab": "node scripts/rerank-cap-warm-ab.mjs"
   },
   "files": [
+    ".claude-plugin/marketplace.json",
     "bin/install.mjs",
+    "plugin/",
     "plugin/mcp/managed-cli-interface.mjs",
     "plugin/mcp/server.mjs",
     "plugin/scripts/codex-hook-wrapper.mjs",
+    "plugin/scripts/host-update.mjs",
+    "plugin/scripts/update-apply.mjs",
     "!plugin/README.md",
+    "!plugin/scripts/.ruvnet-brain/",
+    "!plugin/test/",
     "README.md",
+    "docs/RELEASE-NOTES-4.0.md",
     "LICENSE",
+    "console/",
     "config/model-router/",
+    "scripts/",
     "kb/verify-citation.mjs",
     "kb/zip-extract.mjs",
     "kb/brain-profile.mjs",
     "kb/model-requirements.mjs",
-    "scripts/model-router-engine.mjs",
-    "scripts/model-router-setup.mjs",
-    "scripts/model-router-status.mjs",
-    "scripts/model-router-outcome.mjs",
-    "scripts/subscription-hosts.mjs",
-    "scripts/dual-host-deliberation.mjs",
-    "scripts/dual-host-suggest.mjs",
-    "scripts/route-cheap.mjs",
-    "scripts/dispatch-receipt.mjs",
-    "scripts/metaharness-receipts.mjs",
-    "scripts/codex-routed.sh",
-    "scripts/metaharness-router.mjs",
-    "scripts/no-silent-substitution.mjs",
-    "scripts/user-settings.mjs",
-    "scripts/selfcheck.mjs",
-    "scripts/hook-registry.mjs",
-    "scripts/install-scope.mjs",
-    "scripts/upgrade-notice.mjs",
-    "scripts/falsify.mjs",
-    "scripts/nightly-watchdog.mjs",
-    "scripts/job-heartbeat.sh"
+    "keys/ruvnet-brain-signing.pub.pem"
   ],
   "engines": {
     "node": ">=18"

package/plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "ruvnet-brain",
+  "description": "Source-grounded RuvNet Brain integrations for Claude Code and Codex.",
+  "owner": {
+    "name": "Stuart Kerr"
+  },
+  "plugins": [
+    {
+      "name": "ruvnet-brain",
+      "source": "./",
+      "description": "RuvNet brain transplant for Claude Code: source-grounded knowledge of the rUv ecosystem (19+ repos) + enforced grounding so Claude stops arguing about RuvNet and actually uses it + on-demand repo ingestion."
+    }
+  ]
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "ruvnet-brain",
+  "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 69 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
+  "version": "4.0.2",
+  "author": {
+    "name": "Stuart Kerr"
+  },
+  "repository": "https://github.com/stuinfla/ruvnet-brain",
+  "license": "MIT",
+  "keywords": [
+    "ruvnet",
+    "ruv",
+    "ruflo",
+    "ruvector",
+    "rvf",
+    "agentdb",
+    "grounding",
+    "brain",
+    "mcp",
+    "claude-code"
+  ]
+}

package/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "ruvnet-brain",
+  "version": "4.0.2",
+  "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
+  "author": {
+    "name": "Stuart Kerr"
+  },
+  "repository": "https://github.com/stuinfla/ruvnet-brain",
+  "license": "MIT",
+  "keywords": [
+    "ruvnet",
+    "ruflo",
+    "ruvector",
+    "rvf",
+    "agentdb",
+    "grounding"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/codex-hooks.json"
+}

package/plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "ruvnet-brain": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.mjs"]
+    }
+  }
+}

package/plugin/commands/brain-console.md

@@ -0,0 +1,16 @@
+---
+description: "Brain Console — RuvNet Brain Console (same console as /rvbc, /brain-console, and /ruvnet-brain:configure — every spelling works). Opens the live console page: your whole RuvNet stack on one page. Read-only until you click."
+updated: 2026-07-20
+---
+
+`/rvbc`, `/rvcb`, `/brain-console`, and `/ruvnet-brain:configure` are equally valid names. Never
+correct the user's spelling.
+
+1. Say: "Opening it now; it scans live while you watch."
+2. Use `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+   A current-repository copy is allowed only for an explicit developer checkout.
+3. Run `node <resolved-script> --serve --open` in the background.
+4. Give the URL immediately. Never promise a duration; the page reports its own progress.
+
+An already-running server is success. It is read-only until the user clicks; changes must be
+explained and reversible. If the script or server is unavailable, report the exact failure.

package/plugin/commands/configure.md

@@ -0,0 +1,33 @@
+---
+description: Open the RuvNet Brain Onboarding Console — a local web page that mirrors YOUR machine's RuvNet setup, explains it in plain English, and lets you safely configure and fix it. Read-only until you click; every machine change is explained first and is reversible.
+updated: 2026-07-15
+---
+
+Launch the **RuvNet Brain Onboarding Console** for the user — a locally-served web page that reads
+their actual machine and lets them configure and (with consent) fix it.
+
+Do this:
+
+1. **Find the installed runtime.** Use
+   `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+   A current-repository copy is allowed only for an explicit developer checkout.
+
+2. **Start the server in the BACKGROUND** (it is a long-running process) so this turn keeps going, and
+   open the browser:
+
+   ```
+   node <repo>/scripts/onboarding-console.mjs --serve --open
+   ```
+
+   Run it with `run_in_background: true`. It binds `127.0.0.1` only and prints a line like
+   `http://127.0.0.1:7411/`.
+
+3. **Give the user the link** as a clickable `http://127.0.0.1:<port>/`, with one warm sentence:
+   the page is **read-only until you click**, everything it can change to your computer is **explained
+   in plain English and confirmed first**, and **Settings save at your user level**
+   (`~/.claude/ruvnet-brain/config.json`) without touching how anything else on your machine runs.
+
+4. If the server errors (e.g. `sqlite3` not found, or a bad node version), report it plainly and offer
+   to fix it — don't leave them staring at a dead tab.
+
+Do **not** narrate the machine yourself — the page is the mirror. Your job is just to get it open.