klypix-mcp 1.0.0

package/FORMAT.md

@@ -0,0 +1,105 @@
+# The `.klypix` format (v4)
+
+`.klypix` is an **open, local-first, agent-neutral** canvas file. It's a plain
+**ZIP** of JSON + assets — no proprietary binary, fully inspectable (`unzip
+your.klypix`), and parseable with the MIT library in this package. You own it;
+any agent or app can read and write it.
+
+## Container layout
+
+```
+your.klypix              (a ZIP archive)
+├── manifest.json        metadata + stats
+├── canvas.json          spatial layout: order, positions, connections, lines, strokes, settings
+├── items/
+│   └── <2-hex>/<id>.json one file per item (content only; position lives in canvas.json)
+└── assets/
+    └── <assetId>        embedded binaries (images, PDFs, audio, video, files)
+```
+
+Item files are **sharded** by the first 2 hex chars of the id's random part
+(e.g. `items/a3/txt_a3f9…json`) so a canvas with thousands of items stays fast
+to read partially.
+
+## `manifest.json`
+
+```json
+{
+  "format": "klypix",
+  "version": 4,
+  "schemaVersion": 4,
+  "createdAt": "ISO-8601",
+  "updatedAt": "ISO-8601",
+  "title": "My board",
+  "stats": { "itemCount": 12, "assetCount": 3, "totalBytes": 0 }
+}
+```
+
+## `canvas.json`
+
+```json
+{
+  "version": 4,
+  "view": { "panX": 0, "panY": 0, "zoom": 0.8 },
+  "order": ["<id>", "..."],                       // z-order (render order)
+  "positions": {                                   // per-item geometry, by id
+    "<id>": { "x": 0, "y": 0, "w": 280, "h": 80, "zKey": "a001", "zIndex": 1, "parentId": null }
+  },
+  "connections": [                                 // arrows between items
+    { "id": "con_…", "fromId": "<id>", "toId": "<id>", "relationship": "leads_to", "arrowHead": true }
+  ],
+  "lines": [], "strokes": [],                      // freehand drawing
+  "settings": { "background": "#0a0a0f" }
+}
+```
+
+Position/geometry is kept in `canvas.json.positions`, **not** in the item file —
+so moving an item never rewrites its content, and the spatial layout can be read
+without loading every item.
+
+## Item files — `items/<shard>/<id>.json`
+
+Content only (no x/y/w/h). Common types: `text`, `box`, `image`, `file`,
+`code`, `video`, `audio`, `link`, `canvasLink`, `container`. Example text item:
+
+```json
+{
+  "type": "text",
+  "content": "Decision: ship the open format first",
+  "fontSize": 15,
+  "color": "#e8e8ed",
+  "border": true,
+  "heading": false,
+  "createdBy": "agent"
+}
+```
+
+Items can reference an embedded binary in `assets/` (e.g. an `image`/`file`/
+`video`/`audio` item points at its asset id).
+
+## Connections, links, tags
+
+- **Arrows:** `canvas.json.connections` (`fromId`/`toId`, optional
+  `relationship` ∈ `leads_to | depends_on | relates_to | conflicts_with |
+  supports | questions | costs | blocks`).
+- **`[[wikilinks]]`** inside text content cross-link cards (and auto-draw edges).
+- **`#tags`** inside text content group cards.
+
+## Legacy `.any` (v1–v3)
+
+Older files keep an inline `items` array at the root of `canvas.json` instead of
+the `items/` folder + `positions` map. The parser in this package handles both.
+
+## Read / write it
+
+```js
+import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown } from 'klypix-mcp';
+
+const { struct } = await parseKlypix(fs.readFileSync('board.klypix'));
+console.log(structToMarkdown(struct));            // cards + graph + links + tags
+
+const buf = await buildKlypix({ title: 'Plan', cards: [{ text: 'kickoff' }] });
+fs.writeFileSync('plan.klypix', buf);
+```
+
+That's the whole contract: **a ZIP you own, that any model can read and write.**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdullah Aldahshan — Dahshan Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# klypix-mcp
+
+**An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.**
+
+Your AI forgets everything between sessions, and you can't hand it your *whole*
+messy project at once. `klypix-mcp` fixes that with a single portable file:
+
+- **`.klypix`** is one file that holds your whole project spatially — text, PDFs,
+  screenshots, audio, code, links — arranged and connected on an infinite canvas.
+- This package is an **MCP server**: any MCP-capable agent (Claude Desktop,
+  Cursor, Cline, …) can **list, read, search, create, and append** to your
+  `.klypix` canvases — so your agent gets durable, multimodal, *spatial* memory.
+- **Local-first + agent-neutral.** The file lives on *your* disk. No lab is in
+  the loop — read it with Claude today, GPT tomorrow, a local model next week.
+  No vendor can take it away.
+
+## Quick start (60 seconds)
+
+```bash
+# point it at any folder of .klypix files (a "vault")
+npx klypix-mcp --vault ./canvases
+```
+
+Then add it to your MCP client. For **Claude Desktop**, in
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "klypix": {
+      "command": "npx",
+      "args": ["-y", "klypix-mcp", "--vault", "/absolute/path/to/canvases"]
+    }
+  }
+}
+```
+
+Now ask your agent things like *"summarize the canvas `roadmap`,"* *"turn these
+notes into a board,"* or *"add a card with the decision we just made."*
+
+## Tools the server exposes
+
+| Tool | What it does |
+|---|---|
+| `list_canvases` | List every `.klypix` in the vault |
+| `read_canvas` | Read a canvas as markdown (cards, the connection graph, `[[links]]`, `#tags`) |
+| `search_canvases` | Search across canvases by name + content |
+| `create_canvas` | Create a new `.klypix` from cards + connections |
+| `add_to_canvas` | Append cards/connections to an existing canvas (positions preserved) |
+
+## Use it as a library
+
+```js
+import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown } from 'klypix-mcp';
+```
+
+…or read/write from the shell:
+
+```bash
+npx -p klypix-mcp klypix-read   path/to/board.klypix      # → markdown brief
+echo '{ "title": "Plan", "cards": [{ "text": "kickoff" }] }' \
+  | npx -p klypix-mcp klypix-write --out plan.klypix
+```
+
+## The `.klypix` format
+
+A `.klypix` is just a **ZIP** of JSON + assets — open, inspectable, versioned.
+Full spec in [FORMAT.md](FORMAT.md). The point: *you own the file, and any agent
+can drive it.*
+
+## Why this exists
+
+Frontier labs are racing to put your context inside *their* canvas — a roach
+motel your work checks into and never leaves for a competitor. `klypix-mcp` is
+the opposite: **your project, your file, any model, offline.** That's the one
+thing a lab is structurally disincentivized to build.
+
+MIT licensed. Built by [Dahshan Labs](https://klypix.com). The KLYPIX desktop
+app is the spatial editor for these files — but the file and this server are
+fully open and work without it.

package/bin/klypix-append.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// append-klypix — add cards (+ optional connections) to an EXISTING .klypix,
+// preserving every existing item and its position. The CLI twin of the MCP
+// server's add_to_canvas; both use appendToKlypix() in ./klypix-format.mjs.
+//
+// This is what lets a canvas be a *living* brain: read it, then append new
+// decisions/findings as connected cards without rebuilding or moving anything.
+//
+// Usage:
+//   node scripts/append-klypix.mjs <file.klypix> <addition.json>
+//   echo '<addition>' | node scripts/append-klypix.mjs <file.klypix>
+//
+// addition:
+//   { "cards": [{ "text": "...", "heading"?, "color"? }],
+//     "connections": [{ "from": <idx|title>, "to": <idx|title>, "relationship"? }] }
+//   from/to may reference a NEW card (by index in this addition, or its title)
+//   or an EXISTING card already on the canvas (by its title). New cards land in
+//   a column just to the right of the current content, stacked on top.
+
+import fs from 'fs';
+import { appendToKlypix, atomicWrite } from '../src/klypix-format.mjs';
+
+const args = process.argv.slice(2);
+const file = args.find(a => !a.startsWith('--'));
+const additionPath = args.filter(a => !a.startsWith('--'))[1];
+if (!file) { console.error('Usage: node append-klypix.mjs <file.klypix> <addition.json>'); process.exit(2); }
+if (!fs.existsSync(file)) { console.error(`File not found: ${file}`); process.exit(2); }
+
+let addition;
+try {
+    const raw = additionPath ? fs.readFileSync(additionPath, 'utf8') : fs.readFileSync(0, 'utf8');
+    addition = JSON.parse(raw);
+} catch (e) { console.error('Addition is not valid JSON:', e.message); process.exit(2); }
+
+let buf;
+try {
+    buf = await appendToKlypix(fs.readFileSync(file), addition);
+} catch (e) { console.error(e.message); process.exit(1); }
+
+await atomicWrite(file, buf);
+const cardCount = Array.isArray(addition.cards) ? addition.cards.length : 0;
+const connCount = Array.isArray(addition.connections) ? addition.connections.length : 0;
+console.log(`Appended ${cardCount} card(s), ${connCount} connection(s) to ${file}.`);
+console.log(`Reopen it in KLYPIX, or verify: node scripts/read-klypix.mjs "${file}"`);

package/bin/klypix-mcp.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// klypix-mcp-server — a Model Context Protocol server that gives any MCP client
+// (Claude Desktop, Claude Code, "cowork", …) full READ + WRITE access to your
+// .klypix canvas library. It turns the one-off read-klypix / write-klypix
+// skills into a standing, tool-based connection: an outside agent can list your
+// canvases, read one (cards + connection graph + [[links]] + #tags), search
+// across all of them, create a new board, or add cards to an existing one.
+//
+// It operates on the .klypix FILES in a "vault" folder — no need for the KLYPIX
+// desktop app to be running, and nothing here can corrupt a live canvas.
+//
+// Run (stdio):   node scripts/klypix-mcp-server.mjs --vault "C:\\path\\to\\canvases"
+//   or set env:  KLYPIX_VAULT=...   (default: ~/Documents)
+//
+// Register in Claude Code (.mcp.json) or Claude Desktop (claude_desktop_config
+// .json) — see docs/KLYPIX_MCP.md.
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+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';
+
+// IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
+const log = (...a) => console.error('[klypix-mcp]', ...a);
+
+const vaultArgIdx = process.argv.indexOf('--vault');
+const VAULT = path.resolve(
+    vaultArgIdx >= 0 ? process.argv[vaultArgIdx + 1]
+        : process.env.KLYPIX_VAULT || path.join(os.homedir(), 'Documents'),
+);
+const IS_CANVAS = /\.(klypix|any)$/i;
+const SKIP_DIRS = new Set(['node_modules', '.git', '.cache', 'AppData', '$Recycle.Bin', 'Windows']);
+const MAX_FILES = 400;
+
+function walkVault() {
+    const out = [];
+    const visit = (dir, depth) => {
+        if (out.length >= MAX_FILES || depth > 6) return;
+        let entries;
+        try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+        for (const e of entries) {
+            if (out.length >= MAX_FILES) return;
+            if (e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) visit(full, depth + 1);
+            else if (e.isFile() && IS_CANVAS.test(e.name)) out.push(full);
+        }
+    };
+    visit(VAULT, 0);
+    return out;
+}
+
+// Resolve a user-supplied canvas reference: absolute path, vault-relative path,
+// or a bare filename (matched against the walked list, case-insensitively).
+function resolveCanvas(ref) {
+    if (!ref) return null;
+    if (path.isAbsolute(ref) && fs.existsSync(ref)) return ref;
+    const rel = path.join(VAULT, ref);
+    if (fs.existsSync(rel)) return rel;
+    const want = path.basename(ref).toLowerCase();
+    const matches = walkVault().filter(f => path.basename(f).toLowerCase() === want
+        || path.basename(f).toLowerCase() === want + '.klypix'
+        || path.basename(f).toLowerCase() === want + '.any');
+    return matches[0] || null;
+}
+
+function safeName(title) {
+    const base = String(title || 'untitled').replace(/[^\w\- ]+/g, '').trim() || 'untitled';
+    let name = base, n = 1;
+    while (fs.existsSync(path.join(VAULT, `${name}.klypix`))) name = `${base} ${++n}`;
+    return `${name}.klypix`;
+}
+
+const cardSchema = z.object({
+    text: z.string().describe('Card text. First line is the card title.'),
+    heading: z.boolean().optional().describe('Bold title card for the main goal/topic.'),
+    color: z.string().optional().describe('Hex color, e.g. #ef4444 for a risk/blocker.'),
+});
+const connSchema = z.object({
+    from: z.union([z.number(), z.string()]).describe('Source card: index (0-based), title, or id.'),
+    to: z.union([z.number(), z.string()]).describe('Target card: index, title, or id.'),
+    relationship: z.string().optional().describe('leads_to|depends_on|relates_to|conflicts_with|supports|questions|costs|blocks'),
+    label: z.string().optional(),
+});
+
+const server = new McpServer({ name: 'klypix-canvas', version: '1.0.0' });
+
+server.registerTool('list_canvases', {
+    title: 'List KLYPIX canvases',
+    description: 'List all .klypix / .any canvas files in the vault, with card and connection counts.',
+    inputSchema: {},
+}, async () => {
+    const files = walkVault();
+    if (files.length === 0) {
+        return { content: [{ type: 'text', text: `No .klypix/.any files found under vault: ${VAULT}\nSet --vault or KLYPIX_VAULT to your canvas folder.` }] };
+    }
+    const rows = [];
+    for (const f of files) {
+        try {
+            const { struct } = await parseKlypix(fs.readFileSync(f));
+            const st = fs.statSync(f);
+            rows.push(`- ${path.relative(VAULT, f)} — "${struct.title}" · ${struct.counts.cards} cards, ${struct.counts.connections} connections · ${new Date(st.mtimeMs).toISOString().slice(0, 10)}`);
+        } catch {
+            rows.push(`- ${path.relative(VAULT, f)} — (unreadable)`);
+        }
+    }
+    return { content: [{ type: 'text', text: `# Canvases in ${VAULT}\n\n${rows.join('\n')}` }] };
+});
+
+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.') },
+}, 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) }] };
+    } catch (e) {
+        return { content: [{ type: 'text', text: `Failed to read ${file}: ${e.message}` }], isError: true };
+    }
+});
+
+server.registerTool('search_canvases', {
+    title: 'Search inside all canvases',
+    description: 'Search card text, titles, and #tags across every canvas in the vault. Returns the canvases and the matching cards.',
+    inputSchema: { query: z.string().describe('Text or #tag to find inside canvases.') },
+}, async ({ query }) => {
+    const q = String(query || '').trim().toLowerCase();
+    if (!q) return { content: [{ type: 'text', text: 'Provide a non-empty query.' }], isError: true };
+    const hits = [];
+    for (const f of walkVault()) {
+        let struct;
+        try { ({ struct } = await parseKlypix(fs.readFileSync(f))); } catch { continue; }
+        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'));
+        }
+    }
+    return { content: [{ type: 'text', text: hits.length ? `# Matches for "${query}"\n\n${hits.join('\n\n')}` : `No matches for "${query}" in ${VAULT}.` }] };
+});
+
+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.',
+    inputSchema: {
+        title: z.string().describe('Canvas title (also the filename).'),
+        cards: z.array(cardSchema).min(1).describe('The cards. 5-12 atomic cards is ideal.'),
+        connections: z.array(connSchema).optional().describe('Arrows between cards.'),
+        filename: z.string().optional().describe('Override the output filename (without extension).'),
+    },
+}, async ({ title, cards, connections, filename }) => {
+    if (!fs.existsSync(VAULT)) { try { fs.mkdirSync(VAULT, { recursive: true }); } catch { /* ignore */ } }
+    try {
+        const buf = await buildKlypix({ title, cards, connections });
+        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).` }] };
+    } catch (e) {
+        return { content: [{ type: 'text', text: `Create failed: ${e.message}` }], isError: true };
+    }
+});
+
+server.registerTool('add_to_canvas', {
+    title: 'Add cards to an existing canvas',
+    description: 'Append cards (and optional connections) to an existing v4 .klypix, preserving all existing items and their positions. New cards are placed to the right of the current content. Connections may reference new cards (by index/title) or existing cards (by title).',
+    inputSchema: {
+        canvas: z.string().describe('Canvas filename, vault-relative path, or absolute path.'),
+        cards: z.array(cardSchema).min(1).describe('Cards to add.'),
+        connections: z.array(connSchema).optional(),
+    },
+}, async ({ canvas, cards, connections }) => {
+    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 });
+        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.` }] };
+    } catch (e) {
+        return { content: [{ type: 'text', text: `Add failed: ${e.message}` }], isError: true };
+    }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+log(`ready · vault=${VAULT}`);

package/bin/klypix-read.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// read-klypix — turn a .klypix (or legacy .any) file into structured markdown
+// an AI agent can fully understand: every card's text, the connection graph,
+// [[wikilinks]] + #tags, and a manifest of images/files (with extracted paths
+// so the agent can read images with vision).
+//
+// This is the reference CLI behind the `read-klypix` Claude Code skill. The
+// actual parsing lives in ./klypix-format.mjs (shared with write-klypix and the
+// MCP server) so the format logic has exactly one home.
+//
+// Usage:
+//   node scripts/read-klypix.mjs <file.klypix> [--assets <outDir>] [--json]
+//     --assets <dir>  extract binary assets (images/files) into <dir>
+//     --json          emit a structured JSON object instead of markdown
+
+import fs from 'fs';
+import path from 'path';
+import { parseKlypix, structToMarkdown } from '../src/klypix-format.mjs';
+
+const args = process.argv.slice(2);
+const file = args.find(a => !a.startsWith('--'));
+const assetsDir = (() => { const i = args.indexOf('--assets'); return i >= 0 ? args[i + 1] : null; })();
+const asJson = args.includes('--json');
+if (!file) { console.error('Usage: node read-klypix.mjs <file.klypix> [--assets <dir>] [--json]'); process.exit(2); }
+if (!fs.existsSync(file)) { console.error(`File not found: ${file}`); process.exit(2); }
+
+let parsed;
+try {
+    parsed = await parseKlypix(fs.readFileSync(file));
+} catch (e) {
+    console.error(e.message);
+    process.exit(1);
+}
+const { struct, zip, assetPaths } = parsed;
+// Fall back to the filename for the title when the file didn't store one.
+if (!struct.title || struct.title === 'Untitled') {
+    struct.title = path.basename(file).replace(/\.(klypix|any)$/i, '');
+}
+
+// Optionally extract binary assets so the agent can open images with vision.
+if (assetsDir && assetPaths.length) {
+    fs.mkdirSync(assetsDir, { recursive: true });
+    for (const p of assetPaths) {
+        const bytes = await zip.file(p).async('nodebuffer');
+        fs.writeFileSync(path.join(assetsDir, path.basename(p)), bytes);
+    }
+}
+
+if (asJson) { console.log(JSON.stringify(struct, null, 2)); process.exit(0); }
+console.log(structToMarkdown(struct, { assetsDir }));

package/bin/klypix-write.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// write-klypix — assemble a real .klypix canvas from a simple JSON spec.
+// The reverse of read-klypix. The build logic (content-aware sizing, BFS
+// layout, v4 ZIP output) lives in ./klypix-format.mjs (shared with the MCP
+// server) so it has exactly one home.
+//
+// Usage:
+//   node scripts/write-klypix.mjs <spec.json> [--out <file.klypix>]
+//   cat spec.json | node scripts/write-klypix.mjs --out board.klypix
+//
+// Spec:
+//   { "title": "...", "cards": [{ "text": "...", "heading"?, "color"? }],
+//     "connections": [{ "from": 0, "to": 1, "relationship"? }] }
+//   from/to reference a card by INDEX, generated id, or its title (first line).
+//   relationship ∈ leads_to | depends_on | relates_to | conflicts_with |
+//   supports | questions | costs | blocks.
+
+import fs from 'fs';
+import { buildKlypix, atomicWrite } from '../src/klypix-format.mjs';
+
+const args = process.argv.slice(2);
+const outIdx = args.indexOf('--out');
+const outArg = outIdx >= 0 ? args[outIdx + 1] : null;
+// The spec path is the first POSITIONAL arg that isn't a flag AND isn't the
+// value consumed by --out (else `--out x.klypix` with stdin spec mis-reads x as
+// the spec). null → read the spec from stdin.
+const specPath = args.find((a, i) => !a.startsWith('--') && i !== outIdx + 1) || null;
+
+let spec;
+try {
+    const raw = specPath ? fs.readFileSync(specPath, 'utf8') : fs.readFileSync(0, 'utf8');
+    spec = JSON.parse(raw);
+} catch (e) { console.error('Spec is not valid JSON:', e.message); process.exit(2); }
+
+let buf;
+try {
+    buf = await buildKlypix(spec);
+} catch (e) { console.error(e.message); process.exit(2); }
+
+const outPath = outArg || `${(spec.title || 'untitled').replace(/[^\w\- ]+/g, '').trim() || 'untitled'}.klypix`;
+await atomicWrite(outPath, buf);
+const cardCount = spec.cards.length;
+const connCount = Array.isArray(spec.connections) ? spec.connections.length : 0;
+console.log(`Wrote ${outPath} — ${cardCount} cards, ${connCount} connections.`);
+console.log(`Open it in KLYPIX (Canvas → Open), or verify: node scripts/read-klypix.mjs "${outPath}"`);

package/index.mjs

@@ -0,0 +1,5 @@
+// klypix-mcp — programmatic entry. Re-exports the pure .klypix format library
+// (parse / build / append / markdown / atomic write) so you can read and write
+// the agent-neutral canvas file from any Node code, with no MCP/agent in the
+// loop. The MCP server itself is the `klypix-mcp` bin.
+export * from './src/klypix-format.mjs';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "klypix-mcp",
+  "version": "1.0.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",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "canvas",
+    "agent",
+    "agent-memory",
+    "local-first",
+    "klypix",
+    "whiteboard",
+    "spatial",
+    "ai"
+  ],
+  "homepage": "https://klypix.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dahshanlabs/klypix-mcp"
+  },
+  "bin": {
+    "klypix-mcp": "bin/klypix-mcp.mjs",
+    "klypix-read": "bin/klypix-read.mjs",
+    "klypix-write": "bin/klypix-write.mjs",
+    "klypix-append": "bin/klypix-append.mjs"
+  },
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./format": "./src/klypix-format.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "index.mjs",
+    "FORMAT.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "jszip": "^3.10.1",
+    "zod": "^4.3.6"
+  }
+}

package/src/klypix-format.mjs

@@ -0,0 +1,471 @@
+// klypix-format — the single source of truth for reading & writing .klypix
+// (and legacy .any) canvas files. Shared by read-klypix.mjs, write-klypix.mjs,
+// and klypix-mcp-server.mjs so the format logic lives in exactly one place.
+//
+// .klypix v4 ZIP layout: manifest.json · canvas.json · items/<prefix>/<id>.json
+// · assets/<assetId>. Legacy .any (v1–v3) keeps an inline items array in
+// canvas.json at the root — handled by parseKlypix too.
+
+import JSZip from 'jszip';
+import path from 'path';
+import fs from 'fs';
+
+export const WIKILINK = /\[\[([^[\]]+)\]\]/g;
+export const TAG = /(^|\s)(#[a-zA-Z][\w-]*)/g;
+
+export function extractLinks(text) {
+    const out = []; WIKILINK.lastIndex = 0; let m;
+    while ((m = WIKILINK.exec(text || '')) !== null) out.push(m[1].trim());
+    return out;
+}
+export function extractTags(text) {
+    const out = []; TAG.lastIndex = 0; let m;
+    while ((m = TAG.exec(text || '')) !== null) out.push(m[2].slice(1));
+    return out;
+}
+export function cardTitle(item) {
+    if (item?.type === 'container') return item.title || null;
+    if (item?.type !== 'text') return null;
+    for (const line of String(item.content ?? '').split('\n')) {
+        const t = line.trim();
+        if (t) return t.replace(/^([#>\-*•]+\s+|\d+\.\s+)/, '').trim() || t;
+    }
+    return null;
+}
+// v4 shards item files by the first 2 hex chars of the id's random part.
+export const shard = (id) => id.replace(/^[a-z]+[_:]/i, '').toLowerCase().slice(0, 2).padStart(2, '_');
+
+/**
+ * Atomically persist a .klypix buffer: verify it round-trips, write a sibling
+ * .tmp, then rename over the target. A concurrent reader (e.g. the shared-brain
+ * watcher) therefore never parses a half-written ZIP, and a failed/garbage
+ * write leaves the previous good file intact. Use this for ALL brain writes
+ * instead of fs.writeFileSync.
+ */
+export async function atomicWrite(filePath, buf) {
+    try { await parseKlypix(buf); }
+    catch (e) { throw new Error('refusing to write an unparseable .klypix (' + path.basename(filePath) + '): ' + (e?.message || e)); }
+    const tmp = filePath + '.tmp-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+    fs.writeFileSync(tmp, buf);
+    try { fs.renameSync(tmp, filePath); }    // Node uses MoveFileEx(REPLACE_EXISTING) on Windows → overwrites atomically
+    catch (e) { try { fs.rmSync(tmp); } catch { /* */ } throw e; }
+}
+
+/**
+ * Parse a .klypix/.any buffer into a structured object + the loaded zip (so
+ * callers can extract binary assets). Throws on a non-canvas file.
+ */
+export async function parseKlypix(buffer) {
+    const zip = await JSZip.loadAsync(buffer);
+    const readText = async (p) => { const e = zip.file(p); return e ? e.async('string') : null; };
+
+    const manifestRaw = await readText('manifest.json');
+    const canvasRaw = await readText('canvas.json');
+    if (!canvasRaw) throw new Error('Not a valid .klypix/.any — no canvas.json inside.');
+
+    const manifest = manifestRaw ? JSON.parse(manifestRaw) : null;
+    const canvas = JSON.parse(canvasRaw);
+    // v4 manifests are {format:"klypix", version:4}; positions presence is the
+    // robust fallback (legacy .any keeps an inline items array, no positions).
+    const isV4 = (!!manifest && manifest.format === 'klypix' && manifest.version >= 4) || !!canvas.positions;
+
+    const order = Array.isArray(canvas.order) ? canvas.order : [];
+    const items = {};
+    if (isV4 && canvas.positions) {
+        for (const id of order) {
+            const raw = await readText(`items/${shard(id)}/${id}.json`);
+            if (!raw) continue;
+            items[id] = { id, ...(canvas.positions[id] || {}), ...JSON.parse(raw) };
+        }
+    } else if (Array.isArray(canvas.items)) {
+        for (const it of canvas.items) items[it.id] = it;
+    }
+
+    const connections = Array.isArray(canvas.connections) ? canvas.connections : [];
+    const titleOf = (id) => cardTitle(items[id]) || (items[id]?.type ? `${items[id].type} ${String(id).slice(0, 8)}` : String(id).slice(0, 8));
+    const assetPaths = Object.keys(zip.files).filter(p => p.startsWith('assets/') && !zip.files[p].dir);
+    const cards = order.length ? order.map(id => items[id]).filter(Boolean) : Object.values(items);
+
+    const struct = {
+        title: manifest?.title || canvas.title || 'Untitled',
+        format: isV4 ? 'klypix-v4' : `legacy-v${canvas.version ?? '?'}`,
+        counts: { cards: cards.length, connections: connections.length, assets: assetPaths.length },
+        cards: cards.map(it => ({
+            id: it.id, type: it.type,
+            title: cardTitle(it),
+            text: it.type === 'text' ? it.content : (it.name || it.title || it.url || null),
+            links: it.type === 'text' ? extractLinks(it.content) : [],
+            tags: it.type === 'text' ? extractTags(it.content) : [],
+            pos: { x: it.x, y: it.y },
+        })),
+        connections: connections.map(c => ({
+            from: titleOf(c.fromId), to: titleOf(c.toId),
+            relationship: c.relationship || null, label: c.label || null,
+        })),
+        assets: assetPaths.map(p => path.basename(p)),
+    };
+    return { struct, zip, assetPaths, isV4, canvas, manifest };
+}
+
+const REL = new Set(['leads_to', 'depends_on', 'relates_to', 'conflicts_with', 'supports', 'questions', 'costs', 'blocks']);
+
+/**
+ * Build a real .klypix v4 file (nodebuffer) from a simple spec:
+ *   { title, cards: [{id?, type?, text, heading?, color?, x?, y?, w?}], connections: [{from, to, relationship?, label?}] }
+ * from/to reference a card by INDEX, generated id, or its title (first line).
+ * Cards are content-sized and laid out on a BFS-ordered grid so linked cards
+ * land near each other.
+ */
+export async function buildKlypix(spec) {
+    if (!spec || !Array.isArray(spec.cards) || spec.cards.length === 0) {
+        throw new Error('spec needs a non-empty "cards" array');
+    }
+    const now = Date.now();
+    const nowIso = new Date(now).toISOString();
+    const rand = () => Math.random().toString(36).slice(2, 10);
+
+    const cards = spec.cards.map((c, i) => {
+        const type = c.type || 'text';
+        const prefix = type === 'text' ? 'txt' : type === 'image' ? 'img' : type === 'container' ? 'ctn' : 'itm';
+        return { ...c, type, _id: c.id || `${prefix}_${rand()}_${i}` };
+    });
+    const idByIndex = cards.map(c => c._id);
+    const firstLine = (t) => String(t ?? '').split('\n').map(s => s.trim()).find(Boolean) || '';
+    const idByTitle = new Map(cards.map(c => [firstLine(c.text).toLowerCase(), c._id]));
+    const resolveRef = (ref) => {
+        if (typeof ref === 'number') return idByIndex[ref] ?? null;
+        if (typeof ref === 'string') { if (idByIndex.includes(ref)) return ref; return idByTitle.get(ref.trim().toLowerCase()) ?? null; }
+        return null;
+    };
+
+    const connections = (Array.isArray(spec.connections) ? spec.connections : []).map((c, i) => {
+        const fromId = resolveRef(c.from), toId = resolveRef(c.to);
+        if (!fromId || !toId || fromId === toId) return null;
+        return {
+            id: `con_${rand()}_${i}`, fromId, toId,
+            relationship: REL.has(c.relationship) ? c.relationship : undefined,
+            label: typeof c.label === 'string' ? c.label : undefined,
+            arrowHead: true, width: 2, color: '#10b981', style: 'solid',
+        };
+    }).filter(Boolean);
+
+    // BFS order so connected cards land near each other.
+    const adj = new Map(idByIndex.map(id => [id, []]));
+    for (const c of connections) { adj.get(c.fromId)?.push(c.toId); adj.get(c.toId)?.push(c.fromId); }
+    const indeg = new Map(idByIndex.map(id => [id, 0]));
+    for (const c of connections) indeg.set(c.toId, (indeg.get(c.toId) || 0) + 1);
+    const visited = new Set();
+    const order = [];
+    const starts = [...idByIndex].sort((a, b) => (indeg.get(a) - indeg.get(b)) || (idByIndex.indexOf(a) - idByIndex.indexOf(b)));
+    for (const s of starts) {
+        if (visited.has(s)) continue;
+        const q = [s];
+        while (q.length) {
+            const id = q.shift();
+            if (visited.has(id)) continue;
+            visited.add(id); order.push(id);
+            for (const n of (adj.get(id) || [])) if (!visited.has(n)) q.push(n);
+        }
+    }
+
+    const FONT = 20, PAD = 28, LINE_H = FONT * 1.35;
+    const sizeFor = (card) => {
+        if (card.x != null && card.w != null) return { w: card.w, h: card.h ?? 40 };
+        const lines = String(card.text ?? '').split('\n');
+        const longest = lines.reduce((m, l) => Math.max(m, l.length), 0);
+        const w = Math.max(160, Math.min(360, Math.round(longest * (FONT * 0.55)) + PAD));
+        const h = Math.max(40, Math.round(lines.length * LINE_H) + 14);
+        return { w, h };
+    };
+    const cols = Math.max(1, Math.ceil(Math.sqrt(order.length)));
+    const COL_W = 380, GAP_Y = 70, START = 80;
+    const positions = {};
+    let zi = 0;
+    order.forEach((id, idx) => {
+        const card = cards[idByIndex.indexOf(id)];
+        const { w, h } = sizeFor(card);
+        const col = idx % cols, row = Math.floor(idx / cols);
+        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,
+        };
+    });
+
+    const itemJson = (card) => {
+        if (card.type === 'text') {
+            return {
+                type: 'text', locked: false, createdAt: now, createdBy: 'agent',
+                content: String(card.text ?? ''), fontSize: FONT,
+                color: card.color || '#1a1a1f', border: !!card.border, borderColor: '#1e1e2e',
+                heading: !!card.heading, fontFamily: 'Thmanyah Sans',
+                fontWeight: card.heading ? 'bold' : 'normal', fontStyle: 'normal',
+                textDecoration: 'none', textAlign: 'left', verticalAlign: 'top',
+            };
+        }
+        return { type: card.type, locked: false, createdAt: now, createdBy: 'agent', ...(card._raw || {}) };
+    };
+
+    const zip = new JSZip();
+    const manifest = {
+        format: 'klypix', version: 4, schemaVersion: 4,
+        createdAt: nowIso, updatedAt: nowIso,
+        title: spec.title || 'Untitled',
+        stats: { itemCount: order.length, assetCount: 0, totalBytes: 0 },
+        sync: { enabled: false, lastSyncRev: null, lastSyncAt: null, deviceId: `dev_${rand()}${rand()}` },
+    };
+    const xs = Object.values(positions);
+    const minX = Math.min(...xs.map(p => p.x)), minY = Math.min(...xs.map(p => p.y));
+    const canvasJson = {
+        version: 4,
+        view: { panX: 120 - minX * 0.7, panY: 120 - minY * 0.7, zoom: 0.7 },
+        order, connections, lines: [], strokes: [], nextGroupNumber: 1,
+        positions, settings: { background: '#0a0a0f' },
+    };
+    zip.file('manifest.json', JSON.stringify(manifest));
+    zip.file('canvas.json', JSON.stringify(canvasJson));
+    for (const id of order) {
+        const card = cards[idByIndex.indexOf(id)];
+        zip.file(`items/${shard(id)}/${id}.json`, JSON.stringify(itemJson(card)));
+    }
+    return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+}
+
+/**
+ * Append cards (+ optional connections) to an EXISTING v4 .klypix, preserving
+ * every existing item and its position. New cards are placed in a column just
+ * to the right of the current content and stacked on top (z above existing).
+ * connection from/to may reference a NEW card by index/title, or an EXISTING
+ * card by its title. Returns a nodebuffer of the updated file.
+ */
+export async function appendToKlypix(buffer, addition) {
+    const { zip, canvas, manifest, isV4, struct } = await parseKlypix(buffer);
+    if (!isV4 || !canvas.positions) {
+        throw new Error('append supports v4 .klypix only; for a legacy .any, create a new canvas instead');
+    }
+    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 FONT = 20, LINE_H = FONT * 1.35;
+
+    const ex = Object.values(canvas.positions);
+    const maxX = ex.length ? Math.max(...ex.map(p => p.x + (p.w || 160))) : 80;
+    const minY = ex.length ? Math.min(...ex.map(p => p.y)) : 80;
+    const startX = maxX + 80;
+
+    const titleToId = new Map();
+    for (const c of struct.cards) { const t = (c.title || '').toLowerCase(); if (t && !titleToId.has(t)) titleToId.set(t, c.id); }
+
+    let zTop = Array.isArray(canvas.order) ? canvas.order.length : 0;
+    const added = newCards.map((c, i) => {
+        const lines = String(c.text).split('\n');
+        const longest = lines.reduce((m, l) => Math.max(m, l.length), 0);
+        const w = Math.max(160, Math.min(360, Math.round(longest * (FONT * 0.55)) + 28));
+        const h = Math.max(40, Math.round(lines.length * LINE_H) + 14);
+        return { id: `txt_${rand()}_${i}`, card: c, x: startX, y: minY + i * 160, w, h, z: zTop + i };
+    });
+
+    const addedTitle = new Map(added.map(a => [String(a.card.text).split('\n').map(s => s.trim()).find(Boolean)?.toLowerCase() || '', a.id]));
+    const resolve = (ref) => {
+        if (typeof ref === 'number') return added[ref]?.id ?? null;
+        if (typeof ref === 'string') {
+            const k = ref.trim().toLowerCase();
+            return addedTitle.get(k) || titleToId.get(k) || (canvas.positions[ref] ? ref : null);
+        }
+        return null;
+    };
+
+    canvas.order = Array.isArray(canvas.order) ? canvas.order : [];
+    for (const a of added) {
+        zip.file(`items/${shard(a.id)}/${a.id}.json`, JSON.stringify({
+            type: 'text', locked: false, createdAt: now, createdBy: 'agent',
+            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.order.push(a.id);
+    }
+
+    canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
+    (addition?.connections || []).forEach((cn, i) => {
+        const fromId = resolve(cn.from), toId = resolve(cn.to);
+        if (!fromId || !toId || fromId === toId) return;
+        canvas.connections.push({
+            id: `con_${rand()}_${i}`, fromId, toId,
+            relationship: REL.has(cn.relationship) ? cn.relationship : undefined,
+            label: typeof cn.label === 'string' ? cn.label : undefined,
+            arrowHead: true, width: 2, color: '#10b981', style: 'solid',
+        });
+    });
+
+    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' });
+    // Parse-resilience: never return a buffer that doesn't round-trip — the
+    // caller keeps the last-known-good file rather than writing corruption.
+    try { await parseKlypix(out); }
+    catch (e) { throw new Error('append produced an unparseable .klypix — aborting to protect the brain: ' + (e?.message || e)); }
+    return out;
+}
+
+/**
+ * Build a RICH "map" .klypix: areas become titled containers, their cards
+ * stack inside, connections draw across. Produces a real spatial board (used by
+ * the project brain) rather than a flat grid. Spec:
+ *   { title, areas: [{ title, color?, cards: [{text, heading?, color?}] }],
+ *     connections: [{ from, to, relationship?, label? }] }   // from/to by card title
+ */
+export async function buildKlypixMap(spec) {
+    if (!spec || !Array.isArray(spec.areas) || spec.areas.length === 0) {
+        throw new Error('map spec needs a non-empty "areas" array');
+    }
+    const now = Date.now();
+    const nowIso = new Date(now).toISOString();
+    const rand = () => Math.random().toString(36).slice(2, 10);
+
+    const TITLE_BAR = 44, PAD = 16, CARD_GAP = 12, CARD_W = 280, FONT = 15, LINE_H = FONT * 1.4;
+    const AREA_W = CARD_W + PAD * 2;
+    const COL_GAP = 48, ROW_GAP = 48, START = 80;
+    const cols = Math.max(1, Math.min(4, Math.ceil(Math.sqrt(spec.areas.length))));
+
+    const positions = {};
+    const order = [];
+    const items = {}; // id -> json
+    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;
+
+    // Shelf-pack areas into rows of `cols`; each row's height = tallest area.
+    let rowTopY = START, rowMaxH = 0, colX = START, colIdx = 0;
+    spec.areas.forEach((area, ai) => {
+        const cards = (area.cards || []).filter(c => c && typeof c.text === 'string' && c.text.trim());
+        // measure card heights
+        const measured = cards.map(c => {
+            const lines = String(c.text).split('\n').length;
+            return Math.max(40, Math.round(lines * LINE_H) + 18);
+        });
+        const innerH = measured.reduce((s, h) => s + h + CARD_GAP, 0);
+        const areaH = TITLE_BAR + PAD + innerH + PAD;
+
+        if (colIdx >= cols) { // new row
+            rowTopY += rowMaxH + ROW_GAP;
+            rowMaxH = 0; colIdx = 0; colX = START;
+        }
+        const ax = colX, ay = rowTopY;
+
+        const ctnId = `ctn_${rand()}_${ai}`;
+        items[ctnId] = {
+            type: 'container', locked: false, createdAt: now, createdBy: 'agent',
+            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 };
+        order.push(ctnId); z++;
+
+        let cy = ay + TITLE_BAR + PAD;
+        cards.forEach((c, ci) => {
+            const id = `txt_${rand()}_${ai}_${ci}`;
+            const h = measured[ci];
+            items[id] = {
+                type: 'text', locked: false, createdAt: now, createdBy: 'agent',
+                content: String(c.text), fontSize: FONT,
+                color: c.color || '#e8e8ed', border: true,
+                borderColor: c.color || 'rgba(16,185,129,0.35)',
+                fillColor: 'rgba(18,18,26,0.85)',
+                heading: !!c.heading,
+                fontWeight: c.heading ? 'bold' : 'normal', fontStyle: 'normal',
+                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 };
+            order.push(id); z++;
+            const t = firstLine(c.text).toLowerCase();
+            if (t && !titleToId.has(t)) titleToId.set(t, id);
+            cy += h + CARD_GAP;
+        });
+
+        rowMaxH = Math.max(rowMaxH, areaH);
+        colX += AREA_W + COL_GAP;
+        colIdx++;
+    });
+
+    // Connections (by card title, across all areas).
+    const REL = new Set(['leads_to', 'depends_on', 'relates_to', 'conflicts_with', 'supports', 'questions', 'costs', 'blocks']);
+    const resolve = (ref) => {
+        if (typeof ref === 'string') return titleToId.get(ref.trim().toLowerCase()) || null;
+        return null;
+    };
+    const connections = (Array.isArray(spec.connections) ? spec.connections : []).map((c, i) => {
+        const fromId = resolve(c.from), toId = resolve(c.to);
+        if (!fromId || !toId || fromId === toId) return null;
+        return {
+            id: `con_${rand()}_${i}`, fromId, toId,
+            relationship: REL.has(c.relationship) ? c.relationship : undefined,
+            label: typeof c.label === 'string' ? c.label : undefined,
+            arrowHead: true, width: 2, color: '#10b981', style: 'solid',
+        };
+    }).filter(Boolean);
+
+    const zip = new JSZip();
+    const manifest = {
+        format: 'klypix', version: 4, schemaVersion: 4, createdAt: nowIso, updatedAt: nowIso,
+        title: spec.title || 'Brain', stats: { itemCount: order.length, assetCount: 0, totalBytes: 0 },
+        sync: { enabled: false, lastSyncRev: null, lastSyncAt: null, deviceId: `dev_${rand()}${rand()}` },
+    };
+    const xs = Object.values(positions);
+    const minX = Math.min(...xs.map(p => p.x)), minY = Math.min(...xs.map(p => p.y));
+    const canvasJson = {
+        version: 4, view: { panX: 120 - minX * 0.55, panY: 120 - minY * 0.55, zoom: 0.55 },
+        order, connections, lines: [], strokes: [], nextGroupNumber: spec.areas.length + 1,
+        positions, settings: { background: '#0a0a0f' },
+    };
+    zip.file('manifest.json', JSON.stringify(manifest));
+    zip.file('canvas.json', JSON.stringify(canvasJson));
+    for (const id of order) zip.file(`items/${shard(id)}/${id}.json`, JSON.stringify(items[id]));
+    return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+}
+
+/** Render a parsed struct to the markdown brief (shared by read-klypix + MCP). */
+export function structToMarkdown(struct, { assetsDir } = {}) {
+    const L = [];
+    L.push(`# ${struct.title}`);
+    L.push(`*${struct.format} · ${struct.counts.cards} cards · ${struct.counts.connections} connections · ${struct.counts.assets} assets*\n`);
+    L.push(`## Cards`);
+    for (const c of struct.cards) {
+        L.push(`### ${c.title || `(${c.type})`}  \`${c.type}\``);
+        if (c.text) L.push(c.type === 'text' ? String(c.text).trim() : `→ ${c.text}`);
+        const meta = [];
+        if (c.links?.length) meta.push(`links: ${c.links.map(t => `[[${t}]]`).join(', ')}`);
+        if (c.tags?.length) meta.push(`tags: ${c.tags.map(t => `#${t}`).join(' ')}`);
+        if (meta.length) L.push(`\n_${meta.join(' · ')}_`);
+        L.push('');
+    }
+    if (struct.connections.length) {
+        L.push(`## Connection graph`);
+        for (const e of struct.connections) {
+            const rel = e.relationship ? ` —(${e.relationship})→ ` : ' → ';
+            L.push(`- ${e.from}${rel}${e.to}${e.label ? `  (${e.label})` : ''}`);
+        }
+        L.push('');
+    }
+    if (struct.assets.length) {
+        L.push(`## Assets (images / files)`);
+        L.push(assetsDir
+            ? `Extracted to \`${assetsDir}\` — open them to read images with vision:`
+            : `Re-run with \`--assets <dir>\` to extract these for reading:`);
+        for (const a of struct.assets) L.push(`- ${a}`);
+        L.push('');
+    }
+    return L.join('\n');
+}