klypix-mcp 1.12.0 → 1.13.0

package/bin/klypix-doctor.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// klypix-doctor — `npx klypix-mcp doctor`. The brain's self-check: is THIS machine's
+// brain current, are the 4 Claude Code hooks wired, what verbs does it expose, who else
+// is live on this project's brain, and is the harness projection in sync? ONE fact, ONE
+// reconcile block. Read-only (never writes). Exits 0 = ALIGNED, 1 = DRIFTED — so it
+// doubles as a pre-commit / CI readiness gate.
+//
+//   npx klypix-mcp doctor              # this project + this machine's brain
+//   npx klypix-mcp doctor --npm        # also fetch npm 'latest' and flag a stale brain
+//   npx klypix-mcp doctor --all        # + every registered brain on this machine + vault wiring
+//   npx klypix-mcp doctor --project <dir> | --json | --no-color
+//
+// Synchronous-ish top-level by design: the dispatcher does `await import(this);
+// process.exit(...)`, so all work completes during module evaluation.
+import path from 'path';
+import { execSync } from 'child_process';
+import { inspect, render, inspectAll } from '../src/brain-doctor.mjs';
+
+try {
+  const argv = process.argv.slice(2);
+  const has = (f) => argv.includes(f);
+  const val = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : undefined; };
+  const color = !has('--no-color') && process.stdout.isTTY !== false;
+  const projectDir = path.resolve(val('--project') || process.cwd());
+
+  let npmLatest = null;
+  if (has('--npm')) {
+    try { npmLatest = execSync('npm view klypix-mcp version', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 8000 }).trim(); }
+    catch { npmLatest = '(offline)'; }
+  }
+
+  const report = inspect({ projectDir, npmLatest });
+
+  if (has('--json')) {
+    const all = has('--all') ? inspectAll() : undefined;
+    console.log(JSON.stringify({ ...report, ...(all ? { crossProject: all } : {}) }, null, 2));
+    process.exit(report.verdict === 'DRIFTED' ? 1 : 0);
+  }
+
+  console.log(render(report, { color }));
+
+  let extraDrift = 0;
+  if (has('--all')) {
+    const all = inspectAll();
+    extraDrift = all.drift;
+    const dim = color ? '\x1b[2m' : '', red = color ? '\x1b[31m' : '', grn = color ? '\x1b[32m' : '', rst = color ? '\x1b[0m' : '';
+    console.log(`\n# registered brains (${all.brains.length})`);
+    for (const b of all.brains) {
+      const tag = b.exists ? grn + '●' + rst : red + '○ missing' + rst;
+      const v = !b.hasMcp ? dim + 'no .mcp.json (global config)' + rst : b.vaultOk ? grn + `vault ✓ (${b.vault})` + rst : red + `vault ⚠ ${b.vault} — not this project!` + rst;
+      console.log(`  ${tag} ${b.project} · ${v}\n      ${dim}${b.path}${rst}`);
+    }
+  }
+
+  const drifted = report.verdict === 'DRIFTED' || extraDrift > 0;
+  console.log(drifted ? (color ? '\x1b[33m' : '') + `\n✗ drift found — see reconcile above.` + (color ? '\x1b[0m' : '')
+    : report.verdict === 'NOT-INSTALLED' ? '\n• brain not installed on this machine.'
+      : (color ? '\x1b[32m' : '') + '\n✓ aligned.' + (color ? '\x1b[0m' : ''));
+  process.exit(drifted ? 1 : 0);
+} catch (e) {
+  console.error(`✗ doctor failed: ${e?.message || e}`);
+  process.exit(1);
+}

package/bin/klypix-install.mjs

@@ -141,9 +141,18 @@ try {
     // 6) stamp the install (unified brain version → never-downgrade across channels)
     fs.writeFileSync(path.join(BRAIN_DIR, '.brain-version.json'), JSON.stringify({ brainVersion: VERSION, via: 'npm', dirty: false, installedAt: new Date().toISOString() }, null, 2));
 
+    // 7) READINESS check — re-read what we just wrote and confirm all 4 hooks actually
+    //    took (a malformed pre-existing group, a partial merge, or a later hand-edit can
+    //    leave the brain LIVE but not LEARNING — liveness ≠ readiness). Warn, don't fail.
+    const verify = (() => { try { return JSON.parse(fs.readFileSync(SETTINGS, 'utf8')); } catch { return null; } })();
+    const wiredFor = (evt) => Array.isArray(verify?.hooks?.[evt]) && verify.hooks[evt].some(g => Array.isArray(g?.hooks) && g.hooks.some(h => typeof h?.command === 'string' && h.command.includes(HOOK_MARK)));
+    const notWired = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse'].filter(e => !wiredFor(e));
+
     console.log(`✓ installed klypix brain v${VERSION} → ${BRAIN_DIR}  (${n} scripts, ${deps} dep packages)`);
-    console.log('✓ wired 4 hooks: SessionStart · UserPromptSubmit (--prompt) · Stop (--capture) · PostToolUse (--live) → settings.json');
+    if (!notWired.length) console.log('✓ wired 4 hooks: SessionStart · UserPromptSubmit (--prompt) · Stop (--capture) · PostToolUse (--live) → settings.json');
+    else console.error(`⚠ readiness: ${notWired.length} hook(s) did NOT take (${notWired.join(', ')}) — the brain will read but not capture/sync. Re-run \`npx klypix-mcp install --force\` or check ${SETTINGS}.`);
     console.log('  Every project with a ./brain.klypix now auto-reads its brief + captures decisions. Restart open Claude Code sessions to load the hooks.');
+    console.log('  Verify anytime: `npx klypix-mcp doctor` (is the brain current + wired + in sync, who else is live).');
 } catch (e) {
     console.error(`✗ install failed: ${e?.message || e}`);
     process.exit(1);

package/bin/klypix-link.mjs

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 // klypix-link — make THIS project's brain automatic for EVERY agent tool.
 // `npx klypix-mcp install` gives Claude Code the brain via hooks; `link` extends the
-// same automatic read+capture to Cursor, Cline, Windsurf, Copilot/VS Code, and any
-// AGENTS.md-reading agent, by dropping each tool's native MCP config + rules file in
-// the current project. Idempotent — re-run anytime to refresh. Project-scoped (cwd);
-// touches only files inside the project. Reports what it did; exits non-zero on hard fail.
+// same automatic read+capture to Cursor, Cline, Windsurf, Copilot/VS Code, Gemini CLI,
+// Aider, and any AGENTS.md-reading agent, by dropping each tool's native MCP config +
+// rules file in the current project. Idempotent — re-run anytime to refresh. The managed
+// block carries the brain version + a content hash, so:
 //
-//   cd your-project && npx klypix-mcp link
+//   npx klypix-mcp link            # (re)project every managed block (write)
+//   npx klypix-mcp link --check    # AUDIT only — classify each file ok/stale/hand-edited/
+//                                  # missing WITHOUT writing; exits 1 on drift (CI/pre-commit gate)
+//
+// Project-scoped (cwd); touches only files inside the project. Reports what it did;
+// exits non-zero on hard fail / on detected drift in --check.
 //
 // Synchronous top-level by design: the dispatcher does `await import(this); process.exit(0)`,
 // so all work (and its logs) must complete during module evaluation, before exit.
@@ -14,12 +19,28 @@ import path from 'path';
 import { linkProject } from '../src/agent-rules.mjs';
 
 try {
-  const dirArg = process.argv.slice(3).find(a => !a.startsWith('-'));
+  const args = process.argv.slice(3);
+  const check = args.includes('--check');
+  const dirArg = args.find(a => !a.startsWith('-'));
   const projectDir = path.resolve(dirArg || process.cwd());
-  const { rules, mcp, hasBrain } = linkProject(projectDir);
+  const { rules, mcp, hasBrain, version } = linkProject(projectDir, { check });
+
+  if (check) {
+    // Audit-only: classify, report, exit 1 on any drift.
+    const mark = (s) => s === 'ok' ? '✓' : '⚠';
+    console.log(`klypix — auditing the brain projection in ${projectDir} (brain v${version})\n`);
+    console.log('  MCP server config:');
+    for (const r of mcp) console.log(`    ${mark(r.status)} ${r.tool.padEnd(26)} ${r.file} — ${r.status.toUpperCase()}${r.why ? ' (' + r.why + ')' : ''}`);
+    console.log('\n  Rules / instructions:');
+    for (const r of rules) console.log(`    ${mark(r.status)} ${r.tool.padEnd(26)} ${r.file} — ${r.status.toUpperCase()}${r.stampedVersion ? ' (stamped v' + r.stampedVersion + ')' : ''}`);
+    const drift = [...rules, ...mcp].filter(r => r.status !== 'ok');
+    if (!drift.length) { console.log(`\n✓ in sync — all ${rules.length + mcp.length} managed file(s) match brain v${version}.`); process.exit(0); }
+    console.log(`\n✗ ${drift.length} file(s) drifted (stale / hand-edited / missing) — run \`npx klypix-mcp link\` to re-project.`);
+    process.exit(1);
+  }
 
   const mark = (a) => a === 'unchanged' ? '·' : a === 'skipped' ? '⚠' : '✓';
-  console.log(`klypix — linking the brain to every agent tool in ${projectDir}\n`);
+  console.log(`klypix — linking the brain to every agent tool in ${projectDir} (brain v${version})\n`);
   console.log('  MCP server (so each tool can reach the brain):');
   for (const r of mcp) console.log(`    ${mark(r.action)} ${r.tool.padEnd(26)} ${r.file}${r.why ? '  (' + r.why + ')' : ''}`);
   console.log('\n  Rules (so each tool auto-reads + captures the brain):');
@@ -28,6 +49,7 @@ try {
   const changed = [...rules, ...mcp].filter(r => r.action && !['unchanged', 'skipped'].includes(r.action)).length;
   console.log(`\n✓ ${changed} file(s) written/updated — every agent opened in this project now reads + captures ./brain.klypix.`);
   console.log('  Cline & Windsurf MCP servers live in their global config; the rules file points them at the brain regardless.');
+  console.log('  Verify anytime with `npx klypix-mcp link --check` (or `npx klypix-mcp doctor`).');
   if (!hasBrain) {
     console.log('\n⚠ No ./brain.klypix here yet — the rules reference it for when you create one.');
     console.log('  Make one in the KLYPIX app (Canvas → Save as brain) or with the create_canvas MCP tool.');

package/bin/klypix-mcp.mjs

@@ -47,6 +47,11 @@ if (process.argv[2] === 'install') { await import('./klypix-install.mjs'); proce
 // brain on its own. Project-scoped (cwd); idempotent. Runs before any server setup.
 if (process.argv[2] === 'link') { await import('./klypix-link.mjs'); process.exit(0); }
 
+// `npx klypix-mcp doctor` — the brain's READ-ONLY self-check: is this machine's brain
+// current, are the 4 hooks wired, what verbs does it expose, who's live, is the harness
+// projection in sync? One verdict, one reconcile block. Exits 1 on drift (CI gate).
+if (process.argv[2] === 'doctor') { await import('./klypix-doctor.mjs'); process.exit(0); }
+
 // `npx klypix-mcp init` — 60-second onboarding: seed a starter project brain in
 // the current folder so a new user's FIRST contact isn't an empty vault, then
 // print a paste-ready MCP config. Runs before any server setup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,7 @@
   "bin": {
     "klypix-mcp": "bin/klypix-mcp.mjs",
     "klypix-link": "bin/klypix-link.mjs",
+    "klypix-doctor": "bin/klypix-doctor.mjs",
     "klypix-a2a": "bin/klypix-a2a.mjs",
     "klypix-read": "bin/klypix-read.mjs",
     "klypix-write": "bin/klypix-write.mjs",

package/src/agent-rules.mjs

@@ -1,7 +1,8 @@
 // agent-rules — make a project's brain.klypix AUTOMATIC for EVERY agent tool, not
 // just Claude Code. Claude Code gets the brain via hooks (settings.json, see
-// klypix-install). Other agents (Cursor, Cline, Windsurf, Copilot/VS Code, and the
-// AGENTS.md cross-tool standard) have no hook system — so we drop their NATIVE files:
+// klypix-install). Other agents (Cursor, Cline, Windsurf, Copilot/VS Code, Gemini
+// CLI, Aider, and the AGENTS.md cross-tool standard) have no hook system — so we
+// drop their NATIVE files:
 //
 //   • an MCP server config  → the agent CAN reach the brain's tools
 //   • a rules / instructions → the agent is TOLD to read the brain at task start and
@@ -9,14 +10,39 @@
 //
 // Agent-neutral by construction: the brain DATA is one shared brain.klypix; this just
 // teaches each tool to use it. Idempotent — owned files are rewritten wholesale; shared
-// files (AGENTS.md, copilot-instructions.md) get a fenced block merged in place, never
-// clobbering the user's own content. Pure fs/path; never throws for one bad target.
+// files (AGENTS.md, copilot-instructions.md, GEMINI.md) get a fenced block merged in
+// place, never clobbering the user's own content. Pure fs/path; never throws for one bad
+// target.
+//
+// DRIFT-AWARE (added 1.13.0): the managed fence now carries `v=<brainVersion>` +
+// `hash=<contentHash>` so a projected block is CLASSIFIABLE without re-writing it —
+// ok / stale (older brain) / hand-edited (content changed inside the block) / missing.
+// `linkProject(dir, { check:true })` returns that audit without touching disk; it's what
+// `npx klypix-mcp link --check` and `brain_doctor`'s harness layer read. Closes the
+// audited "harness projection is write-once, drift is undetectable" gap.
 import fs from 'fs';
 import path from 'path';
-
-const FENCE_START = '<!-- klypix-brain:start (managed by klypix-mcp — re-run `npx klypix-mcp link`) -->';
-const FENCE_END = '<!-- klypix-brain:end -->';
-const FENCE_RE = /<!--\s*klypix-brain:start[\s\S]*?klypix-brain:end\s*-->/;
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const sha8 = (s) => crypto.createHash('sha1').update(String(s)).digest('hex').slice(0, 8);
+const cmpSemver = (a, b) => { const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0), pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0); for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); } return 0; };
+
+// The klypix-mcp version this projection was written from — stamped into the fence so a
+// later session can tell a stale block (older brain) from a hand-edited one. Read from
+// package.json walking up from this file (the flat ~/.claude runtime has no versioned
+// package.json, but `link` always runs from the npm package, where it does). Overridable
+// via linkProject(dir, { version }).
+export function resolveVersion() {
+  let dir = HERE;
+  for (; ;) {
+    try { const v = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version; if (v) return v; } catch { /* keep walking */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) return '0.0.0';
+    dir = parent;
+  }
+}
 
 // The one canonical instruction every agent gets. Tool-and-CLI dual so it works whether
 // or not the agent has the klypix-canvas MCP wired.
@@ -39,17 +65,55 @@ Capture **sparingly** — real decisions/milestones, not routine steps. Link rel
 
 **Don't** hand-edit \`brain.klypix\` (it's a packaged canvas — use the tools) or dump file contents into it; capture the *decision*, not the file.`;
 
-const fencedBlock = () => `${FENCE_START}\n${BRAIN_INSTRUCTIONS}\n${FENCE_END}`;
+// Content fingerprint of the canonical instructions — stamped into the fence so a
+// hand-edit INSIDE the block (body != what its hash claims) is detectable.
+const INSTRUCTIONS_HASH = sha8(BRAIN_INSTRUCTIONS);
+
+const FENCE_END = '<!-- klypix-brain:end -->';
+// Versioned + hashed start marker. The attrs are between `start` and the closing `-->`,
+// so the BROAD FENCE_RE (which matches any start…end) still replaces an OLD unstamped
+// block on the next `link` — the upgrade is idempotent.
+const fenceStart = (ver) => `<!-- klypix-brain:start v=${ver} hash=${INSTRUCTIONS_HASH} (managed by klypix-mcp — re-run \`npx klypix-mcp link\`) -->`;
+const FENCE_RE = /<!--\s*klypix-brain:start[\s\S]*?klypix-brain:end\s*-->/;
+// Capturing parse: v=(group1) hash=(group2) inner-body(group3). Attrs optional so a
+// legacy unstamped block parses too (version/hash come back undefined → treated as stale).
+const FENCE_PARSE_RE = /<!--\s*klypix-brain:start(?:\s+v=([0-9][0-9.]*))?(?:\s+hash=([0-9a-f]+))?[\s\S]*?-->([\s\S]*?)<!--\s*klypix-brain:end\s*-->/;
+
+const fencedBlock = (ver) => `${fenceStart(ver)}\n${BRAIN_INSTRUCTIONS}\n${FENCE_END}`;
 
 const exists = (p) => { try { fs.statSync(p); return true; } catch { return false; } };
 const ensureDir = (p) => fs.mkdirSync(path.dirname(p), { recursive: true });
 
-// Shared markdown (AGENTS.md, copilot-instructions.md): merge our fenced block in place.
-function fenceMerge(file) {
+// Parse a managed block out of arbitrary file text → { version, hash, body } | null.
+function parseFence(text) {
+  const m = String(text || '').match(FENCE_PARSE_RE);
+  if (!m) return null;
+  return { version: m[1] || null, hash: m[2] || null, body: m[3] || '' };
+}
+
+// Classify a projected fenced file WITHOUT writing (the drift audit).
+//   missing      — file absent, or present but carries no managed block
+//   hand-edited  — block body no longer matches the hash it was stamped with
+//   stale        — block intact but stamped from an older brain (version < current),
+//                   or a legacy unstamped block (no version) → a re-link refreshes it
+//   ok           — block present, current version, body matches its hash
+function classifyFenced(file, version) {
+  if (!exists(file)) return { status: 'missing' };
+  const fence = parseFence(fs.readFileSync(file, 'utf8'));
+  if (!fence) return { status: 'missing' };
+  if (fence.hash && sha8(fence.body.trim()) !== fence.hash) return { status: 'hand-edited', stampedVersion: fence.version };
+  if (!fence.version) return { status: 'stale', stampedVersion: null };
+  if (cmpSemver(fence.version, version) < 0) return { status: 'stale', stampedVersion: fence.version };
+  return { status: 'ok', stampedVersion: fence.version };
+}
+
+// Shared markdown (AGENTS.md, copilot-instructions.md, GEMINI.md): merge our fenced
+// block in place, preserving the user's own prose outside the fence.
+function fenceMerge(file, version) {
   let cur = '';
   let had = false;
   if (exists(file)) { cur = fs.readFileSync(file, 'utf8'); had = true; }
-  const block = fencedBlock();
+  const block = fencedBlock(version);
   let next;
   let action;
   if (FENCE_RE.test(cur)) { next = cur.replace(FENCE_RE, block); action = 'updated'; }
@@ -61,11 +125,12 @@ function fenceMerge(file) {
 }
 
 // Owned dedicated rules file: rewrite wholesale (optional frontmatter for always-apply).
-function writeDedicated(file, frontmatter) {
-  const body = (frontmatter ? frontmatter + '\n' : '') + fencedBlock() + '\n';
-  if (exists(file) && fs.readFileSync(file, 'utf8') === body) return { action: 'unchanged' };
+function writeDedicated(file, frontmatter, version) {
+  const body = (frontmatter ? frontmatter + '\n' : '') + fencedBlock(version) + '\n';
+  const had = exists(file);
+  if (had && fs.readFileSync(file, 'utf8') === body) return { action: 'unchanged' };
   ensureDir(file); fs.writeFileSync(file, body, 'utf8');
-  return { action: exists(file) ? 'updated' : 'created' };
+  return { action: had ? 'updated' : 'created' };
 }
 
 // Project-level MCP config: add the klypix-canvas server, preserving any sibling servers.
@@ -87,40 +152,81 @@ function mergeMcpJson(file, wrapKey, withType) {
   return { action: before === undefined ? 'created' : 'updated' };
 }
 
+// Check-only classifier for an MCP json: is the klypix-canvas server wired?
+function classifyMcp(file, wrapKey) {
+  if (!exists(file)) return { status: 'missing' };
+  try {
+    const cfg = JSON.parse(fs.readFileSync(file, 'utf8') || '{}');
+    return cfg?.[wrapKey]?.['klypix-canvas'] ? { status: 'ok' } : { status: 'missing' };
+  } catch { return { status: 'hand-edited', why: 'invalid JSON' }; }
+}
+
+// The projection map — the single source of truth shared by WRITE (linkProject) and
+// CHECK (auditProject), so the two can never disagree about what's projected where.
+function targets(projectDir) {
+  const j = (...p) => path.join(projectDir, ...p);
+  return {
+    rules: [
+      { tool: 'AGENTS.md (cross-tool standard)', file: j('AGENTS.md'), kind: 'merge' },
+      { tool: 'Cursor', file: j('.cursor', 'rules', 'klypix-brain.mdc'), kind: 'dedicated', frontmatter: '---\ndescription: KLYPIX project brain — read at task start, capture decisions\nalwaysApply: true\n---' },
+      { tool: 'Windsurf', file: j('.windsurf', 'rules', 'klypix-brain.md'), kind: 'dedicated', frontmatter: '---\ntrigger: always_on\n---' },
+      { tool: 'Cline', file: j('.clinerules', 'klypix-brain.md'), kind: 'dedicated', frontmatter: '' },
+      { tool: 'GitHub Copilot', file: j('.github', 'copilot-instructions.md'), kind: 'merge' },
+      // Added 1.13.0 — close the "not generated at all" coverage gap the audit flagged.
+      { tool: 'Gemini CLI', file: j('GEMINI.md'), kind: 'merge' },
+      { tool: 'Aider', file: j('CONVENTIONS.md'), kind: 'dedicated', frontmatter: '' },
+    ],
+    mcp: [
+      { tool: 'Cursor', file: j('.cursor', 'mcp.json'), wrapKey: 'mcpServers', withType: false },
+      { tool: 'VS Code (Copilot/Continue)', file: j('.vscode', 'mcp.json'), wrapKey: 'servers', withType: true },
+    ],
+  };
+}
+
+const relFile = (projectDir, abs) => path.relative(projectDir, abs).replace(/\\/g, '/');
+
 /**
- * Wire a project so EVERY agent tool reads + captures its brain automatically.
+ * Wire a project so EVERY agent tool reads + captures its brain automatically — or,
+ * with { check:true }, AUDIT the projection without touching disk.
  * @param {string} projectDir absolute project root (holds ./brain.klypix)
- * @returns {{ rules: Array, mcp: Array, hasBrain: boolean }}
+ * @param {{ version?: string, check?: boolean }} [opts]
+ * @returns {{ rules: Array, mcp: Array, hasBrain: boolean, version: string, check: boolean }}
  */
-export function linkProject(projectDir) {
-  const j = (...p) => path.join(projectDir, ...p);
-  const hasBrain = exists(j('brain.klypix')) || exists(j('brain.any'));
-
-  // ── Rules / instructions (the "automatically use the brain" half) ──────────────
-  const rules = [
-    // AGENTS.md — the emerging cross-tool standard (Codex, Jules, Zed, Cursor-also-reads…)
-    { tool: 'AGENTS.md (cross-tool standard)', file: 'AGENTS.md', ...fenceMerge(j('AGENTS.md')) },
-    // Cursor — dedicated always-applied rule
-    { tool: 'Cursor', file: '.cursor/rules/klypix-brain.mdc', ...writeDedicated(j('.cursor', 'rules', 'klypix-brain.mdc'),
-      '---\ndescription: KLYPIX project brain — read at task start, capture decisions\nalwaysApply: true\n---') },
-    // Windsurf — dedicated always-on rule
-    { tool: 'Windsurf', file: '.windsurf/rules/klypix-brain.md', ...writeDedicated(j('.windsurf', 'rules', 'klypix-brain.md'),
-      '---\ntrigger: always_on\n---') },
-    // Cline — drops a file in .clinerules/ (Cline reads every file there)
-    { tool: 'Cline', file: '.clinerules/klypix-brain.md', ...writeDedicated(j('.clinerules', 'klypix-brain.md'), '') },
-    // GitHub Copilot — repo-wide custom instructions
-    { tool: 'GitHub Copilot', file: '.github/copilot-instructions.md', ...fenceMerge(j('.github', 'copilot-instructions.md')) },
-  ];
-
-  // ── MCP server config (the "can reach the brain's tools" half) ─────────────────
-  // Project-level files only; Claude Code is covered by `install` (hooks + bundled MCP),
-  // so we skip .mcp.json to avoid double-registering its server.
-  const mcp = [
-    { tool: 'Cursor', file: '.cursor/mcp.json', ...mergeMcpJson(j('.cursor', 'mcp.json'), 'mcpServers', false) },
-    { tool: 'VS Code (Copilot/Continue)', file: '.vscode/mcp.json', ...mergeMcpJson(j('.vscode', 'mcp.json'), 'servers', true) },
-  ];
-
-  return { rules, mcp, hasBrain };
+export function linkProject(projectDir, opts = {}) {
+  const version = opts.version || resolveVersion();
+  const check = !!opts.check;
+  const t = targets(projectDir);
+  const hasBrain = exists(path.join(projectDir, 'brain.klypix')) || exists(path.join(projectDir, 'brain.any'));
+
+  const rules = t.rules.map((r) => {
+    const file = relFile(projectDir, r.file);
+    if (check) return { tool: r.tool, file, ...classifyFenced(r.file, version) };
+    const res = r.kind === 'merge' ? fenceMerge(r.file, version) : writeDedicated(r.file, r.frontmatter, version);
+    return { tool: r.tool, file, ...res };
+  });
+
+  // Project-level MCP files only; Claude Code is covered by `install` (hooks + bundled
+  // MCP), so we skip .mcp.json to avoid double-registering its server.
+  const mcp = t.mcp.map((m) => {
+    const file = relFile(projectDir, m.file);
+    if (check) return { tool: m.tool, file, ...classifyMcp(m.file, m.wrapKey) };
+    return { tool: m.tool, file, ...mergeMcpJson(m.file, m.wrapKey, m.withType) };
+  });
+
+  return { rules, mcp, hasBrain, version, check };
+}
+
+/**
+ * Check-only harness audit (no writes) — the harness layer of brain_doctor / the body
+ * of `npx klypix-mcp link --check`. Rolls the per-file classification into drift sets.
+ * @returns {{ files, drift, unprojected, ok, version }}
+ */
+export function auditProject(projectDir, opts = {}) {
+  const { rules, mcp, version } = linkProject(projectDir, { ...opts, check: true });
+  const files = [...rules, ...mcp];
+  const ACTIONABLE = new Set(['missing', 'stale', 'hand-edited']);
+  const drift = files.filter((f) => ACTIONABLE.has(f.status));
+  return { files, drift, ok: drift.length === 0, version };
 }
 
-export { BRAIN_INSTRUCTIONS };
+export { BRAIN_INSTRUCTIONS, INSTRUCTIONS_HASH, FENCE_RE, parseFence, cmpSemver };

package/src/brain-doctor.mjs

@@ -0,0 +1,248 @@
+// brain-doctor — the brain reads its OWN state and reports it as ONE fact.
+// ============================================================================
+// The audited gap: klypix had a dozen stamps and footers but no single surface that
+// answers "is THIS brain current, are my hooks wired, is the harness projection in
+// sync, and who else is live?". Liveness ("a process is up") was conflated with
+// readiness ("fully wired + consistent"). This is that surface — a pure, read-only
+// inspection over seams that already exist:
+//
+//   • VERSION   — the BAKED brain-core version (PKG_VERSION in the installed
+//                 klypix-mcp-server.mjs) is the source of truth, because the install
+//                 stamp's version key is channel-dependent (npm writes `brainVersion`,
+//                 the desktop app writes `appVersion`). + the deploy `dirty` flag.
+//   • HOOKS     — are all 4 Claude Code hooks actually wired (HOOK_MARK present)?
+//                 SessionStart firing proves liveness; the other 3 prove readiness.
+//   • TOOLS     — the discoverable MCP verb manifest (what the installed server
+//                 REALLY registers) so a caller can't assume a phantom tool.
+//   • PEERS     — live sessions on this project's brain (the alignment seam), so
+//                 "who else is editing right now?" is answerable, not just footer-passive.
+//   • HARNESS   — per-file projection drift (ok/stale/hand-edited/missing) via the
+//                 versioned fence in agent-rules.
+//
+// Pure node builtins + agent-rules (both in the published package). Never throws on a
+// missing seam — an absent file is a fact to report, not an error.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+import { auditProject, resolveVersion } from './agent-rules.mjs';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const sha = (s) => crypto.createHash('sha1').update(String(s)).digest('hex').slice(0, 16);
+// Same normalization the hook uses to key the sessions lane: forward slashes + a
+// lowercased drive letter, so the CLI computes the SAME sessions filename the hook wrote.
+const normBrainPath = (p) => String(p).replace(/\\/g, '/').replace(/^[a-zA-Z]:/, (m) => m.toLowerCase());
+const readJson = (p, fb = null) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return fb; } };
+const readText = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } };
+const cmpSemver = (a, b) => { const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0), pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0); for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); } return 0; };
+
+const HOOK_MARK = 'global-brain-hook';
+const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse'];
+const SESSION_FRESH_MS = 10 * 60 * 1000;   // matches the hook's lane-freshness window
+
+// ── VERSION layer ────────────────────────────────────────────────────────────
+function inspectVersion(brainDir) {
+  // The baked version in the DEPLOYED server is authoritative (channel-independent).
+  const serverSrc = readText(path.join(brainDir, 'klypix-mcp-server.mjs'));
+  const m = serverSrc && serverSrc.match(/const PKG_VERSION = '([^']+)'/);
+  const baked = m ? m[1] : null;
+  const stamp = readJson(path.join(brainDir, '.brain-version.json'), null);
+  // The stamp's version is `brainVersion` (npm) OR `appVersion` (desktop app) — read both.
+  const stampVersion = stamp ? (stamp.brainVersion || stamp.appVersion || null) : null;
+  return {
+    installed: !!serverSrc || !!stamp,
+    baked,                                     // real brain-core version (or null if not deployed)
+    channel: stamp?.via || null,               // 'npm' | 'app' | 'dev' | null
+    stampVersion,                              // provenance only (namespace varies by channel)
+    dirty: !!(stamp && stamp.dirty),
+    dev: !!(stamp && stamp.dev),
+    sourceSha: stamp?.sourceSha || null,
+    installedAt: stamp?.installedAt || stamp?.deployedAt || null,
+  };
+}
+
+// ── HOOKS (readiness) layer ──────────────────────────────────────────────────
+function inspectHooks(home) {
+  const settings = readJson(path.join(home, '.claude', 'settings.json'), null);
+  const wiredFor = (evt) => {
+    const groups = settings?.hooks?.[evt];
+    return Array.isArray(groups) && groups.some(g => Array.isArray(g?.hooks)
+      && g.hooks.some(h => typeof h?.command === 'string' && h.command.includes(HOOK_MARK)));
+  };
+  const present = !!settings;
+  const wired = present ? HOOK_EVENTS.filter(wiredFor) : [];
+  const missing = present ? HOOK_EVENTS.filter(e => !wired.includes(e)) : HOOK_EVENTS.slice();
+  return { settingsPresent: present, wired, missing };
+}
+
+// ── TOOLS (discoverable manifest) layer ──────────────────────────────────────
+function inspectTools(brainDir, pkgRoot) {
+  // Prefer the DEPLOYED server (what this machine's brain actually exposes); fall back
+  // to the running package's server file. Regex the registration list — no import, no
+  // spawning the stdio server.
+  const candidates = [path.join(brainDir, 'klypix-mcp-server.mjs'), path.join(pkgRoot, 'bin', 'klypix-mcp.mjs')];
+  for (const f of candidates) {
+    const src = readText(f);
+    if (!src) continue;
+    const names = [];
+    const re = /server\.registerTool\(\s*['"]([^'"]+)['"]/g;
+    let mm; while ((mm = re.exec(src))) names.push(mm[1]);
+    if (names.length) return { names, count: names.length, source: f === candidates[0] ? 'deployed' : 'package', hash: sha(names.slice().sort().join(',')).slice(0, 8) };
+  }
+  return { names: [], count: 0, source: null, hash: null };
+}
+
+// ── PEERS (alignment) layer ──────────────────────────────────────────────────
+function inspectPeers(brainDir, brainPath, now) {
+  const file = path.join(brainDir, 'sessions', `${sha(normBrainPath(brainPath))}.json`);
+  const data = readJson(file, null);
+  const sessions = Array.isArray(data?.sessions) ? data.sessions : [];
+  const live = sessions.filter(s => s && now - (s.lastSeen || 0) < SESSION_FRESH_MS)
+    .map(s => ({ id: String(s.id || '').slice(0, 8), branch: s.branch || null, intent: s.intent || '', files: Array.isArray(s.files) ? s.files : [], lastSeenMin: Math.round((now - (s.lastSeen || 0)) / 60000) }));
+  return { file, live, count: live.length };
+}
+
+/**
+ * Inspect this machine's brain (+ a project's harness projection) as one report.
+ * @param {{ projectDir?: string, home?: string, now?: number, npmLatest?: string|null }} [opts]
+ */
+export function inspect(opts = {}) {
+  const home = opts.home || os.homedir();
+  const projectDir = opts.projectDir || process.cwd();
+  const now = opts.now || Date.now();
+  const brainDir = path.join(home, '.claude', 'project-brain');
+  const brainPath = path.join(projectDir, 'brain.klypix');
+  const hasBrain = fs.existsSync(brainPath) || fs.existsSync(path.join(projectDir, 'brain.any'));
+
+  const version = inspectVersion(brainDir);
+  const hooks = inspectHooks(home);
+  const tools = inspectTools(brainDir, PKG_ROOT);
+  const peers = inspectPeers(brainDir, brainPath, now);
+
+  // Harness drift only counts toward the verdict for a real brain project; auditProject
+  // against the BAKED brain version (the deployed truth) when available.
+  const harnessVer = version.baked || resolveVersion();
+  const harness = hasBrain ? auditProject(projectDir, { version: harnessVer }) : { files: [], drift: [], ok: true, version: harnessVer };
+
+  // npm currency (caller fetches it; we just compare to the baked truth).
+  const npm = (opts.npmLatest && !String(opts.npmLatest).startsWith('('))
+    ? { latest: opts.npmLatest, matches: version.baked ? cmpSemver(opts.npmLatest, version.baked) <= 0 : null }
+    : (opts.npmLatest ? { latest: opts.npmLatest, matches: null } : null);
+
+  // ── verdict ──────────────────────────────────────────────────────────────
+  const layers = {
+    version: version.installed ? ((version.dirty || (npm && npm.matches === false)) ? 'drift' : 'ok') : 'absent',
+    hooks: !hooks.settingsPresent ? 'absent' : (hooks.missing.length ? 'drift' : 'ok'),
+    harness: hasBrain ? (harness.ok ? 'ok' : 'drift') : 'n/a',
+  };
+  const drifted = Object.values(layers).filter(s => s === 'drift').length;
+  const verdict = !version.installed ? 'NOT-INSTALLED' : (drifted ? 'DRIFTED' : 'ALIGNED');
+
+  // ── one reconciliation block ──────────────────────────────────────────────
+  const actions = [];
+  if (!version.installed) actions.push('npx klypix-mcp install   # no brain installed on this machine');
+  else {
+    if (version.dirty) actions.push('node scripts/deploy-brain.mjs   # running uncommitted (dirty) hook code — commit + re-deploy');
+    if (npm && npm.matches === false) actions.push(`npx klypix-mcp install   # installed brain v${version.baked} < npm latest v${npm.latest}`);
+    if (hooks.missing.length) actions.push(`npx klypix-mcp install   # half-wired: hooks not active — ${hooks.missing.join(', ')}`);
+    if (hasBrain && !harness.ok) actions.push('npx klypix-mcp link      # harness configs drifted — re-project managed blocks');
+  }
+
+  return { verdict, layers, drifted, version, hooks, tools, peers, harness, npm, project: { dir: projectDir, brainPath, hasBrain }, brainDir, actions };
+}
+
+// One-line drift summary (empty when clean) — for a footer / status line.
+export function driftLine(r) {
+  if (r.verdict === 'ALIGNED') return '';
+  const bits = [];
+  if (!r.version.installed) return 'brain NOT installed — run `npx klypix-mcp install`';
+  if (r.version.dirty) bits.push('dirty deploy');
+  if (r.npm && r.npm.matches === false) bits.push(`v${r.version.baked}<${r.npm.latest}`);
+  if (r.hooks.missing.length) bits.push(`${r.hooks.missing.length} hook(s) unwired`);
+  if (r.project.hasBrain && !r.harness.ok) bits.push(`${r.harness.drift.length} harness file(s) drifted`);
+  return bits.length ? `⚠️ brain DRIFTED: ${bits.join(' · ')}` : '';
+}
+
+// ── human report ──────────────────────────────────────────────────────────────
+const C = { dim: '\x1b[2m', red: '\x1b[31m', grn: '\x1b[32m', yel: '\x1b[33m', rst: '\x1b[0m', bold: '\x1b[1m' };
+export function render(r, opts = {}) {
+  const color = opts.color !== false;
+  const c = color ? C : new Proxy({}, { get: () => '' });
+  const ok = color ? '✅' : '[ok]', warn = color ? '⚠️ ' : '[!]';
+  const L = [];
+  const head = r.verdict === 'ALIGNED' ? `${ok} ALIGNED` : r.verdict === 'NOT-INSTALLED' ? `${warn}NOT INSTALLED` : `${warn}DRIFTED (${r.drifted} layer${r.drifted === 1 ? '' : 's'})`;
+  L.push(`${c.bold}# brain_doctor${c.rst}  —  ${head}`);
+  L.push('');
+
+  // VERSION
+  const vmark = r.layers.version === 'ok' ? ok : r.layers.version === 'absent' ? warn : warn;
+  L.push(`${vmark} ${c.bold}VERSION${c.rst}  brain core ${c.bold}v${r.version.baked || '(not deployed)'}${c.rst}${r.version.channel ? ` ${c.dim}via ${r.version.channel}${c.rst}` : ''}${r.version.dev ? `  ${c.yel}dev${c.rst}` : ''}`);
+  if (r.version.dirty) L.push(`        ${c.red}DIRTY — running uncommitted hook code (source ${String(r.version.sourceSha || '?').slice(0, 12)})${c.rst}`);
+  if (r.npm) L.push(`        npm latest v${r.npm.latest}  ${r.npm.matches === false ? c.yel + '⚠ installed brain is behind' + c.rst : r.npm.matches === true ? c.grn + '✓ current' + c.rst : c.dim + '(no baked version to compare)' + c.rst}`);
+
+  // HOOKS
+  const hmark = r.layers.hooks === 'ok' ? ok : warn;
+  if (!r.hooks.settingsPresent) L.push(`${hmark} ${c.bold}HOOKS${c.rst}    no ~/.claude/settings.json found`);
+  else if (r.hooks.missing.length) L.push(`${hmark} ${c.bold}HOOKS${c.rst}    half-wired — missing: ${c.yel}${r.hooks.missing.join(', ')}${c.rst}  ${c.dim}(liveness up, readiness no)${c.rst}`);
+  else L.push(`${hmark} ${c.bold}HOOKS${c.rst}    all 4 wired: ${r.hooks.wired.join(', ')}`);
+
+  // TOOLS
+  L.push(`${ok} ${c.bold}TOOLS${c.rst}    ${r.tools.count} MCP verb(s)${r.tools.hash ? ` ${c.dim}[#${r.tools.hash}, ${r.tools.source}]${c.rst}` : ''}${r.tools.count ? `: ${c.dim}${r.tools.names.join(', ')}${c.rst}` : ''}`);
+
+  // PEERS
+  if (!r.peers.count) L.push(`${ok} ${c.bold}PEERS${c.rst}    solo — no other live session ${c.dim}(the brain is shared, NOT live-merged)${c.rst}`);
+  else {
+    L.push(`${warn}${c.bold}PEERS${c.rst}    ${r.peers.count} live ${c.dim}(shared, NOT live-merged — coordinate before committing)${c.rst}`);
+    for (const p of r.peers.live) L.push(`        · ${p.id}${p.branch ? ' @' + p.branch : ''}${p.intent ? ` “${p.intent.slice(0, 50)}”` : ''} ${c.dim}(${p.lastSeenMin}m ago)${c.rst}`);
+  }
+
+  // HARNESS
+  if (!r.project.hasBrain) L.push(`${c.dim}· HARNESS  no ./brain.klypix in ${r.project.dir} — projection n/a${c.rst}`);
+  else {
+    const cmark = r.layers.harness === 'ok' ? ok : warn;
+    if (r.harness.ok) L.push(`${cmark} ${c.bold}HARNESS${c.rst}  all ${r.harness.files.length} projected file(s) in sync`);
+    else {
+      L.push(`${cmark} ${c.bold}HARNESS${c.rst}  ${r.harness.drift.length} of ${r.harness.files.length} drifted:`);
+      for (const h of r.harness.drift) L.push(`        · ${h.file} — ${c.yel}${h.status.toUpperCase()}${c.rst}${h.stampedVersion ? ` (stamped v${h.stampedVersion})` : ''}`);
+    }
+  }
+
+  if (r.actions.length) {
+    L.push('');
+    L.push(`${c.bold}reconcile:${c.rst}`);
+    for (const a of r.actions) L.push('  ' + a);
+  }
+  return L.join('\n');
+}
+
+// ── cross-project / cross-channel audit (--all) ─────────────────────────────────
+// Superset of the legacy scripts/brain-doctor.mjs: every registered brain on this
+// machine + its .mcp.json vault wiring (the SS2-class trap: a foreign absolute vault).
+export function inspectAll(opts = {}) {
+  const home = opts.home || os.homedir();
+  const brainDir = path.join(home, '.claude', 'project-brain');
+  const reg = readJson(path.join(brainDir, 'registry.json'), null);
+  const brains = (Array.isArray(reg?.brains) ? reg.brains : []).filter(b => b && b.path);
+  let drift = 0;
+  const out = [];
+  for (const b of brains) {
+    const exists = fs.existsSync(b.path);
+    const dir = path.dirname(b.path);
+    const proj = b.project || path.basename(dir);
+    let vault = '(none → defaults)', vaultOk = true;
+    const cfg = readJson(path.join(dir, '.mcp.json'), null);
+    if (cfg) {
+      const args = cfg?.mcpServers?.['klypix-canvas']?.args || [];
+      const vi = args.indexOf('--vault');
+      vault = vi >= 0 ? args[vi + 1] : '(none → defaults)';
+      const norm = (p) => path.resolve(p).replace(/\\/g, '/').toLowerCase();
+      vaultOk = vault === '.' || (vi >= 0 && norm(path.resolve(dir, vault)) === norm(dir));
+      if (!vaultOk) drift++;
+    }
+    if (!exists) drift++;
+    out.push({ project: proj, path: b.path, exists, vault, vaultOk, hasMcp: !!cfg });
+  }
+  return { brains: out, drift };
+}

package/src/global-brain-hook.mjs

@@ -844,8 +844,16 @@ async function capture(lib) {
             // 🧠 MSG [to]: text — an async note to another session (not a brain card).
             const mg = MSG_RE.exec(trimmed);
             if (mg) {
+                const to = (mg[1] || '').trim();
                 const txt = (mg[2] || '').trim();
-                if (txt) messages.push({ id: sha(sid + '|' + txt + '|' + Date.now() + '|' + Math.random()), from: sid, to: (mg[1] || '').trim() || 'all', text: txt.slice(0, 400), ts: Date.now(), seen: [] });
+                // Skip the feature's OWN documentation/examples, not a real note: a
+                // placeholder target/text (<to>, <text>, <their-id…> — real targets are
+                // id-prefixes/branches and never contain <>) or a marker quoted inside an
+                // inline-code span (`…🧠 MSG…`, i.e. a backtick precedes the marker).
+                const isExample = /[<>\s]/.test(to)   // real targets are ONE token (id/branch/all/*) — <>, spaces ⇒ a doc example
+                    || /^\s*<[^>]+>/.test(txt)
+                    || /`/.test(trimmed.slice(0, trimmed.indexOf('🧠')));
+                if (txt && !isExample) messages.push({ id: sha(sid + '|' + txt + '|' + Date.now() + '|' + Math.random()), from: sid, to: to || 'all', text: txt.slice(0, 400), ts: Date.now(), seen: [] });
                 continue;
             }
             const m = MARKER.exec(trimmed); if (!m) continue;
@@ -1242,6 +1250,35 @@ function selfCheckFooter() {
     } catch { return ''; }
 }
 
+// ── Readiness footer — catch a HALF-WIRED install (liveness ≠ readiness) ─────
+// SessionStart firing proves the brain is ALIVE; but the OTHER three hooks are what
+// make it LEARN — UserPromptSubmit (recall), Stop (capture), PostToolUse (live sync).
+// A settings.json edit, a partial install, or a manual hook-prune can drop any of them,
+// leaving the brain reading-but-not-capturing — invisible until cards silently go
+// missing. This reads settings.json and says so in ONE line when drifted. Cheap +
+// namespace-safe (no version compare, no network); never throws. The full picture
+// (version currency, harness-projection drift, live peers) lives in `npx klypix-mcp
+// doctor` — the footer only carries the one signal worth interrupting every session for.
+function doctorFooter() {
+    try {
+        const SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+        if (!fs.existsSync(SETTINGS)) return '';
+        let settings; try { settings = JSON.parse(fs.readFileSync(SETTINGS, 'utf8')); } catch { return ''; }
+        const wiredFor = (evt) => {
+            const groups = settings?.hooks?.[evt];
+            return Array.isArray(groups) && groups.some(g => Array.isArray(g?.hooks)
+                && g.hooks.some(h => typeof h?.command === 'string' && h.command.includes('global-brain-hook')));
+        };
+        const missing = [['UserPromptSubmit', 'per-prompt recall'], ['Stop', 'decision capture'], ['PostToolUse', 'live sync']]
+            .filter(([evt]) => !wiredFor(evt));
+        if (!missing.length) return '';
+        return '\n\n---\n## ⚠️ Brain half-wired — readiness\n'
+            + `SessionStart fired (the brain is alive), but ${missing.length} hook(s) that make it LEARN are not wired: `
+            + missing.map(([evt, what]) => `**${evt}** (${what})`).join(', ') + '.\n'
+            + 'The brain will read but silently stop capturing/syncing decisions. Re-wire: `npx klypix-mcp install`, then restart this session.\n';
+    } catch { return ''; }
+}
+
 // ── Self-healing brain (decision lifecycle, part 5) ──────────────────────────
 // Open ❓/🎯 cards a later shipped 🏁 milestone appears to have fulfilled —
 // surfaced so the agent CLOSES them (✓ / closes:) instead of recall surfacing
@@ -1289,7 +1326,7 @@ async function read(lib) {
         : lib.structToMarkdown(struct);
     // ⚡ In-flight footer goes RIGHT AFTER the brief (highest signal: what a peer
     // shipped seconds ago, before it's in the brain) — closes the 1.3.17-blindness gap.
-    process.stdout.write(outStr + inflightFooter(input.session_id, struct) + selfHealFooter(drifted) + reconcileFooter(lib, struct) + staleOpenFooter(lib, struct) + selfCheckFooter() + messageFooter(input.session_id || '') + legendFooter() + memoryFooter());
+    process.stdout.write(outStr + inflightFooter(input.session_id, struct) + selfHealFooter(drifted) + reconcileFooter(lib, struct) + staleOpenFooter(lib, struct) + selfCheckFooter() + doctorFooter() + messageFooter(input.session_id || '') + legendFooter() + memoryFooter());
     // Heartbeat: prove the brief actually injected (and how big) so a dead or
     // stale live-copy of the hook stops being a silent no-op.
     appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'read', ok: true, briefBytes: Buffer.byteLength(outStr), cards: struct?.counts?.cards ?? null }, 500);