@koda-sl/baker-cli 0.393.0-dev.799d3f88c → 0.393.0

package/README.md

@@ -106,16 +106,10 @@ offered, so a short option is never pointed at an unrelated one (`--from` at `--
 Previously such an option was accepted and ignored, so a call that
 looked like it had filtered or narrowed a result was in fact answering the unfiltered
 question — and nothing in the output said so. Both spellings of an option work
-(`--run-id` and `--runId`), as they always did. The error's `fix` names the exact call
+(`--run-id` and `--run-id`), as they always did. The error's `fix` names the exact call
 that lists every option: `baker schema <command>` (`check_schema`) when the command
 registers a schema, `baker <command> --help` (`check_help`) when it does not.
 
-### Unknown commands are refused
-
-A subcommand that does not exist (say, `scaffold` under `baker canvas`) stops with `UNKNOWN_COMMAND`
-and exit code 1, naming the real commands closest to it and every command the parent
-has, instead of printing the parent's help screen. Nothing runs.
-
 ### Narrowing a result: `--fields`
 
 `--fields a,b,c` works on every command that prints the JSON envelope. It keeps only
@@ -3207,7 +3201,7 @@ Search the **ad-dna** corpus of scored "winning" competitor ads for reference cr
 
 ### `baker winning-ads search <query>`
 
-Semantic search (dense recall + BM25 + rerank) → `POST /api/ad-library/winners/search`. The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`; plus top-level `pool_size`, `match_confidence` (`high|medium|low`), and `below_floor_count` (matches dropped under the relevance floor). `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
+Semantic search (dense recall + BM25 + rerank) → `POST /api/ad-library/winners/search`. The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`, and `visual` (what the viewer sees) + `container` (a static's layout pattern) when known; plus top-level `pool_size`, `match_confidence` (`high|medium|low`), and `below_floor_count` (matches dropped under the relevance floor). `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `mechanism`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
 
 > `media_url` is the creative itself: for `static` it's the image, for `video` it's the video file. ad-dna stores **no separate poster** for videos, so a video result has only the video URL.
 
@@ -3220,6 +3214,10 @@ baker winning-ads search "B2B lead gen demo" --platform linkedin --format video
 baker winning-ads search "fintech onboarding" --exclude-advertiser adv_ourbrand,adv_usedbefore --output md
 # Similar-to a reference ad, recent only:
 baker winning-ads search --ref-ad-id a_12345 --first-seen-after 2026-01-01T00:00:00Z --limit 5 --output md
+# One varied reference per concept (different brands, containers, hooks) in one call:
+baker winning-ads search "meal kit for busy parents" --scope followed-first --diverse --limit 5 --output md
+# The best proven ads in one container, from any category (no query needed):
+baker winning-ads search --format-pattern comparison_table --platform meta --output md
 ```
 
 | Flag | Purpose |
@@ -3238,6 +3236,8 @@ baker winning-ads search --ref-ad-id a_12345 --first-seen-after 2026-01-01T00:00
 | `--country <list>` / `--language <list>` | Filter by country / language codes |
 | `--first-seen-after` / `--first-seen-before` | ISO datetime bounds (recency) |
 | `--hook-archetype <list>` | Narrow to ads on a proven hook **seed** (from `winning-ads hooks`) |
+| `--format-pattern <list>` | Narrow to statics in these containers (from `winning-ads formats`, e.g. `comparison_table`) |
+| `--diverse` | One varied page (different brands, containers, hooks) instead of rank order; ignores paging |
 | `--output json\|md\|files` | Output format (default json) |
 | `--full` | Include DNA detail + longevity |
 
@@ -3246,16 +3246,17 @@ Reading the scores: **`relevance`** (0–1) = match of the creative to your quer
 ### `baker winning-ads hooks|mechanisms|formats`
 
 Read the **winner-weighted rollup** of the ad-dna corpus → `GET /api/ad-library/seed-catalog` — the hook /
-mechanism / static-format patterns that actually win, ranked by `winner_score`, keyed on the closed seeds/enums
-the extractor emits (no clustering). Ground a creative in a **proven** pattern for the exact segment instead of
-guessing. (Distinct from `winning-ads patterns`, which contrasts two ad cohorts.)
+mechanism / static-format patterns that actually win, ranked by `winner_score` among the ads of the segment you
+pass (`--platform`, `--awareness`, `--industry`; an unset one means any), keyed on the closed seeds/enums the
+extractor emits (no clustering). Ground a creative in a **proven** pattern for the exact segment instead of
+guessing. The rollup is recomputed daily. (Distinct from `winning-ads patterns`, which contrasts two ad cohorts.)
 
 ```bash
 # Top winning hook seeds for problem-aware SaaS on Meta:
 baker winning-ads hooks --platform meta --awareness problem_aware --industry saas --output md
 # Then narrow a reference search to that proven hook:
 baker winning-ads search "onboarding demo" --hook-archetype callout --output md
-# Also: mechanisms (persuasion), formats (static ad layouts):
+# Also: mechanisms (how the product claims to work, not the ad's device), formats (static ad layouts):
 baker winning-ads mechanisms --platform linkedin --output md
 baker winning-ads formats --awareness solution_aware --output md
 ```
@@ -3933,7 +3934,7 @@ baker studio animate "she keeps walking, camera stays with her, then she stops a
 - **480p / 720p only** — 1080p and 4K are real Seedance tiers but not on this route.
 - **Sound costs nothing extra** here, unlike every other model that offers it.
 - **No watermark** unless `--watermark` asks for one; it cannot be removed after the render.
-- **No people from an uploaded picture.** A privacy pre-check refuses any recognisable face in the input image — invented characters included, and images from ByteDance's own image model included. Clips that hit it are re-rendered automatically on Gemini Omni (reference mode) or Veo (frame mode).
+- **No people from an uploaded picture.** A privacy pre-check refuses any recognisable face in the input image — invented characters included, and images from ByteDance's own image model included. A reference-mode clip that hits it is re-rendered automatically on the same model through a second route that accepts faces (about twice the price); a frame-mode clip is reported as refused and never moved to another model — re-run it on Veo.
 
 | Flag | Description |
 |---|---|
@@ -4073,7 +4074,7 @@ baker canvas set-prompt my-canvas.json s0_start --text-file ./hook-frame.txt
 `baker canvas scaffold-ad` renders everything with a known, fixed appearance locally,
 because a video model garbles a wordmark every time:
 
-- **`brand.logo`** — the repo path to the mark. It is copied into the overlay composition
+- **`brand.logo`** — the repo path to the mark. It is copied into the caption composition
   and drawn as a real `<img>`: small top-left for the whole ad, large on the closing card.
 - **`end_card`** — on by default whenever the spec carries a brand. The last beat's PICTURE
   becomes a flat brand colour plate (rendered by ffmpeg, not generated), with the mark and
@@ -4093,9 +4094,24 @@ because a video model garbles a wordmark every time:
   alongside the music bed. Most beats should not have one: it belongs where the picture
   shows a specific physical event (a drill, a door, rain on glass), not on a talking head
   or a calm lifestyle shot. A bed plus two well-placed effects beats eight.
-- **A real brand mark is required.** `scaffold-ad` refuses to build without one in
-  `src/brand/logos/` (SVG or PNG): the mark is drawn on every frame and on the closing
-  card, so a stand-in ships an ad wearing the wrong brand.
+- **The logo is optional.** With no mark in `src/brand/logos/` (and none confirmed for the
+  company's own domain), the ad is built without the corner mark, and one hint says so and
+  how to add one: put the client's logo file in `src/brand/logos/` and re-run. Meta shows
+  the page name and picture above every ad either way. The closing card still carries the
+  call to action when the spec has a `cta`; with neither a mark nor a `cta`, the last beat
+  keeps its footage. A typed stand-in (an SVG wordmark in live `<text>`) is still refused,
+  and `--no-brand` still means no brand layer at all: no mark and no closing card.
+- **Captions and the mark sit inside the safe area.** On 9:16 the caption cards end above
+  the bottom 37% of the frame (Reels covers the bottom 35%) and the mark starts below the
+  top 16% (the Stories and Reels header); 4:5 and 1:1 use modest feed margins. The closing
+  card is centred in the same area. Every composition is sized to the spec's
+  `format.aspect_ratio`, so a 4:5 ad lays its captions out on a 4:5 frame.
+- **Captions and the closing button are set in the brand's face**: a font file in
+  `src/brand/fonts/`, else the typeface `tokens.json` or `BRAND.md` names, loaded as a web
+  font. With neither, they keep the default heavy sans.
+- **A spoken ad's captions print the script.** The voice track is transcribed only to time
+  the words: each caption word is the `say` line as written, at the moment it was said, so
+  a word the recogniser mishears never reaches the screen.
 - **An avatar with no pinned voice cannot speak on camera.** Their lines would be read by
   a separately cast voice, which is dubbing and looks like it.
 - **`voiceover: false`** — a music-led ad. No voice, no transcription: the `say` lines
@@ -4110,6 +4126,13 @@ because a video model garbles a wordmark every time:
 
 Each of these also removes a generation: the closing beat costs no image and no clip.
 
+**The spec is kept, and the canvas is checked.** `scaffold-ad` writes the spec it built
+from beside the canvas as `ad.spec.json` (with the cast it resolved), so a later change
+edits that file and re-runs with `--spec` on it and the same `--slug`. With `--slug` it
+also writes the creative's `_definition.md` and syncs its workflow graph, as
+`scaffold-video` does. The canvas is validated before the command reports success: a
+blocking issue is recorded in the canvas and the command exits `2` with the issues.
+
 #### The finished video is reviewed
 
 When a run's output is a video, `baker canvas run` samples twelve frames across it and
@@ -4200,6 +4223,8 @@ The top-level `output` declares the canvas's final result — the engine returns
 
 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.
 
+A node may also carry `tags` (`{ scene?, role?, region?, on_camera? }`) stating what it is in the ad (scene 3, region 1, the presenter's clip, the spine). `scaffold-video` stamps them and `canvas validate` reads them in place of id conventions like `s3_r1_clip`. They are descriptive only: tags never enter the cache key, so adding or editing them never re-renders or re-bills a node. Canvases without tags validate as they always did.
+
 `baker canvas catalog` prints a one-line index of every node; `baker canvas catalog --node <id>` prints that node's always-current machine-readable schema (params, inputs, outputs, every model), and `--full` prints every node's. The tables below mirror the catalog at time of write.
 
 In every table:
@@ -4254,6 +4279,44 @@ Local ffmpeg passthrough. Write the argv you'd type, declare outputs, the engine
 
 ---
 
+##### `video_concat`
+
+Join clips and stills into one continuous video: the spine of a video ad. Every input is normalized onto one raster (size, frame rate, square pixels, `yuv420p`), cut or held to its timeline length, and joined with hard cuts or `xfade` transitions. Local ffmpeg, free. Because the length and size live in params, `canvas validate` sums the spine against the timeline (`VIDEO_TIMELINE_TOTAL_MISMATCH`) before anything renders.
+
+**Inputs:** one video or image per clip, wired as `c0`, `c1`, … in timeline order (deep validation flags a missing or extra slot).
+
+**Params:**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `width`, `height` | integer | yes | output raster; must be even (libx264 `yuv420p` rejects odd sizes) |
+| `fps` | integer | no | default `30` |
+| `seam_dedup` | `head` \| `tail` \| `off` | no | default `head`: which copy of a repeated splice frame survives on a `continues_frame` clip; the timeline length never changes |
+| `clips` | array | yes | per clip: `duration_s` (its timeline length), `length` (`source` default: play as rendered; `trim`: cut out of a longer input from `offset_s`; `still`: hold an image), `fit` (`fill` default crops, `pad` letterboxes a screenshot), `transition` (`{ type, duration_s }`, the xfade out of this clip; the clip carries that much extra footage), `continues_frame` |
+
+The joined length is the sum of the clips' `duration_s` (a `source` clip counts what is wired into it). **Outputs:** `video` (mp4).
+
+---
+
+##### `av_mux`
+
+Put the soundtrack under a finished picture: the last step of a video ad. The video is stream-copied, the audio loudness-normalized, upmixed to stereo and encoded to AAC. Local ffmpeg, free.
+
+**Inputs:** `video`, `audio`.
+
+**Params:**
+
+| Name | Type | Required | Notes |
+|---|---|---|---|
+| `loudnorm` | `{ i, tp, lra }` \| `false` | no | default `{ i: -14, tp: -1.5, lra: 11 }` (the social target); `false` keeps the mix level |
+| `audio_bitrate` | string | no | default `"192k"` |
+| `sample_rate` | integer | no | default `48000` |
+| `length` | `"shortest"` \| `{ total_s }` | no | default `shortest`: end with the shorter stream; `{ total_s }` cuts both at that second |
+
+**Outputs:** `video` (mp4).
+
+---
+
 ##### `imagemagick`
 
 Local ImageMagick passthrough. Identical schema and safety contract to `ffmpeg`; uses `magick` (v7+) or `convert` (v6) on PATH.
@@ -4488,7 +4551,7 @@ No `image_size`: OpenAI derives the pixel dimensions from the ratio, so a size i
 
 ###### Model: `openai/gpt-5.4-image-2` (legacy)
 
-Kept only so canvases authored before the gpt-image-2 switch still validate and re-run unchanged — `baker canvas rerun` replays a recorded canvas verbatim. It keeps the full standard ratio set (including `4:5` / `5:4`) and still accepts `image_size`, which the provider ignores. Prefer `openai/gpt-image-2` for anything new.
+Kept only so canvases authored before the gpt-image-2 switch still validate and re-run unchanged — `baker canvas run --slug` replays a recorded canvas verbatim. It keeps the full standard ratio set (including `4:5` / `5:4`) and still accepts `image_size`, which the provider ignores. Prefer `openai/gpt-image-2` for anything new.
 
 ###### Model: `google/gemini-3.1-flash-image` (legacy id `google/gemini-3.1-flash-image-preview` still accepted)
 
@@ -4842,7 +4905,7 @@ Accepted ref-image MIMEs vary by model — see per-model sections below.
 |---|---|---|
 | `video` | video | `video/mp4` |
 
-**Cost** — 50 credits estimate per call.
+**Cost** — priced per model from the shared contract table (duration x resolution x audio; the fal route and source-clip premium when they apply), the same table the backend charges from. One clip may not cost more than $20: the backend refuses a dearer one before it runs, and no clip the registry allows reaches it.
 
 ---
 
@@ -4906,7 +4969,7 @@ Ref-image MIMEs: `image/png`, `image/jpeg`, `image/webp`.
 |---|---|---|---|
 | `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) |
+| `duration` | enum | no | every whole second `4`-`15` |
 | `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 |
@@ -4949,18 +5012,18 @@ Ref-image MIMEs: `image/png`, `image/jpeg`, `image/webp`, `image/gif` (via OpenR
 
 > **Switching a clip's model has cross-node constraints** — validate after every model edit. `validate` gates all of these before any billed run:
 > - **One aspect_ratio for the whole canvas.** Every `video_generate` node must agree (`VIDEO_ASPECT_MISMATCH`), or the composite silently crops/letterboxes. Switching one clip to Veo (which only offers `16:9`/`9:16`) forces every other clip to a shared ratio too.
-> - **`duration` is a per-model hard enum.** Seedance `4,5,6,8,10,12,15`; Veo `4,6,8` only. A value outside the model's set is rejected; a scene whose natural span exceeds the model's max is flagged (`VIDEO_SPAN_EXCEEDS_MODEL`, advisory) — a 9.2s scene can't fit Veo's 8s cap and would truncate; split the scene or keep it on a longer-max model.
+> - **`duration` is a per-model hard enum.** Seedance 2.0 `4`-`15`, Seedance 2.5 `4`-`30`, Kling `3`-`15`, Omni `3`-`10`, Veo `4,6,8` only. The scaffolders snap clip lengths to the same registry sets. A value outside the model's set is rejected; a scene whose natural span exceeds the model's max is flagged (`VIDEO_SPAN_EXCEEDS_MODEL`, advisory) — a 9.2s scene can't fit Veo's 8s cap and would truncate; split the scene or keep it on a longer-max model.
 > - **`person_generation` differs.** Veo **image-to-video** accepts only `allow_adult` (the sole legal value for keyframe-driven modes, and the only one permitted in the EU/UK); `allow_all` is text-to-video only. The scaffolder sets `allow_adult` on every Veo clip automatically (`VIDEO_PERSON_GENERATION_MISSING` warns if it's missing on a hand-edited canvas).
 >
 > A scaffolded canvas carries this table inline at `metadata.todo.model_constraints`.
 
-> **Per-model prompt & param profiles (applied automatically).** The scaffolder shapes each clip/frame prompt to the model's documented best practice and sets its request-param levers — see `packages/cli/src/engine/scaffold/lib/prompt-profiles.ts`:
+> **Per-model prompt & param profiles (applied automatically).** The scaffolder shapes each clip/frame prompt to the model's documented best practice and sets its request-param levers — see `packages/cli/src/engine/lib/prompt-profiles.ts`:
 > - **Seedance 2.0** (default video): dialogue in quotes with delivery in **prose** (not `[brackets]`), a `Preserve the composition and colors` keyframe hold, and an **affirmative** stability tail — `Keep it clean and stable: crisp anatomically-correct hands, one consistent face, smooth steady motion` — instead of an `Avoid: …` list (Seedance has no `negative_prompt` param, and inline negation tends to summon the artifact it names). Prompt kept to the ~120-word quality budget (`VIDEO_PROMPT_OVER_BUDGET` warns past ~120).
 > - **Veo 3.1** (fallback): `person_generation=allow_adult` + a caption-suppressing `negative_prompt` set as params; durations snapped to `{4,6,8}`.
 > - **gpt-image** (default frames): clean-plate exclusions placed **LAST** (OpenAI weights early text as composition), an explicit `photorealistic` cue, identity-critical reference **first**, and `quality=high` (gpt-image-2 forces high input fidelity automatically — the `input_fidelity` param is deliberately **not** sent). Gemini keeps exclusions inline; Recraft drops the photoreal cue.
 > - New advisories: `VIDEO_RAW_FACE_KEYFRAME` (a Seedance clip animating a RAW ingested image — real-person 422 risk), `IMAGE_PROMPT_PROFILE_MISSING`, `VIDEO_PROMPT_PROFILE_MISSING`.
 
-> **Content-policy blocks are deterministic, not flaky — and now auto-recover.** ByteDance's Seedance rejects any first/last frame that reads as a real-person likeness (even an AI-generated face) — surfaced as `content_policy_blocked` (HTTP 422/`E005` "flagged as sensitive", **non-retryable on the same model**). This is ByteDance's upstream filter, so it fires on **any** reseller (Replicate or otherwise) — a provider swap does **not** route around it. **When a Seedance `video_generate` clip is blocked, the backend automatically re-renders that same clip on `google/veo-3.1-fast` (`person_generation: allow_adult`) — the one curated model that clears the filter — so the run still completes.** The Seedance attempt is never billed (its output was never finalized); only the Veo render is charged. To skip that wasted first attempt entirely (and control look/cost), scaffold a photoreal-cast ad directly on Veo up front (`--real-face`, which also covers AI-generated photoreal faces), or make the source frame less photorealistic.
+> **Content-policy blocks are deterministic, not flaky.** ByteDance's Seedance rejects a first/last frame or reference that reads as a real-person likeness (even an AI-generated face), surfaced as `content_policy_blocked` (HTTP 422/`E005` "flagged as sensitive", **non-retryable on the same route**). A blocked clip is **not** moved to another model: one guided only by reference images is re-rendered on the same Seedance model through the fal route, which accepts faces (priced at that route, about twice the rate); one that starts from a frame fails with `content_policy_blocked`, nothing billed, and is re-run on `google/veo-3.1` (`person_generation: allow_adult`). To skip the wasted attempt, scaffold a photoreal-cast ad on Veo up front (`--real-face`, which also covers AI-generated photoreal faces), or make the source frame less photorealistic.
 
 ---
 
@@ -4979,7 +5042,7 @@ None.
 | `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.
+**Cost** — ElevenLabs characters x $0.00022 (0.022 credits a character), rounded up to whole credits; the backend charges the same rate on the character count ElevenLabs reports.
 
 ###### Model: `elevenlabs/eleven_v3`
 
@@ -5011,7 +5074,7 @@ None.
 
 ##### `video_lipsync`
 
-Lip-sync a video to an audio track via Sync Labs `sync/lipsync-2` (Replicate).
+Lip-sync a video to an audio track. Model `replicate/sync-lipsync-2`, which runs Sync Labs `sync/lipsync-2` on Replicate.
 
 **Inputs**
 
@@ -5024,7 +5087,7 @@ Lip-sync a video to an audio track via Sync Labs `sync/lipsync-2` (Replicate).
 
 | Name | Type | Required | Notes |
 |---|---|---|---|
-| `model` | literal | yes | `"fal/veed-lipsync"` |
+| `model` | enum | yes | `"replicate/sync-lipsync-2"`. The legacy id `"fal/veed-lipsync"` is still accepted and runs the same model. |
 
 **Outputs**
 
@@ -5032,7 +5095,7 @@ Lip-sync a video to an audio track via Sync Labs `sync/lipsync-2` (Replicate).
 |---|---|---|
 | `video` | video | `video/mp4` |
 
-**Cost** — 20 credits per call.
+**Cost** — $0.40 per minute of the longer input (40 credits for a minute, the quote's assumption when the clips carry no duration). Runs as a background job.
 
 ---
 
@@ -5050,8 +5113,8 @@ Strip a video's background → transparent alpha WebM (VP9) or MOV (ProRes 4444)
 
 | Name | Type | Required | Default | Notes |
 |---|---|---|---|---|
-| `model` | literal | no | `"fal/veed-video-background-removal"` | — |
-| `edge_refinement` | boolean | no | `true` | — |
+| `model` | enum | no | `"replicate/birefnet-video"` | The legacy id `fal/veed-video-background-removal` is still accepted and runs the same model. |
+| `edge_refinement` | boolean | no | `true` | Refines soft edges against background bleed (the model's `refine_fg`). Off bills the lower rate. |
 | `output_codec` | enum | no | `"vp9"` | `vp9 \| h264` |
 
 **Outputs**
@@ -5060,7 +5123,7 @@ Strip a video's background → transparent alpha WebM (VP9) or MOV (ProRes 4444)
 |---|---|---|
 | `video` | video | `video/webm` (VP9 + alpha) or `video/mp4` (H264 RGB + alpha) |
 
-**Cost** — 50 credits per call.
+**Cost** — $0.012 per 30 frames with edge refinement, $0.008 without, at 30fps (36 credits for the 30s the quote assumes). Runs as a background job.
 
 ---
 
@@ -5081,6 +5144,7 @@ Word-level transcription of a video OR a bare audio track (the `video` input acc
 | `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) |
 | `keyterms` | string[] | no | — | Up to 30 names the recogniser must not mangle — a product, a person, a phrase the script coins. The **company's own name is always applied server-side**, so it never needs listing here |
+| `script` | string | no | — | The words the track was asked to say. Given, the `transcript` output is the script's words, spelled as written, at the times the recogniser heard them: aligned locally (misheard words, fillers, accents and numbers said as words are all tolerated), never sent to the recogniser. `scaffold-ad` sets it on every spoken ad |
 
 **Outputs**
 
@@ -5091,7 +5155,7 @@ Word-level transcription of a video OR a bare audio track (the `video` input acc
 
 **Known names are spelled the way the brand spells them.** Every term (the company's own name, plus `keyterms`) is biased into the request — Deepgram `keyterm`, Whisper `prompt` — and its spelling is then enforced on the words that come back, because bias is a probability and a caption prints the mistake at full size over the ad. Verified against the take that shipped wrong: the same Spanish clip returns "Cubicap" bare and "Cubicup" with the name applied. Corrections are listed on the output's `brand_spelling_corrections` metadata, so a rewrite is visible rather than silent. A short name (under 6 characters) gets the bias only — at that length ordinary words sit one edit away, and rewriting those to protect a brand would corrupt the line. **Never patch a mishearing inside a caption composition**: that fix dies with that one creative.
 
-**Cost** — 2 credits estimate; backend reports actual based on duration (Groq: $0.04/hr, 10s minimum; Deepgram Nova-3: $0.0043/min).
+**Cost** — Groq: $0.04/hr, 10s minimum; Deepgram Nova-3: $0.0043/min. Quoted on one minute of audio; the backend charges the transcribed duration.
 
 **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.
 
@@ -5222,7 +5286,7 @@ Place and mix several audio clips onto one timeline — a music bed plus timed v
 
 ##### `image_background_remove`
 
-Strip background → transparent PNG. Powered by `men1scus/birefnet` (Replicate). (Note: mask-only output is no longer produced.)
+Strip background → transparent PNG. Model `replicate/birefnet`, which runs `men1scus/birefnet` on Replicate. The model takes an image and a resolution only: it has no variants and returns no mask.
 
 **Inputs**
 
@@ -5234,19 +5298,18 @@ Strip background → transparent PNG. Powered by `men1scus/birefnet` (Replicate)
 
 | 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` |
+| `model` | enum | no | `"replicate/birefnet"` | The legacy id `fal/birefnet-v2` is still accepted and runs the same model. |
 | `operating_resolution` | enum | no | — | `1024x1024 \| 2048x2048 \| 2304x2304` |
-| `mask_only` | boolean | no | `false` | return binary mask instead of alpha-cut |
+| `model_variant` | enum | no | — | **Deprecated, ignored.** Accepted so older canvases still parse. |
+| `mask_only` | boolean | no | — | **Deprecated, ignored.** The cutout is always returned; there is no mask. |
 
 **Outputs**
 
 | Slot | Kind | MIME |
 |---|---|---|
 | `image` | image | `image/png` (with alpha) |
-| `mask` | image | `image/png` (only when `mask_only: true`) |
 
-**Cost** — 1 credit per call.
+**Cost** — 1 credit per call. Runs as a background job.
 
 ---
 
@@ -5269,7 +5332,7 @@ Generate music from prompt OR score an existing video clip.
 | `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).
+**Cost** — $0.022 per second of audio (2.2 credits a second), 30s when `music_length_ms` is unset; rounded up to whole credits once, not per second. `elevenlabs/video-background-music-v1` runs as a background job.
 
 ###### Model: `elevenlabs/music-v1`
 
@@ -5327,7 +5390,7 @@ None.
 
 Same as `tts`.
 
-**Cost** — `max(1, ceil(total_chars × 0.0015))` credits.
+**Cost** — total characters x $0.00022 (0.022 credits a character), rounded up to whole credits.
 
 ---
 
@@ -5356,7 +5419,7 @@ None.
 |---|---|---|
 | `audio` | audio | provider-determined |
 
-**Cost** — `max(1, ceil(seconds × 2.2))` credits.
+**Cost** — $0.022 per second of audio (2.2 credits a second), 5s when `duration_seconds` is unset.
 
 ---
 
@@ -5431,16 +5494,18 @@ Cache policies (via `--cache-policy`):
 ### 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.
+- **Per-request cost cap: $20 of estimated provider cost for a `video_generate` clip, $10 for every other node.** The backend pre-estimates cost from the shared contract table (for a Seedance clip, on the dearest route it may take) and rejects a single execution above the cap with `cost_limit_exceeded`. No clip the registry allows exceeds $20; split long audio 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 <slug|file.json>`
+#### `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.
 
-Takes a creative's slug (`baker canvas validate <slug>` reads `src/creatives/<slug>/<slug>.canvas.json`) or a canvas path; a slug that names no creative fails with `not_found` and lists the creatives there are. 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.
+**The canvas file is brought up to date first.** Parts of a creative's canvas are projections of its blueprint: each video scene's frame and clip prompts (from `scenes/sNN.json`), a static ad's copy block and type specimen (from `prompt.json`), and the derived spec files the frames read (`prompt.style.json`, `prompt.plate.json`, `prompt.compose.json`). `validate`, `run`, `critique` and `set-prompt` share one preflight that applies every projection and **writes the result back to the canvas file** (only when something changed; `canvas_updated` says so; `sync-definition`, which the file watcher runs over every creative, applies it without writing), so the file on disk, the graph the dashboard shows, the graph the critic scores and the graph that renders are the same. A scene edit that changes timing or the number of scenes is structural and still asks for a re-scaffold. Every preflight failure prints `{ ok: false, error: { code, message, fix? } }` and exits 2.
 
 ```bash
 $ baker canvas validate my-canvas.json
@@ -5455,7 +5520,7 @@ $ baker canvas validate my-canvas.json
 }
 ```
 
-On error you get an array of `ValidationIssue`s, each with `path`, `code`, `message`, and optional `did_you_mean`.
+On error you get `{ ok: false, error: { code: "validation", issues } }`, each issue with `path`, `code`, `message`, and optional `did_you_mean`.
 
 **Absolute asset paths are healed, not reported.** A `source: "path"` ingest (or a `hyperframe_render`
 composition) written as an absolute path inside the workspace is rewritten to its canvas-relative form
@@ -5480,13 +5545,14 @@ names no camera/motion move **and** no exclusions — the six-decision doctrine)
 (the hook, scene 0, is thin across two or more of the four hook layers — text/sound/visual/vibe). Warnings never
 block a run.
 
-#### `baker canvas critique <slug|file.json>`
+#### `baker canvas critique <file.json>`
 
-Takes a creative's slug or a canvas path, like `validate`. Pre-spend creative critic — **advisory, never blocks**. Scores a scaffolded creative 0–1 before a billed `run`,
+Pre-spend creative critic — **advisory, never blocks**. Scores a scaffolded creative 0–1 before a billed `run`,
 so a weak spot gets fixed for free. It branches on modality: a **video** creative is scored on **hook strength**,
 **sound-off first-frame legibility**, **retention risk**, and **mechanism clarity**; a **static ad** on **baked-text
 legibility risk**, **identity grounding** (Rule 1 — every subject on a real reference), **brand-type fidelity** (a
-font specimen wired), and **mechanism clarity**. Reads the canvas only (no generation, no Convex). Ground a video
+font specimen wired), and **mechanism clarity**. Scores the canvas after the shared preflight (so scene and copy
+edits are what gets scored); no generation, no Convex. Ground a video
 hook against a proven pattern with `baker winning-ads hooks`.
 
 ```bash
@@ -5499,20 +5565,28 @@ $ baker canvas critique my-static-ad.json
   "dimensions": [ { "dimension": "text_legibility_risk", "score": 1, "note": "2 copy block(s) — reads cleanly" }, … ] }
 ```
 
-#### `baker canvas run <slug|file.json> [flags]`
+#### `baker canvas run <file.json> [flags]` / `baker canvas run --slug <slug> [flags]`
+
+Validate, then execute the graph. Blocks until done. Logs one line per node. Returns `{ ok, run_id, outputs_dir, output, stats }` on stdout.
+
+`--slug <slug>` runs a creative by name instead of by file: its `src/creatives/<slug>/<slug>.canvas.json` when this workspace has it, else its files restored from the newest run that recorded a portable snapshot (sha-verified, into `src/creatives/<slug>/`), then the normal run flow. Local files are never overwritten unless `--force-remote` is passed. This replaces `baker canvas rerun <slug>`, which still works as a deprecated alias.
 
-Takes a creative's slug (`baker canvas run spring-offer`) or a canvas path, resolved like `validate`. Validate, then execute the graph. Blocks until done. Logs one line per node. Returns `{ ok, run_id, outputs_dir, output, stats }` on stdout.
+A completed render the review calls ready (`verdict` `ready` or `ready_with_notes` for a static ad, no blocking finding for a video) sets `status: rendered` in the creative's `_definition.md` (never moving a `published` or `archived` creative back); the output then carries `definition_status: "rendered"`.
 
 | Flag | Default | Effect |
 |---|---|---|
-| `--cache-dir <path>` | `<workspace root>/canvas/.cache` | Where content-addressed bytes + cache index live. |
-| `--outputs-dir <path>` | `<workspace root>/canvas` | Root for per-run output directories. |
+| `--slug <slug>` | none | Run a creative by name (see above). |
+| `--force-remote` | off | With `--slug`: restore the recorded files even over local ones. |
 | `--run-id <id>` | auto ULID | Override the generated run id. |
 | `--cache-policy <policy>` | `read_write` | `read_write`, `bypass`, or `read_only`. |
 | `--concurrency <n>` | `5` (or `BAKER_CANVAS_CONCURRENCY`) | Max nodes executing at once within a layer. |
-| `--remote-cache <on\|off>` | `on` (or `BAKER_CANVAS_REMOTE_CACHE`) | Company-scoped remote cache + durable asset persistence. |
+| `--remote-cache <on\|off>` | `on` (or `BAKER_CANVAS_REMOTE_CACHE`) | Operator only. Company-scoped remote cache + durable asset persistence. |
 | `--max-credits <n>` | uncapped (or `BAKER_CANVAS_MAX_CREDITS`) | Credit ceiling: aborts before billing when the estimate exceeds it, and at layer boundaries once actual spend does. Completed nodes stay cached, so retrying with a higher cap loses nothing. |
 | `--no-record` | records | Skip posting the durable run-history record (and its live progress). |
+| `--until frames` | none | Stop before the clips with the frames settled; the run is recorded as `awaiting_approval` (not failed, not interrupted) and resumes with `--run-id`. |
+| `--cache-dir <path>` | `<workspace root>/canvas/.cache` | Operator only. Where content-addressed bytes + cache index live. |
+| `--outputs-dir <path>` | `<workspace root>/canvas` | Operator only. Root for per-run output directories. |
+| `--keep-runs <n>` | off | Operator only. Prune old `r_*` run dirs after the run, keeping the N newest. |
 
 **Run history streams live.** The run posts its plan (every node + its dependency edges) the moment validation passes, then re-posts a progress snapshot as each node starts and settles — the dashboard's creative workflow graph shows nodes flipping pending → running → done in real time, with each node's outputs attached as they land. A failed run keeps its per-node trail (what completed, what died). All best-effort: an unreachable backend never changes the run's outcome.
 
@@ -5559,7 +5633,7 @@ It then scaffolds the full pipeline like an **editing timeline**: each clip gets
 
 **Timing-faithful clip + extract (no overlap).** Each phrase clip is generated to its **coverage window** (the deconstruct's real scene/line timing, capped at the gateway-safe ~10s ceiling) and its converted voice is extracted to the **spoken window** (pause to pause) — *not* padded to a word-count estimate. Padding past the window was what ran the voice the clip's whole length and overlapped the next phrase; trusting the deconstruct's timing keeps consecutive phrases back-to-back and lets Seedance pace the quoted text to fit. `metadata.video.talking_scenes` records each phrase's `scene_s` vs `est_speech_s`; on top of that the scaffold flags any scene whose estimated speech overruns its window by more than ~1.3× as **`metadata.todo.overstuffed_scenes`** (also in the stdout checklist) — a loud advisory to shorten the copy or lengthen the scene before rendering, since an over-stuffed line pushes the picture off the audio timeline. It similarly flags **`oversize_scenes`** — a single scene whose own footage exceeds the gateway-safe ~10s clip ceiling (a b-roll shot or one-shot monologue). The phrase splitter only breaks at scene boundaries, so it can't shrink a single over-long scene; its clip would 524 at the gateway, so the advisory tells you to split that scene into two before rendering.
 
-**Timeline-accurate picture — ONE clock.** Seedance can't render under 4s, so each clip is generated at the smallest allowed duration ≥ the scene length and **cut back to the exact scene duration inside the spine's own per-input filter chain** (no standalone trim nodes — one fewer re-encode per scene, and the graph stays a third smaller). Real screenshots/graphics loop fit-padded, generated stills loop fill-cropped, on the same chains. The spine is the ONE clock: every voice, SFX, music, and overlay placement is mapped onto where each scene's picture actually sits in the butted concat (not the reference video's own timestamps, which can carry dead air the picture doesn't reproduce), the audio mix's `total_ms` is pinned to the spine length, and every concat input is normalized to one raster clock (`yuv420p`, 30fps, square pixels, shared timebase) so a generated clip's unadvertised frame rate can never stretch the picture off the audio. The contract is stamped as `metadata.video.timeline` and `baker canvas validate` re-proves it from the live node params after any hand edit. Frames are also prompted as **clean text-free plates** (no baked captions/lower-thirds/tickers/logos-as-text) so the overlay layer is the single source of on-screen text.
+**Timeline-accurate picture — ONE clock.** Seedance can't render under 4s, so each clip is generated at the smallest allowed duration ≥ the scene length and **cut back to the exact scene duration inside the spine's own per-input filter chain** (no standalone trim nodes — one fewer re-encode per scene, and the graph stays a third smaller). Real screenshots/graphics loop fit-padded, generated stills loop fill-cropped, on the same chains. The spine is the ONE clock: every voice, SFX, music, and overlay placement is mapped onto where each scene's picture actually sits in the butted concat (not the reference video's own timestamps, which can carry dead air the picture doesn't reproduce), the audio mix's `total_ms` is pinned to the spine length, and every concat input is normalized to one raster clock (`yuv420p`, 30fps, square pixels, shared timebase) so a generated clip's unadvertised frame rate can never stretch the picture off the audio. The contract is stamped as `metadata.video.timeline` and `baker canvas validate` re-proves it from the live node params after any hand edit. The spine is a `video_concat` node (each clip's `duration_s`, trim or hold is a param, never argv) and the final mux an `av_mux`, and every scene node carries `tags` (its scene, region and role), which is what the validator reads. Frames are also prompted as **clean text-free plates** (no baked captions/lower-thirds/tickers/logos-as-text) so the overlay layer is the single source of on-screen text.
 
 **Scene transitions.** When the deconstruct flags a boundary as `fade`/`whip`/`zoom`/`dissolve`/`swipe` (`scene.transition_out`), the spine reproduces it as an ffmpeg **`xfade`** instead of a hard cut; plain `cut`/`match_cut` stay hard cuts. The overlap is consumed from **extra generated footage** (each transitioning clip is trimmed to `scene_s + transition` and the xfade `offset` lands on the cumulative scene start), so the total length still equals the sum of the scene lengths — the picture stays exactly on the audio timeline.
 
@@ -5591,12 +5665,14 @@ baker canvas run ./reference-ad.video.canvas.json
 | `--max-scenes <n>` | all source scenes | **Cost lever that reduces fidelity** — caps the deconstruct, MERGING away every scene beyond the cap (fewer cuts, lost beats). Prints a warning when set; omit it to reproduce every scene. |
 | `--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. |
+| `--deconstruct-model <id>` | `~google/gemini-flash-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-image-2` | Override the per-frame `image_generate` model (defaults to the strongest, matching `scaffold-static-ad`). |
+| `--image-model <id>` | `openai/gpt-image-2.5-sunburst` | Override the per-frame `image_generate` model (defaults to the strongest, matching `scaffold-static-ad`). |
 | `--video-model <id>` | scored router | Override the `video_generate` model **and skip the router**. Curated roster: `google/gemini-omni-1.1-flash` (**the default video model** — native audio + reference images, `360p`\|`720p`\|`1080p`\|`4k` at ~$0.034\|$0.101\|$0.152\|$0.304 per second, `16:9`\|`9:16`, `duration` 3–10s and 10s when unset), `bytedance/seedance-2.0` (workhorse), `google/veo-3.1` (cine ceiling + real-face), `google/veo-3.1-fast` (cheap Veo), `kwaivgi/kling-v3.0-pro` (motion-transfer). |
 | `--real-face` | auto-detected | Force the Veo route for a photoreal human presenter (dodges the ByteDance real-person filter). **Usually unnecessary** — the scaffold auto-detects a photoreal on-camera person/animal cast from the deconstruct and routes it to Veo on its own; set this only to force it when the cast isn't detected. Covers AI-generated photoreal faces too, not just real ones. |
 | `--motion-transfer` | off | Motion driven from a reference / hyper-dynamic → the router picks Kling. |
+
+A model flag naming a model the registry does not have for that node fails the command (`unknown_model`, listing the models it does have) before anything is billed; it no longer falls back silently to another model.
 | `--identity` | off | Same character/product across clips → the router picks the Seedance workhorse. |
 | `--budget <tier>` | `standard` | Router cost posture: `economy` (cheap Veo-fast tier) / `standard` / `premium`. |
 | `--avatar <handles>` | — | Cast company avatars as the reference's people, comma-separated in the order they appear (`marta` or `marta,joan`). Each recurring person grounds on that avatar's identity sheet and takes its subject description; a `same_as` look of them uses the same sheet. Resolved before anything is billed — a handle that is not `ready` fails the command. |
@@ -5619,9 +5695,7 @@ The two scaffold passes are billed (the full `video_deconstruct` is the heavy on
 
 #### `baker canvas scaffold-static-ad <image> [flags]`
 
-`<image>` is a **local path or an `http(s)` URL** (e.g. a presigned S3 link from ad-dna). A URL is passed straight in; do not `curl` it to a file first. The source is uploaded to durable storage before any billed pass, so the canvas keeps running after a presigned URL expires.
-
-**Every scaffold is a creative in `src/creatives/<slug>/`** (`<slug>.canvas.json`, `prompt.json`, `_definition.md`), never a loose file in the workspace. Without `--slug` a slug is derived from `--title`, else the reference's file name, else `static-ad`, suffixed `-2`, `-3`… past any folder that already exists, and a hint names it. Every flag that shapes the bill (`--platform`, `--placements`, `--aspect`, `--takes`, `--avatar`) is checked before the first billed pass; an unknown value fails with `invalid_platform`, `invalid_placements`, `invalid_aspect`, `invalid_takes` or `avatar` and costs nothing. The output ends with `next_steps`: the one file to edit (`prompt.json`) and the exact command to run (`baker canvas run <slug>`).
+`<image>` is a **local path or an `http(s)` URL** (e.g. a presigned S3 link from ad-dna). A URL is passed straight into the `original` ingest node as `source: "url"` — do not `curl` it to a file first. Note a presigned URL embedded in the emitted canvas will **expire** (the `original` node is composition-only, so a later re-run just skips it); pass a stable URL or a local file if you need the canvas to stay runnable. For the URL case, `--out` defaults to the current directory — pass `--out` to scaffold two URL sources into distinct files, or the second run overwrites the first.
 
 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:
 
@@ -5636,74 +5710,69 @@ It then scaffolds a canvas that draws **only what `prompt.json` holds**; no elem
 - **`text_only`**: no picture is generated. The copy is drawn on the brand's lead colour in its fonts, for near-zero credits. On by default when the reference pictures nothing but copy (no subjects, no people); `--text-only` forces it, `--no-text-only` refuses it.
 - **`baked`**: the copy is painted into the plates, only with `--skip-font` or when no font can load; every other shape is re-framed by `image_aspect_adapt` on `google/gemini-3-pro-image`, never cropped.
 
-**Fonts** come from the first source that has one: a file in `src/brand/fonts/` (via `src/brand/tokens.json` when present), else the heading and body families `tokens.json` or `BRAND.md`'s typography section name, fetched as web font files from Google Fonts or Fontsource and ingested by URL, else Inter (800 and 400). **The logo is optional**: it is drawn from `src/brand/logos/` only when `prompt.json` keeps a logo (a `logo` layout region, or an `advertiser_brand` entry in `brands_logos`) and a real file exists. Meta shows the page name and picture on every ad, so no logo is never an error, never a slot to fill and never a stand-in; a canvas scaffolded with an unfilled logo slot runs without it. Text that belongs to something in the scene (a phone note, a screenshot, a sign, packaging: `surface: "in_scene"` in `text_content`) is painted by the plate, not overlaid, and listed in the report's `in_scene_text`. The plates read `prompt.plate.json` (the scene, the reserved areas, the visual mechanisms and the in-scene text; no overlay copy, no brand names) and the compositions read `prompt.compose.json`; both are re-derived from `prompt.json` by `validate` and `run`, so a copy edit re-draws the formats from the cached plates without paying for a picture again. A format within 10% of the plate's shape is a free crop; a farther one extends the chosen plate once on the same model. Detected elements get **one `[TODO]` ingest slot** each (never the logo), and the original image is wired in for composition only, left out of the render when it shows a person, because the generator copies that face whatever the prompt says (the blueprint's layout carries the composition instead). Each **animal hero** is additionally fused into a generated **multi-view reference sheet** (`image_reference_sheet`, a turnaround built from the one dropped photo) that the render grounds on instead of the lone flat snapshot. Pass `--skip-actor-sheets` to ground straight on the dropped photo. A **person hero** is cast from a company Avatar with `--avatar <handle>`: the slot ingests its identity sheet and `prompt.json` describes that person in the Avatar's own words. The render keeps the face it is given, so it is never a found photo of a real person. The canvas is validated before it's written. stdout returns `{ ok, slug, canvas_path, prompt_path, models, aspect_ratio, placements, output_formats, layout_regions, stats, checklist, next_steps }`; the **checklist** carries `mode`, `summary` (what a run does: pictures, judge, fonts, logo), `fonts`, `logo`, `in_scene_text` and every real asset to drop in.
+**Fonts** come from the first source that has one: a file in `src/brand/fonts/` (via `src/brand/tokens.json` when present), else the heading and body families `tokens.json` or `BRAND.md`'s typography section name, fetched as web font files from Google Fonts or Fontsource and ingested by URL, else Inter (800 and 400). **The logo is optional**: it is drawn from `src/brand/logos/` only when `prompt.json` keeps a logo (a `logo` layout region, or an `advertiser_brand` entry in `brands_logos`) and a real file exists. Meta shows the page name and picture on every ad, so no logo is never an error, never a slot to fill and never a stand-in; a canvas scaffolded with an unfilled logo slot runs without it. Text that belongs to something in the scene (a phone note, a screenshot, a sign, packaging: `surface: "in_scene"` in `text_content`) is painted by the plate, not overlaid, and listed in the report's `in_scene_text`. The plates read `prompt.plate.json` (the scene, the reserved areas, the visual mechanisms and the in-scene text; no overlay copy, no brand names) and the compositions read `prompt.compose.json`; both are re-derived from `prompt.json` by `validate` and `run`, so a copy edit re-draws the formats from the cached plates without paying for a picture again. A format within 10% of the plate's shape is a free crop; a farther one extends the chosen plate once on the same model. Detected elements get **one `[TODO]` ingest slot** each (never the logo), and the original image is wired in for composition only, left out of the render when it shows a person, because the generator copies that face whatever the prompt says (the blueprint's layout carries the composition instead). Each **animal hero** is additionally fused into a generated **multi-view reference sheet** (`image_reference_sheet`, a turnaround built from the one dropped photo) that the render grounds on instead of the lone flat snapshot. Pass `--skip-actor-sheets` to ground straight on the dropped photo. A **person hero** is cast from a company Avatar with `--avatar <handle>`: the slot ingests its identity sheet and `prompt.json` describes that person in the Avatar's own words. The render keeps the face it is given, so it is never a found photo of a real person. The canvas is validated before it's written. stdout returns `{ ok, canvas_path, prompt_path, models, aspect_ratio, placements, output_formats, layout_regions, stats, checklist }`; the **checklist** carries `mode`, `summary` (what a run does: pictures, judge, fonts, logo), `fonts`, `logo`, `in_scene_text` and every real asset to drop in.
 
 **Placement formats.** The canvas delivers the platform's full placement set, each format at its exact size, collected under `final` with the format as its label. The set is derived from `--platform` (`meta` → 4:5 + 9:16, `google` → 1:1 + 4:5 + 16:9, `linkedin` → 1:1, `tiktok` → 9:16, `youtube` → 16:9); override it with `--placements <preset>` or `--placements none` for a single format. The report's `aspect_ratio` is the ratio the plates really render at (the model's nearest to the lead format), and `format_plan` says how each format is made.
 
-**After a run** the CLI reads the finished ad back on what makes a static win, not a checklist of elements: every delivered image's pixel shape against its format, and one vision pass that reads each word against the copy `prompt.json` holds and checks one dominant idea, clipping, artifacts, the brand with the logo covered and the concept's mechanisms, with every format shown a second time at phone-feed thumbnail size (240px wide, same call): a lead message unreadable at that size is blocking. A missing logo, CTA or copy is never a finding; a logo that is drawn and broken is. stdout carries `verdict` (`ready` | `ready_with_notes` | `needs_fixes` | `not_reviewed`), `judge` (the per-plate scores) and hints that end with what the run made; the findings are stored on the run as its `review`. `needs_fixes` means the ad is not done even though every node completed.
+**After a run** the CLI reads the finished ad back on what makes a static win, not a checklist of elements: every delivered image's pixel shape against its format, and one vision pass that reads each word against the copy `prompt.json` holds and checks one dominant idea, clipping, artifacts, the brand with the logo covered and the concept's mechanisms, with every format shown a second time at phone-feed thumbnail size (240px wide, same call): a lead message unreadable at that size is blocking. A missing logo, CTA or copy is never a finding; a logo that is drawn and broken is. stdout carries `verdict` (`ready` | `ready_with_notes` | `needs_fixes` | `not_reviewed`), `judge` (the per-plate scores) and hints that end with what the run made; the findings are stored on the run as its `review`. `needs_fixes` means the ad is not done even though every node completed; its hints name the cheapest fix (overlapping or unreadable copy is fixed with a smaller `size`, a `highlight` or `sticker` treatment or shorter words, which re-draw the formats from the cached plates). **Render budget:** a static ad gets 3 renders per creative in a chat before the person reacts; the fourth exits 2 with `RENDER_BUDGET` without rendering, and `baker creatives feedback record` or `baker creatives select` on that creative opens a new round. Resuming an interrupted run does not count again, and a run that died only on an outage (timeout, network, a provider that says retry) gives its render back.
 
 The logo is never a slot to fill: use the company's committed logo in `src/brand/logos/` (per `BRAND.md`), never `baker images logo <domain>`, whose Brandfetch CDN often serves an outdated mark.
 
 The plate prompt is **model-aware**: for **gpt-image** the exclusions (no invented badges/watermark) are hoisted to the very *end* of the prompt where the model reads them as pure exclusions rather than composition. In the baked-copy fallback it quotes every line of `prompt.json`'s copy (never the logo's text) with an instruction to render each **once, verbatim**; that block is re-read from `prompt.json` on every `validate` and `run`, which also upgrades canvases scaffolded before this change. Run `baker canvas critique` on the scaffolded canvas for an advisory read before you spend.
 
 ```bash
-baker canvas scaffold-static-ad ./reference-ad.png --slug spring-offer --context "competitor ad for <brand>, <category>, <market>"
-# → writes src/creatives/spring-offer/{spring-offer.canvas.json,prompt.json,_definition.md}
+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 spring-offer
-baker canvas run spring-offer
+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. |
-| `--slug <slug>` | derived from `--title` or the reference | Creative slug (lowercase kebab): the creative's folder `src/creatives/<slug>/`, which attaches every run to its generation history. |
-| `--title <text>` | title-cased slug | Creative title for `_definition.md`; also the source of a derived slug. |
+| `--out <path>` | `<image-dir>/static-ad.canvas.json` (cwd when `<image>` is a URL) | Where to write the canvas (`prompt.json` is written alongside). |
+| `--slug <slug>` | — | Creative slug (lowercase kebab): writes the canvas to `src/creatives/<slug>/<slug>.canvas.json` — the repo convention that attaches every run to the creative's dashboard generation history. `--out` wins over `--slug`. With a slug, the reference image is **downloaded into `src/creatives/<slug>/references/` and normalized to a model-safe format** (SVG/AVIF/HEIC/… → PNG), named from the actual bytes (not the URL string) so a presigned/extensionless URL never lands as PNG-bytes-in-`.jpg` — the canvas ingests that committed, portable path instead of the expiring URL. |
 | `--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>` | `openai/gpt-image-2.5-sunburst` | Override the plate model. |
+| `--gen-model <id>` | `openai/gpt-image-2.5-sunburst` | Override the plate model. An unknown model id in any `--*-model` flag fails the command (`unknown_model`) before anything is billed. |
 | `--takes <n>` | `3` | Plates rendered and judged (1-3); `1` skips the judge. A text-only ad renders none. |
 | `--text-only` | on when the reference pictures nothing but copy | Draw a typographic ad: no picture generated, the copy on the brand colours in its fonts. `--no-text-only` renders a picture anyway. |
-| `--platform <channel>` | `meta` | `_definition.md` channel **and** the default placement set the hero fans out to (`meta`\|`google`\|`linkedin`\|`tiktok`\|`youtube`\|`x`\|`other`; `x`/`other` fan out to nothing). Any other value is refused. |
+| `--platform <channel>` | `meta` | `_definition.md` channel **and** the default placement set the hero fans out to (`meta`\|`google`\|`linkedin`\|`tiktok`\|`youtube`\|`x`\|`other`; `x`/`other` fan out to nothing). |
 | `--placements <preset\|none>` | derived from `--platform` | Override the fan-out set: `meta_feed`\|`meta_feed_stories`\|`meta_all`\|`linkedin`\|`google_demandgen`\|`tiktok`\|`youtube`, or `none` for a single base ad. |
-| `--aspect <ratio>` | inferred from the image, else `9:16` | Force the lead format (it leads the placement set when the set has it): `1:1`, `4:5`, `9:16`, `16:9`, `4:3`, `3:4`, `2:3`, `3:2` or `21:9`. |
+| `--aspect <ratio>` | inferred from the image, else `9:16` | Force the lead format (it leads the placement set when the set has it). |
 | `--skip-font` | off | Bake the copy into the plates instead of drawing it in a real font (a font file, else the typeface the brand names, else Inter). |
 | `--skip-actor-sheets` | off | Ground each animal hero on its lone dropped photo instead of a generated multi-view reference sheet. |
 | `--avatar <handles>` | — | Cast company avatars as the image's people, comma-separated in the order they were detected (`marta` or `marta,joan`). Each person slot grounds on that avatar's identity sheet and takes its subject description. Checked before any billed pass; an unknown, not-ready or sheetless avatar fails with code `avatar`. A handle with no person to play is reported in `hints` as `NOT CAST`. |
 
 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`.
 
-**Resuming an interrupted run.** A long `baker canvas run` (multi-clip video) that is killed mid-render — session end, sandbox pause — leaves a marker under the outputs dir. The next `baker canvas run` of the same canvas automatically **resumes** that run: it reuses the run id so still-running billed jobs re-attach instead of being abandoned and re-billed, and completed nodes come from the cache. Resume also works from a **different workspace or a fresh sandbox**: when no local marker survives, the run history is consulted and an interrupted (or stale) run of the exact same canvas is adopted automatically. Ctrl-C / SIGTERM aborts gracefully — no new nodes dispatch, a resumable snapshot is flushed, and the marker survives. A clean completion (or a handled failure) clears the marker, so a normal re-run starts a fresh generation. Force a new run with `--fresh`, or pin a specific run with `--run-id <id>` (also the escape hatch to adopt a run that is reported as concurrently live). Independent same-layer nodes (e.g. video clips) fan out in parallel up to `--parallel`/`--concurrency` (default 8; env `BAKER_CANVAS_CONCURRENCY`).
+**Resuming an interrupted run.** A long `baker canvas run` (multi-clip video) that is killed mid-render — session end, sandbox pause — leaves a marker under the outputs dir. The next `baker canvas run` of the same canvas automatically **resumes** that run: it reuses the run id so still-running billed jobs re-attach instead of being abandoned and re-billed, and completed nodes come from the cache. A live render keeps its marker's heartbeat fresh, so a second `run` of the same canvas is refused while it is alive (checked with `kill(pid, 0)` plus the heartbeat, on Linux and macOS alike). Resume also works from a **different workspace or a fresh sandbox**: when no local marker survives, the run history is consulted for a resumable run of the same source (canvas, `prompt.json`, scenes, compositions and formats), and it is adopted when the backend says it may be: interrupted, stopped at a checkpoint, or a `running` row whose keepalive is older than the backend's staleness threshold. Ctrl-C / SIGTERM aborts gracefully — no new nodes dispatch, a resumable snapshot is flushed, and the marker survives. A clean completion (or a handled failure) clears the marker, so a normal re-run starts a fresh generation. Force a new run with `--fresh`, or pin a specific run with `--run-id <id>` (also the escape hatch to adopt a run that is reported as concurrently live). Independent same-layer nodes (e.g. video clips) fan out in parallel up to `--parallel`/`--concurrency` (default 8; env `BAKER_CANVAS_CONCURRENCY`).
 
-#### `baker canvas rerun <slug> [flags]`
+#### `baker canvas rerun <slug> [flags]` (deprecated)
 
-Re-run a creative's latest recorded canvas **from run history** — no local files needed. Every `canvas run` of a creative uploads a portable snapshot (the canvas JSON plus the local files it ingests: prompt blueprints, composition dirs, reference images) to durable storage and records it on the run. `rerun` restores those files into `src/creatives/<slug>/` (sha-verified; files already matching are left untouched) and then executes the normal run flow — so an interrupted run **resumes** (in-flight jobs re-attach) and a completed one re-renders from the cache at zero credits.
-
-| Flag | Default | Meaning |
-| --- | --- | --- |
-| `--force-remote` | off | Overwrite local files whose content differs from the snapshot (otherwise a conflict aborts with the differing paths). |
-| `--fresh` | off | Start a new run id instead of resuming an interrupted one. |
-| `--regenerate <ids>` | — | Same as `canvas run --regenerate`. |
-| `--concurrency <n>` | — | Same as `canvas run --concurrency`. |
+Now `baker canvas run --slug <slug>`; `rerun` stays as a hidden alias for one release and prints a deprecation note. Every `canvas run` of a creative records a portable snapshot (the canvas JSON plus the local files it ingests: prompt blueprints, composition dirs, reference images) in durable storage, so `run --slug` can rebuild `src/creatives/<slug>/` in a workspace that never had it. A snapshot whose files are exactly the last one uploaded for the creative is reused without a request, and a file the store already holds is not uploaded again. Files the snapshot could not include (missing at run time, or oversized) are listed as warnings.
 
 ```bash
-baker canvas rerun spring-offer
-baker canvas rerun spring-offer --force-remote --regenerate gen
+baker canvas run --slug spring-offer
+baker canvas run --slug spring-offer --force-remote --regenerate gen
 ```
 
-Use it when a creative was built in another conversation (or its sandbox is gone) and you need to continue or re-render it here. Files the snapshot could not include (missing at run time, or oversized) are listed as warnings — supply those locally only if the run actually needs to regenerate the nodes that read them.
+#### `baker canvas stale`
 
-#### `baker canvas inspect <run_id|slug> [--thumbnails]`
+Lists the creatives edited since their last render in this workspace, each with the command to re-render it: `{ ok, data: { stale: [{ slug, canvasPath, renderedRunId }] }, hints? }`. "Edited" is one content fingerprint of the creative's source: the canvas, `prompt.json`, every `scenes/sNN.json`, every local composition directory the canvas renders, and the `formats` in `_definition.md`, so a change counts however it was made. A completed `run` records the fingerprint it drew in `canvas/.rendered/<slug>.json`, and a render attempt of the current source is not asked for again until the source moves. Creatives never rendered in this workspace, and ones with an unfilled `[TODO]` asset slot, are not listed. Read-only, offline, free. The scaffold's turn-end reminder and its `validate-creative-renders` check read this list; the same fingerprint is what `sync-definition` and `run` post as `sourceSha`.
 
-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).
+#### `baker canvas inspect <run_id> [--thumbnails]`
+
+One-page summary of a run: per-node duration + cache status, list of files in the run dir, optional video thumbnails (start/middle/end frames extracted via ffmpeg). When the run has no folder in this workspace (an older version, or a run from another chat), it is read from the company's run history instead (`source: "run_history"`): status, stats, per-node results and the durable URL of every output.
 
 ```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. A creative's slug (`baker canvas inspect spring-offer`) opens that creative's latest run. Reads `manifest.json` for per-node stats.
+Resolves the run dir against `--outputs-dir` (default `./canvas`) or accepts an absolute path. Reads `manifest.json` for per-node stats.
 
 #### `baker canvas catalog`
 
@@ -6166,23 +6235,93 @@ import {
 
 ## Creatives
 
-Publish an approved canvas render as a first-class Baker creative. The image uploads to the Baker image library (tagged `creative`), a creative record is created/updated, and the command prints the creative reference JSON the dashboard renders in chat.
+Publish an approved canvas render as a first-class Baker creative: a static image (PNG, JPG, WebP) or a finished video (MP4, MOV, WebM). An image uploads to the Baker image library (tagged `creative`); a video uploads to the Baker video library and is saved once it plays (bounded at 3 minutes). A creative record is created/updated, and the command prints the creative reference JSON the dashboard renders in chat.
 
 ```bash
-baker creatives publish ./canvas/<run_id>/<final>.png --title "Spring Offer 4x5" \
-  --slug spring-offer-4x5 --run-id r_01JXYZ... \
+baker creatives publish --title "Spring Offer 4x5" \
+  --slug spring-offer-4x5 --run-id r_01JXYZ... --output 4:5 \
   --source-reference-url "https://www.facebook.com/ads/library/?id=..."
+# or from a local file
+baker creatives publish ./canvas/<run_id>/<final>.png --title "Spring Offer 4x5" --slug spring-offer-4x5 --run-id r_01JXYZ...
+# a finished video render (needs the file and --slug)
+baker creatives publish ./canvas/<run_id>/final.mp4 --title "Spring Offer Reel" \
+  --slug spring-offer-reel --run-id r_01JXYZ...
 ```
 
 | Flag | Effect |
 |---|---|
+| `<file>` | The image or video. For an image it is optional with `--run-id`: the run's own saved output (from its run record, sha-verified) is used instead, so a workspace that never had the run's folder can publish it. |
 | `--title <text>` | Required. Human title for the creative. |
-| `--slug <slug>` | Creative slug (`src/creatives/<slug>/`) — attaches the image to that creative's row, marks it `published`. |
+| `--slug <slug>` | Creative slug (`src/creatives/<slug>/`): attaches the image or video to that creative's row, marks it `published`. Required for a video. With `--run-id` an image publish also sets `status: published` in the creative's `_definition.md` (`definitionStatus` in the output). |
 | `--run-id <r_…>` | Pins the approved generation from the creative's run history as the published one. |
+| `--output <label\|slot\|n>` | With `--run-id` and no file: which of the run's images to save when it made several (a label such as `4:5`, a slot, or a 1-based number). |
 | `--source-reference-url <url>` | Original reference ad URL, recorded on the creative. |
-| `--context <text>` | Optional describe context for the uploaded image asset. |
+| `--context <text>` | Optional describe context for the uploaded image or video. |
+
+An image prints `{ ok, data: { creativeId, imageId, reference } }`. A video prints `{ ok, data: { creativeId, videoId, reference }, hints }`, where `reference.asset.kind` is `video` (with `videoId`, `muxPlaybackId`, the poster as `thumbnailUrl`, size and duration) and `hints` names the next step to put it in a Meta ad: `baker ads meta media upload --kind video --video-id <videoId>`.
+
+Without `--slug` an image behaves as before (one creative record per published image). With `--slug` it upserts the repo-convention row — the same one the dashboard's Creatives tab and the `src/creatives/{slug}/` folder describe — so publish, repo sync, and run history all land on a single record regardless of order.
+
+### `baker creatives performance`
+
+How each published creative is doing in the live Meta ads that show it. A creative is linked to an ad when a chat's publish uploads its image or video to Meta and creates an ad with it (or swaps an existing ad onto it); the results are read live from Meta.
+
+```bash
+baker creatives performance                      # every creative in an ad, last 30 days
+baker creatives performance --slug spring-offer  # one creative
+baker creatives performance --days 14 --full     # + ids, last-7-day figures, one row per ad
+```
+
+| Flag | Effect |
+|---|---|
+| `--slug <slug>` | Only this creative. |
+| `--days <n>` | Window ending today, 1-90 (default 30). |
+| `--full` | Adds creative, image and video ids, result type, days live, last-7-day CTR and cost per result, a video's watch funnel (`video`: 3-second views, ThruPlays, 25/50/75/100% watched), and one row per ad. |
+
+Each creative reports `spend`, `impressions`, `ctr` (percent), `cpc`, `results`, `costPerResult`, `frequency`, a `fatigue` verdict (`fresh`, `fading`, `fatigued`, `dead`, `too_early`, `no_delivery`) with its reason, and `definition`: the angle, hook, mechanism, dominantSlot, persona, awareness, hypothesis and reference fields read from the local `src/creatives/<slug>/_definition.md`. A video creative also reports `hookRate` (percent of impressions that watched 3 seconds) and `holdRate` (percent of those that reached a ThruPlay); a static one carries neither. `hints` name worn-out creatives, videos whose hook rate is under 25% (the first 3 seconds need new hooks) or whose hold rate is under 30% behind a working hook (the body loses people), the angle, mechanism and dominant slot with the lowest cost per result (each ranked once two or more values have results), and unreadable ad accounts.
+
+### `baker creatives feedback [--slug <slug>] [--full]`
+
+What reviewers said about creative versions in Baker (Approve, or Not this one with reasons and a note; choosing a version to keep counts as an approval). Compact by default: approved and rejected counts, the top rejection reasons, what approved versions share (format, platform, option) and the 8 latest verdicts, plus `hints[]` saying what to do differently. `--slug` narrows to one creative; `--full` returns every verdict (up to 200) with whole notes.
+
+```bash
+baker creatives feedback
+baker creatives feedback --slug spring-offer --full
+```
+
+Each entry carries its `source`: `review` (the buttons in Baker), `selection` (choosing or saving the version) or `chat` (what the person wrote in a chat, recorded with `feedback record`).
+
+### `baker creatives feedback record`
+
+Record what the person said about one version in a chat: an approval, or a rejection with reasons and their own words. It is stored like the Approve / Not this one buttons, as the verdict of the person who wrote the chat's latest message (`recordedFor: "sender"`), or of the chat itself when nobody has written in it (`"chat"`). One verdict per person per version or option: a later one replaces theirs. Must run from a chat.
+
+```bash
+baker creatives feedback record --slug spring-offer --run r_01K… --verdict rejected \
+  --reasons text_mistakes,weak_hook --note "the price is 49 not 59"
+baker creatives feedback record --slug spring-offer --run r_01K… --option 2 --verdict approved
+```
+
+| Flag | Effect |
+|---|---|
+| `--slug <slug>` | Required. The creative (`src/creatives/<slug>/`). |
+| `--run <r_…>` | Required. The version. |
+| `--verdict approved\|rejected` | Required. |
+| `--option <o>` | One option of a version that made several: its label, its number (`2`) or its slot. |
+| `--reasons <a,b>` | Comma-separated: `text_mistakes`, `logo_or_brand_wrong`, `weak_hook`, `wrong_message`, `looks_fake`, `not_our_style`, `voice_or_sound`, `pacing`, `other`. The two video reasons: `voice_or_sound` (the voiceover, music or mix) and `pacing` (too slow, too fast, the hook lands late). A rejection needs reasons or a note. |
+| `--note <text>` | The person's own words (stored up to 1000 characters). |
+
+After a rejection, `hints[]` restates what to change, starting from that version.
+
+### `baker creatives select`
+
+Choose the version of a creative to keep, or only some of its options, the way choosing it in Baker does: the creative shows that version as the chosen one, and the choice records the chat sender's approval (`source: "selection"`). Naming options replaces the earlier pick. It does not add the image to the library; that is `baker creatives publish`, which, given `--run-id`, also counts as choosing that version.
+
+```bash
+baker creatives select --slug spring-offer --run r_01K…
+baker creatives select --slug spring-offer --run r_01K… --options "beach,2"
+```
 
-Without `--slug` the command behaves as before (one creative record per published image). With `--slug` it upserts the repo-convention row — the same one the dashboard's Creatives tab and the `src/creatives/{slug}/` folder describe — so publish, repo sync, and run history all land on a single record regardless of order.
+Prints `{ ok, data: { creative, runId, kept?, options, approvalRecorded }, hints }`, where `options` lists every option the version offers.
 
 ## Landing Quality (`baker landing`)