klypix-mcp 1.6.0 → 1.8.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

@@ -17,15 +17,20 @@
 
 import fs from 'fs';
 import path from 'path';
+import { createRequire } from 'module';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
   resolveVault, getEmbedder, buildKlypixMap, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opBrainReconcile, opCreateCanvas, opAddToCanvas, opBrainNote,
+  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote,
 } from '../src/klypix-core.mjs';
 
+// Real package version for the MCP handshake (was hardcoded '1.0.0', which
+// misled every client/version diagnosis — it could never reflect the true release).
+const PKG_VERSION = (() => { try { return createRequire(import.meta.url)('../package.json').version; } catch { return '0.0.0'; } })();
+
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
 const log = (...a) => console.error('[klypix-mcp]', ...a);
 
@@ -63,7 +68,7 @@ const toContent = (r) => {
   return r.isError ? { content, isError: true } : { content };
 };
 
-const server = new McpServer({ name: 'klypix-canvas', version: '1.0.0' });
+const server = new McpServer({ name: 'klypix-canvas', version: PKG_VERSION });
 
 server.registerTool('list_canvases', {
   title: 'List KLYPIX canvases',
@@ -121,6 +126,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.',

package/package.json

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

@@ -25,6 +25,7 @@ import {
   parseKlypix, buildKlypix, buildKlypixMap, appendToKlypix, structToMarkdown,
   brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite,
   findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
+  selectGardenCandidates, applyGarden,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -84,6 +85,52 @@ export function resolveCanvas(vault, ref) {
   return matches[0] || null;
 }
 
+// Resolve the DEFAULT project brain for the brain-* ops, INDEPENDENT of the
+// --vault library folder. The vault answers "where does my .klypix library live"
+// (list/read/search); the BRAIN is "THIS project's ./brain.klypix". Conflating
+// them is what made the brain ops read a stray canvas out of a global vault
+// (the "SS2" bug — a foreign brain.klypix picked by a fuzzy basename walk).
+// Precedence, project-first:
+//   1. KLYPIX_BRAIN env (explicit override)
+//   2. ./brain.klypix in the launch cwd — the project brain (coding agents launch
+//      this server with cwd = the project root)
+//   3. <vault>/brain.klypix (exact) — when the vault itself is the brain's home
+//   4. a SINGLE brain.klypix found by walking the vault; if MORE THAN ONE exists
+//      we REFUSE to guess (returns { ambiguous }) instead of silently taking one.
+export function resolveDefaultBrain(vault) {
+  const ex = (p) => { try { return p && fs.existsSync(p) ? path.resolve(p) : null; } catch { return null; } };
+  let f;
+  if ((f = ex(process.env.KLYPIX_BRAIN))) return { file: f, how: 'env (KLYPIX_BRAIN)' };
+  if ((f = ex(path.join(process.cwd(), 'brain.klypix')))) return { file: f, how: 'project cwd' };
+  if ((f = ex(path.join(vault, 'brain.klypix')))) return { file: f, how: 'vault root' };
+  const matches = walkVault(vault).filter(p => /^brain\.(klypix|any)$/i.test(path.basename(p)));
+  if (matches.length === 1) return { file: matches[0], how: 'vault search' };
+  if (matches.length > 1) return { ambiguous: matches };
+  return { file: null };
+}
+
+// Resolve the brain a brain-* op should act on. An explicit `canvas` arg → exact
+// resolve against the vault; otherwise the project-aware default above. Always
+// returns one of: { file, how } · { ambiguous: [paths] } · { file: null }.
+export function brainTarget(vault, canvas) {
+  if (canvas) { const file = resolveCanvas(vault, canvas); return file ? { file, how: `canvas:"${canvas}"` } : { file: null }; }
+  return resolveDefaultBrain(vault);
+}
+
+// One-line provenance shown atop every brain-op result so a wrong brain (the
+// "SS2" class) is OBVIOUS at a glance instead of silent. Counts non-container cards.
+export function brainStamp(file, struct, how) {
+  const title = (struct && struct.title) || path.basename(file);
+  const n = struct ? struct.cards.filter(c => c.type !== 'container').length : '?';
+  return `_brain: ${path.basename(file)} · “${title}” · ${n} cards${how ? ' · via ' + how : ''}_\n\n`;
+}
+
+// Shared error for the refuse-to-guess case — names the candidates so the caller
+// can pick one (canvas:"<path>") or fix the vault / run from the project root.
+function ambiguousBrainErr(matches) {
+  return err(`Found ${matches.length} brain.klypix files in the vault and no ./brain.klypix in the current project — refusing to guess which is "the brain". Pass canvas:"<path>", run from the project root, or set KLYPIX_BRAIN. Candidates:\n${matches.map(m => '  - ' + m).join('\n')}`);
+}
+
 function safeName(vault, title) {
   const base = String(title || 'untitled').replace(/[^\w\- ]+/g, '').trim() || 'untitled';
   let name = base, n = 1;
@@ -272,7 +319,7 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
   if (pipe) { try { [qv] = await embedTexts(pipe, [q]); } catch { /* lexical only */ } }
 
   let curKey = null;
-  try { const cb = resolveCanvas(vault, 'brain') || resolveCanvas(vault, 'brain.klypix'); if (cb) curKey = path.resolve(cb).replace(/\\/g, '/').toLowerCase(); } catch { /* no current brain */ }
+  try { const cb = resolveDefaultBrain(vault).file; if (cb) curKey = path.resolve(cb).replace(/\\/g, '/').toLowerCase(); } catch { /* no current brain */ }
   const fresh = Date.now() - 30 * 86_400_000;
   const scored = [];
   for (const b of brains) {
@@ -323,12 +370,13 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
 }
 
 export async function opBrainInsights({ vault, canvas, staleDays }) {
-  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
-  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>", or run \`npx klypix-mcp init\` to create one.`);
+  const t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>", or run \`npx klypix-mcp init\` to create one.`);
   try {
-    const { struct } = await parseKlypix(fs.readFileSync(file));
+    const { struct } = await parseKlypix(fs.readFileSync(t.file));
     const ins = brainInsights(struct, staleDays ? { staleDays } : {});
-    return { blocks: [text(insightsToMarkdown(ins, struct.title))] };
+    return { blocks: [text(brainStamp(t.file, struct, t.how) + insightsToMarkdown(ins, struct.title))] };
   } catch (e) {
     return err(`Insights failed: ${e.message}`);
   }
@@ -358,25 +406,67 @@ export function collectMigrationFiles(root) {
   return out;
 }
 export async function opBrainReconcile({ vault, canvas, root }) {
-  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
-  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  const t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
+  const file = t.file;
   let struct;
   try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
+  const stamp = brainStamp(file, struct, t.how);
   // Migrations live in the CODE repo (usually beside brain.klypix), not in a
   // separate canvas vault — so default the root to the brain file's folder.
   const repoRoot = root ? path.resolve(root) : path.dirname(file);
   const files = collectMigrationFiles(repoRoot);
-  if (!files.length) return { blocks: [text(`No migration files under ${repoRoot} (looked in: ${MIGRATION_DIRS.join(', ')}). Nothing to reconcile.`)] };
+  if (!files.length) return { blocks: [text(stamp + `No migration files under ${repoRoot} (looked in: ${MIGRATION_DIRS.join(', ')}). Nothing to reconcile.`)] };
   const { gaps, total } = findUnrecordedMigrations(struct, files, { max: 20 });
-  if (!gaps.length) return { blocks: [text(`✓ All ${files.length} migration(s) under ${path.basename(repoRoot)} are referenced by a brain card — no unrecorded rollouts.`)] };
+  if (!gaps.length) return { blocks: [text(stamp + `✓ All ${files.length} migration(s) under ${path.basename(repoRoot)} are referenced by a brain card — no unrecorded rollouts.`)] };
   const lines = gaps.map(g => `- \`${g.path}\` — committed, but no brain card mentions it. If applied to prod, record it:\n    \`🧠 BRAIN [DB] !: migration ${g.file.replace(/\.sql$/i, '')} applied to prod ev: ${g.path}\``);
   const more = total > gaps.length ? `\n\n…and ${total - gaps.length} more.` : '';
-  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}`)] };
+  return { blocks: [text(stamp + `# ⚠️ ${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 t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
+  const file = t.file;
+  let struct;
+  try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
+  const stamp = brainStamp(file, struct, t.how);
+  const areas = selectGardenCandidates(struct);
+  if (!areas.length) return { blocks: [text(stamp + '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(stamp + `# 🌿 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}.`);
+  const tgt = brainTarget(vault, canvas);
+  if (tgt.ambiguous) return ambiguousBrainErr(tgt.ambiguous);
+  if (!tgt.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}.`);
+  const file = tgt.file;
   let struct;
   try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
   const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, 70);
@@ -481,8 +571,10 @@ export async function opAddToCanvas({ vault, canvas, cards, connections, via })
 // 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>".`);
+  const t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
+  const file = t.file;
   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' });
@@ -493,7 +585,9 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
     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.`)] };
+    // Name the resolved brain explicitly (basename + how) so a write never lands
+    // in a surprise file silently — the write-side twin of the read-op stamp.
+    return { blocks: [text(`✓ brain_note → ${path.basename(file)} (via ${t.how}) · ${bits.join(' · ')}. Reopen the brain in KLYPIX to see it.`)] };
   } catch (e) {
     return err(`brain_note failed (brain unchanged): ${e.message}`);
   }

package/src/klypix-format.mjs

@@ -1200,6 +1200,175 @@ 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