@neta-art/cohub-cli 6.2.1 → 6.3.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
@@ -285,9 +289,9 @@ overwrites files; it never deletes existing ones.
 
 Confirm before deleting files or directories.
 
-## Works
+## Apps
 
-Publish and manage Work entries from a Space workspace. Public Work URLs require a username and a Space slug.
+Publish and manage Apps from a Space workspace. Public App URLs require a username and a Space slug.
 
 `--file` and `--dir` take paths relative to the Space workspace — the same paths
 `spaces files ls` shows, not your local filesystem. To publish local build
@@ -297,51 +301,51 @@ Space-side path.
 ```bash
 cohub profile update --username <username>
 cohub spaces update <spaceId> --slug <space-slug>
-cohub -s <spaceId> works ls --json
-cohub works get <workId|url|username/space/work> --json
-cohub works stats <workId|url|username/space/work>
-cohub works download <workId|url|username/space/work> --output <path>
-cohub -s <spaceId> works publish demo --file dist/index.html
-cohub -s <spaceId> works publish site --dir dist
-cohub -s <spaceId> works publish app --port 3000
-cohub works publish-version <workId>
-cohub works versions <workId> --json
-cohub works rm <workId> --yes
+cohub -s <spaceId> apps ls --json
+cohub apps get <appId|url|username/space/app> --json
+cohub apps stats <appId|url|username/space/app>
+cohub apps download <appId|url|username/space/app> --output <path>
+cohub -s <spaceId> apps publish demo --file dist/index.html
+cohub -s <spaceId> apps publish site --dir dist
+cohub -s <spaceId> apps publish app --port 3000
+cohub apps publish-version <appId>
+cohub apps versions <appId> --json
+cohub apps rm <appId> --yes
 ```
 
-Resolve a published Work by public identity:
+Resolve a published App by public identity:
 
 ```bash
-cohub works resolve <workSlug> --owner <username> --space-slug <spaceSlug>
+cohub apps resolve <appSlug> --owner <username> --space-slug <spaceSlug>
 ```
 
-Use `--json` for machine-readable output. `works get`, `works stats`, and `works download` also accept `cohub://works/<username>/<space>/<work>` mention URIs. `works stats` reports total, 24-hour, 7-day, and 30-day views with a source breakdown. Download restores newly published file and directory artifacts directly from the CDN with checksum verification. HTML files with companion assets are restored as directory bundles; Board and port Works are not downloadable. The resolve command remains available for explicit slug-based lookup.
+Use `--json` for machine-readable output. `apps get`, `apps stats`, and `apps download` also accept `app://<username>/<space>/<app>` mention URIs. `apps stats` reports total, 24-hour, 7-day, and 30-day views with a source breakdown. Download restores newly published file and directory artifacts directly from the CDN with checksum verification. HTML files with companion assets are restored as directory bundles; Board and port apps are not downloadable. The resolve command remains available for explicit slug-based lookup.
 
-Realtime rooms use a published Work's runtime identity, so they are available
+Realtime rooms use a published App's runtime identity, so they are available
 through `client.app.realtime` in the SDK rather than as CLI commands.
 
 ## Drive the Cohub UI
 
-Show a file or Work preview in the Cohub tab that started the current work, and call
-methods the Work exposes.
+Show a file or App preview in the Cohub tab that started the current session, and call
+methods the App exposes.
 
 ```bash
-cohub desktop open <workId|url|cohub://works/...|username/space/work|file://path>
+cohub desktop open <appId|url|app://...|username/space/app|file://path>
 cohub desktop open file://src/main.ts
-cohub desktop open work://alice/studio/launch
-cohub desktop open <work-or-file> --call selection.get
-cohub desktop open <work> --call board.focus --data '{"nodeId":"n1"}'
-cohub desktop open <work> --call report.build --input payload.json --json
+cohub desktop open app://alice/studio/launch
+cohub desktop open <app-or-file> --call selection.get
+cohub desktop open <app> --call board.focus --data '{"nodeId":"n1"}'
+cohub desktop open <app> --call report.build --input payload.json --json
 ```
 
-`ui preview` accepts `file://` Space-relative paths, `work://` Work references, and
+`ui preview` accepts `file://` Space-relative paths, `app://` App references, and
 legacy bare targets. A bare target checks the current Space for a file first, then
-falls back to the same Work references as `works get`. Showing a preview is
+falls back to the same App references as `apps get`. Showing a preview is
 idempotent: repeating it re-activates the same tab and refreshes any launch state
-carried by the reference. With `--call`, the command waits for the Work to announce readiness, invokes the method,
-and waits for the Work to complete the same UI command with `client.ui.reportResult()`.
+carried by the reference. With `--call`, the command waits for the App to announce readiness, invokes the method,
+and waits for the App to complete the same UI command with `client.ui.reportResult()`.
 
-Work authors decide what is callable by registering handlers inside the Work:
+App authors decide what is callable by registering handlers inside the App:
 
 ```ts
 client.app.surface.handle("image.open", async (input, { commandId }) => {
@@ -349,7 +353,7 @@ client.app.surface.handle("image.open", async (input, { commandId }) => {
 });
 ```
 
-A Work answers only a Cohub app origin, so a third-party site that embeds it
+An App answers only a Cohub app origin, so a third-party site that embeds it
 cannot invoke these methods.
 
 Retrying with the same `--command-id` re-delivers the command rather than
@@ -361,7 +365,7 @@ Delivery is at-least-once. Deduplication lives in the receiving tab's memory, so
 retry that spans a page reload can run a `--call` method a second time. Prefer
 methods that are safe to repeat.
 
-Commands reach only the frontend instance that originated the current work,
+Commands reach only the frontend instance that originated the current session,
 resolved from request provenance (`X-Cohub-Source-Client`, propagated into the
 Sandbox as `COHUB_SOURCE_CLIENT_ID`). They cannot target another user's browser,
 and offer no DOM access or script evaluation. Pass `--client` to address a
@@ -414,7 +418,7 @@ Confirm before enabling, disabling, or deleting recurring scheduled prompts.
 
 Confirm before:
 
-- deleting files, directories, or Works
+- deleting files, directories, or Apps
 - creating scheduled or recurring prompts with side effects
 - enabling, disabling, or deleting recurring scheduled prompts
 - changing access policies, member roles, or membership

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,6 +1,12 @@
 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",
@@ -13,6 +19,134 @@ const templates = {
         effects: [],
         compositions: [],
     },
+    "create:workflow": {
+        items: [
+            {
+                id: "request",
+                type: "text",
+                frame: { x: 80, y: 190, width: 180, height: 48, rotation: 0 },
+                props: { text: "Request", fontSize: 28 },
+                style: { color: "brand" },
+            },
+            {
+                id: "agent",
+                type: "geo",
+                frame: { x: 360, y: 150, width: 240, height: 120, rotation: 0 },
+                props: { shape: "rounded", text: "Agent" },
+                style: { color: "blue", fillOpacity: 0.08 },
+            },
+            {
+                id: "result",
+                type: "geo",
+                frame: { x: 700, y: 150, 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",
+                frame: { x: 80, y: 100, width: 640, height: 360, rotation: 0 },
+                source: { kind: "space-file", path: "assets/hero.webp" },
+                props: {},
+            },
+            {
+                id: "demo-video",
+                type: "video",
+                frame: { x: 760, y: 100, width: 480, height: 270, rotation: 0 },
+                source: { kind: "space-file", path: "assets/demo.mp4" },
+                props: {},
+            },
+            {
+                id: "soundtrack",
+                type: "audio",
+                frame: { x: 80, y: 500, width: 400, height: 96, rotation: 0 },
+                source: { kind: "space-file", path: "assets/soundtrack.mp3" },
+                props: {},
+            },
+            {
+                id: "brief",
+                type: "file",
+                frame: { x: 520, y: 500, 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",
+                frame: { x: 120, y: 80, width: 320, height: 48, rotation: 0 },
+                props: { text: "Launch", fontSize: 32 },
+                style: { color: "brand" },
+            },
+            {
+                id: "stroke",
+                type: "draw",
+                frame: { x: 120, y: 180, width: 180, height: 100, 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",
@@ -45,7 +179,7 @@ const templates = {
         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 }] },
+        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 },
     },
     "item:arrow": {
@@ -87,28 +221,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 +245,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 +337,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 +351,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

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { BoardAuthoringItemSchema, BoardItemPatchSchema, } from "@neta-art/cohub";
 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;
@@ -40,11 +40,11 @@ function mutationOptions(command) {
 }
 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);
@@ -68,6 +68,36 @@ 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,
+                    x: item.frame.x,
+                    y: item.frame.y,
+                    width: item.frame.width,
+                    height: item.frame.height,
+                }], [
+                { 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")

package/dist/commands/boards.js

@@ -211,7 +211,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")
@@ -252,10 +252,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);
@@ -314,7 +317,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 +362,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 +387,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.1",
+  "version": "6.3.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -15,21 +15,21 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@neta-art/generation": "^0.1.22",
+    "@neta-art/generation": "^0.1.23",
     "commander": "^15.0.0",
-    "pixi.js": "^8.19.0",
-    "sharp": "^0.35.3",
-    "@neta-art/cohub": "8.5.0"
+    "pixi.js": "^8.20.1",
+    "sharp": "^0.35.4",
+    "@neta-art/cohub": "8.6.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.4.0",
     "typescript": "^7.0.2"
   },
   "optionalDependencies": {
-    "@napi-rs/canvas": "^1.0.2"
+    "@napi-rs/canvas": "^1.0.8"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

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);
-        }
-    });
-}