klypix-mcp 1.82.2 → 1.83.0

package/bin/klypix-a2a.mjs

@@ -32,7 +32,7 @@ import crypto from 'crypto';
 import { fileURLToPath } from 'url';
 import { z } from 'zod';
 import {
-  resolveVault, resolveCanvas, getEmbedder, shouldPrewarmSemantic, cardSchema, connSchema,
+  resolveVault, resolveCanvas, getEmbedder, shouldPrewarmSemantic, cardSchema, connSchema, groupSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
   opBrainInsights, opBrainConnect, opCreateCanvas, opAddToCanvas, opBrainNote,
 } from '../src/klypix-core.mjs';
@@ -221,6 +221,7 @@ const a2aCardSchema = cardSchema.extend({
 });
 const cardsArg = z.array(a2aCardSchema).min(1).max(500);
 const connsArg = z.array(connSchema).max(1_000).optional();
+const groupsArg = z.array(groupSchema).max(100).optional();
 
 // Compatibility spellings accepted by the dispatcher but deliberately omitted
 // from the Agent Card. The smoke test asserts every switch case is either
@@ -312,7 +313,9 @@ async function runSkill(skill, args, text, via) {
       }
       const conns = connsArg.safeParse(args.connections);
       if (!conns.success) return needInput('connections must be `[{ "from": <index|title>, "to": <index|title> }]`.');
-      return await opCreateCanvas({ vault: VAULT, title: args.title ?? 'Untitled board', cards: parsed.data, connections: conns.data, filename: args.filename });
+      const groups = groupsArg.safeParse(args.groups);
+      if (!groups.success) return needInput('groups must be `[{ "title": "…", "cards": [<index|title|id>, …] }]` — cards listed in reading order.');
+      return await opCreateCanvas({ vault: VAULT, title: args.title ?? 'Untitled board', cards: parsed.data, connections: conns.data, groups: groups.data, filename: args.filename });
     }
     case 'remember':
     case 'learn_skill': {

package/bin/klypix-worker.mjs

@@ -25,7 +25,7 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
-  resolveVault, getEmbedder, shouldPrewarmSemantic, buildKlypixMap, cardSchema, connSchema,
+  resolveVault, getEmbedder, shouldPrewarmSemantic, buildKlypixMap, cardSchema, connSchema, groupSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
   opBrainTaskContext,
@@ -652,14 +652,15 @@ server.registerTool('brain_garden', {
 
 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 the KLYPIX app (Canvas → Open). Prefer short, titled cards (one idea each) connected by meaningful arrows.',
+  description: 'Create a new .klypix canvas from cards + connections and save it to the vault. The user opens it in the KLYPIX app (Canvas → Open). Prefer short, titled cards (one idea each) connected by meaningful arrows. For anything a person reads IN ORDER — steps, phases, checklists, sections — put the cards in `groups`: each group becomes a titled box with its cards stacked in the order given, boxes left-to-right; the loose grid follows arrows, not reading order, and scatters a sequence.',
   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.'),
+    cards: z.array(cardSchema).min(1).describe('The cards. 5-12 atomic cards is ideal for a mind-map; a checklist can be longer when grouped.'),
     connections: z.array(connSchema).optional().describe('Arrows between cards.'),
+    groups: z.array(groupSchema).optional().describe('Titled boxes, each listing its member cards in reading order (index, title, or id). Ungrouped cards form a band above the boxes — good for the title card, a link, a legend.'),
     filename: z.string().optional().describe('Override the output filename (without extension).'),
   },
-}, async ({ title, cards, connections, filename }) => toContent(await opCreateCanvas({ vault: mcpPresence.vault, title, cards, connections, filename })));
+}, async ({ title, cards, connections, groups, filename }) => toContent(await opCreateCanvas({ vault: mcpPresence.vault, title, cards, connections, groups, filename })));
 
 server.registerTool('add_to_canvas', {
   title: 'Add cards to an existing canvas',

package/bin/klypix-write.mjs

@@ -9,11 +9,15 @@
 //   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.
+//   { "title": "...", "cards": [{ "text": "...", "heading"?, "color"?, "group"? }],
+//     "connections": [{ "from": 0, "to": 1, "relationship"? }],
+//     "groups": [{ "title": "Part 1", "cards": [0, 1, 2], "color"?, "columns"?, "width"? }] }
+//   from/to (and group members) reference a card by INDEX, id, or its title
+//   (first line). relationship ∈ leads_to | depends_on | relates_to |
+//   conflicts_with | supports | questions | costs | blocks.
+//   groups: anything read IN ORDER (steps, phases, sections) — each becomes a
+//   titled box with its cards stacked in the order listed, boxes left-to-right.
+//   Loose cards keep the connection-driven grid, as a band above the boxes.
 
 import fs from 'fs';
 import { buildKlypix, atomicWrite } from '../src/klypix-format.mjs';
@@ -41,5 +45,6 @@ const outPath = outArg || `${(spec.title || 'untitled').replace(/[^\w\- ]+/g, ''
 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.`);
+const groupCount = Array.isArray(spec.groups) ? spec.groups.length : 0;
+console.log(`Wrote ${outPath} — ${cardCount} cards, ${connCount} connections${groupCount ? `, ${groupCount} group box${groupCount === 1 ? '' : 'es'}` : ''}.`);
 console.log(`Open it in the KLYPIX app (Canvas → Open), or verify: node scripts/read-klypix.mjs "${outPath}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.82.2",
+  "version": "1.83.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -84,7 +84,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/plan-fulfillment.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/enrichment.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/plan-fulfillment.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/enrichment.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/klypix-core.mjs

@@ -55,6 +55,7 @@ export 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.'),
+  group: z.string().optional().describe('Put this card inside the titled box of that name (created if missing), in card order. Alternative to listing it in `groups`.'),
 });
 export const connSchema = z.object({
   from: z.union([z.number(), z.string()]).describe('Source card: index (0-based), title, or id.'),
@@ -62,6 +63,17 @@ export const connSchema = z.object({
   relationship: z.string().optional().describe('leads_to|depends_on|relates_to|conflicts_with|supports|questions|costs|blocks'),
   label: z.string().optional(),
 });
+// Groups (2026-09-05): a titled box whose cards stack top-to-bottom IN THE ORDER
+// GIVEN, boxes left-to-right. The plain grid follows arrows, not reading order,
+// which scatters step 1 far from step 2 — for anything a reader follows in
+// sequence, put the cards in groups.
+export const groupSchema = z.object({
+  title: z.string().describe('Box header, e.g. "Part 1 · Get ready". Also the card\'s area.'),
+  cards: z.array(z.union([z.number(), z.string()])).min(1).describe('Member cards IN READING ORDER — index (0-based), title, or id. They stack top-to-bottom inside the box.'),
+  color: z.string().optional().describe('Hex border color for the box (default emerald).'),
+  columns: z.number().int().min(1).max(4).optional().describe('Split a long list into N columns, filled top-to-bottom then next column. Default 1 (2 when more than 12 cards).'),
+  width: z.number().int().min(200).max(640).optional().describe('Card width inside the box in px (default 340). Use ~520 for long prose cards so they do not become skyscrapers.'),
+});
 
 // ── Vault discovery / resolution ─────────────────────────────────────────────
 export const IS_CANVAS = /\.(klypix|any)$/i;
@@ -1154,21 +1166,22 @@ export async function opBrainConnect({ vault, canvas, apply = false, max = 24, t
   }, { brain: true });
 }
 
-export async function opCreateCanvas({ vault, title, cards, connections, filename }) {
+export async function opCreateCanvas({ vault, title, cards, connections, groups, filename }) {
   if (!fs.existsSync(vault)) { try { fs.mkdirSync(vault, { recursive: true }); } catch { /* ignore */ } }
   // Locked on the VAULT: safeName picks a free name by probing the directory, so
   // two concurrent creates of the same title would both see it free and the second
   // atomicWrite would silently replace the first canvas.
   return withVaultCreateLock(vault, async () => {
     try {
-      const buf = await buildKlypix({ title, cards, connections });
+      const buf = await buildKlypix({ title, cards, connections, groups });
       const name = filename ? safeName(vault, filename.replace(IS_CANVAS, '')) : safeName(vault, title);
       const out = path.join(vault, name);
       await atomicWrite(out, buf);
       let detail = '', struct;
       try { ({ struct } = await parseKlypix(buf)); detail = cardDetailBlock(struct); } catch { /* detail is optional */ }
+      const groupNote = Array.isArray(groups) && groups.length ? `, ${groups.length} group box${groups.length === 1 ? '' : 'es'}` : '';
       return {
-        blocks: [text(`Created ${out} — ${cards.length} cards, ${(connections || []).length} connections. Open it in the KLYPIX app (Canvas → Open).${detail}`)],
+        blocks: [text(`Created ${out} — ${cards.length} cards, ${(connections || []).length} connections${groupNote}. Open it in the KLYPIX app (Canvas → Open).${detail}`)],
         file: { name, buffer: buf }, struct,
       };
     } catch (e) {

package/src/klypix-format.mjs

@@ -420,10 +420,14 @@ const REL = new Set(['leads_to', 'depends_on', 'relates_to', 'conflicts_with', '
 
 /**
  * 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.
+ *   { title, cards: [{id?, type?, text, heading?, color?, group?, x?, y?, w?}],
+ *     connections: [{from, to, relationship?, label?}],
+ *     groups?: [{title, cards: [ref…], color?, columns?, width?}], layout?: {groupsPerRow?} }
+ * from/to (and group member refs) reference a card by INDEX, generated id, or
+ * its title (first line). Loose cards are content-sized and laid out on a
+ * BFS-ordered grid so linked cards land near each other. Grouped cards render
+ * inside a titled container in the ORDER LISTED, boxes left-to-right — use
+ * groups for anything read in sequence (steps, phases, sections).
  */
 export async function buildKlypix(spec) {
     if (!spec || !Array.isArray(spec.cards) || spec.cards.length === 0) {
@@ -458,14 +462,62 @@ export async function buildKlypix(spec) {
         };
     }).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);
+    // ── Groups (2026-09-05): titled boxes whose cards stack IN THE ORDER GIVEN.
+    // The BFS grid below is the right shape for a mind-map and the wrong shape
+    // for anything a person reads in sequence — the founder's 27-step App
+    // Review checklist came out with step 1 at the bottom-left, Part 2's steps
+    // scattered, and arrows crossing the whole board, because BFS follows
+    // arrows, not reading order. A group renders as a KLYPIX container (the
+    // same item shape the brain's areas use) with its member cards laid out
+    // top-to-bottom in the order the spec lists them, boxes left-to-right in
+    // spec order. Cards may also name their group inline (`group: "Part 1"`),
+    // which appends them to that box in card order. Ungrouped cards keep the
+    // BFS grid, placed as a band ABOVE the boxes (title card, links, legend).
+    const groupDefs = [];
+    const groupByKey = new Map();
+    const groupOf = new Map(); // cardId → index into groupDefs
+    const groupKey = (t) => String(t ?? '').trim().toLowerCase();
+    const ensureGroup = (g) => {
+        const key = groupKey(g.title);
+        if (!key) throw new Error('every group needs a non-empty "title"');
+        if (groupByKey.has(key)) return groupByKey.get(key);
+        const def = { title: String(g.title).trim(), color: g.color, columns: g.columns, width: g.width, kids: [], _id: `ctn_${rand()}_${groupDefs.length}` };
+        groupByKey.set(key, groupDefs.length);
+        groupDefs.push(def);
+        return groupDefs.length - 1;
+    };
+    // First membership wins — a card listed in two groups stays in the first.
+    const joinGroup = (gi, id) => { if (groupOf.has(id)) return; groupOf.set(id, gi); groupDefs[gi].kids.push(id); };
+    if (spec.groups != null && !Array.isArray(spec.groups)) throw new Error('"groups" must be an array of { title, cards: [...] }');
+    (spec.groups || []).forEach((g, gi0) => {
+        if (!g || typeof g !== 'object') throw new Error(`groups[${gi0}] must be an object with a title and cards`);
+        const gi = ensureGroup(g);
+        (Array.isArray(g.cards) ? g.cards : []).forEach((ref, ci) => {
+            const id = resolveRef(ref);
+            // Loud, not silent: a typo'd ref would otherwise drop the step out of
+            // its box onto the loose grid and the reader would never know.
+            if (!id) throw new Error(`groups[${gi0}] ("${g.title}").cards[${ci}] = ${JSON.stringify(ref)} does not match any card — use its index, id, or exact title`);
+            joinGroup(gi, id);
+        });
+    });
+    cards.forEach(c => { if (c.group != null && String(c.group).trim()) joinGroup(ensureGroup({ title: c.group }), c._id); });
+    const hasGroups = groupDefs.length > 0;
+
+    // BFS order so connected LOOSE cards land near each other. Grouped cards are
+    // excluded from both the walk and the degree count — with no groups this is
+    // byte-for-byte the previous behaviour.
+    const loose = idByIndex.filter(id => !groupOf.has(id));
+    const looseSet = new Set(loose);
+    const adj = new Map(loose.map(id => [id, []]));
+    const indeg = new Map(loose.map(id => [id, 0]));
+    for (const c of connections) {
+        if (!looseSet.has(c.fromId) || !looseSet.has(c.toId)) continue;
+        adj.get(c.fromId).push(c.toId); adj.get(c.toId).push(c.fromId);
+        indeg.set(c.toId, indeg.get(c.toId) + 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)));
+    const starts = [...loose].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];
@@ -478,11 +530,13 @@ export async function buildKlypix(spec) {
     }
 
     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 };
+    // forcedW: a grouped card takes its box's column width so the column reads
+    // as one aligned list (and so a one-line step doesn't shrink to a stub).
+    const sizeFor = (card, forcedW = null) => {
+        if (forcedW == null && 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 w = forcedW ?? Math.max(160, Math.min(360, Math.round(longest * (FONT * 0.55)) + PAD));
         // Wrap-aware height (76eea3f contract): the app renders at width w and
         // wraps at ~0.5em/char; its observer only GROWS an under-estimate, so a
         // long single-line card used to measure 40px and render 150+ → overlap.
@@ -515,6 +569,49 @@ export async function buildKlypix(spec) {
         };
     });
 
+    // Group boxes: below the loose band, left-to-right in spec order, wrapping
+    // after `layout.groupsPerRow` (default 4). Inside a box the kids fill one
+    // column top-to-bottom; a long list (>12) or an explicit `columns` splits
+    // into N columns filled column-major, so reading order survives (finish
+    // column 1, then column 2) — never the row-major/masonry orders that put
+    // step 2 beside step 1 instead of under it.
+    const containerItems = new Map(); // ctnId → item json
+    if (hasGroups) {
+        const G = { TITLE_BAR: 44, PAD: 16, GAP: 12, KID_W: 340, COL_GAP: 60, ROW_GAP: 80 };
+        const perRow = Math.max(1, Math.min(8, Math.round(Number(spec.layout?.groupsPerRow)) || 4));
+        const looseBottom = order.length ? Math.max(...order.map(id => positions[id].y + positions[id].h)) : START;
+        let gx = START, gy = order.length ? looseBottom + G.ROW_GAP : START, rowH = 0, inRow = 0;
+        for (const g of groupDefs) {
+            const n = g.kids.length;
+            const kidW = Math.max(200, Math.min(640, Math.round(Number(g.width)) || G.KID_W));
+            const gcols = Math.max(1, Math.min(4, Math.round(Number(g.columns)) || (n > 12 ? 2 : 1)));
+            const perCol = Math.max(1, Math.ceil(n / gcols));
+            const kidSizes = g.kids.map(id => sizeFor(cards[idByIndex.indexOf(id)], kidW));
+            const colHs = new Array(gcols).fill(0);
+            kidSizes.forEach((sz, i) => { colHs[Math.floor(i / perCol)] += sz.h + G.GAP; });
+            const bodyH = Math.max(0, Math.max(0, ...colHs) - G.GAP);
+            const w = G.PAD * 2 + gcols * kidW + (gcols - 1) * G.GAP;
+            const h = G.TITLE_BAR + G.PAD + bodyH + G.PAD;
+            if (inRow >= perRow) { gx = START; gy += rowH + G.ROW_GAP; rowH = 0; inRow = 0; }
+            positions[g._id] = { x: gx, y: gy, w, h, zKey: nextZKey(), zIndex: zi++, parentId: null };
+            order.push(g._id);
+            containerItems.set(g._id, {
+                type: 'container', locked: false, createdAt: now, createdBy: 'agent', ...authorField(),
+                title: g.title, collapsed: false, scopeLocked: false,
+                borderColor: (typeof g.color === 'string' && g.color.trim()) ? g.color.trim() : '#10b981',
+            });
+            const colY = new Array(gcols).fill(gy + G.TITLE_BAR + G.PAD);
+            g.kids.forEach((id, i) => {
+                const c = Math.floor(i / perCol);
+                const { w: kw, h: kh } = kidSizes[i];
+                positions[id] = { x: gx + G.PAD + c * (kidW + G.GAP), y: colY[c], w: kw, h: kh, zKey: nextZKey(), zIndex: zi++, parentId: g._id };
+                colY[c] += kh + G.GAP;
+                order.push(id);
+            });
+            gx += w + G.COL_GAP; rowH = Math.max(rowH, h); inRow++;
+        }
+    }
+
     const itemJson = (card, w) => {
         if (card.type === 'text') {
             return {
@@ -562,6 +659,7 @@ export async function buildKlypix(spec) {
     zip.file('manifest.json', JSON.stringify(manifest));
     zip.file('canvas.json', JSON.stringify(canvasJson));
     for (const id of order) {
+        if (containerItems.has(id)) { zip.file(`items/${shard(id)}/${id}.json`, JSON.stringify(containerItems.get(id))); continue; }
         const card = cards[idByIndex.indexOf(id)];
         zip.file(`items/${shard(id)}/${id}.json`, JSON.stringify(itemJson(card, positions[id]?.w)));
     }