ruvnet-brain 4.0.90-dev → 4.2.2-dev

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.0.90-dev — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.90--dev-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 4.2.2-dev — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.2.2--dev-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 
@@ -56,7 +56,30 @@
 
 ---
 
-## What's new in 4.0 — it anticipates, and it learns whether it was right
+## What's new in 4.2 — it loads what rUv ships, without being asked
+
+**The corpus stopped drifting behind the org.** Until 4.2 nothing ever ingested a new repo: the
+nightly refreshed lessons, health and proofs and contained *zero* ingestion, so a repo entered the
+brain only when a human typed the command. `brain-stamp.mjs` had been measuring that gap every
+night, but nothing consumed it until the ingestion loop shipped.
+
+- **187 stores, up from 69.** Everything rUv ships that has content, pulled in and kept level by
+  `scripts/ingest-new-repos.mjs` running nightly, newest-first. Empty repos (`size=0KB`) are skipped
+  rather than retried forever — a permanent nightly failure that is actually correct behaviour
+  trains you to ignore the failure line, which is how a real one would hide inside it.
+- **174 capability cards, up from 39.** Ingesting a repo is not the same as making it reachable: a
+  store with no card is *dark* — valid bytes no by-description query can find. Cards are written
+  from each repo's **own** description and README, never from its name, and where there is no
+  grounded source text the store is **left dark and reported** rather than given an invented
+  sentence. 13 remain dark for exactly that reason.
+- **The download barely grew** for 2.4x the corpus — most of rUv's repos are small, so the bulk
+  of the bundle was always the large ones. (No size is hand-typed here: a number typed onto a
+  public page rots the moment the next bundle is built, and this repo gates against exactly that.)
+- **The nightly stopped discarding its own writes.** It hardcoded a node whose ABI did not match
+  agentdb's binding, so `lesson-bridge --apply` and `learning-replay` wrote into a silent
+  non-persistent fallback. It now resolves an ABI-matched interpreter and fails loudly instead.
+
+## What's new in 4.2 — it anticipates, and it learns whether it was right
 
 **Building toward L4/L5 (3.9.x, dev).** The mechanisms for the top two rungs of the proactivity
 ladder are built and wired — but they are **not yet verified to 4.0's bar**, which requires all five
@@ -522,7 +545,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 70 public stores · 140,389 public source chunks (77 built stores incl. private), dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 70 public stores · 140,520 public source chunks (77 built stores incl. private), dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L3 all pass (**L4 downgraded — it measures that the brain spoke, not that anything listened**); private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/bin/install.mjs

@@ -547,7 +547,7 @@ async function unzipInto(zipPath, cacheDir, sourceDir = null) {
 }
 
 /**
- * ISSUE #128 — STALE PLUGIN GENERATIONS ARE STILL DISCOVERED.
+ * ISSUE #128 / #153 — STALE PLUGIN GENERATIONS MAY STILL BACK LIVE SESSIONS.
  *
  * `pruneUnlistedStores` below states the rule this repo already believes: "an update is a
  * replacement, not an overlay." That rule was applied to KB stores and never to the plugin cache.
@@ -563,6 +563,12 @@ async function unzipInto(zipPath, cacheDir, sourceDir = null) {
  * restart, one says an update is landing, one mandates a third version), so whichever the model
  * obeys, the user is misinformed by a source that sounds definitive.
  *
+ * Registry reachability identifies candidates; it is not deletion proof. Claude freezes
+ * CLAUDE_PLUGIN_ROOT at session start, so an unregistered generation can remain live until that
+ * session exits. Modern roots expose `.in_use` PID-incarnation leases. Live or ambiguous leases
+ * retain the complete root; dead leases are collected. Legacy roots without the protocol receive
+ * a 14-day compatibility grace.
+ *
  * WHAT MAKES DELETION SAFE HERE, since this removes directories from someone's machine:
  *   • The registry is the ONLY authority. Unreadable, missing, or naming no ruvnet-brain install →
  *     nothing is removed and a reason is returned. Never guess what to delete — the same discipline
@@ -574,17 +580,26 @@ async function unzipInto(zipPath, cacheDir, sourceDir = null) {
  *     here, and deleting through that link would delete the working tree.
  *   • EVERY registered installPath is protected, not just the first — the plugin may legitimately be
  *     installed at both user and project scope, and treating one as stale would delete a live install.
- *   • The active generation is excluded by RESOLVED PATH, never by version string.
+ *   • Registered generations are excluded by RESOLVED PATH, never by version string.
+ *   • The registry is re-read immediately before deletion; any byte change retains the candidate.
+ *   • Malformed, unreadable, symlinked, live, or unverifiable lease state fails closed.
  *   • Report-only unless `apply` is set, and every removal is returned by name, so a silent sweep is
  *     impossible.
  */
 export function prunePluginGenerations({
   registryPath = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json'),
   apply = false,
+  now = () => Date.now(),
+  graceMs = 14 * 24 * 60 * 60 * 1000,
+  processIdentity = pluginProcessIdentity,
 } = {}) {
-  const nothing = (why) => ({ active: [], stale: [], removed: [], bytes: 0, why });
+  const nothing = (why) => ({ active: [], stale: [], marked: [], removed: [], bytes: 0, staleBytes: 0, cleanupBlocked: [], why });
+  let registryRaw;
   let registry;
-  try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch (e) {
+  try {
+    registryRaw = fs.readFileSync(registryPath, 'utf8');
+    registry = JSON.parse(registryRaw);
+  } catch (e) {
     return nothing(`plugin registry unreadable (${e.code || e.message}) — refusing to remove anything`);
   }
   const active = Object.entries(registry?.plugins || {})
@@ -609,17 +624,126 @@ export function prunePluginGenerations({
       stale.push({ path: full, version: name, bytes: dirBytes(full) });
     }
   }
-  const bytes = stale.reduce((n, s) => n + s.bytes, 0);
-  if (!apply) return { active, stale, removed: [], bytes, why: null };
+  const staleBytes = stale.reduce((n, s) => n + s.bytes, 0);
+  if (!apply) return { active, stale, marked: [], removed: [], bytes: 0, staleBytes, cleanupBlocked: [], why: null };
 
+  const marked = [];
   const removed = [];
+  const cleanupBlocked = [];
   let freed = 0;
-  for (const s of stale) {
-    // One unremovable generation (a permissions quirk, a file held open) must not abort the rest.
-    try { fs.rmSync(s.path, { recursive: true, force: true }); removed.push(s); freed += s.bytes; }
-    catch { /* left in place; it is still reported in `stale` */ }
+  for (const candidate of stale) {
+    const marker = path.join(candidate.path, '.orphaned_at');
+    if (!fs.existsSync(marker)) {
+      const temporary = `${marker}.tmp.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
+      try {
+        fs.writeFileSync(temporary, String(now()), { flag: 'wx', mode: 0o600 });
+        fs.renameSync(temporary, marker);
+        marked.push(candidate.version);
+      } catch {
+        try { fs.rmSync(temporary, { force: true }); } catch { /* retain on ambiguity */ }
+      }
+    }
+
+    let orphanedAt;
+    try {
+      const markerStat = fs.lstatSync(marker);
+      if (!markerStat.isFile() || markerStat.isSymbolicLink()) {
+        cleanupBlocked.push({ version: candidate.version, reason: '.orphaned_at is not a trusted file' });
+        continue;
+      }
+      orphanedAt = Number(fs.readFileSync(marker, 'utf8').trim());
+      if (!Number.isFinite(orphanedAt) || orphanedAt <= 0) {
+        cleanupBlocked.push({ version: candidate.version, reason: '.orphaned_at is malformed' });
+        continue;
+      }
+    } catch {
+      cleanupBlocked.push({ version: candidate.version, reason: '.orphaned_at could not be inspected' });
+      continue;
+    }
+
+    const leaseDir = path.join(candidate.path, '.in_use');
+    let leaseCapable = false;
+    let leaseNames = [];
+    try {
+      if (fs.existsSync(leaseDir)) {
+        const leaseDirStat = fs.lstatSync(leaseDir);
+        if (leaseDirStat.isSymbolicLink() || !leaseDirStat.isDirectory()) {
+          cleanupBlocked.push({ version: candidate.version, reason: '.in_use is not a trusted directory' });
+          continue;
+        }
+        leaseCapable = true;
+        leaseNames = fs.readdirSync(leaseDir);
+      }
+    } catch {
+      cleanupBlocked.push({ version: candidate.version, reason: '.in_use could not be inspected' });
+      continue;
+    }
+
+    if (!leaseCapable && now() - orphanedAt < graceMs) continue;
+    let safeToReap = true;
+    for (const leaseName of leaseNames) {
+      const leasePath = path.join(leaseDir, leaseName);
+      let lease;
+      try {
+        const leaseStat = fs.lstatSync(leasePath);
+        if (!leaseStat.isFile() || leaseStat.isSymbolicLink()) throw new Error('not a trusted file');
+        lease = JSON.parse(fs.readFileSync(leasePath, 'utf8'));
+        if (!Number.isSafeInteger(lease?.pid) || lease.pid <= 0 || typeof lease?.procStart !== 'string' || !lease.procStart.trim()) {
+          throw new Error('malformed');
+        }
+      } catch {
+        cleanupBlocked.push({ version: candidate.version, reason: `lease ${leaseName} is malformed or unreadable` });
+        safeToReap = false;
+        break;
+      }
+      const state = processIdentity(lease);
+      if (state !== 'dead') {
+        cleanupBlocked.push({ version: candidate.version, reason: `lease ${leaseName} is ${state === 'live' ? 'live' : 'ambiguous'}` });
+        safeToReap = false;
+        break;
+      }
+      try { fs.rmSync(leasePath); } catch {
+        cleanupBlocked.push({ version: candidate.version, reason: `dead lease ${leaseName} could not be removed` });
+        safeToReap = false;
+        break;
+      }
+    }
+    if (!safeToReap) continue;
+
+    // The host registry can advance while the collector scans. Any byte change invalidates the
+    // original authority snapshot; retain every candidate rather than deleting on stale evidence.
+    let currentRaw;
+    try { currentRaw = fs.readFileSync(registryPath, 'utf8'); } catch { continue; }
+    if (currentRaw !== registryRaw) continue;
+    try {
+      fs.rmSync(candidate.path, { recursive: true });
+      removed.push(candidate.version);
+      freed += candidate.bytes;
+    } catch { /* retained for a later pass */ }
   }
-  return { active, stale, removed, bytes: freed, why: null };
+  return {
+    active, stale, marked, removed, bytes: freed, staleBytes, cleanupBlocked,
+    why: stale.length
+      ? 'lease-proven orphan reconciliation; legacy generations receive a 14-day grace and live or ambiguous generations are retained'
+      : null,
+  };
+}
+
+/** Verify the exact PID incarnation recorded by a plugin generation lease. */
+function pluginProcessIdentity({ pid, procStart }) {
+  try { process.kill(pid, 0); } catch (error) {
+    return error?.code === 'ESRCH' ? 'dead' : 'unknown';
+  }
+  const result = process.platform === 'win32'
+    ? spawnSync('powershell.exe', [
+      '-NoProfile', '-NonInteractive', '-Command',
+      `$p=Get-Process -Id ${pid} -ErrorAction Stop; $p.StartTime.ToUniversalTime().ToString('ddd MMM dd HH:mm:ss yyyy',[Globalization.CultureInfo]::InvariantCulture)`,
+    ], { encoding: 'utf8' })
+    : spawnSync('ps', ['-p', String(pid), '-o', 'lstart='], {
+      encoding: 'utf8', env: { ...process.env, TZ: 'UTC', LC_ALL: 'C', LANG: 'C' },
+    });
+  if (result.status !== 0 || !String(result.stdout || '').trim()) return 'unknown';
+  return String(result.stdout).trim() === procStart.trim() ? 'live' : 'dead';
 }
 
 /** Size of a directory tree, best-effort — used only to report what was or would be freed. */
@@ -2563,18 +2687,16 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
   const applied = runStableSpine(apply);
   const okApplied = !applied.error && applied.status === 0;
   if (okApplied) {
-    // ISSUE #128 — prune here and nowhere else. This is the moment "an update is a replacement, not
-    // an overlay" becomes true for the host: the new generation is registered and the Stable Spine
-    // has applied, so every OTHER generation in that cache is unreachable by design and can only
-    // mislead — its skills still load, its hooks still fire, and its version banner still speaks.
-    // Making it a consequence of updating, rather than a command someone has to remember, is the
-    // whole point; a cleanup that must be invoked is a cleanup that does not happen.
-    // Best-effort and reported by name — it must never turn a good update into a failed one.
+    // ISSUE #153 — running Claude sessions freeze their plugin root. Collect only generations whose
+    // leases prove that exact PID incarnation dead, or legacy roots past the compatibility grace.
     try {
       const gens = prunePluginGenerations({ apply: true });
       if (gens.removed.length) {
-        ok(`pruned ${gens.removed.length} stale plugin generation(s), freed ${(gens.bytes / 1048576).toFixed(1)} MB: ${gens.removed.map((g) => g.version).join(', ')}`);
-      } else if (gens.why) {
+        ok(`pruned ${gens.removed.length} stale plugin generation(s), freed ${(gens.bytes / 1048576).toFixed(1)} MB: ${gens.removed.join(', ')}`);
+      }
+      if (gens.cleanupBlocked?.length) {
+        warn(`plugin cleanup retained ${gens.cleanupBlocked.length} generation(s): ${gens.cleanupBlocked.map((item) => `${item.version} (${item.reason})`).join(', ')}`);
+      } else if (!gens.removed.length && gens.why) {
         warn(`stale plugin generations were not pruned: ${gens.why}`);
       }
     } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.0.90-dev",
+  "version": "4.2.2-dev",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {

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

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 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.90-dev",
+  "version": "4.2.2-dev",
   "author": {
     "name": "Stuart Kerr"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.0.90-dev",
+  "version": "4.2.2-dev",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/scripts/brain-score.mjs

@@ -132,7 +132,7 @@ function readPanel() {
  * than a guess when the denominator is unknown — a wrong denominator still renders, which is worse
  * than an absent one.
  */
-async function readCoverage() {
+export async function readCoverage(rootOverride) {
   const { storeRoot, storesAt, cardsAt } = await import('../kb/store-root.mjs');
   // ROUTABILITY IS ALIAS-AWARE, BECAUSE THE ROUTER IS.
   //
@@ -148,25 +148,34 @@ async function readCoverage() {
   // broke alias resolution outright. A metric that cannot see aliases manufactures work that
   // damages the thing it measures.
   const { repositoryNames } = await import('../kb/card-lane.mjs');
-  const root = storeRoot();
+  const root = rootOverride ?? storeRoot();
+  // NEVER-MATERIALIZED, THE SAME AMBIGUITY `restore-local-ingests.mjs`'s `classify()` WAS FIXED
+  // FOR (PR #143, Night 1) — but never carried here. `storesAt()`/`cardsAt()` silently return
+  // `[]` on ENOENT, so a host whose store root was never restored (a fresh checkout, this very
+  // nightly agent's own ephemeral container) reads IDENTICALLY to a materialized root that
+  // genuinely has zero coverage. Checked once, here, before either derived number is computed —
+  // a wrong `0` still renders, which is worse than an honestly unmeasured one.
+  const neverMaterialized = !fs.existsSync(root);
   const stores = storesAt(root);
   const cards = new Set(cardsAt(root));
   const org = readJson('data/org-repo-count.json');
   const total = Number.isFinite(org?.count) && org.count > 0 ? org.count : null;
   const carded = stores.filter((s) => isRoutable(s, cards, root, repositoryNames)).length;
+  const absentDetail = 'store root does not exist on this host (never materialized) — not evidence of live coverage';
   return {
     catalogue: {
-      value: total ? Math.round((stores.length / total) * 1000) / 10 : null,
-      detail: total ? `${stores.length}/${total} live repos` : `${stores.length} stores, org total UNKNOWN`,
-      at: org?.at ?? null,
+      value: neverMaterialized ? null : (total ? Math.round((stores.length / total) * 1000) / 10 : null),
+      detail: neverMaterialized ? absentDetail
+        : (total ? `${stores.length}/${total} live repos` : `${stores.length} stores, org total UNKNOWN`),
+      at: neverMaterialized ? null : (org?.at ?? null),
     },
     routable: {
-      value: stores.length ? Math.round((carded / stores.length) * 1000) / 10 : null,
-      detail: `${carded}/${stores.length} built stores have a card`,
+      value: neverMaterialized || !stores.length ? null : Math.round((carded / stores.length) * 1000) / 10,
+      detail: neverMaterialized ? absentDetail : `${carded}/${stores.length} built stores have a card`,
       // Derived from the live store root at this instant, so it is current BY CONSTRUCTION. A
       // read-now value reported as stale would train the reader to ignore the stale flag, which
       // costs more than the flag is worth.
-      at: new Date().toISOString(),
+      at: neverMaterialized ? null : new Date().toISOString(),
     },
   };
 }

package/scripts/build-bundle.mjs

@@ -19,6 +19,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { getVersion, getVersionTag, stripTag } from './version.mjs';
 import { auditRvfIndexes } from './rvf-index-audit.mjs';
+import { validateSelectedRvfGenerations } from './rvf-generation.mjs';
 // The org total is DERIVED, never a literal: it was hardcoded 248 in this file and in its
 // sibling while the account actually had 200 — one stale fact, restated twice (2026-08-12).
 import { orgRepoCount } from './org-repo-count.mjs';
@@ -162,6 +163,15 @@ if (built.length === 0) {
   console.error('[build-bundle] FATAL: zero public RVF stores are eligible for release. Refusing to publish an empty brain bundle.');
   process.exit(1);
 }
+const generationValidation = validateSelectedRvfGenerations(ASSETS, {
+  selectedStores: built,
+  privateStores: [...PRIVATE_STORES],
+});
+if (generationValidation.failures.length) {
+  console.error('[build-bundle] FATAL: RVF generation ledger does not exactly bind selected roots:');
+  for (const failure of generationValidation.failures) console.error(`  ${failure}`);
+  process.exit(1);
+}
 const rvfIndexAudit = await auditRvfIndexes(
   built.map((name) => path.join(ASSETS, `${name}.big.rvf`)),
 );
@@ -208,7 +218,7 @@ for (const name of built) {
   if (!fs.existsSync(generationsFile)) {
     missing.push('RVF-GENERATIONS.json');
   } else {
-    const source = JSON.parse(fs.readFileSync(generationsFile, 'utf8'));
+    const source = generationValidation.manifest;
     const stores = {};
     for (const { name } of builtRepos) {
       if (!source.stores?.[name]) missing.push(`RVF-GENERATIONS.json:${name}`);
@@ -216,8 +226,8 @@ for (const name of built) {
     }
     fs.writeFileSync(path.join(OUT, 'RVF-GENERATIONS.json'), `${JSON.stringify({
       schemaVersion: source.schemaVersion,
-      brainVersion: source.brainVersion,
-      releaseTag: source.releaseTag,
+      brainVersion: stripTag(BRAIN_VERSION),
+      releaseTag: BRAIN_VERSION,
       stores,
     }, null, 2)}\n`);
     copied++;

package/scripts/card-from-source.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * card-from-source.mjs — give a DARK store a card written from the repo's own words.
+ *
+ * A store with no capability card is DARK: the bytes are valid and no by-description query can
+ * reach them. `ingest-repo.mjs` says so on every run. After the 2026-08-20 bulk ingest the brain
+ * held ~111 stores and ~71 of them were dark — loaded, and unusable for anything except a query
+ * that already knew the repo's name, which is precisely the query a knowledge base is least needed
+ * for.
+ *
+ * THE LINE THIS DOES NOT CROSS. `ingest-new-repos.mjs` deliberately refuses to write cards, because
+ * a card invented from a repo NAME is a confident claim in the routing layer that nobody grounded —
+ * it routes real questions to a corpus that cannot answer them, which is worse than an honest gap.
+ * That refusal stands. This is a different act: it copies the repo's OWN description and the
+ * opening of its OWN README. Every content word in the card came from the repository. Nothing here
+ * infers what a project is "probably" for.
+ *
+ * AND IT SAYS WHAT IT IS. Each generated card carries a marker so a reader can tell it apart from
+ * the hand-written ones, which are richer — they say when to REACH for a tool and what it is NOT.
+ * An auto-derived card is a floor, not a substitute: it makes a store reachable and invites a
+ * better card later. Claiming otherwise would be the overselling this file exists to avoid.
+ *
+ *   node scripts/card-from-source.mjs                 # report which stores are dark
+ *   node scripts/card-from-source.mjs --apply         # write cards for them
+ *   node scripts/card-from-source.mjs --apply --max 20
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { storeRoot, darkStores } from '../kb/store-root.mjs';
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const OWNER = process.env.RUVNET_ORG_OWNER || 'ruvnet';
+const APPLY = process.argv.includes('--apply');
+const arg = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
+const MAX = Number(arg('--max', '500'));
+export const MARKER = 'Auto-derived from the repository\'s own description and README';
+
+/** The repo's own description + README opening. Never a guess about what the name implies. */
+export function sourceFacts(repo) {
+  let description = '';
+  let readme = '';
+  try {
+    const meta = JSON.parse(execFileSync('gh', ['api', `repos/${OWNER}/${repo}`], { encoding: 'utf8', maxBuffer: 1 << 24 }));
+    description = String(meta?.description || '').trim();
+  } catch { /* a repo can legitimately have no description */ }
+  try {
+    const raw = execFileSync('gh', ['api', `repos/${OWNER}/${repo}/readme`, '-H', 'Accept: application/vnd.github.raw'],
+      { encoding: 'utf8', maxBuffer: 1 << 24 });
+    readme = raw;
+  } catch { /* and no README */ }
+  return { description, readme };
+}
+
+/** First real prose of a README: skip badges, HTML, headings, and link-only lines. */
+export function firstProse(readme, limit = 600) {
+  const lines = String(readme || '').split('\n');
+  const out = [];
+  for (const line of lines) {
+    const t = line.trim();
+    if (!t) { if (out.length) break; continue; }
+    if (t.startsWith('#') || t.startsWith('<') || t.startsWith('|') || t.startsWith('---')) continue;
+    if (/^!?\[[^\]]*\]\([^)]*\)$/.test(t)) continue;          // a lone badge or image
+    if (/^\[!\[/.test(t)) continue;                            // badge-wrapped link
+    out.push(t);
+    if (out.join(' ').length > limit) break;
+  }
+  return out.join(' ').replace(/\s+/g, ' ').slice(0, limit).trim();
+}
+
+export function buildCard(repo, { description, readme }) {
+  const prose = firstProse(readme);
+  if (!description && !prose) return null;   // nothing grounded to say — leave it dark, honestly
+  const body = [description, prose].filter(Boolean).join(' — ');
+  return `## ${repo.toLowerCase()}\n${body}\n(${MARKER}; a hand-written card saying when to reach for it, and when not to, would be better.)\n`;
+}
+
+function insertSorted(file, card, name) {
+  const s = fs.readFileSync(file, 'utf8');
+  if (new RegExp(`^## ${name}$`, 'mi').test(s)) return false;
+  const heads = [...s.matchAll(/^## (.+)$/gm)].map((m) => [m.index, m[1].trim().toLowerCase()]);
+  const pos = heads.find(([, n]) => n > name)?.[0];
+  fs.writeFileSync(file, pos === undefined ? `${s.replace(/\n+$/, '')}\n\n${card}` : s.slice(0, pos) + card + '\n' + s.slice(pos));
+  return true;
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  const root = storeRoot();
+  const dark = darkStores(root);
+  console.log(`[card] ${dark.length} dark store(s) — valid bytes no by-description query can reach`);
+  if (!dark.length) process.exit(0);
+  if (!APPLY) {
+    console.log(`[card] ${dark.slice(0, 20).join(', ')}${dark.length > 20 ? ' …' : ''}`);
+    console.log('[card] report only. Re-run with --apply to write cards from each repo\'s own source.');
+    process.exit(0);
+  }
+  const repoCards = path.join(ROOT, 'kb', 'capability-cards.md');
+  const liveCards = path.join(root, 'capability-cards.md');
+  let wrote = 0; let skipped = 0;
+  for (const name of dark.slice(0, MAX)) {
+    const card = buildCard(name, sourceFacts(name));
+    if (!card) { skipped += 1; console.log(`[card] ${name}: no description and no README prose — left dark rather than invented`); continue; }
+    for (const f of [repoCards, liveCards]) { try { insertSorted(f, card, name.toLowerCase()); } catch { /* keep going */ } }
+    wrote += 1;
+  }
+  const remaining = darkStores(root).length;
+  console.log(`\n[card] wrote ${wrote}, left ${skipped} dark for lack of grounded source text, ${remaining} still dark.`);
+}