@neta-art/cohub-cli 4.0.0 → 5.0.0

package/README.md

@@ -157,72 +157,44 @@ cohub -s <spaceId> boards capabilities <boardId>
 cohub -s <spaceId> boards watch <boardId> --json
 ```
 
-Pass nodes, effects, and sequences as JSON when creating a Board. The path and
-title stay explicit in the command. Inspect `boards capabilities --json` for the
-supported node types, enums, and coordinate spaces.
-
-```json
-{
-  "nodes": [
-    {
-      "nodeId": "goal",
-      "type": "geo",
-      "parentId": null,
-      "orderKey": null,
-      "x": 80,
-      "y": 80,
-      "width": 240,
-      "height": 120,
-      "rotation": 0,
-      "refKind": null,
-      "refPath": null,
-      "refUrl": null,
-      "view": {},
-      "style": {},
-      "data": {
-        "geo": "rectangle",
-        "text": "Ship",
-        "color": "green",
-        "fillOpacity": 0.12
-      }
-    }
-  ]
-}
+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:
+
+```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
 ```
 
-Transactions are JSON objects without `boardId`; the bound Board supplies it.
-`txId` is generated when omitted, while `baseVersion` must be provided in the
-input or with `--base-version`:
-
-```json
-{
-  "baseVersion": 3,
-  "operations": [
-    {
-      "type": "board.patch",
-      "payload": { "patch": { "title": "Updated plan" } }
-    }
-  ]
-}
+Generate editable semantic JSON templates instead of authoring storage transactions:
+
+```bash
+cohub boards examples item text > item.json
+cohub boards items create <boardId> --input item.json
+
+cohub boards examples composition fade > intro.json
+cohub boards compositions apply <boardId> --input intro.json
+
+cohub boards examples effect pulse > effect.json
+cohub boards effects apply <boardId> --input effect.json
 ```
 
+Use `--mutation-id` or `--command-id` when a script needs a stable idempotency key across retries.
+
 ```bash
-cohub -s <spaceId> boards validate <boardId> --input transaction.json
-cat transaction.json | cohub -s <spaceId> boards apply <boardId> --input - --json
-cohub -s <spaceId> boards play <boardId> <sequenceId>
+cohub -s <spaceId> boards play <boardId> <compositionId>
 cohub -s <spaceId> boards seek <boardId> <playbackId> 400
 cohub -s <spaceId> boards stop <boardId> <playbackId>
 ```
 
-Pass `--tx-id` or `--command-id` when a script needs a stable idempotency key
-across retries.
-
 ## Search
 
 Search Spaces, Chats, and prior turns:

package/dist/board-export.js

@@ -9,7 +9,7 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
-import { boardBootstrapToDocument, boardImageKeySource, imageAssetKey, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
+import { boardAuthoringSnapshotToDocument, boardImageKeySource, imageAssetKey, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
 import { createBoardHeadlessRenderer, exportBoardImageBytes, } from "@neta-art/cohub/board/headless";
 import { resolveBoardId } from "./board-command-support.js";
 import { createClient } from "./client.js";
@@ -64,11 +64,11 @@ export function resolveBundledFonts() {
 export async function loadBoardDocument(spaceId, target) {
     const client = createClient();
     const boardId = await resolveBoardId(spaceId, target);
-    const bootstrap = await client.space(spaceId).board(boardId).inspect({ include: ["nodes"] });
+    const snapshot = await client.space(spaceId).board(boardId).authoring({ include: ["items", "connections"] });
     return {
-        document: boardBootstrapToDocument(bootstrap),
-        boardId: bootstrap.board.id,
-        title: bootstrap.board.title ?? null,
+        document: boardAuthoringSnapshotToDocument(snapshot),
+        boardId: snapshot.board.id,
+        title: snapshot.board.title ?? null,
     };
 }
 /**

package/dist/commands/board-domain.js

@@ -1,8 +1,10 @@
 import { registerBoardAnimationCommands } from "./boards/animation.js";
 import { registerBoardAppearanceCommands } from "./boards/appearance.js";
+import { registerBoardExampleCommands } from "./boards/examples.js";
 import { registerBoardItemCommands } from "./boards/items.js";
 import { registerBoardNodeCommands } from "./boards/nodes.js";
 export function registerBoardDomainCommands(boards) {
+    registerBoardExampleCommands(boards);
     registerBoardAppearanceCommands(boards);
     registerBoardNodeCommands(boards);
     registerBoardItemCommands(boards);

package/dist/commands/boards/animation.js

@@ -1,18 +1,18 @@
-import { boardCompositionApplyOperation, boardCompositionDeleteOperation, boardEffectDeleteOperation, boardEffectUpsertOperation, } from "@neta-art/cohub/board";
-import { BoardEffectSchema, parseBoardCompositionInput, } from "@neta-art/cohub";
+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 { resolvedBoard, showUpdated, withJson, } from "./context.js";
+import { mutateSemantic, 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"))
         .action(async (target, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.inspect({ include: ["effects"] });
+            const result = await board.authoring({ include: ["effects"] });
+            const effects = result.effects ?? [];
             if (jsonRequested(options))
-                return json(result.effects);
-            table(result.effects, [
+                return json(effects);
+            table(effects, [
                 { key: "id", label: "ID" },
                 { key: "kind", label: "KIND" },
                 { key: "enabled", label: "ENABLED" },
@@ -25,13 +25,19 @@ export function registerBoardAnimationCommands(boards) {
     });
     withJson(effects.command("apply <board>")
         .description("Atomically create or replace an effect")
-        .requiredOption("-i, --input <file>", "Board effect JSON; use - for stdin"))
+        .requiredOption("-i, --input <file>", "Board effect JSON; use - for stdin")
+        .addHelpText("after", `
+Create a template:
+  cohub boards examples effect pulse > effect.json
+
+Discover supported effect kinds:
+  cohub boards capabilities <board> --json`))
         .action(async (target, options) => {
         try {
             const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
-            const effect = BoardEffectSchema.omit({ boardId: true, revision: true }).parse(input);
+            const effect = parseBoardEffectInput(input);
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardEffectUpsertOperation(effect)] }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "effect.apply", effect }]), options);
         }
         catch (cause) {
             handleHttp(cause);
@@ -41,7 +47,7 @@ export function registerBoardAnimationCommands(boards) {
         .action(async (target, effectId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardEffectDeleteOperation(effectId)] }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "effect.delete", effectId }]), options);
         }
         catch (cause) {
             handleHttp(cause);
@@ -54,10 +60,11 @@ export function registerBoardAnimationCommands(boards) {
         .action(async (target, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.inspect({ include: ["compositions"] });
+            const result = await board.authoring({ include: ["compositions"] });
+            const compositions = result.compositions ?? [];
             if (jsonRequested(options))
-                return json(result.compositions);
-            table(result.compositions.map((composition) => ({
+                return json(compositions);
+            table(compositions.map((composition) => ({
                 id: composition.id,
                 name: composition.name,
                 duration: composition.timeline.duration,
@@ -81,8 +88,8 @@ export function registerBoardAnimationCommands(boards) {
         .action(async (target, compositionId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.inspect({ include: ["compositions"] });
-            const composition = result.compositions.find((item) => item.id === compositionId);
+            const result = await board.authoring({ include: ["compositions"] });
+            const composition = (result.compositions ?? []).find((item) => item.id === compositionId);
             if (!composition)
                 throw new Error(`Composition not found: ${compositionId}`);
             if (jsonRequested(options))
@@ -114,6 +121,8 @@ export function registerBoardAnimationCommands(boards) {
 Property changes use timeline.tracks with registered channels and keyframes.
 Procedural behavior such as text reveal, particles, and camera focus uses timeline.clips.
 Run boards capabilities to discover channels and clip schemas.
+Create an editable template with:
+  cohub boards examples composition fade > intro.json
 
 Minimal fade composition:
   {"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"}]}],"clips":[],"markers":[]},"playback":{"loop":false,"endBehavior":"hold","reducedMotion":{"mode":"base"}}}`))
@@ -122,9 +131,7 @@ Minimal fade composition:
             const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
             const composition = parseBoardCompositionInput(input);
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                build: () => [boardCompositionApplyOperation(composition)],
-            }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "composition.apply", composition }]), options);
         }
         catch (cause) {
             handleHttp(cause);
@@ -134,9 +141,7 @@ Minimal fade composition:
         .action(async (target, compositionId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                build: () => [boardCompositionDeleteOperation(compositionId)],
-            }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "composition.delete", compositionId }]), options);
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/boards/appearance.js

@@ -1,6 +1,6 @@
-import { BoardAppearanceSchema, DEFAULT_BOARD_APPEARANCE, boardAppearanceOperation, boardPlaybackPolicyOperation, boardTitleOperation, patchBoardAppearance, } from "@neta-art/cohub/board";
+import { BoardAppearanceSchema, DEFAULT_BOARD_APPEARANCE, patchBoardAppearance, } from "@neta-art/cohub/board";
 import { handleHttp } from "../../output.js";
-import { finite, resolvedBoard, showUpdated, withJson, } from "./context.js";
+import { finite, mutateSemantic, resolvedBoard, showUpdated, withJson, } from "./context.js";
 function appearanceFrom(metadata) {
     const parsed = BoardAppearanceSchema.safeParse(metadata.appearance);
     return parsed.success ? parsed.data : DEFAULT_BOARD_APPEARANCE;
@@ -10,7 +10,7 @@ export function registerBoardAppearanceCommands(boards) {
         .action(async (target, title, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardTitleOperation(title)] }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "board.patch", patch: { title } }]), options);
         }
         catch (cause) {
             handleHttp(cause);
@@ -41,24 +41,24 @@ Examples:
             if (opacity < 0 || opacity > 1)
                 throw new Error("opacity must be between 0 and 1");
             const board = await resolvedBoard(boards, target);
-            const result = await board.mutate({
-                build(current) {
-                    const appearance = appearanceFrom(current.board.metadata);
-                    const background = options.reset
-                        ? { kind: "solid" }
-                        : options.color
-                            ? { kind: "solid", color: options.color }
-                            : {
-                                kind: "image",
-                                imageUrl: options.image,
-                                fit: options.fit,
-                                position: options.position,
-                                opacity,
-                                color: appearance.background.color,
-                            };
-                    return [boardAppearanceOperation(patchBoardAppearance(appearance, { background }))];
-                },
-            });
+            const current = await board.summary();
+            const appearance = appearanceFrom(current.board.metadata);
+            const background = options.reset
+                ? { kind: "solid" }
+                : options.color
+                    ? { kind: "solid", color: options.color }
+                    : {
+                        kind: "image",
+                        imageUrl: options.image,
+                        fit: options.fit,
+                        position: options.position,
+                        opacity,
+                        color: appearance.background.color,
+                    };
+            const result = await mutateSemantic(board, [{
+                    type: "board.patch",
+                    patch: { metadataPatch: { appearance: patchBoardAppearance(appearance, { background }) } },
+                }], { baseVersion: current.board.version });
             showUpdated(result, options);
         }
         catch (cause) {
@@ -81,9 +81,13 @@ Examples:
                 ? null
                 : { compositionId: options.composition, delayMs };
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                build: (current) => [boardPlaybackPolicyOperation(current.board.metadata, policy)],
-            }), options);
+            const current = await board.summary();
+            const patch = policy
+                ? { metadataPatch: { playback: policy } }
+                : { metadata: { ...current.board.metadata, playback: undefined } };
+            if (!policy)
+                delete patch.metadata.playback;
+            showUpdated(await mutateSemantic(board, [{ type: "board.patch", patch }], { baseVersion: current.board.version }), options);
         }
         catch (cause) {
             handleHttp(cause);

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

@@ -1,12 +1,28 @@
+import type { BoardClient, BoardSemanticCommand } from "@neta-art/cohub";
 import type { Command } from "commander";
 export type JsonOptions = {
     json?: boolean;
 };
 export declare function withJson(command: Command): Command;
 export declare function finite(value: string | undefined, name: string, fallback?: number): number;
-export declare function resolvedBoard(boards: Command, target: string): Promise<import("@neta-art/cohub").BoardClient>;
+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.
+ */
+export declare function mutateSemantic(board: BoardClient, commands: BoardSemanticCommand[], options?: {
+    baseVersion?: number;
+    mutationId?: string;
+    dryRun?: boolean;
+}): Promise<import("@neta-art/cohub").BoardMutationReceipt>;
 export declare function showUpdated(result: {
     board: {
         version: number;
     };
+    status?: string;
+    outcome?: string;
+    replayed?: boolean;
 }, options: JsonOptions): void;

package/dist/commands/boards/context.js

@@ -18,8 +18,45 @@ export async function resolvedBoard(boards, target) {
     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.
+ */
+export async function mutateSemantic(board, commands, options = {}) {
+    const baseVersion = options.baseVersion ?? (await board.summary()).board.version;
+    const send = (version) => board.mutateSemantic({
+        mutationId: options.mutationId,
+        baseVersion: version,
+        dryRun: options.dryRun ?? false,
+        commands,
+    });
+    try {
+        return await send(baseVersion);
+    }
+    catch (cause) {
+        if (options.dryRun || !isVersionConflict(cause))
+            throw cause;
+        const retry = (await board.summary()).board.version;
+        return send(retry);
+    }
+}
+function isVersionConflict(error) {
+    return Boolean(error && typeof error === "object" &&
+        error.code === "VERSION_CONFLICT");
+}
 export function showUpdated(result, options) {
     if (jsonRequested(options))
         return json(result);
-    ok(`Board updated to version ${result.board.version}`);
+    if (result.outcome === "dry-run") {
+        ok(`Validated against Board version ${result.board.version}; no changes written`);
+        return;
+    }
+    if (result.outcome === "noop" || result.status === "validated") {
+        ok(`Board already matches the requested state at version ${result.board.version}`);
+        return;
+    }
+    ok(`Board updated to version ${result.board.version}${result.replayed ? " (replayed)" : ""}`);
 }

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

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const BOARD_EXAMPLE_KEYS: string[];
+export declare function boardExample(kind: string, type?: string): unknown;
+export declare function registerBoardExampleCommands(boards: Command): void;

package/dist/commands/boards/examples.js

@@ -0,0 +1,224 @@
+import { json } from "../../output.js";
+const frame = { x: 120, y: 80, width: 320, height: 48, rotation: 0 };
+const templates = {
+    "create": {
+        items: [{
+                id: "title",
+                type: "text",
+                frame,
+                props: { text: "Launch plan", fontSize: 32 },
+                style: { color: "brand" },
+            }],
+        connections: [],
+        effects: [],
+        compositions: [],
+    },
+    "item:text": {
+        id: "title",
+        type: "text",
+        frame,
+        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 },
+        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 },
+        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 },
+        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 }] },
+        style: { color: "violet", strokeWidth: 4 },
+    },
+    "item:arrow": {
+        id: "arrow",
+        type: "arrow",
+        frame: { x: 100, y: 100, width: 260, height: 100, 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 },
+        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 },
+        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 },
+        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 },
+        props: { taskRunId: "task-run-id", snapshot: { taskType: "generation", status: "running", title: "Generate concept", artifactCount: 0, artifacts: [] } },
+    },
+    "effect:pulse": {
+        id: "pulse-title",
+        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",
+        name: "Intro",
+        timeline: {
+            duration: 800,
+            tracks: [{
+                    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: [],
+        },
+        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: [],
+        },
+        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: [],
+        },
+        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",
+                    kindVersion: 1,
+                    target: { type: "camera" },
+                    start: 0,
+                    duration: 700,
+                    layer: "screen",
+                    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);
+export function boardExample(kind, type) {
+    const key = type ? `${kind}:${type}` : kind;
+    const template = templates[key];
+    if (!template)
+        throw new Error(`Unknown Board example: ${key}`);
+    return template;
+}
+export function registerBoardExampleCommands(boards) {
+    boards.command("examples <kind> [type]")
+        .description("Print editable semantic JSON templates")
+        .addHelpText("after", `
+Kinds:
+  create
+  item text|image|video|audio|file|task|geo|frame|draw|arrow
+  effect pulse|float
+  composition fade|reveal|motion-path|particles|camera-focus
+
+Examples:
+  cohub boards examples item text > item.json
+  cohub boards examples composition fade > intro.json`)
+        .action((kind, type) => {
+        json(boardExample(kind, type));
+    });
+}

package/dist/commands/boards/items.js

@@ -14,34 +14,29 @@ const baseVersion = (value, fallback) => {
 };
 async function execute(boards, target, command, options) {
     const board = await resolvedBoard(boards, target);
-    const snapshot = await board.authoring();
+    const snapshot = await board.summary();
     const mutation = {
         mutationId: options.mutationId?.trim() || randomUUID(),
         baseVersion: baseVersion(options.baseVersion, snapshot.board.version),
+        dryRun: Boolean(options.dryRun),
         commands: [command],
     };
-    if (options.dryRun) {
-        const result = {
-            mutationId: mutation.mutationId,
-            status: "prepared",
-            board: { id: snapshot.board.id, version: snapshot.board.version },
-            commands: mutation.commands,
-        };
-        if (jsonRequested(options))
-            return json(result);
-        ok(`Prepared against Board version ${snapshot.board.version}; no server validation or write performed`);
-        return;
-    }
+    // Server-side validation: schema, version, references, cascade rules — the
+    // same checks the real write would run, just without persisting anything.
     const receipt = await board.mutateSemantic(mutation);
     if (jsonRequested(options))
         return json(receipt);
+    if (options.dryRun) {
+        ok(`Validated against Board version ${receipt.board.version}; no changes written`);
+        return;
+    }
     ok(`${receipt.replayed ? "Replayed" : "Applied"} mutation at Board version ${receipt.board.version}`);
 }
 function mutationOptions(command) {
     return withJson(command)
         .option("--base-version <version>", "Expected Board version; defaults to latest")
         .option("--mutation-id <id>", "Stable id for safe retries")
-        .option("--dry-run", "Prepare locally without server validation or writing");
+        .option("--dry-run", "Validate on the server (references, version, cascade) without writing");
 }
 export function registerBoardItemCommands(boards) {
     const items = boards.command("items").description("Author Board items with semantic JSON");
@@ -50,9 +45,10 @@ export function registerBoardItemCommands(boards) {
         try {
             const board = await resolvedBoard(boards, target);
             const snapshot = await board.authoring();
+            const items = snapshot.items ?? [];
             if (jsonRequested(options))
-                return json(snapshot.items);
-            table(snapshot.items.map((item) => ({
+                return json(items);
+            table(items.map((item) => ({
                 id: item.id,
                 type: item.type,
                 x: item.frame.x,

package/dist/commands/boards/nodes.js

@@ -1,5 +1,6 @@
 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. */
@@ -21,17 +22,15 @@ export function registerBoardNodeCommands(boards) {
             const board = await resolvedBoard(boards, target);
             const connection = createBoardConnection({
                 id: options.id ?? randomUUID(),
-                sourceNodeId: source,
-                targetNodeId: destination,
+                sourceItemId: source,
+                targetItemId: destination,
                 relation: options.relation,
                 direction: direction,
                 label: options.label,
                 sourcePortId: options.sourcePort,
                 targetPortId: options.targetPort,
             });
-            showUpdated(await board.mutate({
-                build: () => [{ type: "connection.create", payload: { connection } }],
-            }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "connection.create", connection }]), options);
         }
         catch (cause) {
             handleHttp(cause);
@@ -42,9 +41,7 @@ export function registerBoardNodeCommands(boards) {
         .action(async (target, connectionId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                build: () => [{ type: "connection.delete", payload: { connectionId } }],
-            }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "connection.delete", connectionId }]), options);
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/boards.d.ts

@@ -1,15 +1,10 @@
-import type { BoardInspectInput, BoardTransactionInput } from "@neta-art/cohub";
 import type { Command } from "commander";
 import { parseBoardJsonObject } from "../board-command-support.js";
-declare const INSPECT_SECTIONS: readonly ["nodes", "connections", "effects", "compositions", "playback"];
-type InspectSection = (typeof INSPECT_SECTIONS)[number];
 export declare const parseJsonObject: typeof parseBoardJsonObject;
-export declare function readJsonObject(source: string, maxBytes?: number): Promise<Record<string, unknown>>;
-export declare function parseInspectSections(value?: string): InspectSection[] | undefined;
-export declare function parseViewport(value?: string): BoardInspectInput["viewport"];
-export declare function createTransactionInput(input: Record<string, unknown>, options: {
-    txId?: string;
-    baseVersion?: string;
-}): BoardTransactionInput;
+export declare function parseViewport(value?: string): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | undefined;
 export declare function registerBoards(program: Command): Command;
-export {};

package/dist/commands/boards.js

@@ -1,15 +1,11 @@
 import { randomUUID } from "node:crypto";
-import { BOARD_CREATE_INPUT_MAX_BYTES, BOARD_TRANSACTION_INPUT_MAX_BYTES, parseBoardJsonObject, readBoardJsonObject, resolveBoardId, writeBoardOutput, } from "../board-command-support.js";
+import { BOARD_CREATE_INPUT_MAX_BYTES, parseBoardJsonObject, readBoardJsonObject, resolveBoardId, writeBoardOutput, } from "../board-command-support.js";
 import { BOARD_EXPORT_FORMATS, formatFromPath, runBoardExport } from "../board-export.js";
 import { registerBoardDomainCommands } from "./board-domain.js";
 import { createClient, createRealtimeClient } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
 import { resolveSpace } from "../space.js";
-const INSPECT_SECTIONS = ["nodes", "connections", "effects", "compositions", "playback"];
 export const parseJsonObject = parseBoardJsonObject;
-export async function readJsonObject(source, maxBytes = BOARD_TRANSACTION_INPUT_MAX_BYTES) {
-    return readBoardJsonObject(source, maxBytes);
-}
 function parseNumber(value, name, options = {}) {
     if (!value.trim())
         throw new Error(`${name} must be a finite number`);
@@ -24,15 +20,6 @@ function parseNumber(value, name, options = {}) {
         throw new Error(`${name} must be at most ${options.max}`);
     return parsed;
 }
-export function parseInspectSections(value) {
-    if (!value)
-        return undefined;
-    const sections = value.split(",").map((item) => item.trim()).filter(Boolean);
-    const unknown = sections.filter((section) => !INSPECT_SECTIONS.includes(section));
-    if (unknown.length > 0)
-        throw new Error(`Unknown Board section: ${unknown.join(", ")}`);
-    return [...new Set(sections)];
-}
 export function parseViewport(value) {
     if (!value)
         return undefined;
@@ -51,45 +38,11 @@ export function parseViewport(value) {
         throw new Error("viewport width and height must be greater than zero");
     return { x, y, width, height };
 }
-export function createTransactionInput(input, options) {
-    if ("boardId" in input)
-        throw new Error("transaction input must not contain boardId");
-    if (!Array.isArray(input.operations))
-        throw new Error("transaction input must contain an operations array");
-    const rawBaseVersion = options.baseVersion ?? input.baseVersion;
-    if (rawBaseVersion === undefined)
-        throw new Error("baseVersion is required in input or --base-version");
-    const baseVersion = parseNumber(String(rawBaseVersion), "baseVersion", { min: 0, integer: true });
-    const rawTxId = options.txId ?? input.txId;
-    if (rawTxId !== undefined && (typeof rawTxId !== "string" || !rawTxId.trim())) {
-        throw new Error("txId must be a non-empty string");
-    }
-    return {
-        ...input,
-        txId: typeof rawTxId === "string" ? rawTxId : randomUUID(),
-        baseVersion,
-        operations: input.operations,
-    };
-}
-function showBoard(result) {
-    table([
-        {
-            id: result.board.id,
-            title: result.board.title,
-            version: result.board.version,
-            nodes: result.nodes.length,
-            connections: result.connections.length,
-            effects: result.effects.length,
-            compositions: result.compositions.length,
-        },
-    ], [
+function showCreated(result) {
+    table([result.board], [
         { key: "id", label: "ID" },
         { key: "title", label: "Title" },
         { key: "version", label: "Version" },
-        { key: "nodes", label: "Nodes" },
-        { key: "connections", label: "Connections" },
-        { key: "effects", label: "Effects" },
-        { key: "compositions", label: "Compositions" },
     ]);
 }
 function showSummary(result) {
@@ -105,7 +58,7 @@ function showSummary(result) {
         { key: "id", label: "ID" },
         { key: "title", label: "TITLE" },
         { key: "version", label: "VERSION" },
-        { key: "nodes", label: "NODES" },
+        { key: "items", label: "ITEMS" },
         { key: "connections", label: "CONNECTIONS" },
         { key: "effects", label: "EFFECTS" },
         { key: "compositions", label: "COMPOSITIONS" },
@@ -113,23 +66,6 @@ function showSummary(result) {
         { key: "updatedAt", label: "UPDATED" },
     ]);
 }
-function showValidation(result) {
-    table([{ valid: result.valid, diagnostics: result.diagnostics.length }], [
-        { key: "valid", label: "Valid" },
-        { key: "diagnostics", label: "Diagnostics" },
-    ]);
-    if (result.diagnostics.length > 0) {
-        console.log();
-        table(result.diagnostics, [
-            { key: "severity", label: "Severity" },
-            { key: "code", label: "Code" },
-            { key: "path", label: "Path" },
-            { key: "message", label: "Message" },
-        ]);
-    }
-    console.log();
-    table([result.peakCost], Object.keys(result.peakCost).map((key) => ({ key, label: key })));
-}
 function showPlayback(result) {
     table([result], [
         { key: "playbackId", label: "Playback ID" },
@@ -156,38 +92,6 @@ function capabilityUnits(schema) {
         return detail ? [`${field}:${detail}`] : [];
     }).join(", ");
 }
-function registerTransactionCommand(boards, name) {
-    withJson(boards.command(`${name} <board>`)
-        .description(name === "validate" ? "Validate a transaction" : "Apply a transaction")
-        .requiredOption("-i, --input <file>", "Transaction JSON file; use - for stdin")
-        .option("--tx-id <id>", "Override txId; generated when omitted")
-        .option("--base-version <version>", "Override baseVersion")
-        .addHelpText("after", `
-Input example:
-  {"baseVersion":12,"operations":[{"type":"board.patch","payload":{"patch":{"title":"Launch plan"}}}]}
-
-Prefer semantic commands such as boards background, nodes, effects, or compositions for common edits.`))
-        .action(async (target, options) => {
-        try {
-            const transaction = createTransactionInput(await readJsonObject(options.input, BOARD_TRANSACTION_INPUT_MAX_BYTES), options);
-            const spaceId = resolveSpace(boards);
-            const boardId = await resolveBoardId(spaceId, target);
-            const board = createClient().space(spaceId).board(boardId);
-            const result = await board[name](transaction);
-            if (jsonRequested(options))
-                return outJson(result);
-            if (name === "validate")
-                showValidation(result);
-            else {
-                const receipt = result;
-                ok(`Board updated to version ${receipt.board.version}`);
-            }
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-}
 function commandId(options) {
     return options.commandId?.trim() || randomUUID();
 }
@@ -313,14 +217,16 @@ export function registerBoards(program) {
         .description("Create a Board")
         .option("--title <title>", "Board title")
         .option("--mutation-id <id>", "Stable id for safe retries")
-        .option("-i, --input <file>", "BoardCreateInput fields; use - for stdin")
+        .option("-i, --input <file>", "Semantic Board seed JSON; use - for stdin")
         .addHelpText("after", `
-For normal use, create an empty Board and add content with boards nodes, effects, and compositions.
---input is intended for bulk creation and accepts BoardCreateInput fields except path and title.`))
+Create an empty Board, or provide items, connections, effects, compositions, and metadata in --input.
+Generate an editable seed:
+  cohub boards examples create > board.json
+  cohub boards create plan.board -i board.json`))
         .action(async (path, options) => {
         try {
             const content = options.input
-                ? await readJsonObject(options.input, BOARD_CREATE_INPUT_MAX_BYTES)
+                ? await readBoardJsonObject(options.input, BOARD_CREATE_INPUT_MAX_BYTES)
                 : {};
             if ("path" in content || "title" in content) {
                 throw new Error("create input must not contain path or title; use the command argument and --title");
@@ -336,7 +242,7 @@ For normal use, create an empty Board and add content with boards nodes, effects
             if (jsonRequested(options))
                 return outJson(result);
             ok(`Board created: ${result.board.id}`);
-            showBoard(result);
+            showCreated(result);
         }
         catch (cause) {
             handleHttp(cause);
@@ -344,31 +250,30 @@ For normal use, create an empty Board and add content with boards nodes, effects
     });
     withJson(boards.command("inspect <board>")
         .alias("get")
-        .description("Inspect a Board")
-        .option("--include <sections>", "Comma-separated nodes,connections,effects,compositions,playback")
-        .option("--viewport <rect>", "Viewport as x,y,width,height"))
+        .description("Show Board metadata and semantic resource counts")
+        .addHelpText("after", `
+Inspect content with:
+  cohub boards items list <board> --json
+  cohub boards effects list <board> --json
+  cohub boards compositions list <board> --json`))
         .action(async (target, options) => {
         try {
             const spaceId = resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
-            const board = createClient().space(spaceId).board(boardId);
-            if (!jsonRequested(options) && !options.include && !options.viewport) {
-                return showSummary(await board.summary());
-            }
-            const result = await board.inspect({
-                include: parseInspectSections(options.include),
-                viewport: parseViewport(options.viewport),
-            });
+            const result = await createClient().space(spaceId).board(boardId).summary();
             if (jsonRequested(options))
                 return outJson(result);
-            showBoard(result);
+            showSummary(result);
         }
         catch (cause) {
             handleHttp(cause);
         }
     });
     withJson(boards.command("capabilities <board>")
-        .description("Show supported capabilities"))
+        .description("Show authoring schemas and runtime capabilities")
+        .addHelpText("after", `
+Use --json for complete Item, patch, mutation, effect, Composition, and create JSON Schemas.
+Use boards examples for editable starter JSON.`))
         .action(async (target, options) => {
         try {
             const spaceId = resolveSpace(boards);
@@ -388,30 +293,25 @@ For normal use, create an empty Board and add content with boards nodes, effects
                 { key: "coordinates", label: "Coordinates / units" },
                 { key: "digest", label: "Digest" },
             ]);
-            const nodes = result.nodes;
-            if (nodes) {
-                console.log();
-                table([{
-                        types: nodes.types.join(", "),
-                        colors: nodes.colors.join(", "),
-                        geos: nodes.geos.join(", "),
-                        drawPoints: nodes.coordinates.drawPoints,
-                        arrowEndpoints: nodes.coordinates.arrowEndpoints,
-                    }], [
-                    { key: "types", label: "Node types" },
-                    { key: "colors", label: "Colors" },
-                    { key: "geos", label: "Geo kinds" },
-                    { key: "drawPoints", label: "Draw points" },
-                    { key: "arrowEndpoints", label: "Arrow endpoints" },
-                ]);
-            }
+            console.log();
+            table([{
+                    types: result.items.types.join(", "),
+                    colors: result.items.colors.join(", "),
+                    shapes: result.items.shapes.join(", "),
+                    drawPoints: result.items.coordinates.drawPoints,
+                    arrowEndpoints: result.items.coordinates.arrowEndpoints,
+                }], [
+                { key: "types", label: "Item types" },
+                { key: "colors", label: "Colors" },
+                { key: "shapes", label: "Shapes" },
+                { key: "drawPoints", label: "Draw points" },
+                { key: "arrowEndpoints", label: "Arrow endpoints" },
+            ]);
         }
         catch (cause) {
             handleHttp(cause);
         }
     });
-    registerTransactionCommand(boards, "validate");
-    registerTransactionCommand(boards, "apply");
     registerBoardDomainCommands(boards);
     registerExportCommand(boards);
     withJson(boards.command("play <board> <composition-id>")
@@ -514,13 +414,13 @@ For normal use, create an empty Board and add content with boards nodes, effects
                         process.stdout.write(`${JSON.stringify(event)}\n`);
                         return;
                     }
-                    if (event.type === "board.transaction.applied") {
-                        process.stdout.write(`version ${event.payload.version}  transaction ${event.payload.txId}  operations ${event.payload.operations.length}\n`);
+                    if (event.type === "board.changed") {
+                        process.stdout.write(`version ${event.payload.version}  mutation ${event.payload.mutationId}\n`);
                     }
                     else if (event.type === "board.playback.changed") {
                         process.stdout.write(`${event.payload.status}  composition ${event.payload.compositionId}  position ${event.payload.position}\n`);
                     }
-                    else {
+                    else if (event.type === "board.awareness.updated") {
                         process.stdout.write(`awareness ${event.payload.actorName}  ${event.payload.update.type}\n`);
                     }
                 },

package/dist/commands/cron-jobs.js

@@ -9,7 +9,7 @@ function readJsonObject(pathOrJson) {
     return parsed;
 }
 export function registerCronJobs(program) {
-    const cmd = program.command("cron-jobs", { hidden: true }).description("Scheduled jobs");
+    const cmd = program.command("cron-jobs").description("Scheduled jobs");
     cmd
         .command("ls [spaceId]")
         .alias("list")

package/dist/commands/tasks.js

@@ -2,7 +2,7 @@ import { createClient } from "../client.js";
 import { table, json as outJson, jsonRequested, handleHttp } from "../output.js";
 export function registerTasks(program, dependencies = {}) {
     const getClient = dependencies.createClient ?? createClient;
-    const cmd = program.command("tasks", { hidden: true }).description("Task runs");
+    const cmd = program.command("tasks").description("Task runs");
     cmd
         .command("ls")
         .alias("list")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "4.0.0",
+  "version": "5.0.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.19.0",
     "sharp": "^0.35.3",
-    "@neta-art/cohub": "6.0.0"
+    "@neta-art/cohub": "7.0.0"
   },
   "publishConfig": {
     "access": "public"