@koda-sl/baker-cli 0.39.29-dev.994437bd → 0.66.2

package/README.md

@@ -1603,7 +1603,7 @@ Each external source is its own subcommand. Pick the verb that matches the sourc
 | `baker images crop <file>` | Coordinate-based rectangular extract — local file or URL | n/a |
 | `baker images dimensions <file\|url>` | Read width / height / aspect / format without decoding | n/a |
 
-**Auto-ingest** runs the full `processImage` pipeline (Gemini describe + Voyage multimodal embed + OpenRouter text embed) on every hit. Override with `--auto-ingest N` (turn on) or `--no-auto-ingest` (turn off where default is on). After auto-ingest the next `baker images library` query for the same concept hits the local row.
+**Auto-ingest** runs the full `processImage` pipeline (Gemini describe + Voyage multimodal embed + OpenRouter text embed) on every hit. Override with `--auto-ingest N` (turn on) or `--no-auto-ingest` (turn off where default is on). When auto-ingest succeeds, the matching returned hit uses the Baker-owned URL and keeps the original provider URL as `sourceUrl`. After auto-ingest the next `baker images library` query for the same concept hits the local row.
 
 **Provider context biases the description.** When a hit carries human-readable text (Giphy `alt_text` / `title`, Magnific `title`, Brandfetch type+theme, etc.) it's surfaced on the hit as `descriptionContext` and forwarded to Gemini during auto-ingest as a hint — Gemini still trusts the pixels (e.g. it'll correct a wrong botanical name) but uses the hint for cultural/brand/scene awareness it can't infer from bytes alone.
 
@@ -1659,7 +1659,7 @@ baker images find "office" --sources library,magnific --fallback --threshold 0.4
 baker images find "celebration" --sources library,giphy --auto-ingest 3
 ```
 
-Providers: `library`, `magnific`, `google`, `iconify`, `giphy`. Brandfetch is not part of the fanout — it takes a domain, not a query, so it lives at `baker images logo <domain>`. Response shape: `{ groups: { library, external }, meta: { counts, errors } }`. Partial failures (one provider throws) return the successful providers plus a `meta.errors` array; the whole call never fails on a single provider error.
+Providers: `library`, `magnific`, `google`, `iconify`, `giphy`. Brandfetch is not part of the fanout — it takes a domain, not a query, so it lives at `baker images logo <domain>`. Response shape: `{ groups: { library, external }, ingested, meta: { counts, errors } }`. When `--auto-ingest` is used, `ingested[]` preserves successful external ingest order and matching external hits are enriched with the Baker-owned URL plus source provenance. Partial failures (one provider throws) return the successful providers plus a `meta.errors` array; the whole call never fails on a single provider error.
 
 **Flags:**
 
@@ -1669,7 +1669,7 @@ Providers: `library`, `magnific`, `google`, `iconify`, `giphy`. Brandfetch is no
 | `--limit`        | Max results per group (default 20, max 50)                                                 |
 | `--fallback`     | Skip external providers when the top library score ≥ `--threshold`                         |
 | `--threshold`    | Library score floor for `--fallback` (default `0.4`)                                       |
-| `--auto-ingest`  | Ingest top N external hits into the library (0–20, default 0)                              |
+| `--auto-ingest`  | Ingest top N external hits into the library (0–20, default 0) and return Baker-owned URLs on ingested hits |
 | `--context`      | Free-text hint passed to Gemini describe to bias the generated description and tags (overrides provider-derived context on auto-ingest paths) |
 
 ### `baker images stock <query>`
@@ -1699,12 +1699,12 @@ Free tier exists but watermarks previews — pass `--license freemium` to filter
 | `--order`        | `relevance` (default) or `recent`                                                          |
 | `--limit`        | Max results (1–50, default 10)                                                             |
 | `--page`         | Page number for pagination                                                                 |
-| `--auto-ingest`  | Ingest top N hits (0–20, default 0)                                                        |
+| `--auto-ingest`  | Ingest top N hits (0–20, default 0) and return Baker-owned URLs on ingested hits                   |
 | `--context`      | Free-text hint passed to Gemini describe to bias the generated description and tags (overrides provider-derived context on auto-ingest paths) |
 
 ### `baker images google <query>`
 
-Google Images via the official Custom Search JSON API. ⚠ Source is unverified web content — inspect before placing.
+Google Images via the official Custom Search JSON API. ⚠ Source is unverified web content. With `--auto-ingest`, ingested hits return Baker-owned URLs.
 
 ```bash
 baker images google "industrial workshop" --type photo --size large --limit 20
@@ -1723,7 +1723,7 @@ Requires both `GOOGLE_CUSTOM_SEARCH_API_KEY` and `GOOGLE_CUSTOM_SEARCH_ENGINE_ID
 | `--color`        | `imgColorType`: `color \| gray \| mono \| trans`                                                         |
 | `--safe`         | `off \| active`                                                                                          |
 | `--limit`        | Max results (1–50, paginated 10 per call)                                                                |
-| `--auto-ingest`  | Ingest top N (0–20, default 0)                                                                           |
+| `--auto-ingest`  | Ingest top N (0–20, default 0) and return Baker-owned URLs on ingested hits                                      |
 | `--context`      | Free-text hint passed to Gemini describe to bias the generated description and tags (overrides provider-derived context on auto-ingest paths) |
 
 ### `baker images logo <domain>`
@@ -1776,7 +1776,7 @@ Variants that don't exist for a domain are silently skipped — `linear.app` ret
       { "providerMeta": { "type": "symbol", "theme": "light" }, "…": "…" },
       { "providerMeta": { "type": "symbol", "theme": "dark"  }, "…": "…" }
     ],
-    "ingested": [{ "imageId": "…", "deduped": false }]
+    "ingested": [{ "imageId": "…", "deduped": false, "imageUrl": "https://media.withbaker.com/…", "sourceUrl": "https://cdn.brandfetch.io/…" }]
   }
 }
 ```
@@ -2260,6 +2260,1753 @@ baker schema ads.google.query   # Get query command schema
 baker schema images.search      # Get image search schema
 ```
 
+## Creative Canvas
+
+The creative canvas runs declarative JSON pipelines. You author a graph of nodes (text, image, video, audio, composition, control-flow), `baker canvas run` it, and every node's output drops to disk under `canvas/<run_id>/` so you can watch progress and consume the artifacts.
+
+Auth: same `BAKER_API_KEY` + `BAKER_API_URL` as the rest of the CLI.
+
+### Quick start
+
+```bash
+# 1. Validate (free, never calls the API)
+baker canvas validate my-canvas.json
+
+# 2. Run (executes nodes, writes files to ./canvas/<run_id>/)
+baker canvas run my-canvas.json
+
+# 3. Inspect a finished run (per-node timing, file list, optional video thumbs)
+baker canvas inspect <run_id>
+
+# 4. Discover what's available (all node types, all models, all compositions)
+baker canvas catalog | jq
+```
+
+A re-run with no changes hits the cache for every node — total runtime drops to sub-second.
+
+---
+
+### How it works
+
+1. **You write a JSON file** describing nodes and how they wire together (`$ref:other_node.output`).
+2. **The validator** checks the schema, every node's params against the model registry, and that every `{{slot}}` in a prompt has a wired input.
+3. **The engine** runs nodes in topological order. Local nodes (text, ffmpeg, imagemagick, hyperframe_*, font_specimen) execute in-process. Remote nodes (text_generate, image_generate, image_describe, image_search, video_generate, tts, music…) POST to the Convex backend.
+4. **Outputs land on disk** the moment each node finishes — assets are downloaded from S3 and named `<node_id>__<slot>[__<index>].<ext>` inside the run dir.
+5. **The cache** is content-addressed by node params + input hashes. Edit a prompt, only the dependent nodes re-run.
+
+---
+
+### Canvas file structure
+
+```jsonc
+{
+  "schema": "baker-canvas/1",
+  "cache_salt": "v2",                          // optional, bumps the cache key for every node
+  "metadata": { "name": "my-canvas" },
+  "nodes": [
+    { "id": "topic", "type": "text", "params": { "value": "espresso machines" } },
+    {
+      "id": "headline",
+      "type": "text_generate",
+      "inputs": { "topic": "$ref:topic.text" },
+      "params": {
+        "model": "google/gemini-3.5-flash",
+        "prompt": "Write a 6-word tagline for {{topic}}."
+      }
+    }
+  ],
+  "output": { "node": "headline", "output": "text" }
+}
+```
+
+**Wiring nodes together:**
+
+| Token | Meaning |
+|---|---|
+| `$ref:node_id.output` | Read the named output slot of another node. |
+| `$ref:node_id.output#0` | Read element 0 of a list output (e.g. `images#0`). |
+| `{{slot}}` | Inside a string param, substitute the value of `inputs.<slot>`. |
+
+`{{slot}}` substitution by wired value kind:
+
+- Plain strings (e.g. the local `text` node's output) are spliced in as-is.
+- **text/json assets** (e.g. `text_generate.text`, `image_describe.description`) are spliced in as their full content, read from the local asset store. Capped at 256 KB per asset — a larger asset fails the node rather than silently truncating.
+- image/video/audio assets render as compact placeholders (e.g. `[image: 1024x1024]`); use `inputs` to pass the asset itself to nodes that accept it.
+
+The top-level `output` declares the canvas's final result — the engine returns its value on stdout when the run completes.
+
+---
+
+### Node types
+
+Every node shares the envelope `{ id, type, inputs?, params? }`. `inputs` wires other nodes' output slots in; `params` configures the node. The validator enforces required input kinds and per-model param shape **before** anything is billed.
+
+`baker canvas catalog` prints the always-current machine-readable schema for every node and every model. The tables below mirror the catalog at time of write.
+
+In every table:
+
+- "Required" on inputs means the validator blocks the run if the slot is unwired.
+- MIME lists are what the provider's transport accepts; `ingest` outputs flow through unchanged, so the source's MIME is what arrives.
+
+---
+
+#### Local nodes — run in-process, zero credits
+
+##### `text`
+
+A literal string value. Use for prompts, descriptions, copy.
+
+**Inputs:** none.
+
+**Params:** `value` (string, required).
+
+**Outputs:** `text` → `text` / `text/plain`.
+
+---
+
+##### `ffmpeg`
+
+Local ffmpeg passthrough. Write the argv you'd type, declare outputs, the engine stages inputs and ingests results. See [Local CLI nodes](#local-cli-nodes) for the placeholder safety contract.
+
+**Inputs:** open record. Each slot accepts an `AssetRef` or `AssetRef[]`. Reference inside `args` as `{{in.<slot>}}` / `{{in.<slot>.<index>}}`.
+
+**Params:**
+
+| Name | Type | Required | Constraint |
+|---|---|---|---|
+| `args` | string[] | yes | min 1; only `{{in.…}}` / `{{out.…}}` placeholders, no raw paths or URLs |
+| `outputs` | record | yes | `<name> → { kind: "image" \| "video" \| "audio", ext: string }` |
+
+**Outputs:** open record keyed by `params.outputs` entries; kind + ext per declaration.
+
+---
+
+##### `imagemagick`
+
+Local ImageMagick passthrough. Identical schema and safety contract to `ffmpeg`; uses `magick` (v7+) or `convert` (v6) on PATH.
+
+---
+
+##### `hyperframe_render`
+
+Render an HTML/CSS/GSAP composition to **mp4**. Quality, format, and worker count are fixed by the engine for ad-creative delivery — the canvas owns only the composition path and composition vars.
+
+**Inputs**
+
+Open record keyed by the composition's `meta.json` inputs (declared per composition).
+
+**Params**
+
+| Name | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `composition` | string | yes | — | path to composition dir |
+| `timeout_ms` | number | no | 600000 | positive |
+| **composition vars** | per `meta.json` | per `meta.json` | per `meta.json` | substituted into `{{var}}` |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `video` | video | `video/mp4` |
+
+See [authoring compositions](#authoring-compositions) for the composition file format.
+
+---
+
+##### `hyperframe_snapshot`
+
+Render the same composition format to a **PNG** still at **2× device-scale** (retina). Output size = composition `meta.json` `width × height × 2`.
+
+**Inputs**
+
+Open record keyed by the composition's `meta.json` inputs.
+
+**Params**
+
+| Name | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `composition` | string | yes | — | path to composition dir |
+| `wait_for` | `auto \| selector \| function \| timeout` | no | `{ kind: "auto" }` | `auto` waits for `load` + image decode + fonts ready |
+| `timeout_ms` | number | no | 60000 | positive |
+| **composition vars** | per `meta.json` | per `meta.json` | per `meta.json` | substituted into `{{var}}` |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `image` | image | `image/png` |
+
+---
+
+##### `font_specimen`
+
+Render specimen text in a given font file to a **PNG** — black `#000` text on a white `#fff` background — via headless Chromium at 2× device-scale. Produces a **typeface reference image**: wire `image` into `image_generate`'s `reference` input so the model replicates the font when generating images that contain text.
+
+Browser rendering means full text-shaping fidelity: kerning, ligatures, WOFF2, non-Latin scripts. If Chromium cannot parse the font file the node fails with a clear error instead of silently falling back to a system font.
+
+**Inputs**
+
+| Slot | Kind | Required | Notes |
+|---|---|---|---|
+| `font` | font | yes | ttf / otf / woff / woff2 — get one via `ingest` with `expect: "font"` |
+| _(any)_ | text/json | no | Extra slots are allowed and substitute into `text` via `{{slot}}` — wire upstream copy (e.g. a `text_generate` that extracts the exact on-image text) so the specimen renders the real headline, not a placeholder. |
+
+**Params**
+
+| Name | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `text` | string | no | pangram + A–Z + a–z + digits + punctuation | 1–2000 chars; `\n` for line breaks. Set to the exact headline, or `"{{slot}}"` wired to an upstream node. |
+| `font_size` | number | no | 72 | 8–512, integer (CSS px) |
+| `padding` | number | no | 64 | 0–512, integer (CSS px) |
+| `line_height` | number | no | 1.35 | 0.8–3 |
+| `max_width` | number | no | — (no wrap, auto width) | 256–4096, integer; wraps long lines when set |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `image` | image | `image/png` |
+
+**Cost:** 0 engine credits (deterministic — cached by font sha + params).
+
+Example pipeline:
+
+```jsonc
+{ "id": "font", "type": "ingest", "params": { "source": "url", "url": "https://cdn.example.com/brand.woff2", "expect": "font" } }
+{ "id": "specimen", "type": "font_specimen", "inputs": { "font": "$ref:font.asset" }, "params": {} }
+{ "id": "gen", "type": "image_generate", "inputs": { "reference": "$ref:specimen.image" },
+  "params": { "model": "google/gemini-3.1-flash-image-preview", "prompt": "Launch poster headlined 'SALE ENDS FRIDAY' using the exact typeface from the reference image" } }
+```
+
+---
+
+#### `ingest` — URL or local file → `AssetRef`
+
+Pick a `source` discriminator and declare the kind you expect. See [Ingestion](#ingestion-ingest-node) for the strategy table.
+
+**Inputs:** none.
+
+**Params** — discriminated on `source`:
+
+`source: "url"` (yt-dlp / direct fetch / Handinger):
+
+| Name | Type | Required | Constraint |
+|---|---|---|---|
+| `source` | literal | yes | `"url"` |
+| `url` | string | yes | valid URL |
+| `expect` | enum | yes | `image \| video \| audio \| text \| json \| font` |
+
+`source: "path"` (local filesystem → R2):
+
+| Name | Type | Required | Constraint |
+|---|---|---|---|
+| `source` | literal | yes | `"path"` |
+| `path` | string | yes | absolute or cwd-relative; `~` not expanded |
+| `expect` | enum | yes | `image \| video \| audio \| text \| json \| font` |
+
+**Outputs:** `asset` → `<params.expect>` / content-determined (URL strategy table) or extension-inferred (path).
+
+**Path-source notes:** the canvas is **not portable** to another machine without the file. Cache key folds the file's `mtime:size`, so editing the file invalidates the cache automatically. Supported extensions: `png`, `jpg`/`jpeg`, `webp`, `gif`, `avif`, `svg`, `mp4`, `webm`, `mov`, `m4v`, `mp3`, `wav`, `m4a`, `ogg`, `flac`, `json`, `txt`, `md`, `markdown`, `html`/`htm`, `csv`, `ttf`, `otf`, `woff`, `woff2`. Unknown extensions fall back to magic-byte sniffing for common image formats (and an SVG content sniff), else `kind_mismatch`. **SVG (`expect: "image"`) is rasterized to a transparent PNG on ingest** — brand logos are usually SVG, and image-generation models can't read SVG markup, so it's upscaled (longest edge near 2048px) with transparency preserved and the resulting asset carries `metadata.rasterized_from: "svg"`.
+
+**Cost:** 0 engine credits for direct fetch + yt-dlp + local file. Handinger charges per scrape.
+
+---
+
+#### Remote registry-managed nodes — billed in credits, curated model set
+
+Every generative node has a **curated** model enum. The registry (`packages/cli/src/engine/models/registry.ts`) is the source of truth and the validator runs per-model checks on params **and** required input kinds before any API call. The canvas-engine runs inside the controlled E2B sandbox (`packages/e2b-template/src/template.ts`), so models, MIME sets, and per-model param shapes are intentionally narrow.
+
+---
+
+##### `text_generate`
+
+Single-turn LLM text generation via OpenRouter.
+
+**Inputs**
+
+None.
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | enum | yes | one of `~google/gemini-flash-latest`, `~google/gemini-pro-latest` |
+| `prompt` | string | yes | non-empty |
+| `system` | string | no | system prompt |
+| `response_format` | enum | no | `text` (default) or `json_object`. Set `json_object` when a downstream `{{slot}}` consumes the output as JSON (e.g. the ad-blueprint transform) so the model returns clean JSON with no markdown fences or prose. |
+| `web_search` | boolean | no | When `true`, routes through OpenRouter's `:online` web plugin so the model searches the live web before answering. Use it on the ad-blueprint transform so it adapts copy to the target brand's real facts (current pricing, the trust signals it actually has) instead of guessing. Adds web-search cost. |
+| `temperature` | number | no | 0–2 |
+| `max_tokens` | number | no | positive int |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `text` | text | `text/plain` |
+
+**Cost** — 1 credit per call (flat estimate; usage-based pricing is a follow-up).
+
+**Example**
+
+```json
+{
+  "id": "headline",
+  "type": "text_generate",
+  "params": {
+    "model": "~google/gemini-flash-latest",
+    "prompt": "Write a 6-word hero headline for a dog-insurance ad."
+  }
+}
+```
+
+---
+
+##### `image_generate`
+
+Generate images via OpenRouter. The Zod schema is a permissive union; per-model param/aspect-ratio support is registry-validated.
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `reference` | image **or** image[] | no | `image/png`, `image/jpeg`, `image/webp`, `image/gif` |
+
+`reference` accepts a single image or an **array** of images. Wire several to combine references in one
+generation — e.g. a subject reference sheet + a font specimen + the original ad. Each image is
+forwarded to the model as a separate input, in array order (the provider accepts multiple). Wire an
+array as a literal list: `"reference": ["$ref:subject.sheet", "$ref:type.image"]`.
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `images` | image[] | `image/png \| image/jpeg \| image/webp` (provider-determined) |
+
+**Cost** — 5 credits estimate per call (backend charges actual OpenRouter usage).
+
+> `seed` is not supported — OpenRouter's `image_config` schema has no seed slot for image-gen.
+
+Aspect-ratio sets used below:
+- **STD AR** = `1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9`
+- **EXTREME AR** = STD AR + `1:4, 4:1, 1:8, 8:1`
+
+---
+
+###### Model: `openai/gpt-5.4-image-2`
+
+Photorealistic generalist. Optional `reference` image.
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"openai/gpt-5.4-image-2"` |
+| `prompt` | string | yes | non-empty |
+| `aspect_ratio` | enum | no | STD AR |
+| `image_size` | enum | no | `1K \| 2K \| 4K` |
+
+```json
+{ "id": "hero", "type": "image_generate",
+  "params": { "model": "openai/gpt-5.4-image-2", "prompt": "Photo of …", "aspect_ratio": "16:9", "image_size": "2K" } }
+```
+
+###### Model: `google/gemini-3.5-flash`
+
+Newest Gemini Flash image model. Always returns an image output. Best for fast iteration; supports extreme aspect ratios and the `0.5K` size for cheap previews.
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"google/gemini-3.5-flash"` |
+| `prompt` | string | yes | non-empty |
+| `aspect_ratio` | enum | no | EXTREME AR |
+| `image_size` | enum | no | `0.5K \| 1K \| 2K \| 4K` |
+
+###### Model: `google/gemini-3.1-flash-image-preview`
+
+Preview-channel Gemini flash. Same param surface as `3.5-flash`.
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"google/gemini-3.1-flash-image-preview"` |
+| `prompt` | string | yes | non-empty |
+| `aspect_ratio` | enum | no | EXTREME AR |
+| `image_size` | enum | no | `0.5K \| 1K \| 2K \| 4K` |
+
+###### Model: `google/gemini-3-pro-image-preview`
+
+"Nano Banana Pro" — heavier, higher-quality Gemini.
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"google/gemini-3-pro-image-preview"` |
+| `prompt` | string | yes | non-empty |
+| `aspect_ratio` | enum | no | STD AR |
+| `image_size` | enum | no | `1K \| 2K \| 4K` |
+
+###### Model: `recraft/recraft-v4.1-pro-vector`
+
+Crisp vector / logo generator. Adds palette controls forwarded to Recraft via `image_config`.
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"recraft/recraft-v4.1-pro-vector"` |
+| `prompt` | string | yes | non-empty |
+| `aspect_ratio` | enum | no | STD AR |
+| `image_size` | enum | no | `1K \| 2K \| 4K` |
+| `strength` | number | no | 0–1 |
+| `rgb_colors` | `[r,g,b][]` | no | palette, each component 0–255 |
+| `background_rgb_color` | `[r,g,b]` | no | background, each component 0–255 |
+
+```json
+{ "id": "logo", "type": "image_generate",
+  "params": { "model": "recraft/recraft-v4.1-pro-vector", "prompt": "Bold sans-serif wordmark 'OFFUGO'",
+              "aspect_ratio": "16:9", "image_size": "2K",
+              "rgb_colors": [[255, 98, 89]], "background_rgb_color": [249, 250, 251] } }
+```
+
+---
+
+##### `image_reference_sheet`
+
+Fuse 1–6 images of a single subject (person, character, or product) into ONE multi-view reference sheet — a labeled turnaround grid (FRONT / SIDE / BACK…) in consistent style and lighting. Identity drift is the default behavior of image models; a sheet converts subject consistency from a prompting problem into a pipeline input. Wire the `sheet` output into the `reference` input of downstream `image_generate` / `video_generate` nodes to keep the subject consistent across many creatives.
+
+The sheet prompt is baked into the backend — there is no `prompt` param. `subject_description` is spliced verbatim into the template; reuse the exact same wording in downstream prompts. `prompt_override` bypasses the template entirely.
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `references` | image[] | yes (1–6) | `image/png`, `image/jpeg`, `image/webp`, `image/gif` |
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | enum | yes | one of `google/gemini-3-pro-image-preview`, `google/gemini-3.1-flash-image-preview` |
+| `subject_description` | string | yes | exact subject wording — reuse verbatim downstream |
+| `subject_type` | enum | yes | `character \| person \| product` — picks the template + default views |
+| `views` | string[] | no | 2–6 view labels; defaults per `subject_type` (below) |
+| `style` | string | no | style/lighting notes, e.g. `"32-bit pixel art"`, `"matte black studio background"` |
+| `prompt_override` | string | no | full template bypass |
+| `aspect_ratio` | enum | no | STD AR on `3-pro`, EXTREME AR on `3.1-flash` |
+| `image_size` | enum | no | `1K \| 2K \| 4K` on `3-pro`, `0.5K \| 1K \| 2K \| 4K` on `3.1-flash` |
+
+Default views per `subject_type`:
+
+| `subject_type` | Default views |
+|---|---|
+| `character` | FRONT, THREE-QUARTER LEFT, SIDE LEFT, BACK |
+| `person` | FRONT, THREE-QUARTER LEFT, SIDE LEFT, THREE-QUARTER RIGHT, SIDE RIGHT, BACK |
+| `product` | FRONT, BACK, LEFT SIDE, RIGHT SIDE, TOP, THREE-QUARTER |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `sheet` | image | `image/png \| image/jpeg \| image/webp` (provider-determined) |
+
+**Cost** — 20 credits estimate on `3-pro`, 5 on `3.1-flash` (backend charges actual OpenRouter usage).
+
+Guidance:
+- 3–4 full-body views at `16:9` is the sweet spot for characters; more views shrink each figure and lose face detail.
+- Use `google/gemini-3.1-flash-image-preview` while iterating; switch to `google/gemini-3-pro-image-preview` at `2K`+ for final 6-view sheets.
+- Feed the whole sheet downstream as one `reference` input — don't crop individual views.
+
+**Example** — two photos of a sneaker → product sheet → consistent hero shot:
+
+```json
+{
+  "schema": "baker-canvas/1",
+  "nodes": [
+    { "id": "a", "type": "ingest", "params": { "source": "url", "url": "https://example.com/sneaker-front.jpg", "expect": "image" } },
+    { "id": "b", "type": "ingest", "params": { "source": "url", "url": "https://example.com/sneaker-side.jpg", "expect": "image" } },
+    { "id": "sheet", "type": "image_reference_sheet",
+      "inputs": { "references": ["$ref:a.asset", "$ref:b.asset"] },
+      "params": { "model": "google/gemini-3-pro-image-preview",
+                  "subject_description": "navy leather low-top sneaker with white sole and gold logo",
+                  "subject_type": "product",
+                  "style": "matte black studio background, soft even key light",
+                  "aspect_ratio": "16:9", "image_size": "2K" } },
+    { "id": "hero", "type": "image_generate",
+      "inputs": { "reference": "$ref:sheet.sheet" },
+      "params": { "model": "google/gemini-3-pro-image-preview",
+                  "prompt": "The navy leather low-top sneaker with white sole and gold logo from the reference sheet, hero shot on a rain-soaked neon street at night" } }
+  ],
+  "output": { "node": "hero", "output": "images" }
+}
+```
+
+---
+
+##### `image_aspect_adapt`
+
+Adapt ONE creative into multiple aspect ratios in a single step — the standard fan-out when a hero creative must ship to every placement (Meta: 9:16 stories, 1:1 feed, 4:5, 16:9…). The AI recomposes the layout per format: identical subject, faces, products, text (verbatim, same typography), logos, colors, and style; the scene is extended/restructured for the new canvas — never stretched, cropped, or letterboxed.
+
+The adaptation prompt is baked into the backend and is direction-aware (a wider target gets horizontal recomposition guidance, a taller one vertical). Formats that already match the source ratio (within ~2%) pass the source asset through unchanged — no model call, no cost.
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `source` | image | yes | `image/png`, `image/jpeg`, `image/webp`, `image/gif` |
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | enum | yes | one of `google/gemini-3-pro-image-preview`, `google/gemini-3.1-flash-image-preview` |
+| `formats` | enum[] | yes | 1–6 unique target ratios from `1:1 \| 2:3 \| 3:2 \| 3:4 \| 4:3 \| 4:5 \| 5:4 \| 9:16 \| 16:9 \| 21:9` — output order follows this list |
+| `guidance` | string | no | hints appended to the baked prompt, e.g. `"keep the CTA button fully visible"` |
+| `image_size` | enum | no | `1K \| 2K \| 4K` on `3-pro`, `0.5K \| 1K \| 2K \| 4K` on `3.1-flash` |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `images` | image[] | one per requested format, in `formats` order; each carries `metadata.aspect_ratio` and `metadata.adapted` (`false` = source passed through) |
+
+**Cost** — per-format estimate: 20 credits on `3-pro`, 5 on `3.1-flash`, × `formats.length` (backend charges actual OpenRouter usage; pass-through formats are free).
+
+Guidance:
+- List the source's own ratio in `formats` too when you want the full set in one output — it passes through for free.
+- Use `google/gemini-3.1-flash-image-preview` while iterating; switch to `google/gemini-3-pro-image-preview` for final-quality adaptation.
+- Indexes are positional: `$ref:adapt.images#1` is always the second entry of `formats`.
+
+**Example** — one 9:16 story creative fanned out to feed and landscape:
+
+```json
+{
+  "schema": "baker-canvas/1",
+  "nodes": [
+    { "id": "hero", "type": "image_generate",
+      "params": { "model": "google/gemini-3-pro-image-preview",
+                  "prompt": "Story-format ad for a citrus energy drink: can centered, bold OFFER text top, logo bottom",
+                  "aspect_ratio": "9:16", "image_size": "2K" } },
+    { "id": "adapt", "type": "image_aspect_adapt",
+      "inputs": { "source": "$ref:hero.images#0" },
+      "params": { "model": "google/gemini-3-pro-image-preview",
+                  "formats": ["9:16", "1:1", "16:9"],
+                  "guidance": "keep the offer text and logo fully visible" } }
+  ],
+  "output": { "node": "adapt", "output": "images" }
+}
+```
+
+---
+
+##### `image_describe`
+
+Reverse-engineer an image into an exhaustive, replication-grade JSON blueprint via an OpenRouter vision model. The extraction prompt ("Visual Architect") is baked into the backend and returns one JSON object covering not just WHAT is in the image but HOW it is rendered and WHY: `source_context` (who the advertiser is, what they sell, market, and their inferred brand palette), `meta`, `composition`, `subjects` (non-person objects/graphics, each with `expression`, `emotion_conveyed`, `gaze`, `treatment`, and `role_in_intent`), `people` (deep per-person detail plus expression/treatment/role-in-intent), `environment`, `camera` (estimated focal length, aperture, DoF), `lighting`, `color` (hex palette where each color is tagged `brand_ownership` — brand vs borrowed-functional — plus `purpose` and a `purpose_note`), `materials_textures`, `text_content` (all visible text verbatim), `brands_logos` (each mark identified by brand — "Trustpilot", never "green star"), `ad_signals` (proof badges, CTA, price/offer; null when not an ad), `ad_intent` (the persuasion engine: primary emotion, mechanism, arc, viewer takeaway; null when not an ad), `style`, and `post_processing`. The model runs at temperature 0 with JSON mode enforced.
+
+Built for **market adaptation**: logos are named by brand, people and animals carry expression/emotion/intent, and each color is tagged brand vs borrowed-functional — so a downstream transform can keep, localize, or swap each element, preserve the emotional intent, and selectively keep the reds/yellows that do a job (a red "without insurance" column) rather than blindly recoloring to the new brand. Pass `context` with what you already know (advertiser, category, market) to ground `source_context` and color ownership. Because the output is a json asset, wiring it into a downstream `{{slot}}` splices the full blueprint into that prompt — restyle a reference onto a new subject, lock a look across a series, or feed exact palette/lighting into `image_generate`. The output is rich; for dense ads raise `max_tokens` (e.g. 8000+) so the JSON isn't truncated.
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `image` | image | yes | `image/png`, `image/jpeg`, `image/webp`, `image/gif` |
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | enum | yes | one of `~google/gemini-pro-latest`, `~google/gemini-flash-latest` (`pro` for the densest extraction) |
+| `focus` | string | no | aspects to emphasise, e.g. `"typography and color palette"` |
+| `context` | string | no | known provenance to ground `source_context` and color ownership, e.g. `"competitor ad for AssurOpoil, Italian pet insurance"` |
+| `temperature` | number | no | 0–2, defaults to 0 |
+| `max_tokens` | number | no | positive int |
+
+There is no `prompt` param — the extraction schema is the node. Use `focus` to steer emphasis and `context` to supply provenance.
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `description` | json | `application/json` |
+
+**Cost** — 2 credits estimate per call (backend charges actual OpenRouter usage).
+
+**Example** — extract a blueprint from a reference and restyle it onto a new subject:
+
+```json
+{
+  "schema": "baker-canvas/1",
+  "nodes": [
+    { "id": "ref", "type": "ingest", "params": { "source": "url", "url": "https://example.com/competitor-ad.png", "expect": "image" } },
+    { "id": "blueprint", "type": "image_describe",
+      "inputs": { "image": "$ref:ref.asset" },
+      "params": { "model": "~google/gemini-pro-latest" } },
+    { "id": "remix", "type": "image_generate",
+      "inputs": { "blueprint": "$ref:blueprint.description" },
+      "params": { "model": "openai/gpt-5.4-image-2",
+                  "prompt": "Recreate an image matching this exact blueprint, but swap the product for a ceramic mug:\n{{blueprint}}" } }
+  ],
+  "output": { "node": "remix", "output": "images" }
+}
+```
+
+---
+
+##### `image_search`
+
+Search the web for real images instead of generating them. A backend LLM agent picks among Google Images, stock photography (Freepik), and Pinterest, refines queries, selects the best matches, and the chosen images are downloaded into canvas assets. Use it to gather references or candidates (e.g. five photos of an australian shepherd) for a later pick-the-best step.
+
+**Inputs** — none.
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `prompt` | string | yes | What to find, non-empty |
+| `count` | int | no | Images to return, 1–20 (default 5) |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `images` | image[] | `image/png \| image/jpeg \| image/webp \| image/gif \| …` (source-determined) |
+
+**Cost** — `2 + count/2` credits estimate per call (backend charges actual LLM + search-API usage). May return fewer than `count` images when sources run dry or downloads fail; fails only when nothing is retrievable.
+
+**Example**
+
+```json
+{
+  "id": "refs",
+  "type": "image_search",
+  "params": { "prompt": "australian shepherd running on a beach", "count": 5 }
+}
+```
+
+---
+
+##### `image_select`
+
+Pick the best `count` images out of 2+ candidates with a vision LLM, judged against a prompt. The output is a passthrough subset of the input refs — no new pixels are generated, so selection is cheap. Use it after fanning out several `image_generate` variants (or an `image_search` batch) to keep only the strongest before expensive downstream steps.
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `images` | image[] | yes — at least 2 | `image/png`, `image/jpeg`, `image/webp`, `image/gif` |
+
+Wire either a whole upstream array (`"$ref:gen.images"`) or a literal list collecting refs from several nodes (`["$ref:a.images#0", "$ref:b.images#0"]`).
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | enum | yes | one of `~google/gemini-flash-latest`, `~google/gemini-pro-latest` (`pro` for harder aesthetic judgement) |
+| `prompt` | string | yes | selection criteria, e.g. `"most professional product shot, clean background"` |
+| `count` | int | no | images to select, ≥ 1 (default 1); must not exceed the wired image count |
+| `temperature` | number | no | 0–2, defaults to 0 |
+| `max_tokens` | number | no | positive int |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `images` | image[] | per input — exactly `count` refs, in the model's preference order, so `images#0`…`images#count-1` are always safe to wire |
+| `reasoning` | text | `text/plain` — why the winners won, compared against the rejected candidates |
+
+**Cost** — 1 credit estimate per call (backend charges actual OpenRouter usage).
+
+Fail-fast: an invalid model selection (wrong count, duplicate or out-of-range picks, non-JSON response) is a retryable provider error — the node never pads or repairs a selection. Passthrough refs keep `kind`/`url`/`sha256`/`mime`; upstream `width`/`height` metadata is not carried through.
+
+**Example** — fan out 3 variants, keep the best one:
+
+```json
+{
+  "schema": "baker-canvas/1",
+  "nodes": [
+    { "id": "a", "type": "image_generate", "params": { "model": "google/gemini-3.5-flash", "prompt": "hero shot of a ceramic mug, warm morning light" } },
+    { "id": "b", "type": "image_generate", "params": { "model": "google/gemini-3.5-flash", "prompt": "hero shot of a ceramic mug, studio softbox" } },
+    { "id": "c", "type": "image_generate", "params": { "model": "google/gemini-3.5-flash", "prompt": "hero shot of a ceramic mug, dramatic side light" } },
+    { "id": "best", "type": "image_select",
+      "inputs": { "images": ["$ref:a.images#0", "$ref:b.images#0", "$ref:c.images#0"] },
+      "params": { "model": "~google/gemini-pro-latest", "prompt": "most premium-feeling lighting, no harsh shadows" } }
+  ],
+  "output": { "node": "best", "output": "images" }
+}
+```
+
+---
+
+##### `video_generate`
+
+Generate video. Async with polling. Two curated models.
+
+**Inputs**
+
+| Slot | Kind | Required | Notes |
+|---|---|---|---|
+| `first_frame` | image | no | Starting keyframe (image-to-video) |
+| `last_frame` | image | no | Ending keyframe |
+| `reference` | image | no | Alternative to `first_frame` when only one image is given |
+
+Accepted ref-image MIMEs vary by model — see per-model sections below.
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `video` | video | `video/mp4` |
+
+**Cost** — 50 credits estimate per call.
+
+---
+
+###### Model: `bytedance/seedance-2.0`
+
+Production-quality ad-creative model. Routed via **fal.ai** (not OpenRouter) because OpenRouter's Seedance passthrough rejects photorealistic human reference frames via ByteDance's "real person" safety filter.
+
+Ref-image MIMEs: `image/png`, `image/jpeg`, `image/webp` (via fal.ai).
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"bytedance/seedance-2.0"` |
+| `prompt` | string | yes | non-empty |
+| `duration` | enum | no | `4, 5, 6, 8, 10, 12, 15` (gaps trigger 400s) |
+| `resolution` | enum | no | `480p \| 720p \| 1080p` |
+| `aspect_ratio` | enum | no | `1:1, 3:4, 9:16, 4:3, 16:9, 21:9, 9:21` |
+| `generate_audio` | boolean | no | native audio track |
+| `seed` | number | no | nonneg int |
+
+> Seedance does **not** accept `negative_prompt` — its OpenRouter passthrough is `[watermark, req_key]` only. Use Veo if you need negative prompting.
+
+```json
+{ "id": "clip", "type": "video_generate",
+  "inputs": { "first_frame": "$ref:start.images#0", "last_frame": "$ref:end.images#0" },
+  "params": { "model": "bytedance/seedance-2.0", "prompt": "Same person, talking head, …",
+              "duration": 8, "resolution": "720p", "aspect_ratio": "9:16", "generate_audio": false } }
+```
+
+###### Model: `google/veo-3.1-fast`
+
+Cheap/fast model — intended for iteration and tests. Routed via OpenRouter with passthroughs under `provider.options.google-vertex.parameters`.
+
+Ref-image MIMEs: `image/png`, `image/jpeg`, `image/webp`, `image/gif` (via OpenRouter).
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"google/veo-3.1-fast"` |
+| `prompt` | string | yes | non-empty |
+| `duration` | enum | no | `4, 6, 8` |
+| `resolution` | enum | no | `720p \| 1080p` |
+| `aspect_ratio` | enum | no | `16:9 \| 9:16` |
+| `generate_audio` | boolean | no | native audio track |
+| `seed` | number | no | nonneg int |
+| `negative_prompt` | string | no | Veo passthrough |
+| `person_generation` | enum | no | only `allow_all` is currently verified |
+| `enhance_prompt` | boolean | no | Veo passthrough |
+| `conditioning_scale` | number | no | Veo passthrough |
+
+```json
+{ "id": "iter", "type": "video_generate",
+  "params": { "model": "google/veo-3.1-fast", "prompt": "Cinematic dolly-in on a logo",
+              "duration": 6, "resolution": "1080p", "aspect_ratio": "16:9", "enhance_prompt": true } }
+```
+
+---
+
+##### `tts`
+
+Single-voice text-to-speech via ElevenLabs.
+
+**Inputs**
+
+None.
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `audio` | audio | provider-determined (mp3 by default) |
+| `timestamps` | json | `application/json` — present only when `with_timestamps: true` |
+
+**Cost** — `max(1, ceil(text.length × 0.0015))` credits.
+
+###### Model: `elevenlabs/eleven_v3`
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"elevenlabs/eleven_v3"` |
+| `text` | string | yes | non-empty, ≤45454 chars (the $10 per-node cost cap) |
+| `voice` | string | yes | ElevenLabs voice id |
+| `language_code` | string | no | ISO 639-1 hint |
+| `stability` | number | no | 0–1 (top-level shortcut) |
+| `similarity_boost` | number | no | 0–1 (top-level shortcut) |
+| `voice_settings` | json | no | `{ stability, similarity_boost, style, use_speaker_boost, speed }` |
+| `seed` | number | no | 0–4294967295 |
+| `pronunciation_dictionary_locators` | json | no | up to 3 dicts |
+| `apply_text_normalization` | enum | no | `auto \| on \| off` |
+| `apply_language_text_normalization` | boolean | no | Japanese-only, adds latency |
+| `with_timestamps` | boolean | no | character-level alignment in `timestamps` output |
+| `output_format` | enum | no | `mp3_22050_32 … mp3_44100_192` (mp3 family only — assets are stored as `audio/mpeg`) |
+
+> eleven_v3 does **not** support context stitching (`previous_text`/`next_text`/`*_request_ids`) — ElevenLabs returns `unsupported_model` if you pass them, so the registry rejects them at validation time.
+
+```json
+{ "id": "vo", "type": "tts",
+  "params": { "model": "elevenlabs/eleven_v3", "text": "Hey! Quick story —", "voice": "JBFqnCBsd6RMkjVDRZzb",
+              "language_code": "en", "with_timestamps": true } }
+```
+
+---
+
+##### `video_lipsync`
+
+Lip-sync a video to an audio track via VEED (fal.ai).
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `video` | video | yes | `video/mp4`, `video/webm`, `video/quicktime` |
+| `audio` | audio | yes | `audio/wav`, `audio/mpeg`, `audio/mp3` |
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"fal/veed-lipsync"` |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `video` | video | `video/mp4` |
+
+**Cost** — 20 credits per call.
+
+---
+
+##### `video_background_remove`
+
+Strip a video's background → alpha WebM/H264. Powered by fal.ai VEED.
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `video` | video | yes | `video/mp4`, `video/webm`, `video/quicktime` |
+
+**Params**
+
+| Name | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `model` | literal | no | `"fal/veed-video-background-removal"` | — |
+| `edge_refinement` | boolean | no | `true` | — |
+| `output_codec` | enum | no | `"vp9"` | `vp9 \| h264` |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `video` | video | `video/webm` (VP9 + alpha) or `video/mp4` (H264 RGB + alpha) |
+
+**Cost** — 50 credits per call.
+
+---
+
+##### `video_transcribe`
+
+Word-level transcription. Default `transcriber:"groq"` uses Groq Whisper Large v3 Turbo; `transcriber:"deepgram"` uses Deepgram Nova-3, which additionally emits a `rich` output with punctuated words + paragraph/sentence grouping (and speaker indices). Auto-extracts audio locally (mono 16 kHz, 64 kbps MP3) before uploading — payload shrinks ~100× vs. sending the full video.
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `video` | video | yes | `video/mp4`, `video/webm`, `video/quicktime` |
+
+**Params**
+
+| Name | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `language` | string | no | auto | ISO 639-1, 2–8 chars (e.g. `en`, `es`) |
+| `transcriber` | enum | no | `groq` | `groq` (Whisper) \| `deepgram` (Nova-3, adds the `rich` output) |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `transcript` | json | `application/json` — array of `{text, start, end}` (Deepgram prefers the punctuated word form) |
+| `rich` | json | `application/json` — Deepgram only: `{text, words[], paragraphs[], duration_sec, language?}` with punctuated words, sentences, and speaker indices |
+
+**Cost** — 2 credits estimate; backend reports actual based on duration (Groq: $0.04/hr, 10s minimum; Deepgram Nova-3: $0.0043/min).
+
+**Requirements** — `ffmpeg` on PATH for audio extraction (already in the E2B sandbox image). Without it the node still works but uploads the full video and Groq's 100 MB cap applies.
+
+---
+
+##### `video_deconstruct`
+
+Reverse-engineer a video into a replication-grade blueprint: scene boundaries, the **real start/end frame of every scene** (extracted from the video as PNG images), and an exhaustive JSON analysis — per-scene action detail, camera motion, generation-ready frame/motion prompts, overlay text with full typographic style, floating elements, deeply detailed `global.cast` (perceived demographics, ethnicity/skin-tone, styling, market-recasting notes), brand-identified logos in `global.branding` (named by brand and what they signal — "Trustpilot", never "green star" — with on-screen timestamps), dialogue with castable voice descriptions, music spec, SFX list — plus a word-level transcript. Built to feed reproduction/remix and market-adaptation workflows. When the backend has an `AUDD_API_TOKEN` configured and the blueprint reports music, an AudD recognition pass identifies the backing track at `analysis.global.music.identified_track` (title/artist/album + Spotify/Apple links); a recognition miss never fails the run.
+
+**Agent workflow** (structure first, then extract, then author):
+
+1. *(optional, cheap)* `mode:"index"` — one LLM call, no frames: global blueprint + scene boundaries + transcript. Use it to see how many scenes exist before planning.
+2. Full deconstruct — short videos (≤8 min) in one node; longer videos as **several parallel nodes**, each with a `start_s`/`end_s` window of ≤480s (snap window edges to scene boundaries from the index pass). Merge the per-window analyses by concatenating `scenes` (each carries an absolute-time `window` marker).
+3. For a full reproduction, you normally don't run this node directly — `baker canvas scaffold-video <video>` runs the deconstruct for you and scaffolds the canvas. Use this node standalone when you need the raw `analysis`/`transcript` JSON (e.g. windowed long-video analysis) for a custom workflow.
+
+Over-length runs fail with a message that includes ready-to-use suggested windows, so the loop is self-correcting.
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `video` | video | yes | `video/mp4`, `video/webm`, `video/quicktime` |
+
+**Params**
+
+| Name | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `model` | enum | yes | — | `~google/gemini-flash-latest` (cheap/fast) \| `~google/gemini-pro-latest` (densest extraction) |
+| `mode` | enum | no | `full` | `index` = structure-first pass: boundaries + global blueprint + transcript, no frames, ~60s |
+| `language` | string | no | auto | ISO 639-1 transcription hint (e.g. `en`, `es`) |
+| `transcriber` | enum | no | `groq` | transcript provider: `groq` (Whisper) \| `deepgram` (Nova-3, punctuated words) |
+| `max_scenes` | number | no | `20` (full ≤3 min) / `40` (longer) / `60` (index) | 1–60; extra cuts merge into the last scene |
+| `focus` | string | no | — | extra extraction emphasis (e.g. `"overlay typography"`) |
+| `start_s` / `end_s` | number | no | whole video | analysis window (absolute seconds) for chunking long videos; window ≤480s |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `analysis` | json | `application/json` — `video-deconstruct/1` blueprint (or `video-deconstruct-index/1` in index mode) |
+| `start_frames` | image[] | `image/png` — real first frame of each scene, native resolution (absent in `mode:"index"`) |
+| `end_frames` | image[] | `image/png` — real last frame of each scene (absent in `mode:"index"`) |
+| `transcript` | json | `application/json` — array of `{text, start, end}` (same contract as `video_transcribe`; window-scoped on windowed runs) |
+
+`analysis.scenes[i]` aligns positionally with `start_frames#i` / `end_frames#i`, and each scene also embeds its frames' `{url, sha256}` so the JSON is self-sufficient.
+
+**Reproduction recipe** — the blueprint maps 1:1 onto generation nodes:
+
+| Blueprint field | Feed into |
+|---|---|
+| `scenes[i].start_frame_prompt` / `end_frame_prompt` | `image_generate` (overlay text is excluded by contract — recomposite from `overlays`) |
+| `scenes[i].motion_prompt` + `start_frames#i` / `end_frames#i` | `video_generate` (`first_frame` / `last_frame`, e.g. Seedance) |
+| `scenes[i].dialogue[].line` + `voice_description` | `tts` / `dialogue` |
+| `global.music.music_prompt` | `music` |
+| `scenes[i].sfx[].sound_effect_prompt` | `sound_effect` |
+| `scenes[i].overlays[]` (text, timing, 9-grid position, animation, font style) + `floating_elements[]` | `ffmpeg` / `hyperframe_render` overlay pass |
+
+```jsonc
+{
+  "schema": "baker-canvas/1",
+  "nodes": [
+    { "id": "ref",  "type": "ingest", "params": { "source": "url", "url": "https://…/competitor-ad.mp4", "expect": "video" } },
+    { "id": "dec",  "type": "video_deconstruct",
+      "inputs": { "video": "$ref:ref.asset" },
+      "params": { "model": "~google/gemini-flash-latest", "focus": "overlay typography and pacing" } },
+    // Remake scene 1 conditioned on its real boundary frames:
+    { "id": "s1",   "type": "video_generate",
+      "inputs": { "first_frame": "$ref:dec.start_frames#0", "last_frame": "$ref:dec.end_frames#0" },
+      "params": { "model": "bytedance/seedance-2.0", "prompt": "{{motion}}" } }
+  ],
+  "output": { "node": "dec", "output": "analysis" }
+}
+```
+
+**Cost** — 15 credits estimate (3 for `mode:"index"`); backend reports actual OpenRouter usage across `scene_count + 1` Gemini calls (~$0.05–0.40 for a 45s ad on flash) plus Groq transcription ($0.04/hr, 10s min). For videos over 3 minutes, per-scene calls automatically switch from full-video attachment to frame strips (boundary + mid-scene thumbnails) so cost stays flat per scene.
+
+**Limits** — video must have a public URL (use `ingest` first for local files); ≤8 min in one node, ≤30 min total via parallel `start_s`/`end_s` windows. Transcription routes through a Mux audio-only rendition above 5 min (Groq caps uploads at 100MB). Frame extraction rides on a throwaway Mux asset (created, thumbnailed, deleted per run), so expect ~1–3 min wall clock for a 45s video.
+
+**Reproduction** — for the full-pipeline canvas, use `baker canvas scaffold-video <video>` (below): it runs this deconstruct for you, detects the recurring identity elements, and scaffolds the runnable canvas in one command.
+
+---
+
+##### `voice_select`
+
+Cast an ElevenLabs voice from a natural-language description (e.g. a blueprint's `voice_description`). Lists the account's voices (`GET /v2/voices`, free) and ranks them against the brief.
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `description` | string | yes | the casting brief |
+| `gender` / `age` / `accent` / `language` | string | no | structured hints that sharpen the ranking |
+| `limit` | number | no | how many `candidates` to return (default 5) |
+
+**Outputs** — `voice_id` (text, bare id) + `candidates` (json, ranked shortlist). Wire `voice_id` into a `tts` node: set `inputs.voice_ref: $ref:<this>.voice_id` and `params.voice: "{{voice_ref}}"` — the engine splices the id in at run time.
+
+**Cost** — free (voice listing). Generation is billed under `tts`/`dialogue`.
+
+---
+
+##### `audio_timeline`
+
+Place and mix several audio clips onto one timeline — a music bed plus timed voiceover and SFX — into a single track. Local ffmpeg.
+
+**Inputs** — open audio slots (one per clip), wired as `inputs.<slot>`.
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `tracks` | array | yes | `[{slot, start_s, gain_db?}]` — `slot` matches a wired input; `start_s` is absolute seconds; `gain_db` ducks (e.g. `-12` for a music bed) |
+| `total_ms` | number | no | pins the final length (pad/trim) |
+| `output_format` | enum | no | `mp3` (default) / `wav` / `m4a` |
+
+**Outputs** — `audio`. **Cost** — free (local). Requires `ffmpeg`.
+
+---
+
+##### `image_background_remove`
+
+Strip background → transparent PNG (or mask). Powered by fal.ai BiRefNet v2.
+
+**Inputs**
+
+| Slot | Kind | Required | Accepted MIMEs |
+|---|---|---|---|
+| `image` | image | yes | `image/png`, `image/jpeg`, `image/webp` |
+
+**Params**
+
+| Name | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `model` | literal | no | `"fal/birefnet-v2"` | — |
+| `model_variant` | enum | no | `"General Use (Light)"` | `General Use (Light) \| General Use (Heavy) \| Matting \| Portrait \| DIS \| HRSOD \| COD` |
+| `operating_resolution` | enum | no | — | `1024x1024 \| 2048x2048 \| 2304x2304` |
+| `mask_only` | boolean | no | `false` | return binary mask instead of alpha-cut |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `image` | image | `image/png` (with alpha) |
+| `mask` | image | `image/png` (only when `mask_only: true`) |
+
+**Cost** — 1 credit per call.
+
+---
+
+##### `music`
+
+Generate music from prompt OR score an existing video clip.
+
+**Inputs**
+
+| Slot | Kind | Required | Notes |
+|---|---|---|---|
+| `video` | video | required for `video-background-music-v1` only | `video/mp4`, `video/webm`, `video/quicktime` |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `audio` | audio | provider-determined |
+| `timestamps` | json | `application/json` (optional) |
+
+**Cost** — `max(1, ceil(seconds × 2.2))` credits (defaults to 30s if `music_length_ms` unset).
+
+###### Model: `elevenlabs/music-v1`
+
+Compose music from a free-form prompt or a structured composition plan.
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"elevenlabs/music-v1"` |
+| `prompt` | string | no | free-form brief (exactly one of `prompt`/`composition_plan` is required — validated) |
+| `composition_plan` | json | no | structured `{ sections: [...] }` |
+| `music_length_ms` | number | no | 3000–454545 (upper bound keeps the estimate under the $10 per-node cost cap) |
+| `seed` | number | no | — |
+| `force_instrumental` | boolean | no | prompt mode only |
+| `respect_sections_durations` | boolean | no | composition_plan mode only |
+| `with_timestamps` | boolean | no | word-level timestamps |
+| `output_format` | enum | no | mp3 family only (see `tts`) |
+
+###### Model: `elevenlabs/video-background-music-v1`
+
+Score an existing video. Requires `inputs.video`.
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"elevenlabs/video-background-music-v1"` |
+| `description` | string | no | max 1000 chars |
+| `tags` | string[] | no | up to 10 style tags |
+| `output_format` | enum | no | mp3 family only (see `tts`) |
+
+---
+
+##### `dialogue`
+
+Multi-voice scripted dialogue via ElevenLabs Eleven v3.
+
+**Inputs**
+
+None.
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"elevenlabs/eleven_v3"` |
+| `inputs` | json | yes | `{ text, voice_id }[]`, 1–50 items, ≤45454 total chars (the $10 per-node cost cap) |
+| `language_code` | string | no | — |
+| `settings` | json | no | provider settings passthrough |
+| `seed` | number | no | 0–4294967295 |
+| `apply_text_normalization` | enum | no | `auto \| on \| off` |
+| `with_timestamps` | boolean | no | per-voice segment markers in `timestamps` output |
+| `output_format` | enum | no | mp3 family only (see `tts`) |
+
+**Outputs**
+
+Same as `tts`.
+
+**Cost** — `max(1, ceil(total_chars × 0.0015))` credits.
+
+---
+
+##### `sound_effect`
+
+Short SFX from a text prompt. ElevenLabs Text-to-Sound v2.
+
+**Inputs**
+
+None.
+
+**Params**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `model` | literal | yes | `"elevenlabs/eleven_text_to_sound_v2"` |
+| `text` | string | yes | SFX description |
+| `duration_seconds` | number | no | 0.5–30 |
+| `prompt_influence` | number | no | 0–1 |
+| `loop` | boolean | no | seamless loop |
+| `output_format` | enum | no | mp3 family only (see `tts`) |
+
+**Outputs**
+
+| Slot | Kind | MIME |
+|---|---|---|
+| `audio` | audio | provider-determined |
+
+**Cost** — `max(1, ceil(seconds × 2.2))` credits.
+
+---
+
+### Live discovery
+
+The tables above mirror `packages/cli/src/engine/models/registry.ts` at the time of this README write. For the always-current machine-readable schema:
+
+```bash
+baker canvas catalog | jq '.categories | keys'
+baker canvas catalog | jq '.categories.image_generate[].id'
+baker canvas catalog | jq '.categories.video_generate[]'
+```
+
+The validator surfaces unknown models / illegal aspect ratios / out-of-range params / missing required inputs with `did_you_mean` hints **before** the run starts.
+
+### Roadmap
+
+- **Multimodal `text_generate`** — Gemini Flash + Pro support image / video / audio input through OpenRouter's `messages[].content[]` array. The engine schema currently exposes text-only; a follow-up adds optional `image` / `video` / `audio` input slots and a backend handler that builds the multimodal request.
+- **`{{slot}}`-as-attachment** — once multimodal lands, `{{slot}}` in a prompt where the wired input is an `AssetRef` will splice the asset into the request as a content part (in the prompt's positional order), instead of stringifying. Today's text/`TextRef` substitution stays unchanged.
+- **Pre-flight MIME enforcement** — Stage 3 will declare a `outputMimes` set on every node and reject set-disjoint wiring before any API call. Backend already validates MIMEs at dispatch as defence-in-depth.
+
+---
+
+### Outputs on disk
+
+Every run gets its own directory:
+
+```
+./canvas/
+└── r_01KS0F8FZQ3MSBE9QNXH8E5S78/
+    ├── manifest.json                  # per-node timing, cache status, asset refs
+    ├── host_still__images__0.jpg      # image_generate, slot=images, index=0
+    ├── host_video__video.mp4          # video_generate, slot=video
+    ├── app_screenshot__images__0.jpg
+    ├── composite__video.mp4
+    └── _final.mp4                     # the canvas's declared `output` (if a file)
+```
+
+- Naming: `<node_id>__<slot>[__<index>].<ext>`.
+- `_final.<ext>` is a copy of whichever node the top-level `output` points at.
+- `manifest.json` is what `baker canvas inspect` reads — duration, cache hit/miss, asset refs, errors.
+- Default root is `./canvas/`. Override with `--outputs-dir`.
+
+---
+
+### Caching
+
+Cache key:
+
+```
+sha256(canonical({ node_id, node_version, params, input_hashes, cache_salt, extras }))
+```
+
+- Entries live in `./canvas/.cache/` (index + content-addressed blobs).
+- Cache hits re-materialize asset files into the new run dir instantly; misses execute the node and write a new entry atomically.
+- `hyperframe_*` folds a recursive sha256 of the composition directory into `extras` — edit any file in `my-composition/` and the cache busts automatically. No version bump needed.
+- If computing `extras` fails (e.g. the composition directory is unreadable), the node fails with that error — it never falls back to a partial cache key, so stale results can't be served silently.
+- Wipe a single entry: `rm canvas/.cache/index/<key>.json`. Wipe everything: `rm -rf canvas/`.
+
+Cache policies (via `--cache-policy`):
+
+| Policy | Reads | Writes |
+|---|---|---|
+| `read_write` (default) | yes | yes |
+| `read_only` | yes | no |
+| `bypass` | no | no |
+
+`read_only` executes cache misses normally but leaves the cache untouched — use it to re-run a canvas without polluting a shared or committed cache directory.
+
+---
+
+### Safety limits
+
+- **Asset size cap: 2 GiB per asset.** Applies to every download (remote node outputs, `ingest` fetches, yt-dlp output) and to local files ingested via `source: "path"`. Oversized assets fail the node with a `file_too_large` / byte-limit error.
+- **Per-request cost cap: $10 of estimated provider cost.** The backend pre-estimates cost for billable nodes (`video_generate` on Seedance, `tts`, `dialogue`, `music`, `sound_effect`) and rejects a single execution above the cap with `cost_limit_exceeded`. Split long renders or long scripts into smaller nodes.
+- **Retries never double-charge.** Every remote node execution carries a run-scoped idempotency key; if a request is retried after a transient failure, the backend replays the stored response instead of dispatching (and billing) the provider again. A fresh run (including `--cache-policy bypass`) always generates fresh.
+
+---
+
+### CLI commands
+
+#### `baker canvas validate <file.json>`
+
+Parse + schema-check + per-node deep validation (composition `meta.json` is consulted for `hyperframe_*`). Prints a structured result with a per-node cost preview. Exits non-zero on issues. Never calls Convex, never spends credits.
+
+```bash
+$ baker canvas validate my-canvas.json
+{
+  "ok": true,
+  "total_nodes": 4,
+  "estimated_credits": 8,
+  "cost_preview": [
+    { "node_id": "topic", "node_type": "text", "credits": 0 },
+    { "node_id": "headline", "node_type": "text_generate", "credits": 8 }
+  ]
+}
+```
+
+On error you get an array of `ValidationIssue`s, each with `path`, `code`, `message`, and optional `did_you_mean`.
+
+#### `baker canvas run <file.json> [flags]`
+
+Validate, then execute the graph. Blocks until done. Logs one line per node. Returns `{ ok, run_id, outputs_dir, output, stats }` on stdout.
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--cache-dir <path>` | `./canvas/.cache` | Where content-addressed bytes + cache index live. |
+| `--outputs-dir <path>` | `./canvas` | Root for per-run output directories. |
+| `--run-id <id>` | auto ULID | Override the generated run id. |
+| `--cache-policy <policy>` | `read_write` | `read_write`, `bypass`, or `read_only`. |
+
+#### `baker canvas scaffold-video <video> [flags]`
+
+Turn a reference video into a **runnable, self-validated reproduction canvas** in one command — the video counterpart of `scaffold-static-ad`. It runs **billed passes** up front:
+
+1. **`video_deconstruct`** (`~google/gemini-pro-latest`, full mode) — reverse-engineers the video into a scene-by-scene blueprint + word-level transcript, written next to the canvas as **`prompt.json`**. Each scene's `start_frame_prompt`/`end_frame_prompt` are inlined into the frame nodes (see below); `prompt.json` then rides along as the shared **global style reference** (palette, cast cohesion) and as provenance.
+2. **recurring-element selection** (`~google/gemini-flash-latest`) — picks only the **recurring, identity-critical** elements (each `global.cast` person, a recurring animal, a showcased product, the brand logo) and the scene indices each appears in. One real reference image grounds each element across **every** frame it appears in, so the same actor stays consistent the whole video.
+
+It then scaffolds the full pipeline: per scene, two **static-ad-grade frames** (`image_generate` with its **own self-contained `params.prompt`** — edit a frame node to change only that frame; `prompt.json` is wired as a demoted shared-style `target_blueprint`, a per-element reference legend, the real extracted frame as a composition anchor) → `video_generate` (Seedance first/last-frame, fed an ultra-detailed motion brief composed from the scene's action, camera, dialogue, and transcript; duration snapped to the nearest allowed clip length). Each recurring element gets **one shared `[TODO]` ingest slot** wired into every frame it appears in. Globally it casts a `voice_select` per speaker, **one continuous `tts` per speaker** (every line that speaker says concatenated into a single read, voice locked via `voice_ref`), a `sound_effect` per SFX, a `music` bed (styled after the AudD-identified track when available), then concatenates the clips, burns on the animated overlays (the `video-overlay` composition, copied next to the canvas — brand fonts via `@font-face`, plus `typewriter`/`karaoke` reveals), mixes the audio (`audio_timeline`), and muxes it under the video.
+
+The emitted canvas is validated (`validateCanvasDeep`) before it's written, so it always runs. The full editable checklist is embedded in the canvas as **`metadata.todo`** (and a step-by-step guide in `metadata.description`). stdout returns `{ ok, canvas_path, prompt_path, models, stats, checklist }` — the **checklist** lists the recurring elements (with the scenes each spans and the real source image to supply), voices to confirm, SFX/overlay counts, music status, and any scenes clamped to the 15s clip ceiling.
+
+```bash
+baker canvas scaffold-video ./reference-ad.mp4 --focus "competitor UGC ad for <brand>"
+# → writes ./reference-ad.video.canvas.json + ./prompt.json (+ video-overlay-composition/)
+# edit each frame's own params.prompt + drop ONE real source image at each el_* [TODO], confirm voices, then:
+baker canvas validate ./reference-ad.video.canvas.json
+baker canvas run ./reference-ad.video.canvas.json
+```
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--out <path>` | `<video-dir>/<name>.video.canvas.json` | Where to write the canvas (composition is copied alongside). |
+| `--frames <mode>` | `generate` | `generate` regenerates frames anchored on the originals; `reuse` wires the real extracted frames straight into the clips (faithful, cheaper). |
+| `--max-scenes <n>` | provider default | Cap the number of scenes the deconstruct emits. |
+| `--language <code>` | auto | Transcript/dialogue language hint (e.g. `fr`, `en`). |
+| `--focus <text>` | — | Known provenance/emphasis to ground the deconstruct. |
+| `--deconstruct-model <id>` | `~google/gemini-pro-latest` | Override the `video_deconstruct` model. |
+| `--select-model <id>` | `~google/gemini-flash-latest` | Override the element-selection `text_generate` model. |
+| `--image-model <id>` | `openai/gpt-5.4-image-2` | Override the per-frame `image_generate` model (defaults to the strongest, matching `scaffold-static-ad`). |
+| `--video-model <id>` | `bytedance/seedance-2.0` | Override the `video_generate` model. |
+
+The two scaffold passes are billed (the full `video_deconstruct` is the heavy one); **running** the result then generates many image/video/audio assets and is not free. Defaults to vertical 1080×1920 overlays — copy + edit the composition for other aspect ratios. For on-brand overlay type, drop `brand-bold.otf`/`brand-regular.otf` into the copied `video-overlay-composition/` dir (wired via `@font-face`, with a system fallback). Richer transcription (punctuated words + paragraphs) is available via the deconstruct's `transcriber: "deepgram"` param when `DEEPGRAM_API_KEY` is set.
+
+#### `baker canvas scaffold-static-ad <image> [flags]`
+
+Turn a source/inspiration image into a **runnable, self-validated static-ad canvas** — the static counterpart of `scaffold-video`. Like the video scaffold, this runs **billed Gemini passes** up front:
+
+1. **`image_describe`** (`~google/gemini-pro-latest`) — reverse-engineers the image into a blueprint JSON, written next to the canvas as **`prompt.json`**. This is the editable "prompt": you rewrite it by hand into the ad you want (palette, copy, claims, subjects). It feeds the generator directly — there is **no automatic brand-transform step**.
+2. **element selection** (`~google/gemini-flash-latest`) — picks only the **main, identity-critical** elements (the brand logo, a showcased product, a foreground person/animal, a trust badge); background extras are dropped. Each is stamped back onto its blueprint entry as a `reference_image` label so the JSON self-documents which slot grounds which subject.
+3. **global layout** (`~google/gemini-flash-latest`) — produces a structured `layout` block in `prompt.json`: the column/row grid, each region's `x_pct`/`y_pct` bounds, panel splits, background/shape, and every text block's relative size/weight/case/alignment. This is what gives the generator a precise composition to rebuild.
+
+It then scaffolds a canvas that ingests `prompt.json`, wires **one `[TODO]` ingest slot per detected element** (plus an optional brand-font → type-specimen) into `image_generate`, and wires the original image in for composition only. The canvas is validated before it's written. stdout returns `{ ok, canvas_path, prompt_path, models, layout_regions, stats, checklist }` — the **checklist** lists every real asset to drop in.
+
+```bash
+baker canvas scaffold-static-ad ./reference-ad.png --context "competitor ad for <brand>, <category>, <market>"
+# → writes ./static-ad.canvas.json + ./prompt.json
+# edit prompt.json into your ad + replace each [TODO] ingest path with a real file, then:
+baker canvas validate ./static-ad.canvas.json
+baker canvas run ./static-ad.canvas.json
+```
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--context <text>` | — | Known provenance (advertiser, category, market) to ground the describe. |
+| `--out <path>` | `<image-dir>/static-ad.canvas.json` | Where to write the canvas (`prompt.json` is written alongside). |
+| `--describe-model <id>` | registry default (`~google/gemini-pro-latest`) | Override the `image_describe` model. |
+| `--select-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the element-selection `text_generate` model. |
+| `--layout-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the global-layout `text_generate` model. |
+| `--gen-model <id>` | registry default (`openai/gpt-5.4-image-2`) | Override the `image_generate` model. |
+| `--aspect <ratio>` | inferred from the image, else `9:16` | Force the output aspect ratio. |
+| `--skip-font` | off | Skip the brand-font → type-specimen slot. |
+
+Scaffolding runs (and bills) the two vision passes; **running** the result generates a billed image. `baker canvas validate` does not check that the `[TODO]` paths exist — supply the real files before `run`.
+
+#### `baker canvas inspect <run_id> [--thumbnails]`
+
+One-page summary of a completed run: per-node duration + cache status, list of files in the run dir, optional video thumbnails (start/middle/end frames extracted via ffmpeg).
+
+```bash
+baker canvas inspect r_01JXYZ...
+baker canvas inspect r_01JXYZ... --thumbnails
+```
+
+Resolves the run dir against `--outputs-dir` (default `./canvas`) or accepts an absolute path. Reads `manifest.json` for per-node stats.
+
+#### `baker canvas catalog`
+
+Prints the agent-facing node + composition catalog as JSON Schema. Every node has `id`, `version`, `location`, `category`, `summary`, `inputs`/`params`/`outputs` schemas, `cost_estimate_credits`, `runtime_estimate_seconds`, and (when present) `when_to_use`. Grouped by `category`. The `compositions` array enumerates every `@baker/*` composition with its full `meta.json`.
+
+```bash
+baker canvas catalog | jq '.categories | keys'
+baker canvas catalog | jq '.compositions[].id'
+```
+
+---
+
+### Ingestion (`ingest` node)
+
+`ingest` is the on-ramp for any external asset a canvas needs. Pick a `source` (URL or local file path) and declare what kind of asset you want — `image`, `video`, `audio`, `text`, `json`, or `font`. The node figures out the right strategy:
+
+```jsonc
+// URL source — direct CDN image
+{ "id": "src", "type": "ingest", "params": { "source": "url", "url": "https://cdn.example.com/cat.png", "expect": "image" } }
+
+// URL source — YouTube video (yt-dlp)
+{ "id": "src", "type": "ingest", "params": { "source": "url", "url": "https://youtu.be/dQw4w9WgXcQ", "expect": "video" } }
+
+// URL source — YouTube audio-only (yt-dlp -x)
+{ "id": "src", "type": "ingest", "params": { "source": "url", "url": "https://youtu.be/dQw4w9WgXcQ", "expect": "audio" } }
+
+// URL source — blog post → clean markdown (Handinger)
+{ "id": "src", "type": "ingest", "params": { "source": "url", "url": "https://example.com/blog/post", "expect": "text" } }
+
+// URL source — PDF → markdown (Handinger handles PDFs)
+{ "id": "src", "type": "ingest", "params": { "source": "url", "url": "https://example.com/whitepaper.pdf", "expect": "text" } }
+
+// URL source — raw markdown file (direct fetch)
+{ "id": "src", "type": "ingest", "params": { "source": "url", "url": "https://raw.githubusercontent.com/foo/bar/README.md", "expect": "text" } }
+
+// URL source — JSON endpoint (direct fetch)
+{ "id": "src", "type": "ingest", "params": { "source": "url", "url": "https://api.example.com/data.json", "expect": "json" } }
+
+// URL source — font file for font_specimen (direct fetch; magic-byte sniffed, so octet-stream CDNs work)
+{ "id": "src", "type": "ingest", "params": { "source": "url", "url": "https://cdn.example.com/brand.ttf", "expect": "font" } }
+
+// Path source — relative path resolved against process.cwd()
+{ "id": "src", "type": "ingest", "params": { "source": "path", "path": "./inputs/headshot.png", "expect": "image" } }
+
+// Path source — absolute path used as-is
+{ "id": "src", "type": "ingest", "params": { "source": "path", "path": "/abs/work/clip.mp4", "expect": "video" } }
+```
+
+**Strategy resolution** (deterministic from `source` + `expect` + URL extension for text):
+
+| `source` | `expect`      | URL / path                       | Strategy        |
+|----------|---------------|----------------------------------|-----------------|
+| path     | any           | any                              | `local_file` — read from disk, sniff mime, upload to R2 via presign |
+| url      | video / audio | any                              | `yt_dlp` (works on platform URLs *and* direct file URLs via the generic extractor) |
+| url      | image / json / font | any                        | `direct_fetch` (HTTP GET) |
+| url      | text          | ends in `.txt` or `.md`          | `direct_fetch` |
+| url      | text          | anything else (HTML, PDF, …)     | `handinger` `/markdown` (extracted markdown — HTML/PDF made readable) |
+
+If the bytes' mime contradicts `expect` (e.g. `expect: "image"` but the URL serves `text/html`, or a `.pdf` file is passed as `expect: "image"`), the node fails with a clear `kind_mismatch` error instead of forwarding bad bytes downstream.
+
+**Params** — discriminated union on `source`. The agent picks one of two shapes:
+
+`source: "url"`:
+
+| Field    | Type                                                  | Required | Notes |
+|----------|-------------------------------------------------------|----------|-------|
+| `source` | `"url"` (literal)                                     | yes      | Discriminator. |
+| `url`    | string (must parse as `URL`)                          | yes      | `http://` or `https://`. `file://` is rejected — use `source: "path"` for local files. |
+| `expect` | `"image" \| "video" \| "audio" \| "text" \| "json" \| "font"` | yes | Declares the output port's kind. Drives strategy selection and enforces a runtime kind check. |
+
+`source: "path"`:
+
+| Field    | Type                                                  | Required | Notes |
+|----------|-------------------------------------------------------|----------|-------|
+| `source` | `"path"` (literal)                                    | yes      | Discriminator. |
+| `path`   | non-empty string                                      | yes      | Absolute or `process.cwd()`-relative filesystem path. `~/…` is rejected (no shell expansion). |
+| `expect` | `"image" \| "video" \| "audio" \| "text" \| "json" \| "font"` | yes | Same as the url arm. |
+
+**Inputs:** none (`{}` — strict). `ingest` is a source node; it has no upstream slots.
+
+**Output:** `{ asset: AssetRef }`. `asset.kind === params.expect` always — guaranteed statically (the engine's `outputKinds` resolver exposes this to validators / dashboard before the node runs) and at runtime (any mismatch throws `kind_mismatch`).
+
+`AssetRef` shape (returned for every successful run):
+
+```ts
+{
+  kind:    "image" | "video" | "audio" | "text" | "json" | "font",
+  sha256:  string,                            // content hash; identical bytes always yield the same sha
+  mime:    string,                            // e.g. "image/jpeg", "video/mp4", "text/markdown"
+  url:     string,                            // public R2 URL (stable, content-addressed)
+  path:    string,                            // local CLI cache path — downstream local nodes read from this
+  metadata: {
+    // url-sourced assets:
+    source_url?:  string,                     // the URL the agent passed in
+    // path-sourced assets:
+    source_path?: string,                     // absolute resolved path
+    file_size?:   number,                     // bytes
+    original_filename?: string,               // basename of the source path
+
+    strategy:     "direct_fetch" | "handinger" | "yt_dlp" | "local_file",
+    ingested_at:  string,                     // ISO 8601 timestamp
+
+    // yt-dlp adds (when available from --dump-json):
+    original_title?:        string,
+    original_uploader?:     string,
+    original_duration_s?:   number,
+    webpage_url?:           string,
+    width?:                 number,
+    height?:                number,
+
+    // Handinger adds:
+    word_count?:            number,
+  },
+
+  // Kind-specific dimensions (when known, populated by downstream metadata sniffing):
+  width?:        number,   // image, video
+  height?:       number,   // image, video
+  duration_ms?:  number,   // video, audio
+}
+```
+
+The `url` is a stable R2 URL — remote downstream nodes (e.g. `video_lipsync`) fetch from it. The `path` is the local cache file — local downstream nodes (e.g. `ffmpeg`, `video_transcribe`) read from it directly. Both are populated for every `ingest` output.
+
+**Errors:**
+
+| Code                  | Source         | When                                                                         |
+|-----------------------|----------------|------------------------------------------------------------------------------|
+| `INVALID_PARAMS`      | engine validator | Missing/malformed fields, mixing `url` + `path`, unknown `source`, unknown `expect`. |
+| `kind_mismatch`       | url + direct_fetch | URL returned bytes whose mime doesn't match `expect`. Message: `ingest expect=<X> but <url> returned <mime> (kind=<Y>)`. |
+| `kind_mismatch`       | path + local_file | File mime (from extension or magic-byte sniff) doesn't match `expect`, *or* mime doesn't map to any of our kinds (e.g. local PDFs aren't supported as `text` — host them via URL for Handinger to extract). |
+| `provider_error`      | url + handinger / direct_fetch | Handinger `/markdown` non-2xx, or upstream `fetch` non-ok. |
+| `file_not_found`      | path + local_file | `stat()` returned `ENOENT`. Error names the absolute resolved path. |
+| `not_a_file`          | path + local_file | Path exists but is a directory / block device / socket. |
+| `permission_denied`   | path + local_file | `stat()` or `readFile()` returned `EACCES`. |
+| local exec error      | url + yt_dlp   | `yt-dlp` exited non-zero — full stderr surfaced verbatim (last ~40 lines). |
+| `network`             | url            | HTTP timeout, DNS failure, presigned R2 PUT failure. |
+
+All execution-time failures flow through `NodeExecutionError` so they appear in the run output's structured error envelope. The yt-dlp stderr passthrough is important: bot-checks, geo-blocks, age-gates, and outdated-binary errors all come through as the original yt-dlp message. If a YouTube ingest fails with "No video formats found" or "Sign in to confirm you're not a bot", run `yt-dlp -U` to update.
+
+**Validation note** — `baker canvas validate` does **not** check that path-sourced files exist on disk. Validation runs without filesystem state (e.g. on CI, in dashboard previews). Missing files surface as `file_not_found` at execute time with the full resolved path in the message.
+
+**Caching:**
+
+- **Content-addressed dedup is automatic.** Two `ingest` runs that produce identical bytes share the same R2 object and the same local cache shard (keyed by sha256).
+- **Engine-level cache** (`canvas/.cache/index/`) keys by node params + node version + node-supplied cache extras. Re-running the same canvas with the same params is a cache hit and skips the network/yt-dlp/local-read entirely.
+- **yt-dlp version is folded into the cache key** for `source: "url"` with `expect: video | audio`. Upgrading yt-dlp busts the cache automatically, since new versions can produce different bitstreams.
+- **Local file `mtime + size` is folded into the cache key** for `source: "path"`. Editing the file (any save bumps mtime) invalidates the cache so you get fresh ingestion. mtime+size is cheap to read at validate time; for cases where mtime is unreliable (`cp -p`, content-only changes), force-bypass with `--cache-policy bypass` or change the canvas's `cache_salt`.
+- **No TTL.** Handinger and direct fetch don't cache-bust on page changes — if the source page updates, use `--cache-policy bypass` or change `cache_salt`.
+
+**Local files (`source: "path"`):**
+
+- **Path resolution:** absolute paths are used as-is; relative paths resolve against `process.cwd()` (the directory you ran `baker canvas run` from). `~/…` is **not** expanded — use an absolute path instead.
+- **Reproducibility caveat:** canvas JSONs using `source: "path"` are **not portable** — moving the canvas to a different machine without the same files at the same paths will fail at execute time. Pick `source: "url"` for portable canvases; pick `source: "path"` for local convenience.
+- **Mime / kind inference:** primary signal is the file extension (`.png`, `.mp4`, `.m4a`, `.mp3`, `.wav`, `.json`, `.md`, `.txt`, `.csv`, `.html`, …). For images without an extension, a magic-byte sniff catches PNG/JPEG/GIF/WebP. Unknown mimes (or mimes that don't map to a kind, like `application/pdf`) fail with `kind_mismatch`.
+- **R2 upload:** local files are uploaded to R2 via the same presign flow yt-dlp uses, so remote downstream nodes (e.g. `image_background_remove`) can fetch by URL just like with URL-sourced assets. `asset.url` is always populated.
+- **Big files:** no explicit size cap. Files >500 MB are slow due to presign + PUT bandwidth — if that's a concern, host them on a CDN and use `source: "url"`.
+
+**Composition** — `ingest` produces bytes and stops there. For richer pipelines, chain it:
+
+```
+ingest { source: "url",  expect: "video" } → video_transcribe          # YouTube → word-level Whisper transcript
+ingest { source: "url",  expect: "text"  } → text_generate             # Blog post / PDF → summary
+ingest { source: "url",  expect: "image" } → image_background_remove   # CDN image → transparent PNG
+ingest { source: "path", expect: "image" } → image_background_remove   # Local PNG → transparent PNG
+ingest { source: "path", expect: "video" } → video_transcribe          # Local mp4 → transcript
+```
+
+**Requirements:**
+
+- `yt-dlp` and `ffmpeg` on PATH for `source: "url"` with `expect: "video" | "audio"` (already in the E2B sandbox image; install locally with `pip install yt-dlp` and `brew install ffmpeg` / equivalent).
+- `HANDINGER_API_KEY` on the Convex backend for `source: "url"` with `expect: "text"` on non-`.md`/`.txt` URLs.
+- No additional dependencies for `source: "path"` — just filesystem access.
+
+**Cost:** zero engine credits for direct_fetch + yt_dlp. Handinger charges per scrape on your Handinger account (configured outside Baker).
+
+---
+
+### Local CLI nodes
+
+`ffmpeg` and `imagemagick` are pure CLI passthroughs. You write the argv you'd type at the terminal, declare what files come in and what files go out, and the engine handles staging, execution, and ingestion. No `op` discriminator, no flag modeling — anything the binary can do, the node can do.
+
+**Shape (identical for both nodes):**
+
+```jsonc
+{
+  "id": "thumb",
+  "type": "ffmpeg",
+  "inputs": { "video": "$ref:clip.video" },
+  "params": {
+    "args": ["-y", "-i", "{{in.video}}", "-ss", "1", "-frames:v", "1", "{{out.thumb}}"],
+    "outputs": { "thumb": { "kind": "image", "ext": "png" } }
+  }
+}
+```
+
+**How the engine runs it (in order):**
+
+1. **Stages inputs.** Every entry of `inputs` is copied into a per-node tmp dir. Single AssetRef → `{{in.<slot>}}`. AssetRef array → `{{in.<slot>.0}}`, `{{in.<slot>.1}}`, …
+2. **Allocates outputs.** Each `params.outputs` entry gets a tmp path with the declared `ext`. Reference it as `{{out.<name>}}` in `args`.
+3. **Spawns argv.** `spawn(bin, substitutedArgs)` — no shell, no string interpolation outside the placeholder system.
+4. **Captures stderr.** On non-zero exit, throws with the last ~40 lines of stderr for debugging.
+5. **Validates outputs.** Every declared output file must exist and be non-empty.
+6. **Ingests outputs.** Each declared output is added to the asset store with its `kind` (`"image" | "video" | "audio"`) and materialized into the run dir like any other node's outputs.
+
+**Placeholder rules (the safety contract):**
+
+| Allowed in `args` | Rejected at execute time |
+|---|---|
+| `{{in.<slot>}}` / `{{in.<slot>.<index>}}` / `{{out.<name>}}` | Raw absolute paths outside the staging tmp dir (e.g. `/etc/passwd`) |
+| Flags, values, filter graphs (`-i`, `scale=1080:1920`, `[0:v][1:v]vstack`, `30000/1001`) | URL-style inputs (`http://…`, `file://…`, `data:…`) |
+| Substituted placeholders resolving under the staging dir | Home-relative (`~/…`) or relative (`./…`, `../…`) paths |
+
+Why: with raw paths allowed, two runs with the same `args` but different `/local/file.png` would share a cache key and produce different outputs. Placeholders force every input through the engine's content-addressed asset model, which the cache key actually sees.
+
+**Cache key includes** node params, every input's hash, and the tool's `-version` first line (so upgrading `ffmpeg`/`magick` busts the cache automatically).
+
+**Worked examples:**
+
+```jsonc
+// ffmpeg — extract a thumbnail from a video at t=1s
+{
+  "type": "ffmpeg",
+  "inputs": { "video": "$ref:clip.video" },
+  "params": {
+    "args": ["-y", "-i", "{{in.video}}", "-ss", "1", "-frames:v", "1", "{{out.thumb}}"],
+    "outputs": { "thumb": { "kind": "image", "ext": "png" } }
+  }
+}
+
+// ffmpeg — concat two clips via the concat demuxer's filter syntax
+{
+  "type": "ffmpeg",
+  "inputs": { "clips": ["$ref:v1.video", "$ref:v2.video"] },
+  "params": {
+    "args": [
+      "-y",
+      "-i", "{{in.clips.0}}",
+      "-i", "{{in.clips.1}}",
+      "-filter_complex", "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]",
+      "-map", "[v]", "-map", "[a]",
+      "{{out.video}}"
+    ],
+    "outputs": { "video": { "kind": "video", "ext": "mp4" } }
+  }
+}
+
+// imagemagick — resize an image to fit-cover 1080x1920
+{
+  "type": "imagemagick",
+  "inputs": { "image": "$ref:photo.image" },
+  "params": {
+    "args": [
+      "{{in.image}}",
+      "-resize", "1080x1920^",
+      "-gravity", "center",
+      "-extent", "1080x1920",
+      "{{out.result}}"
+    ],
+    "outputs": { "result": { "kind": "image", "ext": "jpg" } }
+  }
+}
+```
+
+**Requirements:** `ffmpeg` on PATH for the `ffmpeg` node; `magick` (v7+) or `convert` (v6) on PATH for the `imagemagick` node. The node fails with a clear message if neither is available.
+
+**Cost:** zero credits (local execution).
+
+---
+
+### Authoring compositions
+
+`hyperframe_render` and `hyperframe_snapshot` render custom HTML/CSS compositions to video or PNG. Point `params.composition` at a directory containing two files:
+
+#### Directory structure
+
+```
+my-composition/
+├── index.html   # HTML/CSS/JS template with {{variable}} placeholders
+└── meta.json    # Declares dimensions, inputs, and params
+```
+
+#### `meta.json`
+
+Declares what the composition accepts:
+
+```json
+{
+  "id": "my-overlay",
+  "title": "Text overlay on a background image",
+  "width": 1080,
+  "height": 1920,
+  "fps": 30,
+  "default_duration": 3,
+  "inputs": {
+    "background": {
+      "kind": "image",
+      "required": true,
+      "staged_as": "background.png",
+      "description": "Full-bleed background image."
+    }
+  },
+  "params": {
+    "headline": {
+      "kind": "string",
+      "required": true,
+      "description": "Text to render."
+    },
+    "font_size": {
+      "kind": "integer",
+      "min": 24,
+      "max": 300,
+      "default": 128
+    },
+    "text_color": {
+      "kind": "color",
+      "default": "#ffffff"
+    }
+  }
+}
+```
+
+**`inputs`** — keyed assets staged into the render directory. Each declares a `kind` (`image`, `video`, `audio`), whether it's `required`, and the filename it's staged as (`staged_as`). Reference staged files by filename in your HTML (e.g. `<img src="background.png" />`).
+
+**`params`** — variables substituted into HTML/CSS/JS via `{{var}}` before render. Supported kinds: `string`, `integer`, `number`, `color`, `json`. The canvas passes every variable as a **primitive in `params`** — no `variables` blob, no `JSON.stringify`. The engine inlines arrays/objects as valid JS literals.
+
+#### `index.html`
+
+Standard HTML with `{{variable}}` placeholders that get substituted from params:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <script src="./gsap.min.js"></script>
+    <style>
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body { width: 1080px; height: 1920px; overflow: hidden; }
+      .bg { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+      .text {
+        position: absolute; inset: 0;
+        display: flex; align-items: center; justify-content: center;
+        font-size: {{font_size}}px;
+        color: {{text_color}};
+        font-weight: 900;
+        text-align: center;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="main" data-start="0"
+         data-duration="{{duration}}" data-width="1080" data-height="1920">
+      <img class="bg" src="background.png" alt="" />
+      <div class="text">{{headline}}</div>
+    </div>
+    <script>
+      (() => {
+        var tl = gsap.timeline({ paused: true });
+        tl.to({}, { duration: 0.01 }, 0);
+        window.__timelines = window.__timelines || {};
+        window.__timelines.main = tl;
+      })();
+    </script>
+  </body>
+</html>
+```
+
+#### Using in a canvas
+
+```jsonc
+{
+  "id": "overlay",
+  "type": "hyperframe_snapshot",
+  "inputs": { "background": "$ref:person_image.images#0" },
+  "params": {
+    "composition": "./my-composition",
+    "headline": "HELLO WORLD",
+    "font_size": 128,
+    "text_color": "#ffffff"
+  }
+}
+```
+
+For video rendering, use `hyperframe_render` instead — same composition format, outputs video instead of PNG.
+
+#### Guardrails
+
+- **GSAP timeline required.** Register a root timeline at `window.__timelines["main"]` — even for static snapshots, use a no-op timeline.
+- **Element IDs.** Every overlay element gets an `id` attribute. `<audio>` / `<video>` elements MUST have an `id` or the renderer drops them silently.
+- **Reserved `duration` param.** Never declare a param called `duration` — the engine injects it automatically from the input video's duration (or `default_duration` for snapshots).
+- **GSAP animations.** Use `gsap.set()` for visibility transitions — `fromTo(opacity)` silently fails under Hyperframes' screenshot capture.
+- **Single root timeline.** `window.__timelines["main"]` only. Sub-composition timelines aren't scrubbed.
+- **Cache invalidation.** The composition directory is hashed recursively; editing any file invalidates the cache automatically.
+
+---
+
+### Bundled canvases & compositions
+
+A few end-to-end canvases ship with the CLI under `packages/cli/canvas/`:
+
+- **`hello-world-overlay.json`** + `hello-world-composition/` — minimal "image + text overlay → png" demo.
+- **`avocado-tutorial.json`** + `tiktok-captions-composition/` — full "persona → first/last frame → Veo video → transcribe → TikTok captions" pipeline.
+#### `phone-scroll-composition`
+
+Non-linear vertical scroll of a tall app screenshot, driven by a GSAP timeline. Inputs: one tall image (`image`, required, staged as `screenshot.png`). Key params:
+
+- **`timeline`** (json, required) — array of `{at: seconds, y: pixels, ease?: gsap-ease, label?: string}` keyframes. Direction changes are just keyframes going the other way. `ease: "none"` between two equal-y keyframes produces a pause. The first keyframe sets the starting position (instant); subsequent keyframes animate from the previous one.
+- **`taps`** (json, optional) — array of `{at: seconds, x: "NN%"|"NNpx", y: "NN%"|"NNpx", kind?: "tap"|"long-press"}` finger-tap ripple overlays.
+- **`background_color`**, **`tap_color`** — visual tuning.
+
+Output is a 720×1280 MP4 (modern phone aspect) intended to feed straight into an `ffmpeg` chromakey filter graph as the `app` overlay.
+
+---
+
+### Programmatic use
+
+The engine library is also exposed for embedding inside another Node program:
+
+```ts
+import { createEngineFromEnv, ValidationError } from "@koda-sl/baker-cli/engine";
+
+const engine = createEngineFromEnv({ log: console.log });
+try {
+  const result = await engine.run(canvasJson, { cache_policy: "read_write" });
+  console.log(result.run_id, result.stats);
+} catch (e) {
+  if (e instanceof ValidationError) console.error(e.issues);
+  else throw e;
+}
+```
+
+For full control (custom asset store, custom fetch, in-memory cache, etc.) the lower-level building blocks are also exported:
+
+```ts
+import {
+  Engine, BackendClient, LocalAssetStore, LocalCacheStore, defaultRegistry,
+} from "@koda-sl/baker-cli/engine";
+```
+
 ## Help & Discovery
 
 Every command supports `--help` for usage info: