klypix-mcp 1.1.0 → 1.2.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.
@@ -347,6 +356,90 @@ server.registerTool('search_all_brains', {
     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

package/package.json

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

@@ -116,6 +116,7 @@ export async function parseKlypix(buffer) {
         })),
         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)),
@@ -599,6 +600,10 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
         for (const c of focus) push(`- ${flat(c.text)}`);
     }
     if (open.length) { push('', '## Open questions'); for (const c of open) push(`- ${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})`);
@@ -633,6 +638,214 @@ 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);
+}
+
+// ── 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
@@ -694,10 +907,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 +947,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 {
@@ -769,7 +1000,7 @@ 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++;