klypix-mcp 1.0.0 → 1.1.0

package/bin/klypix-mcp.mjs

@@ -18,14 +18,39 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import crypto from 'crypto';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown, atomicWrite } from '../src/klypix-format.mjs';
+import { parseKlypix, buildKlypix, buildKlypixMap, appendToKlypix, structToMarkdown, atomicWrite } from '../src/klypix-format.mjs';
 
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
 const log = (...a) => console.error('[klypix-mcp]', ...a);
 
+// `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. (Dormant for
+// the in-app bundled server, which always launches with --vault.)
+if (process.argv[2] === 'init') {
+    const target = path.resolve(process.cwd(), 'brain.klypix');
+    if (fs.existsSync(target)) { console.error(`brain.klypix already exists in ${process.cwd()} — not overwriting.`); process.exit(0); }
+    const buf = await buildKlypixMap({
+        title: 'project brain',
+        areas: [
+            { title: 'Goal', cards: [{ text: '❓ What is this project for, and for whom?\nAgent: survey the repo on your first session and replace this with the real goal.' }] },
+            { title: 'Architecture', cards: [{ text: '❓ Key components and how they fit.\nAgent: record the actual shape from the repo — only what a new session must know.' }] },
+            { title: 'Decisions', cards: [{ text: 'Decisions land here automatically: agents emit `🧠 BRAIN [Area]: …` markers; a new decision that replaces an old one archives it (superseded). Resolve finished items with `✓`, correct in place with `~`. Drag any card into 📌 Focus to make it lead every session brief.' }] },
+            { title: 'Pending / next', cards: [{ text: 'What is in flight and what comes next. Close finished items with the ✓ marker.' }] },
+            { title: 'Open questions', cards: [{ text: 'Unresolved questions (the ❓ marker) live here — the session brief surfaces them first.' }] },
+            { title: '📌 Focus', cards: [{ text: 'Drag any card into this area to make it lead every session brief — steer your agent by moving cards.' }] },
+        ],
+    });
+    fs.writeFileSync(target, buf);
+    const cfg = JSON.stringify({ mcpServers: { 'klypix-canvas': { command: 'npx', args: ['-y', 'klypix-mcp', '--vault', process.cwd().replace(/\\/g, '/')] } } }, null, 2);
+    console.error(`✓ Created ${target}\n\nAdd this to your MCP client config (.mcp.json / claude_desktop_config.json):\n\n${cfg}\n\nThen ask your agent to read the canvas "brain" — it now has a project memory.`);
+    process.exit(0);
+}
+
 const vaultArgIdx = process.argv.indexOf('--vault');
 const VAULT = path.resolve(
     vaultArgIdx >= 0 ? process.argv[vaultArgIdx + 1]
@@ -110,16 +135,36 @@ server.registerTool('list_canvases', {
     return { content: [{ type: 'text', text: `# Canvases in ${VAULT}\n\n${rows.join('\n')}` }] };
 });
 
+const IMG_RE = /\.(png|jpe?g|gif|webp|bmp)$/i;
+const IMG_MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', bmp: 'image/bmp' };
+
 server.registerTool('read_canvas', {
     title: 'Read a KLYPIX canvas',
-    description: 'Read a canvas as structured markdown: every card, the connection graph, [[wikilinks]], #tags, and an asset list. Accepts a filename, vault-relative path, or absolute path.',
-    inputSchema: { canvas: z.string().describe('Canvas filename, vault-relative path, or absolute path.') },
+    description: 'Read a canvas as structured markdown (every card, the connection graph, [[wikilinks]], #tags) AND return its images so you can SEE them, not just their filenames. Pass the canvas TITLE directly (e.g. "SS2") — a filename, vault-relative path, or absolute path also work; you do NOT need to list or search first.',
+    inputSchema: { canvas: z.string().describe('Canvas title or filename (e.g. "SS2"), vault-relative path, or absolute path.') },
 }, async ({ canvas }) => {
     const file = resolveCanvas(canvas);
     if (!file) return { content: [{ type: 'text', text: `Canvas not found: ${canvas} (vault: ${VAULT})` }], isError: true };
     try {
-        const { struct } = await parseKlypix(fs.readFileSync(file));
-        return { content: [{ type: 'text', text: structToMarkdown(struct) }] };
+        const { struct, zip, assetPaths } = await parseKlypix(fs.readFileSync(file));
+        const content = [{ type: 'text', text: structToMarkdown(struct) }];
+        // Return image assets as actual image content so a vision-capable model
+        // SEES them — the whole point of a multimodal canvas. Capped (count +
+        // per-image size) so the response stays sane.
+        let included = 0;
+        for (const p of assetPaths) {
+            if (included >= 8) break;
+            if (!IMG_RE.test(p)) continue;
+            try {
+                const b64 = await zip.file(p).async('base64');
+                if (!b64 || b64.length > 7_000_000) continue; // skip > ~5MB
+                const ext = p.split('.').pop().toLowerCase();
+                content.push({ type: 'image', data: b64, mimeType: IMG_MIME[ext] || 'image/png' });
+                included++;
+            } catch { /* skip unreadable asset */ }
+        }
+        if (included > 0) content.push({ type: 'text', text: `\n(${included} image${included > 1 ? 's' : ''} from this canvas are attached above — read them directly.)` });
+        return { content };
     } catch (e) {
         return { content: [{ type: 'text', text: `Failed to read ${file}: ${e.message}` }], isError: true };
     }
@@ -136,18 +181,192 @@ server.registerTool('search_canvases', {
     for (const f of walkVault()) {
         let struct;
         try { ({ struct } = await parseKlypix(fs.readFileSync(f))); } catch { continue; }
+        const rel = path.relative(VAULT, f);
+        // Match the canvas TITLE + FILENAME too — not just card text — so
+        // searching a canvas by its name (e.g. "SS2") actually finds it.
+        const nameMatch = (struct.title || '').toLowerCase().includes(q) || rel.toLowerCase().includes(q);
         const matched = struct.cards.filter(c =>
             (c.title || '').toLowerCase().includes(q) ||
             String(c.text || '').toLowerCase().includes(q) ||
             (c.tags || []).some(t => ('#' + t).toLowerCase().includes(q)));
-        if (matched.length) {
-            hits.push(`## ${path.relative(VAULT, f)} — "${struct.title}"\n` +
-                matched.slice(0, 6).map(c => `- ${c.title || '(card)'}: ${String(c.text || '').replace(/\s+/g, ' ').slice(0, 120)}`).join('\n'));
+        if (nameMatch || matched.length) {
+            // Rich hits: type + id + position + tags + a longer snippet, so the
+            // agent can FIND a card (and tell duplicates apart) before it WRITES.
+            const head = `## ${rel} — "${struct.title}" · ${struct.counts.cards} cards, ${struct.counts.connections} connections${nameMatch && !matched.length ? '  (name/title match)' : ''}`;
+            const body = matched.slice(0, 8).map(c => {
+                const pos = (c.pos && c.pos.x != null) ? ` @(${Math.round(c.pos.x)},${Math.round(c.pos.y)})` : '';
+                const tags = (c.tags && c.tags.length) ? ' ' + c.tags.map(t => '#' + t).join(' ') : '';
+                return `- [${c.type}] "${c.title || '(card)'}" (${c.id})${pos}${tags}\n    ${String(c.text || '').replace(/\s+/g, ' ').slice(0, 240)}`;
+            }).join('\n');
+            hits.push(matched.length ? `${head}\n${body}` : head);
         }
     }
     return { content: [{ type: 'text', text: hits.length ? `# Matches for "${query}"\n\n${hits.join('\n\n')}` : `No matches for "${query}" in ${VAULT}.` }] };
 });
 
+// ── On-device semantic memory ────────────────────────────────────────────────
+// Embeddings run INSIDE this long-lived server (the hook stays instant), 100%
+// local: transformers.js (WASM) + a 23MB MiniLM model cached under
+// ~/.claude/project-brain/hf-cache on first use. Per-brain vectors are cached
+// incrementally (content-hashed per card) in ~/.claude/project-brain/embeddings/
+// — brains themselves are never mutated by search. Everything degrades to
+// lexical scoring gracefully: no lib, no model, no network → search still works.
+const PB_DIR = path.join(os.homedir(), '.claude', 'project-brain');
+const EMB_DIR = path.join(PB_DIR, 'embeddings');
+const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
+let embedderPromise = null;
+function getEmbedder() {
+    if (!embedderPromise) {
+        embedderPromise = (async () => {
+            // Dual-path: (1) bare specifier — npx/npm installs ship the lib;
+            // (2) ~/.claude/project-brain/semantic — where KLYPIX's one-click
+            // "semantic memory" install places it for the bundled server
+            // (the ONNX runtimes are ~350MB unpacked, far too heavy to bundle
+            // in the installer payload).
+            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);
+            }
+            t.env.cacheDir = path.join(PB_DIR, 'hf-cache');
+            return await t.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { dtype: 'q8' });
+        })().catch(e => { log('semantic unavailable (lexical fallback):', e?.message || e); return null; });
+    }
+    return embedderPromise;
+}
+async function embedTexts(pipe, texts) {
+    const out = await pipe(texts, { pooling: 'mean', normalize: true });
+    const [n, d] = out.dims;
+    const vecs = [];
+    for (let i = 0; i < n; i++) vecs.push(Array.from(out.data.slice(i * d, (i + 1) * d)));
+    return vecs;
+}
+const dot = (a, b) => { let s = 0; for (let i = 0; i < a.length; i++) s += a[i] * b[i]; return s; };
+// Incremental per-brain vector cache: only new/changed cards get embedded.
+async function vectorsForBrain(pipe, brainPath, cards) {
+    const file = path.join(EMB_DIR, sha1(brainPath.replace(/\\/g, '/')) + '.json');
+    let cache = { v: 1, cards: {} };
+    try { cache = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { /* fresh */ }
+    const want = cards.filter(c => c.type !== 'container' && (c.text || '').trim());
+    const missing = want.filter(c => cache.cards[c.id]?.h !== sha1(String(c.text)));
+    if (missing.length) {
+        const vecs = await embedTexts(pipe, missing.map(c => String(c.text).slice(0, 1500)));
+        missing.forEach((c, i) => { cache.cards[c.id] = { h: sha1(String(c.text)), v: vecs[i] }; });
+        const live = new Set(want.map(c => c.id));
+        for (const id of Object.keys(cache.cards)) if (!live.has(id)) delete cache.cards[id];
+        try { fs.mkdirSync(EMB_DIR, { recursive: true }); fs.writeFileSync(file, JSON.stringify(cache)); } catch { /* cache is best-effort */ }
+    }
+    const map = new Map();
+    for (const c of want) { const e = cache.cards[c.id]; if (e?.v) map.set(c.id, e.v); }
+    return map;
+}
+// Death date of an archived card (for as-of queries): the supersede/resolve stamp.
+const deathDateOf = (text) => { const m = /(?:↩︎ superseded|✅) (\d{4}-\d{2}-\d{2})/.exec(String(text)); return m ? Date.parse(m[1]) : null; };
+
+// Cross-project memory: search EVERY brain this machine has touched, not just
+// this vault. The SessionStart/Stop hook registers each ./brain.klypix it runs
+// against into ~/.claude/project-brain/registry.json — so simply having worked
+// in a project makes its decisions findable from any other project ("what did
+// I decide about auth — in ANY project?"). Hybrid ranking: on-device semantic
+// similarity (when the local model is ready) blended with lexical term hits;
+// as_of answers "what was true on <date>" via createdAt + supersession stamps.
+server.registerTool('search_all_brains', {
+    title: 'Search every project brain on this machine',
+    description: 'Cross-project memory search: looks through every brain.klypix this machine has worked with (auto-registered by the brain hook), not just the current vault. Semantic (on-device) + lexical hybrid ranking. Use when the answer may live in ANOTHER project\'s decisions. Optional as_of (YYYY-MM-DD) answers "what was true then" — superseded cards count as live if they were current at that date.',
+    inputSchema: {
+        query: z.string().describe('What to find across all project brains.'),
+        as_of: z.string().optional().describe('Optional YYYY-MM-DD: rank what was TRUE at that date (time-travel query).'),
+    },
+}, async ({ query, as_of }) => {
+    const q = String(query || '').trim().toLowerCase();
+    if (!q) return { content: [{ type: 'text', text: 'Provide a non-empty query.' }], isError: true };
+    const reg = path.join(PB_DIR, 'registry.json');
+    let brains = [];
+    try { brains = (JSON.parse(fs.readFileSync(reg, 'utf8')).brains || []).filter(b => b && b.path); } catch { /* no registry yet */ }
+    if (!brains.length) return { content: [{ type: 'text', text: 'No brains registered yet — the brain hook registers each project as you work in it.' }] };
+    const terms = q.split(/[^\p{L}\p{N}#]+/u).filter(t => t.length >= 3);
+    if (!terms.length) return { content: [{ type: 'text', text: 'Query too short — use words of 3+ characters.' }], isError: true };
+    const asOfTs = as_of ? Date.parse(as_of) : null;
+    if (as_of && Number.isNaN(asOfTs)) return { content: [{ type: 'text', text: `Bad as_of date: "${as_of}" — use YYYY-MM-DD.` }], isError: true };
+
+    // Semantic lane: wait briefly for the embedder; first-ever use downloads
+    // the model in the background — searches stay lexical until it's warm.
+    const pipe = await Promise.race([getEmbedder(), new Promise(r => setTimeout(() => r(null), 20_000))]);
+    let qv = null;
+    if (pipe) { try { [qv] = await embedTexts(pipe, [q]); } catch { /* lexical only */ } }
+
+    const fresh = Date.now() - 30 * 86_400_000;
+    const scored = [];
+    for (const b of brains) {
+        let struct;
+        try { ({ struct } = await parseKlypix(fs.readFileSync(b.path))); } catch { continue; }
+        let vecs = null;
+        if (qv) { try { vecs = await vectorsForBrain(pipe, b.path, struct.cards); } catch { /* lexical for this brain */ } }
+        for (const c of struct.cards) {
+            if (c.type === 'container') continue;
+            const text = String(c.text || '').toLowerCase();
+            const isArchived = /^archive$/i.test(c.area || '');
+            if (asOfTs != null) {
+                if ((c.createdAt || 0) > asOfTs) continue;                  // didn't exist yet
+                const died = isArchived ? deathDateOf(c.text) : null;
+                if (died != null && died <= asOfTs) continue;               // already superseded then
+            }
+            let lex = 0;
+            const title = String(c.title || '').toLowerCase();
+            const tags = (c.tags || []).map(t => ('#' + t).toLowerCase());
+            for (const t of terms) {
+                if (title.includes(t)) lex += 3;
+                if (tags.some(g => g.includes(t))) lex += 2;
+                if (text.includes(t)) lex += 1;
+            }
+            // Floor calibrated on real cards: related ≈ 0.25, unrelated ≈ 0.0
+            // (MiniLM, short decision texts) — 0.18 keeps recall with margin.
+            const sem = (qv && vecs?.get(c.id)) ? dot(qv, vecs.get(c.id)) : null;
+            if (!lex && (sem == null || sem < 0.18)) continue;
+            // Hybrid: semantic dominates when available; lexical is the tie-breaker
+            // and the only signal pre-warm-up. Recency/archive nudges skipped for
+            // time-travel queries (validity already handled above).
+            let score = sem != null ? sem * 10 + Math.min(lex, 6) * 0.5 : lex;
+            if (asOfTs == null) {
+                if ((c.createdAt || 0) >= fresh) score += 0.5;
+                if (isArchived) score -= 1;
+            }
+            scored.push({ score, sem, project: b.project || path.basename(path.dirname(b.path)), area: c.area, c });
+        }
+    }
+    if (!scored.length) return { content: [{ type: 'text', text: `No matches for "${query}" across ${brains.length} registered brain(s).` }] };
+    scored.sort((a, b2) => b2.score - a.score);
+    const top = scored.slice(0, 20);
+    const lines = top.map(h => {
+        const when = h.c.createdAt ? new Date(h.c.createdAt).toISOString().slice(0, 10) : '';
+        return `- [${h.project}${h.area ? ' › ' + h.area : ''}] ${when} ${String(h.c.text || '').replace(/\s+/g, ' ').slice(0, 240)}`;
+    });
+    const mode = qv ? 'semantic+lexical (on-device)' : 'lexical (semantic model warming — retry for semantic ranking)';
+    const asOfNote = asOfTs != null ? ` · as of ${as_of}` : '';
+    return { content: [{ type: 'text', text: `# Cross-project matches for "${query}" (${scored.length} hits in ${brains.length} brains, top ${top.length} · ${mode}${asOfNote})\n\n${lines.join('\n')}` }] };
+});
+
+// Format the cards (optionally only a set of new ids) + connection graph so an
+// agent that just wrote can chain follow-ups: reference card IDs, place near a
+// position, or draw an arrow to something it created. Additive — appended after
+// the human-readable line.
+function cardDetailBlock(struct, onlyIds) {
+    const cards = onlyIds ? struct.cards.filter(c => onlyIds.has(c.id)) : struct.cards;
+    if (!cards.length) return '';
+    const lines = cards.map(c => {
+        const pos = (c.pos && c.pos.x != null) ? `(${Math.round(c.pos.x)},${Math.round(c.pos.y)})` : '(?)';
+        const tags = (c.tags && c.tags.length) ? ' ' + c.tags.map(t => '#' + t).join(' ') : '';
+        const title = c.title || (c.text ? String(c.text).replace(/\s+/g, ' ').slice(0, 40) : '(untitled)');
+        return `- ${c.id} · ${c.type} · ${pos} · "${title}"${tags}`;
+    });
+    let out = `\n\nCards you can reference (id · type · pos · title):\n${lines.join('\n')}`;
+    if (struct.connections && struct.connections.length) {
+        out += `\nConnections: ` + struct.connections.map(cn => `${cn.from} ${cn.relationship ? '—' + cn.relationship + '→' : '→'} ${cn.to}`).join('; ');
+    }
+    return out;
+}
+
 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.',
@@ -164,7 +383,9 @@ server.registerTool('create_canvas', {
         const name = filename ? safeName(filename.replace(IS_CANVAS, '')) : safeName(title);
         const out = path.join(VAULT, name);
         await atomicWrite(out, buf);
-        return { content: [{ type: 'text', text: `Created ${out} — ${cards.length} cards, ${(connections || []).length} connections. Open it in KLYPIX (Canvas → Open).` }] };
+        let detail = '';
+        try { const { struct } = await parseKlypix(buf); detail = cardDetailBlock(struct); } catch { /* detail is optional */ }
+        return { content: [{ type: 'text', text: `Created ${out} — ${cards.length} cards, ${(connections || []).length} connections. Open it in KLYPIX (Canvas → Open).${detail}` }] };
     } catch (e) {
         return { content: [{ type: 'text', text: `Create failed: ${e.message}` }], isError: true };
     }
@@ -182,9 +403,22 @@ server.registerTool('add_to_canvas', {
     const file = resolveCanvas(canvas);
     if (!file) return { content: [{ type: 'text', text: `Canvas not found: ${canvas}` }], isError: true };
     try {
-        const buf = await appendToKlypix(fs.readFileSync(file), { cards, connections });
+        const original = fs.readFileSync(file);
+        // Snapshot existing ids so we can report ONLY the newly-added cards back.
+        let beforeIds = new Set();
+        try { const b = await parseKlypix(original); beforeIds = new Set(b.struct.cards.map(c => c.id)); } catch { /* new/legacy → treat all as new */ }
+        // Provenance: stamp WHICH agent wrote these cards (cursor / claude /
+        // cline — from the MCP client's initialize handshake).
+        let via; try { via = server.server.getClientVersion()?.name; } catch { /* optional */ }
+        const stamped = via ? cards.map(c => ({ ...c, createdVia: via })) : cards;
+        const buf = await appendToKlypix(original, { cards: stamped, connections });
         await atomicWrite(file, buf);
-        return { content: [{ type: 'text', text: `Added ${cards.length} card(s) to ${path.relative(VAULT, file)}. Reopen the canvas in KLYPIX to see them.` }] };
+        let detail = '';
+        try {
+            const { struct } = await parseKlypix(buf);
+            detail = cardDetailBlock(struct, new Set(struct.cards.map(c => c.id).filter(id => !beforeIds.has(id))));
+        } catch { /* detail is optional */ }
+        return { content: [{ type: 'text', text: `Added ${cards.length} card(s) to ${path.relative(VAULT, file)}. Reopen the canvas in KLYPIX to see them.${detail}` }] };
     } catch (e) {
         return { content: [{ type: 'text', text: `Add failed: ${e.message}` }], isError: true };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.0.0",
+  "version": "1.1.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",
@@ -46,6 +46,10 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "jszip": "^3.10.1",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "fractional-indexing": "^3.2.0"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^4.2.0"
   }
 }

package/src/klypix-format.mjs

@@ -9,6 +9,18 @@
 import JSZip from 'jszip';
 import path from 'path';
 import fs from 'fs';
+import { generateKeyBetween } from 'fractional-indexing';
+
+// Valid fractional-indexing z-keys. Hand-rolled keys (e.g. 'a0000' / 'z00013')
+// are REJECTED by the fractional-indexing lib the KLYPIX app uses and crash it
+// the moment you edit such a canvas — so the writer MUST emit lib-valid keys.
+// makeZKeyGen() returns an increasing-key generator starting just above `after`
+// (or from the bottom if `after` is null/invalid).
+const isValidZKey = (k) => { try { generateKeyBetween(k, null); return true; } catch { return false; } };
+function makeZKeyGen(after = null) {
+    let last = (after && isValidZKey(after)) ? after : null;
+    return () => (last = generateKeyBetween(last, null));
+}
 
 export const WIKILINK = /\[\[([^[\]]+)\]\]/g;
 export const TAG = /(^|\s)(#[a-zA-Z][\w-]*)/g;
@@ -97,6 +109,10 @@ export async function parseKlypix(buffer) {
             links: it.type === 'text' ? extractLinks(it.content) : [],
             tags: it.type === 'text' ? extractTags(it.content) : [],
             pos: { x: it.x, y: it.y },
+            createdAt: Number(it.createdAt) || 0,
+            parentId: it.parentId ?? null,
+            // Parent container's title — the card's "area" in brain terms.
+            area: it.parentId ? (cardTitle(items[it.parentId]) || null) : null,
         })),
         connections: connections.map(c => ({
             from: titleOf(c.fromId), to: titleOf(c.toId),
@@ -181,6 +197,7 @@ export async function buildKlypix(spec) {
     const COL_W = 380, GAP_Y = 70, START = 80;
     const positions = {};
     let zi = 0;
+    const nextZKey = makeZKeyGen();
     order.forEach((id, idx) => {
         const card = cards[idByIndex.indexOf(id)];
         const { w, h } = sizeFor(card);
@@ -188,7 +205,7 @@ export async function buildKlypix(spec) {
         positions[id] = {
             x: card.x ?? (START + col * COL_W),
             y: card.y ?? (START + row * (180 + GAP_Y) + (col % 2) * 12),
-            w, h, zKey: 'a' + String(idx).padStart(4, '0'), zIndex: zi++, parentId: null,
+            w, h, zKey: nextZKey(), zIndex: zi++, parentId: null,
         };
     });
 
@@ -278,17 +295,21 @@ export async function appendToKlypix(buffer, addition) {
     };
 
     canvas.order = Array.isArray(canvas.order) ? canvas.order : [];
+    // New cards go above the existing top — generate valid keys starting just
+    // above the highest existing VALID key (ignoring any legacy bad keys).
+    const existingTop = Object.values(canvas.positions || {}).map(p => p && p.zKey).filter(k => k && isValidZKey(k)).sort().pop() || null;
+    const nextZKey = makeZKeyGen(existingTop);
     for (const a of added) {
         zip.file(`items/${shard(a.id)}/${a.id}.json`, JSON.stringify({
             type: 'text', locked: false, createdAt: now, createdBy: 'agent',
+            ...(a.card.createdVia ? { createdVia: String(a.card.createdVia) } : {}),
             content: String(a.card.text), fontSize: FONT,
             color: a.card.color || '#1a1a1f', border: !!a.card.border, borderColor: '#1e1e2e',
             heading: !!a.card.heading, fontFamily: 'Thmanyah Sans',
             fontWeight: a.card.heading ? 'bold' : 'normal', fontStyle: 'normal',
             textDecoration: 'none', textAlign: 'left', verticalAlign: 'top',
         }));
-        // 'z' prefix sorts new cards above existing ones (which use 'a…').
-        canvas.positions[a.id] = { x: a.x, y: a.y, w: a.w, h: a.h, zKey: 'z' + String(a.z).padStart(5, '0'), zIndex: a.z, parentId: null };
+        canvas.positions[a.id] = { x: a.x, y: a.y, w: a.w, h: a.h, zKey: nextZKey(), zIndex: a.z, parentId: null };
         canvas.order.push(a.id);
     }
 
@@ -319,6 +340,490 @@ export async function appendToKlypix(buffer, addition) {
     return out;
 }
 
+// ── Area-grouped layout (project brain) ──────────────────────────────────────
+// Captured decisions carry an [Area]; these route cards INTO titled area
+// containers (find-or-create) so the brain stays a clean areas-as-containers map
+// instead of a rightward strip. Non-destructive, valid z-keys, atomic round-trip.
+const BRAIN_GEOM = { TITLE_BAR: 40, PAD: 14, CARD_GAP: 10, CARD_W: 300, FONT: 12, LINE_H: 17, START: 80, COL_GAP: 44 };
+BRAIN_GEOM.AREA_W = BRAIN_GEOM.CARD_W + BRAIN_GEOM.PAD * 2;
+
+// Chars that fit on one rendered line. The bordered card has 10px L/R padding,
+// so the text area is CARD_W-20; use a conservative char width (font*0.62) so a
+// wrapped line never RE-wraps in-app (which would double a card's height).
+function brainCPL() { return Math.max(8, Math.floor((BRAIN_GEOM.CARD_W - 24) / (BRAIN_GEOM.FONT * 0.62))); }
+
+// Hard-wrap text to ~CARD_W by inserting newlines at word boundaries. KLYPIX text
+// cards show a long SINGLE line as-typed (no auto-wrap until you resize), so a
+// captured decision with no newlines runs off the box. Baking in line breaks
+// makes brain cards render as tidy multi-line blocks regardless of that.
+function wrapText(text, cpl = brainCPL()) {
+    const out = [];
+    for (const para of String(text ?? '').split('\n')) {
+        if (para.length <= cpl) { out.push(para); continue; }
+        let line = '';
+        for (const tok of para.split(/(\s+)/)) {
+            if (line && (line + tok).trimEnd().length > cpl) { out.push(line.trimEnd()); line = tok.replace(/^\s+/, ''); }
+            else line += tok;
+            while (line.length > cpl) { out.push(line.slice(0, cpl)); line = line.slice(cpl); } // break an over-long word
+        }
+        if (line.trim()) out.push(line.trimEnd());
+    }
+    return out.join('\n');
+}
+
+function measureCardH(text) {
+    // text is hard-wrapped to ≤CPL, so the \n-line count is the rendered line
+    // count. Match the bordered card (lineHeight 1.35*font + 8/8 vertical padding
+    // + border) and over-estimate slightly → small gaps, never overlap.
+    const lines = Math.max(1, String(text ?? '').split('\n').length);
+    return Math.max(40, Math.ceil(lines * BRAIN_GEOM.FONT * 1.45) + 26);
+}
+// Container the next NEW area goes to the right of the rightmost item.
+function nextContainerX(canvas) {
+    const all = Object.values(canvas.positions);
+    return all.length ? Math.max(...all.map(p => (p.x || 0) + (p.w || BRAIN_GEOM.AREA_W))) + BRAIN_GEOM.COL_GAP : BRAIN_GEOM.START;
+}
+// Bottom y of a container's current children (where the next card stacks).
+function containerChildBottom(canvas, ctnId) {
+    const ctn = canvas.positions[ctnId];
+    let cy = ctn.y + BRAIN_GEOM.TITLE_BAR + BRAIN_GEOM.PAD;
+    for (const id of canvas.order) {
+        const p = canvas.positions[id];
+        if (p && p.parentId === ctnId) cy = Math.max(cy, p.y + (p.h || 40) + BRAIN_GEOM.CARD_GAP);
+    }
+    return cy;
+}
+// Best-effort area name for a card: "Area: …" first-line prefix → first #tag → 'Notes'.
+function areaOfCard(card) {
+    const line1 = String(card.text || '').split('\n')[0].trim();
+    const m = line1.match(/^([^:\n]{1,40}):\s+\S/);
+    if (m) return m[1].trim();
+    if (Array.isArray(card.tags) && card.tags[0]) return String(card.tags[0]);
+    return 'Notes';
+}
+async function finalizeBrainZip(zip, canvas, manifest, now) {
+    if (manifest) {
+        manifest.updatedAt = new Date(now).toISOString();
+        manifest.stats = manifest.stats || {};
+        manifest.stats.itemCount = canvas.order.length;
+        zip.file('manifest.json', JSON.stringify(manifest));
+    }
+    zip.file('canvas.json', JSON.stringify(canvas));
+    const out = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+    try { await parseKlypix(out); }
+    catch (e) { throw new Error('brain write produced an unparseable .klypix — aborting to protect the brain: ' + (e?.message || e)); }
+    return out;
+}
+
+// Append cards routed INTO their [Area] container (find-or-create), so captures
+// self-organize. addition.cards = [{ text, color?, area? }]. Non-destructive to
+// existing items. Falls back to the flat appender for legacy/no-positions files.
+export async function appendIntoContainers(buffer, addition) {
+    const { zip, canvas, manifest, isV4, struct } = await parseKlypix(buffer);
+    if (!isV4 || !canvas.positions) return appendToKlypix(buffer, addition);
+    const newCards = (addition?.cards || []).filter(c => c && typeof c.text === 'string' && c.text.trim());
+    if (newCards.length === 0) throw new Error('nothing to add — provide cards[] with text');
+
+    const now = Date.now();
+    const rand = () => Math.random().toString(36).slice(2, 10);
+    const G = BRAIN_GEOM;
+    canvas.order = Array.isArray(canvas.order) ? canvas.order : [];
+    const existingTop = Object.values(canvas.positions).map(p => p && p.zKey).filter(k => k && isValidZKey(k)).sort().pop() || null;
+    const nextZKey = makeZKeyGen(existingTop);
+
+    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); }
+    let ctnX = nextContainerX(canvas);
+    const ensureContainer = (area) => {
+        const key = area.toLowerCase();
+        let id = byTitle.get(key);
+        if (id) return id;
+        id = `ctn_${rand()}`;
+        zip.file(`items/${shard(id)}/${id}.json`, JSON.stringify({
+            type: 'container', locked: false, createdAt: now, createdBy: 'agent',
+            title: area, collapsed: false, scopeLocked: false, borderColor: '#10b981',
+        }));
+        canvas.positions[id] = { x: ctnX, 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(key, id);
+        ctnX += G.AREA_W + G.COL_GAP;
+        return id;
+    };
+
+    for (const card of newCards) {
+        const area = (card.area || areaOfCard(card)).toString().trim() || 'Notes';
+        const ctnId = ensureContainer(area);
+        const ctn = canvas.positions[ctnId];
+        const wrapped = wrapText(String(card.text));
+        const h = measureCardH(wrapped);
+        const cy = containerChildBottom(canvas, ctnId);
+        const id = `txt_${rand()}`;
+        zip.file(`items/${shard(id)}/${id}.json`, JSON.stringify({
+            type: 'text', locked: false, createdAt: now, createdBy: 'agent',
+            // Provenance: WHICH agent remembered this (claude-code / cursor /
+            // cline / …) — additive field, ignored by older readers.
+            ...(card.createdVia ? { createdVia: String(card.createdVia) } : {}),
+            content: wrapped, fontSize: G.FONT,
+            color: card.color || '#e8e8ed', border: true, borderColor: card.borderColor || card.color || 'rgba(16,185,129,0.45)',
+            fillColor: 'rgba(18,18,26,0.85)', heading: !!card.heading, fontFamily: 'Thmanyah Sans',
+            fontWeight: card.heading ? 'bold' : 'normal', fontStyle: 'normal',
+            textDecoration: 'none', textAlign: 'left', verticalAlign: 'top',
+        }));
+        canvas.positions[id] = { x: ctn.x + G.PAD, y: cy, w: G.CARD_W, h, zKey: nextZKey(), zIndex: canvas.order.length, parentId: ctnId };
+        canvas.order.push(id);
+        ctn.h = (cy + h + G.PAD) - ctn.y;
+    }
+    return finalizeBrainZip(zip, canvas, manifest, now);
+}
+
+// Tidy an EXISTING brain: re-parent every root-level text card into its [Area]
+// container (find-or-create), grouping the messy strip into clean areas. Moves
+// cards (keeps their ids → connections preserved); never drops a card. Caller
+// should back up first; this round-trip-verifies before returning.
+export async function tidyBrain(buffer) {
+    const { zip, canvas, manifest, isV4, struct } = await parseKlypix(buffer);
+    if (!isV4 || !canvas.positions) throw new Error('tidy supports v4 .klypix only');
+    const now = Date.now();
+    const rand = () => Math.random().toString(36).slice(2, 10);
+    const G = BRAIN_GEOM;
+    canvas.order = Array.isArray(canvas.order) ? canvas.order : [];
+    const top = Object.values(canvas.positions).map(p => p && p.zKey).filter(k => k && isValidZKey(k)).sort().pop() || null;
+    const nextZKey = makeZKeyGen(top);
+
+    // Normalize every text card to the compact brain font (so the render matches
+    // our height measure → no overlap) + cache each card's measured height.
+    const meta = new Map(); // id -> { h }
+    for (const c of struct.cards) {
+        if (c.type === 'container') continue;
+        const wrapped = wrapText(String(c.text ?? ''));
+        let createdAt = 0;
+        const ip = `items/${shard(c.id)}/${c.id}.json`;
+        try { const f = zip.file(ip); if (f) { const j = JSON.parse(await f.async('string')); createdAt = Number(j.createdAt) || 0; j.fontSize = G.FONT; j.content = wrapped; zip.file(ip, JSON.stringify(j)); } } catch { /* leave as-is */ }
+        meta.set(c.id, { h: measureCardH(wrapped), createdAt });
+    }
+
+    const containerIds = new Set(struct.cards.filter(c => c.type === 'container').map(c => c.id));
+    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); }
+
+    // Group ROOT text cards by [Area].
+    const rootText = struct.cards.filter(c => c.type !== 'container' && canvas.positions[c.id] && canvas.positions[c.id].parentId == null);
+    const groups = new Map(); // key -> { title, ids: [] }
+    for (const c of rootText) { const a = areaOfCard(c); const k = a.toLowerCase(); if (!groups.has(k)) groups.set(k, { title: a, ids: [] }); groups.get(k).ids.push(c.id); }
+
+    let moved = 0;
+    const assignTo = (ctnId, ids) => { for (const id of ids) { const p = canvas.positions[id]; canvas.positions[id] = { ...p, parentId: ctnId, zKey: (p && p.zKey && isValidZKey(p.zKey)) ? p.zKey : nextZKey() }; moved++; } };
+    // Ensure a container exists for each area (create if missing); route root cards in.
+    for (const grp of groups.values()) {
+        const key = grp.title.toLowerCase();
+        let ctnId = byTitle.get(key);
+        if (!ctnId) {
+            ctnId = `ctn_${rand()}`;
+            zip.file(`items/${shard(ctnId)}/${ctnId}.json`, JSON.stringify({ type: 'container', locked: false, createdAt: now, createdBy: 'agent', title: grp.title, collapsed: false, scopeLocked: false, borderColor: '#10b981' }));
+            canvas.order.push(ctnId);
+            canvas.positions[ctnId] = { x: G.START, y: G.START, w: G.AREA_W, h: G.TITLE_BAR + G.PAD * 2, zKey: nextZKey(), zIndex: canvas.order.length, parentId: null };
+            byTitle.set(key, ctnId); containerIds.add(ctnId);
+        }
+        assignTo(ctnId, grp.ids);
+    }
+
+    // UNIFIED LAYOUT — re-flow each container's children (chronological, compact
+    // heights) AND shelf-pack ALL containers into one grid by their TRUE height, so
+    // a container that grew (new captures) never overlaps its neighbor below.
+    const childrenOf = (cid) => canvas.order
+        .filter(id => canvas.positions[id] && canvas.positions[id].parentId === cid)
+        .sort((a, b) => (meta.get(a)?.createdAt || 0) - (meta.get(b)?.createdAt || 0));
+    const heightOf = (cid) => { const inner = childrenOf(cid).reduce((s, id) => s + (meta.get(id)?.h || 40) + G.CARD_GAP, 0); return Math.max(G.TITLE_BAR + G.PAD * 2, G.TITLE_BAR + G.PAD + inner + G.PAD); };
+    const orderedCtns = canvas.order.filter(id => containerIds.has(id) && canvas.positions[id]);
+    const cols = Math.max(1, Math.min(4, Math.ceil(Math.sqrt(Math.max(1, orderedCtns.length)))));
+    let colIdx = 0, rowTopY = G.START, rowMaxH = 0, colX = G.START;
+    for (const cid of orderedCtns) {
+        const h = heightOf(cid);
+        if (colIdx >= cols) { rowTopY += rowMaxH + G.COL_GAP; rowMaxH = 0; colIdx = 0; colX = G.START; }
+        canvas.positions[cid] = { ...canvas.positions[cid], x: colX, y: rowTopY, w: G.AREA_W, h };
+        let cy = rowTopY + G.TITLE_BAR + G.PAD;
+        for (const kid of childrenOf(cid)) { const kh = meta.get(kid)?.h || 40; canvas.positions[kid] = { ...canvas.positions[kid], x: colX + G.PAD, y: cy, w: G.CARD_W, h: kh }; cy += kh + G.CARD_GAP; }
+        colX += G.AREA_W + G.COL_GAP; colIdx++; rowMaxH = Math.max(rowMaxH, h);
+    }
+
+    const out = await finalizeBrainZip(zip, canvas, manifest, now);
+    return { buffer: out, moved, containers: byTitle.size };
+}
+
+// ── Tiered brain brief ───────────────────────────────────────────────────────
+// A compact, token-bounded session brief: area map + open questions + recent
+// decisions + milestones. Everything older stays in the file, reachable via the
+// klypix-canvas MCP search or `--full`. Keeps the session-start cost flat as
+// the brain grows (the full markdown scales with history; this doesn't).
+export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMilestones = 8, maxConnections = 30 } = {}) {
+    const cutoff = Date.now() - recentDays * 86_400_000;
+    const texts = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim());
+    const containers = struct.cards.filter(c => c.type === 'container');
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    // 📌 FOCUS — the human steers agent attention SPATIALLY: any card dragged
+    // into a container titled "Focus" (any decoration: "📌 Focus", "Focus
+    // (drag cards here)") leads every brief, full text, regardless of age.
+    const isFocus = (c) => /(^|\s)focus\b/i.test(c.area || '');
+    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));
+    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;
+
+    const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    // HEADLINE = first sentence-ish, hard-capped — the brief is a scannable
+    // changelog; the agent pulls any card's full text via the MCP when needed.
+    const headline = (c, max = 160) => {
+        const t = flat(c.text);
+        const stop = t.search(/(?<=[.!?])\s/);
+        const h = stop > 40 && stop < max ? t.slice(0, stop) : t;
+        return h.length > max ? h.slice(0, max - 1).trimEnd() + '…' : h;
+    };
+    const day = (ts) => ts ? new Date(ts).toISOString().slice(0, 10) : '';
+
+    // TOKEN BUDGET (≈ chars/4): sections are added in priority order — Focus,
+    // Open, Areas, Milestones, Recent, Connections — and Recent stops when the
+    // budget is hit. The brief stays ~flat forever no matter how active a week.
+    const BUDGET_CHARS = 11_000; // ≈ 2.7k tokens
+    let used = 0;
+    const out = [];
+    const push = (...lines) => { for (const l of lines) { out.push(l); used += l.length + 1; } };
+
+    push(`# ${struct.title} — brain brief`);
+    push(`*${struct.format} · ${struct.counts.cards} cards · ${struct.counts.connections} connections · tiered brief (focus + open + last ${recentDays}d headlines); full cards via klypix-canvas MCP search*`);
+    if (focus.length) {
+        push('', '## 📌 Human focus (cards the human placed here — act on these first)');
+        for (const c of focus) push(`- ${flat(c.text)}`);
+    }
+    if (open.length) { push('', '## Open questions'); for (const c of open) push(`- ${flat(c.text)}`); }
+    const areaCounts = containers
+        .filter(c => !/^archive$/i.test(c.title || ''))
+        .map(c => `${flat(c.title)} (${texts.filter(t => t.parentId === c.id).length})`);
+    if (areaCounts.length) { push('', '## Areas', areaCounts.join(' · ')); }
+    if (miles.length) {
+        push('', '## Milestones');
+        for (const c of miles.sort((a, b) => b.createdAt - a.createdAt).slice(0, maxMilestones)) push(`- ${headline(c)}`);
+    }
+    let shownRecent = 0;
+    if (recent.length) {
+        push('', `## Recent decisions (last ${recentDays}d — headlines)`);
+        const byArea = new Map();
+        for (const c of recent) { const a = flat(c.area) || 'Notes'; if (!byArea.has(a)) byArea.set(a, []); byArea.get(a).push(c); }
+        outer: for (const [a, cs] of byArea) {
+            push(`### ${a}`);
+            for (const c of cs) {
+                if (used > BUDGET_CHARS) break outer;
+                push(`- ${day(c.createdAt)} ${headline(c)}`);
+                shownRecent++;
+            }
+        }
+    }
+    if (struct.connections.length && used <= BUDGET_CHARS) {
+        push('', '## Connections');
+        for (const cn of struct.connections.slice(0, maxConnections)) push(`- ${cn.from} → ${cn.to}${cn.label || cn.relationship ? ` (${cn.label || cn.relationship})` : ''}`);
+    }
+    const hidden = [];
+    const unshown = plain.length - shownRecent;
+    if (unshown > 0) hidden.push(`${unshown} older/over-budget decision${unshown === 1 ? '' : 's'}`);
+    if (archivedCount > 0) hidden.push(`${archivedCount} archived/superseded`);
+    if (hidden.length) push('', `*${hidden.join(' + ')} not shown — search the full brain via the klypix-canvas MCP (search/read tools) or \`node ~/.claude/project-brain/global-brain-hook.mjs --full\`.*`);
+    return out.join('\n') + '\n';
+}
+
+// ── Atomic brain capture: supersede + append + resolve + auto-link ──────────
+// One verified write per capture batch. Beyond appendIntoContainers it adds:
+//   • SUPERSEDE — a new decision that heavily overlaps an existing live card in
+//     the same area archives the old one (↩︎ prefix, gray, → Archive) and draws
+//     an old→new "superseded by" arrow, instead of stacking a contradiction.
+//   • RESOLVE — resolutions[] (the ✓ marker) finds the best-matching live card
+//     in the area, stamps "✅ <date>: <note>" onto it and archives it; if no
+//     match, the note lands as a 🏁 milestone so nothing is lost.
+//   • AUTO-LINK — [[Title]] in a new card's text becomes a real connection to
+//     the card/container whose title matches (the graph stops being decorative).
+const tokenSet = (s) => new Set(String(s || '').toLowerCase().replace(/\[\[|\]\]/g, ' ').split(/[^\p{L}\p{N}]+/u).filter(w => w.length >= 4));
+const overlapScore = (a, b) => {
+    if (a.size < 4 || b.size < 4) return 0;            // too short to judge
+    let hit = 0; for (const w of a) if (b.has(w)) hit++;
+    return hit / Math.min(a.size, b.size);
+};
+export async function captureIntoBrain(buffer, { cards = [], resolutions = [], updates = [] } = {}) {
+    const SUPERSEDE_AT = 0.6, RESOLVE_AT = 0.3, UPDATE_AT = 0.45;
+    let work = buffer;
+    const stats = { added: 0, superseded: 0, resolved: 0, linked: 0, updated: 0 };
+
+    // Pass 1 — resolutions + supersede marking operate on EXISTING cards.
+    if (resolutions.length || cards.length || updates.length) {
+        const { zip, canvas, manifest, isV4, struct } = await parseKlypix(work);
+        if (!isV4 || !canvas.positions) {
+            // Legacy file — no surgery possible; degrade to plain append.
+            return { buffer: await appendToKlypix(work, { cards }), 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);
+        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); }
+        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 liveTextCards = () => struct.cards.filter(c =>
+            c.type !== 'container' && (c.text || '').trim()
+            && !/^archive$/i.test(c.area || '')
+            && !/↩|✅/.test(c.text));
+        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 = (id) => {
+            const arc = ensureArchive();
+            const pos = canvas.positions[id];
+            if (pos) canvas.positions[id] = { ...pos, parentId: arc };
+        };
+        canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
+
+        // RESOLVE (✓ markers) — best live match in the area; ❓ cards preferred.
+        const milestonesFallback = [];
+        for (const r of resolutions) {
+            const rTok = tokenSet(r.text);
+            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);
+                if (s > bestScore) { bestScore = s; best = c; }
+            }
+            if (best && bestScore >= RESOLVE_AT) {
+                await rewriteCard(best.id, j => {
+                    j.content = `${j.content}\n✅ ${today}: ${r.text}`;
+                    j.borderColor = 'rgba(16,185,129,0.35)';
+                });
+                archiveCard(best.id);
+                best.text += ` ✅ ${r.text}`; // keep in-memory struct honest for later matching
+                stats.resolved++;
+            } else {
+                milestonesFallback.push({ text: (r.area ? `${r.area}: ` : '') + `🏁 ${r.text}`, area: r.area, borderColor: 'rgba(59,130,246,0.8)' });
+            }
+        }
+
+        // UPDATE (~ markers) — rewrite a matching card IN PLACE: for small
+        // corrections that don't deserve supersession history. Content is
+        // replaced (area prefix + tag preserved), createdAt bumped so the
+        // brief treats it as fresh. No match → falls through as a new card.
+        for (const u of updates) {
+            const uTok = tokenSet(u.text);
+            let best = null, bestScore = 0;
+            for (const c of liveTextCards()) {
+                if (u.area && (c.area || '').toLowerCase() !== u.area.toLowerCase()) continue;
+                const s = overlapScore(uTok, tokenSet(c.text));
+                if (s > bestScore) { bestScore = s; best = c; }
+            }
+            if (best && bestScore >= UPDATE_AT) {
+                const tag = u.area ? `\n#${u.area.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : '';
+                await rewriteCard(best.id, j => {
+                    j.content = (u.area ? `${u.area}: ` : '') + u.text + tag;
+                    j.createdAt = now;
+                    j.borderColor = 'rgba(16,185,129,0.6)';
+                    if (u.createdVia) j.createdVia = String(u.createdVia);
+                });
+                best.text = u.text;
+                stats.updated++;
+            } else {
+                cards.push({ text: (u.area ? `${u.area}: ` : '') + u.text + (u.area ? `\n#${u.area.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : ''), area: u.area, createdVia: u.createdVia });
+            }
+        }
+
+        // SUPERSEDE — pre-mark old cards that a NEW decision replaces. The arrow
+        // 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
+            const nTok = tokenSet(card.text);
+            const area = (card.area || '').toLowerCase();
+            let best = null, bestScore = 0;
+            for (const c of liveTextCards()) {
+                if (area && (c.area || '').toLowerCase() !== area) continue;
+                const s = overlapScore(nTok, tokenSet(c.text));
+                if (s > bestScore) { bestScore = s; best = c; }
+            }
+            if (best && bestScore >= SUPERSEDE_AT) {
+                await rewriteCard(best.id, j => {
+                    j.content = `↩︎ superseded ${today}\n${j.content}`;
+                    j.borderColor = 'rgba(120,120,135,0.5)';
+                });
+                archiveCard(best.id);
+                best.text = `↩︎ ${best.text}`;
+                card.__supersedes = best.id;
+                stats.superseded++;
+            }
+        }
+
+        cards.push(...milestonesFallback);
+        work = await finalizeBrainZip(zip, canvas, manifest, now);
+    }
+
+    // Pass 2 — append the new cards (existing self-organizing path), then wire
+    // connections: supersede arrows + [[wikilink]] auto-links.
+    if (cards.length) {
+        work = await appendIntoContainers(work, { cards });
+        stats.added = cards.length;
+        const { zip, canvas, manifest, struct } = await parseKlypix(work);
+        const now = Date.now();
+        const rand = () => Math.random().toString(36).slice(2, 10);
+        canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
+        const hasConn = (a, b) => canvas.connections.some(cn => (cn.fromId === a && cn.toId === b) || (cn.fromId === b && cn.toId === a));
+        const addConn = (fromId, toId, label, relationship) => {
+            if (!fromId || !toId || fromId === toId || hasConn(fromId, toId)) return;
+            canvas.connections.push({ id: `con_${rand()}`, fromId, toId, relationship, label, arrowHead: true, width: 2, color: '#10b981', style: 'solid' });
+            stats.linked++;
+        };
+        // Locate each appended card by exact text match (newest first wins).
+        const findNew = (text) => {
+            const flatT = wrapText(String(text));
+            for (let i = struct.cards.length - 1; i >= 0; i--) {
+                const c = struct.cards[i];
+                if (c.type !== 'container' && (c.text || '') === flatT) return c;
+            }
+            return null;
+        };
+        const titleIndex = struct.cards
+            .filter(c => (c.title || '').trim())
+            .map(c => ({ id: c.id, t: c.title.trim().toLowerCase() }));
+        for (const card of cards) {
+            const created = findNew(card.text);
+            if (!created) continue;
+            if (card.__supersedes) addConn(card.__supersedes, created.id, 'superseded by', undefined);
+            for (const link of (created.links || [])) {
+                const want = String(link).trim().toLowerCase();
+                if (!want) continue;
+                const target = titleIndex.find(e => e.id !== created.id && (e.t === want || e.t.startsWith(want)));
+                if (target) addConn(created.id, target.id, undefined, 'relates_to');
+            }
+        }
+        work = await finalizeBrainZip(zip, canvas, manifest, now);
+    }
+
+    return { buffer: work, stats };
+}
+
 /**
  * Build a RICH "map" .klypix: areas become titled containers, their cards
  * stack inside, connections draw across. Produces a real spatial board (used by
@@ -345,6 +850,7 @@ export async function buildKlypixMap(spec) {
     const titleToId = new Map(); // card title -> id (for connections)
     const firstLine = (t) => String(t ?? '').split('\n').map(s => s.trim()).find(Boolean) || '';
     let z = 0;
+    const nextZKey = makeZKeyGen();
 
     // Shelf-pack areas into rows of `cols`; each row's height = tallest area.
     let rowTopY = START, rowMaxH = 0, colX = START, colIdx = 0;
@@ -370,7 +876,7 @@ export async function buildKlypixMap(spec) {
             title: area.title || `Area ${ai + 1}`, collapsed: false, scopeLocked: false,
             borderColor: area.color || '#10b981',
         };
-        positions[ctnId] = { x: ax, y: ay, w: AREA_W, h: areaH, zKey: 'a' + String(z).padStart(4, '0'), zIndex: z, parentId: null };
+        positions[ctnId] = { x: ax, y: ay, w: AREA_W, h: areaH, zKey: nextZKey(), zIndex: z, parentId: null };
         order.push(ctnId); z++;
 
         let cy = ay + TITLE_BAR + PAD;
@@ -388,7 +894,7 @@ export async function buildKlypixMap(spec) {
                 textDecoration: 'none', textAlign: 'left', verticalAlign: 'top',
                 fontFamily: 'Thmanyah Sans',
             };
-            positions[id] = { x: ax + PAD, y: cy, w: CARD_W, h, zKey: 'a' + String(z).padStart(4, '0'), zIndex: z, parentId: ctnId };
+            positions[id] = { x: ax + PAD, y: cy, w: CARD_W, h, zKey: nextZKey(), zIndex: z, parentId: ctnId };
             order.push(id); z++;
             const t = firstLine(c.text).toLowerCase();
             if (t && !titleToId.has(t)) titleToId.set(t, id);