@creator-notes/cnotes 0.16.11

package/dist/commands/canvas.js

@@ -0,0 +1,1383 @@
+import { Option } from "commander";
+import { ApiClient } from "../lib/api-client.js";
+import { resolveConfig } from "../lib/config.js";
+import { handleError, ValidationError } from "../lib/errors.js";
+import { readFileSafe } from "../lib/fs-utils.js";
+import { outputJson, outputTable, outputQuiet, truncate, timeAgo } from "../lib/output.js";
+import { readCanvasMarkdown, renderCanvasMarkdown } from "../lib/canvas-read.js";
+import { resolveAgentSession } from "../lib/claude-session.js";
+import { cnotesEnv } from "../lib/env.js";
+import { WARN, dim } from "../lib/style.js";
+/**
+ * A list item is a *collection of member notes* with a short markdown description
+ * that frames them — not a place to dump prose. When a description carries several
+ * distinct items (a markdown list, or multiple paragraphs), those items almost always
+ * want to be notes. Detect that shape so we can warn when a list is created with such a
+ * description but zero `--notes`. See the "list items are collections of notes" rule in
+ * the CLI skill (SKILL.md).
+ */
+function descriptionLooksLikeContent(description) {
+    const lines = description.split(/\r?\n/);
+    const listMarker = /^\s*(?:[-*+]\s+|\d+[.)]\s+)/;
+    const bulletLines = lines.filter((l) => listMarker.test(l)).length;
+    if (bulletLines >= 2)
+        return true;
+    // Multiple non-empty paragraphs also read as content rather than a one-line frame.
+    const paragraphs = description.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean);
+    return paragraphs.length >= 2;
+}
+/** Emit a fail-loud (stderr, non-blocking) nudge when a list item is being used as a text block. */
+function warnListItemMisuse(description, noteCount, label) {
+    if (noteCount > 0)
+        return;
+    if (!descriptionLooksLikeContent(description))
+        return;
+    const which = label ? ` "${label}"` : "";
+    console.error(`${WARN} List item${which} has no member notes, but its description looks like content (multiple items). ` +
+        `A list item is a collection of notes, not a text block.\n` +
+        `  ${dim("→ Create a note per item (e.g. a Question note per open question), then pass --notes <ids>.")}\n` +
+        `  ${dim("→ For a standalone formatted block, use `cnotes canvas add-richtext` instead.")}`);
+}
+/** Deep-walk a layout doc and warn for every leaf list item used as a text block. */
+function warnLayoutListMisuse(node) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            warnLayoutListMisuse(child);
+        return;
+    }
+    if (!node || typeof node !== "object")
+        return;
+    const n = node;
+    if (n.type === "list" && typeof n.description === "string") {
+        const noteIds = Array.isArray(n.noteIds) ? n.noteIds : [];
+        const label = n.description.split(/\n\s*\n/)[0]?.trim().slice(0, 60);
+        warnListItemMisuse(n.description, noteIds.length, label);
+    }
+    for (const value of Object.values(n))
+        warnLayoutListMisuse(value);
+}
+function parseArrowMode(mode) {
+    switch (mode) {
+        case "end":
+            return { arrowStart: false, arrowEnd: true };
+        case "start":
+            return { arrowStart: true, arrowEnd: false };
+        case "both":
+            return { arrowStart: true, arrowEnd: true };
+        case "none":
+            return { arrowStart: false, arrowEnd: false };
+        default:
+            throw new ValidationError(`Invalid --arrow value "${mode}". Expected one of: end, start, both, none.`);
+    }
+}
+function parseLineStyle(style) {
+    if (style === "solid" || style === "dashed")
+        return style;
+    throw new ValidationError(`Invalid --line-style value "${style}". Expected: solid or dashed.`);
+}
+export function registerCanvasCommands(program) {
+    const canvas = program
+        .command("canvas")
+        .alias("c")
+        .description("Manage canvases");
+    canvas
+        .command("list")
+        .description("List canvases in the current workspace")
+        .option("--include-archived", "Include archived canvases")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas list
+  $ cnotes canvas list --include-archived --json
+`)
+        .action(async (opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const params = { workspaceId: cfg.workspaceId };
+            if (opts.includeArchived) {
+                params.includeArchived = "true";
+            }
+            const data = await api.get("/api/canvas", params);
+            const list = data.canvases || data;
+            if (cfg.json) {
+                outputJson(list, cfg.fields);
+                return;
+            }
+            const items = Array.isArray(list) ? list : [];
+            if (items.length === 0) {
+                console.log("No canvases found.");
+                return;
+            }
+            const rows = items.map((c) => [
+                String(c._id || c.id || ""),
+                truncate(String(c.name || "(unnamed)"), 30),
+                c.isDefault ? "(default)" : c.archivedAt ? "(archived)" : "",
+                c.updatedAt ? timeAgo(c.updatedAt) : "",
+            ]);
+            outputTable(["ID", "NAME", "", "UPDATED"], rows);
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("get")
+        .description("Get canvas details with nodes and edges")
+        .argument("<canvasId>", "Canvas ID")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas get <canvasId> --json
+`)
+        .action(async (canvasId) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.get(`/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(cfg.workspaceId)}`);
+            if (cfg.json) {
+                outputJson(data);
+                return;
+            }
+            console.log(`Canvas: ${data.name || "(unnamed)"}`);
+            console.log(`ID: ${canvasId}`);
+            const canvas = data.canvas;
+            const goal = canvas?.goal || data.goal;
+            const targetAudience = canvas?.targetAudience || data.targetAudience;
+            if (goal)
+                console.log(`Goal: ${goal}`);
+            if (targetAudience)
+                console.log(`Audience: ${targetAudience}`);
+            const nodes = data.nodes;
+            const edges = data.edges;
+            if (nodes && nodes.length > 0) {
+                console.log(`\nNodes (${nodes.length}):`);
+                for (const node of nodes) {
+                    const noteTitle = node.note?.title || node.content || node.noteId || "?";
+                    console.log(`  ${node._id || node.id}: ${noteTitle} (${node.positionX}, ${node.positionY})`);
+                }
+            }
+            if (edges && edges.length > 0) {
+                console.log(`\nEdges (${edges.length}):`);
+                for (const edge of edges) {
+                    const label = edge.label ? ` [${edge.label}]` : "";
+                    console.log(`  ${edge.sourceNodeId} -> ${edge.targetNodeId}${label}`);
+                }
+            }
+            const linkNodes = data.canvasLinkNodes;
+            if (linkNodes && linkNodes.length > 0) {
+                console.log(`\nCanvas Links (${linkNodes.length}):`);
+                for (const ln of linkNodes) {
+                    const linked = ln.linkedCanvas;
+                    const name = linked?.name || ln.linkedCanvasId || "?";
+                    console.log(`  ${ln.id}: -> ${name} (${ln.positionX}, ${ln.positionY})`);
+                }
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("digest")
+        .description("Get the AI-generated digest (summary) of a canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .action(async (canvasId) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.get(`/api/canvas/${encodeURIComponent(canvasId)}/digest?workspaceId=${encodeURIComponent(cfg.workspaceId)}`);
+            if (cfg.json) {
+                outputJson(data);
+                return;
+            }
+            const status = String(data.status || "none");
+            if (status === "none") {
+                console.log("No digest available for this canvas.");
+                return;
+            }
+            if (status !== "ready") {
+                console.log(`Digest status: ${status} — try again shortly.`);
+                return;
+            }
+            const canvasName = data.canvasName || "(unnamed)";
+            console.log(`Canvas: ${canvasName}\n`);
+            console.log(String(data.digest || ""));
+            const themes = data.themes;
+            if (themes && themes.length > 0) {
+                console.log(`\nThemes:`);
+                for (const t of themes) {
+                    console.log(`  • ${t}`);
+                }
+            }
+            const notes = data.notes;
+            if (notes && notes.length > 0) {
+                console.log(`\nNotes (${notes.length}):`);
+                for (const n of notes) {
+                    console.log(`  [${n.displayId}] ${n.title} (${n.type})`);
+                    if (n.summary) {
+                        const trimmed = n.summary.replace(/\s+/g, " ").trim();
+                        const truncated = trimmed.length > 160 ? trimmed.slice(0, 157) + "..." : trimmed;
+                        console.log(`    ${truncated}`);
+                    }
+                    else {
+                        console.log(`    (no summary yet)`);
+                    }
+                }
+            }
+            else {
+                console.log(`\nNotes: ${data.noteCount || 0}`);
+            }
+            if (data.generatedAt) {
+                console.log(`Generated: ${timeAgo(data.generatedAt)}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("activity")
+        .description("Show recent activity (edits, agent runs, gestures, restores) on a canvas, newest first. " +
+        "Use this to see what changed and who changed it before making further edits, or to confirm " +
+        "an agent run actually applied.")
+        .argument("<canvasId>", "Canvas ID")
+        .option("--limit <n>", "Max entries (default 50, max 200)", "50")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const params = { workspaceId: cfg.workspaceId };
+            if (opts.limit !== undefined)
+                params.limit = String(opts.limit);
+            const data = await api.get(`/api/canvas/${encodeURIComponent(canvasId)}/activity`, params);
+            if (cfg.json) {
+                outputJson(data);
+                return;
+            }
+            const ops = data.operations ?? [];
+            if (ops.length === 0) {
+                console.log("No activity recorded yet.");
+                return;
+            }
+            console.log(`Canvas: ${data.canvasName}\n`);
+            const rows = ops.map((op) => {
+                const summary = op.structuredSummary?.headline ||
+                    op.summary ||
+                    op.userPrompt ||
+                    "";
+                return [
+                    timeAgo(op.startedAt),
+                    truncate(op.actorName || "—", 18),
+                    truncate(op.operationType, 22),
+                    op.status,
+                    String(op.eventCount ?? 0),
+                    truncate(summary, 60),
+                ];
+            });
+            outputTable(["WHEN", "WHO", "TYPE", "STATUS", "EVENTS", "SUMMARY"], rows);
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("read")
+        .description("Read every note on a canvas as one concatenated markdown document, " +
+        "in display order (top-to-bottom, then left-to-right). Use this to think " +
+        "across a canvas without making multiple round-trips.")
+        .argument("<canvasId>", "Canvas ID")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas read <canvasId>
+`)
+        .action(async (canvasId) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const result = await readCanvasMarkdown(api, cfg.workspaceId, canvasId);
+            if (cfg.json) {
+                outputJson(result);
+                return;
+            }
+            console.log(renderCanvasMarkdown(result));
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("create")
+        .description("Create a new canvas")
+        .argument("<name>", "Canvas name")
+        .option("--goal <text>", "Canvas goal — the purpose, desired outcome, and what it should communicate")
+        .option("--audience <text>", "Target audience — who this canvas is meant to serve or inform")
+        .action(async (name, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const body = {
+                workspaceId: cfg.workspaceId,
+                title: name,
+            };
+            if (opts.goal !== undefined)
+                body.goal = opts.goal;
+            if (opts.audience !== undefined)
+                body.targetAudience = opts.audience;
+            const data = await api.post("/api/canvas", body);
+            const canvas = data.canvas ?? {};
+            if (cfg.quiet) {
+                outputQuiet(String(canvas.id || canvas._id || ""));
+                return;
+            }
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                console.log(`Created canvas: ${name}`);
+                console.log(`ID: ${canvas.id || canvas._id || "(unknown)"}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("update")
+        .description("Update canvas metadata (title, goal, audience)")
+        .argument("<canvasId>", "Canvas ID")
+        .option("--title <text>", "New canvas title")
+        .option("--goal <text>", "Canvas goal — the purpose, desired outcome, and what it should communicate")
+        .option("--audience <text>", "Target audience — who this canvas is meant to serve or inform")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            if (opts.title === undefined && opts.goal === undefined && opts.audience === undefined) {
+                handleError(new ValidationError("At least one of --title, --goal, or --audience is required"), cfg.json);
+                return;
+            }
+            const body = {};
+            if (opts.title !== undefined)
+                body.title = opts.title;
+            if (opts.goal !== undefined)
+                body.goal = opts.goal;
+            if (opts.audience !== undefined)
+                body.targetAudience = opts.audience;
+            const data = await api.patch(`/api/canvas/${encodeURIComponent(canvasId)}`, body, { workspaceId: cfg.workspaceId });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                const changes = [];
+                if (opts.title)
+                    changes.push(`title="${opts.title}"`);
+                if (opts.goal)
+                    changes.push("goal");
+                if (opts.audience)
+                    changes.push("audience");
+                console.log(`Updated canvas ${canvasId}: ${changes.join(", ")}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("delete")
+        .description("Delete a canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .action(async (canvasId) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.delete(`/api/canvas/${canvasId}`);
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                console.log(`Deleted canvas ${canvasId}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("set-as-home")
+        .description("Set a canvas as the workspace home/default canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .action(async (canvasId) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "setAsHome",
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                console.log(`Canvas ${canvasId} set as workspace home.`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("archive")
+        .description("Archive a canvas (soft delete)")
+        .argument("<canvasId>", "Canvas ID")
+        .action(async (canvasId) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "archive",
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                console.log(`Archived canvas ${canvasId}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("unarchive")
+        .description("Unarchive (restore) an archived canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .action(async (canvasId) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "unarchive",
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                console.log(`Unarchived canvas ${canvasId}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("add-node")
+        .description("Add a note to a canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--note <noteId>", "Note display ID or Convex ID")
+        .option("--x <n>", "X position", "100")
+        .option("--y <n>", "Y position", "100")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas add-node <canvasId> --note MEETING-12 --x 200 --y 300
+`)
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "addNode",
+                noteId: opts.note,
+                positionX: parseInt(opts.x, 10),
+                positionY: parseInt(opts.y, 10),
+            });
+            if (cfg.quiet) {
+                outputQuiet(String(data.nodeId || data._id || ""));
+                return;
+            }
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                console.log(`Added note ${opts.note} to canvas at (${opts.x}, ${opts.y})`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("add-text")
+        .description("Add a text annotation to a canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--text <content>", "Text content")
+        .addOption(new Option("--size <size>", "Text size: heading (default, larger) or paragraph (smaller readable text)").choices(["heading", "paragraph"]).default("heading"))
+        .addOption(new Option("--color <variant>", "Color variant: normal (heading color), muted (body text color), highlighted (accent)").choices(["normal", "muted", "highlighted"]))
+        .option("--x <n>", "X position", "100")
+        .option("--y <n>", "Y position", "100")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas add-text <canvasId> --text "Section A" --size heading
+  $ cnotes canvas add-text <canvasId> --text "Note body" --size paragraph --color muted
+`)
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        const fontSize = opts.size === "paragraph" ? 18 : 32;
+        try {
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "addTextNode",
+                content: opts.text,
+                fontSize,
+                colorVariant: opts.color,
+                positionX: parseInt(opts.x, 10),
+                positionY: parseInt(opts.y, 10),
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                console.log(`Added text node to canvas at (${opts.x}, ${opts.y})`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("add-richtext")
+        .description("Add a richtext annotation to a canvas (supports formatted text with headings, lists, bold, etc.)")
+        .argument("<canvasId>", "Canvas ID")
+        .option("--content <content>", "Richtext content inline (markdown)")
+        .option("--content-file <path>", "Read richtext content (markdown) from a file")
+        .addOption(new Option("--size <size>", "Display size: small (560px), medium (1120px), large (1680px billboard)").choices(["small", "medium", "large"]))
+        .option("--color <hex>", "Background color hex (e.g. #3B82F6)")
+        .option("--x <n>", "X position", "100")
+        .option("--y <n>", "Y position", "100")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        let content;
+        if (opts.contentFile) {
+            content = readFileSafe(opts.contentFile);
+        }
+        else if (opts.content) {
+            content = opts.content;
+        }
+        else {
+            handleError(new ValidationError("Either --content or --content-file is required"), cfg.json);
+            return;
+        }
+        try {
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "addRichtextNode",
+                content,
+                size: opts.size,
+                colorHex: opts.color,
+                positionX: parseInt(opts.x, 10),
+                positionY: parseInt(opts.y, 10),
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                const heightInfo = data.estimatedHeight ? ` — estimated height: ${data.estimatedHeight}px` : '';
+                console.log(`Added richtext node to canvas at (${opts.x}, ${opts.y})${heightInfo}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("add-list")
+        .description("Add a list/grid node grouping notes on a canvas. The description is the only label; its first paragraph derives the searchable title.")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--description <markdown>", "Rich-text description (markdown). Required. First paragraph derives the searchable title.")
+        .option("--notes <ids>", "Note IDs (comma-separated, display IDs like TASK-6 or Convex IDs)")
+        .option("--view <mode>", "View mode: list or grid", "list")
+        .option("--x <n>", "X position", "100")
+        .option("--y <n>", "Y position", "100")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            if (opts.view !== "list" && opts.view !== "grid") {
+                throw new ValidationError(`Invalid view mode "${opts.view}". Must be "list" or "grid".`);
+            }
+            const noteIds = opts.notes ? opts.notes.split(",").map((id) => id.trim()) : [];
+            warnListItemMisuse(opts.description, noteIds.length);
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "addListNode",
+                description: opts.description,
+                noteIds: noteIds.length > 0 ? noteIds : undefined,
+                viewMode: opts.view,
+                positionX: parseInt(opts.x, 10),
+                positionY: parseInt(opts.y, 10),
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                const label = opts.description.split(/\n\s*\n/)[0]?.trim().slice(0, 60) ?? "list";
+                console.log(`Added "${label}" (${opts.view}) with ${noteIds.length} notes to canvas`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("add-link")
+        .description("Add a link to another canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--target <canvasId>", "Target canvas ID to link to")
+        .option("--x <n>", "X position", "100")
+        .option("--y <n>", "Y position", "100")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "addCanvasLink",
+                linkedCanvasId: opts.target,
+                positionX: parseInt(opts.x, 10),
+                positionY: parseInt(opts.y, 10),
+            });
+            if (cfg.quiet) {
+                outputQuiet(String(data.nodeId || data._id || ""));
+                return;
+            }
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                console.log(`Added link to canvas ${opts.target} at (${opts.x}, ${opts.y})`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("bulk-add")
+        .description("Add multiple notes to a canvas in one operation with positions")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--notes <json>", "JSON array of {noteId, x, y} objects")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas bulk-add <canvasId> --notes '[{"noteId":"TASK-1","x":100,"y":200},{"noteId":"TASK-2","x":400,"y":200}]'
+`)
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            let items;
+            try {
+                items = JSON.parse(opts.notes);
+            }
+            catch {
+                throw new ValidationError("--notes must be valid JSON array, e.g. '[{\"noteId\":\"TASK-1\",\"x\":100,\"y\":200}]'");
+            }
+            if (!Array.isArray(items) || items.length === 0) {
+                throw new ValidationError("--notes must be a non-empty JSON array");
+            }
+            const notes = items.map((item, i) => {
+                const positionX = Number(item.x);
+                const positionY = Number(item.y);
+                if (isNaN(positionX) || isNaN(positionY)) {
+                    throw new ValidationError(`Item ${i}: x and y must be numbers`);
+                }
+                return {
+                    noteId: String(item.noteId),
+                    positionX,
+                    positionY,
+                };
+            });
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "bulkAddNodes",
+                notes,
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                const results = (data.results || []);
+                const added = results.filter((r) => r.status === "added").length;
+                const skipped = results.filter((r) => r.status !== "added").length;
+                console.log(`Added ${added} notes to canvas${skipped > 0 ? ` (${skipped} skipped/failed)` : ""}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("place")
+        .description("Place items on a canvas using a declarative layout (no x/y math). The server measures every item, packs them with no overlaps, and inserts them in one batch. Per-item failures are reported in the response (HTTP 207). Prefer this over bulk-add whenever you can express the layout as stacks/grids/anchors.")
+        .argument("<canvasId>", "Canvas ID")
+        .option("--spec <path>", "Path to a JSON file containing the layout document")
+        .option("--spec-stdin", "Read the layout document from stdin")
+        .option("--spec-inline <json>", "Pass the layout document inline as a JSON string (short specs only)")
+        .option("--dry-run", "Validate the spec and return solved positions without mutating the canvas")
+        .option("--placement <mode>", "Where to drop the layout vs existing content: auto (default, lands in a clear band below existing nodes / de-collides), append (always below everything), or exact (honor origin verbatim). Overrides any placement in the spec.")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas place <canvasId> --spec ./layout.json
+  $ cnotes canvas place <canvasId> --spec ./layout.json --placement append
+  $ echo '{"root":{"type":"stack","items":[...]}}' | cnotes canvas place <canvasId> --spec-stdin
+  $ cnotes canvas place <canvasId> --spec ./layout.json --dry-run --json
+
+Placement (relative to nodes already on the canvas):
+  auto    default — lands below existing content when no origin is set, and
+          slides the whole block down if it would overlap. You never have to
+          guess a free coordinate.
+  append  always drop just below the lowest existing node.
+  exact   honor the spec's origin exactly, even if it overlaps (pixel-perfect
+          templates only).
+`)
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            let raw;
+            if (opts.spec) {
+                raw = readFileSafe(opts.spec);
+            }
+            else if (opts.specInline) {
+                raw = opts.specInline;
+            }
+            else if (opts.specStdin) {
+                raw = await new Promise((resolve, reject) => {
+                    const chunks = [];
+                    process.stdin.on("data", (c) => chunks.push(c));
+                    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+                    process.stdin.on("error", reject);
+                });
+            }
+            else {
+                throw new ValidationError("One of --spec, --spec-inline, or --spec-stdin is required");
+            }
+            let doc;
+            try {
+                doc = JSON.parse(raw);
+            }
+            catch (e) {
+                throw new ValidationError(`Layout spec is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            // --placement overrides whatever the spec carries (or sets it if absent).
+            if (opts.placement !== undefined) {
+                const allowed = ["auto", "append", "exact"];
+                if (!allowed.includes(opts.placement)) {
+                    throw new ValidationError(`--placement must be one of ${allowed.join(", ")} (got "${opts.placement}")`);
+                }
+                if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+                    throw new ValidationError("Layout spec must be a JSON object to apply --placement");
+                }
+                doc.placement = opts.placement;
+            }
+            warnLayoutListMisuse(doc);
+            const data = await api.post(`/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(cfg.workspaceId)}`, {
+                action: "placeLayout",
+                doc,
+                ...(opts.dryRun ? { dryRun: true } : {}),
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                const items = (data.items || []);
+                const edges = (data.edges || []);
+                const bbox = data.bbox;
+                if (data.dryRun) {
+                    console.log(`[dry run] Would place ${items.length} item${items.length === 1 ? "" : "s"} ` +
+                        `and ${edges.length} edge${edges.length === 1 ? "" : "s"} (no changes made).`);
+                    if (bbox?.width && bbox?.height) {
+                        console.log(`Layout bounding box: ${Math.round(bbox.width)} × ${Math.round(bbox.height)}px`);
+                    }
+                    return;
+                }
+                const placed = items.filter((r) => r.id && !r.error).length;
+                const failed = items.filter((r) => !r.id || r.error).length;
+                const edgesAdded = edges.filter((e) => e.id && !e.error).length;
+                const edgesFailed = edges.filter((e) => !e.id || e.error).length;
+                console.log(`Placed ${placed} items${failed > 0 ? ` (${failed} failed)` : ""}, ` +
+                    `${edgesAdded} edges${edgesFailed > 0 ? ` (${edgesFailed} failed)` : ""}`);
+                if (bbox?.width && bbox?.height) {
+                    console.log(`Layout bounding box: ${Math.round(bbox.width)} × ${Math.round(bbox.height)}px`);
+                }
+                // Surface item-level errors so the user doesn't have to re-run with --json
+                for (const item of items) {
+                    if (item.error)
+                        console.log(`  ✗ item[${item.index}] (${item.type}): ${item.error}`);
+                }
+                for (const edge of edges) {
+                    if (edge.error)
+                        console.log(`  ✗ edge ${edge.from} → ${edge.to}: ${edge.error}`);
+                }
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("bulk-move")
+        .description("Move multiple nodes to new positions in one operation")
+        .argument("<canvasId>", "Canvas ID (used for routing/auth)")
+        .requiredOption("--moves <json>", "JSON array of {nodeId, nodeType, x, y} objects (nodeType: note|text|list|canvas|richtext)")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            let items;
+            try {
+                items = JSON.parse(opts.moves);
+            }
+            catch {
+                throw new ValidationError("--moves must be valid JSON array, e.g. '[{\"nodeId\":\"abc\",\"nodeType\":\"note\",\"x\":100,\"y\":200}]'");
+            }
+            if (!Array.isArray(items) || items.length === 0) {
+                throw new ValidationError("--moves must be a non-empty JSON array");
+            }
+            const validNodeTypes = new Set(["note", "text", "list", "canvas", "richtext"]);
+            const moves = items.map((item, i) => {
+                const positionX = Number(item.x);
+                const positionY = Number(item.y);
+                if (isNaN(positionX) || isNaN(positionY)) {
+                    throw new ValidationError(`Item ${i}: x and y must be numbers`);
+                }
+                const nodeType = item.nodeType || "note";
+                if (!validNodeTypes.has(nodeType)) {
+                    throw new ValidationError(`Item ${i}: nodeType must be one of: note, text, list, canvas, richtext`);
+                }
+                return {
+                    nodeId: String(item.nodeId),
+                    nodeType: nodeType,
+                    positionX,
+                    positionY,
+                };
+            });
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "bulkMoveNodes",
+                moves,
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                const count = typeof data.count === "number" ? data.count : moves.length;
+                console.log(`Moved ${count} nodes`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("bulk-remove")
+        .description("Remove multiple nodes from a canvas in one operation")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--nodes <json>", "JSON array of node ID strings, e.g. '[\"nodeId1\",\"nodeId2\"]'")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            let nodeIds;
+            try {
+                nodeIds = JSON.parse(opts.nodes);
+            }
+            catch {
+                throw new ValidationError("--nodes must be valid JSON array, e.g. '[\"nodeId1\",\"nodeId2\"]'");
+            }
+            if (!Array.isArray(nodeIds) || nodeIds.length === 0) {
+                throw new ValidationError("--nodes must be a non-empty JSON array of strings");
+            }
+            nodeIds = nodeIds.map(String);
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "bulkRemoveNodes",
+                nodeIds,
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                const results = (data.results || []);
+                const deleted = results.filter((r) => r.status === "deleted").length;
+                const failed = results.filter((r) => r.status !== "deleted").length;
+                console.log(`Removed ${deleted} nodes from canvas${failed > 0 ? ` (${failed} failed)` : ""}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("add-edge")
+        .description("Connect two nodes on a canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--source <nodeId>", "Source node ID")
+        .requiredOption("--target <nodeId>", "Target node ID")
+        .option("--label <text>", "Edge label")
+        .option("--arrow <mode>", "Arrow direction: end (default), start, both, none", "end")
+        .option("--line-style <style>", "Line style: solid (default) | dashed", "solid")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const { arrowStart, arrowEnd } = parseArrowMode(opts.arrow);
+            const lineStyle = parseLineStyle(opts.lineStyle);
+            const data = await api.post(`/api/canvas/${canvasId}`, {
+                action: "addEdge",
+                sourceNodeId: opts.source,
+                targetNodeId: opts.target,
+                label: opts.label,
+                arrowStart,
+                arrowEnd,
+                lineStyle,
+            });
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                const label = opts.label ? ` [${opts.label}]` : "";
+                console.log(`Connected ${opts.source} -> ${opts.target}${label}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("update-edge")
+        .description("Update an edge's label, arrows, line style, or direction")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--edge <edgeId>", "Edge ID")
+        .option("--label <text>", "Set a new label (use --clear-label to remove)")
+        .option("--clear-label", "Remove the edge label")
+        .option("--arrow <mode>", "Arrow direction: end | start | both | none")
+        .option("--line-style <style>", "Line style: solid | dashed")
+        .option("--reverse", "Swap source and target nodes")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const body = {
+                action: "updateEdge",
+                edgeId: opts.edge,
+            };
+            if (opts.clearLabel) {
+                body.label = null;
+            }
+            else if (typeof opts.label === "string") {
+                body.label = opts.label;
+            }
+            if (opts.arrow !== undefined) {
+                const { arrowStart, arrowEnd } = parseArrowMode(opts.arrow);
+                body.arrowStart = arrowStart;
+                body.arrowEnd = arrowEnd;
+            }
+            if (opts.lineStyle !== undefined) {
+                body.lineStyle = parseLineStyle(opts.lineStyle);
+            }
+            if (opts.reverse)
+                body.reverse = true;
+            const data = await api.post(`/api/canvas/${canvasId}`, body);
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                console.log(`Updated edge ${opts.edge}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("move-node")
+        .description("Move a node to a new position on a canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--node <nodeId>", "Canvas node ID")
+        .requiredOption("--x <n>", "X position")
+        .requiredOption("--y <n>", "Y position")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const positionX = Number(opts.x);
+            const positionY = Number(opts.y);
+            await api.post(`/api/canvas/${canvasId}`, {
+                action: "moveNode",
+                nodeId: opts.node,
+                positionX,
+                positionY,
+            });
+            if (cfg.json) {
+                outputJson({ success: true, nodeId: opts.node, positionX, positionY });
+            }
+            else {
+                console.log(`Moved node ${opts.node} to (${positionX}, ${positionY})`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("remove-node")
+        .description("Remove a node from a canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--node <nodeId>", "Canvas node ID")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            await api.post(`/api/canvas/${canvasId}`, {
+                action: "removeNode",
+                nodeId: opts.node,
+            });
+            if (cfg.json) {
+                outputJson({ success: true, nodeId: opts.node });
+            }
+            else {
+                console.log(`Removed node ${opts.node} from canvas`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("remove-edge")
+        .description("Remove an edge from a canvas")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--edge <edgeId>", "Canvas edge ID")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            await api.post(`/api/canvas/${canvasId}`, {
+                action: "removeEdge",
+                edgeId: opts.edge,
+            });
+            if (cfg.json) {
+                outputJson({ success: true, edgeId: opts.edge });
+            }
+            else {
+                console.log(`Removed edge ${opts.edge} from canvas`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    // ---- Template commands ----
+    canvas
+        .command("templates")
+        .description("List available canvas templates")
+        .action(async () => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.get("/api/canvas/template");
+            const templates = data.templates || [];
+            if (cfg.json) {
+                outputJson(templates);
+                return;
+            }
+            if (templates.length === 0) {
+                console.log("No templates available.");
+                return;
+            }
+            const rows = templates.map((t) => [
+                String(t.id || ""),
+                String(t.name || ""),
+                truncate(String(t.description || ""), 40),
+                String(t.category || ""),
+                String(t.zoneCount || 0),
+            ]);
+            outputTable(["ID", "NAME", "DESCRIPTION", "CATEGORY", "ZONES"], rows);
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("from-template")
+        .description("Create a canvas from a predefined template")
+        .argument("<templateId>", "Template ID (use 'cnotes canvas templates' to list)")
+        .option("--title <title>", "Custom canvas title")
+        .option("--density <mode>", "Layout density: tight, medium, or spacious")
+        .option("--populate", "Auto-populate zones with matching notes from workspace")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas templates
+  $ cnotes canvas from-template retro --title "Q4 Retro" --populate
+`)
+        .action(async (templateId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            // Validate template exists by fetching template list
+            const templateData = await api.get("/api/canvas/template");
+            const templates = templateData.templates || [];
+            const template = templates.find((t) => t.id === templateId);
+            if (!template) {
+                const available = templates.map((t) => t.id).join(", ");
+                throw new ValidationError(`Unknown template "${templateId}". Available: ${available}`);
+            }
+            // Validate density (must match LAYOUT_DENSITIES in lib/canvas/templates/types.ts)
+            const validDensities = ["tight", "medium", "spacious"];
+            if (opts.density && !validDensities.includes(opts.density)) {
+                throw new ValidationError(`Invalid density "${opts.density}". Must be: ${validDensities.join(", ")}`);
+            }
+            // If --populate, search notes for each zone
+            let zonePopulations;
+            if (opts.populate) {
+                zonePopulations = [];
+                const zones = template.zones;
+                if (zones) {
+                    for (const zone of zones) {
+                        const hint = zone.populationHint;
+                        if (!hint || hint.startsEmpty)
+                            continue;
+                        const searchQuery = hint.searchQuery;
+                        const noteTypes = hint.noteTypes;
+                        const maxNotes = hint.maxNotes || 8;
+                        // Search for matching notes
+                        const searchParams = {
+                            workspaceId: cfg.workspaceId,
+                            limit: String(maxNotes),
+                        };
+                        if (searchQuery)
+                            searchParams.search = searchQuery;
+                        if (noteTypes && noteTypes.length > 0)
+                            searchParams.types = noteTypes.join(",");
+                        try {
+                            const searchResult = await api.get("/api/notes", searchParams);
+                            const notes = searchResult.notes || [];
+                            if (notes.length > 0) {
+                                zonePopulations.push({
+                                    zoneId: String(zone.id),
+                                    noteIds: notes.map((n) => String(n.displayId || n.id || n._id)),
+                                });
+                            }
+                        }
+                        catch {
+                            // Search failed for this zone, continue without population
+                        }
+                    }
+                }
+            }
+            // Create canvas from template
+            const data = await api.post("/api/canvas/template", {
+                workspaceId: cfg.workspaceId,
+                templateId,
+                title: opts.title,
+                density: opts.density,
+                zonePopulations,
+            });
+            if (cfg.quiet) {
+                outputQuiet(String(data.canvasId || ""));
+                return;
+            }
+            if (cfg.json) {
+                outputJson(data);
+            }
+            else {
+                const name = opts.title || template.name;
+                console.log(`Created canvas from template "${templateId}": ${name}`);
+                console.log(`Canvas ID: ${data.canvasId}`);
+                console.log(`Zones: ${data.zoneCount}, Notes: ${data.noteCount}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    // ============================================
+    // AGENT-RUN LIFECYCLE
+    // ============================================
+    //
+    // Bracket a sequence of canvas commands with auto-checkpoints so the
+    // server treats them as a single agent operation. The pattern:
+    //
+    //   eval "$(npx cnotes canvas agent-run begin --canvas <id> --prompt "Reorganize")"
+    //   npx cnotes canvas add-node ...
+    //   npx cnotes canvas add-edge ...
+    //   npx cnotes canvas agent-run end --canvas <id>
+    //
+    // `begin` prints `export CN_AGENT_RUN_ID=...` for shell eval. Subsequent
+    // commands pick up the env var and the api-client adds it as a header,
+    // so all mutations between begin and end share one operation row + a
+    // before/after snapshot pair, recoverable later via "Revert this run".
+    const agentRun = canvas
+        .command("agent-run")
+        .description("Bracket canvas commands with before/after auto-checkpoints");
+    agentRun
+        .command("begin")
+        .description("Open an agent-run session — captures a before-snapshot and prints CN_AGENT_RUN_ID")
+        .requiredOption("--canvas <id>", "Canvas ID to bracket")
+        .requiredOption("--prompt <text>", "User prompt or summary describing the run")
+        .option("--rationale <text>", "Optional rationale (e.g. agent's plan)")
+        .action(async (opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        // This command is designed to be used via `eval "$(...)"`, which makes
+        // stdout a non-TTY. resolveConfig's default would then flip cfg.json on
+        // and we'd emit JSON instead of shell exports — breaking the eval form.
+        // Honour JSON only when the user asked for it explicitly.
+        const wantsJson = program.opts().json === true || cnotesEnv("JSON") === "1";
+        try {
+            const body = {
+                action: "agentRunBegin",
+                prompt: opts.prompt,
+            };
+            if (opts.rationale)
+                body.rationale = opts.rationale;
+            const agentSession = resolveAgentSession();
+            if (agentSession)
+                body.agentSession = agentSession;
+            const data = await api.post(`/api/canvas/${encodeURIComponent(opts.canvas)}`, body);
+            if (cfg.quiet) {
+                outputQuiet(data.agentRunId);
+                return;
+            }
+            if (wantsJson) {
+                outputJson(data);
+                return;
+            }
+            // Print eval-friendly export so users can:
+            //   eval "$(npx cnotes canvas agent-run begin ...)"
+            // Only the runId + before-snapshot id need to ride along on
+            // each request — prompt + rationale were already persisted on
+            // the operation row at agentRunBegin time.
+            console.log(`export CN_AGENT_RUN_ID=${data.agentRunId}`);
+            console.log(`export CN_AGENT_BEFORE_SNAPSHOT_ID=${data.beforeCheckpointId}`);
+            console.error(`# agent run started: v${data.beforeSnapshotNumber} (${data.agentRunId})`);
+            console.error(`# end with: npx cnotes canvas agent-run end --canvas ${opts.canvas}`);
+        }
+        catch (error) {
+            handleError(error, wantsJson);
+        }
+    });
+    agentRun
+        .command("wrap")
+        .description("Run a shell command inside an agent-run scope (auto begin + end). Recommended for AI agents — no eval gymnastics, no env-var leakage, auto-closes the run even on subprocess failure.")
+        .requiredOption("--canvas <id>", "Canvas ID")
+        .requiredOption("--prompt <text>", "Prompt describing the run")
+        .option("--rationale <text>", "Optional rationale (e.g. agent's plan)")
+        .argument("<command...>", "Command to execute (e.g. -- bash -c '...')")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas agent-run wrap --canvas <id> --prompt "Reorganize" -- bash -c 'cnotes canvas add-node <id> --note A-1'
+  $ cnotes canvas agent-run wrap --canvas <id> --prompt "Lay out retro" -- cnotes canvas place <id> --spec ./layout.json
+`)
+        .action(async (command, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        if (command.length === 0) {
+            throw new ValidationError('No command to run. Usage:\n  cnotes canvas agent-run wrap --canvas <id> --prompt "..." -- <command>');
+        }
+        // Step 1: open the run
+        const agentSession = resolveAgentSession();
+        const begin = await api.post(`/api/canvas/${encodeURIComponent(opts.canvas)}`, {
+            action: "agentRunBegin",
+            prompt: opts.prompt,
+            ...(opts.rationale ? { rationale: opts.rationale } : {}),
+            ...(agentSession ? { agentSession } : {}),
+        });
+        console.error(`# agent run started: v${begin.beforeSnapshotNumber} (${begin.agentRunId})`);
+        // Step 2: spawn the wrapped command with the run env var set.
+        // stdio is inherited so the subprocess prints to the user's terminal
+        // exactly as if they'd run it themselves. Only runId + before-snapshot
+        // need to propagate — prompt + rationale are persisted on the
+        // operation row at agentRunBegin time, so resending them per-request
+        // would be redundant (and would add a spoofing surface).
+        const { spawn } = await import("node:child_process");
+        const child = spawn(command[0], command.slice(1), {
+            stdio: "inherit",
+            env: {
+                ...process.env,
+                CN_AGENT_RUN_ID: begin.agentRunId,
+                CN_AGENT_BEFORE_SNAPSHOT_ID: begin.beforeCheckpointId,
+            },
+        });
+        const exitCode = await new Promise((resolve) => {
+            child.on("exit", (code, signal) => {
+                if (signal) {
+                    console.error(`# subprocess killed by signal ${signal}`);
+                    resolve(128);
+                    return;
+                }
+                resolve(code ?? 1);
+            });
+            child.on("error", (err) => {
+                console.error(`# subprocess failed to start: ${err.message}`);
+                resolve(1);
+            });
+        });
+        // Step 3: ALWAYS close the run, even if the subprocess failed.
+        // The after-checkpoint captures whatever state was reached.
+        try {
+            const end = await api.post(`/api/canvas/${encodeURIComponent(opts.canvas)}`, {
+                action: "agentRunEnd",
+                agentRunId: begin.agentRunId,
+            });
+            const status = exitCode === 0 ? "completed" : `exited ${exitCode}`;
+            console.error(`# agent run ${status}: v${end.afterSnapshotNumber} (${begin.agentRunId})`);
+            if (cfg.json) {
+                outputJson({
+                    agentRunId: begin.agentRunId,
+                    beforeCheckpointId: begin.beforeCheckpointId,
+                    beforeSnapshotNumber: begin.beforeSnapshotNumber,
+                    afterCheckpointId: end.afterCheckpointId,
+                    afterSnapshotNumber: end.afterSnapshotNumber,
+                    exitCode,
+                });
+            }
+        }
+        catch (err) {
+            console.error(`# WARNING: agent run did not close cleanly:`, err instanceof Error ? err.message : err);
+            console.error(`# you can close it manually: cnotes canvas agent-run end --canvas ${opts.canvas} --run-id ${begin.agentRunId}`);
+        }
+        process.exit(exitCode);
+    });
+    agentRun
+        .command("end")
+        .description("Close an agent-run session — captures an after-snapshot and prints unset commands")
+        .requiredOption("--canvas <id>", "Canvas ID to close")
+        .option("--run-id <id>", "Agent run ID (defaults to CN_AGENT_RUN_ID env var)")
+        .action(async (opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        const runId = opts.runId ?? cnotesEnv("AGENT_RUN_ID");
+        if (!runId) {
+            throw new ValidationError("No agent run ID found. Pass --run-id or set CNOTES_AGENT_RUN_ID.");
+        }
+        // Same reasoning as `begin`: eval form makes stdout non-TTY, so don't
+        // let the auto-detect flip us into JSON mode.
+        const wantsJson = program.opts().json === true || cnotesEnv("JSON") === "1";
+        try {
+            const data = await api.post(`/api/canvas/${encodeURIComponent(opts.canvas)}`, {
+                action: "agentRunEnd",
+                agentRunId: runId,
+            });
+            if (cfg.quiet) {
+                outputQuiet(String(data.afterSnapshotNumber));
+                return;
+            }
+            if (wantsJson) {
+                outputJson(data);
+                return;
+            }
+            // Tell the user how to clear the env vars; eval-safe so users
+            // running `eval "$(cnotes canvas agent-run end ...)"` get them
+            // unset automatically.
+            console.log(`unset CN_AGENT_RUN_ID CN_AGENT_BEFORE_SNAPSHOT_ID`);
+            console.error(`# agent run closed: v${data.afterSnapshotNumber} (${runId})`);
+        }
+        catch (error) {
+            handleError(error, wantsJson);
+        }
+    });
+}
+//# sourceMappingURL=canvas.js.map