klypix-mcp 1.1.0 → 1.3.0

package/bin/klypix-mcp.mjs

@@ -22,7 +22,7 @@ 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, buildKlypixMap, appendToKlypix, structToMarkdown, atomicWrite } from '../src/klypix-format.mjs';
+import { parseKlypix, buildKlypix, buildKlypixMap, appendToKlypix, structToMarkdown, brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, 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);
@@ -177,6 +177,15 @@ server.registerTool('search_canvases', {
 }, async ({ query }) => {
     const q = String(query || '').trim().toLowerCase();
     if (!q) return { content: [{ type: 'text', text: 'Provide a non-empty query.' }], isError: true };
+    // Tokenize so a multi-word query ("window snap") matches a card holding ANY
+    // term — the old verbatim `.includes(fullQuery)` only fired on an exact
+    // contiguous substring, so most multi-word searches silently found nothing.
+    // NOTE: deliberately NOT reusing the brief's scoreCardsAgainstQuery (its
+    // precision sibling, now shared in src/klypix-format.mjs) — that one skips
+    // containers + archived cards and applies a minScore floor, all of which
+    // would hide results a recall-first finder is expected to surface.
+    const terms = q.split(/\s+/).filter(Boolean);
+    const hit = (s) => { const v = String(s || '').toLowerCase(); return terms.some(t => v.includes(t)); };
     const hits = [];
     for (const f of walkVault()) {
         let struct;
@@ -184,11 +193,11 @@ server.registerTool('search_canvases', {
         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 nameMatch = hit(struct.title) || hit(rel);
         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)));
+            hit(c.title) ||
+            hit(c.text) ||
+            (c.tags || []).some(t => hit('#' + t)));
         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.
@@ -296,9 +305,17 @@ server.registerTool('search_all_brains', {
     let qv = null;
     if (pipe) { try { [qv] = await embedTexts(pipe, [q]); } catch { /* lexical only */ } }
 
+    // Current-project locality prior: a card from the project you're working in
+    // should outrank an equally-relevant card from an unrelated project (the
+    // "cross-project search drowned my own project's cards" complaint). The boost
+    // below is modest + mode-aware — never enough to bury a much stronger foreign hit.
+    let curKey = null;
+    try { const cb = resolveCanvas('brain') || resolveCanvas('brain.klypix'); 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) {
+        let isCur = false;
+        try { isCur = !!curKey && path.resolve(b.path).replace(/\\/g, '/').toLowerCase() === curKey; } catch { /* */ }
         let struct;
         try { ({ struct } = await parseKlypix(fs.readFileSync(b.path))); } catch { continue; }
         let vecs = null;
@@ -331,8 +348,9 @@ server.registerTool('search_all_brains', {
             if (asOfTs == null) {
                 if ((c.createdAt || 0) >= fresh) score += 0.5;
                 if (isArchived) score -= 1;
+                if (isCur) score += sem != null ? 1.5 : 1; // current-project locality prior
             }
-            scored.push({ score, sem, project: b.project || path.basename(path.dirname(b.path)), area: c.area, c });
+            scored.push({ score, sem, cur: isCur, 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).` }] };
@@ -340,13 +358,97 @@ server.registerTool('search_all_brains', {
     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)}`;
+        return `- ${h.cur ? '★ ' : ''}[${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')}` }] };
 });
 
+server.registerTool('brain_insights', {
+    title: 'What matters in a brain — hubs, orphans, stale questions',
+    description: 'Structural read of a brain.klypix: the most-connected "hub" cards (load-bearing decisions), orphaned decisions (no connections — maybe forgotten), stale open questions (aging & unresolved), and area sizes. Use to answer "what matters here / what am I forgetting / what should I review?" — read it at the start of a planning session, or before tidying.',
+    inputSchema: {
+        canvas: z.string().optional().describe('Canvas filename/path. Defaults to the project brain ("brain").'),
+        staleDays: z.number().optional().describe('Open questions older than this many days count as stale (default 21).'),
+    },
+}, async ({ canvas, staleDays }) => {
+    const file = resolveCanvas(canvas || 'brain') || resolveCanvas('brain.klypix');
+    if (!file) return { content: [{ type: 'text', text: `No brain canvas found in ${VAULT}. Pass canvas: "<name>", or run \`npx klypix-mcp init\` to create one.` }], isError: true };
+    try {
+        const { struct } = await parseKlypix(fs.readFileSync(file));
+        const ins = brainInsights(struct, staleDays ? { staleDays } : {});
+        return { content: [{ type: 'text', text: insightsToMarkdown(ins, struct.title) }] };
+    } catch (e) {
+        return { content: [{ type: 'text', text: `Insights failed: ${e.message}` }], isError: true };
+    }
+});
+
+server.registerTool('brain_connect', {
+    title: 'Connect related-but-unlinked brain cards (densify the graph)',
+    description: 'Finds genuinely related cards that AREN\'T linked yet and proposes connections — semantic similarity when the on-device model is installed, else shared tags + [[mentions]]. Dry-run by default (review the suggestions); pass apply:true to draw them (ADDITIVE — never deletes; the human can remove any arrow). Use after brain_insights flags many orphans, to turn a flat list into a real knowledge graph.',
+    inputSchema: {
+        canvas: z.string().optional().describe('Canvas filename/path. Defaults to the project brain ("brain").'),
+        apply: z.boolean().optional().describe('false (default) = suggest only; true = draw the connections.'),
+        max: z.number().optional().describe('Max connections to propose/draw (default 24).'),
+        threshold: z.number().optional().describe('Min semantic similarity 0–1 to link (default 0.45). Higher = fewer, tighter links.'),
+    },
+}, async ({ canvas, apply = false, max = 24, threshold = 0.45 }) => {
+    const file = resolveCanvas(canvas || 'brain') || resolveCanvas('brain.klypix');
+    if (!file) return { content: [{ type: 'text', text: `No brain canvas found in ${VAULT}.` }], isError: true };
+    let struct;
+    try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return { content: [{ type: 'text', text: `Read failed: ${e.message}` }], isError: true }; }
+    const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, 70);
+    const byId = new Map(struct.cards.map(c => [c.id, c]));
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !/^archive$/i.test(c.area || ''));
+    const linked = new Set(struct.connections.map(c => [c.fromId, c.toId].sort().join('|')));
+
+    let edges = [];
+    let mode = 'structural (shared tags + [[mentions]])';
+    const pipe = await Promise.race([getEmbedder(), new Promise(r => setTimeout(() => r(null), 20_000))]);
+    if (pipe) {
+        try {
+            const vecs = await vectorsForBrain(pipe, file, struct.cards);
+            const items = live.filter(c => vecs.get(c.id));
+            for (const a of items) {
+                const av = vecs.get(a.id);
+                const sims = items
+                    .filter(b => b.id !== a.id)
+                    .map(b => ({ b, s: dot(av, vecs.get(b.id)), cross: (b.area || '') !== (a.area || '') }))
+                    .sort((x, y) => (y.s + (y.cross ? 0.03 : 0)) - (x.s + (x.cross ? 0.03 : 0))); // nudge toward cross-area links
+                let taken = 0;
+                for (const { b, s } of sims) {
+                    if (s < threshold || taken >= 2) break;       // each card keeps its ≤2 strongest fresh links
+                    const key = [a.id, b.id].sort().join('|');
+                    if (linked.has(key)) continue;
+                    linked.add(key);
+                    edges.push({ fromId: a.id, toId: b.id, sim: s });
+                    taken++;
+                }
+            }
+            edges.sort((x, y) => y.sim - x.sim);
+            mode = 'semantic (on-device)';
+        } catch (e) { mode = `structural (semantic failed: ${e.message})`; }
+    }
+    if (!edges.length && mode.startsWith('structural')) {
+        edges = proposeStructuralConnections(struct);
+    }
+    const chosen = edges.slice(0, max);
+    if (!chosen.length) return { content: [{ type: 'text', text: `Nothing to connect — no related-but-unlinked cards found (mode: ${mode}).` }] };
+
+    const render = (e) => `- ${flat(byId.get(e.fromId)?.text)} ↔ ${flat(byId.get(e.toId)?.text)}${e.sim != null ? `  (${e.sim.toFixed(2)})` : e.why ? `  (${e.why})` : ''}`;
+    if (!apply) {
+        return { content: [{ type: 'text', text: `# ${chosen.length} suggested connection(s) · ${mode}\n_Review, then re-run with apply:true to draw them._\n\n${chosen.map(render).join('\n')}` }] };
+    }
+    try {
+        const { buffer, added } = await addBrainConnections(fs.readFileSync(file), chosen);
+        await atomicWrite(file, buffer);
+        return { content: [{ type: 'text', text: `✓ Drew ${added} connection(s) into ${path.relative(VAULT, file)} (${mode}). Reopen the brain to see the new arrows.\n\n${chosen.slice(0, added).map(render).join('\n')}` }] };
+    } catch (e) {
+        return { content: [{ type: 'text', text: `Apply failed (brain unchanged): ${e.message}` }], isError: true };
+    }
+});
+
 // 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
@@ -427,3 +529,8 @@ server.registerTool('add_to_canvas', {
 const transport = new StdioServerTransport();
 await server.connect(transport);
 log(`ready · vault=${VAULT}`);
+// Pre-warm the on-device embedder in the BACKGROUND so the first cross-project
+// search of a session is already semantic, not a lexical fallback while the
+// MiniLM model loads. getEmbedder() memoizes + swallows its own errors, so this
+// is a safe fire-and-forget (no await → zero added startup latency).
+getEmbedder().then(p => log(p ? 'semantic ready (pre-warmed)' : 'semantic unavailable — lexical only')).catch(() => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.1.0",
+  "version": "1.3.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-format.mjs

@@ -113,9 +113,13 @@ export async function parseKlypix(buffer) {
             parentId: it.parentId ?? null,
             // Parent container's title — the card's "area" in brain terms.
             area: it.parentId ? (cardTitle(items[it.parentId]) || null) : null,
+            // Evidence anchors (file:line / PR#) with the git blob OID stamped at
+            // capture-time — lets the hook flag a card whose cited code drifted.
+            evidence: Array.isArray(it.evidence) && it.evidence.length ? it.evidence : null,
         })),
         connections: connections.map(c => ({
             from: titleOf(c.fromId), to: titleOf(c.toId),
+            fromId: c.fromId, toId: c.toId,        // raw ids — for graph analysis (brainInsights)
             relationship: c.relationship || null, label: c.label || null,
         })),
         assets: assetPaths.map(p => path.basename(p)),
@@ -463,6 +467,8 @@ export async function appendIntoContainers(buffer, addition) {
             // Provenance: WHICH agent remembered this (claude-code / cursor /
             // cline / …) — additive field, ignored by older readers.
             ...(card.createdVia ? { createdVia: String(card.createdVia) } : {}),
+            // Evidence anchors (file:line / PR#) — additive, ignored by older readers.
+            ...(Array.isArray(card.evidence) && card.evidence.length ? { evidence: card.evidence } : {}),
             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',
@@ -555,7 +561,7 @@ export async function tidyBrain(buffer) {
 // 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 } = {}) {
+export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMilestones = 8, maxConnections = 30, freshness = null } = {}) {
     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');
@@ -574,6 +580,9 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     const archivedCount = texts.length - live.length;
 
     const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    // Freshness badge (✅ verified / ⚠️ drifted / 🌱 unverified) for code-anchored
+    // cards — supplied by the git-aware hook; absent → no badge. Trust at a glance.
+    const fr = (c) => (freshness && freshness[c.id]) ? freshness[c.id] + ' ' : '';
     // 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) => {
@@ -596,16 +605,20 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     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)}`);
+        for (const c of focus) push(`- ${fr(c)}${flat(c.text)}`);
     }
-    if (open.length) { push('', '## Open questions'); for (const c of open) push(`- ${flat(c.text)}`); }
+    if (open.length) { push('', '## Open questions'); 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');
+    if (conflicts.length) { push('', '## ⚠️ Conflicts to reconcile (parallel decisions that may disagree)'); for (const c of conflicts.slice(0, 10)) push(`- ${flat(c.from)}  ⚔️  ${flat(c.to)}`); }
     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)}`);
+        for (const c of miles.sort((a, b) => b.createdAt - a.createdAt).slice(0, maxMilestones)) push(`- ${fr(c)}${headline(c)}`);
     }
     let shownRecent = 0;
     if (recent.length) {
@@ -616,7 +629,7 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
             push(`### ${a}`);
             for (const c of cs) {
                 if (used > BUDGET_CHARS) break outer;
-                push(`- ${day(c.createdAt)} ${headline(c)}`);
+                push(`- ${fr(c)}${day(c.createdAt)} ${headline(c)}`);
                 shownRecent++;
             }
         }
@@ -633,6 +646,255 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     return out.join('\n') + '\n';
 }
 
+// ── Relevance ranking ─────────────────────────────────────────────────────
+// ONE shared lexical ranker so the per-prompt retrieval hook (and, later, the
+// MCP search) rank cards the SAME way — no third divergent scorer. Weights
+// mirror the MCP convention: title 3, tag 2, body 1, plus a gentle recency
+// tiebreak. Pure + node-runnable (no embeddings / network) so the Stop/prompt
+// hooks can call it with zero extra deps. `#file-…`/`#dir-…` tags (added at
+// capture) are what make a git-diff token match a card precisely.
+const STOPWORDS = new Set(['the', 'and', 'for', 'that', 'this', 'with', 'from', 'have', 'has', 'was', 'were', 'are', 'you', 'your', 'not', 'but', 'its', 'into', 'out', 'can', 'will', 'use', 'using', 'about', 'what', 'when', 'why', 'how', 'add', 'fix', 'make', 'need', 'want', 'let', 'see', 'get', 'got', 'now', 'all', 'any', 'via', 'per', 'etc', 'should', 'could', 'would', 'does', 'did', 'still', 'just', 'like', 'also', 'then', 'than', 'them', 'they']);
+export function queryTokens(s) {
+    return [...new Set(String(s || '').toLowerCase().match(/[a-z0-9][a-z0-9_-]{2,}/g) || [])].filter(t => !STOPWORDS.has(t));
+}
+const wordsOf = (s) => new Set(String(s || '').toLowerCase().match(/[a-z0-9][a-z0-9_-]{1,}/g) || []);
+export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2, recentDays = 30 } = {}) {
+    const tokens = Array.isArray(query) ? query.filter(Boolean) : queryTokens(query);
+    if (!tokens.length || !struct || !Array.isArray(struct.cards)) return [];
+    const cutoff = Date.now() - recentDays * 86_400_000;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const scored = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || isArchived(c) || !(c.text || '').trim()) continue;
+        // WORD-level matching (not substring) so "app" can't hit "append-klypix"
+        // and "main" can't hit "domain". Tag match is on the tag's STEM (the
+        // slug after #file-/#dir-/#) so a git-diff token (slugify(basename))
+        // lands EXACTLY on its #file- anchor — the precise signal, weighted = a
+        // title hit so ONE anchored file match (3 + 0.5 recency) clears minScore.
+        const titleW = wordsOf(c.title);
+        const bodyW = wordsOf(c.text);
+        const tagStems = new Set((c.tags || []).map(t => String(t).toLowerCase().replace(/^#/, '').replace(/^(file|dir)-/, '')).filter(Boolean));
+        let score = 0;
+        for (const tok of tokens) {
+            if (titleW.has(tok)) score += 3;
+            else if (tagStems.has(tok)) score += 3;
+            else if (bodyW.has(tok)) score += 1;
+        }
+        if (score <= 0) continue;
+        if ((c.createdAt || 0) >= cutoff) score += 0.5; // gentle recency tiebreak, never dominant
+        scored.push({ card: c, score });
+    }
+    scored.sort((a, b) => b.score - a.score || (b.card.createdAt || 0) - (a.card.createdAt || 0));
+    return scored.filter(s => s.score >= minScore).slice(0, topK);
+}
+
+// ── Repeat / redundancy detection ("you already did this in another session") ─
+// The PRECISION-first sibling of scoreCardsAgainstQuery. Instead of "related
+// context" it answers a sharper question: is the user about to REDO work that's
+// already DONE? It scans COMPLETED-work cards ONLY — 🏁 shipped, ✅ resolved,
+// ↩︎ superseded — and INCLUDES the Archive (resolved/superseded cards live there,
+// which the relevance ranker deliberately skips). Deliberately strict: a high
+// score floor + ≥2 distinct query-token hits, because for a NUDGE a false "you
+// already did this" is costly (erodes trust) while a miss is cheap (the loose
+// recall list still shows below). Returns each card's `kind` so the caller can
+// say "reuse it" (shipped/resolved) vs "see what replaced it" (superseded).
+// Pure + node-runnable; reuses the one shared tokenizer — no divergent scorer.
+export function detectRepeatWork(struct, query, { topK = 2, minScore = 5, minTokens = 2 } = {}) {
+    const tokens = Array.isArray(query) ? query.filter(Boolean) : queryTokens(query);
+    if (tokens.length < minTokens || !struct || !Array.isArray(struct.cards)) return [];
+    const kindOf = (t) => /🏁/.test(t) ? 'shipped' : /✅/.test(t) ? 'resolved' : /↩/.test(t) ? 'superseded' : null;
+    const rank = { shipped: 2, resolved: 2, superseded: 1 };
+    const out = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || !(c.text || '').trim()) continue;
+        const kind = kindOf(c.text);
+        if (!kind) continue;                          // only COMPLETED-work cards qualify
+        // Score the first MEANINGFUL line, not a marker stamp: supersede/resolve
+        // prepend "↩︎ superseded <date>" / lead with "✅ …", which would otherwise
+        // become the title and hide the real content from title-weighted matching.
+        const firstMeaningful = String(c.text).split('\n').map(s => s.trim()).filter(Boolean).find(l => !/^[↩✅🏁]/u.test(l));
+        const titleW = wordsOf(firstMeaningful || c.title);
+        const bodyW = wordsOf(c.text);
+        const tagStems = new Set((c.tags || []).map(t => String(t).toLowerCase().replace(/^#/, '').replace(/^(file|dir)-/, '')).filter(Boolean));
+        let score = 0, matched = 0;
+        for (const tok of tokens) {
+            if (titleW.has(tok)) { score += 3; matched++; }
+            else if (tagStems.has(tok)) { score += 3; matched++; }
+            else if (bodyW.has(tok)) { score += 1; matched++; }
+        }
+        if (matched < minTokens || score < minScore) continue;   // precision-first floor
+        out.push({ card: c, score, kind });
+    }
+    out.sort((a, b) => b.score - a.score || (rank[b.kind] - rank[a.kind]) || (b.card.createdAt || 0) - (a.card.createdAt || 0));
+    return out.slice(0, topK);
+}
+
+// ── Conflict candidate detection ───────────────────────────────────────────
+// REAL conflicts only — a conflict is two decisions that genuinely CONTRADICT
+// (you can't honor both about the same thing). Topical similarity, duplication,
+// and sequential supersession are explicitly NOT conflicts and must never be
+// flagged (no false-conflict dump). This is a cheap LEXICAL pre-filter that
+// returns CANDIDATES only — same-subject, not-already-connected pairs where at
+// least one card uses explicit REVERSAL language. Candidates mean nothing on
+// their own: the caller (brain-conflicts.mjs) confirms each with an LLM
+// contradiction-check before anything is ever drawn or surfaced. No verifier →
+// nothing surfaces. Pure + node-runnable.
+// Strong reversal/contradiction terms ONLY — deliberately NOT bare "not"/"don't"
+// (too common → false positives). A candidate still has to clear the LLM gate.
+const OPPOSITION_RE = /\b(instead of|reverted?|no longer|dropp(?:ed|ing)?|deprecat\w*|abandon\w*|replaced?\b|supersed\w*|changed from|switch(?:ed)? (?:from|to)|rolled? back|overrod|overrides?|contradic\w*|disagree\w*|conflicts? with|reversed?\b)/i;
+export function detectConflicts(struct, { minOverlap = 0.45, topK = 12 } = {}) {
+    if (!struct || !Array.isArray(struct.cards)) return [];
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !isArchived(c));
+    const wset = new Map(live.map(c => [c.id, new Set(queryTokens(c.text))]));
+    const connected = new Set();
+    for (const e of struct.connections || []) { connected.add(e.fromId + '|' + e.toId); connected.add(e.toId + '|' + e.fromId); }
+    const out = [];
+    for (let i = 0; i < live.length; i++) {
+        for (let j = i + 1; j < live.length; j++) {
+            const a = live[i], b = live[j];
+            if (connected.has(a.id + '|' + b.id)) continue;
+            const A = wset.get(a.id), B = wset.get(b.id);
+            if (A.size < 4 || B.size < 4) continue;
+            let inter = 0; for (const t of A) if (B.has(t)) inter++;
+            const overlap = inter / Math.min(A.size, B.size); // overlap coefficient — same subject?
+            // Must be same-subject AND carry an explicit reversal signal. Pure
+            // similarity / duplication is NOT a candidate (that was the dump).
+            if (overlap < minOverlap) continue;
+            if (!(OPPOSITION_RE.test(a.text) || OPPOSITION_RE.test(b.text))) continue;
+            out.push({ aId: a.id, bId: b.id, a: a.text, b: b.text, area: a.area, overlap: Math.round(overlap * 100) / 100 });
+        }
+    }
+    out.sort((x, y) => y.overlap - x.overlap);
+    return out.slice(0, topK);
+}
+
+// ── Brain insights ───────────────────────────────────────────────────────────
+// "What matters here, and what am I forgetting?" — a deterministic structural
+// read of the brain (borrowed from graphify's GRAPH_REPORT, applied to the
+// AUTHORED brain, not derived code). Surfaces:
+//   • hubs       — the most-connected cards (load-bearing decisions)
+//   • orphans    — decision/milestone cards with NO connections (isolated;
+//                  maybe forgotten — link them or archive them)
+//   • stale ❓   — open questions older than `staleDays` (aging unknowns)
+//   • areas      — live-card count per area (what's growing / dormant)
+// Pure + node-runnable: no LLM, no network. The agent renders/acts on it.
+export function brainInsights(struct, { staleDays = 21, topHubs = 6 } = {}) {
+    const cutoff = Date.now() - staleDays * 86_400_000;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const cards = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim());
+    const live = cards.filter(c => !isArchived(c));
+    const deg = new Map();
+    for (const cn of struct.connections) {
+        if (cn.fromId) deg.set(cn.fromId, (deg.get(cn.fromId) || 0) + 1);
+        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 hubs = live
+        .map(c => ({ id: c.id, area: c.area, degree: deg.get(c.id) || 0, headline: headline(c) }))
+        .filter(x => x.degree > 0)
+        .sort((a, b) => b.degree - a.degree)
+        .slice(0, topHubs);
+    const orphans = live
+        .filter(c => !isQuestion(c) && !/🌿|⤵/.test(c.text) && !(deg.get(c.id) > 0))
+        .map(c => ({ id: c.id, area: c.area, headline: headline(c), age: c.createdAt }));
+    const staleQuestions = live
+        .filter(c => isQuestion(c) && (c.createdAt || 0) < cutoff)
+        .map(c => ({ id: c.id, area: c.area, headline: headline(c), age: c.createdAt }))
+        .sort((a, b) => (a.age || 0) - (b.age || 0));
+    const areas = struct.cards
+        .filter(c => c.type === 'container' && !/^archive$/i.test(c.title || ''))
+        .map(c => ({ title: c.title, count: cards.filter(t => t.parentId === c.id).length }))
+        .sort((a, b) => b.count - a.count);
+    return {
+        hubs, orphans, staleQuestions, areas,
+        totals: { live: live.length, archived: cards.length - live.length, connections: struct.connections.length },
+    };
+}
+
+// Render brainInsights as a compact markdown report (used by the MCP tool).
+export function insightsToMarkdown(ins, title = 'brain') {
+    const out = [`# ${title} — insights`, `*${ins.totals.live} live cards · ${ins.totals.archived} archived · ${ins.totals.connections} connections*`];
+    if (ins.hubs.length) { out.push('', '## 🪢 Hubs (most-connected — the load-bearing cards)'); for (const h of ins.hubs) out.push(`- (${h.degree}) [${h.area || '?'}] ${h.headline}`); }
+    if (ins.orphans.length) { out.push('', `## 🔌 Orphaned decisions (${ins.orphans.length} — no connections; link them or archive)`); for (const o of ins.orphans.slice(0, 12)) out.push(`- [${o.area || '?'}] ${o.headline}`); if (ins.orphans.length > 12) out.push(`- …and ${ins.orphans.length - 12} more`); }
+    if (ins.staleQuestions.length) { out.push('', `## ⏳ Stale open questions (${ins.staleQuestions.length} — unresolved & aging)`); for (const q of ins.staleQuestions.slice(0, 12)) out.push(`- [${q.area || '?'}] ${q.headline}`); }
+    out.push('', '## 📍 Areas (by live cards)', ins.areas.map(a => `${a.title} (${a.count})`).join(' · ') || '(none)');
+    if (!ins.hubs.length && !ins.orphans.length && !ins.staleQuestions.length) out.push('', '_Brain is small/tidy — no hubs, orphans, or stale questions to flag yet._');
+    return out.join('\n') + '\n';
+}
+
+// Append raw connections (by id) to a brain — additive, never deletes, skips
+// self-links / duplicates / dangling ids, verifies a round-trip parse. Used by
+// the brain_connect tool to densify a sparse brain into a real graph.
+export async function addBrainConnections(buffer, edges) {
+    const { zip, canvas, manifest, isV4 } = await parseKlypix(buffer);
+    if (!isV4 || !canvas.positions) throw new Error('connections need a v4 .klypix');
+    canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
+    const linked = (a, b) => canvas.connections.some(c => (c.fromId === a && c.toId === b) || (c.fromId === b && c.toId === a));
+    const rand = () => Math.random().toString(36).slice(2, 10);
+    let added = 0;
+    for (const e of edges || []) {
+        if (!e.fromId || !e.toId || e.fromId === e.toId) continue;
+        if (!canvas.positions[e.fromId] || !canvas.positions[e.toId]) continue; // both must exist
+        if (linked(e.fromId, e.toId)) continue;
+        canvas.connections.push({
+            id: `con_${rand()}`, fromId: e.fromId, toId: e.toId,
+            relationship: REL.has(e.relationship) ? e.relationship : 'relates_to',
+            label: typeof e.label === 'string' ? e.label : undefined,
+            arrowHead: true, width: 2, color: typeof e.color === 'string' ? e.color : '#10b981', style: 'solid',
+        });
+        added++;
+    }
+    if (!added) return { buffer, added: 0 };
+    const out = await finalizeBrainZip(zip, canvas, manifest, Date.now());
+    return { buffer: out, added };
+}
+
+// Structural connection suggestions — pure, no embeddings (the fallback when
+// the on-device model isn't installed, and the twin of the in-app Connect
+// button). Signals, strongest first: an unlinked [[title]] mention (3), a
+// shared topical tag ACROSS areas (2), a shared tag within an area (1). The
+// area-name tag is dropped (redundant with containment), and — crucially —
+// each card keeps at most `maxPerCard` links, so a tag shared by ten cards
+// can't explode into a 45-edge clique. Mirrors the semantic pass's discipline.
+export function proposeStructuralConnections(struct, { maxPerCard = 2 } = {}) {
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !/^archive$/i.test(c.area || ''));
+    const linked = new Set(struct.connections.map(c => [c.fromId, c.toId].sort().join('|')));
+    const titleIx = live.filter(c => (c.title || '').trim()).map(c => ({ id: c.id, t: c.title.trim().toLowerCase() }));
+    const tagsOf = (c) => (c.tags || [])
+        .map(t => String(t).toLowerCase().replace(/^#/, ''))
+        .filter(t => t && t !== 'area' && t !== String(c.area || '').toLowerCase());
+    const cand = [];
+    for (const c of live) {
+        for (const link of (c.links || [])) {
+            const want = String(link).trim().toLowerCase();
+            const tgt = titleIx.find(e => e.id !== c.id && (e.t === want || e.t.startsWith(want)));
+            if (tgt) cand.push({ a: c.id, b: tgt.id, score: 3, why: 'mention' });
+        }
+        const ct = tagsOf(c);
+        if (!ct.length) continue;
+        for (const d of live) {
+            if (d.id <= c.id) continue;
+            if (tagsOf(d).some(t => ct.includes(t))) cand.push({ a: c.id, b: d.id, score: c.area !== d.area ? 2 : 1, why: 'shared tag' });
+        }
+    }
+    cand.sort((x, y) => y.score - x.score);
+    const per = new Map();
+    const edges = [];
+    for (const e of cand) {
+        if (e.a === e.b) continue;
+        const key = [e.a, e.b].sort().join('|');
+        if (linked.has(key)) continue;
+        if ((per.get(e.a) || 0) >= maxPerCard || (per.get(e.b) || 0) >= maxPerCard) continue;
+        linked.add(key);
+        per.set(e.a, (per.get(e.a) || 0) + 1);
+        per.set(e.b, (per.get(e.b) || 0) + 1);
+        edges.push({ fromId: e.a, toId: e.b, why: e.why });
+    }
+    return edges;
+}
+
 // ── 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
@@ -650,9 +912,9 @@ const overlapScore = (a, b) => {
     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;
+    const SUPERSEDE_AT = 0.6, RESOLVE_AT = 0.3, UPDATE_AT = 0.45, CLOSE_AT = 0.25;
     let work = buffer;
-    const stats = { added: 0, superseded: 0, resolved: 0, linked: 0, updated: 0 };
+    const stats = { added: 0, superseded: 0, resolved: 0, linked: 0, updated: 0, closed: 0 };
 
     // Pass 1 — resolutions + supersede marking operate on EXISTING cards.
     if (resolutions.length || cards.length || updates.length) {
@@ -694,10 +956,28 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             if (pos) canvas.positions[id] = { ...pos, h: measureCardH(j.content) };
             return true;
         };
-        const archiveCard = (id) => {
+        const archiveCard = async (id) => {
             const arc = ensureArchive();
+            // The Archive is readable STORAGE, not a vector-scaled layout: un-bake
+            // any group-shrink (font/width baked tiny) by restoring the frozen
+            // authored baseline and dropping it, so the card sits in the Archive
+            // at full readable size and re-seeds cleanly if the Archive is resized.
+            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 };
+            if (pos) canvas.positions[id] = { ...pos, parentId: arc, ...(authoredW ? { w: authoredW } : {}) };
         };
         canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
 
@@ -716,7 +996,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
                     j.content = `${j.content}\n✅ ${today}: ${r.text}`;
                     j.borderColor = 'rgba(16,185,129,0.35)';
                 });
-                archiveCard(best.id);
+                await archiveCard(best.id);
                 best.text += ` ✅ ${r.text}`; // keep in-memory struct honest for later matching
                 stats.resolved++;
             } else {
@@ -743,11 +1023,14 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
                     j.createdAt = now;
                     j.borderColor = 'rgba(16,185,129,0.6)';
                     if (u.createdVia) j.createdVia = String(u.createdVia);
+                    // Self-heal: a ~ update re-stamps the evidence (fresh OID +
+                    // verifiedAt), so confirming/correcting a drifted fact marks it ✅.
+                    if (Array.isArray(u.evidence) && u.evidence.length) j.evidence = u.evidence;
                 });
                 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 });
+                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, ...(Array.isArray(u.evidence) && u.evidence.length ? { evidence: u.evidence } : {}) });
             }
         }
 
@@ -769,13 +1052,45 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
                     j.content = `↩︎ superseded ${today}\n${j.content}`;
                     j.borderColor = 'rgba(120,120,135,0.5)';
                 });
-                archiveCard(best.id);
+                await archiveCard(best.id);
                 best.text = `↩︎ ${best.text}`;
                 card.__supersedes = best.id;
                 stats.superseded++;
             }
         }
 
+        // CLOSE-LINK — a card carrying `closes` resolves the (often cross-area)
+        // strategy/question card that SPAWNED it: stamp ✅, archive it, and draw a
+        // "closed by" arrow in pass 2. Unlike supersede (same-area, high lexical
+        // overlap), a shipped milestone rarely echoes the strategy's prose — so
+        // this matches across ALL areas, prefers an explicit [[wikilink]]/title
+        // hit, and otherwise fires on only a low overlap. This is the fix for
+        // "strategy cards never get closed out when their feature actually ships".
+        for (const card of cards) {
+            const target = (card.closes || '').toString().trim();
+            if (!target) continue;
+            const wantTitle = target.replace(/^\[\[/, '').replace(/\]\]$/, '').trim().toLowerCase();
+            const tTok = tokenSet(target);
+            let best = null, bestScore = 0;
+            for (const c of liveTextCards()) {
+                const ct = (c.title || '').trim().toLowerCase();
+                if (ct && wantTitle && (ct === wantTitle || ct.startsWith(wantTitle) || wantTitle.startsWith(ct))) { best = c; bestScore = 1; break; }
+                const s = overlapScore(tTok, tokenSet(c.text));
+                if (s > bestScore) { bestScore = s; best = c; }
+            }
+            if (best && bestScore >= CLOSE_AT) {
+                const ship = String(card.text).replace(/\s+/g, ' ').replace(/^[^:\n]{1,40}:\s*/, '').replace(/^🏁\s*/, '').trim().slice(0, 80);
+                await rewriteCard(best.id, j => {
+                    j.content = `${j.content}\n✅ ${today}: closed by → ${ship}`;
+                    j.borderColor = 'rgba(16,185,129,0.35)';
+                });
+                await archiveCard(best.id);
+                best.text = `✅ ${best.text}`;
+                card.__closes = best.id;
+                stats.closed++;
+            }
+        }
+
         cards.push(...milestonesFallback);
         work = await finalizeBrainZip(zip, canvas, manifest, now);
     }
@@ -811,6 +1126,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             const created = findNew(card.text);
             if (!created) continue;
             if (card.__supersedes) addConn(card.__supersedes, created.id, 'superseded by', undefined);
+            if (card.__closes) addConn(card.__closes, created.id, 'closed by', undefined);
             for (const link of (created.links || [])) {
                 const want = String(link).trim().toLowerCase();
                 if (!want) continue;