klypix-mcp 1.5.0 → 1.7.0

package/README.md

@@ -52,9 +52,29 @@ notes into a board,"* or *"add a card with the decision we just made."*
 | `list_canvases` | List every `.klypix` in the vault |
 | `read_canvas` | Read a canvas as markdown (cards, the connection graph, `[[links]]`, `#tags`) |
 | `search_canvases` | Search across canvases by name + content |
+| `search_all_brains` | Cross-project memory search across every registered brain |
+| `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |
+| `brain_connect` | Find + draw related-but-unlinked cards (densify the graph) |
+| `brain_reconcile` | Flag committed-but-unrecorded DB migrations (the brain can't see prod) |
 | `create_canvas` | Create a new `.klypix` from cards + connections |
 | `add_to_canvas` | Append cards/connections to an existing canvas (positions preserved) |
 
+### Tools vs. the *automatic* brain
+
+This package is the **agent-neutral read/write surface** — any MCP client (Claude
+Code, Claude Desktop, Cursor, Cline, Windsurf…) gets the **tools** above and can
+read, search, and write canvases on demand (*pull*). That works in any agent, in
+any project.
+
+The **automatic** brain — auto-capturing decisions from your work, injecting the
+relevant cards into each prompt, and coordinating across concurrent sessions
+(*push*) — runs in a host **hook**, which is a Claude Code / KLYPIX-desktop
+feature, not part of this npm package. So `npx klypix-mcp` gives you the tools
+everywhere; the hands-free brain comes with the [KLYPIX desktop app](https://klypix.com)
+or the Claude Code project-brain hook. (`search_all_brains` is also hook-fed — it
+reads the cross-project registry the hook writes, so it stays empty until a hook
+has registered at least one brain.)
+
 ## Also speaks A2A (Agent-to-Agent)
 
 The same engine is exposed as an **A2A agent** so other agents and orchestrators

package/bin/klypix-mcp.mjs

@@ -23,7 +23,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   resolveVault, getEmbedder, buildKlypixMap, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opBrainReconcile, opCreateCanvas, opAddToCanvas,
+  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote,
 } from '../src/klypix-core.mjs';
 
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
@@ -121,6 +121,19 @@ server.registerTool('brain_reconcile', {
   },
 }, async ({ canvas, root }) => toContent(await opBrainReconcile({ vault: VAULT, canvas, root })));
 
+server.registerTool('brain_garden', {
+  title: 'Garden the brain — consolidate over-grown areas (sleep-time compute)',
+  description: 'Tidy an over-grown brain WITHOUT losing anything — SMART and non-invasive: it only consolidates DORMANT cards (old + peripheral), never load-bearing ones. Two phases: call it with no apply to get the areas that have accumulated forgotten cards (deterministic: >3 cards that are older than 14 days, beyond the area\'s newest 8, AND have ≤1 connection — so hubs and still-referenced decisions are left untouched; Focus/Instructions/Archive/Open-questions areas protected) plus their card text; YOU write one tight synthesis per area; then call again with apply:true and syntheses:[{title, synthesis}]. Each area gets a 🌿 synthesis card, the originals are stamped "⤵ consolidated", moved to Archive, and arrowed to the synthesis — nothing is deleted, and one undo un-gardens. Run it when brain_insights or the brief shows an area has grown noisy.',
+  inputSchema: {
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+    apply: z.boolean().optional().describe('false (default) = list over-grown areas + cards to synthesize; true = consolidate using the supplied syntheses.'),
+    syntheses: z.array(z.object({
+      title: z.string().describe('Area title EXACTLY as returned by the dry run.'),
+      synthesis: z.string().describe('3-6 sentence prose synthesis preserving every still-relevant fact/decision/number.'),
+    })).optional().describe('Required when apply:true — one entry per area you want consolidated.'),
+  },
+}, async ({ canvas, apply, syntheses }) => toContent(await opBrainGarden({ vault: VAULT, canvas, apply, syntheses })));
+
 server.registerTool('create_canvas', {
   title: 'Create a KLYPIX canvas',
   description: 'Create a new .klypix canvas from cards + connections and save it to the vault. The user opens it in KLYPIX (Canvas → Open). Prefer short, titled cards (one idea each) connected by meaningful arrows.',
@@ -147,6 +160,21 @@ server.registerTool('add_to_canvas', {
   return toContent(await opAddToCanvas({ vault: VAULT, canvas, cards, connections, via }));
 });
 
+server.registerTool('brain_note', {
+  title: 'Write a deliberate note to the project brain (decision / question / milestone / resolve / update)',
+  description: 'Record something in the project brain ON DEMAND — the agent-neutral twin of the Claude-Code capture hook, so any client (Cursor / Cline / Desktop) can write the brain, not just read it. Unlike add_to_canvas (a flat append), this routes through the brain\'s capture engine, so a new decision SUPERSEDES a heavily-overlapping older one, ✓ RESOLVES/archives a matching card, closes: resolves the strategy/question a milestone fulfils, and ~ UPDATES a card in place — the full decision lifecycle, with dedup. Use it to remember a decision, ask an open question, mark a milestone, resolve a finished item, or correct a card. Defaults to the project brain ("brain").',
+  inputSchema: {
+    text: z.string().describe('The note — one concise idea; the first line becomes the card title.'),
+    marker: z.enum(['', '?', '!', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · ✓=resolve+archive the best-matching card · ~=update the matching card in place. Default: decision.'),
+    area: z.string().optional().describe('Area/topic — routes the card into that titled container and becomes a #tag (e.g. "Auth", "Release").'),
+    closes: z.string().optional().describe('Title or [[wikilink]] of a strategy/question card this note fulfils — resolves+archives it and draws a "closed by" arrow.'),
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+  },
+}, async ({ text, marker, area, closes, canvas }) => {
+  let via; try { via = server.server.getClientVersion()?.name; } catch { /* optional */ }
+  return toContent(await opBrainNote({ vault: VAULT, canvas, text, area, marker: marker || '', closes, via }));
+});
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 log(`ready · vault=${VAULT}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.5.0",
+  "version": "1.7.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",

package/src/klypix-core.mjs

@@ -24,7 +24,8 @@ import { z } from 'zod';
 import {
   parseKlypix, buildKlypix, buildKlypixMap, appendToKlypix, structToMarkdown,
   brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite,
-  findUnrecordedMigrations,
+  findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
+  selectGardenCandidates, applyGarden,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -110,8 +111,16 @@ export function getEmbedder(log = () => {}) {
       let t;
       try { t = await import('@huggingface/transformers'); }
       catch {
-        const local = path.join(PB_DIR, 'semantic', 'node_modules', '@huggingface', 'transformers', 'dist', 'transformers.mjs');
-        t = await import(new URL('file:///' + local.replace(/\\/g, '/')).href);
+        // The optional dep ships dist/transformers.node.mjs on v4 (Node build) and
+        // dist/transformers.mjs on older lines — try both so a correct one-click
+        // install resolves regardless of version.
+        const base = path.join(PB_DIR, 'semantic', 'node_modules', '@huggingface', 'transformers', 'dist');
+        let lastErr;
+        for (const f of ['transformers.node.mjs', 'transformers.mjs']) {
+          try { t = await import(new URL('file:///' + path.join(base, f).replace(/\\/g, '/')).href); lastErr = null; break; }
+          catch (e) { lastErr = e; }
+        }
+        if (!t) throw lastErr;
       }
       t.env.cacheDir = path.join(PB_DIR, 'hf-cache');
       return await t.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { dtype: 'q8' });
@@ -366,6 +375,40 @@ export async function opBrainReconcile({ vault, canvas, root }) {
   return { blocks: [text(`# ⚠️ ${total} migration(s) committed but unrecorded in the brain\n_The brain can't see prod — it flags migrations that are in git but unmentioned, so you can confirm the rollout. It never asserts a migration was applied. To dismiss one without applying, record any card that names it (e.g. "committed, not applied")._\n\n${lines.join('\n')}${more}`)] };
 }
 
+// ── Brain gardener (two-phase: select → agent synthesizes → apply) ───────────
+// The portable /garden. Dry-run returns the over-grown areas + their old cards
+// for the CALLING agent to synthesize (the engine is pure — the model writes the
+// prose); apply consolidates each area into a 🌿 card and archives the originals
+// with audit arrows. Mirrors brain_connect's dry-run/apply discipline.
+export async function opBrainGarden({ vault, canvas, apply = false, syntheses }) {
+  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
+  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  let struct;
+  try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
+  const areas = selectGardenCandidates(struct);
+  if (!areas.length) return { blocks: [text('Nothing to garden — no area has 3+ DORMANT cards (old, beyond its newest 8, AND peripheral/≤1 link). Anything still woven into the graph is protected. The brain is tidy.')] };
+
+  if (!apply) {
+    const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    const body = areas.map(a => `## ${a.title}  (${a.candidates.length} dormant cards)\n` + a.candidates.map(c => `- ${flat(c.text).slice(0, 240)}`).join('\n')).join('\n\n');
+    return { blocks: [text(`# 🌿 Gardener — ${areas.length} area(s) with DORMANT cards to consolidate\nThese are old, peripheral (≤1 link) cards only — hubs and still-referenced decisions were left untouched. For EACH area below, write ONE tight synthesis (3-6 sentences, plain prose, no headers) that preserves every still-relevant fact / decision / number and drops only repetition + play-by-play. Then call \`brain_garden\` again with \`apply:true\` and \`syntheses: [{ "title": "<area title EXACTLY as shown>", "synthesis": "<text>" }, …]\`. Originals are archived with audit arrows — nothing is deleted; one undo un-gardens.\n\n${body}`)] };
+  }
+
+  if (!Array.isArray(syntheses) || !syntheses.length) return err('apply:true needs syntheses:[{title, synthesis}, …] — run the dry run first (apply omitted) to get the areas + their cards.');
+  try {
+    const { buffer, stats } = await applyGarden(fs.readFileSync(file), { syntheses });
+    const skippedNote = (stats.skipped && stats.skipped.length)
+      ? `\n\n⚠️ Left untouched (faithfulness guard): ${stats.skipped.map(s => `"${s.title}" — ${s.reason}`).join('; ')}.`
+      : '';
+    if (!stats.synthCards) return { blocks: [text(`No areas consolidated — each synthesis \`title\` must match a dry-run area title exactly.${skippedNote}`)] };
+    let out = buffer; try { out = (await tidyBrain(buffer)).buffer; } catch { /* keep apply result if tidy fails */ }
+    await atomicWrite(file, out);
+    return { blocks: [text(`🌿 Gardened ${stats.areas} area(s): ${stats.archived} old card(s) → ${stats.synthCards} synthesis card(s); originals archived with "consolidated into" arrows (any prose-dropped figures appended verbatim). Reopen the brain in KLYPIX to see it.${skippedNote}`)] };
+  } catch (e) {
+    return err(`Garden apply failed (brain unchanged): ${e.message}`);
+  }
+}
+
 export async function opBrainConnect({ vault, canvas, apply = false, max = 24, threshold = 0.45, log = () => {} }) {
   const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
   if (!file) return err(`No brain canvas found in ${vault}.`);
@@ -465,5 +508,31 @@ export async function opAddToCanvas({ vault, canvas, cards, connections, via })
   }
 }
 
+// brain_note — the DELIBERATE, marker-aware write every agent (not just the
+// Claude-Code Stop hook) can make on demand. Routes through the SAME captureInto-
+// Brain engine the hook uses, so supersede / resolve / close-link / dedup behave
+// identically to a harvested 🧠 marker. The agent-neutral half of "the brain is an
+// open file any agent reads AND writes": a hookless client (Cursor/Cline/Desktop)
+// can now record a decision, ask an open question, mark a milestone, resolve a card,
+// or correct one — with the full lifecycle, not just a flat append.
+export async function opBrainNote({ vault, canvas, text: noteText, area, marker = '', closes, via }) {
+  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
+  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  if (!noteText || !String(noteText).trim()) return err('brain_note needs a non-empty text.');
+  if (!['', '?', '!', '✓', '~'].includes(marker)) return err(`Invalid marker "${marker}" — use: (none)=decision · ?=open question · !=milestone · ✓=resolve a matching card · ~=update a matching card.`);
+  const input = noteToCaptureInput({ text: noteText, area, marker, closes: closes || '', createdVia: via || 'mcp' });
+  try {
+    const res = await captureIntoBrain(fs.readFileSync(file), input);
+    let out = res.buffer; try { out = (await tidyBrain(res.buffer)).buffer; } catch { /* keep append result if tidy fails */ }
+    await atomicWrite(file, out);
+    const s = res.stats || {};
+    const bits = [`${s.added || 0} added`];
+    for (const k of ['resolved', 'updated', 'closed', 'superseded', 'linked']) if (s[k]) bits.push(`${s[k]} ${k}`);
+    return { blocks: [text(`✓ brain_note → ${path.relative(vault, file)} (${bits.join(' · ')}). Reopen the brain in KLYPIX to see it.`)] };
+  } catch (e) {
+    return err(`brain_note failed (brain unchanged): ${e.message}`);
+  }
+}
+
 // Re-export the format helpers the bins need for non-op work (init onboarding).
 export { buildKlypixMap, parseKlypix };

package/src/klypix-format.mjs

@@ -573,8 +573,11 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     const live = texts.filter(c => !isArchived(c));
     const focus = live.filter(isFocus);
     const rest = live.filter(c => !isFocus(c));
-    const open = rest.filter(c => /❓/.test(c.text));
-    const miles = rest.filter(c => /🏁/.test(c.text) && !/❓/.test(c.text));
+    // 🎯 (goal/target) reads as an OPEN item alongside ❓ — a goal card is
+    // still-to-do until a ✓/closes: or a covering milestone closes it (so it
+    // must NOT masquerade as a plain decision that quietly ages out of view).
+    const open = rest.filter(c => /❓|🎯/.test(c.text));
+    const miles = rest.filter(c => /🏁/.test(c.text) && !/❓|🎯/.test(c.text));
     const plain = rest.filter(c => !open.includes(c) && !miles.includes(c));
     const recent = plain.filter(c => c.createdAt >= cutoff).sort((a, b) => b.createdAt - a.createdAt).slice(0, maxRecent);
     const archivedCount = texts.length - live.length;
@@ -607,7 +610,7 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
         push('', '## 📌 Human focus (cards the human placed here — act on these first)');
         for (const c of focus) push(`- ${fr(c)}${flat(c.text)}`);
     }
-    if (open.length) { push('', '## Open questions'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}`); }
+    if (open.length) { push('', '## Open questions & goals'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}`); }
     // ⚠️ Conflicts — pairs flagged conflicts_with (e.g. by parallel sessions);
     // surfaced HIGH so the next session reconciles them, not buries them.
     const conflicts = (struct.connections || []).filter(c => c.relationship === 'conflicts_with');
@@ -837,7 +840,7 @@ export function brainInsights(struct, { staleDays = 21, topHubs = 6 } = {}) {
         if (cn.toId) deg.set(cn.toId, (deg.get(cn.toId) || 0) + 1);
     }
     const headline = (c) => String(c.text || '').replace(/\s+/g, ' ').trim().replace(/^(.*?)([.!?](\s|$)|$)/, '$1').slice(0, 120);
-    const isQuestion = (c) => /❓/.test(c.text);
+    const isQuestion = (c) => /❓|🎯/.test(c.text); // ❓ open question + 🎯 goal both read as "open"
     const hubs = live
         .map(c => ({ id: c.id, area: c.area, degree: deg.get(c.id) || 0, headline: headline(c) }))
         .filter(x => x.degree > 0)
@@ -1042,7 +1045,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             let best = null, bestScore = 0;
             for (const c of liveTextCards()) {
                 if (r.area && (c.area || '').toLowerCase() !== r.area.toLowerCase()) continue;
-                const s = overlapScore(rTok, tokenSet(c.text)) + (/❓/.test(c.text) ? 0.15 : 0);
+                const s = overlapScore(rTok, tokenSet(c.text)) + (/❓|🎯/.test(c.text) ? 0.15 : 0);
                 if (s > bestScore) { bestScore = s; best = c; }
             }
             if (best && bestScore >= RESOLVE_AT) {
@@ -1092,7 +1095,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
         // to the new card is drawn in pass 2 (after the new ids exist), matched
         // back by remembering which old card each new card displaced.
         for (const card of cards) {
-            if (/❓|🏁/.test(card.text)) continue; // only plain decisions supersede
+            if (/❓|🎯|🏁/.test(card.text)) continue; // only plain decisions supersede (not questions/goals/milestones)
             const nTok = tokenSet(card.text);
             const area = (card.area || '').toLowerCase();
             let best = null, bestScore = 0;
@@ -1197,6 +1200,229 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
     return { buffer: work, stats };
 }
 
+// ── Brain gardener — sleep-time consolidation with a visible audit trail ─────
+// The portable engine twin of the in-app /garden (so ANY agent can run it over
+// MCP, not just the KLYPIX canvas). Two phases, like brain_connect: the engine
+// SELECTS deterministically (the model never decides WHAT merges, only writes the
+// prose), the agent writes one synthesis per area, then the engine APPLIES — each
+// area gets a 🌿 synthesis card; the originals are stamped "⤵ consolidated", moved
+// to Archive, and arrowed → the synthesis. Nothing is deleted (archived verbatim).
+const GARDEN_KEEP_NEWEST = 8;       // per area, never consolidate the newest N
+const GARDEN_MIN_AGE_DAYS = 14;     // only cards older than this are candidates
+const GARDEN_MIN_CANDIDATES = 3;    // don't bother merging fewer than this
+const GARDEN_MAX_DEGREE = 1;        // SMART guard: protect load-bearing cards —
+//   only consolidate cards with ≤ this many connections (orphans + leaves). A
+//   card the graph leans on (degree ≥ 2) is signal, not noise, and is left alone.
+// Areas the gardener must never touch: human steering + config + its own output.
+const GARDEN_PROTECTED = /^(archive|📌?\s*focus|(🤖\s*)?(agent\s+)?instructions|open questions|pending)/i;
+// Faithfulness guard: a synthesis shorter than this (after whitespace-collapse)
+// is treated as degenerate (model returned a stub) and its area is skipped.
+const MIN_SYNTHESIS_CHARS = 60;
+// Distinct "figures" worth never losing — tokens carrying ≥2 digits (versions
+// 1.3.7, dates 2026-06-24, sizes 50mb, counts 326, migration ids). Trivial single
+// digits (1, 3) are ignored. Used to append any prose-dropped figure verbatim.
+const figuresIn = (text) => {
+    const out = new Set();
+    for (const m of String(text || '').matchAll(/[0-9][0-9a-zA-Z._:-]*/g)) {
+        const tok = m[0].replace(/[._:-]+$/, '').toLowerCase();
+        if ((tok.match(/\d/g) || []).length >= 2) out.add(tok);
+    }
+    return out;
+};
+
+// Deterministic candidate selection — PURE, so the model never chooses WHAT to
+// merge. SMART + non-invasive: a card is a candidate only if it's DORMANT —
+// old (> minAgeDays), beyond the area's newest N, AND peripheral (connection
+// degree ≤ maxDegree). That protects hubs and still-referenced cards (the spine
+// of the brain), so consolidation hits forgotten noise — the same cards
+// brain_insights flags as orphaned — never load-bearing decisions. Returns each
+// over-grown area with its dormant cards (oldest first), each tagged with degree.
+export function selectGardenCandidates(struct, { keepNewest = GARDEN_KEEP_NEWEST, minAgeDays = GARDEN_MIN_AGE_DAYS, minCandidates = GARDEN_MIN_CANDIDATES, maxDegree = GARDEN_MAX_DEGREE, now = Date.now() } = {}) {
+    if (!struct || !Array.isArray(struct.cards)) return [];
+    const cutoff = now - minAgeDays * 86_400_000;
+    // Connection degree per card — both ends of every edge. A card that is linked
+    // to (or links out to) the rest of the graph is structurally load-bearing.
+    const degree = new Map();
+    for (const cn of (struct.connections || [])) {
+        if (cn.fromId) degree.set(cn.fromId, (degree.get(cn.fromId) || 0) + 1);
+        if (cn.toId) degree.set(cn.toId, (degree.get(cn.toId) || 0) + 1);
+    }
+    const out = [];
+    for (const ctn of struct.cards) {
+        if (ctn.type !== 'container') continue;
+        const title = (ctn.title || '').trim();
+        if (!title || GARDEN_PROTECTED.test(title)) continue;
+        const children = struct.cards
+            .filter(c => c.type === 'text' && c.parentId === ctn.id && (c.text || '').trim() && !/⤵|↩|✅/.test(c.text))
+            .sort((a, b) => (a.createdAt || 0) - (b.createdAt || 0));
+        const old = children
+            .slice(0, Math.max(0, children.length - keepNewest))
+            .filter(c => (c.createdAt || 0) < cutoff && (degree.get(c.id) || 0) <= maxDegree);  // dormant: old AND peripheral
+        if (old.length >= minCandidates) out.push({ containerId: ctn.id, title, candidates: old.map(c => ({ id: c.id, text: c.text, createdAt: c.createdAt || 0, degree: degree.get(c.id) || 0 })) });
+    }
+    return out;
+}
+
+// Apply: re-selects deterministically (robust to drift since the dry-run) and,
+// for each area the agent supplied a synthesis for, adds the 🌿 card + archives
+// the originals with audit arrows. `syntheses`: [{ title, synthesis }].
+export async function applyGarden(buffer, { syntheses = [] } = {}) {
+    const stats = { areas: 0, archived: 0, synthCards: 0, skipped: [] };
+    const { zip, canvas, manifest, isV4, struct } = await parseKlypix(buffer);
+    if (!isV4 || !canvas.positions) throw new Error('garden needs a v4 .klypix');
+    const areas = selectGardenCandidates(struct);
+    const synthByTitle = new Map();
+    for (const s of syntheses || []) { const t = String(s?.title || '').trim().toLowerCase(); const txt = String(s?.synthesis || '').trim(); if (t && txt) synthByTitle.set(t, txt); }
+    if (!areas.length || !synthByTitle.size) return { buffer, stats };
+
+    const now = Date.now();
+    const today = new Date(now).toISOString().slice(0, 10);
+    const rand = () => Math.random().toString(36).slice(2, 10);
+    const top = Object.values(canvas.positions).map(p => p && p.zKey).filter(k => k && isValidZKey(k)).sort().pop() || null;
+    const nextZKey = makeZKeyGen(top);
+    canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
+    const byTitle = new Map();
+    for (const c of struct.cards) if (c.type === 'container') { const t = (c.title || '').trim().toLowerCase(); if (t && !byTitle.has(t)) byTitle.set(t, c.id); }
+    // Archive primitives (mirror captureIntoBrain): find-or-create Archive, move a
+    // card into it un-baking any group-shrink, and rewrite a card's text in place.
+    const ensureArchive = () => {
+        let id = byTitle.get('archive');
+        if (id) return id;
+        id = `ctn_${rand()}`;
+        const G = BRAIN_GEOM;
+        zip.file(`items/${shard(id)}/${id}.json`, JSON.stringify({ type: 'container', locked: false, createdAt: now, createdBy: 'agent', title: 'Archive', collapsed: false, scopeLocked: false, borderColor: 'rgba(120,120,135,0.6)' }));
+        canvas.positions[id] = { x: nextContainerX(canvas), y: G.START, w: G.AREA_W, h: G.TITLE_BAR + G.PAD * 2, zKey: nextZKey(), zIndex: canvas.order.length, parentId: null };
+        canvas.order.push(id);
+        byTitle.set('archive', id);
+        return id;
+    };
+    const rewriteCard = async (id, mutate) => {
+        const ip = `items/${shard(id)}/${id}.json`;
+        const f = zip.file(ip); if (!f) return false;
+        const j = JSON.parse(await f.async('string'));
+        mutate(j);
+        j.content = wrapText(String(j.content || ''));
+        zip.file(ip, JSON.stringify(j));
+        const pos = canvas.positions[id];
+        if (pos) canvas.positions[id] = { ...pos, h: measureCardH(j.content) };
+        return true;
+    };
+    const archiveCard = async (id) => {
+        const arc = ensureArchive();
+        let authoredW = null;
+        const ip = `items/${shard(id)}/${id}.json`;
+        const f = zip.file(ip);
+        if (f) {
+            const j = JSON.parse(await f.async('string'));
+            const a = j.authoredInParent;
+            if (a) {
+                if (j.type === 'text' && a.fontSize) j.fontSize = a.fontSize;
+                if (a.authoredWidth != null) j.authoredWidth = a.authoredWidth;
+                authoredW = a.w || null;
+                delete j.authoredInParent;
+                zip.file(ip, JSON.stringify(j));
+            }
+        }
+        const pos = canvas.positions[id];
+        if (pos) canvas.positions[id] = { ...pos, parentId: arc, ...(authoredW ? { w: authoredW } : {}) };
+    };
+
+    for (const area of areas) {
+        const synthesis = synthByTitle.get(area.title.trim().toLowerCase());
+        if (!synthesis) continue;                          // model skipped this area — leave it untouched
+        const ctnPos = canvas.positions[area.containerId];
+        if (!ctnPos) continue;
+        // FAITHFULNESS GUARD (1) — degeneracy: a synthesis far too thin for the
+        // cards it replaces is rejected; that area is left untouched + reported,
+        // so a one-word "done" can't bury real history. (Originals stay put.)
+        const collapsed = synthesis.replace(/\s+/g, ' ').trim();
+        if (collapsed.length < MIN_SYNTHESIS_CHARS) {
+            stats.skipped.push({ title: area.title, reason: `synthesis too thin (${collapsed.length} chars, need ${MIN_SYNTHESIS_CHARS}) — revise and re-apply` });
+            continue;
+        }
+        // FAITHFULNESS GUARD (2) — figures net: any distinct number (version /
+        // size / date / count) in the originals that the prose dropped is appended
+        // verbatim, so the crispest facts survive on the visible card even if the
+        // synthesis missed them. The originals are archived verbatim regardless.
+        const origFigs = new Set();
+        for (const c of area.candidates) for (const f of figuresIn(c.text)) origFigs.add(f);
+        const synLower = synthesis.toLowerCase();
+        const missing = [...origFigs].filter(f => !synLower.includes(f));
+        const finalSynth = missing.length ? `${synthesis}\n↳ figures: ${missing.slice(0, 10).join(', ')}${missing.length > 10 ? ' …' : ''}` : synthesis;
+        const span = `${new Date(area.candidates[0].createdAt || now).toISOString().slice(0, 10)} → ${new Date(area.candidates[area.candidates.length - 1].createdAt || now).toISOString().slice(0, 10)}`;
+        const content = wrapText(`${area.title}: 🌿 Consolidated history (${span}, ${area.candidates.length} cards)\n${finalSynth}`);
+        const sid = `txt_${rand()}`;
+        zip.file(`items/${shard(sid)}/${sid}.json`, JSON.stringify({ type: 'text', locked: false, createdAt: now, createdBy: 'agent', createdVia: 'gardener', content, fontSize: 12, color: '#e8e8ed', border: true, borderColor: 'rgba(59,130,246,0.6)', heading: false }));
+        canvas.positions[sid] = { x: ctnPos.x + 20, y: ctnPos.y + (ctnPos.h || 0) + 10, w: 300, h: measureCardH(content), zKey: nextZKey(), zIndex: canvas.order.length, parentId: area.containerId };
+        canvas.order.push(sid);
+        stats.synthCards++;
+        for (const cand of area.candidates) {
+            await rewriteCard(cand.id, j => { j.content = `⤵ consolidated ${today}\n${j.content}`; j.borderColor = 'rgba(120,120,135,0.5)'; });
+            await archiveCard(cand.id);
+            canvas.connections.push({ id: `con_${rand()}`, fromId: cand.id, toId: sid, relationship: 'relates_to', label: 'consolidated into', arrowHead: true, width: 1.5, color: 'rgba(120,120,135,0.7)', style: 'solid' });
+            stats.archived++;
+        }
+        stats.areas++;
+    }
+    if (!stats.synthCards) return { buffer, stats };
+    const out = await finalizeBrainZip(zip, canvas, manifest, now);
+    return { buffer: out, stats };
+}
+
+// ── Stale-open reconcile ("marked open, but a milestone says it's done") ─────
+// The READ-side twin of the closes: write path. An open ❓/🎯 card lingers as
+// "still to do" forever unless someone emits a ✓/closes: for it — so a goal that
+// quietly SHIPPED keeps surfacing in recall as a "next move". This pure pass
+// finds open cards a LATER live 🏁 milestone appears to fulfil (its text COVERS
+// the open card's distinctive tokens) and returns them so the surface can PROMPT
+// the human to close them — never auto-archives (precision-first, suggestion-only,
+// like the migration tripwire). Requires the milestone to post-date the goal so a
+// pre-existing milestone can't "fulfil" a newer goal. No I/O, node-runnable.
+export function findStaleOpenCards(struct, { coverAt = 0.6, max = 5 } = {}) {
+    const empty = { gaps: [], total: 0 };
+    if (!struct || !Array.isArray(struct.cards)) return empty;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const isOpen = (c) => /❓|🎯/.test(c.text);
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !isArchived(c) && !/↩|✅/.test(c.text));
+    const opens = live.filter(isOpen);
+    const miles = live.filter(c => /🏁/.test(c.text) && !isOpen(c));
+    if (!opens.length || !miles.length) return empty;
+    const out = [];
+    for (const o of opens) {
+        const oTok = tokenSet(o.text);
+        if (oTok.size < 3) continue;                       // too vague to match safely → leave it
+        let best = null, bestCov = 0;
+        for (const m of miles) {
+            if ((m.createdAt || 0) <= (o.createdAt || 0)) continue; // only a milestone shipped AFTER the goal
+            const cov = coverageOf(oTok, tokenSet(m.text));          // how much of the goal the milestone covers
+            if (cov > bestCov) { bestCov = cov; best = m; }
+        }
+        if (best && bestCov >= coverAt) out.push({ open: o, by: best, cov: Math.round(bestCov * 100) / 100 });
+    }
+    out.sort((a, b) => b.cov - a.cov);
+    return { gaps: out.slice(0, max), total: out.length };
+}
+
+// ── Deliberate note → capture input ──────────────────────────────────────────
+// Turn ONE structured note into captureIntoBrain's input shape — the deliberate
+// twin of the Stop hook's transcript marker parser. This is what lets an ON-DEMAND
+// write (the brain_note MCP tool, the brain-note CLI — any agent, not just the
+// Claude-Code hook) get IDENTICAL supersede / resolve / close / dedup semantics as
+// a harvested 🧠 marker. marker ∈ '' (decision) | '?' (open question) | '!'
+// (milestone) | '✓' (resolve+archive a match) | '~' (update a match in place).
+export function noteToCaptureInput({ text = '', area = '', marker = '', closes = '', evidence = null, createdVia = 'mcp' } = {}) {
+    const body = String(text).trim();
+    if (!body) return { cards: [], resolutions: [], updates: [] };
+    const a = String(area || '').trim();
+    if (marker === '✓') return { cards: [], resolutions: [{ area: a, text: body }], updates: [] };
+    if (marker === '~') return { cards: [], resolutions: [], updates: [{ area: a, text: body, createdVia, ...(evidence ? { evidence } : {}) }] };
+    const prefix = marker === '?' ? '❓ ' : marker === '!' ? '🏁 ' : '';
+    const borderColor = marker === '?' ? 'rgba(245,166,35,0.8)' : marker === '!' ? 'rgba(59,130,246,0.8)' : 'rgba(16,185,129,0.6)';
+    const tag = a ? `\n#${a.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : '';
+    const cardText = (a ? `${a}: ${prefix}${body}` : `${prefix}${body}`) + tag;
+    return { cards: [{ text: cardText, area: a, color: '#e8e8ed', borderColor, createdVia, ...(closes ? { closes } : {}), ...(evidence ? { evidence } : {}) }], resolutions: [], updates: [] };
+}
+
 /**
  * Build a RICH "map" .klypix: areas become titled containers, their cards
  * stack inside, connections draw across. Produces a real spatial board (used by