@lovinka/vitrinka 1.1.1 → 1.5.0

package/dist/mcp.js

@@ -19,7 +19,7 @@
 // Register (user-level MCP config):
 //   claude mcp add --scope user vitrinka -- node <repo>/mcp/server.ts
 import { createInterface } from 'node:readline';
-import { readToken } from "./lib/token.js";
+import { readToken, tokenPath } from "./lib/token.js";
 import { readOperator, actorHeaderValue } from "./lib/operator.js";
 import { resolveBaseUrl } from "./lib/base-url.js";
 import { makeApi } from "./lib/http.js";
@@ -33,7 +33,7 @@ const TOKEN = readToken();
 // this side uses the MCP semantics (treatEmptyAsUnset=false).
 const OPERATOR = actorHeaderValue(readOperator(false));
 const PROTOCOL_VERSION = '2025-06-18';
-const SERVER_INFO = { name: 'vitrinka', version: '1.1.1' };
+const SERVER_INFO = { name: 'vitrinka', version: '1.4.0' };
 // ---------- HTTP helper ----------
 const rawApi = makeApi({ baseUrl: BASE_URL, token: TOKEN, operator: OPERATOR });
 // Thin shim so the existing call sites keep their (method, path, body, opts)
@@ -61,6 +61,33 @@ const TOOLS = {
         inputSchema: { type: 'object', properties: {}, additionalProperties: false },
         handler: () => api('GET', '/api/v1/projects'),
     },
+    get_project_memory: {
+        description: 'Read a project\'s memory document — the durable context (stack, conventions, decisions, gotchas) '
+            + 'maintained on the project page. ALWAYS read it before working a project\'s boards; it is the operator\'s '
+            + 'source of truth about the project.',
+        inputSchema: {
+            type: 'object',
+            properties: { project: selectorProps.project },
+            required: ['project'],
+            additionalProperties: false,
+        },
+        handler: (a) => api('GET', `/api/v1/projects/${seg(a.project)}/memory`),
+    },
+    save_project_memory: {
+        description: 'Replace a project\'s memory document (markdown, ≤64 KiB). Fetch the current body first and edit '
+            + 'surgically — this overwrites the whole document. Use for durable facts worth every future session knowing, '
+            + 'never for conversation-scoped notes.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: selectorProps.project,
+                body: { type: 'string', description: 'The full new markdown body' },
+            },
+            required: ['project', 'body'],
+            additionalProperties: false,
+        },
+        handler: (a) => api('PUT', `/api/v1/projects/${seg(a.project)}/memory`, { body: a.body }),
+    },
     list_sets: {
         description: 'List the artifact sets of a project (all branches) or of one branch — newest first, without file lists. Each set has a share URL, version, key, optional custom name and title.',
         inputSchema: {
@@ -81,6 +108,45 @@ const TOOLS = {
         },
         handler: (a) => api('GET', `/api/v1/sets/${seg(a.project)}/${seg(a.branch)}/${seg(a.selector)}`),
     },
+    search_shots: {
+        description: 'Search the cross-set screens library (shot index): every ingested screenshot, filterable by '
+            + 'project / journey / surface / branch / kind, free text over route·note·title·label (FTS prefix match), '
+            + 'and a time range. Default mode returns the NEWEST shot per screen (history = older occurrences, '
+            + 'fetch them via the returned screenKey at GET /api/v1/library/screen); all=true returns every occurrence. '
+            + 'Use this to pull screens onto boards, e.g. "all marketplace_pro screens" or the "inquiry" journey.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: selectorProps.project,
+                journey: { type: 'string', description: 'Journey tag, e.g. "inquiry" (case-insensitive; from manifest per-shot journey or the set journey title)' },
+                surface: { type: 'string', description: 'Capture surface, e.g. "ios", "web"' },
+                branch: { ...selectorProps.branch, description: 'Branch slug filter' },
+                kind: { type: 'string', description: 'Set kind filter (default sets are "screenshots")' },
+                q: { type: 'string', description: 'Free text over route, note, title, label, journey' },
+                since: { type: 'string', description: 'Inclusive RFC 3339 lower bound on capture ts' },
+                until: { type: 'string', description: 'Exclusive RFC 3339 upper bound on capture ts' },
+                all: { type: 'boolean', description: 'true = every occurrence flat; default false = newest per screen' },
+                limit: { type: 'number', description: 'Max results (default 200, cap 1000)' },
+                offset: { type: 'number', description: 'Pagination offset' },
+            },
+            additionalProperties: false,
+        },
+        handler: (a) => {
+            const p = new URLSearchParams();
+            for (const k of ['project', 'journey', 'surface', 'branch', 'kind', 'q', 'since', 'until']) {
+                if (a[k])
+                    p.set(k, String(a[k]));
+            }
+            if (a.all)
+                p.set('all', '1');
+            if (a.limit)
+                p.set('limit', String(a.limit));
+            if (a.offset)
+                p.set('offset', String(a.offset));
+            const qs = p.toString();
+            return api('GET', '/api/v1/library' + (qs ? '?' + qs : ''));
+        },
+    },
     rename_set: {
         description: 'Set (or change) the custom URL-addressable name of a set — e.g. name fixit/main v2 "payout-flow" so https://…/fixit/main/payout-flow resolves. Pass an empty name to clear it. Requires VITRINKA_TOKEN.',
         inputSchema: {
@@ -115,6 +181,47 @@ const TOOLS = {
             return api('PATCH', `/api/v1/sets/${seg(a.project)}/${seg(a.branch)}/${seg(a.selector)}`, patch);
         },
     },
+    list_components: {
+        description: 'List a project\'s indexed UI components — compact rows (library, name, kind, one-line '
+            + 'summary). LOAD THIS BEFORE MOCKING a project\'s UI so artifact mockups use its real component '
+            + 'vocabulary (names, variants, tokens) instead of inventing one. Monorepos have several libraries '
+            + '(e.g. "expo" vs "web") — filter with library. Empty = the project has not run '
+            + '`vitrinka index-components` yet.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: { type: 'string', description: 'Project slug, e.g. "fixit"' },
+                library: { type: 'string', description: 'One UI kit only, e.g. "web"' },
+                query: { type: 'string', description: 'Substring filter over name + summary' },
+            },
+            required: ['project'],
+            additionalProperties: false,
+        },
+        handler: (a) => {
+            const q = new URLSearchParams();
+            if (a.library)
+                q.set('library', String(a.library));
+            if (a.query)
+                q.set('q', String(a.query));
+            const qs = q.toString();
+            return api('GET', `/api/v1/projects/${seg(a.project)}/components${qs ? '?' + qs : ''}`);
+        },
+    },
+    get_component: {
+        description: 'One indexed component in full: props (names/types), variant vocabulary, summary, source '
+            + 'path. Use after list_components when a mockup needs the exact prop shape.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: { type: 'string' },
+                library: { type: 'string' },
+                name: { type: 'string' },
+            },
+            required: ['project', 'library', 'name'],
+            additionalProperties: false,
+        },
+        handler: (a) => api('GET', `/api/v1/projects/${seg(a.project)}/components?library=${seg(a.library)}&name=${seg(a.name)}`),
+    },
     // ---- annotation-board work queue (design 2026-07-04) ----
     //
     // The agent loop: list_work → set_status working → fix the app →
@@ -122,21 +229,27 @@ const TOOLS = {
     // reply → set_status in_review. Only the USER resolves (accept in the
     // board UI); never set status "resolved" yourself.
     list_boards: {
-        description: 'List the annotation boards (Freeform-style canvases over screenshot sets). Each has a slug, title and URL.',
-        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-        handler: () => api('GET', '/api/v1/boards'),
+        description: 'List the annotation boards (Freeform-style canvases over screenshot sets). Each has a slug, title, owning project and URL. Optionally filter to one project.',
+        inputSchema: {
+            type: 'object',
+            properties: { project: { type: 'string', description: 'Only boards of this project (e.g. "fixit"); omit for all' } },
+            additionalProperties: false,
+        },
+        handler: (a) => api('GET', `/api/v1/boards${a.project ? `?project=${seg(a.project)}` : ''}`),
     },
     ask_board: {
-        description: 'Ask the operator a first-class multiple-choice question on a board — rendered as one-click pills, optionally anchored to a card. The answer returns on the work wire as a {type:"choice"} item (wait_for_work), so this is how you let the user "pick B" in one click instead of prose. An "Other / Něco jiného" free-text escape is always added by the engine, so pass only the real options — never hard-block off-vocabulary answers. Stamps the operator as X-Board-Actor.',
+        description: 'Ask the operator a first-class multiple-choice question on a board — rendered as one-click pills, optionally anchored to a card. The answer is STAGED on the board until the operator presses "Send to Claude", then returns on the work wire as a {type:"choice"} item (wait_for_work) — so answers may arrive in a batch, not per click. You can also poll GET /api/v1/boards/{slug}/questions to see staged/answered state without holding the wire. This is how you let the user "pick B" in one click instead of prose. An "Other / Něco jiného" free-text escape is always added by the engine, so pass only the real options — never hard-block off-vocabulary answers. Stamps the operator as X-Board-Actor.',
         inputSchema: {
             type: 'object',
             properties: {
                 board: { type: 'string', description: 'Board slug (from list_boards)' },
                 prompt: { type: 'string', description: 'The question' },
                 options: {
-                    type: 'array', items: { type: 'string' },
-                    description: '1-12 answer options (the "Other" escape is appended automatically)',
+                    type: 'array',
+                    items: { anyOf: [{ type: 'string' }, { type: 'object', properties: { label: { type: 'string' }, hint: { type: 'string' }, recommended: { type: 'boolean' } }, required: ['label'], additionalProperties: false }] },
+                    description: '1-12 answer options — strings, or {label, hint?, recommended?} to carry tradeoffs (hint shows on hover, recommended gets a hairline mark). The "Other" escape is appended automatically.',
                 },
+                multiSelect: { type: 'boolean', description: 'Allow picking several options; the choice item then carries options: [labels] (default false)' },
                 cardId: { type: 'number', description: 'Optional card id to anchor the question to (omit for a board-level question)' },
             },
             required: ['board', 'prompt', 'options'],
@@ -144,22 +257,279 @@ const TOOLS = {
         },
         handler: (a) => api('POST', `/api/v1/boards/${seg(a.board)}/questions`, {
             prompt: String(a.prompt),
-            options: Array.isArray(a.options) ? a.options.map(String) : [],
+            options: Array.isArray(a.options) ? a.options : [],
+            ...(a.multiSelect ? { multiSelect: true } : {}),
             ...(a.cardId !== undefined ? { cardId: Number(a.cardId) } : {}),
         }),
     },
+    compose_board: {
+        description: 'Place a BATCH of AI-authored content on a board in one call — text blocks, notes, '
+            + 'shapes and questions, wired together. This is how you present ideas, decision maps and '
+            + 'brainstorm notes visually. Batch-or-bust: compose the whole thought in ONE call (never one '
+            + 'card per call); the server owns geometry (layout modes, no coordinates) and GUARANTEES the '
+            + 'batch lands in FREE space — an occupancy scan places it near your intent (anchor/section) '
+            + 'without ever overlapping existing cards, so express flow and order, never positions. '
+            + 'Everything appears live at once. Cards land on the toggleable "✦ eve" layer. Give cards a "ref" so edges/questions '
+            + 'in the same call can reference them. All-or-nothing: on 400 the error carries {code,index} '
+            + 'pointing at the bad item and nothing was placed. DEEP COMPOSITION: frames NEST — a cluster/'
+            + 'section may list other frames in "children" (max depth 5), and any frame may carry '
+            + 'payload.layout {mode, gap, cols, padding} to OWN its inner flow forever (the server reflows '
+            + 'it recursively on every change — one call renders a whole laid-out tree). TEMPLATES: pass '
+            + '{template: "name", params: {slot: "value"}} to instantiate a registry template (save_template '
+            + 'creates them; get_templates lists them) — its cards/edges/questions land first, then any '
+            + 'inline ones; {{slot}} placeholders substitute from params.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                board: { type: 'string', description: 'Board slug (from list_boards)' },
+                layout: { type: 'string', enum: ['column', 'row', 'grid'], description: 'How the batch flows: column (default — reading order), row, or grid (3 per row)' },
+                anchorCardId: { type: 'number', description: 'Place the batch beside this existing card (omit for free space beside the board)' },
+                section: { type: 'string', description: 'Journey section name (see scrape_board sections[]): the batch lands INSIDE that frame, below its existing content, and the frame grows to fit. Mutually exclusive with anchorCardId and journey.' },
+                journey: { type: 'string', description: 'Pass-chain key ("checkout"): target a journey\'s ITERATION chain instead of a named section. Alone = the batch lands in the chain\'s LATEST pass (creates pass 1 if none — a plain section whose title matches is adopted as pass 1). This is THE way to present round 2/3 of a journey: one call opens the next pass and fills it.' },
+                pass: { anyOf: [{ type: 'string', enum: ['next'] }, { type: 'number' }], description: 'With journey: "next" CREATES the next pass section (auto-named "Checkout — pass N", placed beside pass N−1, layout inherited) and fills it in this same call; a number targets that existing pass. Omit = latest.' },
+                template: { type: 'string', description: 'Registry template name (save_template / get_templates): its cards/edges/questions are instantiated FIRST, then any inline ones — one call renders the whole skeleton' },
+                params: { type: 'object', description: 'Template {{slot}} substitutions, e.g. {version: "2.4"}; unfilled slots render literally' },
+                cards: {
+                    type: 'array',
+                    description: 'Up to 60 cards. kind "text": payload {md, role: idea|note|pro|con|risk|heading|caption} — markdown (#/##/### **bold** `code` - lists). kind "note": payload {text}. kind "shape": payload {shape: rect|ellipse, color}. kind "viz": payload {viz, data, title?} — data-only visualizations: table {cols,rows}, matrix {x:[lo,hi],y:[lo,hi],points:[{label,x,y}] with x/y in 0..1}, flow {steps:[label]}, bars {items:[{label,value}]}, timeline {items:[{label,when}]}, line {series:[{label,points:[numbers]}], x?:[labels]} — a chart, stat {items:[{label,value,delta?,unit?}]} — KPI stat boxes. kind "cluster": payload {title} — a frame; list member refs in "children" and they are laid out inside it. kind "section": payload {title} — a NAMED JOURNEY FRAME ("Onboarding", "Checkout"): always visible (not on the ✦ eve layer), auto-indexed (pill navigation + scrape sections[]), membership is spatial — cards inside it belong to it; "children" lays the listed refs out inside. Also use a section to present the NEXT ITERATION of a journey ("Checkout — iteration 2") as its own frame beside the original — never mix a new take into the old section. UI CORE ELEMENTS (data-only, ~100-300 tokens each): kind "step" {n?, title, note?, status: todo|pass|fail, cardId?} — a numbered journey step; cardId references an EXISTING shot card for a live thumbnail (never re-upload a screen you can reference). kind "callout" {tone: info|warn|success|decision, md}. kind "checklist" {title?, items:[{text, done?}]} — interactive, users tick items live (state persists on the card). kind "compare" {a:{cardId}, b:{cardId}, mode: wipe|ghost} — two existing cards\' faces behind a wipe/ghost slider (iteration pixel-diff). Kanban: a cluster with payload {title, role:"kanban"} renders as a status column. Any card may carry payload.lane (e.g. "iphone") — the arrange/auto-layout \'lanes\' mode groups rows by it. kind "wireframe" {title?, device: phone|tablet|web, fidelity?: lo|tokens, nodes:[{t, label?, …}]} — a ~100-250-token LO-FI UI MOCKUP (the cheap alternative to an HTML artifact; use it to SKETCH proposed screens): nodes render top-to-bottom inside a device frame; t: nav {label}, tabbar {label: "home · search · profile"}, heading {label}, text {label? — omit for gray placeholder lines}, button {label, primary?}, input {label = placeholder}, img {h: s|m|l — crossed placeholder box}, list {n: rows}, listitem {label?}, divider, chiprow {label: "a, b, c"}, modal {label}; unknown t renders as a labeled dashed box. fidelity defaults "lo" (sketchy gray — the brainstorming register); "tokens" tints primaries. kind "doc" {title?, nodes:[{t, …}]} — a declarative node DOCUMENT in ONE card (~300 tokens for a dense dashboard): containers t: row|col {nodes:[…]} nest freely; content leaves t: heading|text {md}, stat|bars|table|line|timeline|flow|matrix (same data shape as the viz kinds, inline), checklist {items:[{text,done?}]} (static), img, divider; inner nodes are pixels (not annotatable) — use real cards when structure matters. FRAME NESTING: cluster/section children may include other frames (depth ≤5), and any frame payload may carry layout {mode: column|row|grid|flow|lanes|masonry, gap: S|M|L|px, cols, padding} — the server then owns that frame\'s inner flow recursively, forever. kind "link" {url, mode?: preview|phone|widget|live} — a WEBSITE card: the server unfurls title/og:metadata/favicon async, probes iframe embeddability, and (when the capture sidecar is configured) takes real 16:10 desktop + phone-viewport screenshots; preview = 16:10 face, phone = mobile frame, widget = compact favicon+title row with hover peek, live = embedded iframe when the site allows framing. kind "board" {board: "<slug>", title?} — a PORTAL card: a live minimap window into another board (click-through, card/open-thread counts); the target board must exist, self-portals 400. Optional w/h override the per-kind default footprint.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            ref: { type: 'string', description: 'Batch-local handle for edges/questions/children (e.g. "idea1")' },
+                            children: { type: 'array', items: { type: 'string' }, description: 'cluster/section only: refs of batch cards to lay out inside this frame — INCLUDING other frames (nesting, max depth 5)' },
+                            kind: { type: 'string', description: 'text|note|shape|viz|cluster|section|step|callout|checklist|compare|wireframe|doc|link|board — OPEN vocabulary: the server validates; an unknown kind 400s with the full allowed list, so new kinds work without a schema update' },
+                            payload: { type: 'object', description: 'Kind-specific payload (see cards description)' },
+                            w: { type: 'number' }, h: { type: 'number' },
+                        },
+                        required: ['kind', 'payload'],
+                        additionalProperties: false,
+                    },
+                },
+                edges: {
+                    type: 'array',
+                    description: 'Up to 40 wires between cards. from/to: a ref string from this batch, or an existing card id (number).',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            from: { description: 'Card ref (string) or existing card id (number)' },
+                            to: { description: 'Card ref (string) or existing card id (number)' },
+                            label: { type: 'string' },
+                        },
+                        required: ['from', 'to'],
+                        additionalProperties: false,
+                    },
+                },
+                questions: {
+                    type: 'array',
+                    description: 'Up to 12 questions, optionally anchored to a batch card (cardRef) or existing card (cardId). Same staged-answer mechanics as ask_board.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            prompt: { type: 'string' },
+                            options: { type: 'array', items: { anyOf: [{ type: 'string' }, { type: 'object', properties: { label: { type: 'string' }, hint: { type: 'string' }, recommended: { type: 'boolean' } }, required: ['label'], additionalProperties: false }] }, description: '1-12 options — strings or {label, hint?, recommended?} (the "Other" escape is appended automatically)' },
+                            multiSelect: { type: 'boolean' },
+                            cardRef: { type: 'string' },
+                            cardId: { type: 'number' },
+                        },
+                        required: ['prompt', 'options'],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ['board'],
+            additionalProperties: false,
+        },
+        handler: (a) => api('POST', `/api/v1/boards/${seg(a.board)}/compose`, {
+            ...(a.layout ? { layout: String(a.layout) } : {}),
+            ...(a.section ? { section: String(a.section) } : {}),
+            ...(a.journey ? { journey: String(a.journey) } : {}),
+            ...(a.pass !== undefined ? { pass: a.pass } : {}),
+            ...(a.anchorCardId !== undefined ? { anchor: { cardId: Number(a.anchorCardId) } } : {}),
+            ...(a.template ? { template: String(a.template) } : {}),
+            ...(a.params ? { params: a.params } : {}),
+            cards: Array.isArray(a.cards) ? a.cards : [],
+            edges: Array.isArray(a.edges) ? a.edges : [],
+            questions: Array.isArray(a.questions) ? a.questions : [],
+        }),
+    },
+    save_template: {
+        description: 'Save a REUSABLE board template into the registry (upsert by name). Two modes: '
+            + 'pass body {cards, edges?, questions?} (compose-shaped, {{slot}} placeholders in any string '
+            + 'payload field become instantiation params) — or pass board + section to EXTRACT a live '
+            + 'section\'s whole subtree (nested frames, layouts, children) as the skeleton. Instantiate '
+            + 'later with compose_board {template, params}; get_templates lists the registry. Blob-backed '
+            + 'cards (shots/media/artifacts) are skipped on extraction — reference them at instantiation '
+            + 'time instead.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Registry key — a slug (a-z, 0-9, dashes, ≤64); saving again overwrites' },
+                title: { type: 'string', description: 'Human title shown in listings' },
+                body: { type: 'object', description: 'Compose-shaped subtree {cards, edges?, questions?} with {{slot}} placeholders. Mutually exclusive with board+section.' },
+                board: { type: 'string', description: 'With section: extract from this board (slug)' },
+                section: { type: 'string', description: 'With board: the journey section name whose subtree becomes the template' },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        },
+        handler: (a) => api('POST', '/api/v1/templates', {
+            name: String(a.name),
+            ...(a.title ? { title: String(a.title) } : {}),
+            ...(a.body ? { body: a.body } : {}),
+            ...(a.board ? { board: String(a.board) } : {}),
+            ...(a.section ? { section: String(a.section) } : {}),
+        }),
+    },
+    arrange: {
+        description: 'Auto-align board cards server-side — the LAYOUT ENGINE: geometry is computed in Go, '
+            + 'costs you zero tokens, snaps to the board lattice and lands as ONE atomic layout event that '
+            + 'returns every card\'s final bounds. Never do pixel math yourself — express intent with the '
+            + 'knobs (gap/padding "S"|"M"|"L" or px, cols, sizing uniform). Default scope is the AI '
+            + 'expression layer; scope "all" tidies everything; scope "section:<Name>" reflows one journey '
+            + 'section INSIDE its frame (which grows to fit); ids picks specific cards. Modes: column, row, '
+            + 'grid (cols per row), flow (row-wrap at the section\'s inner width), lanes (payload.lane rows — '
+            + 'journey steps × variants), masonry (column-balanced mixed heights), timeline (creation order), '
+            + 'timeaxis (one row positioned PROPORTIONALLY by real creation time — activity history with time ticks), '
+            + 'compare (sections: ["A","B"] side-by-side, members row-aligned pairwise — iterations), '
+            + 'align-left, align-top, distribute-h, distribute-v. AUTO-LAYOUT: pass save:true with a section '
+            + 'scope to PERSIST the layout onto the section — the server then re-flows it automatically on '
+            + 'every change (one arrange call, tidy forever; prefer this over repeated arrange calls).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                board: { type: 'string', description: 'Board slug' },
+                mode: { type: 'string', description: 'column|row|grid|flow|lanes|masonry|timeline|timeaxis|compare|align-left|align-top|distribute-h|distribute-v — open vocabulary, server-validated (unknown mode 400s with the list)' },
+                save: { type: 'boolean', description: 'With a section scope: persist this layout onto the section (payload.layout) so the server auto-reflows it on every future change' },
+                sections: { type: 'array', items: { type: 'string' }, description: 'mode "compare" only: exactly two section names to align side-by-side' },
+                scope: { type: 'string', description: 'Which cards move: "ai" (default — the expression layer), "all", or "section:<Name>" (that journey\'s members, arranged inside the frame)' },
+                ids: { type: 'array', items: { type: 'number' }, description: 'Explicit card ids; overrides scope' },
+                gap: { anyOf: [{ type: 'string', enum: ['S', 'M', 'L'] }, { type: 'number' }], description: 'Spacing between cards: S (12), M (24, default), L (48) or explicit px 0-400' },
+                padding: { anyOf: [{ type: 'string', enum: ['S', 'M', 'L'] }, { type: 'number' }], description: 'Frame inner padding when scoped to a section (default 24)' },
+                cols: { type: 'number', description: 'grid mode: cards per row (default 3)' },
+                sizing: { type: 'string', enum: ['natural', 'uniform'], description: 'uniform = every card takes the selection\'s max footprint (even rows); default natural' },
+            },
+            required: ['board', 'mode'],
+            additionalProperties: false,
+        },
+        handler: (a) => api('POST', `/api/v1/boards/${seg(a.board)}/arrange`, {
+            mode: String(a.mode),
+            ...(a.scope ? { scope: String(a.scope) } : {}),
+            ...(Array.isArray(a.ids) && a.ids.length ? { ids: a.ids.map(Number) } : {}),
+            ...(a.gap !== undefined ? { gap: a.gap } : {}),
+            ...(a.padding !== undefined ? { padding: a.padding } : {}),
+            ...(a.cols !== undefined ? { cols: Number(a.cols) } : {}),
+            ...(a.sizing ? { sizing: String(a.sizing) } : {}),
+            ...(a.save ? { save: true } : {}),
+            ...(Array.isArray(a.sections) && a.sections.length ? { sections: a.sections.map(String) } : {}),
+        }),
+    },
+    update_cards: {
+        description: 'Batch-edit YOUR OWN board layer — patch payload/geometry or remove cards you '
+            + 'composed. Restricted to AI-layer cards (payload.layer "ai") plus section frames (shared '
+            + 'journey structure — rename/resize/remove is allowed; removing a frame never deletes its '
+            + 'members): the user\'s shots and notes are untouchable, a non-AI target 403s with '
+            + '{code:"not_ai_layer"}. Use it to refine a brainstorm in place (reword a text card, retitle '
+            + 'a cluster or section, drop a dead idea) instead of composing duplicates. Removals are SOFT '
+            + '— trashed, never fully deleted: restore lifts your trashed cards back (GET '
+            + '/api/v1/boards/{slug}/trash lists them; the response of a remove is your undo handle).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                board: { type: 'string', description: 'Board slug' },
+                patch: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'number' },
+                            payload: { type: 'object', description: 'Replacement payload (the "layer" marker is preserved automatically)' },
+                            x: { type: 'number' }, y: { type: 'number' }, w: { type: 'number' }, h: { type: 'number' },
+                        },
+                        required: ['id'],
+                        additionalProperties: false,
+                    },
+                },
+                remove: { type: 'array', items: { type: 'number' }, description: 'Card ids to TRASH (AI layer only; soft delete — restorable)' },
+                restore: { type: 'array', items: { type: 'number' }, description: 'Trashed card ids to lift back onto the board (AI layer only)' },
+            },
+            required: ['board'],
+            additionalProperties: false,
+        },
+        handler: (a) => api('POST', `/api/v1/boards/${seg(a.board)}/update-cards`, {
+            patch: Array.isArray(a.patch) ? a.patch : [],
+            remove: Array.isArray(a.remove) ? a.remove : [],
+            ...(Array.isArray(a.restore) && a.restore.length ? { restore: a.restore.map(Number) } : {}),
+        }),
+    },
     scrape_board: {
-        description: 'Read a WHOLE board as one structured testing digest — every media image (URL), note text and annotation — with the connect-tool edges walked into ordered journey chains ("flow": [[A,B,C]]). Use this to process a testing session end-to-end (pasted screenshots + notes) rather than acting on one annotation at a time; the flow tells you the user\'s step order. Images are absolute URLs (no auth on the mesh) — fetch them to SEE each step.',
+        description: 'Read a WHOLE board as one structured testing digest — every media image (URL), note text and annotation — with the connect-tool edges walked into ordered journey chains ("flow": [[A,B,C]]) and the journey sections summarized in "sections": [{name, cards, bounds, order, journey?, pass?}] plus "journeys": [{journey, passes, latest}] (the pass-chain orientation map). Pass section to ISOLATE the digest to one journey ("Checkout") — the scoped read for section-focused work. Each card carries its containing "section" name. Images are absolute URLs (no auth on the mesh) — fetch them to SEE each step.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: 'Board slug (from list_boards)' },
+                section: { type: 'string', description: 'Journey section name — digest only that frame\'s members (404 if no such section)' },
+                diff: { type: 'array', items: { type: 'string' }, description: 'Exactly two section names — the ITERATION DIFF: members matched pairwise (same file, then reading order) as {pairs:[{a,b}]} plus unpaired leftovers. Mutually exclusive with section.' },
+            },
+            required: ['slug'],
+            additionalProperties: false,
+        },
+        handler: (a) => {
+            const q = new URLSearchParams();
+            if (a.section)
+                q.set('section', String(a.section));
+            if (Array.isArray(a.diff) && a.diff.length === 2)
+                q.set('diff', a.diff.map(String).join(','));
+            const qs = q.toString();
+            return api('GET', `/api/v1/boards/${seg(a.slug)}/scrape${qs ? `?${qs}` : ''}`);
+        },
+    },
+    list_sections: {
+        description: 'The automatic journey-section index of a board: every section (name, bounds, member card count, reading order, journey/pass when part of an iteration chain) PLUS "journeys": [{journey, title, passes, latest}] — the one-call orientation on "checkout has 3 passes, latest is pass 3". Cheaper than scrape_board when you only need the map of journeys — e.g. to pick a section for compose_board/arrange/scrape_board scoping or request_review, or a journey key for compose_board {journey, pass}.',
         inputSchema: {
             type: 'object',
-            properties: { slug: { type: 'string', description: 'Board slug (from list_boards)' } },
+            properties: { slug: { type: 'string', description: 'Board slug' } },
             required: ['slug'],
             additionalProperties: false,
         },
-        handler: (a) => api('GET', `/api/v1/boards/${seg(a.slug)}/scrape`),
+        handler: (a) => api('GET', `/api/v1/boards/${seg(a.slug)}/sections`),
+    },
+    get_templates: {
+        description: 'The board template library: the built-in markdown skeletons (QA session, iteration review, decision map, metrics dashboard, presentation deck, kanban triage) PLUS the saved REGISTRY templates (created with save_template, instantiable via compose_board {template, params} — each listed with its {{param}} slots). Fetch ONCE before structuring a new board and start from a matching template instead of inventing structure.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async () => {
+            const md = await api('GET', '/static/templates.md', undefined, { raw: true });
+            const reg = await api('GET', '/api/v1/templates');
+            const list = (reg.status === 200 && reg.body && Array.isArray(reg.body.templates))
+                ? reg.body.templates : [];
+            if (md.status !== 200 || typeof md.body !== 'string' || list.length === 0) {
+                return md;
+            }
+            const lines = list.map((t) => `- **${t.name}**${t.title ? ` — ${t.title}` : ''}${t.params?.length ? ` · params: ${t.params.map((p) => `{{${p}}}`).join(' ')}` : ''}`);
+            return {
+                status: 200,
+                body: md.body + '\n\n---\n\n## Saved registry templates\n\nInstantiate with `compose_board {template: "<name>", params: {…}}`.\n\n' + lines.join('\n') + '\n',
+            };
+        },
+    },
+    request_review: {
+        description: 'Manually trigger an AI review pass on a board (needs the board\'s ai-review toggle ON), optionally scoped to one journey section — "review the Checkout journey" — or to a PASS CHAIN via journey: reviews the chain\'s LATEST pass with the previous pass attached as reviewer context, so the reviewer sees what changed between iterations. Returns the created pass; findings stream to the board\'s AI BOARD tab as eve completes. 409 = review off or a pass already running; 422 = no reviewable shot cards in scope.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                board: { type: 'string', description: 'Board slug' },
+                section: { type: 'string', description: 'Journey section name to scope the pass to (omit = whole board). Mutually exclusive with journey.' },
+                journey: { type: 'string', description: 'Pass-chain key (see list_sections journeys[]): review the LATEST pass with the previous pass as context' },
+            },
+            required: ['board'],
+            additionalProperties: false,
+        },
+        handler: (a) => api('POST', `/api/v1/boards/${seg(a.board)}/review-passes`, {
+            ...(a.section ? { section: String(a.section) } : {}),
+            ...(a.journey ? { journey: String(a.journey) } : {}),
+        }),
     },
     wait_for_work: {
-        description: 'BLOCK until annotation work exists — the continuous-work tool (board-v3). Long-polls the server: costs nothing while idle, returns up to 3 ready-to-act markdown capsules the instant the user annotates (or re-queues). {"idle":true} means the window elapsed quietly — simply call it again. Scope to just your session\'s work with project + branch (or a board slug). A listening session (/vitrinka:listen) loops on this forever.',
+        description: 'BLOCK until annotation work exists — the continuous-work tool (board-v3). Long-polls the server: costs nothing while idle, returns up to 3 ready-to-act markdown capsules the instant the user annotates (or re-queues). {"idle":true} means the window elapsed quietly — simply call it again. ALWAYS SCOPE to just your session\'s work: pass project + branch (or a board slug) — unscoped waits pick up other boards\' and other sessions\' items. A listening session (/vitrinka:listen) loops on this forever, scoped the same way its monitor is.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -193,7 +563,7 @@ const TOOLS = {
         handler: (a) => api('GET', `/api/v1/annotations/${seg(a.id)}/capsule`, undefined, { raw: true }),
     },
     list_work: {
-        description: 'List annotation work items (the agent queue), FIFO. Each item: id, board, intent (fix|investigate|refactor|redesign|other), prompt, source set ref + file, crop URL. Filter by status (open = waiting for an agent), board slug, and/or project + branch (scope to your repo+branch). Start here.',
+        description: 'List annotation work items (the agent queue), FIFO. Each item: id, board, intent (fix|investigate|refactor|redesign|reshoot|other; reshoot = NO code changes — just re-capture the screen per the capsule protocol and attach_after), prompt, source set ref + file, crop URL. ALWAYS SCOPE: pass board (slug) or project + branch (your repo+branch) — an unscoped call is the global firehose across every board and returns other sessions\' backlogs, which are NOT yours to work. Filter by status (open = waiting for an agent). Start here — scoped.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -219,7 +589,7 @@ const TOOLS = {
         },
     },
     get_annotation: {
-        description: 'Get one annotation\'s full brief: region, intent, prompt revisions, thread messages (incl. file attachments the user added — fetch their URLs), fix attempts (before/after history), the element context (elements: E-numbers the region overlaps + screen siblings) and its card\'s source set. Fetch the cropUrl (PNG, no auth on the mesh) to SEE the annotated region — user markup strokes are baked in.',
+        description: 'Get one annotation\'s full brief: region, intent, prompt revisions, thread messages (incl. file attachments the user added — fetch their URLs), fix attempts (before/after history), explicit references (refs: the prompt\'s ⌖E tokens — elements the USER deliberately pointed at, each with its own cropUrl; treat them as intent, ranked above the implicit context), the element context (elements: E-numbers the region overlaps + screen siblings) and its card\'s source set. Fetch the cropUrl (PNG, no auth on the mesh) to SEE the annotated region — user markup strokes are baked in; fetch each ref\'s cropUrl to SEE what its ⌖E token points at (image-less targets like notes carry no crop).',
         inputSchema: {
             type: 'object',
             properties: { id: { type: 'number', description: 'Annotation id (from list_work)' } },
@@ -330,9 +700,41 @@ async function handle(msg) {
                     + 'the flow board (vitrinka board-from-set) and hand the user the /boards/<slug> URL as the '
                     + 'primary link; set/share pages are the archive behind it. Boards are live and interactive: '
                     + 'the user annotates regions and thread replies route to claude by default (@eve only when '
-                    + 'explicitly mentioned) — a session in the app repo keeps listening via /vitrinka:listen, which '
-                    + 'arms a native background monitor (`vitrinka watch`) that re-invokes the session on each new '
-                    + 'annotation (zero-token idle); the session then drains the queue via wait_for_work.',
+                    + 'explicitly mentioned) — after publishing a board, the session in the app repo attaches the '
+                    + 'listener AUTOMATICALLY (no need to offer or wait to be asked): follow '
+                    + '~/.claude/skills/vitrinka/listen/SKILL.md, which arms a native background monitor '
+                    + '(`vitrinka watch`) that re-invokes the session on each new annotation (zero-token idle); '
+                    + 'the session then drains the queue via wait_for_work. /vitrinka:listen (re)arms it manually. '
+                    + 'WORK SCOPE: a working session cares ONLY about its own board\'s (or repo+branch\'s) '
+                    + 'annotations — always pass {board} or {project, branch} to list_work and wait_for_work, '
+                    + 'and never act on items from other boards that an unscoped call surfaces; those belong '
+                    + 'to other sessions\' queues. '
+                    + 'BOARD VOCABULARY (ai-expression-layer): you can PRESENT on boards, not just answer. '
+                    + 'compose_board places a whole thought in ONE call — markdown text cards (roles: '
+                    + 'heading/idea/pro/con/risk), data-only viz cards (table/matrix/flow/bars/timeline — '
+                    + 'always cheaper than an HTML artifact), cluster frames grouping a direction, wires, and '
+                    + 'anchored multiple-choice questions (options carry {label,hint,recommended}; answers '
+                    + 'arrive staged as choice items). Batch-or-bust: never place cards one call at a time. '
+                    + 'Never send coordinates — express INTENT (anchor, section, layout mode, order) and the server '
+                    + 'guarantees collision-free placement near it (occupancy scan) plus geometry-true image '
+                    + 'aspect (uniform sizing never squishes a screenshot). Pick a layout (column/row/grid) '
+                    + 'and use arrange to tidy. Every mutation is undoable server-side per actor: your '
+                    + 'compose/arrange batches group into single steps on YOUR stack (POST '
+                    + '/api/v1/boards/{slug}/undo reverts your last batch if you mis-compose; the user\'s '
+                    + '⌘Z never touches your work). '
+                    + 'JOURNEY SECTIONS: name board regions after customer journeys with kind "section" frames '
+                    + '("Onboarding", "Checkout") — they are always visible, auto-indexed (list_sections, pill '
+                    + 'navigation, scrape_board sections[]), and every tool scopes to them: compose_board '
+                    + '{section}, arrange {scope:"section:Name"} with gap/padding/cols knobs, scrape_board '
+                    + '{section} for an isolated digest, request_review {section} for a scoped AI review pass. '
+                    + 'Sections are also the ITERATION surface: when you produce the next take on a journey '
+                    + '(reworked screens, a redesign, round 2 of a flow), present it as its OWN section beside '
+                    + 'the current one ("Checkout — iteration 2") instead of mixing cards into the original — '
+                    + 'iterations then sit side by side, each pill-navigable, separately scrapeable and '
+                    + 'separately reviewable. '
+                    + 'update_cards edits/removes only your own layer (plus section frames — shared structure). '
+                    + 'PRESENTATION GENERATION: sections are slides — compose a deck as a series of sections (one heading + 2-3 supporting cards each: stat/line viz, callout, step referencing a shot), arrange each with save:true; the user presents with shift-P (arrows step sections). TEMPLATES: call get_templates for compose-ready skeletons (QA session, iteration review, decision map, metrics dashboard, presentation deck, kanban triage) — start from one instead of inventing structure. Everything else you place lives under the board\'s ✦ eve toggle, so express freely — the '
+                    + 'user can always mute the layer.',
             });
             return;
         case 'notifications/initialized':
@@ -355,10 +757,40 @@ async function handle(msg) {
                 replyError(id ?? null, -32602, `unknown tool: ${name}`);
                 return;
             }
+            // Enforce the declared inputSchema's required + additionalProperties —
+            // without this a misnamed argument (e.g. body instead of text) sails
+            // through and the handler stringifies undefined into real data.
+            {
+                const args = (params?.arguments ?? {});
+                const schema = tool.inputSchema;
+                const missing = (schema.required ?? []).filter((k) => args[k] === undefined);
+                const extra = schema.additionalProperties === false && schema.properties
+                    ? Object.keys(args).filter((k) => !(k in schema.properties))
+                    : [];
+                if (missing.length || extra.length) {
+                    reply(id, {
+                        content: [{ type: 'text', text: `invalid arguments for ${name}: ${[
+                                    missing.length ? `missing required ${missing.join(', ')}` : '',
+                                    extra.length ? `unknown ${extra.join(', ')}` : '',
+                                ].filter(Boolean).join('; ')} — see the tool's inputSchema` }],
+                        isError: true,
+                    });
+                    return;
+                }
+            }
             try {
                 const res = await tool.handler(params?.arguments ?? {});
                 const isErr = res.status >= 400;
-                const text = typeof res.body === 'string' ? res.body : JSON.stringify(res.body, null, 2);
+                // Compact JSON — pretty-printing burned ~25% of every tool result on
+                // whitespace the model pays for (ai-expression-layer §token discipline).
+                let text = typeof res.body === 'string' ? res.body : JSON.stringify(res.body);
+                if (res.status === 401) {
+                    // Write auth failed — say why and where the token comes from, so the
+                    // model can relay actionable guidance instead of a bare "unauthorized".
+                    text += `\n\nwrite auth failed: ${TOKEN
+                        ? `the configured write token was rejected by ${BASE_URL} (stale or mistyped)`
+                        : 'no write token is configured on this machine'} — the token is the SERVER's VITRINKA_TOKEN (one shared secret, no per-user mint); save it to ${tokenPath()} or $VITRINKA_TOKEN, and run \`vitrinka doctor\` for a full diagnosis.`;
+                }
                 reply(id, {
                     content: [{ type: 'text', text }],
                     isError: isErr,