Skip to content

The VS Code of video editing, built for agents.

TypeScript

Remove outdated API documentation files and introduce new reference files for `dapi` CLI commands, including `context`, `fonts`, `models`, `mount`, `open`, and others. Update the main reference README to reflect the new command structure and organization, ensuring clarity and accessibility for users. This restructuring enhances the overall documentation quality and usability.

konstantin-paulus5e3b6d577a19
diff --git a/apps/cli/api-spec.md b/apps/cli/api-spec.md
deleted file mode 100644
index ffbf1899..00000000
--- a/apps/cli/api-spec.md
+++ /dev/null
@@ -1,756 +0,0 @@
-# Dapi CLI Reference
-
-User-facing reference for the `dapi` CLI. All canvas/project commands talk to the running Diffusion Studio app over a local socket. Responses are JSON written to stdout. Errors print to stderr and exit non-zero.
-
-**Top-level:** `open`, `whoami`, `context` (alias `ctx`), `mount`, `models`, `voices`.
-**Groups:** `selection` (alias `sel`), `node` (aliases `n`, `entity`), `project` (alias `p`), `asset` (alias `a`), `folder` (alias `fld`), `font` (alias `f`).
-Selection reads and mutations live under `selection`. Anything that targets one or more nodes lives under `node` — scenes are nodes too; they are created declaratively via `mount` (`<scene key="...">`). Declarative composition happens through `mount`, which renders a Solid JSX project into the canvas (see [jsx-spec.md](./jsx-spec.md)); `node insert` runs the same pipeline but inserts the rendered nodes into an existing parent entity instead of mounting document roots. AI asset generation (image / video / speech / audio) is **declared in the project module** and produced on mount (see the JSX API); the `models` and `voices` commands list what's available to reference from those declarations. Inspecting an existing asset (probe / transcribe / analyze / visualize / frame) lives under `asset`; writing an asset's original file back out to disk is `asset export`. Organizing the asset library into folders lives under `folder`; moving assets between folders is `asset mv`.
-
-Shared types used below:
-
-```ts
-NodeRef = { id: number; name: string; type: string } // node ids are entity ids — integers
-Size = { width: number; height: number }
-Asset = { id: string; name: string; type: string } // asset ids are opaque strings (sqids)
-Folder = { id: string; name: string; type: 'folder' } // folder ids are opaque strings (sqids)
-Time = number | `${number}f` | "MM:SS" // seconds, frames at 30 fps ("45f"), or a clock string — see jsx-spec.md
-```
-
-Time inputs take the `Time` format unless noted otherwise. Times in **outputs** are plain seconds — except the raw records of `node ls`, which use engine units (frames at 30 fps, packed colors, dB).
-
----
-
-## App
-
-### `dapi open [target]`
-
-Launches Diffusion Studio, or opens a target. Behavior depends on what `[target]` resolves to.
-
-- **Input:** `[target]` — optional. One of:
- - *omitted* — launches the app.
- - **`diffusion://...` URL** — follows the deep link.
- - **file path** — opens the file in the app.
- - **folder path** — see "Folder open" below.
-- **Options:**
- - `-b, --background` — launch with the window hidden (`show: false`), so the app runs headlessly and can be driven by other CLI commands without any visible UI.
-- **Output:**
- - File / URL / no target: nothing.
- - Folder: one JSON object (see below).
-- **Notes:** does not require the app to already be running.
-
-#### Folder open
-
-When `[target]` is a directory, `open` either creates a project from the folder's contents or switches to a previously created one. The decision is driven by a `.dapi` marker file at the folder root.
-
-**First time** (no marker present):
-
-1. Creates a new project named after the folder.
-2. Imports every supported asset file under the folder (recursively, excluding the marker itself), mirroring the on-disk directory structure as library folders. Directories without any supported assets beneath them produce no folder.
-3. Writes the `.dapi` marker at the folder root with the new project id.
-4. Opens the project.
-
-**Subsequent times** (marker present):
-
-1. Reads the project id from the marker.
-2. Switches to that project. No re-import.
-3. If the referenced project no longer exists, the marker is treated as stale and the first-time flow runs again, overwriting the marker.
-
-**Marker file** — `.dapi` at the folder root. JSON:
-
-```ts
-{
- version: 1;
- projectId: string;
- createdAt: string; // ISO 8601
-}
-```
-
-Add to `.gitignore` to keep project association per-clone, or commit it to share the same project across teammates.
-
-**Output:** one JSON object
-
-```ts
-{
- project: { id: string; name: string };
- created: boolean; // true if a new project was created this run (first-time or stale-marker)
- imported: number; // assets imported this run; 0 on switch-only
-}
-```
-
----
-
-### `dapi whoami`
-
-Prints the authenticated account, or `null` if signed out.
-
-- **Input:** none
-- **Output:** one JSON value
- ```ts
- { id: string; email: string; provider: string } | null
- ```
-
----
-
-## Document
-
-### `dapi context`
-
-Essential context about the open project. Call this first to understand the canvas situation. Alias: `ctx`.
-
-- **Input:** none
-- **Output:** one JSON object
- ```ts
- {
- project: { id: string; name: string };
- entityCount: number;
- scenes: Array<{ id: number; name: string; size: Size }>;
- activeSceneId: number | null; // null if no scene is active
- currentFrame: number; // current timeline playhead position, in frames
- fontFamilies: string[];
- }
- ```
----
-
-## Scripting
-
-### `dapi mount (<path> | --code <str>)`
-
-Compiles a Solid JSX project module and executes it in the app, mounting the rendered roots into the document — like reloading a webpage, re-mounting rebuilds them in place instead of adding copies. Every top-level element declares its identity in the JSX with a `key`: `<scene key="intro">` replaces the node carrying that key (or creates it). With `--code`, the `export default () =>` wrapper is optional — a bare JSX expression (no `export default` in the source) is wrapped into a component module automatically. Full specification: [jsx-spec.md](./jsx-spec.md).
-
-- **Output:** none.
-
----
-
-## Selection
-
-All under `dapi selection` (alias `dapi sel`). Mutating commands return the resulting selection state in the same shape as `selection ls`, so callers can chain or assert without a follow-up read.
-
-### `dapi selection ls`
-
-The currently selected nodes. Alias: `get`.
-
-- **Input:** none
-- **Output:** JSON Lines, one per selected node (no output if nothing is selected)
- ```ts
- NodeRef
- ```
-
----
-
-### `dapi selection set [ids...]`
-
-Replaces the current selection with exactly the given node ids. No ids = clear the selection.
-
-- **Input:** `[ids...]` — zero or more node ids
-- **Output:** JSON Lines, one per selected node (no output when clearing)
- ```ts
- NodeRef
- ```
-
----
-
-### `dapi selection focus`
-
-Pans and zooms the canvas to fit the currently selected nodes in view, framing them with padding — the same focus used by `node screenshot` before it captures. No-op if nothing is selected (the canvas is left unchanged).
-
-- **Input:** none
-- **Output:** JSON Lines, one per selected node (no output if nothing is selected)
- ```ts
- NodeRef
- ```
-
----
-
-## Node operations
-
-All under `dapi node` (aliases `dapi n`, `dapi entity`).
-
-### `dapi node ls [ids...]`
-
-The raw entity records, exactly as persisted — every component the entity carries, keyed by component name. The property-level counterpart to `node tree`'s structure. With no ids, returns the root (top-level nodes). Alias: `get`.
-
-- **Input:** `[ids...]` — zero or more entity ids (optional)
-- **Output:** JSON Lines, one per entity
- ```ts
- EntityRecord = { id: string; eid: number } & { [component: string]: unknown }
- // e.g. Name, Size, Position, Rotation, Paint, Color, Trim, ChildOf (parent eid), …
- ```
- Records are raw engine data: times are frames at 30 fps, colors are packed `0xRRGGBB` integers, volume is dB.
-- **Errors:** if any input id fails to resolve, writes a per-id message to stderr and exits non-zero after emitting all successful records to stdout.
-
-
----
-
-### `dapi node tree [id] [--depth N]`
-
-An entity's subtree as a nested JSON object — structure only, every entity and sub-entity included, and the way to discover their ids. Key characteristics are folded into a compact `description` built from whatever the entity carries; use `node ls` for exact property values. The root is level 0, so `--depth 1` yields the root plus its immediate children.
-
-- **Input:**
- - `[id]` — root entity id (optional; omitted = one tree per top-level node, mirroring `ls`)
- - `--depth <N>` — max depth, non-negative integer (optional; default `3`, `0` = full subtree)
-- **Output:** JSON Lines, one nested object per root; category arrays are omitted when empty
- ```ts
- NodeTree = NodeRef & {
- description: string; // e.g. "hidden; size: 200x300; text: Hello World"
- children?: NodeTree[]; // child nodes (masks listed separately)
- masks?: NodeTree[];
- paints?: NodeTree[]; // fills
- strokes?: NodeTree[];
- shadows?: NodeTree[];
- effects?: NodeTree[];
- colorStops?: NodeTree[]; // on gradient paints
- textRanges?: NodeTree[]; // on text nodes
- keyframeTracks?: NodeTree[]; // keyframes nest beneath their track
- keyframes?: NodeTree[];
- animations?: NodeTree[];
- }
- ```
-
----
-
-### `dapi node grep <pattern> [id]`
-
-Searches entity records for a pattern and prints the matching entities, with the components that matched. The search corpus is the raw records [`node ls`](#dapi-node-ls-ids) would emit — component values stringified — so anything `ls` can show, `grep` can find; the caveat carries over too: values are raw engine units (frames at 30 fps, packed colors, dB). `[id]` scopes the search to a subtree, like giving `grep -r` a path. The structural counterpart of `tree` (find entities by content rather than by position) and the discovery front-end to `ls`, `selection set`, and `patch`: `grep` to find ids, then read, select, or edit them.
-
-The common case — find nodes by name — is `dapi node grep -k Name Title`. Presence queries work with a match-anything pattern: `dapi node grep -k Trim .` lists every entity carrying a `Trim` component.
-
-- **Input:**
- - `<pattern>` — JavaScript regex, unanchored (required). Case-sensitive unless `-i` is given.
- - `[id]` — root entity id (optional; omitted = every top-level node's subtree)
- - `-i, --ignore-case` — case-insensitive matching
- - `-t, --type <types...>` — only match entities of these node types (e.g. `-t text image`; the `type` values of `node tree`)
- - `-k, --component <names...>` — restrict matching to these components (e.g. `-k Name Chars`; the component keys of `node ls`)
- - `-l, --refs-only` — output only the matching entity refs, no match detail
- - `-c, --count` — output only the number of matching entities
-- **Output:** JSON Lines, one per matching entity (no output if nothing matches — this is a successful run, exit `0`); the structured analog of grep's `file:line:content`
- ```ts
- NodeRef & { matches: Array<{ component: string; value: string }> }
- // value is the stringified component value the pattern matched
- ```
- With `--refs-only`, plain `NodeRef` lines; with `--count`, a single number.
-- **Errors:** exits non-zero if the pattern is not a valid regex, or if `[id]` doesn't resolve to a live entity.
-
----
-
-### `dapi node screenshot [id] [-t, --time <time>]`
-
-Focuses the node on the canvas and captures a screenshot, written to a PNG file in the system temp directory. If `[id]` is omitted, captures the canvas (the active scene).
-
-- **Input:**
- - `[id]` — node id (optional; defaults to the canvas)
- - `-t, --time <time>` — timeline position at which to record the node, a `Time` value (optional; defaults to the current playhead position)
-- **Output:** one JSON object — the absolute path to a freshly written PNG in the system temp directory with a uuid filename
- ```ts
- { path: string } // e.g. "/tmp/3f2c1a8e-....png"
- ```
-
----
-
-### `dapi node insert <parentId> (<path> | --code <str>) [--index <N>]`
-
-Compiles a Solid JSX project module and executes it in the app — the same pipeline as [`mount`](#dapi-mount-path---code-str), including declared asset generation — but instead of mounting the rendered roots into the document, inserts them as children of an existing entity. Because the result is inserted rather than reconciled, root elements take no `key`: every run inserts fresh entities; there is no replace-or-create matching and nothing is deleted. Full specification: [jsx-spec.md](./jsx-spec.md).
-
-The rendered roots must be valid as children of the target parent, following the JSX containment rules: a node parent takes any element or paint root except `<scene>` (scenes only exist at the document top level) and `<colorStop>`; a gradient paint parent takes only `<colorStop>` roots — this is how a stop is added to an existing gradient (`node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'`); other sub-entities take no children.
-
-- **Input:**
- - `<parentId>` — entity id of the parent to insert into (required)
- - project module — exactly one of:
- - `<path>` — path to the module file
- - `--code <str>` — inline module source; the `export default () =>` wrapper is optional, a bare JSX expression is wrapped automatically (e.g. `--code '<rect width={100} height={100} />'`)
- - `-i, --index <N>` — the inserted node's 0-based position among the parent's children, a non-negative integer (optional; default = append after the last child; values past the end are clamped). Node roots only: paints stack in insertion order and color stops render sorted by `offset`, so `--index` is rejected for them.
-- **Output:** none.
-- **Errors:** exits non-zero if `<parentId>` doesn't resolve to a live entity, if compilation or evaluation fails, if a rendered root is invalid as a child of the parent (e.g. a `<scene>`, or a non-`<colorStop>` in a gradient paint), or if `--index` is given for a paint or color stop root. On any of these, **nothing is inserted**.
-
----
-
-### `dapi node rm <ids...>`
-
-Deletes one or more entities and all their descendants. Alias: `remove`.
-
-- **Input:** `<ids...>` — one or more entity ids (required)
-- **Output:** JSON Lines, one per input id
- ```ts
- | { status: "fulfilled"; id: number }
- | { status: "rejected"; id: number; error: string }
- ```
-
----
-
-### `dapi node patch ([path] | --json <str>)`
-
-Assigns JSX props on one or more existing entities in a single call. Every patch entry takes the same properties, with the same value requirements, as a JSX element in [`mount`](#dapi-mount-path---code-str) — the full table lives in [jsx-spec.md](./jsx-spec.md#element-reference) and is not repeated here; the payload type is `PatchProps` from `@diffusionstudio/jsx`. Patches are applied through the same setters as a render, so the two surfaces cannot diverge. Changes are tracked for undo like a UI edit.
-
-Any live entity is addressable — not just nodes: paints and color stops can be patched too (`color`, `offset`, `opacity`, gradient `rotation`). There is no separate rename command: renaming a node is patching its `name`.
-
-- **Input:** exactly one of:
- - `[path]` — path to a `.json` file containing the patch array
- - `--json <str>` — the array inline
-
- Payload shape:
- ```ts
- Array<{ id: number } & PatchProps>
- ```
-
- All props are optional; a patch may set any subset. An unsupported property or an out-of-range value rejects that entity; a rejected patch applies none of its props (no half-applied patches). Notes beyond the JSX table:
- - `fill` recolors the entity's existing solid fill(s), or creates one if the entity has none.
- - `src` takes a path, URL, or asset id (`generate.*` declarations are JSX-only). The source resolves asynchronously after the other props land — if resolution fails, the entity is reported rejected even though its other props were applied; patch `src` on its own to avoid ambiguity.
- - `syncTo` re-runs audio alignment against the document node carrying the given key and writes the entity's `startTime` from the measured offset (see [jsx-spec.md](./jsx-spec.md#audio-sync)). The command blocks until alignment settles; a failed alignment rejects the entity.
- - Element applicability is not checked: props are applied wherever `mount` would apply them (e.g. `fontSize` only makes sense on a text node).
-- **Output:** JSON Lines, one per input id
- ```ts
- | { status: "fulfilled"; id: number }
- | { status: "rejected"; id: number; error: string }
- ```
-
----
-
-### `dapi node cp <ids...>`
-
-Deep-clones one or more nodes, including all descendants. Alias: `duplicate`.
-
-- **Input:** `<ids...>` — one or more node ids (required)
-- **Output:** JSON Lines, one per input id
- ```ts
- | { status: "fulfilled"; sourceId: number; newId: number }
- | { status: "rejected"; sourceId: number; error: string }
- ```
-
----
-
-### `dapi node render [id] ([config] | --json <str>)`
-
-Renders a scene to a video file. Composes the scene frame-by-frame and muxes the result, writing it to disk. Operates on one scene — scenes are nodes, so this is the node-level render. If `[id]` is omitted, renders the active scene.
-
-Encode settings are passed as a single JSON config — the same object the in-app render method takes (`EncoderConfig`), minus the runtime-only fields the CLI fills in for you (`scene`, `target`, `onProgress`). The whole config is **optional**; omit it to render with the defaults below. The encode window follows the scene's timeline workarea (its `Trim`): the render starts at the workarea start and runs to the scene's end, unless capped earlier with `trim.end`. Renders locally; **no credits** and no authenticated account required.
-
-Like the generators, this is **long-running** — the CLI blocks until the render finishes (or fails) before printing. While waiting, a progress spinner with elapsed time is shown on **stderr** (a single static line when stderr isn't a TTY), so stdout stays clean JSON for piping.
-
-- **Input:**
- - `[id]` — scene node id (optional; defaults to the active scene).
- - `-o, --output <path>` — write the video here (optional; default a uuid-named file in the system temp directory). The container extension is derived from the config's `format`.
- - Encode config (optional) — at most one of:
- - `[config]` — path to a `.json` file containing the config object. Node ids are integers, so a lone non-numeric positional is read as the config path (`dapi node render encode.json` works without an id).
- - `--json <str>` — the object inline
-
- Config shape (every field optional; all defaults shown):
- ```ts
- {
- format?: "mp4" | "webm" | "ogg" | "mov"; // default "mp4"; sets the output extension
- video?: {
- codec?: "avc" | "hevc" | "vp9" | "av1" | "vp8"; // default "avc" (H.264); valid codecs depend on format
- enabled?: boolean; // default true
- bitrate?: number; // bits/sec, default 10_000_000 (10 Mbps)
- fps?: number; // default the scene's frame rate
- resolution?: number; // target height in px (e.g. 720, 1080, 1440, 2160); default 1080. Width follows the scene's aspect ratio
- };
- audio?: {
- enabled?: boolean; // default true; set false to render video only
- codec?: "aac" | "opus"; // default "aac"; valid codecs depend on format
- bitrate?: number; // bits/sec, default 128_000 (128 kbps)
- sampleRate?: number; // Hz, e.g. 44100, 48000, 96000; default 48000
- numberOfChannels?: number; // default 2
- };
- trim?: {
- end?: number; // seconds; cap the encode here. Default the scene's full duration. Caps the workarea end; cannot extend past the scene
- };
- }
- ```
-- **Output:** one JSON object — the absolute path to the written video file
- ```ts
- { path: string } // e.g. "/tmp/3f2c1a8e-....mp4", or the --output path
- ```
-- **Errors:** exits non-zero if the id is unknown or the node is not a scene (`Not a scene`), if no scene is active and `[id]` is omitted, if the config is malformed or holds a value out of range or incompatible with the chosen `format` (e.g. an unsupported codec), if `--output` can't be written, or if the render fails or is canceled.
-
----
-
-## Projects
-
-All under `dapi project` (alias `dapi p`).
-
-### `dapi project active`
-
-Prints the currently active project, or `null` if none is open.
-
-- **Input:** none
-- **Output:** one JSON value
- ```ts
- { id: string; name: string } | null
- ```
-
----
-
-### `dapi project ls`
-
-Lists all projects, most recently accessed first. Alias: `list`.
-
-- **Input:** none
-- **Output:** one JSON object per line (newline-delimited)
- ```ts
- { id: string; name: string; createdAt: string; lastAccessedAt: string }
- ```
-
----
-
-### `dapi project create [name]`
-
-Creates a new project and opens it.
-
-- **Input:** `[name]` — optional project name
-- **Output:** one JSON object
- ```ts
- { id: string; name: string }
- ```
-
----
-
-### `dapi project set <id>`
-
-Sets the active project by id, opening it. Returns `null` if no project has that id.
-
-- **Input:** `<id>` — project id (required)
-- **Output:** one JSON value
- ```ts
- { id: string; name: string } | null
- ```
-
----
-
-### `dapi project rm <id>`
-
-Deletes a project by id. Alias: `remove`.
-
-- **Input:** `<id>` — project id (required)
-- **Output:** one JSON object
- ```ts
- { id: string; name: string }
- ```
-
----
-
-## Assets
-
-All under `dapi asset` (alias `dapi a`). Operate on the open project.
-
-### `dapi asset add <paths...>`
-
-Adds one or more local files as assets in the open project.
-
-- **Input:**
- - `<paths...>` — absolute or relative file paths (resolved against CWD)
- - `--folder <id>` — folder to place the new assets in (optional; default the library root)
-- **Output:** JSON Lines, one per input path
- ```ts
- | ({ status: "fulfilled"; path: string } & Asset)
- | { status: "rejected"; path: string; error: string }
- ```
-- **Errors:** exits non-zero before importing anything if `--folder` doesn't resolve to a folder.
-
----
-
-### `dapi asset ls [ids...]`
-
-The raw asset records, as persisted minus the file handles — every serializable property the asset carries (per-type media metadata, `folderId`, a stored `transcript`, …). The property-level counterpart to `asset tree`'s structure. With no ids, returns every asset in the library. Alias: `get`.
-
-- **Input:** `[ids...]` — zero or more asset ids (optional)
-- **Output:** JSON Lines, one per asset
- ```ts
- AssetRecord = { id: string } & { [property: string]: unknown }
- // e.g. name, type, mimeType, size, createdAt, folderId; duration/width/height/… by type
- ```
-- **Errors:** if any input id fails to resolve, writes a per-id message to stderr and exits non-zero after emitting all successful records to stdout.
-
----
-
-### `dapi asset tree`
-
-Prints the asset library of the open project as its folder tree — folders and assets interleaved in one array, each folder carrying its contents in `children`.
-
-- **Input:**
- - `--folder <id>` — folder whose contents to list (optional; default the library root)
- - `--depth <N>` — max depth, positive integer (optional; default = full tree). `--depth 1` yields just the direct entries of the listing root; a folder at the cutoff is listed without `children` (indistinguishable from a genuinely empty folder — raise the depth to tell them apart).
-- **Output:** JSON Lines, one per entry of the listing root (no output if the listing root is empty); each entry carries its own subtree in `children`
- ```ts
- AssetTree = Array<(Asset | Folder) & { children?: AssetTree }> // one root entry per line
- ```
- Folders are the entries with type `folder`. `children` is present only on folders with contents; assets never carry it.
-- **Errors:** exits non-zero if `--folder` doesn't resolve to a folder.
-
----
-
-### `dapi asset rm <ids...>`
-
-Deletes one or more assets from the open project by id. Alias: `remove`.
-
-- **Input:** `<ids...>` — asset ids (required)
-- **Output:** JSON Lines, one per input id
- ```ts
- | { status: "fulfilled"; id: string; name: string }
- | { status: "rejected"; id: string; error: string }
- ```
-
----
-
-### `dapi asset mv <ids...> [--to <folderId>]`
-
-Moves one or more assets into a folder. Alias: `move`.
-
-- **Input:**
- - `<ids...>` — asset ids (required)
- - `--to <folderId>` — destination folder (optional; omitted = the library root)
-- **Output:** JSON Lines, one per input id
- ```ts
- | { status: "fulfilled"; id: string; folderId: string | null }
- | { status: "rejected"; id: string; error: string }
- ```
-- **Errors:** exits non-zero before moving anything if `--to` doesn't resolve to a folder; an unknown asset id rejects that id only.
-
----
-
-### `dapi asset export <ids...>`
-
-Writes one or more assets' original file bytes to a location on the file system — the exact bytes stored in the library, streamed to disk in chunks (never buffered whole). No re-encode, no processing, no credits. Any asset type is accepted except image sequences. The counterpart of `asset add`.
-
-- **Input:**
- - `<ids...>` — asset ids (required)
- - `-o, --output <path>` — where to write (optional; default the system temp directory). Interpreted as:
- - **a directory** — when the path is an existing directory, ends with a path separator, or multiple ids are given. Created if missing. Each asset is written into it named after the asset, with an extension derived from its media type when the name lacks one. A name that collides with an existing file is uniquified with a ` (N)` suffix — never overwritten.
- - **a file path** — otherwise (single id only). Written exactly there, overwriting an existing file.
-- **Output:** JSON Lines, one per input id, in the requested order
- ```ts
- | { status: "fulfilled"; id: string; path: string } // path = the file actually written
- | { status: "rejected"; id: string; error: string }
- ```
-- **Errors:** exits non-zero before writing anything if `--output` must be a directory (multiple ids, or a trailing path separator) but resolves to an existing file, or if the output directory can't be created. An unknown id — or an image-sequence asset — rejects that id only; a rejected asset leaves no partial file behind.
-
----
-
-### `dapi asset probe <id|path>`
-
-Reads the container and per-track technical metadata of an asset — like `ffprobe`, but demuxed locally with mediabunny. Reports the container format, duration, metadata tags, and every track's codec parameters without decoding any media. Reads locally; no credits.
-
-- **Input:**
- - `<id|path>` — an asset id, or a local file to add and probe (required). Any asset type is accepted.
-- **Output:** one JSON object. The shape is **not yet stable** — it reports whatever mediabunny surfaces about the container and its tracks. Packet stats (frame rate, bitrate, packet count) are estimated from a leading sample of packets, so they are fast but approximate. Assets mediabunny can't demux (images, transcripts) don't error; they report file-level info only, with `format: null` and no tracks.
-- **Errors:** exits non-zero if the id is unknown.
-
----
-
-### `dapi asset transcribe <id|path>`
-
-Transcribes the speech in a video or audio asset and returns the timed transcript. Word-level start/end times are in **seconds** (source/content time).
-
-- **Input:**
- - `<id|path>` — a video or audio asset id, or a local file to add and transcribe (required).
-- **Output:** one JSON object — the transcript:
- ```ts
- {
- id: string; // the asset id
- segments: Array<{
- text: string; // spoken words only (no silence markers)
- words: Array<{ text: string; start: number; end: number }>; // seconds;
- }>;
- }
- ```
-- **Errors:** exits non-zero if the id is unknown or the asset is not a video/audio asset, or if no speech is detected in the audio (`No speech detected`).
-
----
-
-### `dapi asset analyze <id|path>`
-
-Analyzes an image, video, or audio asset with a multimodal model. With no prompt it returns a general description of the asset; with `--prompt` it answers that question about the asset (e.g. "what's the dominant color?", "summarize what happens").
-
-- **Input:**
- - `<id|path>` — an image, video, or audio asset id, or a local file to add and analyze (required).
- - `-p, --prompt <str>` — question or instruction about the asset (optional; defaults to a general description).
- - `-s, --start <time>` — start of the segment to analyze, a `Time` value (optional; default `0`). Timestamps in the analysis are relative to this point. Ignored for images.
- - `-e, --end <time>` — end of the segment to analyze, a `Time` value (optional; default the asset's duration). Ignored for images.
-- **Output:** one JSON object — the model's answer
- ```ts
- { id: string; analysis: string } // id = the analyzed asset id
- ```
-- **Errors:** exits non-zero if the id is unknown, or the asset's media type isn't supported by the chosen model.
-
----
-
-### `dapi asset visualize <id|path>`
-
-Renders a visual preview of an asset to a PNG, written to a file in the system temp directory. The visualization is chosen by the asset's media type, so a single command covers the whole library. Renders locally; no credits. Alias: `viz`.
-
-- **By media type:**
- - **audio** — an amplitude waveform with a time axis (tick labels along the bottom in `mm:ss`), drawn from decoded audio peaks.
- - **video** — a composite: a **filmstrip** of frames sampled at even intervals across the window, with the **waveform** of the video's audio track drawn beneath it, sharing one `mm:ss` (or milliseconds) time axis. Videos with no audio track render the filmstrip alone.
- - **image** — a thumbnail of the image, auto-scaled.
-- **Input:**
- - `<id|path>` — an image, audio, or video asset id, or a local file to add and visualize (required).
- - `-s, --start <time>` — start of the window to visualize, a `Time` value in source/content time (optional; default `0`). Ignored for images.
- - `-e, --end <time>` — end of the window to visualize, a `Time` value (optional; default the asset's duration). Ignored for images.
- - `-x, --scale <factor>` — scale factor for the thumbnails (optional; default `1`, clamped to `0.25`–`4`). The overall canvas size stays fixed, so smaller thumbnails fit **more rows and columns** (a denser grid sampling more moments) and larger thumbnails fit fewer but show more detail each. For images, scales the output resolution instead (never above the source size).
- - `-o, --output <path>` — write the PNG here instead of a temp file (optional).
-- **Output:** one JSON object — the absolute path to the written PNG
- ```ts
- { path: string } // e.g. "/tmp/3f2c1a8e-....png", or the --output path
- ```
-- **Errors:** exits non-zero if the id is unknown, the media type isn't visualizable (e.g. a transcript asset, or an audio asset with no decodable audio), `--start`/`--end` fall outside the asset or cross (`--start` ≥ `--end`), `--scale` isn't a positive number, or `--output` can't be written.
-
----
-
-### `dapi asset frame <id|path>`
-
-Decodes one or more frames of a video asset at the given times and writes each to a PNG file — like `node screenshot`, but grabs the asset's own pixels at full resolution (unlike `node screenshot`, which captures the composited canvas). Renders locally; no credits.
-
-- **Input:**
- - `<id|path>` — a video asset id, or a local video file to add and grab frames from (required).
- - `-t, --time <time...>` — one or more timestamps to grab, `Time` values in source/content time (optional; default `0`). Order is preserved in the output regardless of the order given.
- - `-o, --output <dir>` — directory to write the PNGs into (optional; default the system temp directory). Each frame is written as a uuid-named `.png`.
-- **Output:** JSON Lines, one object per requested timestamp, in the requested order
- ```ts
- { time: number; path: string } // time = the requested timestamp in seconds; path = the written PNG
- ```
-- **Errors:** exits non-zero if the id is unknown, the asset is not a video, any `--time` is past the asset's duration, or a PNG can't be written.
-
----
-
-## Folders
-
-All under `dapi folder` (alias `dapi fld`). Operate on the open project. Folders organize the asset library and nest arbitrarily; assets reference their containing folder via `folderId` (`null` = library root). Everywhere a folder id is optional, omitting it means the library root — there is no sentinel value for the root. Read the full hierarchy (folders and assets together) with [`asset tree`](#dapi-asset-tree); move assets between folders with [`asset mv`](#dapi-asset-mv-ids---to-folderid).
-
-### `dapi folder ls [parentId]`
-
-Lists the direct child folders of a parent folder, sorted by name. With no id, lists the root-level folders. Aliases: `list`, `get`.
-
-- **Input:** `[parentId]` — parent folder id (optional; omitted = the library root)
-- **Output:** JSON Lines, one per child folder (no output if the parent has no subfolders)
- ```ts
- Folder
- ```
-- **Errors:** exits non-zero if `[parentId]` doesn't resolve to a folder.
-
----
-
-### `dapi folder create <name> [-p, --parent <id>]`
-
-Creates a folder.
-
-- **Input:**
- - `<name>` — folder name (required)
- - `-p, --parent <id>` — parent folder (optional; omitted = the library root)
-- **Output:** one JSON object
- ```ts
- Folder
- ```
-- **Errors:** exits non-zero if `--parent` doesn't resolve to a folder.
-
----
-
-### `dapi folder rename <id> <name>`
-
-Renames a folder.
-
-- **Input:**
- - `<id>` — folder id (required)
- - `<name>` — new name (required)
-- **Output:** one JSON object
- ```ts
- Folder
- ```
-
----
-
-### `dapi folder mv <ids...> [--to <folderId>]`
-
-Moves one or more folders under a new parent. A folder cannot be moved into itself or any of its descendants — such a move rejects that id and leaves it where it was. Alias: `move`.
-
-- **Input:**
- - `<ids...>` — folder ids (required)
- - `--to <folderId>` — destination parent folder (optional; omitted = the library root)
-- **Output:** JSON Lines, one per input id
- ```ts
- | { status: "fulfilled"; id: string; parentId: string | null }
- | { status: "rejected"; id: string; error: string } // unknown id, or a cycle
- ```
-- **Errors:** exits non-zero before moving anything if `--to` doesn't resolve to a folder.
-
----
-
-### `dapi folder rm <ids...>`
-
-Deletes one or more folders. **Deletion cascades:** every descendant folder and every asset inside the subtree is deleted with it. The fulfilled record reports what the cascade removed, so callers can detect when a delete swept more than intended. Alias: `remove`.
-
-- **Input:** `<ids...>` — folder ids (required)
-- **Output:** JSON Lines, one per input id
- ```ts
- | { status: "fulfilled"; id: string; deletedFolders: number; deletedAssets: number }
- // deletedFolders counts the folder itself plus all descendants
- | { status: "rejected"; id: string; error: string }
- ```
-
----
-
-## Generation reference
-
-**Asset generation (image / video / speech / audio) is declared in the project module** (`generate.*` declarations, see the JSX API) and produced by the editor on mount. There are no CLI commands that generate; the two commands below only list what you can reference from those declarations. (Captioning is also declarative — a `<captions>` element in a mounted or inserted project, see [Captions](./jsx-spec.md#captions).) Both require the app to be running.
-
-### `dapi models [type]`
-
-Lists the generation models available for a media type, including each model's capabilities — use it to discover valid model ids and the per-model constraints (durations, aspect ratios, features) to set on an asset declaration (see the JSX API).
-
-- **Input:** `[type]` — optional; one of `image`, `video`, `audio`. Omit to list all three groups.
-- **Output:** JSON Lines, one per model
- ```ts
- {
- type: "image" | "video" | "audio";
- id: string; // the model id to set on <asset model="…">
- name: string;
- durations?: string[]; // video only, e.g. ["5s","10s"]
- aspectRatios?: string[]; // video only
- features?: Array<"start-frame" | "end-frame" | "audio">; // video only
- }
- ```
-
----
-
-### `dapi voices`
-
-Lists the speech voices available for declared voice assets (see the JSX API).
-
-- **Input:** none
-- **Output:** JSON Lines, one per voice
- ```ts
- { id: string; label: string; description: string }
- ```
-
----
-
-## Fonts
-
-### `dapi fonts`
-
-Lists local fonts available on this machine. macOS only.
-
-- **Input:**
- - `-f, --family <pattern>` — filter to families whose name contains `<pattern>` (case-insensitive)
- - `-w, --weight <weights...>` — filter to variants with the given CSS weight(s), e.g. `-w 400 700`
- - `-s, --style <style>` — `"normal"` or `"italic"`
- - `-l, --limit <n>` — output at most `<n>` families
- - `-n, --names-only` — output only family names, one per line, plain text (no JSON)
-- **Output:** JSON Lines, one per family — or plain family names when `--names-only` is set
- ```ts
- {
- family: string;
- variants: Array<{
- weight: string; // CSS weight, e.g. "400"
- style: "normal" | "italic";
- source: string; // CSS local() source
- }>;
- }
- ```
-
----
-
-## Conventions
-
-- **Stdout:** JSON. Commands that return a single record emit one JSON value. Commands that return a collection emit JSON Lines (one JSON object per line, no surrounding array) so per-item results stay streamable — this covers list reads (`selection ls`, `selection focus`, `node ls`, `node grep`, `asset ls`, `folder ls`, `models`, `voices`, `fonts`), selection mutations that return the new state, and batch operations (`node rm`, `node patch`, `node cp`, `asset add`, `asset rm`, `asset mv`, `asset export`, `folder mv`, `folder rm`). `node tree` emits one nested JSON object per root, and `asset tree` emits one nested object per root entry. Exceptions: `open` for file / URL / no-target writes nothing; `fonts --names-only` writes plain family names; `mount` and `node insert` write nothing.
-- **Unix-style names are canonical:** list/read → `ls`, delete/remove → `rm`, duplicate → `cp`, move/reparent → `mv`, search → `grep`. The longer English forms (`list`, `remove`, `duplicate`, `move`) are aliases of the Unix forms, not the other way around. `get` is a universal alias for `ls` on every command that has one. Applied wherever the semantics match; commands without a natural Unix equivalent (`tree`, `rename`, `patch`, `add`, `create`, `active`, `context`, `whoami`, `open`, `focus`, `set`) keep their descriptive names.
-- **Stderr:** human-readable error messages.
-- **Exit codes:** `0` on success, `1` on any error (missing file, app not running, invalid input, IPC error).
-- **App must be running:** every command except `open` and `fonts` talks to the open Diffusion Studio instance. If the app isn't running, the CLI prints an instruction to launch it and exits `1`.
diff --git a/apps/cli/jsx-spec.md b/apps/cli/jsx-spec.md
deleted file mode 100644
index 7ce3a761..00000000
--- a/apps/cli/jsx-spec.md
+++ /dev/null
@@ -1,701 +0,0 @@
-# JSX API Specification
-
-The JSX API defines the code contract for injecting content into the editor via the
-CLI. Compositions are authored as **Solid components** that a custom renderer (built
-on `solid-js/universal`, Solid's equivalent of React's reconciler) mounts **directly
-into the editor's ECS**. Every JSX element becomes an entity; every prop is a
-component write. There is no hidden DOM, no CSS resolution, and no measuring pass.
-
-A project is structured like a SolidJS app: a **root** is established on the canvas —
-typically a Scene, identified by its key and created if absent — and the project's
-component tree renders into it.
-
-**All positioning is explicit** (`x`, `y`, `width`, `height` in pixels).
-
-## Pipeline
-
-1. **Compile** — the CLI bundles the entry file with esbuild + `babel-preset-solid`
- in `universal` mode, so JSX compiles against the editor's renderer runtime
- (`@diffusionstudio/jsx`) instead of the DOM. Compile errors fail here, before the
- app is contacted.
-2. **Ship** — the resulting single-file ESM bundle is sent to the running app over
- the local socket.
-3. **Evaluate** — the app imports the module. Top-level code (including top-level
- `await`) runs to completion. The module's **default export** is the project
- component.
-4. **Mount** — the component tree is rendered into a **staging root**. The universal
- renderer materializes each element as an ECS entity with the appropriate
- components (see [Element reference](#element-reference)). Mounting is synchronous;
- an error here aborts the import with nothing inserted.
-5. **Commit** — the rendered roots are reconciled against the document (see
- [Roots](#roots)) as a **single undoable operation** that also covers the
- generated assets below.
-6. **Generate** — declared assets generate in dependency order, **blocking the
- command** until every one has landed. Each placeholder renders a generating
- state until its asset lands, then the node's paint is attached.
-7. **Sync** — nodes declaring `syncTo` are aligned once every generated asset
- has landed: each node's audio is cross-correlated against its target's and
- its `startTime` is written from the measured offset (see
- [Audio sync](#audio-sync)). Local and blocking; captions wait for it.
-
-## Project module contract
-
-The entry file is a standard Solid component module:
-
-```tsx
-export default function Project() {
- return (
- <scene key="intro" name="Intro" fill="black" width={1920} height={1080}>
- {/* ... */}
- </scene>
- );
-}
-```
-
-The component receives no props — which document node each rendered root
-maps onto is declared in the JSX itself via `key` (see [Roots](#roots)).
-
-### Module environment
-
-- **Provided by the host** (marked external at compile time, resolved in-app so the
- project shares the editor's reactive runtime): `solid-js`, `solid-js/store`,
- `@diffusionstudio/jsx`.
-- **Everything else is bundled** by the CLI at compile time — npm dependencies,
- local imports, JSON, etc. A project folder is an ordinary npm package: install
- any helper library (`date-fns`, `zod`, `d3-scale`, …) and import it; it is
- resolved from the project's `node_modules` and baked into the shipped bundle.
- Libraries must be browser-compatible (no Node builtins) — violations surface as
- compile errors, before the app is contacted.
-- The module executes **inside the editor process**, unsandboxed. This is local
- tooling with a local trust model — the same trust as running the CLI itself. Only
- effects made through the JSX runtime are part of the document (and its undo
- history); anything else the module does is unsupported.
-- Solid's control flow (`<For>`, `<Show>`, `<Index>`, `<Switch>`) and primitives
- (`createSignal`, `createMemo`, …) are fully available during mount. See
- [Lifecycle](#lifecycle) for what happens after mount.
-
-## Roots
-
-A mount renders one or more root elements (a fragment of roots is allowed) and
-**refreshes the document** — like reloading a webpage, re-running a mount
-rebuilds its roots in place instead of accumulating copies; a rendered root
-with no existing node to replace is created. Roots are typically `<scene>`
-elements, but any element can be a root (e.g. a bare `<rect>`). Every
-top-level element must declare its identity with a `key`:
-
-| Identity | Contract |
-| -------- | -------- |
-| `<scene key="intro">` | Rebuilds the existing node carrying the same key, or creates it (storing the key) if none does. Keyed nodes in the document that the render no longer produces are **deleted** — the mount owns its keyed roots. |
-
-Keys must be unique within a render, and rebuilding keeps the node's
-entity id and canvas position. Nodes without a key (e.g. hand-made scratch
-scenes) are never touched. The **first** rendered root becomes the active
-scene. Assigning a `name` alongside the key (e.g.
-`<scene key="intro" name="Intro">`) is recommended — the key identifies the
-node across mounts, the name labels it in the editor.
-
-`<scene>` is valid **only** at the document root — scenes do not nest.
-
-### Canvas placement
-
-The canvas holds many roots, but a root's position on the canvas is an **editor
-concern, not part of the composition** — `<scene>` has no `x`/`y`, and a project
-describes content, not canvas arrangement.
-
-- **Rebuilt roots** (matched by `key`) keep their existing canvas
- position.
-- **New roots** are placed automatically: in the nearest empty space around the
- current viewport center, gapped so they never overlap existing content — the
- same auto-placement the editor uses when generating onto the canvas. A mount
- that creates multiple roots places them side by side in render order.
-
-The camera is not moved; because placement anchors to the viewport center, new
-roots typically land in view. Use `dapi selection focus` to frame them explicitly.
-
-## Element reference
-
-Lowercase intrinsic elements map 1:1 onto internal node types:
-
-| Element | Internal node | Notes |
-| ------------ | ------------- | ----- |
-| `<scene>` | **Geometry with Scene tag** | Clips its children to `width`×`height`. Document root only. |
-| `<group>` | **Geometry with Group tag** | Container with a transform; give it `fill` to draw a rectangle. |
-| `<rect>` | **Geometry with Solid paint** | A filled rectangle; takes only paint children. |
-| `<video>` | **Geometry with Video paint** | `src` resolves to a video asset. |
-| `<image>` | **Geometry with Image paint** | `src` resolves to an image asset. |
-| `<audio>` | **Geometry with Audio component and a hidden Waveform paint** | No visual output; carries volume. |
-| `<text>` | **Geometry with Text component** | Children become editable glyphs. |
-| `<sequence>` | **Sequential group** | See [Sequences](#sequences). |
-| `<captions>` | **Caption node** | Transcribes the enclosing scene's audio. See [Captions](#captions). |
-| `<solidPaint>` | **Solid paint** | Paint child — see [Paints](#paints). |
-| `<linearGradientPaint>` / `<radialGradientPaint>` | **Gradient paint** | Paint child; takes `<colorStop>` children — see [Paints](#paints). |
-| `<colorStop>` | **Gradient color stop** | Valid only inside gradient paints. |
-
-User-defined components are ordinary Solid components — they compose intrinsics and
-carry no runtime cost; only intrinsic elements produce entities.
-
-### Coordinates and sizing
-
-- Coordinates are **pixels relative to the parent's box**, origin top-left. No
- percentages, no layout keywords — explicit numbers until the layout engine lands.
-- **Every element's box defaults to its parent's box**: `x` and `y` default to `0`,
- `width` and `height` default to the parent's size (the JSX analog of
- `position: absolute; inset: 0`). The scene's box is its required
- `width`×`height`.
-- How media pixels map into the box is controlled by `objectFit`, never by the box itself.
- A generated asset's placeholder therefore always has a definite size, even before
- the asset exists.
-
-### Common props
-
-All visual elements accept:
-
-| Prop | Type | Default | Meaning |
-| ---- | ---- | ------- | ------- |
-| `key` | `string` | — | Stable identity across mounts; **required** on document roots (see [Roots](#roots)). |
-| `name` | `string` | — | Human-readable node name. |
-| `x`, `y` | `Animatable<number>` | `0` | Position relative to the parent, px. |
-| `width`, `height` | `Animatable<number>` | parent size | Box size, px. |
-| `rotation` | `Animatable<number>` | `0` | Rotation in degrees. |
-| `opacity` | `Animatable<number>` | `1` | `0`–`1`. |
-| `cornerRadius` | `Animatable<number>` | `0` | Uniform corner radius, px. |
-| `inPoint`, `outPoint`, `startTime` | `Time` | see [Timing](#timing) | Temporal placement. |
-
-`Animatable` props also take a keyframe list — see [Animation](#animation).
-
-Common and per-element props share one property table, exported as
-`PatchProps`. `dapi node patch` accepts exactly these keys with the same value
-requirements as patch entries on existing nodes (see
-[CLI_API.md](./CLI_API.md#dapi-node-patch-path---json-str)).
-
-### Per-element props
-
-**`<scene>`** — `key` (**required** — see [Roots](#roots)), `width`
-(**required**), `height` (**required**), `name` (recommended), `fill`. No
-timing or transform props.
-
-**`<group>`** — common props plus `fill` (any CSS color, applied to the node's
-fill; alpha is ignored — use `opacity`).
-
-**`<rect>`** — common props plus `fill` (any CSS color, default light gray;
-alpha is ignored — use `opacity`). Takes only [paint children](#paints); use
-`cornerRadius` for rounded corners.
-
-**`<video>`** — common props plus:
-
-| Prop | Type | Default | Meaning |
-| ---- | ---- | ------- | ------- |
-| `src` | `string \| AssetRef` | **required** | See [Media source resolution](#media-source-resolution). |
-| `objectFit` | `"cover" \| "contain" \| "fill"` | `"cover"` | How the source maps into the box. |
-| `volume` | `Animatable<number>` | `1` | `0`–`1`; `1` = unity gain. |
-| `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |
-| `syncTo` | `string` | — | Key of another element carrying audio; derives `startTime` by audio alignment (see [Audio sync](#audio-sync)). Mutually exclusive with `startTime`. |
-
-**`<image>`** — common props plus `src` (**required**) and `objectFit` (default
-`"contain"`).
-
-**`<audio>`** — `name`, timing props, `src` (**required**), `volume`, `muted`,
-`syncTo` (see [Audio sync](#audio-sync)). No spatial props; no visual output.
-
-**`<text>`** — common props plus:
-
-| Prop | Type | Default | Meaning |
-| ---- | ---- | ------- | ------- |
-| children | `string` (or expressions resolving to strings) | **required** | The text content. |
-| `fontFamily` | `string` | editor default | A family available on the machine (`dapi fonts`). |
-| `fontSize` | `number` | editor default | Px. |
-| `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`–`900`. |
-| `fontStyle` | `"normal" \| "italic"` | `"normal"` | |
-| `fill` | `string` | none | Any CSS color. |
-| `textAlign` | `"left" \| "center" \| "right"` | `"left"` | Horizontal alignment of glyphs within the box. |
-| `textBaseline` | `"top" \| "middle" \| "bottom"` | `"top"` | Vertical alignment within the box. |
-
-Because the box defaults to the parent's box, a centered full-frame title is simply
-`<text textAlign="center" textBaseline="middle">…</text>`.
-
-**`<sequence>`** — `name` only. Purely structural (see [Sequences](#sequences)).
-
-**`<captions>`** —
-
-| Prop | Type | Default | Meaning |
-| ---- | ---- | ------- | ------- |
-| `preset` | `"classic" \| "cascade" \| "spotlight" \| "whisper" \| "paper" \| "guinea" \| "stark"` | `"classic"` | Caption style preset (see [Captions](#captions)). |
-| `colors` | `string[]` | preset defaults | Fills the preset's color slots in order; any CSS color, alpha ignored — use per-preset defaults by omitting. Ignored by presets without slots. |
-
-## Paints
-
-Internally a node's fill is not a property but a **paint child** — a sub-entity
-appended to the geometry, exactly like the editor's fill list. The `fill` prop is
-shorthand for a solid paint; declaring paints as JSX children exposes the full
-model, including gradients:
-
-```tsx
-<rect width={640} height={360} cornerRadius={24}>
- <linearGradientPaint rotation={90}>
- <colorStop offset={0} color="#FF0055" />
- <colorStop offset={1} color="#0055FF" />
- </linearGradientPaint>
-</rect>
-```
-
-Paint elements are valid inside any visual element (`<rect>`, `<group>`,
-`<scene>`, `<text>`, `<video>`, `<image>`). Multiple paints stack in document
-order — later paints render on top; a paint child on a `<video>`/`<image>`
-draws over the media paint created by `src`.
-
-| Element | Props | Meaning |
-| ------- | ----- | ------- |
-| `<solidPaint>` | `color` (**required**), `opacity` | Solid fill; equivalent to the `fill` prop. |
-| `<linearGradientPaint>` | `rotation`, `opacity` | Linear gradient across the parent's box; `rotation` in degrees, `0` = left → right. |
-| `<radialGradientPaint>` | `rotation`, `opacity` | Radial gradient centered in the parent's box. |
-| `<colorStop>` | `offset` (**required**, `0`–`1`), `color` (**required**), `opacity` | Gradient color stop. Valid only inside gradient paints, which take no other children. |
-
-Colors accept any CSS color; alpha is ignored — use `opacity`. Paints have no
-spatial or timing props and cannot be document roots.
-
-## Media source resolution
-
-`src` accepts:
-
-- **Global path** — e.g. `"/Movies/video.mp4"`, resolved against the user's OS.
-- **Remote URL** — e.g. `"https://my.videoarchive.com/audio/clip.wav"`, registered
- as a remote asset.
-- **Asset id** — e.g. `"gbHJ"`, an imported asset.
-- **`AssetRef`** — the value returned by an `generate.*` declaration (see
- [Generated assets](#generated-assets)). The node is inserted immediately as a
- placeholder and its paint is attached once the asset has generated.
-
-## Timing
-
-Timing props follow Lottie-inspired semantics. All values are
-**composition-relative** (measured against the parent's timeline), in any supported
-[time format](#time-formats).
-
-| Prop | Lottie | Meaning |
-| ---- | ------ | ------- |
-| `inPoint` | `ip` | Composition time at which the node becomes visible/audible. |
-| `outPoint` | `op` | Composition time at which the node stops. |
-| `startTime` | `st` | Composition time at which the node's *source* time 0 is placed. Shifts the source content within the in/out window. Defaults to the in point. |
-
-### Semantics
-
-- `inPoint` / `outPoint` define the **visible/audible window** on the parent
- timeline. They are a pair; if omitted, a media node fits its natural duration and
- a group auto-fits its children.
-- `startTime` controls **which part of the source plays inside that window**. It is
- the composition time where source frame 0 sits, so it may be negative to skip into
- the source.
-- Instead of declaring `startTime`, a media node can derive it from another node's
- audio with `syncTo` (see [Audio sync](#audio-sync)).
-
-> Example: `inPoint={0} outPoint={16} startTime="-30f"` shows the clip from
-> composition second 0 to 16, but because source-time-0 is placed 30 frames *before*
-> the in point, the first 30 frames (1s @ 30fps) of the source are trimmed —
-> playback begins 1s into the source.
-
-### Time formats
-
-```ts
-type Time = number | `${number}f` | `${string}:${string}`;
-```
-
-The canonical internal unit is frames at **30 fps**; all formats are converted on
-import. All values may be negative.
-
-| Format | Example | Meaning |
-| ------ | ------- | ------- |
-| `number` | `2.2` | Seconds (may be fractional). |
-| `"${number}f"` | `"-30f"` | Frames. |
-| `"MM:SS"` | `"02:30"` | Minutes and seconds. |
-| `"HH:MM:SS"` | `"01:02:30"` | Hours, minutes, seconds. |
-
-## Animation
-
-Animatable props accept a keyframe list in place of a static value:
-
-```tsx
-<image
- src="/photo.jpg"
- inPoint={0} outPoint={5}
- x={[
- { time: 0, value: -400 },
- { time: 1, value: 200, easing: "easeOut" },
- ]}
- opacity={[{ time: 0, value: 0 }, { time: "15f", value: 1 }]}
-/>
-```
-
-```ts
-type Keyframe<T> = { time: Time; value: T; easing?: Easing };
-type Animatable<T> = T | Keyframe<T>[];
-```
-
-Animatable props: `x`, `y`, `width`, `height`, `rotation`, `opacity`,
-`cornerRadius`, `volume`, `color`, `offset`. As part of the shared property
-table this applies to `dapi node patch` identically, and to paints and color
-stops (`color`, `opacity`, `offset` animate gradients).
-
-### Semantics
-
-- `time` is **node-local**: `0` is the node's in point, in any
- [time format](#time-formats). Timing props are composition-relative;
- keyframe times are not, so animation moves with the clip.
-- Outside the keyframed range the value holds at the first/last keyframe.
-- `easing` shapes the segment from its keyframe to the next; the last
- keyframe's easing is ignored. Default `"linear"`.
-- A **static value replaces any existing keyframes** on that property — mount
- and `dapi node patch` own what they set. Keyframes land as regular editor
- keyframes, editable in the timeline and inspector, and props the render
- doesn't set keep their hand-made tracks across re-mounts.
-
-### Easing
-
-| Easing | Use for |
-| ------ | ------- |
-| `"linear"` (default) | Constant-rate change. |
-| `"easeIn"`, `"easeOut"`, `"easeInOut"` | Standard acceleration curves (CSS equivalents). |
-| `"gentle"`, `"snappy"`, `"bouncy"`, `"strong"` | Spring presets, from soft settle to hard overshoot. |
-| `"cubicBezier(x1,y1,x2,y2)"` | Custom curve, CSS control points. |
-| `"spring(bounce,duration)"` | Custom spring: bounce `0`–`1`, duration in ms. |
-| `"steps(n)"` | Discrete hold: n equal steps, no interpolation. |
-
-Named presets expand to the same descriptors the editor's interpolation
-inspector writes, so they round-trip cleanly.
-
-## Sequences
-
-`<sequence>` enforces **sequential, non-overlapping** placement of its children —
-the editor's track-like behavior. It has no spatial or temporal properties of its
-own; it lays its children out back-to-back in document order.
-
-```tsx
-<sequence>
- <video src="/Movies/intro.mp4" inPoint={0} outPoint={12} />
- <video src="/Movies/main.mp4" inPoint={12} outPoint="02:30" />
- <video src="/Movies/outro.mp4" inPoint="02:30" outPoint="02:45" />
-</sequence>
-```
-
-## Audio sync
-
-`syncTo` places a node in time by listening instead of arithmetic: the node's
-audio is cross-correlated against another node's audio, and its `startTime` is
-computed so the two recordings coincide on the timeline. It replaces manual
-offset measurement for multi-recorder material: a lav or voice track against
-camera audio, two cameras on the same take, two microphones in one room.
-
-```tsx
-<scene key="talk" width={1920} height={1080}>
- <video key="camera" src="/Movies/take-3.mp4" inPoint={0} outPoint={45} muted />
- <audio src="/Movies/lav.wav" syncTo="camera" />
-</scene>
-```
-
-- `syncTo` names the `key` of another element in the same render. Both sides
- must carry an audio track; any pairing works (audio-to-video, audio-to-audio,
- video-to-video).
-- The computed placement is `startTime = target.startTime + offset`, where
- `offset` is the measured source-time offset between the two recordings
- (positive when this node's recording started after the target's; possibly
- negative). `syncTo` and `startTime` are mutually exclusive.
-- `inPoint`/`outPoint` keep their normal meaning and remain yours to set. When
- omitted on a synced node, the window defaults to the intersection of the
- node's natural extent with the target's window (instead of the usual
- natural-duration fit), so a lav track simply covers its take.
-- Alignment reads source content: `muted` and `volume` on either side do not
- affect the measurement. Use `muted` to keep only one side audible, as on the
- camera track above.
-- Chains resolve in dependency order (A may sync to B while B syncs to C).
- Unknown keys, cycles, and combining `syncTo` with `startTime` are mount
- errors; nothing is inserted.
-
-Alignment runs at the [sync stage](#pipeline) of the pipeline: after generated
-assets land (either side may be generated), before captions read the scene. It
-is local, consumes no credits, and blocks the command, so exit `0` means final
-placement. A correlation too weak to trust fails the command (see
-[Errors](#errors)) while the node keeps its default placement. Offsets are
-**cached** by the pair of source contents, so re-mounting an unchanged project
-re-measures nothing.
-
-Because `syncTo` is part of the shared property table, `dapi node patch`
-accepts it too: patching `syncTo` onto an existing node re-aligns it against
-the document node carrying that key.
-
-## Captions
-
-`<captions />` inside a scene transcribes that scene's audio into a caption node — a
-styled, timed transcript, produced on import. To caption an already-open scene,
-insert one with `dapi node insert.
-
-Transcription is **asynchronous and non-blocking**: the caption node is inserted at
-commit and its transcript attaches once ready. Because it reads the scene's audio,
-it runs **after** any generated assets in the scene have landed and after
-[audio sync](#audio-sync) has resolved — so captioning a generated
-`voice`/`audio` track transcribes the finished audio at its final placement. The
-scene must contain an unmuted audio or video source; otherwise the caption node
-is left empty.
-
-Transcripts are **cached**: every transcript asset records a fingerprint of the
-scene's audible mix (source content, placement, source offset, playback rate,
-gain). When a scene's fingerprint matches an existing transcript, that asset is
-reused instead of transcribing again — re-mounting a project with unchanged
-audio consumes no credits. Any change to the scene's audio invalidates the
-fingerprint.
-
-### Presets
-
-`preset` selects the caption style — the same presets as the editor's caption
-inspector. Some presets expose **color slots**, filled in order by the `colors`
-prop; a missing or omitted entry falls back to the slot's default.
-
-| Preset | Style | Color slots (defaults) |
-| ------ | ----- | ---------------------- |
-| `"classic"` (default) | Centered lowercase text with a soft drop shadow, a few words at a time. | — |
-| `"cascade"` | Light text in the lower left; words appear progressively as they are spoken. | — |
-| `"spotlight"` | Bold italic centered line; the spoken word lights up in the highlight color. | 1: highlight (`#24D5FF`) |
-| `"whisper"` | Small, wide, understated line shown in ~2 s phrases. | — |
-| `"paper"` | Centered two-line block; the line being spoken is emphasized with a heavier weight. | — |
-| `"guinea"` | Uppercase display text; the spoken word enlarges and cycles through the three colors. | 3: `#F55353`, `#FEB139`, `#F6F54D` |
-| `"stark"` | Heavy uppercase text blended into the footage with a difference blend. | — |
-
-```tsx
-<captions preset="spotlight" colors={["#FF0055"]} />
-```
-
-## Generated assets
-
-Assets that don't exist yet are **declared as values** with the `generate` namespace
-from `@diffusionstudio/jsx`. A declaration returns an **`AssetRef`** that is passed
-wherever a source is expected — `src`, `startFrame`, `endFrame`, `refs`. This makes
-generative content declarative: the project describes the asset it wants and the
-editor produces it on mount.
-
-```tsx
-import { generate } from "@diffusionstudio/jsx";
-
-const hero = generate.image({
- prompt: "A neon city at night, cinematic",
- model: "flux-2-turbo",
- aspectRatio: "16:9",
- seed: 42,
-});
-
-// one generated asset can feed another
-const heroMotion = generate.video({
- prompt: "slow camera push-in",
- model: "kling-3-pro",
- startFrame: hero,
- duration: 5,
-});
-
-export default function Project() {
- return (
- <scene key="intro" name="Intro" width={1920} height={1080}>
- <video src={heroMotion} inPoint={0} outPoint={5} />
- <image src={hero} x={40} y={40} width={200} height={112} />
- </scene>
- );
-}
-```
-
-Declarations are **pure**: calling `generate.*` registers a spec and returns a ref; no
-generation starts until [commit](#pipeline). A ref that is never used by a mounted
-element (directly or as an input to another asset) is dropped. Declarations may live
-at module scope or inside components.
-
-### Declaration options
-
-Run `dapi models <type>` to discover valid `model` ids and per-model constraints;
-`dapi voices` lists voices.
-
-```ts
-type AssetInput = string | AssetRef; // path, URL, asset id, or another declaration
-
-generate.image(opts: {
- prompt: string; // required
- model?: string; // default: first model from `dapi models image`
- aspectRatio?: "1:1" | "4:3" | "3:4" | "16:9" | "9:16"; // default "16:9"
- refs?: AssetInput[]; // image references
- seed?: number; // reproducible generation
-}): AssetRef;
-
-generate.video(opts: {
- prompt: string; // required
- model?: string; // default: first model from `dapi models video`
- aspectRatio?: "1:1" | "4:3" | "3:4" | "16:9" | "9:16"; // default "16:9"
- duration?: number; // whole seconds; default 5
- audio?: boolean; // generate audio alongside; models with the `audio` feature only
- startFrame?: AssetInput; // image used as the first frame
- endFrame?: AssetInput; // image used as the last frame; `end-frame` feature only
- seed?: number;
-}): AssetRef;
-
-generate.voice(opts: {
- prompt: string; // required — the text to speak
- voice?: string; // default: first voice from `dapi voices`
-}): AssetRef;
-
-generate.audio(opts: {
- prompt: string; // required
- model?: string; // default: first model from `dapi models audio`
-}): AssetRef;
-```
-
-### Dependency order
-
-`startFrame`, `endFrame`, and `refs` accept other `AssetRef`s. The dependency graph
-is built from these values and generated in topological order, so referenced assets
-exist before the assets that consume them. Because dependencies are **values, not
-string ids**, a declaration can only reference refs that already exist — reference
-cycles are impossible by construction. Assets referenced only as inputs generate
-too, but produce no node of their own.
-
-### Caching and idempotency
-
-Generation is long-running and consumes credits, so results are **cached by
-content** — a key derived from the fully-resolved spec (`type`, `model`, `prompt`,
-resolved references, `seed`, …). Within a session, re-running an unchanged project
-reuses cached assets instead of regenerating, and two declarations with identical
-specs collapse to a single asset; changing any option produces a new asset. Set
-`seed` to make a spec reproducible. The cache is per-session and is not persisted
-across app restarts.
-
-## Lifecycle
-
-Mounting is a **one-shot render**: the reactive graph exists to *compose* the
-document (loops, conditionals, derived values, component props), not to drive it
-afterward.
-
-1. The component tree renders synchronously into the staging root; `onMount`
- callbacks flush once.
-2. The subtree commits and the reactive root is **disposed**. Signal changes after
- commit do not affect the document.
-3. Ownership transfers to the document: every materialized node is a fully editable
- composition node. Asset generation is owned by the engine, not the
- reactive graph, so it proceeds normally after disposal.
-
-The update path is **re-running the project**, which rebuilds the mount root in
-place — like refreshing a webpage; unchanged asset specs hit the generation cache. A future *live
-mode* may keep the reactive root mounted so signals animate the document — the
-one-shot contract above is deliberately forward-compatible with it.
-
-## Errors
-
-| Stage | Where it surfaces | Effect |
-| ----- | ----------------- | ------ |
-| Compile (syntax/type-stripping/bundling) | CLI stderr, exit 1 | App never contacted. |
-| Evaluate / mount (thrown errors, invalid props, invalid root — e.g. nested `<scene>`, a root element without `key`, missing `src`, malformed `Time`, an unknown or cyclic `syncTo` key, `syncTo` combined with `startTime`) | CLI stderr, exit 1 | Staging root discarded; **nothing inserted**. |
-| Generation (per-model constraints: `aspectRatio`, `duration`, feature flags) | CLI stderr, exit 1, after every generation settled | No rollback — the mounted tree stays committed; the affected placeholder stops showing its generating state and is left without a paint. |
-| Sync (a side without a decodable audio track, or no reliable alignment) | CLI stderr, exit 1, after every alignment settled | No rollback; the tree stays committed and the node keeps its default placement. |
-
-Runtime errors are mapped back to the source via inline sourcemaps produced at
-compile time.
-
-## CLI surface
-
-The JSX pipeline is a single command, `dapi mount`; `dapi node insert` runs the
-same pipeline into an existing parent, and `dapi node patch` assigns the same
-props on existing nodes. `dapi models` and `dapi voices`
-(see [CLI_API.md](./CLI_API.md)) describe what can be referenced from `generate.*`
-declarations.
-
-### `dapi mount (<path> | --code <str>)`
-
-Compiles a project module, executes it in the app, and mounts the rendered roots
-into the document (see [Pipeline](#pipeline)). Which nodes are replaced is
-declared in the JSX via the root elements' `key` (see [Roots](#roots)).
-
-- **Input:**
- - `<path>` — path to a `.tsx` / `.jsx` / `.ts` / `.js` entry module. Exactly one
- of `<path>` or:
- - `--code <str>` — inline module source, compiled identically.
-- **Output:** none. The command exits `0` once the tree is committed and every
- declared asset has generated; inspect the result with `dapi context`,
- `dapi node ls`, or `dapi node tree`.
-- **Notes:** a newly added top-level scene becomes the active scene. The command
- is long-running when assets are declared — it blocks until generation
- finishes.
-
-## Types and tooling
-
-`@diffusionstudio/jsx` ships the JSX namespace (intrinsic elements and props),
-`Time`, `AssetRef`, and the `generate` namespace. For editor IntelliSense and
-typechecking in a project folder:
-
-```json
-{
- "compilerOptions": {
- "jsx": "preserve",
- "jsxImportSource": "@diffusionstudio/jsx"
- }
-}
-```
-
-The CLI does not typecheck — types are stripped at compile time. Run `tsc --noEmit`
-in the project folder for type safety.
-
-## Full example
-
-```tsx
-import { For } from "solid-js";
-import { generate, type Time } from "@diffusionstudio/jsx";
-
-const hero = generate.image({
- prompt: "A neon city at night, cinematic",
- aspectRatio: "16:9",
- seed: 42,
-});
-
-const heroMotion = generate.video({
- prompt: "slow camera push-in",
- startFrame: hero,
- duration: 5,
-});
-
-const TITLES = [
- { text: "Hello World", inPoint: 3, outPoint: 6 },
- { text: "Chapter One", inPoint: 6, outPoint: 9 },
-];
-
-function Title(props: { text: string; inPoint: Time; outPoint: Time }) {
- return (
- <text
- textAlign="center"
- textBaseline="middle"
- fill="#FFFFFF"
- fontSize={128}
- fontWeight="bold"
- height={1080}
- width={1920}
- inPoint={props.inPoint}
- outPoint={props.outPoint}
- >
- {props.text}
- </text>
- );
-}
-
-export default function Project() {
- return (
- <scene key="my-first-scene" name="MyFirstScene" fill="black" width={1920} height={1080}>
- <sequence>
- <video src={heroMotion} inPoint={0} outPoint={5} />
- <video src="/Movies/video.mp4" inPoint={5} outPoint={16} startTime="-30f" />
- </sequence>
-
- <image src={hero} x={40} y={40} width={200} height={112} />
-
- <For each={TITLES}>{(t) => <Title {...t} />}</For>
-
- <audio
- src="https://my.videoarchive.com/audio/video-xyz.wav"
- inPoint={2.2}
- outPoint={16}
- volume={0.5}
- />
-
- <captions />
- </scene>
- );
-}
-```
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
new file mode 100644
index 00000000..7731b31b
--- /dev/null
+++ b/apps/cli/reference/README.md
@@ -0,0 +1,114 @@
+# dapi CLI Reference
+
+Reference for `dapi`, the Diffusion Studio CLI. Every canvas and project command talks to the running app over a local socket. Responses are JSON written to stdout; errors are human-readable messages on stderr with a non-zero exit.
+
+Each feature command has its own file (linked below). The JSX code syntax consumed by [`mount`](./mount.md) and [`node insert`](./node/insert.md) is specified in [jsx/](./jsx/README.md).
+
+## Groups
+
+**Top-level:** [`open`](./open.md), [`whoami`](./whoami.md), [`context`](./context.md) (alias `ctx`), [`mount`](./mount.md), [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md).
+
+| Group | Alias | Scope |
+| ----- | ----- | ----- |
+| `selection` | `sel` | Read and mutate the current node selection. |
+| `node` | `n`, `entity` | Anything that targets one or more nodes; scenes are nodes too. |
+| `project` | `p` | Create, list, open, and delete projects. |
+| `asset` | `a` | Manage and inspect assets in the open project. |
+| `folder` | `fld` | Organize the asset library into folders. |
+
+How the surface is divided:
+
+- Declarative composition happens through `mount`, which renders a Solid JSX project into the canvas (see [jsx/](./jsx/README.md)); `node insert` runs the same pipeline but inserts the rendered nodes into an existing parent entity instead of mounting document roots.
+- Scenes are created declaratively via `mount` (`<scene key="...">`); there is no imperative scene command.
+- AI asset generation (image / video / speech / audio) is declared in the project module (`generate.*`, see [jsx/generate.md](./jsx/generate.md)) and produced on mount. `models` and `voices` list what those declarations can reference.
+- Inspecting an existing asset (probe / transcribe / analyze / visualize / frame) lives under `asset`; writing an asset's original file back to disk is `asset export`.
+- Organizing the library lives under `folder`; moving assets between folders is `asset mv`.
+
+## Commands
+
+### App
+
+- [`dapi open`](./open.md): launch the app, or open a file, folder, or deep link
+- [`dapi whoami`](./whoami.md): print the authenticated account
+
+### Document
+
+- [`dapi context`](./context.md): essential context about the open project
+- [`dapi mount`](./mount.md): compile a Solid JSX project module and mount it into the canvas
+
+### Selection
+
+- [`dapi selection ls`](./selection/ls.md): list the selected nodes
+- [`dapi selection set`](./selection/set.md): replace the selection
+- [`dapi selection focus`](./selection/focus.md): frame the selection on the canvas
+
+### Nodes
+
+- [`dapi node ls`](./node/ls.md): raw entity records
+- [`dapi node tree`](./node/tree.md): an entity's subtree as nested JSON
+- [`dapi node grep`](./node/grep.md): search entity records with a regex
+- [`dapi node screenshot`](./node/screenshot.md): capture a node as a PNG
+- [`dapi node insert`](./node/insert.md): render a JSX module into an existing parent
+- [`dapi node rm`](./node/rm.md): delete entities
+- [`dapi node cp`](./node/cp.md): deep-clone nodes
+- [`dapi node patch`](./node/patch.md): assign JSX props on existing entities
+- [`dapi node render`](./node/render.md): render a scene to a video file
+
+### Projects
+
+- [`dapi project active`](./project/active.md): print the active project
+- [`dapi project ls`](./project/ls.md): list projects
+- [`dapi project create`](./project/create.md): create and open a project
+- [`dapi project set`](./project/set.md): set the active project
+- [`dapi project rm`](./project/rm.md): delete a project
+
+### Assets
+
+- [`dapi asset add`](./asset/add.md): add local files as assets
+- [`dapi asset ls`](./asset/ls.md): raw asset records
+- [`dapi asset tree`](./asset/tree.md): the library as its folder tree
+- [`dapi asset rm`](./asset/rm.md): delete assets
+- [`dapi asset mv`](./asset/mv.md): move assets into a folder
+- [`dapi asset export`](./asset/export.md): write assets' original bytes to disk
+- [`dapi asset probe`](./asset/probe.md): container and track metadata
+- [`dapi asset transcribe`](./asset/transcribe.md): timed speech transcript
+- [`dapi asset frame`](./asset/frame.md): decode video frames to PNGs
+- [`dapi asset visualize`](./asset/visualize.md): waveform / filmstrip / thumbnail PNG
+- [`dapi asset analyze`](./asset/analyze.md): AI description of an asset
+
+### Folders
+
+- [`dapi folder ls`](./folder/ls.md): list child folders
+- [`dapi folder create`](./folder/create.md): create a folder
+- [`dapi folder rename`](./folder/rename.md): rename a folder
+- [`dapi folder mv`](./folder/mv.md): reparent folders
+- [`dapi folder rm`](./folder/rm.md): delete folders (cascades)
+
+### Generation reference
+
+- [`dapi models`](./models.md): list generation models and constraints
+- [`dapi voices`](./voices.md): list speech voices
+
+### Fonts
+
+- [`dapi fonts`](./fonts.md): list local fonts
+
+## Shared types
+
+```ts
+NodeRef = { id: number; name: string; type: string } // node ids are entity ids: integers
+Size = { width: number; height: number }
+Asset = { id: string; name: string; type: string } // asset ids are opaque strings (sqids)
+Folder = { id: string; name: string; type: 'folder' } // folder ids are opaque strings (sqids)
+Time = number | `${number}f` | "MM:SS" // seconds, frames at 30 fps ("45f"), or a clock string; see jsx/timing.md
+```
+
+Time inputs take the `Time` format unless noted otherwise. Times in **outputs** are plain seconds, except the raw records of `node ls`, which use engine units (frames at 30 fps, packed colors, dB).
+
+## Conventions
+
+- **Stdout is JSON.** Commands that return a single record emit one JSON value. Commands that return a collection emit JSON Lines (one object per line, no surrounding array) so per-item results stay streamable. `node tree` and `asset tree` emit one nested object per root. Exceptions: `open` for file / URL / no-target writes nothing; `fonts --names-only` writes plain family names; `mount` and `node insert` write nothing.
+- **Unix-style names are canonical:** list/read is `ls`, delete is `rm`, duplicate is `cp`, move/reparent is `mv`, search is `grep`. The longer English forms (`list`, `remove`, `duplicate`, `move`) are aliases of the Unix forms, not the other way around. `get` is a universal alias for `ls`. Commands without a natural Unix equivalent (`tree`, `rename`, `patch`, `add`, `create`, `active`, `context`, `whoami`, `open`, `focus`, `set`) keep their descriptive names.
+- **Stderr:** human-readable error messages.
+- **Exit codes:** `0` on success, `1` on any error (missing file, app not running, invalid input, IPC error).
+- **App must be running:** every command except `open` and `fonts` talks to the open Diffusion Studio instance. If the app isn't running, the CLI prints an instruction to launch it and exits `1`.
diff --git a/apps/cli/reference/asset/add.md b/apps/cli/reference/asset/add.md
new file mode 100644
index 00000000..dd67dce6
--- /dev/null
+++ b/apps/cli/reference/asset/add.md
@@ -0,0 +1,21 @@
+# `dapi asset add <paths...>`
+
+Adds one or more local files as assets in the open project. The counterpart of [`asset export`](./export.md).
+
+## Input
+
+- `<paths...>`: absolute or relative file paths (resolved against CWD)
+- `--folder <id>`: folder to place the new assets in (optional; default the library root)
+
+## Output
+
+JSON Lines, one per input path:
+
+```ts
+| ({ status: "fulfilled"; path: string } & Asset)
+| { status: "rejected"; path: string; error: string }
+```
+
+## Errors
+
+Exits non-zero before importing anything if `--folder` doesn't resolve to a folder.
diff --git a/apps/cli/reference/asset/analyze.md b/apps/cli/reference/asset/analyze.md
new file mode 100644
index 00000000..abeca34e
--- /dev/null
+++ b/apps/cli/reference/asset/analyze.md
@@ -0,0 +1,22 @@
+# `dapi asset analyze <id|path>`
+
+Analyzes an image, video, or audio asset with a multimodal model. With no prompt it returns a general description of the asset; with `--prompt` it answers that question about the asset (e.g. "what's the dominant color?", "summarize what happens").
+
+## Input
+
+- `<id|path>`: an image, audio, or video asset id, or a local file to add and analyze (required).
+- `-p, --prompt <str>`: question or instruction about the asset (optional; defaults to a general description).
+- `-s, --start <time>`: start of the segment to analyze, a `Time` value (optional; default `0`). Timestamps in the analysis are relative to this point. Ignored for images.
+- `-e, --end <time>`: end of the segment to analyze, a `Time` value (optional; default the asset's duration). Ignored for images.
+
+## Output
+
+One JSON object, the model's answer:
+
+```ts
+{ id: string; analysis: string } // id = the analyzed asset id
+```
+
+## Errors
+
+Exits non-zero if the id is unknown, or the asset's media type isn't supported by the chosen model.
diff --git a/apps/cli/reference/asset/export.md b/apps/cli/reference/asset/export.md
new file mode 100644
index 00000000..4bc20652
--- /dev/null
+++ b/apps/cli/reference/asset/export.md
@@ -0,0 +1,23 @@
+# `dapi asset export <ids...>`
+
+Writes one or more assets' original file bytes to a location on the file system: the exact bytes stored in the library, streamed to disk in chunks (never buffered whole). No re-encode, no processing, no credits. Any asset type is accepted except image sequences. The counterpart of [`asset add`](./add.md).
+
+## Input
+
+- `<ids...>`: asset ids (required)
+- `-o, --output <path>`: where to write (optional; default the system temp directory). Interpreted as:
+ - **a directory** when the path is an existing directory, ends with a path separator, or multiple ids are given. Created if missing. Each asset is written into it named after the asset, with an extension derived from its media type when the name lacks one. A name that collides with an existing file is uniquified with a ` (N)` suffix, never overwritten.
+ - **a file path** otherwise (single id only). Written exactly there, overwriting an existing file.
+
+## Output
+
+JSON Lines, one per input id, in the requested order:
+
+```ts
+| { status: "fulfilled"; id: string; path: string } // path = the file actually written
+| { status: "rejected"; id: string; error: string }
+```
+
+## Errors
+
+Exits non-zero before writing anything if `--output` must be a directory (multiple ids, or a trailing path separator) but resolves to an existing file, or if the output directory can't be created. An unknown id, or an image-sequence asset, rejects that id only; a rejected asset leaves no partial file behind.
diff --git a/apps/cli/reference/asset/frame.md b/apps/cli/reference/asset/frame.md
new file mode 100644
index 00000000..8035d3e9
--- /dev/null
+++ b/apps/cli/reference/asset/frame.md
@@ -0,0 +1,21 @@
+# `dapi asset frame <id|path>`
+
+Decodes one or more frames of a video asset at the given times and writes each to a PNG file; like [`node screenshot`](../node/screenshot.md), but grabs the asset's own pixels at full resolution (unlike `node screenshot`, which captures the composited canvas). Renders locally; no credits.
+
+## Input
+
+- `<id|path>`: a video asset id, or a local video file to add and grab frames from (required).
+- `-t, --time <time...>`: one or more timestamps to grab, `Time` values in source/content time (optional; default `0`). Order is preserved in the output regardless of the order given.
+- `-o, --output <dir>`: directory to write the PNGs into (optional; default the system temp directory). Each frame is written as a uuid-named `.png`.
+
+## Output
+
+JSON Lines, one object per requested timestamp, in the requested order:
+
+```ts
+{ time: number; path: string } // time = the requested timestamp in seconds; path = the written PNG
+```
+
+## Errors
+
+Exits non-zero if the id is unknown, the asset is not a video, any `--time` is past the asset's duration, or a PNG can't be written.
diff --git a/apps/cli/reference/asset/ls.md b/apps/cli/reference/asset/ls.md
new file mode 100644
index 00000000..b316fab7
--- /dev/null
+++ b/apps/cli/reference/asset/ls.md
@@ -0,0 +1,20 @@
+# `dapi asset ls [ids...]`
+
+The raw asset records, as persisted minus the file handles: every serializable property the asset carries (per-type media metadata, `folderId`, a stored `transcript`, …). The property-level counterpart to [`asset tree`](./tree.md)'s structure. With no ids, returns every asset in the library. Alias: `get`.
+
+## Input
+
+- `[ids...]`: zero or more asset ids (optional)
+
+## Output
+
+JSON Lines, one per asset:
+
+```ts
+AssetRecord = { id: string } & { [property: string]: unknown }
+// e.g. name, type, mimeType, size, createdAt, folderId; duration/width/height/… by type
+```
+
+## Errors
+
+If any input id fails to resolve, writes a per-id message to stderr and exits non-zero after emitting all successful records to stdout.
diff --git a/apps/cli/reference/asset/mv.md b/apps/cli/reference/asset/mv.md
new file mode 100644
index 00000000..bab227be
--- /dev/null
+++ b/apps/cli/reference/asset/mv.md
@@ -0,0 +1,21 @@
+# `dapi asset mv <ids...> [--to <folderId>]`
+
+Moves one or more assets into a folder. Alias: `move`.
+
+## Input
+
+- `<ids...>`: asset ids (required)
+- `--to <folderId>`: destination folder (optional; omitted = the library root)
+
+## Output
+
+JSON Lines, one per input id:
+
+```ts
+| { status: "fulfilled"; id: string; folderId: string | null }
+| { status: "rejected"; id: string; error: string }
+```
+
+## Errors
+
+Exits non-zero before moving anything if `--to` doesn't resolve to a folder; an unknown asset id rejects that id only.
diff --git a/apps/cli/reference/asset/probe.md b/apps/cli/reference/asset/probe.md
new file mode 100644
index 00000000..54e0edc6
--- /dev/null
+++ b/apps/cli/reference/asset/probe.md
@@ -0,0 +1,15 @@
+# `dapi asset probe <id|path>`
+
+Reads the container and per-track technical metadata of an asset; like `ffprobe`, but demuxed locally with mediabunny. Reports the container format, duration, metadata tags, and every track's codec parameters without decoding any media. Reads locally; no credits.
+
+## Input
+
+- `<id|path>`: an asset id, or a local file to add and probe (required). Any asset type is accepted.
+
+## Output
+
+One JSON object. The shape is **not yet stable**: it reports whatever mediabunny surfaces about the container and its tracks. Packet stats (frame rate, bitrate, packet count) are estimated from a leading sample of packets, so they are fast but approximate. Assets mediabunny can't demux (images, transcripts) don't error; they report file-level info only, with `format: null` and no tracks.
+
+## Errors
+
+Exits non-zero if the id is unknown.
diff --git a/apps/cli/reference/asset/rm.md b/apps/cli/reference/asset/rm.md
new file mode 100644
index 00000000..eef45210
--- /dev/null
+++ b/apps/cli/reference/asset/rm.md
@@ -0,0 +1,16 @@
+# `dapi asset rm <ids...>`
+
+Deletes one or more assets from the open project by id. Alias: `remove`.
+
+## Input
+
+- `<ids...>`: asset ids (required)
+
+## Output
+
+JSON Lines, one per input id:
+
+```ts
+| { status: "fulfilled"; id: string; name: string }
+| { status: "rejected"; id: string; error: string }
+```
diff --git a/apps/cli/reference/asset/transcribe.md b/apps/cli/reference/asset/transcribe.md
new file mode 100644
index 00000000..8860b240
--- /dev/null
+++ b/apps/cli/reference/asset/transcribe.md
@@ -0,0 +1,25 @@
+# `dapi asset transcribe <id|path>`
+
+Transcribes the speech in a video or audio asset and returns the timed transcript. Word-level start/end times are in **seconds** (source/content time).
+
+## Input
+
+- `<id|path>`: a video or audio asset id, or a local file to add and transcribe (required).
+
+## Output
+
+One JSON object, the transcript:
+
+```ts
+{
+ id: string; // the asset id
+ segments: Array<{
+ text: string; // spoken words only (no silence markers)
+ words: Array<{ text: string; start: number; end: number }>; // seconds
+ }>;
+}
+```
+
+## Errors
+
+Exits non-zero if the id is unknown or the asset is not a video/audio asset, or if no speech is detected in the audio (`No speech detected`).
diff --git a/apps/cli/reference/asset/tree.md b/apps/cli/reference/asset/tree.md
new file mode 100644
index 00000000..ff0d4fe0
--- /dev/null
+++ b/apps/cli/reference/asset/tree.md
@@ -0,0 +1,22 @@
+# `dapi asset tree`
+
+Prints the asset library of the open project as its folder tree: folders and assets interleaved in one array, each folder carrying its contents in `children`.
+
+## Input
+
+- `--folder <id>`: folder whose contents to list (optional; default the library root)
+- `--depth <N>`: max depth, positive integer (optional; default = full tree). `--depth 1` yields just the direct entries of the listing root; a folder at the cutoff is listed without `children` (indistinguishable from a genuinely empty folder; raise the depth to tell them apart).
+
+## Output
+
+JSON Lines, one per entry of the listing root (no output if the listing root is empty); each entry carries its own subtree in `children`:
+
+```ts
+AssetTree = Array<(Asset | Folder) & { children?: AssetTree }> // one root entry per line
+```
+
+Folders are the entries with type `folder`. `children` is present only on folders with contents; assets never carry it.
+
+## Errors
+
+Exits non-zero if `--folder` doesn't resolve to a folder.
diff --git a/apps/cli/reference/asset/visualize.md b/apps/cli/reference/asset/visualize.md
new file mode 100644
index 00000000..e93a64d0
--- /dev/null
+++ b/apps/cli/reference/asset/visualize.md
@@ -0,0 +1,29 @@
+# `dapi asset visualize <id|path>`
+
+Renders a visual preview of an asset to a PNG, written to a file in the system temp directory. The visualization is chosen by the asset's media type, so a single command covers the whole library. Renders locally; no credits. Alias: `viz`.
+
+## By media type
+
+- **audio**: an amplitude waveform with a time axis (tick labels along the bottom in `mm:ss`), drawn from decoded audio peaks.
+- **video**: a composite: a **filmstrip** of frames sampled at even intervals across the window, with the **waveform** of the video's audio track drawn beneath it, sharing one `mm:ss` (or milliseconds) time axis. Videos with no audio track render the filmstrip alone.
+- **image**: a thumbnail of the image, auto-scaled.
+
+## Input
+
+- `<id|path>`: an image, audio, or video asset id, or a local file to add and visualize (required).
+- `-s, --start <time>`: start of the window to visualize, a `Time` value in source/content time (optional; default `0`). Ignored for images.
+- `-e, --end <time>`: end of the window to visualize, a `Time` value (optional; default the asset's duration). Ignored for images.
+- `-x, --scale <factor>`: scale factor for the thumbnails (optional; default `1`, clamped to `0.25`-`4`). The overall canvas size stays fixed, so smaller thumbnails fit **more rows and columns** (a denser grid sampling more moments) and larger thumbnails fit fewer but show more detail each. For images, scales the output resolution instead (never above the source size).
+- `-o, --output <path>`: write the PNG here instead of a temp file (optional).
+
+## Output
+
+One JSON object, the absolute path to the written PNG:
+
+```ts
+{ path: string } // e.g. "/tmp/3f2c1a8e-....png", or the --output path
+```
+
+## Errors
+
+Exits non-zero if the id is unknown, the media type isn't visualizable (e.g. a transcript asset, or an audio asset with no decodable audio), `--start`/`--end` fall outside the asset or cross (`--start` >= `--end`), `--scale` isn't a positive number, or `--output` can't be written.
diff --git a/apps/cli/reference/context.md b/apps/cli/reference/context.md
new file mode 100644
index 00000000..97661784
--- /dev/null
+++ b/apps/cli/reference/context.md
@@ -0,0 +1,22 @@
+# `dapi context`
+
+Essential context about the open project. Call this first to understand the canvas situation. Alias: `ctx`.
+
+## Input
+
+None.
+
+## Output
+
+One JSON object:
+
+```ts
+{
+ project: { id: string; name: string };
+ entityCount: number;
+ scenes: Array<{ id: number; name: string; size: Size }>;
+ activeSceneId: number | null; // null if no scene is active
+ currentFrame: number; // current timeline playhead position, in frames
+ fontFamilies: string[];
+}
+```
diff --git a/apps/cli/reference/folder/create.md b/apps/cli/reference/folder/create.md
new file mode 100644
index 00000000..a4dd1448
--- /dev/null
+++ b/apps/cli/reference/folder/create.md
@@ -0,0 +1,20 @@
+# `dapi folder create <name> [-p, --parent <id>]`
+
+Creates a folder.
+
+## Input
+
+- `<name>`: folder name (required)
+- `-p, --parent <id>`: parent folder (optional; omitted = the library root)
+
+## Output
+
+One JSON object:
+
+```ts
+Folder // { id: string; name: string; type: 'folder' }
+```
+
+## Errors
+
+Exits non-zero if `--parent` doesn't resolve to a folder.
diff --git a/apps/cli/reference/folder/ls.md b/apps/cli/reference/folder/ls.md
new file mode 100644
index 00000000..001d58de
--- /dev/null
+++ b/apps/cli/reference/folder/ls.md
@@ -0,0 +1,21 @@
+# `dapi folder ls [parentId]`
+
+Lists the direct child folders of a parent folder, sorted by name. With no id, lists the root-level folders. Aliases: `list`, `get`.
+
+Folders organize the asset library and nest arbitrarily; assets reference their containing folder via `folderId` (`null` = library root). Everywhere a folder id is optional, omitting it means the library root; there is no sentinel value for the root. Read the full hierarchy (folders and assets together) with [`asset tree`](../asset/tree.md); move assets between folders with [`asset mv`](../asset/mv.md).
+
+## Input
+
+- `[parentId]`: parent folder id (optional; omitted = the library root)
+
+## Output
+
+JSON Lines, one per child folder (no output if the parent has no subfolders):
+
+```ts
+Folder // { id: string; name: string; type: 'folder' }
+```
+
+## Errors
+
+Exits non-zero if `[parentId]` doesn't resolve to a folder.
diff --git a/apps/cli/reference/folder/mv.md b/apps/cli/reference/folder/mv.md
new file mode 100644
index 00000000..721e971d
--- /dev/null
+++ b/apps/cli/reference/folder/mv.md
@@ -0,0 +1,21 @@
+# `dapi folder mv <ids...> [--to <folderId>]`
+
+Moves one or more folders under a new parent. A folder cannot be moved into itself or any of its descendants; such a move rejects that id and leaves it where it was. Alias: `move`.
+
+## Input
+
+- `<ids...>`: folder ids (required)
+- `--to <folderId>`: destination parent folder (optional; omitted = the library root)
+
+## Output
+
+JSON Lines, one per input id:
+
+```ts
+| { status: "fulfilled"; id: string; parentId: string | null }
+| { status: "rejected"; id: string; error: string } // unknown id, or a cycle
+```
+
+## Errors
+
+Exits non-zero before moving anything if `--to` doesn't resolve to a folder.
diff --git a/apps/cli/reference/folder/rename.md b/apps/cli/reference/folder/rename.md
new file mode 100644
index 00000000..61830086
--- /dev/null
+++ b/apps/cli/reference/folder/rename.md
@@ -0,0 +1,16 @@
+# `dapi folder rename <id> <name>`
+
+Renames a folder.
+
+## Input
+
+- `<id>`: folder id (required)
+- `<name>`: new name (required)
+
+## Output
+
+One JSON object:
+
+```ts
+Folder // { id: string; name: string; type: 'folder' }
+```
diff --git a/apps/cli/reference/folder/rm.md b/apps/cli/reference/folder/rm.md
new file mode 100644
index 00000000..909fb169
--- /dev/null
+++ b/apps/cli/reference/folder/rm.md
@@ -0,0 +1,17 @@
+# `dapi folder rm <ids...>`
+
+Deletes one or more folders. **Deletion cascades:** every descendant folder and every asset inside the subtree is deleted with it. The fulfilled record reports what the cascade removed, so callers can detect when a delete swept more than intended. Alias: `remove`.
+
+## Input
+
+- `<ids...>`: folder ids (required)
+
+## Output
+
+JSON Lines, one per input id:
+
+```ts
+| { status: "fulfilled"; id: string; deletedFolders: number; deletedAssets: number }
+ // deletedFolders counts the folder itself plus all descendants
+| { status: "rejected"; id: string; error: string }
+```
diff --git a/apps/cli/reference/fonts.md b/apps/cli/reference/fonts.md
new file mode 100644
index 00000000..34b96b4e
--- /dev/null
+++ b/apps/cli/reference/fonts.md
@@ -0,0 +1,26 @@
+# `dapi fonts`
+
+Lists local fonts available on this machine. macOS only. Does not require the app to be running. Font families listed here are valid `fontFamily` values on [`<text>`](./jsx/text.md).
+
+## Options
+
+- `-f, --family <pattern>`: filter to families whose name contains `<pattern>` (case-insensitive)
+- `-w, --weight <weights...>`: filter to variants with the given CSS weight(s), e.g. `-w 400 700`
+- `-s, --style <style>`: `"normal"` or `"italic"`
+- `-l, --limit <n>`: output at most `<n>` families
+- `-n, --names-only`: output only family names, one per line, plain text (no JSON)
+
+## Output
+
+JSON Lines, one per family (or plain family names when `--names-only` is set):
+
+```ts
+{
+ family: string;
+ variants: Array<{
+ weight: string; // CSS weight, e.g. "400"
+ style: "normal" | "italic";
+ source: string; // CSS local() source
+ }>;
+}
+```
diff --git a/apps/cli/reference/jsx/README.md b/apps/cli/reference/jsx/README.md
new file mode 100644
index 00000000..162aec2c
--- /dev/null
+++ b/apps/cli/reference/jsx/README.md
@@ -0,0 +1,103 @@
+# JSX Code Syntax
+
+The JSX API defines the code contract for injecting content into the editor via the CLI. Compositions are authored as **Solid components** that a custom renderer (built on `solid-js/universal`, Solid's equivalent of React's reconciler) mounts **directly into the editor's ECS**. Every JSX element becomes an entity; every prop is a component write. There is no hidden DOM, no CSS resolution, and no measuring pass.
+
+A project is structured like a SolidJS app: a **root** is established on the canvas (typically a Scene, identified by its key and created if absent) and the project's component tree renders into it. **All positioning is explicit** (`x`, `y`, `width`, `height` in pixels).
+
+The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the project's roots into the document, and [`dapi node insert`](../node/insert.md) runs the same pipeline into an existing parent entity. [`dapi node patch`](../node/patch.md) assigns the same props on existing nodes.
+
+## Contents
+
+| File | Covers |
+| ---- | ------ |
+| [module.md](./module.md) | Project module contract, module environment, types and tooling |
+| [roots.md](./roots.md) | Root elements, `key` identity, canvas placement |
+| [elements.md](./elements.md) | Element-to-node mapping, coordinates and sizing, the shared property table |
+| [scene.md](./scene.md), [group.md](./group.md), [rect.md](./rect.md), [text.md](./text.md), [video.md](./video.md), [image.md](./image.md), [audio.md](./audio.md) | Per-element props |
+| [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>` |
+| [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`) |
+| [timing.md](./timing.md) | `inPoint` / `outPoint` / `startTime`, time formats |
+| [keyframes.md](./keyframes.md) | Keyframe animation and easing |
+| [transitions.md](./transitions.md) | The `transition` prop on sequence clips |
+| [sequences.md](./sequences.md) | `<sequence>` sequential placement |
+| [audio-sync.md](./audio-sync.md) | `syncTo` audio alignment |
+| [captions.md](./captions.md) | `<captions>` and style presets |
+| [generate.md](./generate.md) | Declarative AI asset generation (`generate.*`) |
+| [lifecycle.md](./lifecycle.md) | One-shot render lifecycle |
+| [errors.md](./errors.md) | Where each pipeline stage fails and with what effect |
+
+## Pipeline
+
+1. **Compile**: the CLI bundles the entry file with esbuild + `babel-preset-solid` in `universal` mode, so JSX compiles against the editor's renderer runtime (`@diffusionstudio/jsx`) instead of the DOM. Compile errors fail here, before the app is contacted.
+2. **Ship**: the resulting single-file ESM bundle is sent to the running app over the local socket.
+3. **Evaluate**: the app imports the module. Top-level code (including top-level `await`) runs to completion. The module's **default export** is the project component.
+4. **Mount**: the component tree is rendered into a **staging root**. The universal renderer materializes each element as an ECS entity with the appropriate components (see [elements.md](./elements.md)). Mounting is synchronous; an error here aborts the import with nothing inserted.
+5. **Commit**: the rendered roots are reconciled against the document (see [roots.md](./roots.md)) as a **single undoable operation** that also covers the generated assets below.
+6. **Generate**: declared assets generate in dependency order, **blocking the command** until every one has landed. Each placeholder renders a generating state until its asset lands, then the node's paint is attached (see [generate.md](./generate.md)).
+7. **Sync**: nodes declaring `syncTo` are aligned once every generated asset has landed: each node's audio is cross-correlated against its target's and its `startTime` is written from the measured offset (see [audio-sync.md](./audio-sync.md)). Local and blocking; captions wait for it.
+
+## Full example
+
+```tsx
+import { For } from "solid-js";
+import { generate, type Time } from "@diffusionstudio/jsx";
+
+const hero = generate.image({
+ prompt: "A neon city at night, cinematic",
+ aspectRatio: "16:9",
+ seed: 42,
+});
+
+const heroMotion = generate.video({
+ prompt: "slow camera push-in",
+ startFrame: hero,
+ duration: 5,
+});
+
+const TITLES = [
+ { text: "Hello World", inPoint: 3, outPoint: 6 },
+ { text: "Chapter One", inPoint: 6, outPoint: 9 },
+];
+
+function Title(props: { text: string; inPoint: Time; outPoint: Time }) {
+ return (
+ <text
+ textAlign="center"
+ textBaseline="middle"
+ color="#FFFFFF"
+ fontSize={128}
+ fontWeight="bold"
+ height={1080}
+ width={1920}
+ inPoint={props.inPoint}
+ outPoint={props.outPoint}
+ >
+ {props.text}
+ </text>
+ );
+}
+
+export default function Project() {
+ return (
+ <scene key="my-first-scene" name="MyFirstScene" fill="black" width={1920} height={1080}>
+ <sequence>
+ <video src={heroMotion} inPoint={0} outPoint={5} transition={{ type: "dissolve" }} />
+ <video src="/Movies/video.mp4" inPoint={5} outPoint={16} startTime="-30f" />
+ </sequence>
+
+ <image src={hero} x={40} y={40} width={200} height={112} />
+
+ <For each={TITLES}>{(t) => <Title {...t} />}</For>
+
+ <audio
+ src="https://my.videoarchive.com/audio/video-xyz.wav"
+ inPoint={2.2}
+ outPoint={16}
+ volume={0.5}
+ />
+
+ <captions />
+ </scene>
+ );
+}
+```
diff --git a/apps/cli/reference/jsx/audio-sync.md b/apps/cli/reference/jsx/audio-sync.md
new file mode 100644
index 00000000..082b94d2
--- /dev/null
+++ b/apps/cli/reference/jsx/audio-sync.md
@@ -0,0 +1,24 @@
+# Audio sync
+
+`syncTo` places a node in time by listening instead of arithmetic: the node's audio is cross-correlated against another node's audio, and its `startTime` is computed so the two recordings coincide on the timeline. It replaces manual offset measurement for multi-recorder material: a lav or voice track against camera audio, two cameras on the same take, two microphones in one room.
+
+```tsx
+<scene key="talk" width={1920} height={1080}>
+ <video key="camera" src="/Movies/take-3.mp4" inPoint={0} outPoint={45} muted />
+ <audio src="/Movies/lav.wav" syncTo="camera" />
+</scene>
+```
+
+## Semantics
+
+- `syncTo` names the `key` of another element in the same render. Both sides must carry an audio track; any pairing works (audio-to-video, audio-to-audio, video-to-video).
+- The computed placement is `startTime = target.startTime + offset`, where `offset` is the measured source-time offset between the two recordings (positive when this node's recording started after the target's; possibly negative). `syncTo` and `startTime` are mutually exclusive.
+- `inPoint`/`outPoint` keep their normal meaning and remain yours to set. When omitted on a synced node, the window defaults to the intersection of the node's natural extent with the target's window (instead of the usual natural-duration fit), so a lav track simply covers its take.
+- Alignment reads source content: `muted` and `volume` on either side do not affect the measurement. Use `muted` to keep only one side audible, as on the camera track above.
+- Chains resolve in dependency order (A may sync to B while B syncs to C). Unknown keys, cycles, and combining `syncTo` with `startTime` are mount errors; nothing is inserted.
+
+## Execution
+
+Alignment runs at the sync stage of the [pipeline](./README.md#pipeline): after generated assets land (either side may be generated), before captions read the scene. It is local, consumes no credits, and blocks the command, so exit `0` means final placement. A correlation too weak to trust fails the command (see [errors.md](./errors.md)) while the node keeps its default placement. Offsets are **cached** by the pair of source contents, so re-mounting an unchanged project re-measures nothing.
+
+Because `syncTo` is part of the shared property table, [`dapi node patch`](../node/patch.md) accepts it too: patching `syncTo` onto an existing node re-aligns it against the document node carrying that key.
diff --git a/apps/cli/reference/jsx/audio.md b/apps/cli/reference/jsx/audio.md
new file mode 100644
index 00000000..94c38193
--- /dev/null
+++ b/apps/cli/reference/jsx/audio.md
@@ -0,0 +1,18 @@
+# `<audio>`
+
+An audio clip: no visual output, no spatial props; carries volume. When `inPoint`/`outPoint` are omitted, the node fits its natural duration (see [timing.md](./timing.md)).
+
+```tsx
+<audio src="https://my.videoarchive.com/audio/clip.wav" inPoint={2.2} outPoint={16} volume={0.5} />
+```
+
+## Props
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). |
+| `name` | `string` | none | Human-readable node name. |
+| `inPoint`, `outPoint`, `startTime` | `Time` | see [timing.md](./timing.md) | Temporal placement. |
+| `volume` | `Animatable<number>` | `1` | `0`-`1`; `1` = unity gain. |
+| `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |
+| `syncTo` | `string` | none | Key of another element carrying audio; derives `startTime` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `startTime`. |
diff --git a/apps/cli/reference/jsx/captions.md b/apps/cli/reference/jsx/captions.md
new file mode 100644
index 00000000..80ae9df9
--- /dev/null
+++ b/apps/cli/reference/jsx/captions.md
@@ -0,0 +1,32 @@
+# Captions
+
+`<captions />` inside a scene transcribes that scene's audio into a caption node: a styled, timed transcript, produced on import. To caption an already-open scene, insert one with [`dapi node insert`](../node/insert.md).
+
+```tsx
+<captions preset="spotlight" colors={["#FF0055"]} />
+```
+
+Transcription is **asynchronous and non-blocking**: the caption node is inserted at commit and its transcript attaches once ready. Because it reads the scene's audio, it runs **after** any generated assets in the scene have landed and after [audio sync](./audio-sync.md) has resolved; captioning a generated `voice`/`audio` track transcribes the finished audio at its final placement. The scene must contain an unmuted audio or video source; otherwise the caption node is left empty.
+
+Transcripts are **cached**: every transcript asset records a fingerprint of the scene's audible mix (source content, placement, source offset, playback rate, gain). When a scene's fingerprint matches an existing transcript, that asset is reused instead of transcribing again; re-mounting a project with unchanged audio consumes no credits. Any change to the scene's audio invalidates the fingerprint.
+
+## Props
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `preset` | see below | `"classic"` | Caption style preset. |
+| `colors` | `string[]` | preset defaults | Fills the preset's color slots in order; any CSS color, alpha ignored. Ignored by presets without slots. |
+
+## Presets
+
+`preset` selects the caption style: the same presets as the editor's caption inspector. Some presets expose **color slots**, filled in order by the `colors` prop; a missing or omitted entry falls back to the slot's default.
+
+| Preset | Style | Color slots (defaults) |
+| ------ | ----- | ---------------------- |
+| `"classic"` (default) | Centered lowercase text with a soft drop shadow, a few words at a time. | none |
+| `"cascade"` | Light text in the lower left; words appear progressively as they are spoken. | none |
+| `"spotlight"` | Bold italic centered line; the spoken word lights up in the highlight color. | 1: highlight (`#24D5FF`) |
+| `"whisper"` | Small, wide, understated line shown in ~2 s phrases. | none |
+| `"paper"` | Centered two-line block; the line being spoken is emphasized with a heavier weight. | none |
+| `"guinea"` | Uppercase display text; the spoken word enlarges and cycles through the three colors. | 3: `#F55353`, `#FEB139`, `#F6F54D` |
+| `"stark"` | Heavy uppercase text blended into the footage with a difference blend. | none |
diff --git a/apps/cli/reference/jsx/elements.md b/apps/cli/reference/jsx/elements.md
new file mode 100644
index 00000000..a2f45ada
--- /dev/null
+++ b/apps/cli/reference/jsx/elements.md
@@ -0,0 +1,48 @@
+# Element reference
+
+Lowercase intrinsic elements map 1:1 onto internal node types:
+
+| Element | Internal node | Notes |
+| ------- | ------------- | ----- |
+| [`<scene>`](./scene.md) | **Geometry with Scene tag** | Clips its children to `width`×`height`. Document root only. |
+| [`<group>`](./group.md) | **Geometry with Group tag** | Container with a transform; give it `fill` to draw a rectangle. |
+| [`<rect>`](./rect.md) | **Geometry with Solid paint** | A filled rectangle; takes only paint children. |
+| [`<video>`](./video.md) | **Geometry with Video paint** | `src` resolves to a video asset. |
+| [`<image>`](./image.md) | **Geometry with Image paint** | `src` resolves to an image asset. |
+| [`<audio>`](./audio.md) | **Geometry with Audio component and a hidden Waveform paint** | No visual output; carries volume. |
+| [`<text>`](./text.md) | **Geometry with Text component** | Children become editable glyphs. |
+| [`<sequence>`](./sequences.md) | **Sequential group** | Lays children out back-to-back. |
+| [`<captions>`](./captions.md) | **Caption node** | Transcribes the enclosing scene's audio. |
+| [`<solidPaint>`](./paints.md) | **Solid paint** | Paint child. |
+| [`<linearGradientPaint>` / `<radialGradientPaint>`](./paints.md) | **Gradient paint** | Paint child; takes `<colorStop>` children. |
+| [`<colorStop>`](./paints.md) | **Gradient color stop** | Valid only inside gradient paints. |
+
+User-defined components are ordinary Solid components; they compose intrinsics and carry no runtime cost. Only intrinsic elements produce entities.
+
+## Coordinates and sizing
+
+- Coordinates are **pixels relative to the parent's box**, origin top-left. No percentages, no layout keywords; explicit numbers until the layout engine lands.
+- **Every element's box defaults to its parent's box**: `x` and `y` default to `0`, `width` and `height` default to the parent's size (the JSX analog of `position: absolute; inset: 0`). The scene's box is its required `width`×`height`.
+- How media pixels map into the box is controlled by `objectFit`, never by the box itself. A generated asset's placeholder therefore always has a definite size, even before the asset exists.
+
+## Common props
+
+All visual elements accept:
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `key` | `string` | none | Stable identity across mounts; **required** on document roots (see [roots.md](./roots.md)). |
+| `name` | `string` | none | Human-readable node name. |
+| `x`, `y` | `Animatable<number>` | `0` | Position relative to the parent, px. |
+| `width`, `height` | `Animatable<number>` | parent size | Box size, px. |
+| `rotation` | `Animatable<number>` | `0` | Rotation in degrees. |
+| `opacity` | `Animatable<number>` | `1` | `0`-`1`. |
+| `cornerRadius` | `Animatable<number>` | `0` | Uniform corner radius, px. |
+| `inPoint`, `outPoint`, `startTime` | `Time` | see [timing.md](./timing.md) | Temporal placement. |
+| `transition` | `TransitionSpec \| null` | none | Transition into the next clip; direct children of `<sequence>` only (see [transitions.md](./transitions.md)). |
+
+`Animatable` props also take a keyframe list; see [keyframes.md](./keyframes.md).
+
+## One property table
+
+Common and per-element props share a single property table, exported as `PatchProps` from `@diffusionstudio/jsx`. [`dapi node patch`](../node/patch.md) accepts exactly these keys, with the same value requirements, as patch entries on existing nodes; JSX and CLI cannot drift.
diff --git a/apps/cli/reference/jsx/errors.md b/apps/cli/reference/jsx/errors.md
new file mode 100644
index 00000000..1c1b62d7
--- /dev/null
+++ b/apps/cli/reference/jsx/errors.md
@@ -0,0 +1,12 @@
+# Errors
+
+Where each [pipeline](./README.md#pipeline) stage fails, and with what effect:
+
+| Stage | Where it surfaces | Effect |
+| ----- | ----------------- | ------ |
+| Compile (syntax/type-stripping/bundling) | CLI stderr, exit 1 | App never contacted. |
+| Evaluate / mount (thrown errors, invalid props, invalid root: e.g. nested `<scene>`, a root element without `key`, missing `src`, malformed `Time`, an unknown or cyclic `syncTo` key, `syncTo` combined with `startTime`) | CLI stderr, exit 1 | Staging root discarded; **nothing inserted**. |
+| Generation (per-model constraints: `aspectRatio`, `duration`, feature flags) | CLI stderr, exit 1, after every generation settled | No rollback; the mounted tree stays committed. The affected placeholder stops showing its generating state and is left without a paint. |
+| Sync (a side without a decodable audio track, or no reliable alignment) | CLI stderr, exit 1, after every alignment settled | No rollback; the tree stays committed and the node keeps its default placement. |
+
+Runtime errors are mapped back to the source via inline sourcemaps produced at compile time.
diff --git a/apps/cli/reference/jsx/generate.md b/apps/cli/reference/jsx/generate.md
new file mode 100644
index 00000000..320c9169
--- /dev/null
+++ b/apps/cli/reference/jsx/generate.md
@@ -0,0 +1,78 @@
+# Generated assets
+
+Assets that don't exist yet are **declared as values** with the `generate` namespace from `@diffusionstudio/jsx`. A declaration returns an **`AssetRef`** that is passed wherever a source is expected (`src`, `startFrame`, `endFrame`, `refs`). This makes generative content declarative: the project describes the asset it wants and the editor produces it on mount.
+
+```tsx
+import { generate } from "@diffusionstudio/jsx";
+
+const hero = generate.image({
+ prompt: "A neon city at night, cinematic",
+ model: "flux-2-turbo",
+ aspectRatio: "16:9",
+ seed: 42,
+});
+
+// one generated asset can feed another
+const heroMotion = generate.video({
+ prompt: "slow camera push-in",
+ model: "kling-3-pro",
+ startFrame: hero,
+ duration: 5,
+});
+
+export default function Project() {
+ return (
+ <scene key="intro" name="Intro" width={1920} height={1080}>
+ <video src={heroMotion} inPoint={0} outPoint={5} />
+ <image src={hero} x={40} y={40} width={200} height={112} />
+ </scene>
+ );
+}
+```
+
+Declarations are **pure**: calling `generate.*` registers a spec and returns a ref; no generation starts until [commit](./README.md#pipeline). A ref that is never used by a mounted element (directly or as an input to another asset) is dropped. Declarations may live at module scope or inside components.
+
+## Declaration options
+
+Run [`dapi models <type>`](../models.md) to discover valid `model` ids and per-model constraints; [`dapi voices`](../voices.md) lists voices.
+
+```ts
+type AssetInput = string | AssetRef; // path, URL, asset id, or another declaration
+
+generate.image(opts: {
+ prompt: string; // required
+ model?: string; // default: first model from `dapi models image`
+ aspectRatio?: "1:1" | "4:3" | "3:4" | "16:9" | "9:16"; // default "16:9"
+ refs?: AssetInput[]; // image references
+ seed?: number; // reproducible generation
+}): AssetRef;
+
+generate.video(opts: {
+ prompt: string; // required
+ model?: string; // default: first model from `dapi models video`
+ aspectRatio?: "1:1" | "4:3" | "3:4" | "16:9" | "9:16"; // default "16:9"
+ duration?: number; // whole seconds; default 5
+ audio?: boolean; // generate audio alongside; models with the `audio` feature only
+ startFrame?: AssetInput; // image used as the first frame
+ endFrame?: AssetInput; // image used as the last frame; `end-frame` feature only
+ seed?: number;
+}): AssetRef;
+
+generate.voice(opts: {
+ prompt: string; // required: the text to speak
+ voice?: string; // default: first voice from `dapi voices`
+}): AssetRef;
+
+generate.audio(opts: {
+ prompt: string; // required
+ model?: string; // default: first model from `dapi models audio`
+}): AssetRef;
+```
+
+## Dependency order
+
+`startFrame`, `endFrame`, and `refs` accept other `AssetRef`s. The dependency graph is built from these values and generated in topological order, so referenced assets exist before the assets that consume them. Because dependencies are **values, not string ids**, a declaration can only reference refs that already exist; reference cycles are impossible by construction. Assets referenced only as inputs generate too, but produce no node of their own.
+
+## Caching and idempotency
+
+Generation is long-running and consumes credits, so results are **cached by content**: a key derived from the fully-resolved spec (`type`, `model`, `prompt`, resolved references, `seed`, …). Within a session, re-running an unchanged project reuses cached assets instead of regenerating, and two declarations with identical specs collapse to a single asset; changing any option produces a new asset. Set `seed` to make a spec reproducible. The cache is per-session and is not persisted across app restarts.
diff --git a/apps/cli/reference/jsx/group.md b/apps/cli/reference/jsx/group.md
new file mode 100644
index 00000000..37c08738
--- /dev/null
+++ b/apps/cli/reference/jsx/group.md
@@ -0,0 +1,19 @@
+# `<group>`
+
+A container with a transform. Children are positioned relative to the group's box; give it `fill` to draw a rectangle behind them.
+
+```tsx
+<group x={100} y={100} width={800} height={600} fill="#111111">
+ {/* children */}
+</group>
+```
+
+## Props
+
+All [common props](./elements.md#common-props), plus:
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `fill` | `string` | none | Any CSS color, applied to the node's fill; alpha is ignored (use `opacity`). |
+
+Also accepts [paint children](./paints.md). When `inPoint`/`outPoint` are omitted, a group auto-fits its children (see [timing.md](./timing.md)).
diff --git a/apps/cli/reference/jsx/image.md b/apps/cli/reference/jsx/image.md
new file mode 100644
index 00000000..bd142668
--- /dev/null
+++ b/apps/cli/reference/jsx/image.md
@@ -0,0 +1,18 @@
+# `<image>`
+
+An image. `src` resolves to an image asset (see [media.md](./media.md)).
+
+```tsx
+<image src="/photo.jpg" x={40} y={40} width={200} height={112} />
+```
+
+## Props
+
+All [common props](./elements.md#common-props), plus:
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). |
+| `objectFit` | `"cover" \| "contain" \| "fill"` | `"contain"` | How the source maps into the box. |
+
+A paint child draws over the media paint created by `src` (see [paints.md](./paints.md)).
diff --git a/apps/cli/reference/jsx/keyframes.md b/apps/cli/reference/jsx/keyframes.md
new file mode 100644
index 00000000..f8080eee
--- /dev/null
+++ b/apps/cli/reference/jsx/keyframes.md
@@ -0,0 +1,42 @@
+# Keyframes
+
+Animatable props accept a keyframe list in place of a static value:
+
+```tsx
+<image
+ src="/photo.jpg"
+ inPoint={0} outPoint={5}
+ x={[
+ { time: 0, value: -400 },
+ { time: 1, value: 200, easing: "easeOut" },
+ ]}
+ opacity={[{ time: 0, value: 0 }, { time: "15f", value: 1 }]}
+/>
+```
+
+```ts
+type Keyframe<T> = { time: Time; value: T; easing?: Easing };
+type Animatable<T> = T | Keyframe<T>[];
+```
+
+Animatable props: `x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`. As part of the shared property table this applies to [`dapi node patch`](../node/patch.md) identically, and to [paints and color stops](./paints.md) (`color`, `opacity`, `offset` animate gradients).
+
+## Semantics
+
+- `time` is **node-local**: `0` is the node's in point, in any [time format](./timing.md#time-formats). Timing props are composition-relative; keyframe times are not, so animation moves with the clip.
+- Outside the keyframed range the value holds at the first/last keyframe.
+- `easing` shapes the segment from its keyframe to the next; the last keyframe's easing is ignored. Default `"linear"`.
+- A **static value replaces any existing keyframes** on that property; mount and `dapi node patch` own what they set. Keyframes land as regular editor keyframes, editable in the timeline and inspector, and props the render doesn't set keep their hand-made tracks across re-mounts.
+
+## Easing
+
+| Easing | Use for |
+| ------ | ------- |
+| `"linear"` (default) | Constant-rate change. |
+| `"easeIn"`, `"easeOut"`, `"easeInOut"` | Standard acceleration curves (CSS equivalents). |
+| `"gentle"`, `"snappy"`, `"bouncy"`, `"strong"` | Spring presets, from soft settle to hard overshoot. |
+| `"cubicBezier(x1,y1,x2,y2)"` | Custom curve, CSS control points. |
+| `"spring(bounce,duration)"` | Custom spring: bounce `0`-`1`, duration in ms. |
+| `"steps(n)"` | Discrete hold: n equal steps, no interpolation. |
+
+Named presets expand to the same descriptors the editor's interpolation inspector writes, so they round-trip cleanly.
diff --git a/apps/cli/reference/jsx/lifecycle.md b/apps/cli/reference/jsx/lifecycle.md
new file mode 100644
index 00000000..83f50f15
--- /dev/null
+++ b/apps/cli/reference/jsx/lifecycle.md
@@ -0,0 +1,9 @@
+# Lifecycle
+
+Mounting is a **one-shot render**: the reactive graph exists to *compose* the document (loops, conditionals, derived values, component props), not to drive it afterward.
+
+1. The component tree renders synchronously into the staging root; `onMount` callbacks flush once.
+2. The subtree commits and the reactive root is **disposed**. Signal changes after commit do not affect the document.
+3. Ownership transfers to the document: every materialized node is a fully editable composition node. Asset generation is owned by the engine, not the reactive graph, so it proceeds normally after disposal.
+
+The update path is **re-running the project**, which rebuilds the mount root in place, like refreshing a webpage; unchanged asset specs hit the generation cache. A future *live mode* may keep the reactive root mounted so signals animate the document; the one-shot contract above is deliberately forward-compatible with it.
diff --git a/apps/cli/reference/jsx/media.md b/apps/cli/reference/jsx/media.md
new file mode 100644
index 00000000..fd6cb2a8
--- /dev/null
+++ b/apps/cli/reference/jsx/media.md
@@ -0,0 +1,10 @@
+# Media source resolution
+
+`src` (on [`<video>`](./video.md), [`<image>`](./image.md), [`<audio>`](./audio.md)) accepts:
+
+- **Global path**: e.g. `"/Movies/video.mp4"`, resolved against the user's OS.
+- **Remote URL**: e.g. `"https://my.videoarchive.com/audio/clip.wav"`, registered as a remote asset.
+- **Asset id**: e.g. `"gbHJ"`, an imported asset (discover ids with [`dapi asset ls`](../asset/ls.md) or [`dapi asset tree`](../asset/tree.md)).
+- **`AssetRef`**: the value returned by a `generate.*` declaration (see [generate.md](./generate.md)). The node is inserted immediately as a placeholder and its paint is attached once the asset has generated.
+
+In [`dapi node patch`](../node/patch.md), `src` takes a path, URL, or asset id; `generate.*` declarations are JSX-only.
diff --git a/apps/cli/reference/jsx/module.md b/apps/cli/reference/jsx/module.md
new file mode 100644
index 00000000..3ce26288
--- /dev/null
+++ b/apps/cli/reference/jsx/module.md
@@ -0,0 +1,37 @@
+# Project module
+
+The entry file is a standard Solid component module:
+
+```tsx
+export default function Project() {
+ return (
+ <scene key="intro" name="Intro" fill="black" width={1920} height={1080}>
+ {/* ... */}
+ </scene>
+ );
+}
+```
+
+The component receives no props; which document node each rendered root maps onto is declared in the JSX itself via `key` (see [roots.md](./roots.md)).
+
+## Module environment
+
+- **Provided by the host** (marked external at compile time, resolved in-app so the project shares the editor's reactive runtime): `solid-js`, `solid-js/store`, `@diffusionstudio/jsx`.
+- **Everything else is bundled** by the CLI at compile time: npm dependencies, local imports, JSON, etc. A project folder is an ordinary npm package: install any helper library (`date-fns`, `zod`, `d3-scale`, …) and import it; it is resolved from the project's `node_modules` and baked into the shipped bundle. Libraries must be browser-compatible (no Node builtins); violations surface as compile errors, before the app is contacted.
+- The module executes **inside the editor process**, unsandboxed. This is local tooling with a local trust model, the same trust as running the CLI itself. Only effects made through the JSX runtime are part of the document (and its undo history); anything else the module does is unsupported.
+- Solid's control flow (`<For>`, `<Show>`, `<Index>`, `<Switch>`) and primitives (`createSignal`, `createMemo`, …) are fully available during mount. See [lifecycle.md](./lifecycle.md) for what happens after mount.
+
+## Types and tooling
+
+`@diffusionstudio/jsx` ships the JSX namespace (intrinsic elements and props), `Time`, `AssetRef`, and the `generate` namespace. For editor IntelliSense and typechecking in a project folder:
+
+```json
+{
+ "compilerOptions": {
+ "jsx": "preserve",
+ "jsxImportSource": "@diffusionstudio/jsx"
+ }
+}
+```
+
+The CLI does not typecheck; types are stripped at compile time. Run `tsc --noEmit` in the project folder for type safety.
diff --git a/apps/cli/reference/jsx/paints.md b/apps/cli/reference/jsx/paints.md
new file mode 100644
index 00000000..00a35c19
--- /dev/null
+++ b/apps/cli/reference/jsx/paints.md
@@ -0,0 +1,25 @@
+# Paints
+
+Internally a node's fill is not a property but a **paint child**: a sub-entity appended to the geometry, exactly like the editor's fill list. The `fill` prop is shorthand for a solid paint; declaring paints as JSX children exposes the full model, including gradients:
+
+```tsx
+<rect width={640} height={360} cornerRadius={24}>
+ <linearGradientPaint rotation={90}>
+ <colorStop offset={0} color="#FF0055" />
+ <colorStop offset={1} color="#0055FF" />
+ </linearGradientPaint>
+</rect>
+```
+
+Paint elements are valid inside any visual element (`<rect>`, `<group>`, `<scene>`, `<text>`, `<video>`, `<image>`). Multiple paints stack in document order; later paints render on top, and a paint child on a `<video>`/`<image>` draws over the media paint created by `src`.
+
+| Element | Props | Meaning |
+| ------- | ----- | ------- |
+| `<solidPaint>` | `color` (**required**), `opacity` | Solid fill; equivalent to the `fill` prop. |
+| `<linearGradientPaint>` | `rotation`, `opacity` | Linear gradient across the parent's box; `rotation` in degrees, `0` = left to right. |
+| `<radialGradientPaint>` | `rotation`, `opacity` | Radial gradient centered in the parent's box. |
+| `<colorStop>` | `offset` (**required**, `0`-`1`), `color` (**required**), `opacity` | Gradient color stop. Valid only inside gradient paints, which take no other children. |
+
+Colors accept any CSS color; alpha is ignored (use `opacity`). `color`, `opacity`, and `offset` are animatable (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props and cannot be document roots.
+
+Paints are live entities like any other: patch them with [`dapi node patch`](../node/patch.md), and add a stop to an existing gradient with [`dapi node insert`](../node/insert.md) (`node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'`).
diff --git a/apps/cli/reference/jsx/rect.md b/apps/cli/reference/jsx/rect.md
new file mode 100644
index 00000000..919a4014
--- /dev/null
+++ b/apps/cli/reference/jsx/rect.md
@@ -0,0 +1,15 @@
+# `<rect>`
+
+A filled rectangle. Takes only [paint children](./paints.md); use `cornerRadius` for rounded corners.
+
+```tsx
+<rect x={40} y={40} width={640} height={360} cornerRadius={24} fill="#FF0055" />
+```
+
+## Props
+
+All [common props](./elements.md#common-props), plus:
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `fill` | `string` | light gray | Any CSS color; alpha is ignored (use `opacity`). Shorthand for a solid paint child. |
diff --git a/apps/cli/reference/jsx/roots.md b/apps/cli/reference/jsx/roots.md
new file mode 100644
index 00000000..580dd57f
--- /dev/null
+++ b/apps/cli/reference/jsx/roots.md
@@ -0,0 +1,22 @@
+# Roots
+
+A mount renders one or more root elements (a fragment of roots is allowed) and **refreshes the document**: like reloading a webpage, re-running a mount rebuilds its roots in place instead of accumulating copies; a rendered root with no existing node to replace is created. Roots are typically [`<scene>`](./scene.md) elements, but any element can be a root (e.g. a bare `<rect>`). Every top-level element must declare its identity with a `key`:
+
+| Identity | Contract |
+| -------- | -------- |
+| `<scene key="intro">` | Rebuilds the existing node carrying the same key, or creates it (storing the key) if none does. Keyed nodes in the document that the render no longer produces are **deleted**; the mount owns its keyed roots. |
+
+Keys must be unique within a render, and rebuilding keeps the node's entity id and canvas position. Nodes without a key (e.g. hand-made scratch scenes) are never touched. The **first** rendered root becomes the active scene. Assigning a `name` alongside the key (e.g. `<scene key="intro" name="Intro">`) is recommended: the key identifies the node across mounts, the name labels it in the editor.
+
+`<scene>` is valid **only** at the document root; scenes do not nest.
+
+[`dapi node insert`](../node/insert.md) skips this reconciliation entirely: its roots take no `key` and every run inserts fresh entities.
+
+## Canvas placement
+
+The canvas holds many roots, but a root's position on the canvas is an **editor concern, not part of the composition**: `<scene>` has no `x`/`y`, and a project describes content, not canvas arrangement.
+
+- **Rebuilt roots** (matched by `key`) keep their existing canvas position.
+- **New roots** are placed automatically: in the nearest empty space around the current viewport center, gapped so they never overlap existing content (the same auto-placement the editor uses when generating onto the canvas). A mount that creates multiple roots places them side by side in render order.
+
+The camera is not moved; because placement anchors to the viewport center, new roots typically land in view. Use [`dapi selection focus`](../selection/focus.md) to frame them explicitly.
diff --git a/apps/cli/reference/jsx/scene.md b/apps/cli/reference/jsx/scene.md
new file mode 100644
index 00000000..4c9bc7ba
--- /dev/null
+++ b/apps/cli/reference/jsx/scene.md
@@ -0,0 +1,20 @@
+# `<scene>`
+
+The composition root: clips its children to `width`×`height`. Valid **only** at the document top level; scenes do not nest. The first rendered root becomes the active scene (see [roots.md](./roots.md)).
+
+```tsx
+<scene key="intro" name="Intro" fill="black" width={1920} height={1080}>
+ {/* children */}
+</scene>
+```
+
+## Props
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `key` | `string` | **required** | Identity across mounts; re-mounting replaces the scene carrying the same key (see [roots.md](./roots.md)). |
+| `width`, `height` | `number` | **required** | Composition size in pixels. |
+| `name` | `string` | none | Scene name (recommended). |
+| `fill` | `string` | none | Background fill, any CSS color (alpha is ignored). |
+
+No timing or transform props. Canvas position is an editor concern; `<scene>` has no `x`/`y`.
diff --git a/apps/cli/reference/jsx/sequences.md b/apps/cli/reference/jsx/sequences.md
new file mode 100644
index 00000000..c4a0f607
--- /dev/null
+++ b/apps/cli/reference/jsx/sequences.md
@@ -0,0 +1,21 @@
+# Sequences
+
+`<sequence>` enforces **sequential, non-overlapping** placement of its children: the editor's track-like behavior. It has no spatial or temporal properties of its own; it lays its children out back-to-back in document order.
+
+```tsx
+<sequence>
+ <video src="/Movies/intro.mp4" inPoint={0} outPoint={12} />
+ <video src="/Movies/main.mp4" inPoint={12} outPoint="02:30" />
+ <video src="/Movies/outro.mp4" inPoint="02:30" outPoint="02:45" />
+</sequence>
+```
+
+## Props
+
+| Prop | Type | Meaning |
+| ---- | ---- | ------- |
+| `name` | `string` | Human-readable node name. |
+
+Purely structural; nothing else.
+
+Direct children of a sequence may declare a [`transition`](./transitions.md) into the following clip.
diff --git a/apps/cli/reference/jsx/text.md b/apps/cli/reference/jsx/text.md
new file mode 100644
index 00000000..149aeaa0
--- /dev/null
+++ b/apps/cli/reference/jsx/text.md
@@ -0,0 +1,24 @@
+# `<text>`
+
+A text node; children become editable glyphs. Because the box defaults to the parent's box, a centered full-frame title is simply `<text textAlign="center" textBaseline="middle">…</text>`.
+
+```tsx
+<text color="#FFFFFF" fontSize={128} fontWeight="bold" textAlign="center" textBaseline="middle">
+ Hello World
+</text>
+```
+
+## Props
+
+All [common props](./elements.md#common-props), plus:
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| children | `string` (or expressions resolving to strings) | **required** | The text content. |
+| `fontFamily` | `string` | editor default | A family available on the machine ([`dapi fonts`](../fonts.md)). |
+| `fontSize` | `number` | editor default | Px. |
+| `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`-`900`. |
+| `fontStyle` | `"normal" \| "italic"` | `"normal"` | |
+| `color` | `Animatable<string>` | editor default | The glyph color, any CSS color. |
+| `textAlign` | `"left" \| "center" \| "right"` | `"left"` | Horizontal alignment of glyphs within the box. |
+| `textBaseline` | `"top" \| "middle" \| "bottom"` | `"top"` | Vertical alignment within the box. |
diff --git a/apps/cli/reference/jsx/timing.md b/apps/cli/reference/jsx/timing.md
new file mode 100644
index 00000000..d15ac98b
--- /dev/null
+++ b/apps/cli/reference/jsx/timing.md
@@ -0,0 +1,34 @@
+# Timing
+
+Timing props follow Lottie-inspired semantics. All values are **composition-relative** (measured against the parent's timeline), in any supported [time format](#time-formats).
+
+| Prop | Lottie | Meaning |
+| ---- | ------ | ------- |
+| `inPoint` | `ip` | Composition time at which the node becomes visible/audible. |
+| `outPoint` | `op` | Composition time at which the node stops. |
+| `startTime` | `st` | Composition time at which the node's *source* time 0 is placed. Shifts the source content within the in/out window. Defaults to the in point. |
+
+## Semantics
+
+- `inPoint` / `outPoint` define the **visible/audible window** on the parent timeline. They are a pair; if omitted, a media node fits its natural duration and a group auto-fits its children.
+- `startTime` controls **which part of the source plays inside that window**. It is the composition time where source frame 0 sits, so it may be negative to skip into the source.
+- Instead of declaring `startTime`, a media node can derive it from another node's audio with `syncTo` (see [audio-sync.md](./audio-sync.md)).
+
+> Example: `inPoint={0} outPoint={16} startTime="-30f"` shows the clip from composition second 0 to 16, but because source-time-0 is placed 30 frames *before* the in point, the first 30 frames (1s @ 30fps) of the source are trimmed; playback begins 1s into the source.
+
+## Time formats
+
+```ts
+type Time = number | `${number}f` | `${string}:${string}`;
+```
+
+The canonical internal unit is frames at **30 fps**; all formats are converted on import. All values may be negative.
+
+| Format | Example | Meaning |
+| ------ | ------- | ------- |
+| `number` | `2.2` | Seconds (may be fractional). |
+| `"${number}f"` | `"-30f"` | Frames. |
+| `"MM:SS"` | `"02:30"` | Minutes and seconds. |
+| `"HH:MM:SS"` | `"01:02:30"` | Hours, minutes, seconds. |
+
+CLI flags documented as taking a `Time` value (e.g. `--time` on [`node screenshot`](../node/screenshot.md) and [`asset frame`](../asset/frame.md)) accept the same formats.
diff --git a/apps/cli/reference/jsx/transitions.md b/apps/cli/reference/jsx/transitions.md
new file mode 100644
index 00000000..50b36262
--- /dev/null
+++ b/apps/cli/reference/jsx/transitions.md
@@ -0,0 +1,37 @@
+# Transitions
+
+`transition` declares a transition **into the next clip**, set on the **outgoing** clip and rendered centered on the cut. It is valid only on direct children of [`<sequence>`](./sequences.md).
+
+```tsx
+<sequence>
+ <video src="/Movies/intro.mp4" inPoint={0} outPoint={12} transition={{ type: "fadeToBlack", duration: "20f" }} />
+ <video src="/Movies/main.mp4" inPoint={12} outPoint={24} transition={{}} /> {/* dissolve, 1s */}
+ <video src="/Movies/outro.mp4" inPoint={24} outPoint={30} />
+</sequence>
+```
+
+```ts
+type TransitionSpec = {
+ type?: TransitionType; // default "dissolve"
+ duration?: Time; // length, centered on the cut; default 1 second
+};
+```
+
+## Types
+
+The editor's transition inspector options:
+
+| `type` | Effect |
+| ------ | ------ |
+| `"dissolve"` (default) | Crossfade between the two clips. |
+| `"slideFromRight"` | The next clip slides in from the right. |
+| `"slideFromLeft"` | The next clip slides in from the left. |
+| `"fadeToBlack"` | Fade out to black, then in to the next clip. |
+| `"fadeToWhite"` | Fade out to white, then in to the next clip. |
+
+## Semantics
+
+- `duration` takes any [time format](./timing.md#time-formats) and is centered on the cut: half plays before it, half after.
+- A **partial value merges** into the clip's existing transition: `transition={{ duration: 2 }}` keeps the current type; `transition={{}}` applies the defaults.
+- **`null` removes** the clip's transition.
+- Part of the shared property table: [`dapi node patch`](../node/patch.md) accepts `transition` with identical semantics, e.g. `--json '[{ "id": 42, "transition": { "type": "dissolve" } }]'`.
diff --git a/apps/cli/reference/jsx/video.md b/apps/cli/reference/jsx/video.md
new file mode 100644
index 00000000..17b4ecef
--- /dev/null
+++ b/apps/cli/reference/jsx/video.md
@@ -0,0 +1,21 @@
+# `<video>`
+
+A video clip. `src` resolves to a video asset (see [media.md](./media.md)); when `inPoint`/`outPoint` are omitted, the node fits its natural duration (see [timing.md](./timing.md)).
+
+```tsx
+<video src="/Movies/main.mp4" inPoint={0} outPoint={12} startTime="-30f" volume={0.8} />
+```
+
+## Props
+
+All [common props](./elements.md#common-props), plus:
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). |
+| `objectFit` | `"cover" \| "contain" \| "fill"` | `"cover"` | How the source maps into the box. |
+| `volume` | `Animatable<number>` | `1` | `0`-`1`; `1` = unity gain. |
+| `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |
+| `syncTo` | `string` | none | Key of another element carrying audio; derives `startTime` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `startTime`. |
+
+A paint child draws over the media paint created by `src` (see [paints.md](./paints.md)).
diff --git a/apps/cli/reference/models.md b/apps/cli/reference/models.md
new file mode 100644
index 00000000..89fb6404
--- /dev/null
+++ b/apps/cli/reference/models.md
@@ -0,0 +1,24 @@
+# `dapi models [type]`
+
+Lists the generation models available for a media type, including each model's capabilities. Use it to discover valid model ids and the per-model constraints (durations, aspect ratios, features) to set on an asset declaration (see [jsx/generate.md](./jsx/generate.md)).
+
+There are no CLI commands that generate; asset generation is declared in the project module and produced on mount.
+
+## Input
+
+- `[type]` (optional): one of `image`, `video`, `audio`. Omit to list all three groups.
+
+## Output
+
+JSON Lines, one per model:
+
+```ts
+{
+ type: "image" | "video" | "audio";
+ id: string; // the model id to set on a generate.* declaration
+ name: string;
+ durations?: string[]; // video only, e.g. ["5s","10s"]
+ aspectRatios?: string[]; // video only
+ features?: Array<"start-frame" | "end-frame" | "audio">; // video only
+}
+```
diff --git a/apps/cli/reference/mount.md b/apps/cli/reference/mount.md
new file mode 100644
index 00000000..917e0ec5
--- /dev/null
+++ b/apps/cli/reference/mount.md
@@ -0,0 +1,22 @@
+# `dapi mount (<path> | --code <str>)`
+
+Compiles a Solid JSX project module and executes it in the app, mounting the rendered roots into the document. Like reloading a webpage, re-mounting rebuilds the roots in place instead of adding copies: every top-level element declares its identity in the JSX with a `key`, and `<scene key="intro">` replaces the node carrying that key (or creates it).
+
+The full JSX code syntax lives in [jsx/](./jsx/README.md); start with the [pipeline](./jsx/README.md#pipeline) and [roots](./jsx/roots.md).
+
+## Input
+
+Exactly one of:
+
+- `<path>`: path to a `.tsx` / `.jsx` / `.ts` / `.js` entry module.
+- `--code <str>`: inline module source, compiled identically. The `export default () =>` wrapper is optional; a bare JSX expression (no `export default` in the source) is wrapped into a component module automatically.
+
+## Output
+
+None. The command exits `0` once the tree is committed and every declared asset has generated; inspect the result with [`dapi context`](./context.md), [`dapi node ls`](./node/ls.md), or [`dapi node tree`](./node/tree.md).
+
+## Notes
+
+- A newly added top-level scene becomes the active scene.
+- The command is long-running when assets are declared: it blocks until generation finishes (see [jsx/generate.md](./jsx/generate.md)).
+- Compile errors fail before the app is contacted; mount errors insert nothing (see [jsx/errors.md](./jsx/errors.md)).
diff --git a/apps/cli/reference/node/cp.md b/apps/cli/reference/node/cp.md
new file mode 100644
index 00000000..d7c888eb
--- /dev/null
+++ b/apps/cli/reference/node/cp.md
@@ -0,0 +1,16 @@
+# `dapi node cp <ids...>`
+
+Deep-clones one or more nodes, including all descendants. Alias: `duplicate`.
+
+## Input
+
+- `<ids...>`: one or more node ids (required)
+
+## Output
+
+JSON Lines, one per input id:
+
+```ts
+| { status: "fulfilled"; sourceId: number; newId: number }
+| { status: "rejected"; sourceId: number; error: string }
+```
diff --git a/apps/cli/reference/node/grep.md b/apps/cli/reference/node/grep.md
new file mode 100644
index 00000000..f7ca9f5d
--- /dev/null
+++ b/apps/cli/reference/node/grep.md
@@ -0,0 +1,32 @@
+# `dapi node grep <pattern> [id]`
+
+Searches entity records for a pattern and prints the matching entities, with the components that matched. The search corpus is the raw records [`node ls`](./ls.md) would emit (component values stringified), so anything `ls` can show, `grep` can find; the caveat carries over too: values are raw engine units (frames at 30 fps, packed colors, dB). `[id]` scopes the search to a subtree, like giving `grep -r` a path.
+
+The structural counterpart of [`tree`](./tree.md) (find entities by content rather than by position) and the discovery front-end to `ls`, [`selection set`](../selection/set.md), and [`patch`](./patch.md): `grep` to find ids, then read, select, or edit them.
+
+The common case (find nodes by name) is `dapi node grep -k Name Title`. Presence queries work with a match-anything pattern: `dapi node grep -k Trim .` lists every entity carrying a `Trim` component.
+
+## Input
+
+- `<pattern>`: JavaScript regex, unanchored (required). Case-sensitive unless `-i` is given.
+- `[id]`: root entity id (optional; omitted = every top-level node's subtree)
+- `-i, --ignore-case`: case-insensitive matching
+- `-t, --type <types...>`: only match entities of these node types (e.g. `-t text image`; the `type` values of `node tree`)
+- `-k, --component <names...>`: restrict matching to these components (e.g. `-k Name Chars`; the component keys of `node ls`)
+- `-l, --refs-only`: output only the matching entity refs, no match detail
+- `-c, --count`: output only the number of matching entities
+
+## Output
+
+JSON Lines, one per matching entity (no output if nothing matches; this is a successful run, exit `0`); the structured analog of grep's `file:line:content`:
+
+```ts
+NodeRef & { matches: Array<{ component: string; value: string }> }
+// value is the stringified component value the pattern matched
+```
+
+With `--refs-only`, plain `NodeRef` lines; with `--count`, a single number.
+
+## Errors
+
+Exits non-zero if the pattern is not a valid regex, or if `[id]` doesn't resolve to a live entity.
diff --git a/apps/cli/reference/node/insert.md b/apps/cli/reference/node/insert.md
new file mode 100644
index 00000000..419759a0
--- /dev/null
+++ b/apps/cli/reference/node/insert.md
@@ -0,0 +1,23 @@
+# `dapi node insert <parentId> (<path> | --code <str>) [--index <N>]`
+
+Compiles a Solid JSX project module and executes it in the app; the same pipeline as [`mount`](../mount.md), including declared asset generation, but instead of mounting the rendered roots into the document, inserts them as children of an existing entity. Because the result is inserted rather than reconciled, root elements take no `key`: every run inserts fresh entities; there is no replace-or-create matching and nothing is deleted.
+
+The full JSX code syntax lives in [jsx/](../jsx/README.md).
+
+The rendered roots must be valid as children of the target parent, following the JSX containment rules: a node parent takes any element or paint root except `<scene>` (scenes only exist at the document top level) and `<colorStop>`; a gradient paint parent takes only `<colorStop>` roots. That is how a stop is added to an existing gradient (`node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'`); other sub-entities take no children.
+
+## Input
+
+- `<parentId>`: entity id of the parent to insert into (required)
+- Project module, exactly one of:
+ - `<path>`: path to the module file
+ - `--code <str>`: inline module source; the `export default () =>` wrapper is optional, a bare JSX expression is wrapped automatically (e.g. `--code '<rect width={100} height={100} />'`)
+- `-i, --index <N>`: the inserted node's 0-based position among the parent's children, a non-negative integer (optional; default = append after the last child; values past the end are clamped). Node roots only: paints stack in insertion order and color stops render sorted by `offset`, so `--index` is rejected for them.
+
+## Output
+
+None.
+
+## Errors
+
+Exits non-zero if `<parentId>` doesn't resolve to a live entity, if compilation or evaluation fails, if a rendered root is invalid as a child of the parent (e.g. a `<scene>`, or a non-`<colorStop>` in a gradient paint), or if `--index` is given for a paint or color stop root. On any of these, **nothing is inserted**.
diff --git a/apps/cli/reference/node/ls.md b/apps/cli/reference/node/ls.md
new file mode 100644
index 00000000..c0ea9dcd
--- /dev/null
+++ b/apps/cli/reference/node/ls.md
@@ -0,0 +1,22 @@
+# `dapi node ls [ids...]`
+
+The raw entity records, exactly as persisted: every component the entity carries, keyed by component name. The property-level counterpart to [`node tree`](./tree.md)'s structure. With no ids, returns the root (top-level nodes). Alias: `get`.
+
+## Input
+
+- `[ids...]`: zero or more entity ids (optional)
+
+## Output
+
+JSON Lines, one per entity:
+
+```ts
+EntityRecord = { id: string; eid: number } & { [component: string]: unknown }
+// e.g. Name, Size, Position, Rotation, Paint, Color, Trim, ChildOf (parent eid), …
+```
+
+Records are raw engine data: times are frames at 30 fps, colors are packed `0xRRGGBB` integers, volume is dB.
+
+## Errors
+
+If any input id fails to resolve, writes a per-id message to stderr and exits non-zero after emitting all successful records to stdout.
diff --git a/apps/cli/reference/node/patch.md b/apps/cli/reference/node/patch.md
new file mode 100644
index 00000000..1c2494c4
--- /dev/null
+++ b/apps/cli/reference/node/patch.md
@@ -0,0 +1,36 @@
+# `dapi node patch ([path] | --json <str>)`
+
+Assigns JSX props on one or more existing entities in a single call. Every patch entry takes the same properties, with the same value requirements, as a JSX element in [`mount`](../mount.md); the single property table lives in [jsx/elements.md](../jsx/elements.md) and is not repeated here (the payload type is `PatchProps` from `@diffusionstudio/jsx`). Patches are applied through the same setters as a render, so the two surfaces cannot diverge. Changes are tracked for undo like a UI edit.
+
+Any live entity is addressable, not just nodes: paints and color stops can be patched too (`color`, `offset`, `opacity`, gradient `rotation`). There is no separate rename command: renaming a node is patching its `name`.
+
+## Input
+
+Exactly one of:
+
+- `[path]`: path to a `.json` file containing the patch array
+- `--json <str>`: the array inline
+
+Payload shape:
+
+```ts
+Array<{ id: number } & PatchProps>
+```
+
+All props are optional; a patch may set any subset. An unsupported property or an out-of-range value rejects that entity; a rejected patch applies none of its props (no half-applied patches). Notes beyond the JSX table:
+
+- `fill` recolors the entity's existing solid fill(s), or creates one if the entity has none.
+- `src` takes a path, URL, or asset id (`generate.*` declarations are JSX-only). The source resolves asynchronously after the other props land; if resolution fails, the entity is reported rejected even though its other props were applied. Patch `src` on its own to avoid ambiguity.
+- `syncTo` re-runs audio alignment against the document node carrying the given key and writes the entity's `startTime` from the measured offset (see [jsx/audio-sync.md](../jsx/audio-sync.md)). The command blocks until alignment settles; a failed alignment rejects the entity.
+- `transition` sets, merges into, or (with `null`) removes the clip's transition into the next clip (see [jsx/transitions.md](../jsx/transitions.md)).
+- Keyframe lists are accepted wherever the property is animatable, with the same semantics as mount (see [jsx/keyframes.md](../jsx/keyframes.md)); a static value replaces any existing keyframes.
+- Element applicability is not checked: props are applied wherever `mount` would apply them (e.g. `fontSize` only makes sense on a text node).
+
+## Output
+
+JSON Lines, one per input id:
+
+```ts
+| { status: "fulfilled"; id: number }
+| { status: "rejected"; id: number; error: string }
+```
diff --git a/apps/cli/reference/node/render.md b/apps/cli/reference/node/render.md
new file mode 100644
index 00000000..a4981f4f
--- /dev/null
+++ b/apps/cli/reference/node/render.md
@@ -0,0 +1,52 @@
+# `dapi node render [id] ([config] | --json <str>)`
+
+Renders a scene to a video file. Composes the scene frame-by-frame and muxes the result, writing it to disk. Operates on one scene; scenes are nodes, so this is the node-level render. If `[id]` is omitted, renders the active scene.
+
+Encode settings are passed as a single JSON config: the same object the in-app render method takes (`EncoderConfig`), minus the runtime-only fields the CLI fills in for you (`scene`, `target`, `onProgress`). The whole config is **optional**; omit it to render with the defaults below. The encode window follows the scene's timeline workarea (its `Trim`): the render starts at the workarea start and runs to the scene's end, unless capped earlier with `trim.end`. Renders locally; **no credits** and no authenticated account required.
+
+Like the generators, this is **long-running**: the CLI blocks until the render finishes (or fails) before printing. While waiting, a progress spinner with elapsed time is shown on **stderr** (a single static line when stderr isn't a TTY), so stdout stays clean JSON for piping.
+
+## Input
+
+- `[id]`: scene node id (optional; defaults to the active scene).
+- `-o, --output <path>`: write the video here (optional; default a uuid-named file in the system temp directory). The container extension is derived from the config's `format`.
+- Encode config (optional), at most one of:
+ - `[config]`: path to a `.json` file containing the config object. Node ids are integers, so a lone non-numeric positional is read as the config path (`dapi node render encode.json` works without an id).
+ - `--json <str>`: the object inline
+
+Config shape (every field optional; all defaults shown):
+
+```ts
+{
+ format?: "mp4" | "webm" | "ogg" | "mov"; // default "mp4"; sets the output extension
+ video?: {
+ codec?: "avc" | "hevc" | "vp9" | "av1" | "vp8"; // default "avc" (H.264); valid codecs depend on format
+ enabled?: boolean; // default true
+ bitrate?: number; // bits/sec, default 10_000_000 (10 Mbps)
+ fps?: number; // default the scene's frame rate
+ resolution?: number; // target height in px (e.g. 720, 1080, 1440, 2160); default 1080. Width follows the scene's aspect ratio
+ };
+ audio?: {
+ enabled?: boolean; // default true; set false to render video only
+ codec?: "aac" | "opus"; // default "aac"; valid codecs depend on format
+ bitrate?: number; // bits/sec, default 128_000 (128 kbps)
+ sampleRate?: number; // Hz, e.g. 44100, 48000, 96000; default 48000
+ numberOfChannels?: number; // default 2
+ };
+ trim?: {
+ end?: number; // seconds; cap the encode here. Default the scene's full duration. Caps the workarea end; cannot extend past the scene
+ };
+}
+```
+
+## Output
+
+One JSON object: the absolute path to the written video file.
+
+```ts
+{ path: string } // e.g. "/tmp/3f2c1a8e-....mp4", or the --output path
+```
+
+## Errors
+
+Exits non-zero if the id is unknown or the node is not a scene (`Not a scene`), if no scene is active and `[id]` is omitted, if the config is malformed or holds a value out of range or incompatible with the chosen `format` (e.g. an unsupported codec), if `--output` can't be written, or if the render fails or is canceled.
diff --git a/apps/cli/reference/node/rm.md b/apps/cli/reference/node/rm.md
new file mode 100644
index 00000000..0eb02535
--- /dev/null
+++ b/apps/cli/reference/node/rm.md
@@ -0,0 +1,16 @@
+# `dapi node rm <ids...>`
+
+Deletes one or more entities and all their descendants. Alias: `remove`.
+
+## Input
+
+- `<ids...>`: one or more entity ids (required)
+
+## Output
+
+JSON Lines, one per input id:
+
+```ts
+| { status: "fulfilled"; id: number }
+| { status: "rejected"; id: number; error: string }
+```
diff --git a/apps/cli/reference/node/screenshot.md b/apps/cli/reference/node/screenshot.md
new file mode 100644
index 00000000..534b9677
--- /dev/null
+++ b/apps/cli/reference/node/screenshot.md
@@ -0,0 +1,16 @@
+# `dapi node screenshot [id] [-t, --time <time>]`
+
+Focuses the node on the canvas and captures a screenshot, written to a PNG file in the system temp directory. If `[id]` is omitted, captures the canvas (the active scene). To grab a video asset's own pixels at full resolution instead of the composited canvas, use [`asset frame`](../asset/frame.md).
+
+## Input
+
+- `[id]`: node id (optional; defaults to the canvas)
+- `-t, --time <time>`: timeline position at which to record the node, a `Time` value (optional; defaults to the current playhead position)
+
+## Output
+
+One JSON object: the absolute path to a freshly written PNG in the system temp directory with a uuid filename.
+
+```ts
+{ path: string } // e.g. "/tmp/3f2c1a8e-....png"
+```
diff --git a/apps/cli/reference/node/tree.md b/apps/cli/reference/node/tree.md
new file mode 100644
index 00000000..f54071d5
--- /dev/null
+++ b/apps/cli/reference/node/tree.md
@@ -0,0 +1,29 @@
+# `dapi node tree [id] [--depth N]`
+
+An entity's subtree as a nested JSON object: structure only, every entity and sub-entity included, and the way to discover their ids. Key characteristics are folded into a compact `description` built from whatever the entity carries; use [`node ls`](./ls.md) for exact property values. The root is level 0, so `--depth 1` yields the root plus its immediate children.
+
+## Input
+
+- `[id]`: root entity id (optional; omitted = one tree per top-level node, mirroring `ls`)
+- `--depth <N>`: max depth, non-negative integer (optional; default `3`, `0` = full subtree)
+
+## Output
+
+JSON Lines, one nested object per root; category arrays are omitted when empty:
+
+```ts
+NodeTree = NodeRef & {
+ description: string; // e.g. "hidden; size: 200x300; text: Hello World"
+ children?: NodeTree[]; // child nodes (masks listed separately)
+ masks?: NodeTree[];
+ paints?: NodeTree[]; // fills
+ strokes?: NodeTree[];
+ shadows?: NodeTree[];
+ effects?: NodeTree[];
+ colorStops?: NodeTree[]; // on gradient paints
+ textRanges?: NodeTree[]; // on text nodes
+ keyframeTracks?: NodeTree[]; // keyframes nest beneath their track
+ keyframes?: NodeTree[];
+ animations?: NodeTree[];
+}
+```
diff --git a/apps/cli/reference/open.md b/apps/cli/reference/open.md
new file mode 100644
index 00000000..1f7b4672
--- /dev/null
+++ b/apps/cli/reference/open.md
@@ -0,0 +1,59 @@
+# `dapi open [target]`
+
+Launches Diffusion Studio, or opens a target. Behavior depends on what `[target]` resolves to. Does not require the app to already be running.
+
+## Input
+
+- `[target]` (optional), one of:
+ - *omitted*: launches the app.
+ - **`diffusion://...` URL**: follows the deep link.
+ - **file path**: opens the file in the app.
+ - **folder path**: see [Folder open](#folder-open) below.
+
+## Options
+
+- `-b, --background`: launch with the window hidden (`show: false`), so the app runs headlessly and can be driven by other CLI commands without any visible UI.
+
+## Output
+
+- File / URL / no target: nothing.
+- Folder: one JSON object (see below).
+
+## Folder open
+
+When `[target]` is a directory, `open` either creates a project from the folder's contents or switches to a previously created one. The decision is driven by a `.dapi` marker file at the folder root.
+
+**First time** (no marker present):
+
+1. Creates a new project named after the folder.
+2. Imports every supported asset file under the folder (recursively, excluding the marker itself), mirroring the on-disk directory structure as library folders. Directories without any supported assets beneath them produce no folder.
+3. Writes the `.dapi` marker at the folder root with the new project id.
+4. Opens the project.
+
+**Subsequent times** (marker present):
+
+1. Reads the project id from the marker.
+2. Switches to that project. No re-import.
+3. If the referenced project no longer exists, the marker is treated as stale and the first-time flow runs again, overwriting the marker.
+
+**Marker file**: `.dapi` at the folder root. JSON:
+
+```ts
+{
+ version: 1;
+ projectId: string;
+ createdAt: string; // ISO 8601
+}
+```
+
+Add it to `.gitignore` to keep the project association per-clone, or commit it to share the same project across teammates.
+
+**Output:** one JSON object
+
+```ts
+{
+ project: { id: string; name: string };
+ created: boolean; // true if a new project was created this run (first-time or stale-marker)
+ imported: number; // assets imported this run; 0 on switch-only
+}
+```
diff --git a/apps/cli/reference/project/active.md b/apps/cli/reference/project/active.md
new file mode 100644
index 00000000..5156dba5
--- /dev/null
+++ b/apps/cli/reference/project/active.md
@@ -0,0 +1,15 @@
+# `dapi project active`
+
+Prints the currently active project, or `null` if none is open.
+
+## Input
+
+None.
+
+## Output
+
+One JSON value:
+
+```ts
+{ id: string; name: string } | null
+```
diff --git a/apps/cli/reference/project/create.md b/apps/cli/reference/project/create.md
new file mode 100644
index 00000000..9f8d65e5
--- /dev/null
+++ b/apps/cli/reference/project/create.md
@@ -0,0 +1,15 @@
+# `dapi project create [name]`
+
+Creates a new project and opens it.
+
+## Input
+
+- `[name]`: optional project name
+
+## Output
+
+One JSON object:
+
+```ts
+{ id: string; name: string }
+```
diff --git a/apps/cli/reference/project/ls.md b/apps/cli/reference/project/ls.md
new file mode 100644
index 00000000..d03c330c
--- /dev/null
+++ b/apps/cli/reference/project/ls.md
@@ -0,0 +1,15 @@
+# `dapi project ls`
+
+Lists all projects, most recently accessed first. Alias: `list`.
+
+## Input
+
+None.
+
+## Output
+
+JSON Lines, one per project:
+
+```ts
+{ id: string; name: string; createdAt: string; lastAccessedAt: string }
+```
diff --git a/apps/cli/reference/project/rm.md b/apps/cli/reference/project/rm.md
new file mode 100644
index 00000000..6cff8561
--- /dev/null
+++ b/apps/cli/reference/project/rm.md
@@ -0,0 +1,15 @@
+# `dapi project rm <id>`
+
+Deletes a project by id. Alias: `remove`.
+
+## Input
+
+- `<id>`: project id (required)
+
+## Output
+
+One JSON object:
+
+```ts
+{ id: string; name: string }
+```
diff --git a/apps/cli/reference/project/set.md b/apps/cli/reference/project/set.md
new file mode 100644
index 00000000..666cec4a
--- /dev/null
+++ b/apps/cli/reference/project/set.md
@@ -0,0 +1,15 @@
+# `dapi project set <id>`
+
+Sets the active project by id, opening it. Returns `null` if no project has that id.
+
+## Input
+
+- `<id>`: project id (required)
+
+## Output
+
+One JSON value:
+
+```ts
+{ id: string; name: string } | null
+```
diff --git a/apps/cli/reference/selection/focus.md b/apps/cli/reference/selection/focus.md
new file mode 100644
index 00000000..0fdbb12e
--- /dev/null
+++ b/apps/cli/reference/selection/focus.md
@@ -0,0 +1,15 @@
+# `dapi selection focus`
+
+Pans and zooms the canvas to fit the currently selected nodes in view, framing them with padding; the same focus [`node screenshot`](../node/screenshot.md) uses before it captures. No-op if nothing is selected (the canvas is left unchanged).
+
+## Input
+
+None.
+
+## Output
+
+JSON Lines, one per selected node (no output if nothing is selected):
+
+```ts
+NodeRef // { id: number; name: string; type: string }
+```
diff --git a/apps/cli/reference/selection/ls.md b/apps/cli/reference/selection/ls.md
new file mode 100644
index 00000000..57f538b1
--- /dev/null
+++ b/apps/cli/reference/selection/ls.md
@@ -0,0 +1,17 @@
+# `dapi selection ls`
+
+The currently selected nodes. Alias: `get`.
+
+Mutating selection commands ([`set`](./set.md), [`focus`](./focus.md)) return the resulting selection state in this same shape, so callers can chain or assert without a follow-up read.
+
+## Input
+
+None.
+
+## Output
+
+JSON Lines, one per selected node (no output if nothing is selected):
+
+```ts
+NodeRef // { id: number; name: string; type: string }
+```
diff --git a/apps/cli/reference/selection/set.md b/apps/cli/reference/selection/set.md
new file mode 100644
index 00000000..c28b8f77
--- /dev/null
+++ b/apps/cli/reference/selection/set.md
@@ -0,0 +1,15 @@
+# `dapi selection set [ids...]`
+
+Replaces the current selection with exactly the given node ids. No ids = clear the selection.
+
+## Input
+
+- `[ids...]`: zero or more node ids
+
+## Output
+
+JSON Lines, one per selected node (no output when clearing):
+
+```ts
+NodeRef // { id: number; name: string; type: string }
+```
diff --git a/apps/cli/reference/voices.md b/apps/cli/reference/voices.md
new file mode 100644
index 00000000..b7cf287a
--- /dev/null
+++ b/apps/cli/reference/voices.md
@@ -0,0 +1,15 @@
+# `dapi voices`
+
+Lists the speech voices available for `generate.voice` declarations (see [jsx/generate.md](./jsx/generate.md)).
+
+## Input
+
+None.
+
+## Output
+
+JSON Lines, one per voice:
+
+```ts
+{ id: string; label: string; description: string }
+```
diff --git a/apps/cli/reference/whoami.md b/apps/cli/reference/whoami.md
new file mode 100644
index 00000000..bdd303f9
--- /dev/null
+++ b/apps/cli/reference/whoami.md
@@ -0,0 +1,15 @@
+# `dapi whoami`
+
+Prints the authenticated account, or `null` if signed out.
+
+## Input
+
+None.
+
+## Output
+
+One JSON value:
+
+```ts
+{ id: string; email: string; provider: string } | null
+```
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 9c9f5ec2..90b94d46 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -955,20 +955,24 @@ function listFonts(opts: ListFontsOptions): void {
const program = new Command();
+// Appends the command's reference page to its help description.
+const DOCS_BASE = "https://github.com/diffusionstudio/editor/blob/main/apps/cli/reference";
+const docs = (page: string) => `\nReference: ${DOCS_BASE}/${page}.md`;
+
program
.name("dapi")
- .description("CLI for Diffusion Studio")
+ .description(`CLI for Diffusion Studio${docs("README")}`)
.version(version);
program
.command("context")
.alias("ctx")
- .description("Print essential context about the open project")
+ .description(`Print essential context about the open project${docs("context")}`)
.action(() => context());
program
.command("open")
- .description("Open Diffusion Studio")
+ .description(`Open Diffusion Studio${docs("open")}`)
.argument("[target]", `file path, folder path, or "${PROTOCOL}://" URL to open`)
.option("-b, --background", "launch with the window hidden (headless)")
.action((target: string | undefined, opts: { background?: boolean }) =>
@@ -976,7 +980,7 @@ program
program
.command("mount")
- .description("Compile a Solid JSX project module and mount it into the canvas")
+ .description(`Compile a Solid JSX project module and mount it into the canvas${docs("mount")}`)
.argument("[path]", "path to a .tsx / .jsx / .ts / .js entry module")
.option("--code <str>", "inline module source; export default wrapper optional for bare JSX")
.action((path: string | undefined, opts: MountOptions) => mountProject(path, opts));
@@ -988,7 +992,7 @@ const asset = program
asset
.command("add")
- .description("Add one or more local files as assets in the open project")
+ .description(`Add one or more local files as assets in the open project${docs("asset/add")}`)
.argument("<paths...>", "absolute or relative file paths to add")
.option("--folder <id>", "folder to place the new assets in (default: the library root)")
.action((paths: string[], opts: AssetAddOptions) => addAssets(paths, opts));
@@ -996,13 +1000,13 @@ asset
asset
.command("ls")
.alias("get")
- .description("Print raw asset records — every persisted property except the file handles; with no ids, lists every asset")
+ .description(`Print raw asset records — every persisted property except the file handles; with no ids, lists every asset${docs("asset/ls")}`)
.argument("[ids...]", "asset ids to list (optional)")
.action((ids: string[]) => listAssets(ids));
asset
.command("tree")
- .description("Print the asset library of the open project as its folder tree")
+ .description(`Print the asset library of the open project as its folder tree${docs("asset/tree")}`)
.option("--folder <id>", "folder whose contents to list (default: the library root)")
.option("--depth <n>", "max depth to descend (positive integer; default = full tree)")
.action((opts: AssetTreeOptions) => assetTree(opts));
@@ -1010,40 +1014,40 @@ asset
asset
.command("rm")
.alias("remove")
- .description("Delete one or more assets from the open project by id")
+ .description(`Delete one or more assets from the open project by id${docs("asset/rm")}`)
.argument("<ids...>", "asset ids to delete")
.action((ids: string[]) => deleteAssets(ids));
asset
.command("mv")
.alias("move")
- .description("Move one or more assets into a folder")
+ .description(`Move one or more assets into a folder${docs("asset/mv")}`)
.argument("<ids...>", "asset ids to move")
.option("--to <folderId>", "destination folder (default: the library root)")
.action((ids: string[], opts: MoveOptions) => moveAssets(ids, opts));
asset
.command("export")
- .description("Write one or more assets' original file bytes to disk (no re-encode)")
+ .description(`Write one or more assets' original file bytes to disk (no re-encode)${docs("asset/export")}`)
.argument("<ids...>", "asset ids to export")
.option("-o, --output <path>", "directory to write into, or an exact file path for a single id (default: system temp dir)")
.action((ids: string[], opts: AssetExportOptions) => exportAssets(ids, opts));
asset
.command("probe")
- .description("Read the container and per-track technical metadata of an asset")
+ .description(`Read the container and per-track technical metadata of an asset${docs("asset/probe")}`)
.argument("<id|path>", "asset id, or a local file to add and probe")
.action((ref: string) => assetProbe(ref));
asset
.command("transcribe")
- .description("Transcribe the speech in a video or audio asset and print the timed transcript")
+ .description(`Transcribe the speech in a video or audio asset and print the timed transcript${docs("asset/transcribe")}`)
.argument("<id|path>", "video or audio asset id, or a local file to add and transcribe")
.action((ref: string) => assetTranscribe(ref));
asset
.command("frame")
- .description("Decode one or more frames of a video asset and write them as PNGs")
+ .description(`Decode one or more frames of a video asset and write them as PNGs${docs("asset/frame")}`)
.argument("<id|path>", "video asset id, or a local file to add and grab frames from")
.option("-t, --time <time...>", `one or more timestamps to grab — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0)`)
.option("-o, --output <dir>", "directory to write the PNGs into (default: system temp dir)")
@@ -1052,7 +1056,7 @@ asset
asset
.command("visualize")
.alias("viz")
- .description("Render a visual preview of an asset (waveform, filmstrip, or thumbnail) to a PNG")
+ .description(`Render a visual preview of an asset (waveform, filmstrip, or thumbnail) to a PNG${docs("asset/visualize")}`)
.argument("<id|path>", "image, audio, or video asset id, or a local file to add and visualize")
.option("-s, --start <time>", `start of the window to visualize — seconds, "45f" frames, or "MM:SS" (default: 0)`)
.option("-e, --end <time>", `end of the window to visualize — seconds, "45f" frames, or "MM:SS" (default: asset duration)`)
@@ -1062,7 +1066,7 @@ asset
asset
.command("analyze")
- .description("Analyze an image, audio, or video asset with AI and print a description of its contents")
+ .description(`Analyze an image, audio, or video asset with AI and print a description of its contents${docs("asset/analyze")}`)
.argument("<id|path>", "image, audio, or video asset id, or a local file to add and analyze")
.option("-p, --prompt <str>", "question or instruction to guide the analysis")
.option("-s, --start <time>", `start of the segment to analyze — seconds, "45f" frames, or "MM:SS" (default: 0); timestamps in the analysis are relative to this point`)
@@ -1077,20 +1081,20 @@ const folder = program
folder
.command("ls")
.aliases(["list", "get"])
- .description("List the direct child folders of a parent folder; with no id, the root-level folders")
+ .description(`List the direct child folders of a parent folder; with no id, the root-level folders${docs("folder/ls")}`)
.argument("[parentId]", "parent folder id (optional; omitted = the library root)")
.action((parentId: string | undefined) => listFolders(parentId));
folder
.command("create")
- .description("Create a folder")
+ .description(`Create a folder${docs("folder/create")}`)
.argument("<name>", "folder name")
.option("-p, --parent <id>", "parent folder (default: the library root)")
.action((name: string, opts: FolderCreateOptions) => createFolder(name, opts));
folder
.command("rename")
- .description("Rename a folder")
+ .description(`Rename a folder${docs("folder/rename")}`)
.argument("<id>", "folder id")
.argument("<name>", "new name")
.action((id: string, name: string) => renameFolder(id, name));
@@ -1098,7 +1102,7 @@ folder
folder
.command("mv")
.alias("move")
- .description("Move one or more folders under a new parent")
+ .description(`Move one or more folders under a new parent${docs("folder/mv")}`)
.argument("<ids...>", "folder ids to move")
.option("--to <folderId>", "destination parent folder (default: the library root)")
.action((ids: string[], opts: MoveOptions) => moveFolders(ids, opts));
@@ -1106,7 +1110,7 @@ folder
folder
.command("rm")
.alias("remove")
- .description("Delete one or more folders, including all nested folders and the assets inside")
+ .description(`Delete one or more folders, including all nested folders and the assets inside${docs("folder/rm")}`)
.argument("<ids...>", "folder ids to delete")
.action((ids: string[]) => deleteFolders(ids));
@@ -1118,18 +1122,18 @@ const selection = program
selection
.command("ls")
.alias("get")
- .description("List the currently selected nodes")
+ .description(`List the currently selected nodes${docs("selection/ls")}`)
.action(() => listSelection());
selection
.command("set")
- .description("Replace the current selection with exactly the given node ids; none = clear")
+ .description(`Replace the current selection with exactly the given node ids; none = clear${docs("selection/set")}`)
.argument("[ids...]", "node ids to select")
.action((ids: string[]) => setSelection(ids));
selection
.command("focus")
- .description("Pan and zoom the canvas to fit the current selection in view")
+ .description(`Pan and zoom the canvas to fit the current selection in view${docs("selection/focus")}`)
.action(() => focusSelection());
const node = program
@@ -1140,20 +1144,20 @@ const node = program
node
.command("ls")
.alias("get")
- .description("Print raw entity records — every component, as persisted; with no ids, lists the root scenes")
+ .description(`Print raw entity records — every component, as persisted; with no ids, lists the root scenes${docs("node/ls")}`)
.argument("[ids...]", "entity ids to list (optional)")
.action((ids: string[]) => listNodes(ids));
node
.command("tree")
- .description("Print an entity's subtree as a nested JSON object, sub-entities included; with no id, prints every top-level node's tree")
+ .description(`Print an entity's subtree as a nested JSON object, sub-entities included; with no id, prints every top-level node's tree${docs("node/tree")}`)
.argument("[id]", "root entity id (optional; omitted = every top-level node)")
.option("--depth <n>", "max depth to descend (default: 3; 0 = full subtree)")
.action((id: string | undefined, opts: TreeOptions) => nodeTree(id, opts));
node
.command("grep")
- .description("Search entity records for a regex and print the matching entities with the components that matched — the search corpus is the raw records node ls emits")
+ .description(`Search entity records for a regex and print the matching entities with the components that matched — the search corpus is the raw records node ls emits${docs("node/grep")}`)
.argument("<pattern>", "regex to match against stringified component values")
.argument("[id]", "root entity id to scope the search to a subtree (optional; omitted = the whole document)")
.option("-i, --ignore-case", "case-insensitive matching")
@@ -1165,14 +1169,14 @@ node
node
.command("screenshot")
- .description("Focus a node on the canvas and capture a screenshot as a PNG")
+ .description(`Focus a node on the canvas and capture a screenshot as a PNG${docs("node/screenshot")}`)
.argument("[id]", "node id to capture (optional; defaults to the canvas)")
.option("-t, --time <time>", `timeline position to record at — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: the current playhead)`)
.action((id: string | undefined, opts: ScreenshotOptions) => nodeScreenshot(id, opts));
node
.command("insert")
- .description("Compile a Solid JSX project module and insert the rendered entities into a parent entity")
+ .description(`Compile a Solid JSX project module and insert the rendered entities into a parent entity${docs("node/insert")}`)
.argument("<parentId>", "entity id of the parent to insert into — a node, or a gradient paint for <colorStop> roots")
.argument("[path]", "path to a .tsx / .jsx / .ts / .js entry module")
.option("--code <str>", "inline module source; export default wrapper optional for bare JSX")
@@ -1182,27 +1186,27 @@ node
node
.command("rm")
.alias("remove")
- .description("Delete one or more entities and all their descendants")
+ .description(`Delete one or more entities and all their descendants${docs("node/rm")}`)
.argument("<ids...>", "entity ids to delete")
.action((ids: string[]) => deleteNodes(ids));
node
.command("cp")
.alias("duplicate")
- .description("Deep-clone one or more nodes, including all descendants")
+ .description(`Deep-clone one or more nodes, including all descendants${docs("node/cp")}`)
.argument("<ids...>", "node ids to duplicate")
.action((ids: string[]) => duplicateNodes(ids));
node
.command("patch")
- .description("Assign JSX props on one or more existing entities in a single call — the same properties, with the same value requirements, as mount. Renaming a node is patching its name")
+ .description(`Assign JSX props on one or more existing entities in a single call — the same properties, with the same value requirements, as mount. Renaming a node is patching its name${docs("node/patch")}`)
.argument("[path]", "path to a .json file containing the patch array")
.option("--json <str>", "inline JSON array of { id, ...jsx props }")
.action((path: string | undefined, opts: JsonPayloadOptions) => patchNodes(path, opts));
node
.command("render")
- .description("Render a scene to a video file")
+ .description(`Render a scene to a video file${docs("node/render")}`)
.argument("[id]", "scene node id (optional; defaults to the active scene)")
.argument("[config]", "path to a .json encode config (EncoderConfig)")
.option("-o, --output <path>", "write the video here (default: a temp file)")
@@ -1217,53 +1221,53 @@ const project = program
project
.command("active")
- .description("Print the currently active project, or null if none is open")
+ .description(`Print the currently active project, or null if none is open${docs("project/active")}`)
.action(() => activeProject());
project
.command("ls")
.alias("list")
- .description("List all projects, most recently accessed first")
+ .description(`List all projects, most recently accessed first${docs("project/ls")}`)
.action(() => listProjects());
project
.command("create")
- .description("Create a new project and open it")
+ .description(`Create a new project and open it${docs("project/create")}`)
.argument("[name]", "optional project name")
.action((name?: string) => createProject(name));
project
.command("set")
- .description("Set the active project by id, or null if no project has that id")
+ .description(`Set the active project by id, or null if no project has that id${docs("project/set")}`)
.argument("<id>", "project id to set active")
.action((id: string) => openProject(id));
project
.command("rm")
.alias("remove")
- .description("Delete a project by id")
+ .description(`Delete a project by id${docs("project/rm")}`)
.argument("<id>", "project id to delete")
.action((id: string) => deleteProject(id));
program
.command("models")
- .description("List available AI generation models and their constraints (for generate.* declarations — see the JSX API)")
+ .description(`List available AI generation models and their constraints (for generate.* declarations — see the JSX API)${docs("models")}`)
.argument("[type]", `filter to one of "image", "video", "audio"`)
.action((type: string | undefined) => listModels(type));
program
.command("voices")
- .description("List the speech voices available for generate.voice declarations (see the JSX API)")
+ .description(`List the speech voices available for generate.voice declarations (see the JSX API)${docs("voices")}`)
.action(() => listVoices());
program
.command("whoami")
- .description("Print the authenticated account, or null if signed out")
+ .description(`Print the authenticated account, or null if signed out${docs("whoami")}`)
.action(() => whoami());
program
.command("fonts")
- .description("List the local fonts available on this machine")
+ .description(`List the local fonts available on this machine${docs("fonts")}`)
.option("-f, --family <pattern>", "filter to families whose name contains <pattern> (case-insensitive)")
.option("-w, --weight <weights...>", "filter to variants with the given CSS weight(s), e.g. -w 400 700")
.option("-s, --style <style>", `filter to variants with the given style: "normal" or "italic"`)
diff --git a/docs/README.md b/docs/README.md
index 587d8a7a..296118a1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,4 +7,4 @@ Diffusion Studio is driven through `dapi`, its CLI. Start here:
- [Writing compositions](composition.md): the JSX API with elements, timing, paints, generative assets, and captions
- [Working with media](assets.md): the asset library and the vision/audio toolchain
-The exhaustive specifications these docs are distilled from live with the CLI source: [api-spec.md](../apps/cli/api-spec.md) and [jsx-spec.md](../apps/cli/jsx-spec.md).
+The exhaustive specification these docs are distilled from lives with the CLI source: [apps/cli/reference](../apps/cli/reference/README.md), one file per command, with the JSX code syntax in [apps/cli/reference/jsx](../apps/cli/reference/jsx/README.md).