Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

docs(api): developer documentation for the Concat API under docs/

Jareera0c42068f625
diff --git a/README.md b/README.md
index 5257858d..e8da0c74 100644
--- a/README.md
+++ b/README.md
@@ -89,7 +89,7 @@ Optional models download from the settings panel on first use and then never nee
> [!IMPORTANT]
> The best way to contribute is to grab a build from the [Releases](https://github.com/jub0t/Concat/releases) page and use it: find where it breaks, and say where it could be better.
>
-> Ready to write code? [CONTRIBUTING.md](./CONTRIBUTING.md) covers setup, the layout of the tree, the checks to run, and how contributions are licensed. Want to write an effect, a filter or a transition instead? [EFFECTS.md](./EFFECTS.md) is the whole of it: a folder, a manifest, and a chain or a shader, loaded from your effects folder while the app runs. [ROADMAP.MD](./ROADMAP.MD) says where the project is going, and [this Discussion](https://github.com/jub0t/Concat/discussions/3) is where it was announced.
+> Ready to write code? [CONTRIBUTING.md](./CONTRIBUTING.md) covers setup, the layout of the tree, the checks to run, and how contributions are licensed. Want to write an effect, a filter or a transition instead? [EFFECTS.md](./EFFECTS.md) is the whole of it: a folder, a manifest, and a chain or a shader, loaded from your effects folder while the app runs. Driving Concat from a script, a service or an agent? [docs/](./docs/README.md) is the developer reference for the Concat API and its transports: JSON-RPC, gRPC and MCP. [ROADMAP.MD](./ROADMAP.MD) says where the project is going, and [this Discussion](https://github.com/jub0t/Concat/discussions/3) is where it was announced.
>
> Contributors are free to claim a `@Contributor` role in the Discord server, just ask for it.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..be1a1730
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,112 @@
+<!-- https://github.com/jub0t/Concat/issues/123 -->
+
+# Concat developer docs
+
+**In one line:** anything the Concat window can do to a project, your program
+can do through the Concat API, over JSON-RPC or gRPC.
+
+## Pick a page
+
+| I want to… | Go to |
+|---|---|
+| See a working example in 30 seconds | [Quick start](#quick-start) below |
+| Understand the model: sessions, jobs, errors | [API overview](api/overview.md) |
+| Look up a method and its reply | [Methods](api/methods.md) |
+| Make an edit (add a clip, trim, title, effect) | [Edit commands](api/edits.md) |
+| Know what a clip / project / package looks like as JSON | [Types](api/types.md) |
+| Script Concat over stdin or a socket | [JSON-RPC](transports/json-rpc.md) |
+| Use generated clients over HTTP/2 | [gRPC](transports/grpc.md) |
+| Connect an AI agent (Model Context Protocol) | [MCP](transports/mcp.md) |
+| Copy-paste a whole script | [Recipes](recipes.md) |
+
+## Quick start
+
+**1. Run one call.** From a source checkout:
+
+```sh
+cd src
+cargo run -p concat-cli -- api '{"method":"version"}'
+```
+
+```json
+{"jsonrpc":"2.0","id":null,"result":{"apiVersion":"0.2","concat":"0.2.3","dirs":{"config":"…","data":"…"},"capabilities":["events"]}}
+```
+
+**2. Make a video.** Put these lines in `edit.jsonl` and pipe them in with
+`cargo run -p concat-cli -- api < edit.jsonl`:
+
+```jsonl
+{"jsonrpc":"2.0","id":1,"method":"project.create","params":{"location":"/edits","name":"Reel"}}
+{"jsonrpc":"2.0","id":2,"method":"media.import","params":{"path":"/edits/Reel","file":"/footage/take1.mp4"}}
+{"jsonrpc":"2.0","id":3,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addClipAtFirstFree","mediaId":"m1","start":0}}}
+{"jsonrpc":"2.0","id":4,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addTextClip","start":1,"style":{"content":"Hello"}}}}
+{"jsonrpc":"2.0","id":5,"method":"export.run","params":{"path":"/edits/Reel","output":"/edits/reel.mp4"}}
+```
+
+**3. Watch it finish.** The export answers at once with a job name, then
+reports as events until it is done:
+
+```jsonl
+{"jsonrpc":"2.0","id":5,"result":{"job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4"}}
+{"jsonrpc":"2.0","method":"export.progress","params":{"job":"j1","path":"/edits/Reel","frame":30,"total":150,"stage":"video"}}
+{"jsonrpc":"2.0","method":"export.done","params":{"job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4","width":1920,"height":1080}}
+```
+
+> [!TIP]
+> The same lines work over a socket. `concat-cli serve` listens on
+> `127.0.0.1:7420`, and the window's **Settings › Remote** page serves the
+> same API while the editor is open. See [JSON-RPC](transports/json-rpc.md).
+
+## The three ways in
+
+| Transport | How you reach it | Status |
+|---|---|---|
+| **JSON-RPC 2.0 lines** | `concat-cli api` (stdin), `concat-cli serve` (TCP or Unix socket), the window's Remote page | ✅ Shipped |
+| **gRPC** over HTTP/2 | `concat-cli serve --grpc`, in a build with the `grpc` feature | ✅ Shipped, behind a feature |
+| **MCP** | An MCP server exposing the API as tools | 🚧 Not in this tree yet. [MCP](transports/mcp.md) says what exists and how to bridge today |
+
+All three carry the **same methods, payloads and errors**. A method added
+to the API reaches every transport without a change to any of them.
+
+## Five things to know
+
+1. **Call `version` first.** Its `capabilities` list says what this build
+ serves.
+2. **Projects are folders.** Every method names a project by its folder
+ path, and the folder must be open (`project.open`) first.
+3. **Edits are commands.** `edit.apply` carries the window's own edit
+ vocabulary, unchanged. Same clamps, same refusals.
+4. **Exports are jobs.** `export.run` returns at once; progress comes as
+ events; one export runs at a time.
+5. **Errors have codes.** Branch on `code` (`notOpen`, `refused`, `busy`…);
+ show `message` to a person.
+
+## Where the code is
+
+| Piece | Path |
+|---|---|
+| The contract: methods, payloads, events, errors | `src/crates/concat-api/src/message.rs` |
+| The dispatcher that runs them | `src/crates/concat-api/src/lib.rs` |
+| The JSON-RPC envelope | `src/crates/concat-api/src/rpc.rs` |
+| The socket server: JSON-RPC lines, gRPC, tokens | `src/crates/concat-server/` |
+| The gRPC service definition | `src/crates/concat-server/proto/concat.proto` |
+| The CLI: `api` and `serve` | `src/crates/concat-cli/src/main.rs` |
+| The edit commands | `src/crates/concat-project/src/commands/mod.rs` |
+
+Related reading: [`ARCHITECTURE.md`](../ARCHITECTURE.md) places the API in
+the engine; [`EFFECTS.md`](../EFFECTS.md) is for writing the packages the
+catalogue lists.
+
+## Licensing
+
+Concat is AGPL-3.0-or-later. A program that talks to it over this API is a
+client. A plugin built on the API may carry its own licence under
+[`LICENSE-EXCEPTIONS.md`](../LICENSE-EXCEPTIONS.md).
+
+## Keeping these pages true
+
+These pages live with the code. A pull request that adds or changes a
+method, command, event, error or transport updates the page that describes
+it. The `apiVersion` a build reports is `API_VERSION` in `message.rs`; the
+rules for bumping it are in the
+[overview](api/overview.md#versioning-and-capabilities).
diff --git a/docs/api/edits.md b/docs/api/edits.md
new file mode 100644
index 00000000..73ffcfc0
--- /dev/null
+++ b/docs/api/edits.md
@@ -0,0 +1,632 @@
+# Edit commands
+
+**In one line:** every edit the window can make, as a JSON object you send
+through `edit.apply`.
+
+```json
+{"method":"edit.apply","path":"/edits/Reel","command":{"op":"trimClip","clipId":"c2","edge":"end","delta":-1.5}}
+```
+
+A command is `{"op": "<name>", …fields}`. Fields are camelCase. The reply
+is an *EditorView* ([Types](types.md#editorview)) of the project after the
+edit; `createdId` names what the command made, if anything.
+
+## Cheat sheet
+
+| Op | Does | Makes |
+|---|---|---|
+| **Media** | | |
+| [`addMedia`](#addmedia) | file into the bin | `m…` |
+| [`removeMedia`](#removemedia) | bin item and every clip of it, out | |
+| [`updateMediaPath`](#updatemediapath) | relink a file | |
+| [`replaceClipMedia`](#replaceclipmedia) | point a clip at another file | `m…` if new |
+| **Placing clips** | | |
+| [`addClip`](#addclip) | media on a named track | `c…` |
+| [`addClipAtFirstFree`](#addclipatfirstfree) | media on the first free track | `c…` |
+| [`addTextClip`](#addtextclip) | a title | `c…` |
+| [`addLayerClip`](#addlayerclip) | an effect layer over everything beneath | `c…` |
+| [`freezeFrame`](#freezeframe) | a held still, cut into a clip | `c…` |
+| **Moving and cutting** | | |
+| [`moveClips`](#moveclips) | reposition any number of clips | |
+| [`trimClip`](#trimclip) | drag one edge | |
+| [`splitClips`](#splitclips) | cut at a time | `c…` (the tail) |
+| [`mergeClips`](#mergeclips) | rejoin split pieces | |
+| [`removeClips`](#removeclips) | delete | |
+| **Changing a clip** | | |
+| [`updateClip`](#updateclip) | patch: name, volume, fades, opacity, effects, transition, text, crop… | |
+| [`setClipTransform`](#setcliptransform) | scale, offset, rotation, stretch | |
+| [`setClipSpeed`](#setclipspeed) | playback rate | |
+| [`setClipSpeedCurve`](#setclipspeedcurve) | speed over time | |
+| [`setClipAnimation`](#setclipanimation) | a named in/out/combo/loop shape | |
+| [`setClipKey`](#setclipkey) · [`clearClipKey`](#clearclipkey) · [`clearClipKeys`](#clearclipkeys) | keyframes on scale, offset, rotation, opacity, volume | |
+| [`setEffectKey`](#seteffectkey) · [`clearEffectKey`](#cleareffectkey) · [`clearEffectKeys`](#cleareffectkeys) | keyframes on an effect parameter | |
+| [`setClipCutout`](#setclipcutout) · [`addCutoutStroke`](#addcutoutstroke) | background removal and brush corrections | |
+| [`detachAudio`](#detachaudio) · [`reattachAudio`](#reattachaudio) | a video's sound as its own clip, and back | `c…` |
+| **Tracks** | | |
+| [`addTrack`](#addtrack) | a new lane | `t…` |
+| [`removeTrack`](#removetrack) | a lane and its clips, out | |
+| [`setTrackFlag`](#settrackflag) | visible / muted | |
+| **Timelines** | | |
+| [`addTimeline`](#addtimeline) | a new timeline, made active | `tl…` |
+| [`removeTimeline`](#removetimeline) · [`renameTimeline`](#renametimeline) · [`selectTimeline`](#selecttimeline) · [`moveTimeline`](#movetimeline) · [`setTimelineVideo`](#settimelinevideo) | manage timelines | |
+| **Templates and fonts** | | |
+| [`setMediaPlaceholder`](#setmediaplaceholder) · [`fillSlot`](#fillslot) | template slots | |
+| [`addFont`](#addfont) · [`removeFont`](#removefont) | fonts for titles | |
+| **Grouping** | | |
+| [`batch`](#batch) | several commands as one undo step | last id inside |
+
+## Rules that apply to every command
+
+- **Ids.** Clips are `c…`, tracks `t…` (the first timeline's starter lanes
+ are `T1`–`T4`), timelines `tl…` (the first is `TL1`), media `m…`. Ids
+ come from the *EditorView* replies.
+- **Unknown ids** are usually a tolerated no-op: the request succeeds,
+ nothing changes, no undo step. Where a command errs instead, its entry
+ says so.
+- **Times** are seconds on the timeline. A start below 0 lands at 0.
+- **Numbers are clamped**, not refused, into the range each field states.
+ A NaN or infinite number is refused: "A number in that edit is not finite."
+- **A refusal** is a `refused` error whose message is the exact sentence
+ the window would show. The project is as it was.
+- Commands act on the **active timeline**, except where the entry says
+ "all timelines".
+
+## Refusal sentences
+
+| Sentence | Raised by |
+|---|---|
+| That media is no longer in the bin. | a clip-placing command whose media is gone |
+| That track no longer exists. | a clip-placing command whose track is gone |
+| There are no tracks. | first-free placement on a timeline with no tracks |
+| A timeline needs at least one track. | `removeTrack` on the last track |
+| A project needs at least one timeline. | `removeTimeline` on the last timeline |
+| That template slot no longer exists. | `fillSlot` with an unknown id |
+| That media is not a template slot. | `fillSlot` on ordinary media |
+| A number in that edit is not finite. | any command carrying NaN or infinity |
+| *(one of several sentences)* | `mergeClips`, saying why the pieces cannot be rejoined |
+
+---
+
+## Media
+
+### `addMedia`
+
+Imports a probed file into the bin, minting an `m` id.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `item` | *NewMedia* | The file as `media.probe` describes it (see [Types](types.md#newmedia)) |
+
+> [!TIP]
+> You rarely need this. `media.import` probes and adds in one request.
+> Use `addMedia` when you already have the probe, or inside a `batch`.
+
+A path already in the bin is a no-op that mints nothing.
+
+### `removeMedia`
+
+Removes a bin item and **every clip referencing it, on all timelines**.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `mediaId` | string | The bin item. Unknown id: no-op |
+
+### `updateMediaPath`
+
+Relinks a bin item to a new path on disk.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `mediaId` | string | The bin item. Unknown id: no-op |
+| `newPath` | string | The new absolute path |
+
+### `replaceClipMedia`
+
+Points a clip at another file, adding it to the bin first if it is not
+there. The clip keeps its in-point, length, looks and name; the copy stands
+in frame for frame. The bin keeps the original.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | The clip. Unknown id: no-op |
+| `item` | *NewMedia* | The probed file |
+
+---
+
+## Placing clips
+
+### `addClip`
+
+Places a clip of a bin item on a named track.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `mediaId` | string | The bin item. Gone: **refused** |
+| `trackId` | string | The lane. Gone: **refused** |
+| `start` | number | Seconds; floored at 0 |
+| `ripple` | bool | *optional*, default `false`. When the drop would overlap, shift every clip at or after `start` right by the new clip's length |
+
+Duration comes from the media: its own length for video and audio, 5 s
+for a still or a file with no reported length.
+
+```json
+{"op":"addClip","mediaId":"m1","trackId":"T1","start":2.5}
+```
+
+### `addClipAtFirstFree`
+
+`addClip` without naming a lane: lands on the lowest track with nothing in
+the clip's span, or on the bottom track (overlapping) rather than refusing.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `mediaId` | string | The bin item. Gone: **refused** |
+| `start` | number | Seconds; floored at 0 |
+
+### `addTextClip`
+
+Places a title: a clip with no media behind it, named after the text's
+first line.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `trackId` | string | *optional*. The lane. Absent picks a free track; a vanished track is **refused** |
+| `above` | bool | *optional*, default `false`. With no `trackId`: land on the first free lane *above* the highest occupied one, minting a lane at the top if needed. What captions use |
+| `start` | number | Seconds; floored at 0 |
+| `style` | *TextStyle* | *optional*. Only the fields you set; the rest are the window's defaults. `{"content": "Hello"}` is enough |
+| `duration` | number | *optional*, default 4 s |
+| `offsetY` | number | *optional*. Vertical placement as a fraction of frame height, clamped to ±3. Lower thirds are made of this |
+
+```json
+{"op":"addTextClip","start":1,"duration":3,"style":{"content":"Chapter one","fontSize":0.12,"color":"#ffcc00"},"offsetY":0.35}
+```
+
+### `addLayerClip`
+
+Places a layer: an effect over a span of the timeline that treats
+everything beneath it. The chain starts as the one package at its
+defaults; the clip's `opacity` is how hard it is applied.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `trackId` | string | *optional*. Absent picks the first free track |
+| `start` | number | Seconds; floored at 0 |
+| `duration` | number | *optional*, default 5 s |
+| `effectId` | string | A package id from `catalogue.list`, e.g. `concat.warm` |
+| `name` | string | What the lane calls it |
+
+### `freezeFrame`
+
+Splits a clip at `time`, inserts a held still, and ripples later clips on
+that track by the hold's length. `createdId` is the freeze clip.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | A picture clip under the playhead |
+| `time` | number | Must fall strictly inside the clip |
+| `duration` | number | *optional*, default 1 s; floored at 1/60 s |
+| `still` | *NewMedia* | The probed still (a JPEG of the frame). **Required for video**; an image clip may omit it and reuse its media |
+
+Audio and text clips: no-op.
+
+---
+
+## Moving and cutting
+
+### `moveClips`
+
+Repositions any number of clips as one undo step.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `moves` | array of `{clipId, start, trackId}` | Where each clip goes. `start` floors at 0. Unknown `clipId`: that move is skipped. Unknown `trackId`: moved in time, kept on its track |
+
+```json
+{"op":"moveClips","moves":[{"clipId":"c2","start":0,"trackId":"T1"},{"clipId":"c3","start":6.1,"trackId":"T1"}]}
+```
+
+### `trimClip`
+
+Drags one edge of a clip.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | Unknown id: no-op |
+| `edge` | `"start"` or `"end"` | Which edge |
+| `delta` | number | Signed timeline seconds. Positive drags the head right (shortening) or the tail right (lengthening) |
+| `ripple` | bool | *optional*, default `false`. Close the lane up behind the trim: later clips on the track move by the change in length |
+
+How the edges differ:
+
+- **`start`** moves the in-point with the edge (scaled by speed), so the
+ remaining frames stay where they were.
+- **`end`** only lengthens or shortens.
+- Either edge stops at the 1/60 s minimum duration.
+
+### `splitClips`
+
+Cuts each named clip in two at one time.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipIds` | string[] | The clips under the playhead |
+| `time` | number | The cut point, in timeline seconds |
+
+- The head keeps the id and the transition; the tail is minted fresh and
+ stays source-continuous.
+- A clip the time misses, or grazes within 1/60 s of an edge, is skipped.
+
+### `mergeClips`
+
+Rejoins split pieces into the earliest piece, which keeps its id.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipIds` | string[] | The pieces, any order |
+
+**Refused** unless the pieces sit on one track, come from one file at one
+speed, touch within a microsecond, and are in source order. The message
+says which condition failed.
+
+### `removeClips`
+
+Deletes clips from the active timeline.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipIds` | string[] | Unknown ids are ignored |
+| `ripple` | bool | *optional*, default `false`. Leave no gap: on each touched track, later clips move left by the removed spans before them. Untouched tracks stay put |
+
+---
+
+## Changing a clip
+
+### `updateClip`
+
+Applies a patch: only the fields present change.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | Unknown id: no-op |
+| `patch` | *ClipPatch* | The fields to change |
+
+*ClipPatch* fields (all optional):
+
+| Field | Type | Clamp / meaning |
+|---|---|---|
+| `name` | string | Taken verbatim |
+| `volume` | number | Floored at 0; **not** capped at 1 |
+| `fadeIn`, `fadeOut` | number | Seconds, floored at 0 |
+| `opacity` | number | 0..=1 |
+| `preservePitch` | bool | Keep voices at pitch when speed ≠ 1 |
+| `muted` | bool | Silence the clip's own sound |
+| `reverse` | bool | Play backwards |
+| `flipH`, `flipV` | bool | Mirror |
+| `blend` | string | `normal` (or empty), `multiply`, `screen`, `add`, `lighten`, `darken` |
+| `filters` | *AppliedFilter*[] | **Replaces** the whole audio chain |
+| `videoEffects` | *AppliedFilter*[] | **Replaces** the whole video chain |
+| `crop` | *Crop* or `null` | See below |
+| `transitionIn` | *Transition* or `null` | The transition on the cut into the clip |
+| `text` | *TextStyle* or `null` | Title styling; also renames the clip after its first line |
+| `audioStream` | integer or `null` | Which of the media's audio streams to play; `null` means the file's first |
+
+> [!IMPORTANT]
+> `crop`, `transitionIn`, `text` and `audioStream` have three states:
+> **absent** leaves the value alone, **`null`** clears it, a **value**
+> replaces it.
+
+```json
+{"op":"updateClip","clipId":"c2","patch":{"volume":0.5,"fadeIn":0.5,"videoEffects":[{"id":"concat.gaussian-blur","params":{"radius":4}}],"transitionIn":{"id":"concat.dissolve","duration":0.75}}}
+```
+
+### `setClipTransform`
+
+Places the picture. Send only the fields you moved.
+
+| Field | Type | Clamp |
+|---|---|---|
+| `clipId` | string | Unknown id: no-op |
+| `scale` | number | 0.05..=8 |
+| `offsetX` | number | Fraction of frame width, ±3 |
+| `offsetY` | number | Fraction of frame height, ±3 |
+| `rotation` | number | Degrees, wrapped into (-180, 180] |
+| `stretchX`, `stretchY` | number | 0.1..=10, a multiplier beyond `scale` |
+
+### `setClipSpeed`
+
+Changes the playback rate while holding the source covered constant: the
+timeline length is what stretches.
+
+| Field | Type | Clamp |
+|---|---|---|
+| `clipId` | string | Unknown id: no-op |
+| `speed` | number | 0.0625..=16 |
+
+### `setClipSpeedCurve`
+
+Speed that changes over the clip.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | The clip |
+| `curve` | *SpeedPoint*[] or `null` | Points of `{at, speed}`, `at` a fraction 0..=1 of the clip. `null` returns to a constant rate at the current mean |
+
+### `setClipAnimation`
+
+A named shape on one slot of the clip.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | The clip |
+| `slot` | `"in"`, `"out"`, `"combo"`, `"loop"` | Which slot |
+| `animation` | `{preset, duration}` or `null` | `preset` is a name the inspector's menu offers for that slot (e.g. `"Fade"`, `"Zoom In"`, `"Slide Up"`, `"Pulse"`, `"Shake"`); `duration` in seconds for in/out. `null` takes it off |
+
+### `setClipKey`
+
+Puts a keyframe on one property at one point of the clip.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | The clip |
+| `property` | `"scale"`, `"offsetX"`, `"offsetY"`, `"rotation"`, `"opacity"`, `"volume"` | Which property |
+| `at` | number | Where in the clip, 0..=1 |
+| `value` | number | The value there, in the property's own units |
+| `ease` | `[x1, y1, x2, y2]` | *optional*, default linear. A CSS-style cubic bezier; the names `"linear"`, `"in"`, `"out"`, `"inOut"` are accepted too |
+
+A key within 0.002 of `at` on the same property is replaced.
+
+### `clearClipKey`
+
+Removes the key at `at` on one property, if there is one.
+
+| Field | Type |
+|---|---|
+| `clipId` | string |
+| `property` | as above |
+| `at` | number, 0..=1 |
+
+### `clearClipKeys`
+
+Removes every key on one property.
+
+| Field | Type |
+|---|---|
+| `clipId` | string |
+| `property` | as above |
+
+### `setEffectKey`
+
+A keyframe on one parameter of one link in the clip's video chain.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | The clip |
+| `entry` | integer | Index into `videoEffects`. Out of range: no-op |
+| `key` | string | The parameter's key from `catalogue.list` |
+| `at` | number | 0..=1 |
+| `value` | number | The parameter's own value; keep it within the package's range yourself |
+| `ease` | `[x1, y1, x2, y2]` | *optional*, default linear |
+
+### `clearEffectKey`
+
+Removes the key at `at` on one parameter of one link.
+
+| Field | Type |
+|---|---|
+| `clipId` | string |
+| `entry` | integer |
+| `key` | string |
+| `at` | number |
+
+### `clearEffectKeys`
+
+Removes every key on one parameter of one link.
+
+| Field | Type |
+|---|---|
+| `clipId` | string |
+| `entry` | integer |
+| `key` | string |
+
+### `setClipCutout`
+
+Sets or clears a picture's cutout: the mask that removes its background.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | Unknown id: no-op |
+| `cutout` | *Cutout* or `null` | `{"mode": "auto"}` is the usual start; `null` takes it off |
+
+*Cutout* fields: `mode` (`auto` or `custom`), `subject` (`auto`, `person`,
+`object`; default `auto`), `feather` (edge softness as a fraction of the
+picture's width), `strokes` (corrections, see next).
+
+Masks are found at export time; `export.run` reports it as
+`cutout.progress`.
+
+### `addCutoutStroke`
+
+Paints one brush stroke onto a clip's cutout. A clip with no cutout gets a
+custom one; an automatic cutout becomes custom.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `clipId` | string | Unknown id: no-op |
+| `stroke` | *Stroke* | `tool` (`smartBrush`, `brush`, `smartEraser`, `eraser`), `size` (diameter as a fraction of picture width), `points` (`[[x, y], …]` as fractions of the source picture), `at` (*optional* source second the stroke was painted at) |
+
+A stroke with no points is a no-op.
+
+### `detachAudio`
+
+Pulls a video clip's sound out into its own audio clip on a free lane,
+muting the video and moving its audio filters to the sound.
+
+| Field | Type |
+|---|---|
+| `clipId` | string, the video clip |
+
+No-op unless the clip is an unmuted video whose media has audio and is not
+already detached.
+
+### `reattachAudio`
+
+Undoes a detach: deletes the detached sound, unmutes the video, hands the
+filters back.
+
+| Field | Type |
+|---|---|
+| `clipId` | string, the video **or** its detached sound |
+
+---
+
+## Tracks
+
+### `addTrack`
+
+Appends a lane, named after the highest "Track N" in use. No fields.
+
+### `removeTrack`
+
+Deletes a lane and every clip on it.
+
+| Field | Type |
+|---|---|
+| `trackId` | string |
+
+**Refused** on the last track.
+
+### `setTrackFlag`
+
+Flips one of a track's two toggles.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `trackId` | string | Unknown id: no-op |
+| `flag` | `"visible"` or `"muted"` | Which toggle |
+| `value` | bool | The new setting |
+
+---
+
+## Timelines
+
+### `addTimeline`
+
+Adds a fresh timeline with four lanes and makes it active. No fields.
+
+### `removeTimeline`
+
+Deletes a timeline; the active tab moves to a neighbour if it was this one.
+
+| Field | Type |
+|---|---|
+| `timelineId` | string. Unknown id: no-op |
+
+**Refused** on the last timeline.
+
+### `setTimelineVideo`
+
+Sets a timeline's output frame and rate.
+
+| Field | Type |
+|---|---|
+| `timelineId` | string. Unknown id: no-op |
+| `video` | *VideoSettings* |
+
+A zero dimension or rate is a no-op, not clamped.
+
+### `renameTimeline`
+
+| Field | Type |
+|---|---|
+| `timelineId` | string |
+| `name` | string, trimmed. Whitespace-only is ignored |
+
+### `selectTimeline`
+
+Switches which timeline later commands act on.
+
+| Field | Type |
+|---|---|
+| `timelineId` | string. Unknown id: selection stays |
+
+### `moveTimeline`
+
+Moves a timeline tab to a new position.
+
+| Field | Type |
+|---|---|
+| `timelineId` | string |
+| `index` | integer, 0-based, counted with the tab already removed; clamped to the end |
+
+---
+
+## Templates and fonts
+
+### `setMediaPlaceholder`
+
+Marks a bin item as a template slot, or back to ordinary media.
+
+| Field | Type |
+|---|---|
+| `mediaId` | string. Unknown id: no-op |
+| `placeholder` | bool |
+
+### `fillSlot`
+
+Swaps a file into a template slot in place, on all timelines. The slot
+keeps its id, so clips keep working.
+
+| Field | Type |
+|---|---|
+| `mediaId` | string, a placeholder |
+| `item` | *NewMedia* |
+
+**Refused** if the id is unknown or the item is not a placeholder.
+`template.instantiate` does this for every slot for you.
+
+### `addFont`
+
+Registers a font file for titles.
+
+| Field | Type |
+|---|---|
+| `family` | string, the name titles refer to |
+| `path` | string, the font file |
+
+A path already registered is a no-op.
+
+### `removeFont`
+
+| Field | Type |
+|---|---|
+| `family` | string |
+
+Clips keep the family name; the face returns when the file does.
+
+---
+
+## Grouping
+
+### `batch`
+
+Several commands as one atomic edit and one undo step.
+
+| Field | Type |
+|---|---|
+| `commands` | *Command*[], applied in order. Nesting is allowed |
+
+- Applied to a staged copy; committed only if **every** command succeeds.
+- `createdId` in the reply is the last id minted inside.
+
+```json
+{"op":"batch","commands":[
+ {"op":"addTrack"},
+ {"op":"addTextClip","start":0,"duration":2,"style":{"content":"One"}},
+ {"op":"addTextClip","start":2,"duration":2,"style":{"content":"Two"}}
+]}
+```
+
+> [!NOTE]
+> A batch cannot refer to an id it mints, because the id is not known
+> until the batch is applied. Use `addClipAtFirstFree` / `addTextClip`
+> with `duration` rather than add-then-trim.
diff --git a/docs/api/methods.md b/docs/api/methods.md
new file mode 100644
index 00000000..956a13a1
--- /dev/null
+++ b/docs/api/methods.md
@@ -0,0 +1,526 @@
+# Methods
+
+**In one line:** every method the API answers, what it takes, what it gives
+back.
+
+## Cheat sheet
+
+| Method | Does | Replies with |
+|---|---|---|
+| [`version`](#version) | what this build serves | *VersionInfo* |
+| [`project.create`](#projectcreate) | new project folder, opened | *EditorView* |
+| [`project.open`](#projectopen) | open a folder | *EditorView* |
+| [`project.close`](#projectclose) | close, optionally save | `{}` |
+| [`project.list`](#projectlist) | recent projects | *ProjectInfo*[] |
+| [`project.get`](#projectget) | current state | *EditorView* |
+| [`project.document`](#projectdocument) | the `concat.json` a save writes | JSON object |
+| [`project.save`](#projectsave) | write to disk, optionally rename | `{}` |
+| [`project.setVideo`](#projectsetvideo) | frame size and rate (undoable) | *EditorView* |
+| [`edit.apply`](#editapply) | one edit command | *EditorView* |
+| [`edit.undo`](#editundo) | step back | *EditorView* |
+| [`edit.redo`](#editredo) | step forward | *EditorView* |
+| [`media.probe`](#mediaprobe) | what is in a file | *MediaSummary* |
+| [`media.import`](#mediaimport) | probe + add to bin | *EditorView* |
+| [`catalogue.list`](#cataloguelist) | effect packages and their params | *PackageInfo*[] |
+| [`template.list`](#templatelist) | the template library | *TemplateInfo*[] |
+| [`template.instantiate`](#templateinstantiate) | project from a template | *EditorView* |
+| [`template.save`](#templatesave) | project into a template | *TemplateInfo* |
+| [`export.run`](#exportrun) | render to a file, as a job | *Started* |
+| [`export.cancel`](#exportcancel) | stop a job | `{}` |
+| [`preview.frame`](#previewframe) | one frame as PNG | *Written* or *Picture* |
+
+Types in *italics* are in [Types](types.md).
+
+## How to read this page
+
+- Examples are **bare requests**, the shape `concat-cli api` takes on
+ stdin. On a socket or over gRPC the same fields go in `params` inside
+ the envelope. See [JSON-RPC](../transports/json-rpc.md).
+- Replies are shown as the `result` payload alone.
+- *optional* parameters may be left out; the default is stated.
+- `path` is always the project **folder**, and it must be open first, or
+ the reply is `notOpen`.
+
+---
+
+## `version`
+
+What this build serves. **Call it first.**
+
+**Parameters:** none.
+
+```json
+{"method":"version"}
+```
+
+**Reply**, a *VersionInfo*:
+
+```json
+{
+ "apiVersion": "0.2",
+ "concat": "0.2.3",
+ "dirs": {
+ "config": "/Users/ada/Library/Application Support/app.concat.editor",
+ "data": "/Users/ada/Library/Application Support/app.concat.editor"
+ },
+ "capabilities": ["events", "gpu", "json-rpc"]
+}
+```
+
+The capability names and the bump rules are in the
+[overview](overview.md#versioning-and-capabilities).
+
+---
+
+## `project.create`
+
+Creates a project folder and opens it.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `location` | string | The directory the project folder is made in |
+| `name` | string | The project's name. The folder is named after it; characters a filesystem refuses become `-` |
+| `video` | *VideoSettings* | *optional*. Frame and rate. **Default:** 1920×1080 at 30 fps |
+
+```json
+{"method":"project.create","location":"/edits","name":"Reel","video":{"width":1080,"height":1920,"rateNum":30,"rateDen":1}}
+```
+
+**Reply:** an *EditorView* of the new project.
+
+Good to know:
+
+- A fresh project has one timeline `TL1` with four tracks `T1`–`T4`.
+- It is added to the recents list, like one the window made.
+- A folder that already holds a project is refused (`failed`).
+
+---
+
+## `project.open`
+
+Opens a project folder.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+
+```json
+{"method":"project.open","path":"/edits/Reel"}
+```
+
+**Reply:** an *EditorView*.
+
+Good to know:
+
+- Opening a folder already open returns its state as it stands, edits and
+ all. The history is untouched.
+
+---
+
+## `project.close`
+
+Closes an open project.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+| `save` | bool | *optional*. Write the document first. **Default:** `false` |
+
+```json
+{"method":"project.close","path":"/edits/Reel","save":true}
+```
+
+**Reply:** `{}`.
+
+> [!WARNING]
+> Without `save: true`, unsaved edits are dropped.
+
+A running export is not affected; it holds its own copy of what it needs.
+
+---
+
+## `project.list`
+
+The projects this machine opened most recently, newest first.
+
+**Parameters:** none.
+
+**Reply:** an array of *ProjectInfo*.
+
+```json
+[{"path":"/edits/Reel","name":"Reel","width":1920,"height":1080,"rateNum":30,"rateDen":1,"openedAt":1790002385144}]
+```
+
+This is the launch screen's list. It names projects whether or not they
+are open now.
+
+---
+
+## `project.get`
+
+The state of an open project.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+
+**Reply:** an *EditorView*.
+
+---
+
+## `project.document`
+
+The document exactly as a save writes it: the contents of `concat.json`.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+
+**Reply:** the document, a JSON object.
+
+> [!TIP]
+> To inspect the project as data, prefer `project.get`. Its `project`
+> field is the same model without the flat `tracks` / `clips` / `video`
+> mirror that older builds read.
+
+---
+
+## `project.save`
+
+Writes the document to the project folder.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+| `name` | string | *optional*. A new name for the project |
+
+**Reply:** `{}`.
+
+---
+
+## `project.setVideo`
+
+Sets the active timeline's frame and rate, as an **undoable** edit.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+| `video` | *VideoSettings* | The frame and rate |
+
+```json
+{"method":"project.setVideo","path":"/edits/Reel","video":{"width":3840,"height":2160,"rateNum":60,"rateDen":1}}
+```
+
+**Reply:** an *EditorView*.
+
+A zero dimension or rate is `refused`.
+
+---
+
+## `edit.apply`
+
+Applies **one edit command** and records one undo step.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+| `command` | *Command* | The edit: `{"op": "…", …fields}`. All of them are in [Edit commands](edits.md) |
+
+```json
+{"method":"edit.apply","path":"/edits/Reel","command":{"op":"addClip","mediaId":"m1","trackId":"T1","start":2.5}}
+```
+
+**Reply:** an *EditorView* of the project after the edit.
+
+Good to know:
+
+- `createdId` in the reply is the id of what the command made: a clip
+ `c…`, track `t…`, timeline `tl…` or media `m…`. For a `batch` it is the
+ last id minted inside.
+- A **refusal** is a `refused` error. Its message is the sentence the
+ window would show. Nothing changed.
+- An edit that names something no longer there is, for most commands, a
+ **tolerated no-op**: unchanged view, no undo step.
+- Several commands as one undo step: wrap them in `{"op": "batch",
+ "commands": [...]}`.
+
+---
+
+## `edit.undo`
+
+Steps the history back one edit.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+
+**Reply:** an *EditorView*. With nothing to undo, it is the unchanged view.
+`canUndo` and `canRedo` say where the history stands.
+
+---
+
+## `edit.redo`
+
+Steps the history forward one edit.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+
+**Reply:** an *EditorView*.
+
+---
+
+## `media.probe`
+
+What is inside a media file. Touches no project.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The file |
+
+```json
+{"method":"media.probe","path":"/footage/take1.mp4"}
+```
+
+**Reply:** a *MediaSummary*.
+
+```json
+{
+ "path": "/footage/take1.mp4",
+ "duration": 6.121029,
+ "kind": "video",
+ "video": {"index":0,"codec":"h264","width":854,"height":480,"frameRate":30.0,"frameRateFraction":"30/1"},
+ "audio": {"index":1,"codec":"aac","sampleRate":48000,"channels":2,"title":"","language":"und"},
+ "audioTracks": [
+ {"index":1,"codec":"aac","sampleRate":48000,"channels":2,"title":"","language":"und"},
+ {"index":2,"codec":"aac","sampleRate":48000,"channels":2,"title":"","language":"und"}
+ ]
+}
+```
+
+A file that cannot be read or decoded is `failed`.
+
+---
+
+## `media.import`
+
+Probes a file and adds it to the project's bin. What dropping a file on
+the window does.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+| `file` | string | The file to import |
+
+```json
+{"method":"media.import","path":"/edits/Reel","file":"/footage/take1.mp4"}
+```
+
+**Reply:** an *EditorView*. `createdId` is the new media id (`m1`, `m2`, …).
+
+Good to know:
+
+- A path already in the bin is a no-op, and `createdId` is absent.
+- This is `media.probe` + the `addMedia` command, as one request.
+- The bin item's fields are in [Types → MediaItem](types.md#mediaitem).
+
+---
+
+## `catalogue.list`
+
+Every effect package the build knows, with its parameters. Enough to build
+a valid effect chain without reading a manifest.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `kind` | string | *optional*. One of `effect`, `filter`, `audio`, `transition`, `generator`. **Default:** all kinds. Any other word is `invalid` |
+
+```json
+{"method":"catalogue.list","kind":"effect"}
+```
+
+**Reply:** an array of *PackageInfo*, in id order.
+
+```json
+[{
+ "id": "concat.gaussian-blur",
+ "name": "Gaussian Blur",
+ "kind": "effect",
+ "category": "Blur",
+ "description": "A soft, even blur.",
+ "intensity": "radius",
+ "params": [
+ {"key":"radius","label":"Radius","type":"float","min":1.0,"max":50.0,"default":10.0,"step":1.0,"unit":"px","animate":false,"values":[],"labels":[]}
+ ]
+}]
+```
+
+How to use it:
+
+- `id` is what a clip's chain stores: in `videoEffects`, `filters`, or a
+ `transitionIn`.
+- each param's `key` is what the chain entry's `params` object stores it
+ under. See [Types → AppliedFilter](types.md#appliedfilter).
+
+---
+
+## `template.list`
+
+The template library.
+
+**Parameters:** none.
+
+**Reply:** an array of *TemplateInfo*, each naming its slots.
+
+What a template is: a bundle folder under `templates/` in the config
+directory, holding `template.json` (a project document whose placeholder
+media have blank paths), `assets/` (media and fonts that are part of the
+design) and `poster.jpg`.
+
+---
+
+## `template.instantiate`
+
+Makes a project from a template with every slot filled, and opens it.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `template` | string | The bundle folder, as `template.list` gave it |
+| `location` | string | The directory the project folder is made in |
+| `name` | string | The project's name |
+| `fills` | array of `{"mediaId", "file"}` | The file for each slot. `mediaId` is the slot's id from `template.list` |
+
+```json
+{"method":"template.instantiate","template":"/Users/ada/Library/Application Support/app.concat.editor/templates/Intro","location":"/edits","name":"My intro","fills":[{"mediaId":"m1","file":"/footage/logo.png"},{"mediaId":"m2","file":"/footage/take1.mp4"}]}
+```
+
+**Reply:** an *EditorView* of the new project.
+
+Good to know:
+
+- **Every slot must be filled.** A set that leaves one empty makes nothing.
+- Every file is probed first, so a bad path refuses the whole request and
+ leaves no folder behind.
+
+---
+
+## `template.save`
+
+Packs an open project into a new template bundle in the library.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+| `name` | string | The template's name |
+
+**Reply:** the new bundle's *TemplateInfo*.
+
+---
+
+## `export.run`
+
+Renders the active timeline to a file, as a **job**. Exactly what the
+window's Export sheet does: cutouts analysed, titles painted, then the
+frame loop and the mix.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+| `output` | string | The file to write. The container follows the extension; `.mp4` is the usual choice |
+| `crf` | integer | *optional*. Constant rate factor; lower is better and bigger. **Default:** 20 |
+| `preset` | string | *optional*. x264 preset name, `ultrafast` … `veryslow`. **Default:** `medium` |
+| `width` | integer | *optional*. **Default:** the timeline's |
+| `height` | integer | *optional*. **Default:** the timeline's |
+| `rateNum` | integer | *optional*. Frame rate numerator. **Default:** the timeline's |
+| `rateDen` | integer | *optional*. Frame rate denominator. **Default:** the timeline's |
+| `codec` | string | *optional*. `h264`, `hevc` or `av1`. **Default:** `h264`. Anything else is `invalid` |
+| `tenBit` | bool | *optional*. Ten bits a channel. **Default:** `false` |
+
+```json
+{"method":"export.run","path":"/edits/Reel","output":"/edits/reel.mp4","crf":18,"codec":"hevc"}
+```
+
+**Reply**, a *Started*, at once:
+
+```json
+{"job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4"}
+```
+
+**Then events**, until the job ends:
+
+```jsonl
+{"event":"cutout.progress","job":"j1","path":"/edits/Reel","mediaId":"m3","fetching":true,"fraction":0.4}
+{"event":"export.progress","job":"j1","path":"/edits/Reel","frame":30,"total":150,"stage":"video"}
+{"event":"export.progress","job":"j1","path":"/edits/Reel","frame":150,"total":150,"stage":"mux"}
+{"event":"export.done","job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4","width":1920,"height":1080}
+```
+
+or
+
+```json
+{"event":"export.failed","job":"j1","path":"/edits/Reel","error":{"code":"failed","message":"…"}}
+```
+
+Rules:
+
+- **One export at a time.** A second is refused with `busy`.
+- An empty timeline is `refused`.
+- `cutout.progress` only appears for clips with an automatic cutout whose
+ masks are not cached yet. `fetching` is true while the model downloads.
+- Event shapes are in [Types → Events](types.md#events). The job model is
+ in the [overview](overview.md#jobs-and-events).
+
+---
+
+## `export.cancel`
+
+Stops a running export at its next frame.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `job` | string | The job `export.run` named |
+
+**Reply:** `{}`. The job then ends with `export.failed` whose `error.code`
+is `cancelled`.
+
+A job that is not running (finished, or never existed) is `notFound`.
+
+---
+
+## `preview.frame`
+
+Composites the true frame at one instant, titles and effects included, as
+a PNG.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+| `time` | number | The timeline instant, in seconds |
+| `output` | string | *optional*. The file to write; folders above it are created. **Absent:** the picture comes back inline |
+| `width` | integer | *optional*. Frame width |
+| `height` | integer | *optional*. Frame height |
+
+```json
+{"method":"preview.frame","path":"/edits/Reel","time":1.5,"output":"/edits/frames/1.5.png","width":640,"height":360}
+```
+
+**Reply with `output`**, a *Written*:
+
+```json
+{"path":"/edits/frames/1.5.png","width":640,"height":360}
+```
+
+**Reply without**, a *Picture*:
+
+```json
+{"width":640,"height":360,"png":"iVBORw0KGgo…"}
+```
+
+Rules:
+
+- `width` and `height` count only **together**. Give both or neither;
+ neither means the timeline's size.
+- Zero for either is `invalid`.
+- The PNG is RGBA, 8 bits a channel, base64 in the standard alphabet with
+ padding.
diff --git a/docs/api/overview.md b/docs/api/overview.md
new file mode 100644
index 00000000..6a12e60e
--- /dev/null
+++ b/docs/api/overview.md
@@ -0,0 +1,228 @@
+# API overview
+
+**In one line:** one dispatcher answers every request; transports only carry
+JSON to it and back.
+
+**On this page:** [Three shapes](#three-shapes) · [Sessions](#sessions) ·
+[Projects on disk](#projects-on-disk) · [Jobs and events](#jobs-and-events) ·
+[Errors](#errors) · [Versioning](#versioning-and-capabilities) ·
+[Tolerance](#tolerance-and-refusal) · [Concurrency](#concurrency) ·
+[Embedding in Rust](#embedding-in-rust) · [App directories](#app-directories)
+
+---
+
+## Three shapes
+
+Everything that crosses the API is one of three JSON objects.
+
+| Shape | Looks like | Direction |
+|---|---|---|
+| **Request** | `{"method": "project.open", "path": "…"}` | in |
+| **Response** | `{"result": …}` or `{"error": {"code": "…", "message": "…"}}` | out, one per request |
+| **Event** | `{"event": "export.progress", "job": "j1", …}` | out, any time a job has news |
+
+- Methods are named `area.verb`: `project.open`, `edit.apply`, `export.run`.
+- A result is the method's payload **alone**. Nothing wraps it.
+- Field names are **camelCase** everywhere: requests, replies, the project
+ document, the edit commands.
+
+On stdin or a socket the three travel inside the JSON-RPC 2.0 envelope,
+which adds an `id` and nothing else. See [JSON-RPC](../transports/json-rpc.md).
+gRPC carries the same JSON as text inside a protobuf message. See
+[gRPC](../transports/grpc.md).
+
+---
+
+## Sessions
+
+A **session** is one open project. The API keeps one per project folder.
+
+- Every project method takes `path`, the project **folder**.
+- The folder must be open. A method on a closed folder is a `notOpen`
+ error, never a silent open.
+- `project.open` on a folder already open returns its state as it stands,
+ edits and all.
+- The path is canonicalised, so `.` and its absolute spelling are one
+ session.
+
+A session holds the **edit history**:
+
+| Method | Does |
+|---|---|
+| `edit.apply` | applies one command, records one undo step |
+| `edit.undo` / `edit.redo` | walk the history |
+| `project.save` | writes `concat.json` |
+| `project.close` | drops the session; saves first only if `save: true` |
+
+> [!WARNING]
+> `project.close` without `save: true` drops unsaved edits, the same as the
+> window's "Don't save".
+
+On a socket, **all connected callers share the sessions**. A project one
+caller opens is open for the others.
+
+---
+
+## Projects on disk
+
+A project is a **folder** holding `concat.json`.
+
+`project.create`:
+
+1. makes `<location>/<name>` (characters a filesystem refuses become `-`),
+2. writes the manifest,
+3. opens a session,
+4. puts it at the front of the recents list.
+
+It refuses a folder that already holds a project.
+
+| To read the project as… | Call |
+|---|---|
+| the model the engine holds | `project.get` |
+| the exact bytes a save writes | `project.document` |
+
+Both shapes are in [Types](types.md).
+
+---
+
+## Jobs and events
+
+A request that would take long runs as a **job**. Today that is
+`export.run`.
+
+1. The response names the job at once: `{"job": "j1", …}`.
+2. The work runs on its own thread.
+3. Progress arrives as **events**, each carrying `job` and `path`.
+4. The job ends with exactly one of `export.done` or `export.failed`.
+
+| Event | When |
+|---|---|
+| `cutout.progress` | masks for an automatic cutout are being found before the render; a model may download first |
+| `export.progress` | `frame` of `total`, in stage `video`, `audio` or `mux` |
+| `export.done` | the file was written |
+| `export.failed` | the file was not written; `error.code` is `cancelled` if you cancelled it |
+
+Rules:
+
+- **One export at a time.** A second `export.run` is refused with `busy`.
+- Job names are unique for the life of the dispatcher: `j1`, `j2`, …
+- On a socket, events go to **every** connected caller. Filter by `job`.
+- On stdin, the process waits for running jobs before it exits, so a job
+ begun on the last line still finishes.
+
+---
+
+## Errors
+
+An error has a `code` you branch on and a `message` you can show a person.
+
+| Code | JSON-RPC number | Meaning |
+|---|---|---|
+| `parse` | -32700 | The line was not JSON |
+| `invalid` | -32600 | Not a request: unknown method, missing or ill-typed field, value out of range |
+| `notOpen` | -32001 | That project folder is not open |
+| `notFound` | -32002 | That job, template or package does not exist |
+| `refused` | -32003 | The edit layer said no. Nothing changed. The message is the window's own sentence |
+| `busy` | -32004 | A one-at-a-time job is already running |
+| `cancelled` | -32005 | The job was stopped by `export.cancel`. Only ever inside `export.failed` |
+| `unauthorized` | -32006 | Wrong or missing token. Raised by the socket transports, never by the API itself |
+| `failed` | -32000 | Everything else: a file that would not read or write, a decode that failed, a model that did not download |
+
+In the JSON-RPC envelope the number is `error.code` and the name is
+`error.data.code`. Over gRPC both are fields of the `Error` message.
+
+---
+
+## Versioning and capabilities
+
+**Call `version` first.** Its reply has:
+
+| Field | Meaning |
+|---|---|
+| `apiVersion` | The contract this build speaks. Currently `0.2` |
+| `concat` | The build's own version |
+| `dirs` | The config and data directories (see [below](#app-directories)) |
+| `capabilities` | What this build serves, as names to test for |
+
+Capability names:
+
+| Name | Means |
+|---|---|
+| `events` | Jobs report through events. Every build has it |
+| `gpu` | Frames composite on a GPU. Depends on the machine |
+| `json-rpc` | Listening for JSON-RPC lines on TCP |
+| `unix-socket` | Listening for JSON-RPC lines on a Unix socket |
+| `grpc` | Listening for gRPC |
+
+When `apiVersion` changes:
+
+- ✅ Bumped when a method's **shape changes** in a way an old caller would
+ misread.
+- ❌ Not bumped for a new method, a new optional field, a new event or a
+ new capability. Ignore names you do not know.
+
+---
+
+## Tolerance and refusal
+
+The edit layer is forgiving about **state** and strict about **shape**.
+
+| Situation | Outcome |
+|---|---|
+| An edit names a clip, track or media that no longer exists | Usually a tolerated **no-op**: success, nothing changed, no undo step. Each command in [Edit commands](edits.md) says which |
+| A number is outside its range | **Clamped**, not refused. Scale 100 lands at 8; start -2 lands at 0 |
+| A number is NaN or infinite | `refused` |
+| A field has the wrong type, or the `op` / `method` is unknown | `invalid` |
+| A file cannot be probed, read or written | `failed` |
+
+---
+
+## Concurrency
+
+- The dispatcher handles **one request at a time**, in order, like the
+ window's event loop.
+- Long work is a job, so a request never waits on a render.
+- The socket server queues every caller through that one thread.
+- Responses on one connection come back in the order the requests were
+ sent. The envelope's `id` lets you tell them apart anyway.
+
+---
+
+## Embedding in Rust
+
+The dispatcher and the server are ordinary workspace crates.
+
+```rust
+use std::sync::Arc;
+use concat_api::{Api, Event, Request, Response};
+
+let mut api = Api::new(Arc::new(|event: Event| {
+ println!("{}", serde_json::to_string(&event).unwrap());
+}))?;
+let response: Response = api.dispatch(Request::ProjectList);
+api.finish(); // wait for running jobs before dropping it
+```
+
+| Need | Use |
+|---|---|
+| Your own config and data folders (tests, embedders) | `Api::with_dirs(dirs, sink)` |
+| The API on sockets, with a token | `concat_server::Server::start(config, Api::new)` |
+| Calling the served API from the same process | `Server::hub()` |
+
+`Api` is not `Send`: it lives on one thread. The event sink is called from
+job threads, so it must be `Send + Sync`. The window's Remote page is a
+`Server::start` from the settings sheet.
+
+---
+
+## App directories
+
+`version` reports two folders. Recents, settings and templates live in
+`config`; downloaded models and painted titles in `data`.
+
+| Platform | `config` | `data` |
+|---|---|---|
+| macOS | `~/Library/Application Support/app.concat.editor` | same folder |
+| Windows | `%APPDATA%\app.concat.editor` | same folder |
+| Linux | `~/.config/app.concat.editor` (or `$XDG_CONFIG_HOME/…`) | `~/.local/share/app.concat.editor` (or `$XDG_DATA_HOME/…`) |
+| Portable build | `portable/` beside the executable | same folder |
diff --git a/docs/api/types.md b/docs/api/types.md
new file mode 100644
index 00000000..650d9b25
--- /dev/null
+++ b/docs/api/types.md
@@ -0,0 +1,443 @@
+# Types
+
+**In one line:** the JSON shapes that requests carry and replies return.
+
+**On this page:** [Replies](#replies) · [The project model](#the-project-model)
+· [Media](#media) · [Catalogue](#catalogue) · [Templates](#templates) ·
+[Events](#events) · [Errors](#errors)
+
+Every field is camelCase. A field marked *optional* may be absent from a
+reply; a request may leave it out.
+
+---
+
+## Replies
+
+### VersionInfo
+
+Reply to `version`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `apiVersion` | string | The contract, e.g. `"0.2"` |
+| `concat` | string | The build's version |
+| `dirs` | `{config, data}` | The app's directories, as paths |
+| `capabilities` | string[] | See [overview](overview.md#versioning-and-capabilities) |
+
+### EditorView
+
+Reply to every method that opens or changes a project.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `project` | *Project* | The whole project |
+| `canUndo` | bool | There is something to undo |
+| `canRedo` | bool | There is something to redo |
+| `settings` | `{name, width, height, rateNum, rateDen}` | The project's name and the active timeline's frame and rate |
+| `createdId` | string | *optional*. The id the command just minted |
+
+```json
+{
+ "project": { "…": "see Project" },
+ "canUndo": true,
+ "canRedo": false,
+ "settings": {"name":"Reel","width":1920,"height":1080,"rateNum":30,"rateDen":1},
+ "createdId": "c2"
+}
+```
+
+### ProjectInfo
+
+One entry of `project.list`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `path` | string | The project folder |
+| `name` | string | The name in the title bar |
+| `width`, `height` | integer | Output size |
+| `rateNum`, `rateDen` | integer | Frame rate as a fraction |
+| `openedAt` | integer | Milliseconds since the epoch |
+
+### Started
+
+Reply to `export.run`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `job` | string | `"j1"`, `"j2"`, … Every event about this job carries it |
+| `path` | string | The project folder |
+| `output` | string | The file it will write |
+
+### Written
+
+Reply to `preview.frame` with `output`.
+
+| Field | Type |
+|---|---|
+| `path` | string, the file written |
+| `width`, `height` | integer |
+
+### Picture
+
+Reply to `preview.frame` without `output`.
+
+| Field | Type |
+|---|---|
+| `width`, `height` | integer |
+| `png` | string, the PNG as base64 (standard alphabet, padded) |
+
+### Done
+
+`{}`. The reply of methods with nothing to say beyond having worked.
+
+---
+
+## The project model
+
+What `project.get` returns as `project`, and what `project.document` writes
+to `concat.json` (plus a compatibility mirror; see
+[`project.document`](methods.md#projectdocument)).
+
+### Project
+
+| Field | Type | Meaning |
+|---|---|---|
+| `media` | *MediaItem*[] | The bin, shared by all timelines |
+| `fonts` | `{family, path}`[] | Fonts added from disk |
+| `timelines` | *Timeline*[] | In tab order. Always at least one |
+| `activeTimelineId` | string | The timeline commands act on |
+
+### Timeline
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | `"TL1"` for the first, `"tl…"` after |
+| `name` | string | The tab label |
+| `video` | *VideoSettings* | This timeline's frame and rate |
+| `tracks` | *Track*[] | Top to bottom. Never empty |
+| `clips` | *Clip*[] | In insertion order, **not** time order; sort by `start` yourself |
+
+### VideoSettings
+
+| Field | Type | Meaning |
+|---|---|---|
+| `width`, `height` | integer | Frame size in pixels |
+| `rateNum`, `rateDen` | integer | Frame rate as a fraction: 30 fps is `30/1`, 29.97 is `30000/1001` |
+
+### Track
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | `"T1"`–`"T4"` on the first timeline, `"t…"` after |
+| `visible` | bool | Video on this track reaches the composite |
+| `muted` | bool | Audio on this track is silent |
+
+### Clip
+
+A clip as `project.get` returns it. Fields with a default are left out of
+the JSON when they hold it.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | `"c…"`. Survives splits (the head keeps it) and merges |
+| `trackId` | string | The lane |
+| `mediaId` | string | Empty for a text or layer clip |
+| `name` | string | Display label |
+| `kind` | string | `video`, `audio`, `image`, `text`, `layer` |
+| `start` | number | Seconds from the start of the timeline |
+| `duration` | number | Seconds on the timeline. Never below 1/60 |
+| `sourceStart` | number | In-point: seconds into the media |
+| `volume` | number | Linear gain, 1 is unity |
+| `fadeIn`, `fadeOut` | number | Audio ramp seconds |
+| `scale` | number | Multiplier over the fitted size |
+| `offsetX`, `offsetY` | number | Fractions of frame width / height from centred |
+| `rotation` | number | Degrees, clockwise |
+| `stretchX`, `stretchY` | number | *optional*, default 1 |
+| `opacity` | number | 0..1 |
+| `speed` | number | Playback rate; the curve's mean when a curve is set |
+| `speedCurve` | *SpeedPoint*[] | *optional* |
+| `reverse` | bool | *optional* |
+| `animationIn`, `animationOut`, `animationCombo`, `animationLoop` | `{preset, duration}` | *optional* |
+| `keys` | *ClipKey*[] | *optional*. User keyframes, sorted by property then `at` |
+| `flipH`, `flipV` | bool | *optional* |
+| `blend` | string | *optional*. `multiply`, `screen`, `add`, `lighten`, `darken`; absent is normal |
+| `crop` | *Crop* | *optional* |
+| `cutout` | *Cutout* | *optional* |
+| `preservePitch` | bool | Keep pitch when speed ≠ 1 |
+| `filters` | *AppliedFilter*[] | Audio chain, in order |
+| `videoEffects` | *AppliedFilter*[] | Video chain, in order |
+| `audioStream` | integer | *optional*. Which audio stream of the media plays |
+| `muted` | bool | *optional*. True when the sound is detached |
+| `detachedFrom` | string | *optional*. On a detached audio clip: the video it came from |
+| `transitionIn` | *Transition* | *optional* |
+| `text` | *TextStyle* | *optional*. Present on a text clip |
+
+A clip fresh from `addClip`:
+
+```json
+{"id":"c2","trackId":"T1","mediaId":"m1","name":"take1.mp4","kind":"video","start":0.0,"duration":6.12,"sourceStart":0.0,"volume":1.0,"fadeIn":0.0,"fadeOut":0.0,"scale":1.0,"offsetX":0.0,"offsetY":0.0,"rotation":0.0,"opacity":1.0,"speed":1.0,"preservePitch":true,"filters":[],"videoEffects":[]}
+```
+
+### MediaItem
+
+One entry of the bin. The probe's findings are stored, so a project opens
+meaningfully even when the file is missing.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | `"m…"`, never re-issued |
+| `path` | string | Absolute path. Also the duplicate check |
+| `name` | string | Display name, normally the file's basename |
+| `duration` | number | *optional*. Seconds, when the container says |
+| `kind` | string | `video`, `audio`, `image` |
+| `width`, `height` | integer | *optional* |
+| `frameRate` | number | *optional*. Decimal, for display |
+| `frameRateFraction` | string | *optional*. Exact, e.g. `"30000/1001"` |
+| `videoCodec`, `audioCodec` | string | *optional* |
+| `hasAudio` | bool | The file carries sound |
+| `audioTracks` | *AudioTrack*[] | *optional*. Every audio stream, in file order |
+| `placeholder` | bool | *optional*. True for a template slot |
+
+### AudioTrack
+
+| Field | Type |
+|---|---|
+| `index` | integer, the stream's index in the file |
+| `codec` | string |
+| `channels` | integer |
+| `sampleRate` | integer |
+| `title` | string, *optional* |
+| `language` | string, *optional* |
+
+### AppliedFilter
+
+One link of an effect chain, in `filters` or `videoEffects`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | A package id from `catalogue.list`, e.g. `"concat.gaussian-blur"` |
+| `params` | object | Parameter key → number. Missing keys mean the package's defaults |
+| `enabled` | bool | *optional*, default `true`. False bypasses without losing settings |
+| `keys` | object | *optional*. Parameter key → *ParamKey*[] (`{at, value, ease}`) for animated parameters |
+
+```json
+{"id":"concat.gaussian-blur","params":{"radius":4},"enabled":true}
+```
+
+Every parameter is stored as a number, whatever its `type` in the
+catalogue: a `bool` is 0 or 1, an `enum` is one of its `values`, a `color`
+is packed RGBA, a `point` is two keys `<key>.x` and `<key>.y` in 0..1.
+
+### Transition
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | A transition package id, e.g. `"concat.dissolve"`, `"concat.push"`, `"concat.clock-wipe"` |
+| `duration` | number | Seconds, default 1 |
+
+### TextStyle
+
+A title's styling. Sizes are **fractions of the frame**, so a title made at
+1080p exports right at 4K. In a command you send only the fields you
+change; the rest take these defaults.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `content` | string | `"Your text"` | The words, newlines included |
+| `fontFamily` | string | `"\"Cabinet Grotesk\""` | CSS-style family name, quoted where needed. May name an added font |
+| `fontSize` | number | 0.09 | Cap height as a fraction of frame height |
+| `fontWeight` | number | 700 | 100..=900 |
+| `italic` | bool | false | |
+| `color` | string | `"#ffffff"` | CSS hex |
+| `align` | string | `"center"` | `left`, `center`, `right`. Also which point of the block the clip's position pins |
+| `opacity` | number | 1 | 0..=1, multiplied with the clip's |
+| `strokeWidth` | number | 0 | Outline as a fraction of frame height; 0 is none |
+| `strokeColor` | string | `"#000000"` | |
+| `shadow` | bool | true | A drop shadow |
+| `background` | string | `""` | A plate colour behind the text; empty is none |
+| `lineHeight` | number | 1.2 | Multiple of the font size; floored at 0.5 |
+| `tracking` | number | 0 | Extra letter spacing, in frame-height fractions |
+| `maxWidth` | number | 0 | Wrap width as a fraction of frame width; 0 is no wrap |
+| `maxHeight` | number | 0 | Box height as a fraction of frame height; 0 is the words' own |
+
+### Crop
+
+Fractions of the source taken off each edge: `{left, top, right, bottom}`,
+each 0..=0.9, with at least a tenth of the picture left.
+
+### Cutout
+
+| Field | Type | Meaning |
+|---|---|---|
+| `mode` | string | `auto` (the model's mask) or `custom` (the mask plus strokes) |
+| `subject` | string | *optional*, default `auto`. `person`, `object`, or `auto` (person if found, else object) |
+| `feather` | number | Edge softness as a fraction of picture width |
+| `strokes` | *Stroke*[] | *optional*. Corrections, in order |
+
+### Stroke
+
+| Field | Type | Meaning |
+|---|---|---|
+| `tool` | string | `smartBrush`, `brush`, `smartEraser`, `eraser` |
+| `size` | number | Diameter as a fraction of picture width |
+| `points` | `[x, y]`[] | Fractions of the source picture, `[0, 0]` top-left |
+| `at` | number | *optional*. Source second the stroke was painted at |
+
+### ClipKey
+
+| Field | Type | Meaning |
+|---|---|---|
+| `property` | string | `scale`, `offsetX`, `offsetY`, `rotation`, `opacity`, `volume` |
+| `at` | number | 0..=1 of the clip's length |
+| `value` | number | In the property's own units |
+| `ease` | `[x1, y1, x2, y2]` | A cubic bezier; default linear `[0, 0, 1, 1]` |
+
+### SpeedPoint
+
+`{at, speed}`: `at` a fraction 0..=1 of the clip, `speed` source seconds
+per timeline second there.
+
+### NewMedia
+
+A probed file, as `addMedia`, `fillSlot`, `replaceClipMedia` and
+`freezeFrame` take it. The same fields as *MediaItem* minus `id` and
+`placeholder`: `path`, `name`, `duration`, `kind`, `width`, `height`,
+`frameRate`, `frameRateFraction`, `videoCodec`, `audioCodec`, `hasAudio`,
+`audioTracks`.
+
+> [!TIP]
+> Build one from a `media.probe` reply: copy `path`, `duration`, `kind`
+> and `audioTracks`; take `width`, `height`, `frameRate`,
+> `frameRateFraction` and `videoCodec` from its `video`; `audioCodec`
+> from its `audio`; `hasAudio` is whether `audio` is present; `name` is
+> the file's basename. Or skip all that with `media.import`.
+
+---
+
+## Media
+
+### MediaSummary
+
+Reply to `media.probe`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `path` | string | The file, as given |
+| `duration` | number | *optional*. Container duration in seconds |
+| `kind` | string | `video`, `audio`, `image` |
+| `video` | *VideoStreamInfo* | *optional*. The first video stream |
+| `audio` | *AudioStreamInfo* | *optional*. The first audio stream, what a clip plays unless it names another |
+| `audioTracks` | *AudioStreamInfo*[] | Every audio stream, in file order |
+
+**VideoStreamInfo:** `index`, `codec`, `width`, `height`, `frameRate`
+(decimal), `frameRateFraction` (exact, e.g. `"30/1"`).
+
+**AudioStreamInfo:** `index`, `codec`, `sampleRate`, `channels`, `title`,
+`language`.
+
+---
+
+## Catalogue
+
+### PackageInfo
+
+One entry of `catalogue.list`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | `author.name`, e.g. `"concat.gaussian-blur"`. What a chain stores |
+| `name` | string | The catalogue card's title |
+| `kind` | string | `effect`, `filter`, `audio`, `transition`, `generator` |
+| `category` | string | The shelf the card sits on |
+| `description` | string | One sentence |
+| `intensity` | string | *optional*. The parameter the simple view shows as its one slider |
+| `params` | *ParamInfo*[] | In inspector order |
+
+### ParamInfo
+
+| Field | Type | Meaning |
+|---|---|---|
+| `key` | string | What `params` stores it under |
+| `label` | string | The control's label |
+| `type` | string | `float`, `int`, `bool`, `enum`, `color`, `point` |
+| `min`, `max` | number | The range |
+| `default` | number | The value an untouched control means |
+| `step` | number | Slider increment; 0 is continuous |
+| `unit` | string | Shown after the number |
+| `animate` | bool | Can carry keyframes |
+| `values` | number[] | For `enum`: the values the document may hold |
+| `labels` | string[] | For `enum`: the name of each value, in `values` order |
+
+---
+
+## Templates
+
+### TemplateInfo
+
+| Field | Type | Meaning |
+|---|---|---|
+| `path` | string | The bundle folder. What `template.instantiate` takes |
+| `name` | string | |
+| `width`, `height` | integer | Output size |
+| `rateNum`, `rateDen` | integer | Frame rate |
+| `slots` | *SlotInfo*[] | In the order they first appear on the timeline |
+| `hasPoster` | bool | The bundle carries `poster.jpg` |
+
+### SlotInfo
+
+| Field | Type | Meaning |
+|---|---|---|
+| `mediaId` | string | The placeholder's id. What a fill names |
+| `name` | string | As the creator labelled it |
+| `kind` | string | `video`, `audio`, `image`: what the slot wants |
+| `seconds` | number | Timeline seconds the slot covers |
+
+---
+
+## Events
+
+Every event carries `job` and `path`. As a bare object the tag is `event`;
+in the JSON-RPC envelope the tag becomes the notification's `method` and
+the rest its `params`.
+
+### `cutout.progress`
+
+| Field | Type | Meaning |
+|---|---|---|
+| `mediaId` | string | The media being analysed |
+| `fetching` | bool | True while a model downloads, false while it runs |
+| `fraction` | number | 0..=1 |
+
+### `export.progress`
+
+| Field | Type | Meaning |
+|---|---|---|
+| `frame` | integer | Frames done |
+| `total` | integer | Frames in total |
+| `stage` | string | `video`, `audio`, `mux` |
+
+### `export.done`
+
+| Field | Type |
+|---|---|
+| `output` | string, the file written |
+| `width`, `height` | integer |
+
+### `export.failed`
+
+| Field | Type |
+|---|---|
+| `error` | *ApiError*; `code` is `cancelled` when `export.cancel` stopped it |
+
+---
+
+## Errors
+
+### ApiError
+
+| Field | Type | Meaning |
+|---|---|---|
+| `code` | string | One of the codes in the [overview](overview.md#errors) |
+| `message` | string | The sentence a person would be shown |
+
+In the JSON-RPC envelope: `{"code": <number>, "message": "…", "data": {"code": "<name>"}}`.
diff --git a/docs/recipes.md b/docs/recipes.md
new file mode 100644
index 00000000..2954e96f
--- /dev/null
+++ b/docs/recipes.md
@@ -0,0 +1,265 @@
+# Recipes
+
+**In one line:** copy-paste scripts for the things people most often want
+from the API.
+
+Each recipe is shown two ways where it makes sense: as **lines** for
+`concat-cli api` (paste into a `.jsonl` file, or type one at a time), and
+as **Python** against a socket using the `Concat` class from
+[JSON-RPC → Python client](transports/json-rpc.md#a-minimal-python-client).
+
+**Recipes:** [Rough cut from a folder](#1-rough-cut-from-a-folder-of-clips)
+· [Export and show progress](#2-export-and-show-progress) ·
+[A title card](#3-a-title-card) · [A look on every clip](#4-a-look-on-every-clip)
+· [Contact sheet of frames](#5-a-contact-sheet-of-frames) ·
+[A project from a template](#6-a-project-from-a-template) ·
+[Vertical cut of a landscape edit](#7-a-vertical-cut-of-a-landscape-edit) ·
+[Undo, redo, save](#8-undo-redo-save) · [Inspect a project](#9-inspect-a-project-without-changing-it)
+
+Run the CLI from the `src/` folder: `cargo run -p concat-cli -- api < file.jsonl`.
+
+---
+
+## 1. Rough cut from a folder of clips
+
+Import every file and lay them end to end on the first track.
+
+**Lines** (two files shown; repeat the pattern):
+
+```jsonl
+{"jsonrpc":"2.0","id":1,"method":"project.create","params":{"location":"/edits","name":"Rough cut"}}
+{"jsonrpc":"2.0","id":2,"method":"media.import","params":{"path":"/edits/Rough cut","file":"/footage/a.mp4"}}
+{"jsonrpc":"2.0","id":3,"method":"media.import","params":{"path":"/edits/Rough cut","file":"/footage/b.mp4"}}
+{"jsonrpc":"2.0","id":4,"method":"edit.apply","params":{"path":"/edits/Rough cut","command":{"op":"addClip","mediaId":"m1","trackId":"T1","start":0}}}
+{"jsonrpc":"2.0","id":5,"method":"project.get","params":{"path":"/edits/Rough cut"}}
+```
+
+Read the clip's `duration` from the `project.get` reply, then place the
+next clip at that `start`. Python does the bookkeeping:
+
+```python
+import glob, os
+c = Concat(token=TOKEN)
+folder = "/edits/Rough cut"
+c.call("project.create", location="/edits", name="Rough cut")
+
+at = 0.0
+for file in sorted(glob.glob("/footage/*.mp4")):
+ view = c.call("media.import", path=folder, file=file)
+ media_id = view["createdId"]
+ view = c.call("edit.apply", path=folder,
+ command={"op": "addClip", "mediaId": media_id, "trackId": "T1", "start": at})
+ clip = next(cl for cl in view["project"]["timelines"][0]["clips"] if cl["id"] == view["createdId"])
+ at += clip["duration"]
+
+c.call("project.save", path=folder)
+```
+
+> [!TIP]
+> `media.import` on a file already in the bin is a no-op and returns no
+> `createdId`. Look the id up in `project.media` by `path` if you re-run.
+
+---
+
+## 2. Export and show progress
+
+**Lines:**
+
+```jsonl
+{"jsonrpc":"2.0","id":1,"method":"project.open","params":{"path":"/edits/Reel"}}
+{"jsonrpc":"2.0","id":2,"method":"export.run","params":{"path":"/edits/Reel","output":"/edits/reel.mp4","crf":18,"preset":"slow","codec":"h264"}}
+```
+
+The CLI keeps running until the job ends, printing each event.
+
+**Python**, with a progress line:
+
+```python
+def show(event):
+ p = event["params"]
+ if event["method"] == "export.progress":
+ print(f'\r{p["stage"]:5} {p["frame"]}/{p["total"]}', end="")
+ elif event["method"] == "cutout.progress":
+ print(f'\rcutout {p["mediaId"]} {"fetching" if p["fetching"] else "analysing"} {p["fraction"]:.0%}', end="")
+
+c = Concat(token=TOKEN, on_event=show)
+c.call("project.open", path="/edits/Reel")
+started = c.call("export.run", path="/edits/Reel", output="/edits/reel.mp4", crf=18)
+end = c.wait_for_job(started["job"])
+print()
+if end["method"] == "export.done":
+ print("wrote", end["params"]["output"])
+else:
+ print("failed:", end["params"]["error"]["message"])
+```
+
+To stop it from another connection:
+
+```json
+{"jsonrpc":"2.0","id":9,"method":"export.cancel","params":{"job":"j1"}}
+```
+
+The job then ends with `export.failed` and `error.code` = `cancelled`.
+
+---
+
+## 3. A title card
+
+A three-second title on its own lane above the footage, then a lower
+third.
+
+```jsonl
+{"jsonrpc":"2.0","id":1,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addTextClip","above":true,"start":0,"duration":3,"style":{"content":"Summer 2026","fontSize":0.14}}}}
+{"jsonrpc":"2.0","id":2,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addTextClip","above":true,"start":5,"duration":4,"offsetY":0.35,"style":{"content":"Ada Lovelace\nEngine designer","fontSize":0.05,"align":"left","background":"#00000099","maxWidth":0.5}}}}
+```
+
+Only the style fields you set change; the rest are the window's defaults
+(white, bold, centred, with a shadow). All of them are in
+[Types → TextStyle](api/types.md#textstyle).
+
+Change a title later with a patch. Absent fields stay, `null` clears:
+
+```json
+{"op":"updateClip","clipId":"c7","patch":{"text":{"content":"Summer 2026","color":"#ffcc00"}}}
+```
+
+---
+
+## 4. A look on every clip
+
+Find a filter, then set it on each video clip.
+
+```python
+looks = c.call("catalogue.list", kind="filter")
+print([p["id"] for p in looks]) # e.g. concat.warm, concat.film, concat.black-white …
+
+view = c.call("project.get", path="/edits/Reel")
+timeline = next(t for t in view["project"]["timelines"] if t["id"] == view["project"]["activeTimelineId"])
+commands = [
+ {"op": "updateClip", "clipId": clip["id"],
+ "patch": {"videoEffects": clip["videoEffects"] + [{"id": "concat.film", "params": {}}]}}
+ for clip in timeline["clips"] if clip["kind"] == "video"
+]
+c.call("edit.apply", path="/edits/Reel", command={"op": "batch", "commands": commands})
+```
+
+Notes:
+
+- `videoEffects` in a patch **replaces** the chain, so append to what the
+ clip has.
+- Empty `params` means the package's defaults. The keys and ranges are in
+ the `catalogue.list` reply.
+- One `batch` means one undo step for the whole pass.
+
+The same over everything at once, as a layer instead of per clip:
+
+```json
+{"op":"addLayerClip","start":0,"duration":60,"effectId":"concat.film","name":"Film look"}
+```
+
+---
+
+## 5. A contact sheet of frames
+
+One PNG a second, to a folder.
+
+```python
+view = c.call("project.open", path="/edits/Reel")
+timeline = next(t for t in view["project"]["timelines"] if t["id"] == view["project"]["activeTimelineId"])
+length = max((cl["start"] + cl["duration"] for cl in timeline["clips"]), default=0)
+
+t = 0.0
+while t < length:
+ c.call("preview.frame", path="/edits/Reel", time=t, output=f"/edits/frames/{t:06.1f}.png", width=320, height=180)
+ t += 1.0
+```
+
+Or one frame straight into memory:
+
+```python
+import base64
+pic = c.call("preview.frame", path="/edits/Reel", time=2.5)
+png_bytes = base64.b64decode(pic["png"])
+```
+
+---
+
+## 6. A project from a template
+
+```python
+templates = c.call("template.list")
+intro = next(t for t in templates if t["name"] == "Intro")
+for slot in intro["slots"]:
+ print(slot["mediaId"], slot["name"], slot["kind"], f'{slot["seconds"]:.1f}s')
+
+fills = [
+ {"mediaId": intro["slots"][0]["mediaId"], "file": "/footage/logo.png"},
+ {"mediaId": intro["slots"][1]["mediaId"], "file": "/footage/take1.mp4"},
+]
+view = c.call("template.instantiate", template=intro["path"], location="/edits", name="My intro", fills=fills)
+```
+
+Every slot must be filled, and every file is probed before anything is
+made. To make a template from a project you have open:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"template.save","params":{"path":"/edits/Reel","name":"Reel template"}}
+```
+
+---
+
+## 7. A vertical cut of a landscape edit
+
+A second timeline in the same project, 1080×1920, with the same clips
+re-framed.
+
+```jsonl
+{"jsonrpc":"2.0","id":1,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addTimeline"}}}
+{"jsonrpc":"2.0","id":2,"method":"project.setVideo","params":{"path":"/edits/Reel","video":{"width":1080,"height":1920,"rateNum":30,"rateDen":1}}}
+{"jsonrpc":"2.0","id":3,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addClipAtFirstFree","mediaId":"m1","start":0}}}
+{"jsonrpc":"2.0","id":4,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"setClipTransform","clipId":"c9","scale":1.8,"offsetX":-0.1}}}
+{"jsonrpc":"2.0","id":5,"method":"export.run","params":{"path":"/edits/Reel","output":"/edits/reel-vertical.mp4"}}
+```
+
+`addTimeline` makes the new timeline active, so the `project.setVideo`
+and the edits that follow land on it. Switch back with
+`{"op":"selectTimeline","timelineId":"TL1"}`. The clip id `c9` above is
+whatever `createdId` came back from the add.
+
+---
+
+## 8. Undo, redo, save
+
+```jsonl
+{"jsonrpc":"2.0","id":1,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"removeClips","clipIds":["c2"],"ripple":true}}}
+{"jsonrpc":"2.0","id":2,"method":"edit.undo","params":{"path":"/edits/Reel"}}
+{"jsonrpc":"2.0","id":3,"method":"edit.redo","params":{"path":"/edits/Reel"}}
+{"jsonrpc":"2.0","id":4,"method":"project.save","params":{"path":"/edits/Reel"}}
+{"jsonrpc":"2.0","id":5,"method":"project.close","params":{"path":"/edits/Reel"}}
+```
+
+Every reply's `canUndo` / `canRedo` tells you where the history stands.
+A tolerated no-op (an unknown id, a value already held) records no undo
+step.
+
+---
+
+## 9. Inspect a project without changing it
+
+```sh
+cd src
+cargo run -p concat-cli -- api '{"method":"project.open","path":"/edits/Reel"}' | python3 -c '
+import json, sys
+view = json.loads(sys.stdin.readline())["result"]
+p = view["project"]
+print(view["settings"])
+for t in p["timelines"]:
+ print(t["id"], t["name"], f'{t["video"]["width"]}x{t["video"]["height"]}')
+ for clip in sorted(t["clips"], key=lambda c: c["start"]):
+ print(f' {clip["id"]:5} {clip["kind"]:5} {clip["start"]:7.2f} +{clip["duration"]:6.2f} {clip["name"]}')
+'
+```
+
+Opening does not change the project document; nothing in the folder is
+written unless you call `project.save`. The only side effect is the
+recents list, which moves the project to the front.
diff --git a/docs/transports/grpc.md b/docs/transports/grpc.md
new file mode 100644
index 00000000..679121fe
--- /dev/null
+++ b/docs/transports/grpc.md
@@ -0,0 +1,191 @@
+# gRPC
+
+**In one line:** the same API over HTTP/2 with generated clients. Two
+RPCs, `Call` and `Events`, carrying the API's JSON as text.
+
+**On this page:** [Build and run](#build-and-run) · [The service](#the-service)
+· [The token](#the-token) · [Errors](#errors) · [Try it with grpcurl](#try-it-with-grpcurl)
+· [Clients](#clients) · [Why an envelope](#why-an-envelope-and-not-a-second-schema)
+
+---
+
+## Build and run
+
+gRPC is behind the `grpc` feature. It is off by default because it brings
+tokio and hyper, which nothing else in the workspace needs. CI builds and
+tests it on every change.
+
+```sh
+cd src
+cargo run -p concat-cli --features grpc -- serve --grpc 127.0.0.1:7421
+```
+
+```
+Concat API 0.2: gRPC on 127.0.0.1:7421
+Concat API 0.2: token 3f9c1e…
+```
+
+`--grpc` combines with `--json` and `--socket`; all callers share one
+dispatcher. A build without the feature refuses `--grpc` with a message
+saying so.
+
+> [!NOTE]
+> The window's Remote page serves JSON-RPC only. For gRPC, run
+> `concat-cli serve`.
+
+---
+
+## The service
+
+`src/crates/concat-server/proto/concat.proto`, package `concat.v1`:
+
+```proto
+service Concat {
+ rpc Call (Request) returns (Response); // one call, one response
+ rpc Events (EventsRequest) returns (stream Event); // every job's events, while open
+}
+
+message Request { string method = 1; string params = 2; } // params: JSON text, or empty
+message Response { oneof outcome { string result = 1; Error error = 2; } }
+message Error { string code = 1; int32 number = 2; string message = 3; }
+message EventsRequest {}
+message Event { string event = 1; string params = 2; } // params: JSON text
+```
+
+| Field | Holds |
+|---|---|
+| `Request.method` | The method name, e.g. `"edit.apply"` |
+| `Request.params` | The params object as JSON text. Empty for a method with none |
+| `Response.result` | The reply as JSON text: exactly what a JSON-RPC `result` holds |
+| `Response.error` | `code` is the API's name (`notOpen`, …), `number` its JSON-RPC number, `message` the sentence |
+| `Event.event` | `"export.progress"`, … |
+| `Event.params` | Its fields as JSON text |
+
+Everything in [Methods](../api/methods.md), [Edit commands](../api/edits.md)
+and [Types](../api/types.md) applies unchanged. Parse `result` and
+`params` with your JSON library.
+
+---
+
+## The token
+
+Every call carries the server's token as bearer metadata:
+
+```
+authorization: Bearer 3f9c1e…
+```
+
+Missing or wrong: the RPC fails with status `UNAUTHENTICATED`. This
+applies to `Events` too. The comparison is constant-time. Where the token
+comes from is in [JSON-RPC → The token](json-rpc.md#the-token).
+
+---
+
+## Errors
+
+Two layers, deliberately kept apart:
+
+| Layer | Means | Looks like |
+|---|---|---|
+| gRPC status | the transport refused | `UNAUTHENTICATED` (token), `INTERNAL` (the server could not run the call at all) |
+| `Response.error` | the API refused | `{code: "notOpen", number: -32001, message: "…"}` with the call itself returning `OK` |
+
+So a `Call` that returns `OK` still needs its `outcome` checked.
+
+---
+
+## Try it with grpcurl
+
+There is no reflection service; hand grpcurl the proto.
+
+```sh
+PROTO=src/crates/concat-server/proto/concat.proto
+TOKEN=3f9c1e…
+
+grpcurl -plaintext -proto $PROTO -H "authorization: Bearer $TOKEN" \
+ -d '{"method":"version","params":""}' \
+ 127.0.0.1:7421 concat.v1.Concat/Call
+```
+
+```json
+{"result": "{\"apiVersion\":\"0.2\",\"concat\":\"0.2.3\",\"dirs\":{…},\"capabilities\":[\"events\",\"grpc\"]}"}
+```
+
+An edit:
+
+```sh
+grpcurl -plaintext -proto $PROTO -H "authorization: Bearer $TOKEN" \
+ -d '{"method":"edit.apply","params":"{\"path\":\"/edits/Reel\",\"command\":{\"op\":\"addTrack\"}}"}' \
+ 127.0.0.1:7421 concat.v1.Concat/Call
+```
+
+Events, streamed until you stop it:
+
+```sh
+grpcurl -plaintext -proto $PROTO -H "authorization: Bearer $TOKEN" \
+ -d '{}' 127.0.0.1:7421 concat.v1.Concat/Events
+```
+
+---
+
+## Clients
+
+### Rust
+
+The generated client ships in the crate under the feature:
+
+```rust
+use concat_server::grpc::proto::{concat_client::ConcatClient, Request as Call, EventsRequest};
+use tonic::Request;
+
+let mut client = ConcatClient::connect("http://127.0.0.1:7421").await?;
+let mut request = Request::new(Call { method: "version".into(), params: String::new() });
+request.metadata_mut().insert("authorization", format!("Bearer {token}").parse()?);
+let response = client.call(request).await?.into_inner();
+```
+
+### Python
+
+```sh
+pip install grpcio grpcio-tools
+python -m grpc_tools.protoc -I src/crates/concat-server/proto \
+ --python_out=. --grpc_python_out=. concat.proto
+```
+
+```python
+import json, grpc, concat_pb2, concat_pb2_grpc
+
+channel = grpc.insecure_channel("127.0.0.1:7421")
+stub = concat_pb2_grpc.ConcatStub(channel)
+meta = [("authorization", f"Bearer {TOKEN}")]
+
+def call(method, **params):
+ req = concat_pb2.Request(method=method, params=json.dumps(params) if params else "")
+ res = stub.Call(req, metadata=meta)
+ if res.HasField("error"):
+ raise RuntimeError(f"{res.error.code}: {res.error.message}")
+ return json.loads(res.result)
+
+print(call("version")["capabilities"])
+for event in stub.Events(concat_pb2.EventsRequest(), metadata=meta):
+ print(event.event, json.loads(event.params))
+```
+
+### Anything else
+
+Any language with a protobuf and gRPC toolchain: generate from
+`concat.proto`, send the bearer, parse the JSON text.
+
+---
+
+## Why an envelope and not a second schema
+
+The protobuf carries JSON text rather than typed messages on purpose:
+
+- A method added to the API reaches gRPC with **no change** to the proto.
+- There is **one set of docs** for every transport.
+- Both transports parse requests through the same code, so they refuse
+ the same things the same way.
+
+What gRPC adds over the line transport is HTTP/2, generated clients, and
+a streamed reply for events.
diff --git a/docs/transports/json-rpc.md b/docs/transports/json-rpc.md
new file mode 100644
index 00000000..6f135327
--- /dev/null
+++ b/docs/transports/json-rpc.md
@@ -0,0 +1,243 @@
+# JSON-RPC
+
+**In one line:** one JSON object per line, in and out, over stdin, TCP or a
+Unix socket. The same lines everywhere.
+
+**On this page:** [The envelope](#the-envelope) · [Over stdin](#over-stdin-concat-cli-api)
+· [Over a socket](#over-a-socket-concat-cli-serve) · [From the window](#from-the-window)
+· [The token](#the-token) · [Events](#events) · [Security](#security) ·
+[Python client](#a-minimal-python-client)
+
+---
+
+## The envelope
+
+A call, its response, and an event, as JSON-RPC 2.0:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"project.open","params":{"path":"/edits/Reel"}}
+```
+```json
+{"jsonrpc":"2.0","id":1,"result":{"project":{"…":"…"},"canUndo":false,"canRedo":false,"settings":{"…":"…"}}}
+```
+```json
+{"jsonrpc":"2.0","id":1,"error":{"code":-32001,"message":"/edits/Reel is not open - open it first","data":{"code":"notOpen"}}}
+```
+```json
+{"jsonrpc":"2.0","method":"export.progress","params":{"job":"j1","path":"/edits/Reel","frame":30,"total":150,"stage":"video"}}
+```
+
+Rules:
+
+| Rule | Detail |
+|---|---|
+| One object per line | Newline-delimited. No pretty printing across lines |
+| `id` is yours | A string, a number or null. It comes back as given. Anything else is `invalid` |
+| Every call is answered | Even one without an `id` (the reply's `id` is `null`) |
+| `params` is an object | The method's fields. Omit it for a method with none |
+| Errors carry two codes | `error.code` is the JSON-RPC number, `error.data.code` is the API's name. See [Errors](../api/overview.md#errors) |
+| Events are notifications | No `id`. `method` is the event's name, `params` its fields |
+
+> [!TIP]
+> **The bare shape is accepted too.** `{"method": "version"}` with no
+> envelope is the request as it is, and it is answered with `"id": null`.
+> Handy when typing by hand.
+
+---
+
+## Over stdin: `concat-cli api`
+
+From a source checkout:
+
+```sh
+cd src
+cargo run -p concat-cli -- api '{"method":"catalogue.list","kind":"filter"}' # one request
+cargo run -p concat-cli -- api < edits.jsonl # one call per line
+```
+
+How it behaves:
+
+- Reads a line, answers it, flushes. Blank lines are skipped.
+- Writes events between responses as they happen, never half a line.
+- A line that is not a call gets an error response; the loop goes on.
+- At end of input it **waits for running jobs**, so an export begun on
+ the last line still finishes and its events are written.
+
+No token, no socket. The process is yours.
+
+---
+
+## Over a socket: `concat-cli serve`
+
+```sh
+cd src
+cargo run -p concat-cli -- serve # JSON-RPC on 127.0.0.1:7420
+cargo run -p concat-cli -- serve --json 0.0.0.0:7420 # any interface (read Security first)
+cargo run -p concat-cli -- serve --socket /tmp/concat.sock # a Unix socket
+cargo run -p concat-cli -- serve --token "my secret" # your own token
+```
+
+It prints where it listens and the token to present, then serves until
+stopped:
+
+```
+Concat API 0.2: JSON-RPC on 127.0.0.1:7420
+Concat API 0.2: token 3f9c1e…
+```
+
+| Flag | Meaning |
+|---|---|
+| `--json ADDR` | TCP address for JSON-RPC lines. Default `127.0.0.1:7420` when nothing else is asked for |
+| `--socket PATH` | A Unix socket path (Unix only). A file already there is replaced |
+| `--grpc ADDR` | gRPC, in a build with the feature. See [gRPC](grpc.md) |
+| `--token TOKEN` | The token every connection presents. Also `CONCAT_API_TOKEN`. Minted when absent |
+
+Several flags at once serve on all of them. All callers share one
+dispatcher and its open projects.
+
+---
+
+## From the window
+
+**Settings › Remote** serves the same JSON-RPC lines while the editor is
+open.
+
+| Control | Meaning |
+|---|---|
+| **Serve the API** | The switch. Remembered across launches |
+| **Address** | Host and port. Default `127.0.0.1:7420` |
+| **Token** | Yours, or one the window mints and shows you when the field is empty |
+| Status line | "Listening on … · N connected", or why the bind failed |
+
+Edits made over the socket land in the same session the window shows.
+What you can do from the window, you can do from the socket, and the
+other way round.
+
+---
+
+## The token
+
+Every connection, **loopback included**, presents the token as its
+**first line**, as a call to `auth`:
+
+```json
+{"jsonrpc":"2.0","id":0,"method":"auth","params":{"token":"3f9c1e…"}}
+```
+```json
+{"jsonrpc":"2.0","id":0,"result":{}}
+```
+
+- Anything else first, or the wrong token: an `unauthorized` error and
+ the connection is closed.
+- `auth` is the transport's word, not the API's. It never reaches the
+ dispatcher and is not a method you call again.
+- The comparison is constant-time.
+- With no token configured, the server **mints one** (128 bits, 32 hex
+ digits) that only the process that started it knows: printed by
+ `concat-cli serve`, shown on the window's Remote page.
+
+Why loopback too: another user's process on the same machine reaches
+`127.0.0.1` as easily as yours does.
+
+---
+
+## Events
+
+Once authenticated, a connection receives **every** event from every job,
+whoever started it. Each names its `job` and `path`; keep the ones you
+asked for.
+
+Responses and events share one writer per connection, so a line is never
+interleaved with another. But an event can arrive **between** your call
+and its response. Read by `method` versus `id`, not by position:
+
+```
+you → {"jsonrpc":"2.0","id":7,"method":"project.get",...}
+ ← {"jsonrpc":"2.0","method":"export.progress","params":{...}} ← someone's job
+ ← {"jsonrpc":"2.0","id":7,"result":{...}} ← your answer
+```
+
+---
+
+## Security
+
+> [!WARNING]
+> The API reads and writes whatever paths it is given, as the user running
+> it. A server is a door into the machine.
+
+- **No encryption.** Bind off loopback only behind something that
+ provides it (an SSH tunnel, a reverse proxy with TLS).
+- The token gates the door; the network is the wall. Do not put the port
+ on the open internet.
+- Anyone with the token can create, edit and export projects and read any
+ file the server's user can read.
+
+---
+
+## A minimal Python client
+
+Standard library only. Handles the handshake, matches responses by `id`,
+and hands events to a callback.
+
+```python
+import json, socket, itertools
+
+class Concat:
+ def __init__(self, host="127.0.0.1", port=7420, token="", on_event=None):
+ self.sock = socket.create_connection((host, port))
+ self.reader = self.sock.makefile("r", encoding="utf-8")
+ self.ids = itertools.count(1)
+ self.on_event = on_event or (lambda e: None)
+ self._send({"jsonrpc": "2.0", "id": 0, "method": "auth", "params": {"token": token}})
+ self._wait(0)
+
+ def call(self, method, **params):
+ rid = next(self.ids)
+ self._send({"jsonrpc": "2.0", "id": rid, "method": method, "params": params})
+ return self._wait(rid)
+
+ def wait_for_job(self, job):
+ """Blocks until export.done / export.failed for `job`; returns the event."""
+ while True:
+ msg = self._read()
+ if "id" in msg:
+ continue # a response to something else; not expected here
+ self.on_event(msg)
+ if msg["params"].get("job") == job and msg["method"] in ("export.done", "export.failed"):
+ return msg
+
+ def _send(self, obj):
+ self.sock.sendall((json.dumps(obj) + "\n").encode("utf-8"))
+
+ def _read(self):
+ line = self.reader.readline()
+ if not line:
+ raise ConnectionError("server closed the connection")
+ return json.loads(line)
+
+ def _wait(self, rid):
+ while True:
+ msg = self._read()
+ if "id" not in msg:
+ self.on_event(msg) # an event; keep waiting
+ continue
+ if msg["id"] != rid:
+ continue # not ours; keep waiting
+ if "error" in msg:
+ raise RuntimeError(f'{msg["error"]["data"]["code"]}: {msg["error"]["message"]}')
+ return msg["result"]
+```
+
+Use it:
+
+```python
+c = Concat(token="3f9c1e…", on_event=lambda e: print(e["method"], e["params"]))
+print(c.call("version")["capabilities"])
+view = c.call("project.create", location="/edits", name="Reel")
+view = c.call("media.import", path="/edits/Reel", file="/footage/take1.mp4")
+c.call("edit.apply", path="/edits/Reel", command={"op": "addClipAtFirstFree", "mediaId": view["createdId"], "start": 0})
+started = c.call("export.run", path="/edits/Reel", output="/edits/reel.mp4")
+print(c.wait_for_job(started["job"]))
+```
+
+More in [Recipes](../recipes.md).
diff --git a/docs/transports/mcp.md b/docs/transports/mcp.md
new file mode 100644
index 00000000..6cdab2b8
--- /dev/null
+++ b/docs/transports/mcp.md
@@ -0,0 +1,148 @@
+# MCP
+
+**In one line:** an MCP server for Concat is planned and prototyped, not
+shipped. This page says what exists, what it should look like, and how to
+connect an agent today.
+
+**Status:** 🚧 not in this tree.
+
+**On this page:** [What exists](#what-exists) · [The shape it should take](#the-shape-it-should-take)
+· [Bridging today](#bridging-today) · [Guidance for agents](#guidance-for-agents)
+
+---
+
+## What exists
+
+| Thing | Where | State |
+|---|---|---|
+| The API an MCP server would expose | `concat-api` | ✅ Shipped. Every method in [Methods](../api/methods.md) |
+| A socket server with a token and event fan-out | `concat-server` | ✅ Shipped. [JSON-RPC](json-rpc.md), [gRPC](grpc.md) |
+| A prototype: the window serving MCP over Streamable HTTP with 17 tools, plus a stdio Python bridge | [PR #69](https://github.com/jub0t/Concat/pull/69) | ❌ Closed, not merged. It re-implemented the transport instead of reusing `concat-server` |
+| The request | [issue #95 "MCP support"](https://github.com/jub0t/Concat/issues/95) | Closed on 2026-09-19 with a pointer to the documentation issue [#123](https://github.com/jub0t/Concat/issues/123). The [roadmap](../../ROADMAP.MD) lists MCP integrations under the Concat API |
+
+The design direction, from the September 2026 audit: build the MCP server
+on the official Rust SDK (`rmcp`) over `concat-server`'s `Hub`, so it is a
+third transport beside JSON-RPC and gRPC and not a second API.
+
+---
+
+## The shape it should take
+
+The API is already close to a tool set. The intended mapping:
+
+| MCP concept | Concat |
+|---|---|
+| A **tool** | One API method. `project.open`, `edit.apply`, `export.run`, … Names, params and results as in [Methods](../api/methods.md) |
+| A tool's **input schema** | The method's params. For `edit.apply`, the `command` union in [Edit commands](../api/edits.md) |
+| A tool **result** | The reply payload as JSON; a `preview.frame` reply as an image content block |
+| A **notification** / progress | The job events: `export.progress`, `export.done`, `export.failed`, `cutout.progress` |
+| A **resource** | `concat://project/<path>` for `project.get`; the catalogue as `concat://catalogue` |
+| **Auth** | The same token `concat-server` mints, as a bearer |
+
+Principles that carry over from the other transports:
+
+- **No new meaning in the transport.** A tool calls a method; it does not
+ interpret the edit.
+- **Refusals are the window's sentences.** An agent that hits `refused`
+ can show or reason about the message as it is.
+- **Discover, don't assume.** `version` → `capabilities`, and
+ `catalogue.list` → what effects exist, before building a chain.
+
+---
+
+## Bridging today
+
+Until the server ships, an agent reaches Concat through a small MCP
+server that wraps the JSON-RPC socket. Three moving parts:
+
+1. `concat-cli serve` (or the window's Remote page), listening on
+ `127.0.0.1:7420` with a token.
+2. A stdio MCP server, spawned by the agent's host, that opens one socket
+ connection and turns tool calls into `call(method, params)`.
+3. Tool definitions that mirror the methods.
+
+A sketch in Python, using the `Concat` class from
+[JSON-RPC → Python client](json-rpc.md#a-minimal-python-client) and the
+`mcp` package:
+
+```python
+# concat_mcp.py — run with: python concat_mcp.py (the host spawns it over stdio)
+import os
+from mcp.server.fastmcp import FastMCP
+from concat_client import Concat # the class from the JSON-RPC page
+
+api = Concat(port=int(os.environ.get("CONCAT_PORT", 7420)), token=os.environ["CONCAT_API_TOKEN"])
+mcp = FastMCP("concat")
+
+def version() -> dict:
+ """What this Concat build serves."""
+ return api.call("version")
+
+def project_open(path: str) -> dict:
+ """Open a project folder. Returns the editor view."""
+ return api.call("project.open", path=path)
+
+def project_create(location: str, name: str) -> dict:
+ """Create a project folder under `location` and open it."""
+ return api.call("project.create", location=location, name=name)
+
+def media_import(path: str, file: str) -> dict:
+ """Probe a file and add it to the project's bin."""
+ return api.call("media.import", path=path, file=file)
+
+def edit_apply(path: str, command: dict) -> dict:
+ """Apply one edit command ({"op": ..., ...}). See docs/api/edits.md."""
+ return api.call("edit.apply", path=path, command=command)
+
+def catalogue_list(kind: str | None = None) -> list:
+ """Effect packages and their parameters."""
+ return api.call("catalogue.list", **({"kind": kind} if kind else {}))
+
+def export_run(path: str, output: str) -> dict:
+ """Render the timeline to a file and wait for it to finish."""
+ started = api.call("export.run", path=path, output=output)
+ return api.wait_for_job(started["job"])["params"]
+
+if __name__ == "__main__":
+ mcp.run()
+```
+
+Register it with the host as a stdio server with `CONCAT_API_TOKEN` in
+its environment. The exact registration is the host's; the server above
+speaks standard MCP over stdio.
+
+> [!NOTE]
+> This is a bridge, not the product. It has one connection, no streaming
+> progress, and a hand-picked tool list. The shipped server will expose
+> every method and stream events.
+
+---
+
+## Guidance for agents
+
+If you are an agent reading this because you have been pointed at Concat:
+
+1. Call `version`. Check `apiVersion` starts with `0.2` and read
+ `capabilities`.
+2. Open or create a project. Keep its **folder path**; every call needs
+ it.
+3. Import media with `media.import`. The reply's `createdId` is the media
+ id.
+4. Place clips with `addClipAtFirstFree` or `addClip`. Read the returned
+ `EditorView` for clip ids; do not guess them.
+5. Prefer one `batch` for a sequence of edits that belong together.
+6. Export with `export.run`, then wait for `export.done` or
+ `export.failed` for **that job**. Do not start a second export
+ meanwhile; it is refused with `busy`.
+7. Treat a `refused` message as the reason, in plain words. Nothing
+ changed.
+8. Save with `project.save` before `project.close`, or pass `save: true`.
+
+[Recipes](../recipes.md) has complete scripts for each of these.
diff --git a/src/README.md b/src/README.md
index 5c68acfe..8a891606 100644
--- a/src/README.md
+++ b/src/README.md
@@ -133,6 +133,10 @@ number means and what is not measured.
## Driving Concat without the window
+The full reference - every method, every edit command, every type, and a
+page per transport - is in [`docs/`](../docs/README.md) at the repository
+root. What follows is the short version.
+
Everything the window does to a project, a script can do through the Concat
API: `concat-api` is the one dispatcher, and the transports only carry it.
On a line - stdin, TCP, a Unix socket - a call is JSON-RPC 2.0, one object