Skip to content

The VS Code of video editing, built for agents.

TypeScript

Add initial documentation for Diffusion Studio, including README, CLI reference, asset management, and composition guidelines.

konstantin-paulus707c08190f6a
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..0099a05f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,130 @@
+# Diffusion Studio
+
+**FFmpeg for agents:** a video editor you drive from the command line, with a generative-AI and vision toolchain built in.
+
+Diffusion Studio is a canvas-based video editor. What makes it different is `dapi`, its CLI: every part of the editor (projects, the scene graph, the asset library, AI generation, rendering) is scriptable over a local socket, with JSON on stdout and deterministic exit codes. A human uses the canvas; an agent uses `dapi`. Both edit the same document.
+
+```sh
+dapi open # use -b to run the editor headless
+dapi mount hero.tsx # render a composition into it
+dapi node export -o hero.mp4 # encode the scene to disk
+```
+
+## Compositions as code
+
+Compositions are [SolidJS](https://www.solidjs.com) modules. `dapi mount` compiles them and renders each element into an editable node in the document; re-mounting rebuilds in place, like reloading a webpage. Solid's control flow (`<For>`, `<Show>`, …) and any npm package are available to compose the tree, and generative assets are declared as values and produced on mount:
+
+```tsx
+import { For } from "solid-js";
+import { generate } from "@diffusionstudio/jsx";
+
+const hero = generate.image({ prompt: "A neon city at night, cinematic" });
+const motion = generate.video({ prompt: "slow camera push-in", startFrame: hero });
+
+const TITLES = [
+ { text: "The Grid", inPoint: 0, outPoint: 2.5 },
+ { text: "Neon Nights", inPoint: 2.5, outPoint: 5 },
+];
+
+export default function Project() {
+ return (
+ <scene key="intro" name="Intro" width={1920} height={1080} fill="black">
+ <video src={motion} width={1920} height={1080} />
+ <sequence>
+ <For each={TITLES}>
+ {(t) => (
+ <text
+ textAlign="center"
+ textBaseline="middle"
+ fontSize={128}
+ width={1920}
+ height={1080}
+ fill="white"
+ inPoint={t.inPoint}
+ outPoint={t.outPoint}
+ >
+ {t.text}
+ </text>
+ )}
+ </For>
+ </sequence>
+ </scene>
+ );
+}
+```
+
+Everything a mount produces stays a first-class editor node, so a person can pick up in the UI exactly where the script left off.
+
+## Seeing and hearing the media
+
+Cutting footage requires looking at it. The CLI ships the inspection tools an agent needs to work with media it cannot watch:
+
+```sh
+dapi asset probe clip.mp4 # container + codec metadata, like ffprobe
+dapi asset frame clip.mp4 -t 0 12 45 # decode frames to PNGs
+dapi asset visualize track.mp3 # waveform / filmstrip previews
+dapi asset transcript interview.wav # timed, word-level transcript
+dapi asset analyze b-roll.mp4 -p "when is the product shown?" # ask a vision model
+dapi asset sync lav.wav -v camera.mp4 # align external audio to camera audio
+dapi node screenshot # see the canvas itself
+```
+
+## CLI at a glance
+
+| Command | Purpose |
+| --- | --- |
+| `dapi open` | Launch the app, open a file, or turn a folder of footage into a project |
+| `dapi context` | Summary of the open project: scenes, playhead, fonts |
+| `dapi mount` | Compile and mount a JSX composition |
+| `dapi node …` | The scene graph: `ls`, `tree`, `grep`, `patch`, `insert`, `cp`, `rm`, `screenshot`, `export` |
+| `dapi asset …` | The media library: `add`, `ls`, `probe`, `frame`, `visualize`, `analyze`, `transcript`, `sync`, `export` |
+| `dapi project …` / `dapi folder …` / `dapi selection …` | Projects, library folders, canvas selection |
+| `dapi models` / `dapi voices` / `dapi fonts` | Discover generation models, speech voices, local fonts |
+
+Conventions throughout: single results are one JSON value, collections are JSON Lines, errors go to stderr with exit code `1`. Everything is built to be piped, grepped, and driven by a program.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md): install the CLI, open a project, first mount, first export
+- [CLI reference](docs/cli.md): every command, its options, and its output
+- [Writing compositions](docs/composition.md): the JSX API with elements, timing, paints, generative assets, and captions
+- [Working with media](docs/assets.md): the asset library and the vision/audio toolchain
+
+## Repository layout
+
+| Path | Package | What it is |
+| --- | --- | --- |
+| `apps/web` | `@diffusionstudio/web` | The editor UI (Solid + Vite) |
+| `apps/desktop` | `@diffusionstudio/desktop` | Electron shell hosting the editor |
+| `apps/cli` | `@diffusionstudio/cli` | The `dapi` CLI |
+| `packages/jsx` | `@diffusionstudio/jsx` | Solid JSX runtime and types for compositions |
+
+## Contributing / local setup
+
+Requirements: Node 20+ and npm.
+
+```sh
+git clone https://github.com/diffusionstudio/editor.git
+cd editor
+npm install
+
+npm run dev # editor in the browser (Vite dev server)
+npm run dev:desktop # editor as a desktop app (Electron)
+```
+
+To build the CLI and put `dapi` on your PATH (macOS/Homebrew layout; adjust the link target for other setups):
+
+```sh
+npm run symlink:create --workspace=@diffusionstudio/cli
+```
+
+Before sending a PR:
+
+```sh
+npm run check # typecheck all workspaces
+npm run lint # lint all workspaces
+```
+
+## License
+
+[MPL-2.0](LICENSE)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..587d8a7a
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,10 @@
+# Diffusion Studio documentation
+
+Diffusion Studio is driven through `dapi`, its CLI. Start here:
+
+- [Getting started](getting-started.md): install the CLI, open a project, first mount, first export
+- [CLI reference](cli.md): every command, its options, and its output
+- [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).
diff --git a/docs/assets.md b/docs/assets.md
new file mode 100644
index 00000000..675076b5
--- /dev/null
+++ b/docs/assets.md
@@ -0,0 +1,92 @@
+# Working with media
+
+The asset library holds a project's media. Beyond storage, the CLI ships an inspection toolchain (probe, decode, visualize, transcribe, analyze, align) so an agent can *look at* footage before cutting it. All of it runs locally except `analyze` and `transcript`, which use hosted models.
+
+**Id or path:** every inspection command takes either an asset id or a local file path. A path is imported into the library first, then inspected, so `dapi asset probe clip.mp4` works on a file that isn't in the project yet.
+
+## The library
+
+```sh
+dapi asset add <paths...> [--folder <id>] # import files
+dapi asset ls [--folder <id>] [--depth N] # the library as a folder tree
+dapi asset mv <ids...> [--to <folderId>] # move assets between folders
+dapi asset rm <ids...> # delete assets
+dapi asset export <ids...> [-o <path>] # write original file bytes back to disk (no re-encode)
+```
+
+Folders nest arbitrarily and are managed with `dapi folder`:
+
+```sh
+dapi folder ls [parentId]
+dapi folder create <name> [-p, --parent <id>]
+dapi folder rename <id> <name>
+dapi folder mv <ids...> [--to <folderId>]
+dapi folder rm <ids...> # cascades: deletes all descendant folders AND assets;
+ # the output reports the deleted counts
+```
+
+Omitting a folder id anywhere always means the library root. (Opening a folder with `dapi open ./dir` builds this tree automatically from the directory structure; see [Getting started](getting-started.md#turn-a-folder-of-footage-into-a-project).)
+
+## Inspecting media
+
+### `asset probe`
+
+```sh
+dapi asset probe <id|path>
+```
+
+Container and per-track technical metadata (format, duration, codec parameters), demuxed locally without decoding, like `ffprobe`. Packet stats (frame rate, bitrate) are estimated from a leading sample, so they're fast but approximate.
+
+### `asset frame`
+
+```sh
+dapi asset frame <id|path> [-t <time...>] [-o <dir>]
+```
+
+Decodes video frames at the given timestamps to PNGs, at the asset's full resolution. Prints `{ time, path }` per frame. (For the *composited* canvas instead of the raw asset, use `dapi node screenshot`.)
+
+### `asset visualize`
+
+```sh
+dapi asset visualize <id|path> [-s <start>] [-e <end>] [-x <scale>] [-o <path>]
+```
+
+Renders a one-image preview chosen by media type: audio gets an amplitude **waveform** with a time axis, video gets a **filmstrip** of evenly sampled frames with the audio waveform beneath it, and images get a thumbnail. `-s`/`-e` window the preview; `-x` trades thumbnail size against grid density. Prints `{ path }`.
+
+### `asset transcript`
+
+```sh
+dapi asset transcript <id|path>
+```
+
+Transcribes speech in a video or audio asset. Returns segments with **word-level start/end times in seconds**: the raw material for caption timing, jump cuts, and content search.
+
+### `asset analyze`
+
+```sh
+dapi asset analyze <id|path> [-p <prompt>] [-s <start>] [-e <end>]
+```
+
+Puts a multimodal model in front of an image, video, or audio asset. Without a prompt, returns a general description; with one, answers it ("what's the dominant color?", "when is the product shown?"). `-s`/`-e` scope the analyzed segment; timestamps in the answer are relative to `-s`.
+
+### `asset sync`
+
+```sh
+dapi asset sync <audioId|path> -v <videoId|path>
+```
+
+Measures the offset between a standalone recording (a lav or voice track) and the camera audio of the same take, by cross-correlation. Prints `{ offsetSeconds, confidence }` with the convention `audioStart = videoStart + offsetSeconds`; a clear match scores above ~0.9. Read-only: position the clip yourself with the reported offset.
+
+## A typical agent pass
+
+```sh
+dapi open -b ./shoot # project from footage
+dapi asset ls --depth 1 # what's here?
+dapi asset probe gbHJ # what format is it?
+dapi asset visualize gbHJ # what does it look like over time?
+dapi asset transcript gbHJ # what is said, and when?
+dapi asset analyze gbHJ -p "best moment for a thumbnail?"
+dapi mount cut.tsx # compose the edit
+dapi node screenshot # verify visually
+dapi node export -o cut.mp4 # ship it
+```
diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 00000000..2e648cfd
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,201 @@
+# CLI reference
+
+`dapi` drives a running Diffusion Studio instance over a local socket. Every command except `open` and `fonts` needs the app running; launch it with `dapi open` (add `-b` for headless).
+
+## Conventions
+
+- **stdout is JSON.** Single results are one JSON value; collections and batch results are JSON Lines (one object per line, no surrounding array). `mount` and `node insert` print nothing on success.
+- **stderr is for humans:** error messages and progress spinners.
+- **Exit codes:** `0` on success, `1` on any error.
+- **Unix names are canonical:** `ls`, `rm`, `cp`, `mv`, `grep`. The English forms (`list`, `remove`, `duplicate`, `move`) are aliases, and `get` is an alias for every `ls`.
+- **Group aliases:** `selection`→`sel`, `node`→`n`, `project`→`p`, `asset`→`a`, `folder`→`fld`, `context`→`ctx`.
+- **Batch commands** (`node rm`, `node patch`, `asset add`, …) emit one `{ status: "fulfilled" | "rejected", … }` line per input, so partial failures are visible per item.
+
+### Time values
+
+Wherever a command takes a time, three formats are accepted (frames are at 30 fps):
+
+| Format | Example | Meaning |
+| --- | --- | --- |
+| number | `2.2` | seconds |
+| `"<n>f"` | `"45f"` | frames |
+| clock | `"02:30"`, `"01:02:30"` | MM:SS or HH:MM:SS |
+
+Times in output are plain seconds, except in `node ls`, whose raw records use engine units (frames, packed `0xRRGGBB` colors, dB).
+
+## App
+
+### `open`
+
+```sh
+dapi open [target] [-b, --background]
+```
+
+Launches the app, or opens a target: a file, a `diffusion://` deep link, or a **folder**, which creates a project from the folder's media (or switches to the one created earlier; see [Getting started](getting-started.md#turn-a-folder-of-footage-into-a-project)). `--background` launches with no window, for headless use. The only command that doesn't need the app already running (besides `fonts`).
+
+### `whoami`
+
+Prints the signed-in account `{ id, email, provider }`, or `null`.
+
+### `context`
+
+Prints the open project's essentials: project id and name, entity count, scenes with sizes, the active scene, the playhead position (frames), and available font families. Call it first.
+
+## Composing
+
+### `mount`
+
+```sh
+dapi mount (<path> | --code <str>)
+```
+
+Compiles a Solid JSX module and mounts its rendered roots into the document. Re-mounting rebuilds keyed roots in place, like reloading a webpage. Declared generative assets are produced during the mount, which blocks until they land. With `--code`, a bare JSX expression is wrapped into a module automatically. See [Writing compositions](composition.md).
+
+### `node insert`
+
+```sh
+dapi node insert <parentId> (<path> | --code <str>) [-i, --index <N>]
+```
+
+Same pipeline as `mount`, but inserts the rendered roots as children of an existing entity instead of mounting document roots. Roots take no `key`; every run inserts fresh nodes. `--index` sets the position among the parent's children (node roots only). Also how you extend sub-entities, e.g. adding a stop to a gradient:
+
+```sh
+dapi node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'
+```
+
+### `node patch`
+
+```sh
+dapi node patch ([path.json] | --json <str>)
+```
+
+Assigns JSX props on existing entities. The payload is an array of `{ id, …props }`, taking exactly the props a JSX element takes (see the [element reference](composition.md#elements)). A rejected entry applies none of its props. Renaming is patching `name`; recoloring is patching `fill`; paints and color stops are patchable too.
+
+```sh
+dapi node patch --json '[{ "id": 42, "x": 100, "opacity": 0.5 }]'
+```
+
+Note: `src` resolves asynchronously after the other props; patch it on its own to keep failure reporting unambiguous.
+
+## Inspecting the scene graph
+
+### `node tree`
+
+```sh
+dapi node tree [id] [--depth N]
+```
+
+An entity's subtree as nested JSON: structure only, with a compact `description` per node. The way to discover ids. Default depth `3`; `0` means the full subtree. Omit the id for one tree per top-level node.
+
+### `node ls`
+
+```sh
+dapi node ls [ids...]
+```
+
+The raw entity records: every component the entity carries, in engine units. The property-level counterpart to `tree`. With no ids, lists the top-level nodes.
+
+### `node grep`
+
+```sh
+dapi node grep <pattern> [id] [-i] [-t <types...>] [-k <components...>] [-l] [-c]
+```
+
+Searches entity records by regex and prints matching entities with the components that matched. `[id]` scopes to a subtree. `-t` filters by node type, `-k` restricts to specific components, `-l` prints refs only, `-c` prints a count. Find nodes by name with `dapi node grep -k Name Title`; find every entity with a `Trim` component with `dapi node grep -k Trim .`.
+
+### `node screenshot`
+
+```sh
+dapi node screenshot [id] [-t, --time <time>]
+```
+
+Focuses the node (or the active scene, if omitted) and captures it to a PNG at the given timeline position. Prints `{ path }`.
+
+### `selection`
+
+```sh
+dapi selection ls # the selected nodes
+dapi selection set [ids...] # replace the selection (no ids = clear)
+dapi selection focus # pan/zoom the canvas to the selection
+```
+
+Mutations print the resulting selection, so calls can be chained without a follow-up read.
+
+## Editing nodes
+
+### `node cp`
+
+Deep-clones nodes including descendants: `dapi node cp <ids...>`. Prints `{ sourceId, newId }` per input.
+
+### `node rm`
+
+Deletes nodes and their descendants: `dapi node rm <ids...>`.
+
+## Rendering
+
+### `node export`
+
+```sh
+dapi node export [id] [-o, --output <path>] ([config.json] | --json <str>)
+```
+
+Renders a scene to a video file, locally. Defaults to the active scene and an MP4 (H.264, 10 Mbps, 1080p, AAC 128 kbps) in the temp directory; prints `{ path }`. Long-running: progress goes to stderr, stdout stays clean JSON. The encode window follows the scene's workarea.
+
+All config fields are optional:
+
+```jsonc
+{
+ "format": "mp4", // "mp4" | "webm" | "ogg" | "mov"
+ "video": {
+ "codec": "avc", // "avc" | "hevc" | "vp9" | "av1" | "vp8"
+ "bitrate": 10000000, // bits/sec
+ "fps": 30, // default: the scene's frame rate
+ "resolution": 1080, // target height; width follows the scene's aspect
+ "enabled": true
+ },
+ "audio": {
+ "codec": "aac", // "aac" | "opus"
+ "bitrate": 128000,
+ "sampleRate": 48000,
+ "numberOfChannels": 2,
+ "enabled": true // false = video only
+ },
+ "trim": { "end": 30 } // seconds; cap the encode
+}
+```
+
+## Projects
+
+```sh
+dapi project active # the open project, or null
+dapi project ls # all projects, most recent first
+dapi project create [name] # create and open
+dapi project set <id> # switch to a project
+dapi project rm <id> # delete
+```
+
+## Assets and folders
+
+The library commands (`asset add/ls/mv/rm/export`, `folder ls/create/rename/mv/rm`) and the media-inspection commands (`probe`, `transcript`, `analyze`, `visualize`, `frame`, `sync`) are covered in [Working with media](assets.md).
+
+## Discovery
+
+### `models`
+
+```sh
+dapi models [image|video|audio]
+```
+
+Lists the generation models available per media type, with each model's id and its constraints (durations, aspect ratios, features). These are what you reference from `generate.*` declarations.
+
+### `voices`
+
+Lists the speech voices for `generate.voice` declarations.
+
+### `fonts`
+
+```sh
+dapi fonts [-f <pattern>] [-w <weights...>] [-s normal|italic] [-l <n>] [-n]
+```
+
+Lists local font families and variants (macOS only). `-n` prints plain family names. Works without the app running.
diff --git a/docs/composition.md b/docs/composition.md
new file mode 100644
index 00000000..c866a728
--- /dev/null
+++ b/docs/composition.md
@@ -0,0 +1,180 @@
+# Writing compositions
+
+Compositions are **Solid JSX modules**. `dapi mount` compiles the module, runs it in the app, and renders every JSX element into an editable node in the document: no hidden DOM, no CSS, no layout pass. All positioning is explicit pixels.
+
+```tsx
+export default function Project() {
+ return (
+ <scene key="intro" name="Intro" width={1920} height={1080} fill="black">
+ {/* ... */}
+ </scene>
+ );
+}
+```
+
+The module's default export is the project component. Solid's control flow (`<For>`, `<Show>`, …) and primitives (`createSignal`, `createMemo`, …) are available to *compose* the tree; the render is one-shot: after commit, the nodes belong to the document and signal changes no longer affect it. The update path is re-running the mount.
+
+**Dependencies:** `solid-js` and `@diffusionstudio/jsx` are provided by the app; everything else you import (npm packages, local files, JSON) is bundled by the CLI. Libraries must be browser-compatible.
+
+## Roots and keys
+
+Every top-level element declares its identity with a `key`:
+
+- Mounting rebuilds the existing node carrying that key, or creates it. Entity id and canvas position are preserved across re-mounts.
+- Keyed nodes the render no longer produces are **deleted**; the mount owns its keyed roots. Unkeyed nodes (made by hand in the editor) are never touched.
+- Keys must be unique within a render. Give roots a `name` too: the key identifies, the name labels.
+
+The first rendered root becomes the active scene. New roots are auto-placed on the canvas near the viewport center; `<scene>` has no `x`/`y` because canvas arrangement is an editor concern, not part of the composition.
+
+## Elements
+
+| Element | What it makes |
+| --- | --- |
+| `<scene>` | A scene; clips children to its `width`×`height`. Document root only; scenes don't nest. |
+| `<group>` | Container with a transform; give it `fill` to draw a rectangle. |
+| `<rect>` | A filled rectangle. |
+| `<text>` | Editable text. |
+| `<video>` / `<image>` | Media; `src` is required. |
+| `<audio>` | Sound only, no spatial props. |
+| `<sequence>` | Lays children out back-to-back in time. |
+| `<captions>` | Transcribes the scene's audio into styled captions. |
+| `<solidPaint>`, `<linearGradientPaint>`, `<radialGradientPaint>`, `<colorStop>` | Fills, declared as children; see [Paints](#paints). |
+
+User-defined components are ordinary Solid components; only intrinsic elements produce nodes.
+
+### Common props
+
+| Prop | Default | Meaning |
+| --- | --- | --- |
+| `key` | none | Stable identity; required on document roots. |
+| `name` | none | Node name in the editor. |
+| `x`, `y` | `0` | Position in px, relative to the parent, origin top-left. |
+| `width`, `height` | parent size | Box size in px. |
+| `rotation` | `0` | Degrees. |
+| `opacity` | `1` | `0`–`1`. |
+| `cornerRadius` | `0` | Px. |
+| `inPoint`, `outPoint`, `startTime` | see [Timing](#timing) | Temporal placement. |
+
+**Every box defaults to its parent's box**, the JSX analog of `position: absolute; inset: 0`. So a centered full-frame title is just:
+
+```tsx
+<text textAlign="center" textBaseline="middle" fontSize={128}>Hello</text>
+```
+
+### Per-element props
+
+- **`<scene>`**: `key`, `width`, `height` (all required), `name`, `fill`. No timing or transform props.
+- **`<rect>` / `<group>`**: `fill` (any CSS color; alpha is ignored, use `opacity`).
+- **`<video>`**: `src` (required), `objectFit` (`"cover"` | `"contain"` | `"fill"`, default `"cover"`), `volume` (`0`–`1`).
+- **`<image>`**: `src` (required), `objectFit` (default `"contain"`).
+- **`<audio>`**: `src` (required), `volume`, timing props.
+- **`<text>`**: string children (required), `fontFamily` (see `dapi fonts`), `fontSize`, `fontWeight`, `fontStyle`, `fill`, `textAlign`, `textBaseline`.
+
+These same props are what `dapi node patch` assigns on existing nodes.
+
+## Media sources
+
+`src` accepts:
+
+- an **absolute path** like `"/Movies/clip.mp4"`
+- a **remote URL**, registered as a remote asset
+- an **asset id**: an imported library asset (see `dapi asset ls`)
+- an **`AssetRef`**: the value returned by a `generate.*` declaration
+
+## Timing
+
+Composition-relative, Lottie-inspired. Values take any [time format](cli.md#time-values) (seconds, `"45f"` frames, `"MM:SS"`).
+
+| Prop | Meaning |
+| --- | --- |
+| `inPoint` / `outPoint` | The window on the parent timeline where the node is visible/audible. Omitted: media fits its natural duration, groups auto-fit their children. |
+| `startTime` | Where source time 0 sits on the composition timeline (defaults to the in point). May be negative to skip into the source. |
+
+```tsx
+<video src="/Movies/clip.mp4" inPoint={0} outPoint={16} startTime="-30f" />
+// plays from composition 0-16 s, starting 1 s (30 frames) into the source
+```
+
+`<sequence>` removes the arithmetic for back-to-back cuts: children are placed sequentially and non-overlapping in document order.
+
+## Paints
+
+A node's fill is a **paint child**; the `fill` prop is shorthand for a solid paint. Declaring paints as children unlocks gradients and stacking (later paints render on top, including over the media paint of a `<video>` or `<image>`):
+
+```tsx
+<rect width={640} height={360} cornerRadius={24}>
+ <linearGradientPaint rotation={90}>
+ <colorStop offset={0} color="#FF0055" />
+ <colorStop offset={1} color="#0055FF" />
+ </linearGradientPaint>
+</rect>
+```
+
+`<solidPaint>` takes `color` (required) and `opacity`; gradient paints take `rotation` and `opacity` and only `<colorStop>` children (`offset` and `color` required). Colors are any CSS color; alpha is ignored, use `opacity`.
+
+## Generated assets
+
+Assets that don't exist yet are declared as values with the `generate` namespace and passed wherever a source is expected:
+
+```tsx
+import { generate } from "@diffusionstudio/jsx";
+
+const hero = generate.image({ prompt: "A neon city at night, cinematic", seed: 42 });
+const motion = generate.video({ prompt: "slow camera push-in", startFrame: hero, duration: 5 });
+const vo = generate.voice({ prompt: "Welcome to the future." });
+```
+
+- `generate.image({ prompt, model?, aspectRatio?, refs?, seed? })`
+- `generate.video({ prompt, model?, aspectRatio?, duration?, audio?, startFrame?, endFrame?, seed? })`
+- `generate.voice({ prompt, voice? })` where `prompt` is the text to speak
+- `generate.audio({ prompt, model? })`
+
+Run `dapi models <type>` for valid model ids and per-model constraints, `dapi voices` for voices.
+
+Declarations are pure: nothing generates until the mount commits, and refs never used by a mounted element are dropped. Because `startFrame`/`endFrame`/`refs` take refs as values, dependencies generate in the right order and cycles are impossible.
+
+**Caching:** results are cached by content (model, prompt, resolved refs, seed, …) within a session: re-mounting an unchanged project reuses assets instead of regenerating, and identical declarations collapse to one asset. Set `seed` for reproducibility.
+
+## Captions
+
+`<captions />` inside a scene transcribes that scene's audio into a styled, timed caption node. It runs after generated assets land (so it can caption generated voice-over), attaches asynchronously, and is cached against the scene's audible mix, so re-mounting with unchanged audio doesn't re-transcribe.
+
+```tsx
+<captions preset="spotlight" colors={["#FF0055"]} />
+```
+
+| Preset | Style |
+| --- | --- |
+| `"classic"` (default) | Centered lowercase text, soft drop shadow, a few words at a time. |
+| `"cascade"` | Light text lower-left; words appear as spoken. |
+| `"spotlight"` | Bold italic centered line; the spoken word lights up (1 color slot). |
+| `"whisper"` | Small, wide, understated ~2 s phrases. |
+| `"paper"` | Centered two-line block; the spoken line is emphasized. |
+| `"guinea"` | Uppercase display; the spoken word enlarges and cycles 3 colors (3 slots). |
+| `"stark"` | Heavy uppercase, difference-blended into the footage. |
+
+`colors` fills a preset's color slots in order; presets without slots ignore it.
+
+## Types and tooling
+
+For IntelliSense and typechecking in a project folder:
+
+```sh
+npm install --save-dev @diffusionstudio/jsx solid-js
+```
+
+```jsonc
+// tsconfig.json
+{
+ "compilerOptions": {
+ "jsx": "preserve",
+ "jsxImportSource": "@diffusionstudio/jsx"
+ }
+}
+```
+
+The CLI strips types without checking them; run `tsc --noEmit` for type safety.
+
+## Errors
+
+Compile errors surface on stderr before the app is contacted. Evaluate/mount errors (invalid props, a root without `key`, nested `<scene>`, …) abort with **nothing inserted**. Generation errors surface after all generations settle; the mounted tree stays committed and the affected placeholder is left without media. Runtime errors map back to your source via sourcemaps.
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 00000000..828af947
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,78 @@
+# Getting started
+
+## Install the CLI
+
+The CLI is built from this repository. With Node 20+ installed:
+
+```sh
+git clone https://github.com/diffusionstudio/editor.git
+cd editor
+npm install
+npm run symlink:create --workspace=@diffusionstudio/cli
+```
+
+`symlink:create` builds `dapi` and links it into `/opt/homebrew/bin` (the macOS/Homebrew layout). On other setups, build with `npm run build --workspace=@diffusionstudio/cli` and link `apps/cli/dist/index.js` onto your PATH yourself.
+
+## Launch the editor
+
+Every `dapi` command except `open` and `fonts` talks to a running Diffusion Studio instance. Start one:
+
+```sh
+dapi open # launch the app
+dapi open -b # launch headless (no window), ideal for agents and CI
+```
+
+When developing from source, `npm run dev:desktop` starts the app too.
+
+## Turn a folder of footage into a project
+
+Point `open` at a directory and it becomes a project: every supported media file underneath is imported, with the directory structure mirrored as library folders.
+
+```sh
+dapi open ./shoot-2026-07
+```
+
+The first run creates the project and writes a `.dapi` marker file into the folder; later runs read the marker and just switch to that project. Commit the marker to share one project across a team, or add it to `.gitignore` to keep the association per-clone.
+
+You can also manage projects directly: `dapi project create`, `dapi project ls`, `dapi project set <id>`.
+
+## Look around
+
+```sh
+dapi context # the open project: scenes, active scene, playhead, fonts
+dapi asset ls # the media library as a folder tree
+```
+
+`dapi context` (alias `ctx`) is the right first call in any session; it tells you what is on the canvas before you change it.
+
+## Mount your first composition
+
+Compositions are Solid JSX modules rendered into the document with `dapi mount`. For a one-liner, pass code inline:
+
+```sh
+dapi mount --code '<scene key="hello" name="Hello" width={1920} height={1080} fill="black">
+ <text textAlign="center" textBaseline="middle" fontSize={120} fill="white">Hello World</text>
+</scene>'
+```
+
+The `key` is the scene's stable identity: re-running the mount rebuilds that scene in place instead of adding a copy. For anything real, put the module in a file (`dapi mount hero.tsx`) and see [Writing compositions](composition.md).
+
+Check the result visually:
+
+```sh
+dapi node screenshot # prints { "path": "/tmp/….png" }
+```
+
+## Export
+
+```sh
+dapi node export -o hello.mp4
+```
+
+Renders the active scene locally with sensible defaults (MP4, H.264, 1080p). Codec, bitrate, resolution, and trim are configurable; see [`node export`](cli.md#node-export) in the CLI reference.
+
+## Next
+
+- [CLI reference](cli.md): the full command surface
+- [Writing compositions](composition.md): timing, paints, generative assets, captions
+- [Working with media](assets.md): probe, transcribe, analyze, and align footage