@neta-art/cohub-cli 6.2.2 → 6.4.0

package/README.md

@@ -157,53 +157,57 @@ cohub -s <spaceId> spaces activity 365 --json
 
 ## Boards
 
-Board commands use the selected Space and support `-h` at every level:
+Board targets accept a Board ID or a `.board` path. Every command supports `-h` and `--json`:
 
 ```bash
 cohub boards -h
-cohub boards inspect -h
-cohub -s <spaceId> boards create boards/plan.board --title "Plan"
-cohub -s <spaceId> boards inspect <boardId> --json
+cohub -s <spaceId> boards inspect boards/plan.board --json
+cohub -s <spaceId> boards items list <boardId>
+cohub -s <spaceId> boards connections list <boardId>
 cohub -s <spaceId> boards capabilities <boardId>
 cohub -s <spaceId> boards watch <boardId> --json
 ```
 
-Pass semantic items, effects, and compositions as JSON when creating a Board. The path and title stay explicit in the command. Generate editable templates instead of guessing fields:
+Use targeted reads for large Boards:
 
 ```bash
-cohub boards examples create > board-content.json
-cohub boards examples item geo > item.json
-cohub boards examples effect pulse > effect.json
-cohub boards examples composition fade > intro.json
-```
-
-Inspect `boards capabilities --json` for supported Item types, animation channels, effect kinds, and coordinate spaces.
-
-```bash
-cohub -s <spaceId> boards create boards/plan.board \
-  --title "Plan" \
-  --input board-content.json
+cohub -s <spaceId> boards items get <boardId> <itemId> --json
+cohub -s <spaceId> boards connections get <boardId> <connectionId> --json
+cohub -s <spaceId> boards effects get <boardId> <effectId> --json
+cohub -s <spaceId> boards compositions get <boardId> <compositionId> --json
 ```
 
-Generate editable semantic JSON templates instead of authoring storage transactions:
+Create semantic JSON from an example, then apply it to one resource:
 
 ```bash
 cohub boards examples item text > item.json
-cohub boards items create <boardId> --input item.json
+cohub -s <spaceId> boards items create <boardId> --input item.json
 
 cohub boards examples composition fade > intro.json
-cohub boards compositions apply <boardId> --input intro.json
+cohub -s <spaceId> boards compositions apply <boardId> --input intro.json
+```
+
+Apply related changes atomically with one request. The batch contains semantic commands, not a full Board snapshot:
 
-cohub boards examples effect pulse > effect.json
-cohub boards effects apply <boardId> --input effect.json
+```json
+{"commands":[
+  {"type":"item.patch","itemId":"title","patch":{"props":{"text":"Updated"}}},
+  {"type":"connection.create","connection":{"id":"title-agent","source":{"itemId":"title"},"target":{"itemId":"agent"}}}
+]}
+```
+
+```bash
+cohub boards examples batch basic > changes.json
+cohub -s <spaceId> boards batch <boardId> --input changes.json --dry-run
+cohub -s <spaceId> boards batch <boardId> --input changes.json
 ```
 
-Use `--mutation-id` or `--command-id` when a script needs a stable idempotency key across retries.
+Use `--base-version` and `--mutation-id` for controlled, retry-safe scripts. Use `--dry-run` to validate without writing. Playback is grouped under `playback`:
 
 ```bash
-cohub -s <spaceId> boards play <boardId> <compositionId>
-cohub -s <spaceId> boards seek <boardId> <playbackId> 400
-cohub -s <spaceId> boards stop <boardId> <playbackId>
+cohub -s <spaceId> boards playback play <boardId> <compositionId>
+cohub -s <spaceId> boards playback seek <boardId> <playbackId> 400
+cohub -s <spaceId> boards playback stop <boardId> <playbackId>
 ```
 
 ## Search

package/dist/board-export.d.ts

@@ -1,8 +1,9 @@
 /**
  * Board image export for the CLI.
  *
- * Rendering runs through the same PixiJS card renderers the web editor uses (see
- * `@neta-art/cohub/board`), on a Canvas2D backend. Everything platform-specific
+ * The CLI and web editor share canonical Board geometry and card semantics. Each
+ * host selects the renderer primitive suited to its backend; this path uses
+ * Canvas2D. Everything platform-specific
  * lives here: fetching the document over HTTP, pulling image bytes out of the
  * space, and locating fonts on disk.
  */

package/dist/board-export.js

@@ -1,8 +1,9 @@
 /**
  * Board image export for the CLI.
  *
- * Rendering runs through the same PixiJS card renderers the web editor uses (see
- * `@neta-art/cohub/board`), on a Canvas2D backend. Everything platform-specific
+ * The CLI and web editor share canonical Board geometry and card semantics. Each
+ * host selects the renderer primitive suited to its backend; this path uses
+ * Canvas2D. Everything platform-specific
  * lives here: fetching the document over HTTP, pulling image bytes out of the
  * space, and locating fonts on disk.
  */

package/dist/commands/board-domain.js

@@ -1,12 +1,14 @@
 import { registerBoardAnimationCommands } from "./boards/animation.js";
 import { registerBoardAppearanceCommands } from "./boards/appearance.js";
 import { registerBoardExampleCommands } from "./boards/examples.js";
+import { registerBoardBatchCommand } from "./boards/batch.js";
+import { registerBoardConnectionCommands } from "./boards/connections.js";
 import { registerBoardItemCommands } from "./boards/items.js";
-import { registerBoardNodeCommands } from "./boards/nodes.js";
 export function registerBoardDomainCommands(boards) {
     registerBoardExampleCommands(boards);
     registerBoardAppearanceCommands(boards);
-    registerBoardNodeCommands(boards);
+    registerBoardBatchCommand(boards);
+    registerBoardConnectionCommands(boards);
     registerBoardItemCommands(boards);
     registerBoardAnimationCommands(boards);
 }

package/dist/commands/boards/animation.js

@@ -1,14 +1,14 @@
 import { parseBoardEffectInput, parseBoardCompositionInput, } from "@neta-art/cohub";
 import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
 import { handleHttp, json, jsonRequested, table } from "../../output.js";
-import { mutateSemantic, resolvedBoard, showUpdated, withJson, } from "./context.js";
+import { mutateSemantic, readInput, readOptions, resolvedBoard, showUpdated, withJson, } from "./context.js";
 export function registerBoardAnimationCommands(boards) {
     const effects = boards.command("effects").description("Manage Board effects");
-    withJson(effects.command("list <board>").alias("ls").description("List effects"))
+    readOptions(withJson(effects.command("list <board>").alias("ls").description("List effects")))
         .action(async (target, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.authoring({ include: ["effects"] });
+            const result = await board.authoring(readInput(options, "effects"));
             const effects = result.effects ?? [];
             if (jsonRequested(options))
                 return json(effects);
@@ -23,6 +23,27 @@ export function registerBoardAnimationCommands(boards) {
             handleHttp(cause);
         }
     });
+    withJson(effects.command("get <board> <effect-id>").description("Get one complete Board effect"))
+        .action(async (target, effectId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            const result = await board.authoring({ include: ["effects"], effectIds: [effectId] });
+            const effect = result.effects?.[0];
+            if (!effect)
+                throw new Error(`Effect not found: ${effectId}`);
+            if (jsonRequested(options))
+                return json(effect);
+            table([effect], [
+                { key: "id", label: "ID" },
+                { key: "kind", label: "KIND" },
+                { key: "enabled", label: "ENABLED" },
+                { key: "layer", label: "LAYER" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
     withJson(effects.command("apply <board>")
         .description("Atomically create or replace an effect")
         .requiredOption("-i, --input <file>", "Board effect JSON; use - for stdin")
@@ -56,11 +77,11 @@ Discover supported effect kinds:
     const compositions = boards
         .command("compositions")
         .description("Manage atomic Board animation compositions");
-    withJson(compositions.command("list <board>").alias("ls").description("List compositions"))
+    readOptions(withJson(compositions.command("list <board>").alias("ls").description("List compositions")))
         .action(async (target, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.authoring({ include: ["compositions"] });
+            const result = await board.authoring(readInput(options, "compositions"));
             const compositions = result.compositions ?? [];
             if (jsonRequested(options))
                 return json(compositions);
@@ -88,8 +109,8 @@ Discover supported effect kinds:
         .action(async (target, compositionId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.authoring({ include: ["compositions"] });
-            const composition = (result.compositions ?? []).find((item) => item.id === compositionId);
+            const result = await board.authoring({ include: ["compositions"], compositionIds: [compositionId] });
+            const composition = result.compositions?.[0];
             if (!composition)
                 throw new Error(`Composition not found: ${compositionId}`);
             if (jsonRequested(options))

package/dist/commands/boards/batch.d.ts

@@ -0,0 +1,4 @@
+import { type BoardSemanticCommand } from "@neta-art/cohub";
+import type { Command } from "commander";
+export declare function parseBatchCommands(input: Record<string, unknown>): BoardSemanticCommand[];
+export declare function registerBoardBatchCommand(boards: Command): void;

package/dist/commands/boards/batch.js

@@ -0,0 +1,62 @@
+import { randomUUID } from "node:crypto";
+import { BoardSemanticCommandSchema } from "@neta-art/cohub";
+import { BOARD_TRANSACTION_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
+import { handleHttp, json, jsonRequested, ok } from "../../output.js";
+import { mutateSemantic, resolvedBoard, withJson, } from "./context.js";
+export function parseBatchCommands(input) {
+    if (!Array.isArray(input.commands) || input.commands.length === 0) {
+        throw new Error("batch input must contain a non-empty commands array");
+    }
+    return input.commands.map((command, index) => {
+        const parsed = BoardSemanticCommandSchema.safeParse(command);
+        if (!parsed.success) {
+            const issue = parsed.error.issues[0];
+            const path = issue?.path.length ? `.${issue.path.join(".")}` : "";
+            throw new Error(`commands[${index}]${path}: ${issue?.message ?? "invalid command"}`);
+        }
+        return parsed.data;
+    });
+}
+export function registerBoardBatchCommand(boards) {
+    withJson(boards.command("batch <board>")
+        .description("Apply an atomic batch of semantic Board changes")
+        .requiredOption("-i, --input <file>", "Batch JSON with a commands array; use - for stdin")
+        .option("--base-version <version>", "Expected Board version; defaults to latest")
+        .option("--mutation-id <id>", "Stable id for safe retries")
+        .option("--dry-run", "Validate the whole batch without writing")
+        .addHelpText("after", `
+Input format:
+  {"commands":[{"type":"item.patch","itemId":"title","patch":{"props":{"text":"Updated"}}}]}
+
+Commands are applied atomically. See boards capabilities for supported fields.`))
+        .action(async (target, options) => {
+        try {
+            const input = await readBoardJsonObject(options.input, BOARD_TRANSACTION_INPUT_MAX_BYTES);
+            const commands = parseBatchCommands(input);
+            const parsedVersion = options.baseVersion === undefined ? undefined : Number(options.baseVersion);
+            if (parsedVersion !== undefined && (!Number.isSafeInteger(parsedVersion) || parsedVersion < 0)) {
+                throw new Error("base version must be a non-negative integer");
+            }
+            const board = await resolvedBoard(boards, target);
+            const result = await mutateSemantic(board, commands, {
+                ...(parsedVersion === undefined ? {} : { baseVersion: parsedVersion }),
+                mutationId: options.mutationId?.trim() || randomUUID(),
+                dryRun: Boolean(options.dryRun),
+            });
+            if (jsonRequested(options))
+                return json(result);
+            if (result.outcome === "dry-run") {
+                ok(`Validated ${commands.length} changes; no changes written`);
+            }
+            else if (result.outcome === "noop" || result.status === "validated") {
+                ok(`Board already matches the requested ${commands.length} changes`);
+            }
+            else {
+                ok(`${result.replayed ? "Replayed" : "Applied"} ${commands.length} changes at Board version ${result.board.version}`);
+            }
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

package/dist/commands/boards/connections.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardConnectionCommands(boards: Command): void;

package/dist/commands/boards/connections.js

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import { createBoardConnection } from "@neta-art/cohub/board";
+import { handleHttp, json, jsonRequested, table } from "../../output.js";
+import { mutateSemantic, readInput, readOptions, resolvedBoard, showUpdated, withJson, } from "./context.js";
+const columns = [
+    { key: "id", label: "ID" },
+    { key: "source", label: "SOURCE" },
+    { key: "target", label: "TARGET" },
+    { key: "relation", label: "RELATION" },
+    { key: "direction", label: "DIRECTION" },
+    { key: "label", label: "LABEL" },
+];
+function rows(connections) {
+    return connections.map((connection) => ({
+        id: connection.id,
+        source: connection.source.itemId,
+        target: connection.target.itemId,
+        relation: connection.relation ?? "",
+        direction: connection.direction ?? "",
+        label: connection.label ?? "",
+    }));
+}
+export function registerBoardConnectionCommands(boards) {
+    const connections = boards.command("connections").description("Manage Board connections");
+    readOptions(withJson(connections.command("list <board>").alias("ls").description("List Board connections")))
+        .action(async (target, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            const result = await board.authoring(readInput(options, "connections"));
+            const value = result.connections ?? [];
+            if (jsonRequested(options))
+                return json(value);
+            table(rows(value), columns);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(connections.command("get <board> <connection-id>").description("Get one complete Board connection"))
+        .action(async (target, connectionId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            const result = await board.authoring({ include: ["connections"], connectionIds: [connectionId] });
+            const connection = result.connections?.[0];
+            if (!connection)
+                throw new Error(`Connection not found: ${connectionId}`);
+            if (jsonRequested(options))
+                return json(connection);
+            table(rows([connection]), columns);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(connections.command("create <board> <source> <target>").description("Create a Board connection")
+        .option("--id <id>", "Connection id")
+        .option("--relation <relation>", "Relation type")
+        .option("--direction <direction>", "none, forward, backward, or both", "forward")
+        .option("--label <label>", "Connection label")
+        .option("--source-port <id>", "Source port id")
+        .option("--target-port <id>", "Target port id"))
+        .action(async (target, source, destination, options) => {
+        try {
+            const direction = options.direction ?? "forward";
+            if (!["none", "forward", "backward", "both"].includes(direction)) {
+                throw new Error("--direction must be none, forward, backward, or both");
+            }
+            const board = await resolvedBoard(boards, target);
+            const connection = createBoardConnection({
+                id: options.id ?? randomUUID(),
+                sourceItemId: source,
+                targetItemId: destination,
+                relation: options.relation,
+                direction: direction,
+                label: options.label,
+                sourcePortId: options.sourcePort,
+                targetPortId: options.targetPort,
+            });
+            showUpdated(await mutateSemantic(board, [{ type: "connection.create", connection }]), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(connections.command("delete <board> <connection-id>").alias("rm").description("Delete a Board connection"))
+        .action(async (target, connectionId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await mutateSemantic(board, [{ type: "connection.delete", connectionId }]), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

package/dist/commands/boards/context.d.ts

@@ -1,17 +1,20 @@
-import type { BoardClient, BoardSemanticCommand } from "@neta-art/cohub";
+import type { BoardAuthoringReadInput, BoardClient, BoardSemanticCommand } from "@neta-art/cohub";
 import type { Command } from "commander";
 export type JsonOptions = {
     json?: boolean;
 };
+export type ReadOptions = JsonOptions & {
+    ids?: string;
+};
 export declare function withJson(command: Command): Command;
 export declare function finite(value: string | undefined, name: string, fallback?: number): number;
+export declare function readInput(options: ReadOptions, section: NonNullable<BoardAuthoringReadInput["include"]>[number]): BoardAuthoringReadInput;
+export declare function readOptions(command: Command, label?: string): Command;
 export declare function resolvedBoard(boards: Command, target: string): Promise<BoardClient>;
 /**
- * Send semantic commands with one automatic version-conflict retry: a racing
- * edit between our version read and the submit is transparently rebased (same
- * commands, fresh baseVersion, same id — a retry that lands is idempotent).
- * `options.baseVersion` lets an agent chain mutations without re-reading the
- * board between writes.
+ * Send semantic commands with one automatic version-conflict retry when the
+ * caller did not pin a base version. An explicit `baseVersion` is a strict
+ * optimistic-concurrency check and must fail instead of being rebased.
  */
 export declare function mutateSemantic(board: BoardClient, commands: BoardSemanticCommand[], options?: {
     baseVersion?: number;

package/dist/commands/boards/context.js

@@ -13,20 +13,29 @@ export function finite(value, name, fallback) {
         throw new Error(`${name} must be a finite number`);
     return result;
 }
+export function readInput(options, section) {
+    const ids = options.ids?.split(",").map((id) => id.trim()).filter(Boolean);
+    return {
+        include: [section],
+        ...(ids?.length ? { [`${section.slice(0, -1)}Ids`]: ids } : {}),
+    };
+}
+export function readOptions(command, label = "Comma-separated resource IDs") {
+    return command.option("--ids <ids>", label);
+}
 export async function resolvedBoard(boards, target) {
     const spaceId = resolveSpace(boards);
     const boardId = await resolveBoardId(spaceId, target);
     return createClient().space(spaceId).board(boardId);
 }
 /**
- * Send semantic commands with one automatic version-conflict retry: a racing
- * edit between our version read and the submit is transparently rebased (same
- * commands, fresh baseVersion, same id — a retry that lands is idempotent).
- * `options.baseVersion` lets an agent chain mutations without re-reading the
- * board between writes.
+ * Send semantic commands with one automatic version-conflict retry when the
+ * caller did not pin a base version. An explicit `baseVersion` is a strict
+ * optimistic-concurrency check and must fail instead of being rebased.
  */
 export async function mutateSemantic(board, commands, options = {}) {
-    const baseVersion = options.baseVersion ?? (await board.summary()).board.version;
+    const pinnedVersion = options.baseVersion;
+    const baseVersion = pinnedVersion ?? (await board.summary()).board.version;
     const send = (version) => board.mutateSemantic({
         mutationId: options.mutationId,
         baseVersion: version,
@@ -37,7 +46,7 @@ export async function mutateSemantic(board, commands, options = {}) {
         return await send(baseVersion);
     }
     catch (cause) {
-        if (options.dryRun || !isVersionConflict(cause))
+        if (options.dryRun || pinnedVersion !== undefined || !isVersionConflict(cause))
             throw cause;
         const retry = (await board.summary()).board.version;
         return send(retry);

package/dist/commands/boards/examples.js

@@ -1,11 +1,18 @@
 import { json } from "../../output.js";
-const frame = { x: 120, y: 80, width: 320, height: 48, rotation: 0 };
 const templates = {
+    "batch:basic": {
+        commands: [
+            { type: "board.patch", patch: { title: "Updated title" } },
+            { type: "item.patch", itemId: "title", patch: { props: { text: "Updated text" } } },
+        ],
+    },
     "create": {
         items: [{
                 id: "title",
                 type: "text",
-                frame,
+                position: { x: 120, y: 80 },
+                size: { width: 320, height: 48 },
+                rotation: 0,
                 props: { text: "Launch plan", fontSize: 32 },
                 style: { color: "brand" },
             }],
@@ -13,73 +20,233 @@ const templates = {
         effects: [],
         compositions: [],
     },
+    "create:workflow": {
+        items: [
+            {
+                id: "request",
+                type: "text",
+                position: { x: 80, y: 190 },
+                size: { width: 180, height: 48 },
+                rotation: 0,
+                props: { text: "Request", fontSize: 28 },
+                style: { color: "brand" },
+            },
+            {
+                id: "agent",
+                type: "geo",
+                position: { x: 360, y: 150 },
+                size: { width: 240, height: 120 },
+                rotation: 0,
+                props: { shape: "rounded", text: "Agent" },
+                style: { color: "blue", fillOpacity: 0.08 },
+            },
+            {
+                id: "result",
+                type: "geo",
+                position: { x: 700, y: 150 },
+                size: { width: 240, height: 120 },
+                rotation: 0,
+                props: { shape: "rounded", text: "Result" },
+                style: { color: "green", fillOpacity: 0.08 },
+            },
+        ],
+        connections: [
+            { id: "request-agent", source: { itemId: "request" }, target: { itemId: "agent" }, relation: "triggers", label: "invoke" },
+            { id: "agent-result", source: { itemId: "agent" }, target: { itemId: "result" }, relation: "produces", label: "output" },
+        ],
+        effects: [],
+        compositions: [],
+    },
+    "create:media": {
+        items: [
+            {
+                id: "hero",
+                type: "image",
+                position: { x: 80, y: 100 },
+                size: { width: 640, height: 360 },
+                rotation: 0,
+                source: { kind: "space-file", path: "assets/hero.webp" },
+                props: {},
+            },
+            {
+                id: "demo-video",
+                type: "video",
+                position: { x: 760, y: 100 },
+                size: { width: 480, height: 270 },
+                rotation: 0,
+                source: { kind: "space-file", path: "assets/demo.mp4" },
+                props: {},
+            },
+            {
+                id: "soundtrack",
+                type: "audio",
+                position: { x: 80, y: 500 },
+                size: { width: 400, height: 96 },
+                rotation: 0,
+                source: { kind: "space-file", path: "assets/soundtrack.mp3" },
+                props: {},
+            },
+            {
+                id: "brief",
+                type: "file",
+                position: { x: 520, y: 500 },
+                size: { width: 320, height: 180 },
+                rotation: 0,
+                source: { kind: "space-file", path: "docs/brief.md" },
+                props: {},
+            },
+        ],
+        connections: [],
+        effects: [],
+        compositions: [],
+    },
+    "create:animation": {
+        items: [
+            {
+                id: "title",
+                type: "text",
+                position: { x: 120, y: 80 },
+                size: { width: 320, height: 48 },
+                rotation: 0,
+                props: { text: "Launch", fontSize: 32 },
+                style: { color: "brand" },
+            },
+            {
+                id: "stroke",
+                type: "draw",
+                rotation: 0,
+                props: { points: [{ x: 2, y: 98, p: 0.5 }, { x: 90, y: 2, p: 0.5 }, { x: 178, y: 98, p: 0.5 }] },
+                style: { color: "violet", strokeWidth: 4 },
+            },
+        ],
+        connections: [],
+        effects: [{
+                id: "pulse-title",
+                target: { type: "item", itemId: "title" },
+                kind: "effects.pulse",
+                kindVersion: 1,
+                lifecycle: "when-visible",
+                timeOrigin: "visible",
+                seed: "pulse-title",
+                params: { amount: 0.04, period: 1600 },
+            }],
+        compositions: [
+            {
+                id: "intro",
+                name: "Intro",
+                timeline: {
+                    duration: 800,
+                    tracks: [{
+                            id: "title-opacity",
+                            target: { type: "item", itemId: "title" },
+                            channel: "style.opacity",
+                            fill: "both",
+                            keyframes: [{ time: 0, value: 0 }, { time: 800, value: 1, easing: "ease-out-cubic" }],
+                        }],
+                },
+            },
+            {
+                id: "draw-stroke",
+                name: "Draw stroke",
+                timeline: {
+                    duration: 900,
+                    clips: [{
+                            id: "reveal-stroke",
+                            kind: "draw.reveal",
+                            kindVersion: 1,
+                            target: { type: "item", itemId: "stroke" },
+                            start: 0,
+                            duration: 900,
+                            easing: "ease-out-cubic",
+                            seed: "reveal-stroke",
+                        }],
+                },
+            },
+        ],
+    },
     "item:text": {
         id: "title",
         type: "text",
-        frame,
+        position: { x: 120, y: 80 },
+        size: { width: 320, height: 48 },
+        rotation: 0,
         props: { text: "Launch plan", fontSize: 32 },
         style: { color: "brand" },
     },
     "item:image": {
         id: "hero",
         type: "image",
-        frame: { x: 120, y: 160, width: 640, height: 360, rotation: 0 },
+        position: { x: 120, y: 160 },
+        size: { width: 640, height: 360 },
+        rotation: 0,
         source: { kind: "space-file", path: "assets/hero.webp" },
         props: {},
     },
     "item:geo": {
         id: "goal",
         type: "geo",
-        frame: { x: 120, y: 160, width: 280, height: 140, rotation: 0 },
+        position: { x: 120, y: 160 },
+        size: { width: 280, height: 140 },
+        rotation: 0,
         props: { shape: "rounded", text: "Ship" },
         style: { color: "green", fillOpacity: 0.12 },
     },
     "item:frame": {
         id: "scene",
         type: "frame",
-        frame: { x: 80, y: 60, width: 960, height: 540, rotation: 0 },
+        position: { x: 80, y: 60 },
+        size: { width: 960, height: 540 },
+        rotation: 0,
         props: { label: "Scene 1" },
         style: { color: "neutral" },
     },
     "item:draw": {
         id: "stroke",
         type: "draw",
-        frame: { x: 100, y: 100, width: 180, height: 100, rotation: 0 },
-        props: { points: [{ x: 0, y: 80, p: 0.5 }, { x: 90, y: 10, p: 0.8 }, { x: 180, y: 70, p: 0.5 }] },
+        rotation: 0,
+        props: { points: [{ x: 102, y: 198, p: 0.5 }, { x: 190, y: 102, p: 0.5 }, { x: 278, y: 198, p: 0.5 }] },
         style: { color: "violet", strokeWidth: 4 },
     },
     "item:arrow": {
         id: "arrow",
         type: "arrow",
-        frame: { x: 100, y: 100, width: 260, height: 100, rotation: 0 },
+        rotation: 0,
         props: { start: { x: 116, y: 150 }, end: { x: 344, y: 150 }, bend: 0, arrowStart: false, arrowEnd: true, label: "next" },
         style: { color: "brand", strokeWidth: 2.5 },
     },
     "item:video": {
         id: "demo-video",
         type: "video",
-        frame: { x: 120, y: 160, width: 640, height: 360, rotation: 0 },
+        position: { x: 120, y: 160 },
+        size: { width: 640, height: 360 },
+        rotation: 0,
         source: { kind: "space-file", path: "assets/demo.mp4" },
         props: {},
     },
     "item:audio": {
         id: "soundtrack",
         type: "audio",
-        frame: { x: 120, y: 540, width: 480, height: 96, rotation: 0 },
+        position: { x: 120, y: 540 },
+        size: { width: 480, height: 96 },
+        rotation: 0,
         source: { kind: "space-file", path: "assets/soundtrack.mp3" },
         props: {},
     },
     "item:file": {
         id: "brief",
         type: "file",
-        frame: { x: 120, y: 160, width: 360, height: 220, rotation: 0 },
+        position: { x: 120, y: 160 },
+        size: { width: 360, height: 220 },
+        rotation: 0,
         source: { kind: "space-file", path: "docs/brief.md" },
         props: {},
     },
     "item:task": {
         id: "task",
         type: "task",
-        frame: { x: 120, y: 160, width: 420, height: 240, rotation: 0 },
+        position: { x: 120, y: 160 },
+        size: { width: 420, height: 240 },
+        rotation: 0,
         props: { taskRunId: "task-run-id", snapshot: { taskType: "generation", status: "running", title: "Generate concept", artifactCount: 0, artifacts: [] } },
     },
     "effect:pulse": {
@@ -87,28 +254,20 @@ const templates = {
         target: { type: "item", itemId: "title" },
         kind: "effects.pulse",
         kindVersion: 1,
-        enabled: true,
         lifecycle: "when-visible",
         timeOrigin: "visible",
-        layer: "front",
         seed: "pulse-title",
         params: { amount: 0.04, period: 1600 },
-        assetRefs: [],
-        metadata: {},
     },
     "effect:float": {
         id: "float-hero",
         target: { type: "item", itemId: "hero" },
         kind: "effects.float",
         kindVersion: 1,
-        enabled: true,
         lifecycle: "when-visible",
         timeOrigin: "visible",
-        layer: "front",
         seed: "float-hero",
         params: { distance: 8, period: 2200 },
-        assetRefs: [],
-        metadata: {},
     },
     "composition:fade": {
         id: "intro",
@@ -119,63 +278,87 @@ const templates = {
                     id: "title-opacity",
                     target: { type: "item", itemId: "title" },
                     channel: "style.opacity",
-                    channelVersion: 1,
-                    interpolation: "linear",
                     fill: "both",
                     keyframes: [
                         { time: 0, value: 0 },
                         { time: 800, value: 1, easing: "ease-out-cubic" },
                     ],
-                    metadata: {},
                 }],
-            clips: [],
-            markers: [],
         },
-        playback: { loop: false, endBehavior: "hold", reducedMotion: { mode: "base" } },
-        metadata: {},
     },
     "composition:reveal": {
         id: "reveal",
         name: "Reveal",
         timeline: {
-            duration: 900,
-            tracks: [{ id: "title-opacity", target: { type: "item", itemId: "title" }, channel: "style.opacity", channelVersion: 1, interpolation: "linear", fill: "both", keyframes: [{ time: 0, value: 0 }, { time: 600, value: 1 }], metadata: {} }],
-            clips: [{ id: "reveal-title", kind: "text.reveal", kindVersion: 1, target: { type: "item", itemId: "title" }, start: 0, duration: 600, layer: "content", fill: "both", easing: "ease-out-cubic", params: { mode: "words" }, assetRefs: [], seed: "reveal-title", metadata: {} }],
-            markers: [],
+            duration: 600,
+            clips: [{ id: "reveal-title", kind: "text.reveal", kindVersion: 1, target: { type: "item", itemId: "title" }, start: 0, duration: 600, fill: "both", easing: "ease-out-cubic", params: { mode: "words" }, seed: "reveal-title" }],
         },
-        playback: { loop: false, endBehavior: "hold", reducedMotion: { mode: "base" } },
-        metadata: {},
     },
     "composition:motion-path": {
         id: "motion",
         name: "Motion path",
         timeline: {
             duration: 1200,
-            tracks: [],
-            clips: [{ id: "move-hero", kind: "motion.path", kindVersion: 1, target: { type: "item", itemId: "hero" }, start: 0, duration: 1200, layer: "content", fill: "both", easing: "ease-in-out-cubic", params: { points: [{ x: 0, y: 0 }, { x: 160, y: -40 }, { x: 320, y: 0 }], orient: true }, assetRefs: [], seed: "move-hero", metadata: {} }],
-            markers: [],
+            clips: [{ id: "move-hero", kind: "motion.path", kindVersion: 1, target: { type: "item", itemId: "hero" }, start: 0, duration: 1200, fill: "both", easing: "ease-in-out-cubic", params: { points: [{ x: 0, y: 0 }, { x: 160, y: -40 }, { x: 320, y: 0 }], orient: true }, seed: "move-hero" }],
+        },
+    },
+    "composition:draw-reveal": {
+        id: "draw-stroke",
+        name: "Draw stroke",
+        timeline: {
+            duration: 900,
+            clips: [{ id: "reveal-stroke", kind: "draw.reveal", kindVersion: 1, target: { type: "item", itemId: "stroke" }, start: 0, duration: 900, easing: "ease-out-cubic", seed: "reveal-stroke" }],
+        },
+    },
+    "composition:trail": {
+        id: "move-with-trail",
+        name: "Move with trail",
+        timeline: {
+            duration: 1200,
+            clips: [
+                { id: "move-hero", kind: "motion.path", kindVersion: 1, target: { type: "item", itemId: "hero" }, start: 0, duration: 1200, easing: "ease-in-out-cubic", fill: "both", params: { points: [{ x: 0, y: 0 }, { x: 320, y: 0 }] }, seed: "move-hero" },
+                { id: "trail-hero", kind: "effects.trail", kindVersion: 1, target: { type: "item", itemId: "hero" }, start: 0, duration: 1200, params: { alpha: 0.48 }, seed: "trail-hero" },
+            ],
+        },
+    },
+    "composition:impact": {
+        id: "impact",
+        name: "Impact",
+        timeline: {
+            duration: 500,
+            clips: [{ id: "impact-ring", kind: "effects.impact", kindVersion: 1, target: { type: "board" }, start: 0, duration: 500, layer: "front", params: { center: { x: 400, y: 300 }, radius: 120 }, seed: "impact-ring" }],
+        },
+    },
+    "composition:flash": {
+        id: "flash",
+        name: "Flash",
+        timeline: {
+            duration: 300,
+            clips: [{ id: "screen-flash", kind: "effects.flash", kindVersion: 1, target: { type: "board" }, start: 0, duration: 300, layer: "screen", params: { alpha: 0.3 }, seed: "screen-flash" }],
         },
-        playback: { loop: false, endBehavior: "hold", reducedMotion: { mode: "base" } },
-        metadata: {},
     },
     "composition:particles": {
         id: "celebrate",
         name: "Celebrate",
         timeline: {
             duration: 1000,
-            tracks: [],
-            clips: [{ id: "particles", kind: "effects.particles", kindVersion: 1, target: { type: "board" }, start: 0, duration: 1000, layer: "front", fill: "none", easing: "linear", params: { count: 420, bounds: { x: 0, y: 0, width: 800, height: 600 } }, assetRefs: [], seed: "particles", metadata: {} }],
-            markers: [],
+            clips: [{ id: "particles", kind: "effects.particles", kindVersion: 1, target: { type: "board" }, start: 0, duration: 1000, layer: "front", params: { count: 420, bounds: { x: 0, y: 0, width: 800, height: 600 } }, seed: "particles" }],
+        },
+        playback: { endBehavior: "reset" },
+    },
+    "composition:camera-shake": {
+        id: "shake",
+        name: "Camera shake",
+        timeline: {
+            duration: 500,
+            clips: [{ id: "shake-camera", kind: "camera.shake", kindVersion: 1, target: { type: "camera" }, start: 0, duration: 500, layer: "screen", params: { amount: 8, frequency: 28 }, seed: "shake-camera" }],
         },
-        playback: { loop: false, endBehavior: "reset", reducedMotion: { mode: "base" } },
-        metadata: {},
     },
     "composition:camera-focus": {
         id: "tour",
         name: "Tour",
         timeline: {
             duration: 1000,
-            tracks: [],
             clips: [{
                     id: "focus-title",
                     kind: "camera.focus",
@@ -187,14 +370,9 @@ const templates = {
                     fill: "forwards",
                     easing: "ease-out-cubic",
                     params: { focus: { type: "item", itemId: "title" }, fit: "contain", padding: 32 },
-                    assetRefs: [],
                     seed: "focus-title",
-                    metadata: {},
                 }],
-            markers: [],
         },
-        playback: { loop: false, endBehavior: "hold", reducedMotion: { mode: "base" } },
-        metadata: {},
     },
 };
 export const BOARD_EXAMPLE_KEYS = Object.keys(templates);
@@ -206,19 +384,28 @@ export function boardExample(kind, type) {
     return template;
 }
 export function registerBoardExampleCommands(boards) {
-    boards.command("examples <kind> [type]")
+    boards.command("examples [kind] [type]")
         .description("Print editable semantic JSON templates")
+        .option("--list", "List available examples")
         .addHelpText("after", `
 Kinds:
-  create
+  create [workflow|media|animation]
+  batch basic
   item text|image|video|audio|file|task|geo|frame|draw|arrow
   effect pulse|float
-  composition fade|reveal|motion-path|particles|camera-focus
+  composition fade|reveal|draw-reveal|motion-path|trail|impact|flash|particles|camera-shake|camera-focus
 
 Examples:
+  cohub boards examples --list
+  cohub boards examples create workflow > board.json
+  cohub boards examples batch basic > changes.json
   cohub boards examples item text > item.json
   cohub boards examples composition fade > intro.json`)
-        .action((kind, type) => {
+        .action((kind, type, options) => {
+        if (options.list)
+            return json(BOARD_EXAMPLE_KEYS);
+        if (!kind)
+            throw new Error("Example kind is required. Use --list to see available examples.");
         json(boardExample(kind, type));
     });
 }

package/dist/commands/boards/items.js

@@ -1,8 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { BoardAuthoringItemSchema, BoardItemPatchSchema, } from "@neta-art/cohub";
+import { computeArrowFrame, computeDrawBounds } from "@neta-art/cohub/board";
 import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
 import { handleHttp, json, jsonRequested, ok, table } from "../../output.js";
-import { resolvedBoard, withJson, } from "./context.js";
+import { readInput, readOptions, resolvedBoard, withJson, } from "./context.js";
 const baseVersion = (value, fallback) => {
     if (value === undefined)
         return fallback;
@@ -38,23 +39,39 @@ function mutationOptions(command) {
         .option("--mutation-id <id>", "Stable id for safe retries")
         .option("--dry-run", "Validate on the server (references, version, cascade) without writing");
 }
+function itemLayout(item) {
+    if ("position" in item) {
+        const size = "size" in item ? item.size : undefined;
+        return { x: item.position.x, y: item.position.y, width: size?.width ?? "", height: size?.height ?? "" };
+    }
+    if (item.type === "draw") {
+        const points = item.props.points;
+        const strokeWidth = item.style?.strokeWidth ?? 4;
+        const bounds = computeDrawBounds(points, strokeWidth);
+        return { x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height };
+    }
+    const bounds = computeArrowFrame({
+        start: item.props.start,
+        end: item.props.end,
+        bend: item.props.bend,
+        size: item.style?.strokeWidth ?? 2.5,
+    });
+    return { x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height };
+}
 export function registerBoardItemCommands(boards) {
     const items = boards.command("items").description("Author Board items with semantic JSON");
-    withJson(items.command("list <board>").alias("ls").description("List semantic Board items"))
+    readOptions(withJson(items.command("list <board>").alias("ls").description("List semantic Board items")))
         .action(async (target, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const snapshot = await board.authoring();
+            const snapshot = await board.authoring(readInput(options, "items"));
             const items = snapshot.items ?? [];
             if (jsonRequested(options))
                 return json(items);
             table(items.map((item) => ({
                 id: item.id,
                 type: item.type,
-                x: item.frame.x,
-                y: item.frame.y,
-                width: item.frame.width,
-                height: item.frame.height,
+                ...itemLayout(item),
             })), [
                 { key: "id", label: "ID" },
                 { key: "type", label: "TYPE" },
@@ -68,12 +85,39 @@ export function registerBoardItemCommands(boards) {
             handleHttp(cause);
         }
     });
+    withJson(items.command("get <board> <item-id>").description("Get one complete Board item"))
+        .action(async (target, itemId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            const snapshot = await board.authoring({ include: ["items"], itemIds: [itemId] });
+            const item = snapshot.items?.[0];
+            if (!item)
+                throw new Error(`Item not found: ${itemId}`);
+            if (jsonRequested(options))
+                return json(item);
+            table([{
+                    id: item.id,
+                    type: item.type,
+                    ...itemLayout(item),
+                }], [
+                { key: "id", label: "ID" },
+                { key: "type", label: "TYPE" },
+                { key: "x", label: "X" },
+                { key: "y", label: "Y" },
+                { key: "width", label: "WIDTH" },
+                { key: "height", label: "HEIGHT" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
     mutationOptions(items.command("create <board>")
         .description("Create one item")
         .requiredOption("-i, --input <file>", "Board Item JSON; use - for stdin")
         .addHelpText("after", `
 Minimal text item:
-  {"id":"title","type":"text","frame":{"x":120,"y":80,"width":320,"height":48,"rotation":0},"props":{"text":"Launch plan","fontSize":32},"style":{"color":"brand"}}`))
+  {"id":"title","type":"text","position":{"x":120,"y":80},"size":{"width":320,"height":48},"props":{"text":"Launch plan","fontSize":32},"style":{"color":"brand"}}`))
         .action(async (target, options) => {
         try {
             const value = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
@@ -92,7 +136,7 @@ Minimal text item:
         .addHelpText("after", `
 Objects merge recursively, arrays replace, and null clears optional fields.
 Move and rename a text item without replacing its size or font:
-  {"frame":{"x":160,"y":120},"props":{"text":"Updated"}}`))
+  {"position":{"x":160,"y":120},"props":{"text":"Updated"}}`))
         .action(async (target, itemId, options) => {
         try {
             const value = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);

package/dist/commands/boards.d.ts

@@ -7,4 +7,11 @@ export declare function parseViewport(value?: string): {
     width: number;
     height: number;
 } | undefined;
+export declare function showCreated(result: {
+    board: {
+        id: string;
+        title: string;
+        version: number;
+    };
+}, path: string): void;
 export declare function registerBoards(program: Command): Command;

package/dist/commands/boards.js

@@ -38,8 +38,9 @@ export function parseViewport(value) {
         throw new Error("viewport width and height must be greater than zero");
     return { x, y, width, height };
 }
-function showCreated(result) {
-    table([result.board], [
+export function showCreated(result, path) {
+    table([{ path, ...result.board }], [
+        { key: "path", label: "Path" },
         { key: "id", label: "ID" },
         { key: "title", label: "Title" },
         { key: "version", label: "Version" },
@@ -211,7 +212,7 @@ function registerExportCommand(boards) {
 export function registerBoards(program) {
     const boards = program
         .command("boards")
-        .description("Inspect and update Boards")
+        .description("Inspect and update Boards by ID or .board path")
         .hook("preAction", () => { resolveSpace(boards); });
     withJson(boards.command("create <path>")
         .description("Create a Board")
@@ -240,9 +241,9 @@ Generate an editable seed:
             };
             const result = await createClient().space(resolveSpace(boards)).boards.create(input);
             if (jsonRequested(options))
-                return outJson(result);
-            ok(`Board created: ${result.board.id}`);
-            showCreated(result);
+                return outJson({ ...result, path });
+            ok(`Board created: ${path}`);
+            showCreated(result, path);
         }
         catch (cause) {
             handleHttp(cause);
@@ -252,10 +253,13 @@ Generate an editable seed:
         .alias("get")
         .description("Show Board metadata and semantic resource counts")
         .addHelpText("after", `
-Inspect content with:
+Inspect resources with:
   cohub boards items list <board> --json
+  cohub boards connections list <board> --json
   cohub boards effects list <board> --json
-  cohub boards compositions list <board> --json`))
+  cohub boards compositions list <board> --json
+Apply multiple changes atomically:
+  cohub boards batch <board> --input changes.json --dry-run`))
         .action(async (target, options) => {
         try {
             const spaceId = resolveSpace(boards);
@@ -273,6 +277,9 @@ Inspect content with:
         .description("Show authoring schemas and runtime capabilities")
         .addHelpText("after", `
 Use --json for complete Item, patch, mutation, effect, Composition, and create JSON Schemas.
+Coordinates:
+  draw points and arrow start/end points are world-space.
+  Position and size are optional; Board geometry derives the persisted frame automatically.
 Use boards examples for editable starter JSON.`))
         .action(async (target, options) => {
         try {
@@ -314,7 +321,8 @@ Use boards examples for editable starter JSON.`))
     });
     registerBoardDomainCommands(boards);
     registerExportCommand(boards);
-    withJson(boards.command("play <board> <composition-id>")
+    const playback = boards.command("playback").description("Control shared Board playback");
+    withJson(playback.command("play <board> <composition-id>")
         .description("Start shared playback")
         .option("--position <time>", "Initial position in milliseconds")
         .option("--time-scale <scale>", "Playback speed from 0 to 4")
@@ -358,11 +366,11 @@ Use boards examples for editable starter JSON.`))
             handleHttp(cause);
         }
     };
-    withJson(boards.command("pause <board> <playback-id>")
+    withJson(playback.command("pause <board> <playback-id>")
         .description("Pause playback")
         .option("--command-id <id>", "Idempotency command ID"))
         .action(playbackAction("pause"));
-    withJson(boards.command("seek <board> <playback-id> <position>")
+    withJson(playback.command("seek <board> <playback-id> <position>")
         .description("Seek playback")
         .option("--command-id <id>", "Idempotency command ID"))
         .action(async (target, playbackId, position, options) => {
@@ -383,7 +391,7 @@ Use boards examples for editable starter JSON.`))
             handleHttp(cause);
         }
     });
-    withJson(boards.command("stop <board> <playback-id>")
+    withJson(playback.command("stop <board> <playback-id>")
         .description("Stop playback")
         .option("--command-id <id>", "Idempotency command ID"))
         .action(playbackAction("stop"));

package/dist/output.js

@@ -75,6 +75,27 @@ function errorMessageFromBody(body) {
         return errorBody.message;
     return null;
 }
+function diagnosticDetailFromBody(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const diagnostics = body.diagnostics;
+    if (!Array.isArray(diagnostics) || diagnostics.length === 0)
+        return null;
+    const lines = diagnostics.slice(0, 8).flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const diagnostic = item;
+        if (typeof diagnostic.message !== "string" || !diagnostic.message.trim())
+            return [];
+        const path = typeof diagnostic.path === "string" ? diagnostic.path : "";
+        const message = diagnostic.message.replace(path ? `${path}: ` : "", "");
+        return [`${path ? `${path}: ` : ""}${message}`];
+    });
+    if (lines.length === 0)
+        return null;
+    const suffix = diagnostics.length > lines.length ? ` (+${diagnostics.length - lines.length} more)` : "";
+    return `${lines.join("; ")}${suffix}`;
+}
 function debugErrorMetaFromBody(body) {
     if (!body || typeof body !== "object")
         return [];
@@ -139,7 +160,10 @@ export function handleHttp(e) {
     const presentation = errorPresentationFromHttpError(e);
     const message = presentation?.message ?? errorMessageFromBody(body) ?? (e instanceof Error ? e.message : String(e));
     const fetchDetail = fetchFailureDetail(e);
+    const diagnosticDetail = diagnosticDetailFromBody(body);
     const detailParts = [];
+    if (diagnosticDetail)
+        detailParts.push(diagnosticDetail);
     if (presentation?.detail)
         detailParts.push(presentation.detail);
     if (process.env.COHUB_DEBUG_ERRORS) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "6.2.2",
+  "version": "6.4.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,7 +19,7 @@
     "commander": "^15.0.0",
     "pixi.js": "^8.20.1",
     "sharp": "^0.35.4",
-    "@neta-art/cohub": "8.5.1"
+    "@neta-art/cohub": "8.7.0"
   },
   "publishConfig": {
     "access": "public"

package/dist/commands/boards/nodes.d.ts

@@ -1,3 +0,0 @@
-import type { Command } from "commander";
-/** Connection shortcuts; Item authoring lives in ./items.ts. */
-export declare function registerBoardNodeCommands(boards: Command): void;

package/dist/commands/boards/nodes.js

@@ -1,50 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { createBoardConnection } from "@neta-art/cohub/board";
-import { mutateSemantic } from "./context.js";
-import { handleHttp } from "../../output.js";
-import { resolvedBoard, showUpdated, withJson, } from "./context.js";
-/** Connection shortcuts; Item authoring lives in ./items.ts. */
-export function registerBoardNodeCommands(boards) {
-    withJson(boards.command("connect <board> <source> <target>")
-        .description("Connect two Board items")
-        .option("--id <id>", "Connection id")
-        .option("--relation <relation>", "Relation type")
-        .option("--direction <direction>", "none, forward, backward, or both", "forward")
-        .option("--label <label>", "Connection label")
-        .option("--source-port <id>", "Source port id")
-        .option("--target-port <id>", "Target port id"))
-        .action(async (target, source, destination, options) => {
-        try {
-            const direction = options.direction ?? "forward";
-            if (!["none", "forward", "backward", "both"].includes(direction)) {
-                throw new Error("--direction must be none, forward, backward, or both");
-            }
-            const board = await resolvedBoard(boards, target);
-            const connection = createBoardConnection({
-                id: options.id ?? randomUUID(),
-                sourceItemId: source,
-                targetItemId: destination,
-                relation: options.relation,
-                direction: direction,
-                label: options.label,
-                sourcePortId: options.sourcePort,
-                targetPortId: options.targetPort,
-            });
-            showUpdated(await mutateSemantic(board, [{ type: "connection.create", connection }]), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-    withJson(boards.command("disconnect <board> <connection-id>")
-        .description("Remove a Board connection"))
-        .action(async (target, connectionId, options) => {
-        try {
-            const board = await resolvedBoard(boards, target);
-            showUpdated(await mutateSemantic(board, [{ type: "connection.delete", connectionId }]), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-}