gooseworks 0.4.1 → 0.4.2

package/skills/goose-video/SKILL.md

@@ -2,440 +2,307 @@
 name: goose-video
 slug: goose-video
 description: >
-  GooseWorks video ads — remix a video ad template (iMessage chat-reveal, more coming) into a
-  branded video ad for the user's product. Renders LOCALLY on the user's machine (Playwright +
-  ffmpeg + GooseWorks media proxies) and saves the finished MP4 back to the project over MCP.
-  Use when the user says "make the video for project <id>", "for video batch <id>", references a
-  video ad project/batch or template, or asks to remix a video ad. Unlike goose-ads (static images,
-  generated server-side), video renders locally and reports progress + the result back through the
-  gooseworks MCP tools.
+  Order a finished video ad without leaving the chat. Use it when the user says "make me a video
+  ad for <brand>", "I want a video ad", or asks for a UGC / iMessage / explainer video. One
+  sentence is enough: it picks the brand, asks what the ad is for, suggests formats in a table
+  with demo links, asks that format's questions, and shows the script for approval before any
+  real spend. It renders on the GooseWorks server, returns the video in the chat, and works in
+  hosted connectors too. For an existing app video project or batch, it hands off to
+  goose-video-local.
 category: ads
-version: 0.3.0
+version: 1.0.0
 author: GooseWorks
-tags: [gooseworks, ads, video, remix, imessage, local-render, byoa]
+tags: [gooseworks, ads, video, order, server-render]
 ---
 
-# GooseWorks Video Ads — local remix runtime
-
-You produce **video** ad creative on the user's OWN machine and sync the result back to the
-GooseWorks app over MCP. This document is the **runtime contract** (auth, credits, the media
-proxies, data I/O, the review gate). A separate **recipe skill** — fetched per format — tells you
-*what to make* (the pieces, prompts, models, order of assembly).
-
-**Division of authority — read both, but when they disagree THIS doc wins on the environment AND the
-review/approval flow.** The recipe governs WHAT to make; this doc governs WHEN you pause, generate,
-and spend. In particular: a recipe may spell out a **multi-phase, multi-gate** flow — "generate the
-still [GATE] → approve → author the prompt [GATE] → approve → render [GATE] → approve", several
-separate pauses. **Do NOT run it that way.** Collapse every one of those gates into the single
-**review-once** flow below: one review set, one approval (Step 3). Take the recipe's pieces, prompts
-and models; ignore its intermediate pauses. This is the exact contradiction that confused past runs
-(GOOSE-2542) — there is no ambiguity: review-once wins.
-
-You run inside the user's own Claude Code session (they pasted an instruction with a project
-id). The app NEVER runs you — it is the viewer + review surface; you are the renderer.
-
-## CLI-free environments (cowork / headless)
-
-You may be running WITHOUT the `gooseworks` CLI binary (e.g. Anthropic cowork). The
-`mcp__gooseworks__*` tools work over the MCP connection regardless, so wherever this skill
-says to shell out, use the MCP equivalent:
-
-- `gooseworks fetch <slug>` → the **`fetch_skill`** MCP tool (returns the same content/scripts/
-  files/dependencySkills). `gooseworks search <q>` → **`search_skills`**.
-- `gooseworks credits` → the **`get_ad_credits`** MCP tool.
-- `gooseworks doctor` → do the manual toolchain check in the preflight below.
-
-## Report problems so we can fix them (telemetry — do this, don't skip it)
-
-If anything blocks or degrades this run — a media/proxy call fails or errors, a required input or
-asset is missing, a recipe instruction is ambiguous or contradictory, the render toolchain won't set
-up, or you hit a bug you can't work around — **report it** so the team gets visibility and can fix
-the skill. It's fire-and-forget, never counts against you, and never blocks your work.
-
-- **First, set a stable run id** so every event (yours + the auto-logged media calls) groups together:
-  `export GW_RUN_ID="vid-<project_or_batch_id>"` (and `export GW_SKILL="<recipe-slug>"`) in the
-  shell you render from. The media proxies read `GW_RUN_ID` automatically.
-- **CLI present →** `gooseworks log "<what happened>" --event-type <type> --level error --details '{"error":"...","step":"...","model":"..."}'`
-- **No CLI (cowork / headless) →** the **`log_cli_event`** MCP tool with the same fields (pass `run_id`).
-- `--event-type`: `api_failure` (a proxy/model call failed) · `missing_input` · `blocker` ·
-  `confusion` (unclear/contradictory instruction) · `error` (a bug) · `step`/`info` (progress notes).
-- Put the **real error text + the step you were on** in `--details`. Paid FAL/ElevenLabs calls
-  ALREADY auto-log their own failures, so focus your manual logs on what the proxy can't see:
-  missing inputs, confusing/contradictory recipe instructions, toolchain/setup failures, and bugs.
-- Logging is FOR US — it does not replace telling the user. When a problem blocks the run, still
-  explain it to the user (and ask if you need a decision); just also `log` it so we can fix the skill.
-
-## Prerequisite — MCP + a render toolchain (Phase 0 preflight)
-
-- The `mcp__gooseworks__*` tools are REQUIRED. If they're unavailable, stop and tell the user
-  to connect the GooseWorks MCP server (or run `gooseworks install --claude --mcp` on the CLI)
-  and restart. There is no REST fallback.
-- **The render runs wherever THIS agent runs, and it needs a real toolchain: `ffmpeg` +
-  `ffprobe` + a Playwright **Chromium**.** Establish it in this priority order, and do NOT start
-  rendering until one is confirmed:
-  1. **CLI present →** run `gooseworks doctor` (checks login, MCP, ffmpeg/ffprobe, Playwright
-     Chromium in one shot). Fix any ✗ with the command it prints, then continue.
-  2. **No CLI →** check the toolchain yourself: `ffmpeg -version`, `ffprobe -version`, and a
-     Playwright Chromium probe (`npx playwright --version` and, if needed, `npx playwright install
-     chromium`). If all resolve, continue.
-  3. **Docker available →** this is the most reliable way to get the toolchain in a sandbox that
-     lacks it: run the render steps inside the prebuilt image
-     **`ghcr.io/gooseworks-ai/goose-video-render`** (ffmpeg + ffprobe + Playwright Chromium baked
-     in), mounting the project working directory. Use Docker whenever the host is missing ffmpeg or
-     Chromium and `docker` is on PATH. (Note: nested Docker is usually disabled inside managed
-     sandboxes like cowork — treat this as an option, not a guarantee.)
-  4. **None of the above works →** STOP and tell the user plainly, e.g.: *"Video rendering needs
-     ffmpeg + a Playwright Chromium (or Docker) on the machine running this agent. This environment
-     doesn't have them and I can't install them here. Options: (a) enable/allow Docker so I can use
-     the goose-video-render image, (b) install ffmpeg + `npx playwright install chromium`, or
-     (c) run this skill locally in your own Claude Code where the toolchain is available."* Do not
-     half-render or fake a result. Static image ads (the `goose-ads` skill) do NOT need any of this
-     and work anywhere — offer that as the fallback if they just want an ad now.
-
-## Identity, token, credits
-
-- Read `~/.gooseworks/credentials.json` → `api_key` (your agent token), `api_base`, `agent_id`.
-  Never print the token.
-- **CRITICAL — target the org-default Ads agent on EVERY file op.** The app serves project files
-  (the render-file route) from the org's DEFAULT agent, but MCP file writes default to your
-  token's pinned agent — which can be a DIFFERENT agent, so a render written with the default
-  scope is **invisible in the app**. First resolve the Ads agent: `list_accessible_scopes` → the
-  scope with `is_org_default: true` (the ORG default — NOT the `is_default` / `default_agent_id`
-  fields, which are the *user's* default agent and are often a DIFFERENT agent). Its `agent_id` is
-  `ADS_AGENT` (name "Ads agent", slug `org-default`; usually also the `agent_id` in
-  credentials.json). Then pass `target: { type: "agent", agent_id: ADS_AGENT }` on EVERY
-  `get_upload_url` / `get_download_url` / `write_file` / `list_directory` / `read_file` — NEVER
-  omit `target`.
-- **CRITICAL — publish under the PROJECT FOLDER, not the workspace root (the #1 "video renders but
-  is invisible" bug).** `get_upload_url` stores at `<ADS_AGENT>/files/<path>` verbatim, but the
-  render-file route reads from
-  `<ADS_AGENT>/files/agent-config/brands/<brand_slug>/projects/<project_id>/<path>`
-  (see backend `resolveProjectFileKey`). So EVERY publish/preview `path` MUST be prefixed with
-  `agent-config/brands/<brand_slug>/projects/<project_id>/` — e.g. upload to
-  `agent-config/brands/<brand_slug>/projects/<project_id>/working/final.mp4`, NEVER bare
-  `working/final.mp4`. A bare path 404s in the app even though the render row AND a bare-path
-  `get_download_url` both "succeed" (they resolve the wrong key). The render `output_url` still
-  stays the project-relative `...render-file?path=working/final.mp4` — the route re-prepends the
-  prefix itself. Always verify with `get_download_url` on the FULL `agent-config/...` path (must
-  be non-empty; curl it for HTTP 200) BEFORE marking the render complete.
-- Media generation (FAL / ElevenLabs) through the GooseWorks proxies is the **REAL spend** — billed
-  to the agent per call as you generate (Step 4). `submit_render { kind: "full" }` additionally
-  debits **1 nominal ad credit when the render ROW is opened** (a bookkeeping fee, NOT the render's
-  true cost) — so open it only once you actually have a rendered master (Step 4.1/4.2), and never
-  re-submit on a guess (that double-bills). The final-video QC gate (Step 4.3) then sits between
-  that master and PINNING it. Call `get_ad_credits` first; the user can check `gooseworks credits`.
-
-## Step 0 — project id, or video BATCH id? (fan out before anything else)
-
-The handoff you were pasted is EITHER a single `project <id>` OR a `video batch <id>`. A batch is
-the app's "N concepts" flow: one composer submission fans out into **N independent concept projects**
-(the user picked a concept count, default 3), and the app expects EACH to be rendered. **Handle both:**
-
-- **`project <id>`** → you have one project. Treat it as a batch of one and continue to Step 1.
-- **`video batch <id>`** → call `get_ad_video_batch { video_batch_id }`. It returns every child
-  concept under `projects[]` — each is a normal project with its own `id`, `variant_index`
-  (Concept 1..N), and its own `creative_brief` (the per-concept angle/hook/offer/message). **You
-  MUST process every concept, not just the first** — dropping concepts 2..N is the #1 batch bug.
-
-**Loop shape (one agent, sequential, ONE approval for the whole batch):**
-1. Run **Step 1 + Step 1.5 + Step 2 + Step 3-assemble** for EACH concept project (each has its own
-   `project_id`, brief, and `working/` folder — never cross-write between concepts).
-2. Mirror EVERY concept's review set (Step 3's `update_ad_project_script` per project), then stop
-   for **ONE** approval that covers all concepts — show the per-concept credit estimate and the
-   batch total. Set the batch to `review` (`update_ad_video_batch { status: "review" }`).
-3. On approval, set the batch to `rendering` and run **Step 4 (the expensive render)** for each
-   concept **sequentially** (finish Concept 1's master before starting Concept 2 — one machine can't
-   render them in parallel). Deliver each (Step 5). When all concepts are pinned, set the batch to
-   `complete`.
-
-If a single concept fails, keep going with the rest, mark that concept blocked, and report which
-ones shipped — never abort the whole batch on one bad concept. Everything below (Steps 1–5) is
-written per-project; a batch just runs it N times with the shared approval gate above.
-
-## Step 1 — resolve the project, source, brand
-
-1. `get_ad_project { project_id }` → keep `brand_id`, `source_sample_id`, `name`, `status`, the
-   **top-level** `app_url` + `brand_url` (returned alongside `project`, NOT inside it — the links
-   you hand the user for the in-app review in Step 3 and delivery in Step 5), AND the user's
-   **`creative_brief`**, project **`assets`**, `character_id`, `default_voice_id` — these are the
-   authoritative inputs the user chose in the composer (see Step 1.5). Do NOT discard them.
-
-### Step 1.5 — the project brief is AUTHORITATIVE (honor it; don't re-ask)
-
-The composer already collected the user's creative direction onto the project. **Read it and treat
-it as ground truth — it OVERRIDES the template recipe's defaults, and it REPLACES the clarifying
-questions you would otherwise ask.** Only fall back to the recipe default (then, last, to asking)
-for a field the brief leaves empty. Map the fields you WILL honor:
-
-- `creative_brief.productName` / `.offer` / `.angle` → the product, offer/code, and angle. Do
-  **not** ask "which product / what offer / what angle" if these are set.
-- `creative_brief.concept` (on a batch child) → this concept's **`angle` / `hook` / `offer` /
-  `message` / `note`** — the per-concept differentiator. Honor it verbatim; it's WHY the user asked
-  for N concepts. `angle: "auto"` or empty means "you choose."
-- Project `assets` + `creative_brief.reference_image_urls` → the user's **own reference images**.
-  Use them as the product/brand refs (alongside the brand kit), don't ignore them for generic recipe
-  assets.
-- `character_id` → the avatar/creator to use. `default_voice_id` → the voice for any VO (put its
-  NAME in the review `subtitle`). Use these instead of picking your own.
-- `creative_brief.ratio` / `.durationSeconds` → target aspect ratio + length. Honor when the
-  format's render pipeline supports it; if the format physically can't (e.g. a fixed phone-mockup
-  aspect), keep the format's native value and note the constraint in the review rather than silently
-  ignoring the request.
-- `polish_policy` (`standard` | `extra`) → `extra` means spend the extra pass on QC/polish.
-2. `get_ad_template { template_id: source_sample_id }` → the source video: `media_url`,
-   `recipe`, `format` (e.g. "imessage"), `extracted_script`, `how_to`, `remix_spec`.
-3. Brand gate: `get_brand_kit { brand_id }`. If `researchStatus` is `complete`, REUSE it —
-   never re-research. If not, run brand research first (`gooseworks fetch brand-research`,
-   follow it, then `finalize_brand_research { brand_id }`) before continuing.
-
-## Step 2 — read the template's recipe (it carries everything; NO hardcoded format map)
-
-The ad format is a **template (data) in the ad_sample DB**, not a per-format skill.
-`get_ad_template(source_sample_id)` returns the template's `recipe` — a self-contained brief you
-read and execute. **Do NOT map `format` to a hardcoded recipe slug** (there is no such table):
-
-- `recipe.format` — the format label (e.g. `vignette`), for display only.
-- `recipe.atoms` — the **capabilities** this template composes (e.g. `create-video-seedance-2-fal`,
-  `create-image-gpt-image-fal`, `review-ugc-render`, `watch`). `gooseworks fetch <name>` each — they
-  live in `skills/ads/capabilities/` and are reused across templates (so they cache).
-- `recipe.instructions` — the **playbook** to follow: `instructions.inline` prose, or
-  `instructions.doc_url` (an S3 markdown doc — fetch it).
-- `recipe.config` — every param (prompts, layout, timings, palette, model choices).
-- `recipe.inputs` — the brand-asset contract (which product / logo / offer this template needs).
-- `recipe.assets` — reference material as S3 links (reference render, style guide, example frames) —
-  fetch as needed.
-
-Runtime: **read the recipe → `gooseworks fetch` each capability in `recipe.atoms` → follow
-`recipe.instructions` with `recipe.config` + the brand's bound `inputs`.** The template IS the recipe;
-there is no `format → recipe-slug` table and no per-format skill to fetch.
-
-Save each fetched capability's scripts + files under `/tmp/gooseworks-scripts/<name>/`. If a capability
-is a Node package (a phone-mockup renderer), `npm install` in its folder so its `generate.js` +
-Playwright resolve, and point the recorder's `NODE_PATH` at it.
-
-> **Migration note:** older phone-mockup formats (`imessage` / `chatgpt` / `apple-notes`) whose DB
-> recipe does not yet carry `atoms` / `instructions` still hold the legacy `recipe.thread` payload;
-> migrate them to this shape (capabilities + instructions in the DB) — do not reintroduce a CLI map.
-
-## Step 3 — assemble the review set, then get ONE approval in the app (before the expensive render)
-
-This is a **review-once** flow: put the whole review set in the app, get ONE approval, then run the
-expensive render + any remaining paid work end-to-end. Never spend on the expensive render before
-approval, and don't drip pieces out one at a time and re-pause.
-
-**What goes in the review — show the REAL cheap pieces, PROMPT only the expensive render.** Split
-every piece three ways by cost, NOT just "free vs paid":
-- **FREE** (an iMessage / Apple-Notes HTML mockup, a text/CTA line — rendered locally, no proxy
-  call) → generate NOW and mirror the real asset.
-- **CHEAP paid** — a single still/image, the creator/avatar frame, the end card, a short voiceover
-  or music bed (each costs cents → roughly **≤ 100 credits**) → **generate these NOW too** and
-  mirror the real asset. The few credits buy a real review: the user SEES the actual creator face
-  and end card and HEARS the VO, instead of judging a prompt. **This OVERRIDES any recipe rule that
-  says to gate ALL paid calls** — only the expensive render below is gated.
-- **EXPENSIVE paid** — the video take / final AI render (hundreds of credits) → do NOT generate.
-  Put its **exact prompt/spec** (+ ref image URLs) in the tile. This is the ONE thing approved as a
-  prompt (you can't preview a hundreds-of-credits video for free); it's generated only in Step 4.
-
-**The expensive render's exact prompt must be in the panel BEFORE you ask for approval** — so a
-single "go" runs it (plus any remaining paid work) without re-pausing mid-run.
-
-**Show every cost in CREDITS, never dollars.** 1 credit = $0.01 and media generations bill at
-provider-cost × 1.2, so **credits ≈ round-up(provider-$ × 120)** per generation, plus a flat
-**200-credit base per video**. Convert any $ figures to credits and show ONLY credits to the user —
-never print a "$…" amount.
-
-**Never assemble/stitch the finished video for review.** The review is of the individual pieces (or
-their prompts) — never a "full cascade" / "approved cut" clip. Building the whole video before
-approval defeats the gate (the user opens the review to an already-finished video) and wastes the
-render (GOOSE-2542). The full video is assembled ONLY in Step 4, after approval. A `video`
-ingredient here is only a genuinely separate SOURCE clip the format needs (e.g. supplied b-roll).
-
-1. **Assemble every piece the format needs — not just the script.** Read the recipe for the exact
-   list. For an iMessage video that's the **script** (bubble thread), the **conversation image(s)**,
-   and the **end card**; richer templates add a hook frame, background, product shots, music bed, a
-   creator/avatar, a voiceover… For each piece, decide FREE / CHEAP-paid / EXPENSIVE-paid (above):
-   - **FREE or CHEAP paid** (≤ ~100 credits — HTML mockups, a still, the creator frame, the end
-     card, a short VO/music bed) → generate it now and `get_upload_url` the asset to the project
-     folder `agent-config/brands/<brand_slug>/projects/<project_id>/working/review/<name>` (same
-     path-prefix rule as final publish — a bare `working/review/<name>` won't render in the panel);
-     set that piece's `path` in `script_drafts` to the project-relative `working/review/<name>`.
-   - **EXPENSIVE paid** (the video take / final render, hundreds of credits) → do NOT generate. Put
-     the **exact prompt/spec** (and any ref image URLs) in the tile's `text` / `subtitle` so the
-     user reviews what will be spent on. No `path` yet — it's generated in Step 4.
-   Include the **estimated cost in CREDITS** (never dollars) of the cheap pieces already generated +
-   the pending render, so the user approves knowing the total spend. **Answer clarifying questions
-   from the project brief FIRST (Step 1.5)** — only ask the user for a field (angle, which product,
-   offer/code) the `creative_brief` leaves empty AND the recipe can't default. Do not re-ask for
-   anything the composer already captured.
-2. **Mirror the whole ingredient set for review** — `update_ad_project_script { project_id,
-   script_drafts, script }`. `script_drafts` is a structured payload of **container-tagged
-   ingredients** so the app renders each piece the right way:
-   `{ format, scenes?, ingredients: [{ container, label, subtitle?, path?, text? }] }`. Each
-   ingredient's `container` tells the app HOW to show it:
-   - `image` (a frame shown in the video), `endcard` (the end card), `avatar` (a character
-     headshot), `background` → rendered as an image tile.
-   - `voice` (a voiceover clip — put the voice NAME in `subtitle`), `music` (the bed),
-     `audio` → rendered as an audio player.
-   - `video` (a clip) → a video player. `text` (a copy line like the CTA) → a text tile.
-   - `script` / `thread` / `note` / `conversation` → the written script (or set `scenes[]`
-     for the podcast shape, or pass the readable `script` string).
-   `path` = `working/review/<name>` (upload the preview asset first via `get_upload_url`); `url`
-   works too. **Label every ingredient** ("Hook image", "End card", "Voiceover", "Background
-   music", "HER"). The `update_ad_project_script` call itself writes no render and costs no credits
-   (the cheap pieces you already generated above have their own small cost) — it just populates the
-   review panel.
-3. **STOP — the review happens in the APP's review panel, NOT in this chat.** You've mirrored the
-   ingredients (3.2); now hand the user the project's `app_url` (from `get_ad_project`) and tell
-   them to review the pieces there and hit **"Approve & render"**. That button gives them a short
-   message to paste back into this session — THAT is your go-ahead. Do NOT paste the
-   script/ingredients into the chat for a thumbs-up, and do NOT render until that approval comes
-   back from the app. If they want changes (via the app's comments or here), regenerate the
-   affected ingredient, call `update_ad_project_script` again, tell them it's refreshed in the
-   app, and wait for a fresh approval. Only AFTER the app approval do Step 4. A single approval
-   authorises the WHOLE remaining chain — generate every paid piece, render, self-QC, publish —
-   with NO further pauses (that is exactly why every paid prompt must already be in the panel).
-
-## Step 4 — render locally, report stages, publish
-
-1. Now generate every PAID piece you showed as a prompt in Step 3 — the AI stills/video, voice,
-   music, the end-card render — through the media proxies (below), each from its approved prompt.
-   Then assemble per the recipe (Playwright record where needed → ffmpeg stitch → `mix-master`
-   audio).
-2. Open the row LAST: `submit_render { project_id, kind: "full" }` → keep `render_id`, then
-   `update_render_status { render_id, status: "running" }`. The render row tracks status only
-   (queued / running / complete / failed) — narrate fine-grained progress with
-   `append_project_message` instead.
-3. **MANDATORY final-video QC gate — YOU review EVERY finished master before `set_final_render`,
-   whatever the format (UGC or not).** This is your own automated quality check, separate from the
-   user's Step-3 approval — it does not go back to the user. The render row is already open (its
-   nominal credit spent, `submit_render` in 4.2);
-   this gate stands between a rendered master and PINNING/publishing it, so a bad render never gets
-   set as final. A master that looks fine on a still can still have a mis-voiced word, a caption
-   drifting off its line, a beat out of order, or a deformation — review the actual VIDEO, not
-   stills. Run the passes that APPLY to this format:
-   - **Audio ↔ script** — any master with SPEECH (VO or native/Seedance voice); **skip for
-     music-only / no-speech formats.** `review-ugc-render` is format-agnostic despite the name —
-     a deterministic Whisper transcript-vs-script diff, not UGC-specific: persist the approved
-     spoken lines to `working/approved-script.txt`, then `gooseworks fetch review-ugc-render` and
-     run `review_render.py --video <master>.mp4 --script-file working/approved-script.txt --json
-     working/review-verdict.json` (exit 0 PASS / 2 FAIL / 3 ERROR). It blocks a mis-voiced word
-     (approved "human-vetted" → "human witted"), a dropped phrase, or silence. It routes Whisper
-     through the gooseworks proxy when `OPENAI_BASE_URL` is set; with no backend at all, run
-     `fal-ai/whisper` via `fal-proxy` (upload the audio, pass its `get_download_url` as `audio_url`)
-     and diff the transcript yourself.
-   - **Captions / subtitles** — ANY captioned format (the most common non-UGC defect); **skip for
-     UGC/Seedance masters, which carry no subtitle track.** Concrete check: diff the caption file
-     you burned (SRT/ASS) against the SAME Whisper transcript + word timings from the audio pass —
-     every caption line must match the heard/scripted words and sit within ~0.3s of when they're
-     spoken; then in the visual pass below, OCR-read the burned caption off 4–5 sampled frames to
-     confirm it's actually on screen at that time and not colliding with a hyperframe or the end
-     card. Mismatched text or >0.3s drift fails the gate.
-   - **Visual + structure** — always: run the `watch` skill on the master — beat/scene order + SFX,
-     the brand's product (not the source's) is shown, the end card has the real wordmark + code, no
-     deformation/artifact, duration within ~20% of the source.
-   If ANY applicable pass fails, FIX it (regenerate/stitch the offending window, rebuild captions)
-   and re-review — only a clean pass proceeds to `set_final_render`. **This gate is universal: it
-   runs from the master skill for every format, so a recipe never has to opt in.**
-4. Publish: `get_upload_url { target: { type: "agent", agent_id: ADS_AGENT } }` → PUT the master
-   and poster **under the project folder** (see Identity's path-prefix rule) — to
-   `agent-config/brands/<brand_slug>/projects/<project_id>/working/final.mp4` and
-   `.../working/final-thumb.jpg`. **Always target ADS_AGENT AND use the full project-folder path**
-   — a bare `working/final.mp4`, even on the right agent, 404s in the app. Verify servable:
-   `get_download_url { target: ADS_AGENT, path: "agent-config/brands/<brand_slug>/projects/<project_id>/working/final.mp4" }`
-   must return a non-empty URL (curl it for HTTP 200).
-   Then `update_render_status { render_id, status: "complete", output_url, thumbnail_url }` where
-   **output_url MUST be the durable render-file URL**
-   `/api/ads/projects/<project_id>/render-file?path=working/final.mp4` (the app re-presigns it on
-   every view) — NEVER a raw proxy/CDN URL (those expire). Same for `thumbnail_url`.
-5. `set_final_render { project_id, render_id }` to pin it, then return the `app_url` +
-   `brand_url` (from the project/links) verbatim. Never end on just "done" or a file path.
-
-Narrate each long step in one line via `append_project_message { project_id, role: "agent",
-content }` — never sit silent on a queue > 90s.
-
-## Media generation — the GooseWorks proxies (queue loop)
-
-Media APIs go through GooseWorks proxies with your agent token; do NOT use an SDK's default host
-(your token isn't a FAL/ElevenLabs token → 401). Base = `<api_base>/api/internal/<proxy>`; pass
-`?token=<api_key>&agent_id=<agent_id>&project_id=<project_id>` (agent_id bills the Ads agent;
-`project_id` = the id of the project you're rendering — it attributes this generation's credits to
-that ad project so the user sees per-project spend in the app. ALWAYS pass it). FAL = `fal-proxy`
-(+ `fal-storage-proxy` to host a local image and get a CDN URL); ElevenLabs = `elevenlabs-proxy`
-(VO / music bed).
-
-**FAL queue gotcha** (#1 waste of generations): submit returns `status_url`/`response_url` on
-`queue.fal.run` (the real host, not the proxy). Polling those 401s forever — rewrite their host
-to the proxy base (keep the path), re-add `?token=&agent_id=`. Only the final `*.fal.media`
-image is a real public URL. Helper:
-
-```python
-import json, os, pathlib, time, requests
-from urllib.parse import urlparse
-
-def _cfg():
-    c = json.loads(pathlib.Path(os.path.expanduser("~/.gooseworks/credentials.json")).read_text())
-    return c["api_base"].rstrip("/"), c["api_key"], c.get("agent_id")
-
-def _params(tok, agent, project_id=None):
-    p = {"token": tok}
-    if agent: p["agent_id"] = agent
-    if project_id: p["project_id"] = project_id  # attributes the spend to this ad project
-    return p
-
-def fal_generate(model_path, payload, project_id=None, timeout_s=180, poll_s=3):
-    """model_path e.g. 'fal-ai/nano-banana-2/edit' (the recipe names the model).
-    Pass project_id = the ad project you're rendering so credits attribute to it.
-    Returns the result image URL (a public *.fal.media CDN URL)."""
-    api_base, tok, agent = _cfg()
-    base = api_base + "/api/internal/fal-proxy"
-    sub = requests.post(f"{base}/{model_path}", params=_params(tok, agent, project_id), json=payload).json()
-    to_proxy = lambda u: base + urlparse(u).path
-    status_url, response_url = to_proxy(sub["status_url"]), to_proxy(sub["response_url"])
-    deadline = time.time() + timeout_s
-    while time.time() < deadline:
-        st = requests.get(status_url, params=_params(tok, agent, project_id)).json()
-        if st.get("status") == "COMPLETED":
-            return requests.get(response_url, params=_params(tok, agent, project_id)).json()["images"][0]["url"]
-        if st.get("status") in ("FAILED", "ERROR"):
-            raise RuntimeError(f"FAL failed: {st}")
-        time.sleep(poll_s)
-    raise TimeoutError("FAL polling exceeded timeout")
-```
-
-ElevenLabs (VO / music) is the same shape against `<api_base>/api/internal/elevenlabs-proxy`
-with `?token=&agent_id=&project_id=`. Feed FAL a local image by storing it (`get_upload_url`) and passing its
-`get_download_url` presigned URL as an `image_urls` / `audio_url` entry — this is the reliable
-path. (`fal-storage-proxy` may 404 depending on the install; don't block on it — prefer the
-`get_download_url` presigned URL.)
-
-## Rules
-
-- **MCP + ffmpeg + Playwright required** — run `gooseworks doctor` in Phase 0; stop with the
-  exact fix it prints if anything is ✗.
-- **Assemble the whole review set first**, mirror it with `update_ad_project_script`, and get the
-  user's approval **in the app's review panel** (the "Approve & render" button) BEFORE the expensive
-  render — never ask for a thumbs-up in this chat (review-once, in-app).
-- **Show the REAL cheap pieces; PROMPT only the expensive render.** Generate the FREE + CHEAP-paid
-  pieces (≤ ~100 credits — stills, creator frame, end card, short VO/music) and mirror the real
-  assets; put ONLY the expensive video take/render in the panel as its exact prompt. That prompt
-  must be in the panel before you ask to approve, so a single "go" runs the render + any remaining
-  paid work (→ QC → publish) with no re-pausing.
-- **Costs in CREDITS, never dollars.** credits ≈ round-up(provider-$ × 120) per generation + a flat
-  200-credit base per video; never show a "$…" figure to the user.
-- **Never assemble the full video before approval.** The review shows the
-  individual PIECES, never the finished cut (or their prompts) — not a
-  stitched/composited cut; do not add a "full cascade" / finished-video clip
-  as a review ingredient (GOOSE-2542). The assembled video is produced only in
-  Step 4.
-- **submit_render only after the master is rendered** (Step 4.2), never on a guess; `output_url` =
-  the durable render-file URL, never a CDN URL.
-- **Always pass `project_id` on media-proxy calls** (fal / ElevenLabs) so the credits attribute
-  to this ad project — that's what lets the user see per-project spend in the app.
-- **Verify a real, non-empty MP4** (watch it) before marking the render complete.
-- **Reuse the brand** when its research is complete; never re-research.
-- On a hard error (auth/quota/model/timeout) set the render `failed` with a short
-  `error_message` and stop — don't ship the source unchanged. **Also `log` it** (`gooseworks log`
-  / `log_cli_event`, `--event-type api_failure|error`) so we can see + fix it (see "Report problems").
-- **Report blockers/bugs/confusing instructions via telemetry** (`gooseworks log` or the
-  `log_cli_event` MCP tool) — not just to the user. Set `GW_RUN_ID` once so events group.
-- Always end a successful run with `app_url` + `brand_url`, verbatim.
+# GooseWorks Video Ads — order a video in chat
+
+## Purpose
+
+Produces one finished vertical video ad, rendered on the GooseWorks server and billed in credits. Examples: an animated iMessage, ChatGPT or Notes thread that ends on the brand's product, or a kinetic-type explainer. The live catalogue decides what can be ordered.
+
+**The customer starts with one sentence.** "Make me a video ad for Bioma" is the normal opening, not an edge case. They will not name a format, a tool or a step. Getting from that sentence to a good choice is this skill's job.
+
+**The whole job happens in the chat.** The customer is in Claude Code, ChatGPT or a terminal. They will not open a browser to review a script, compare voices or watch a result. Choosing, previewing, approving and receiving all happen here, as text and links they can click. The app is for **payment and nothing else**.
+
+**This is not the Video Ads Lab.** The lab is internal, admin-only and free. This spends a customer's money.
+
+
+## Route first: is this a new order?
+
+This skill **orders a new video**. Hand off to **`goose-video-local`** and stop following this skill when the customer brings any of these:
+
+- a **video batch** id ("for video batch <id>");
+- the app's copy-for-Claude command (it names `goose-video-local`);
+- "remix this video ad template" for a specific app template.
+
+Those render on the customer's own machine. Use `goose-video-local` if it is installed; otherwise load it with `fetch_skill("goose-video-local")` on the GooseWorks MCP.
+
+A bare **project** id ("make the video for project <id>"): call `video_project_read { brand_id, project_id }` first. **Stay here** when it returns an `order`, or the project's `script_drafts.recipe` is set: that is an order made through this skill, so continue it on the same `project_id`. **Anything else** goes to `goose-video-local`.
+
+Everything else, including "make me a video ad for <brand>", starts at step 1 below.
+
+## Inputs
+
+- A brand, usually named in the opening sentence. Resolved to `brand_id`; with one brand in the org it needs no input.
+- What the ad is for, in the customer's words (optional; asked once, never forced). **It is sent with the order** as `brief.prompt` and reaches the script. It is not only for sorting the table.
+- Anything else they volunteer about the ad: who it's for, names or terms it must say, things to stay away from. These are never asked for; they're kept when the customer offers them.
+- The picked format's own answers (voice, music, angle…). The catalogue says which apply; some formats ask nothing.
+
+Never an input: a reference video (these formats don't use one), or a promo code (it comes from the brand).
+
+## Composed Atoms
+
+MCP tools; the work happens in the app.
+
+- `brand_list`: brand NAME → `brand_id`. Pass `query` when they named one.
+- `brand_create { name, website_url }`: only when the customer asks to add a brand that isn't there. Free.
+- `video_catalog_list { kind: "formats", brand_id }`: what can be ordered. Each format has `card.description`, `card.best_for`, `card.needs`, `ask[]`, `brand_requirements[]`, `default_credits` and `examples[]` (demo videos: a curated sample first, then real runs). The response also carries `brief_fields`: the intent fields every format's `brief` accepts on top of its `ask[]` (`prompt`, `audience`, `must_mention`, `avoid`, `notes`).
+- `video_catalog_list { kind: "voices" }`: voices with playable `preview_url`s, for formats that speak.
+- `video_project_upsert`: the free draft. Returns `project_id`, `quote`, `ready`, `missing` and `questions` (0–2 things worth asking before the script is written; usually none).
+- `video_project_upsert { project_id, patch: { brief } }`: changes the brief, checked the same way as when it was created. A key replaces its value, `null` removes it. Free. Once ordered, only the brief fields change (never the format's own answers), and they reach the script on the next `redraft`. A brief change never moves the quote.
+- `video_render_run { dry_run: true }`: re-reads the price. Free.
+- `video_render_run { kind: "partial" }`: **writes the script and stops.** Reserves the quote and shows the script before the expensive work. Works for every orderable format, chat or voiceover.
+- `video_render_run { kind: "full" }`: finishes an approved preview.
+- `video_render_run { kind: "edit", edit: { script } }`: puts the customer's OWN words into the draft, verbatim, through the format's own guards. Free before approval, and the **only** route that keeps their copy. Offered where the format's `edits.script` is non-empty; refused as `script_not_editable` elsewhere.
+- `video_render_run { kind: "redraft", reason }`: another draft, before approval, written from why they turned this one down, or with no `reason` after a brief change (the change is the reason). It **re-runs the writer** either way, so every word (and the picture on a character format) is replaced — it does not keep copy the customer supplied. Same order, **no new hold**, but **not free**: it adds a few credits of model spend inside the hold already placed. Up to 3, and refused if it would pass the hold. `dry_run: true` says what it would add.
+- `video_project_read { brand_id, project_id }`: status, the drafted script while previewing, and the finished video. Returns an `order` object for recipe projects.
+- `job_cancel { job_id }`: declines a preview. `job_id` is the order id (the project id also works). Releases the whole hold.
+
+## Workflow
+
+The opening is fixed: **brand → what it's for → suggested formats → first question.** Do each step without waiting for the customer to ask for it.
+
+### 1. Resolve the brand, quietly when you can
+
+Call `brand_list`, with `query` when they named a brand. `query` is a case-insensitive substring match, so "Kolkata Chai" also finds "Kolkata Chai Co". If it finds nothing, call `brand_list` once more with no query before deciding.
+
+- **The org has exactly one brand** → use it. Say which in one line ("Making this for **Bioma**.") and move on. Don't ask.
+- **The name they said matches exactly one brand** → use it. Say which.
+- **Several match, or they named none and the org has several** → show a table (name, website) and ask. The wrong brand is a wasted order.
+- **Nothing matches** → say so, list the brands they do have in a table, and offer to add the new one here: "Or send me its website and I'll add it." With a website, call `brand_create { name, website_url }` (free). It starts brand research, which fills in the logo and colours in a few minutes. Say so, then carry on from step 2 while it runs. Before step 5, check `brand_get_context` shows `research_status: complete`; until then drafts are blocked. Adding a brand is not a trip to the app. Never create a brand they didn't ask for, and never guess the website.
+
+If the GooseWorks MCP's own instructions have you check onboarding first and it turns out unfinished, finish it, then come back here with the customer's original sentence.
+
+### 2. Ask what the ad is for, in one open question
+
+Unless the opening sentence already said it, ask **one** plain question and wait:
+
+> What's this ad for? For example: launching something, a sale, explaining how it works, or showing real results. Anything you tell me helps me pick the right format.
+
+This is a free-text question: **no menu, no table, no list of formats yet.** Take whatever they say, even "not sure" or "just something good". Never ask it twice, and never block on it: a vague answer is an answer.
+
+**Keep the answer. It goes into the order in step 5**, not just into the table's order. Write it down as they said it; that becomes `brief.prompt`. If their words (here or in the opening) also say who the ad is for, a name or term the ad must say, or something to stay away from, note those too:
+
+| They said | Goes in | Example |
+|---|---|---|
+| What the ad is for (the whole answer) | `prompt` | "creative is the bottleneck for small teams, make it a problem-solver" |
+| Who it's for | `audience` | "heads of growth at seed-stage startups" |
+| A name or term it must say | `must_mention` (a list) | `["Claude", "ChatGPT"]` |
+| Something to keep out | `avoid` (a list) | `["no villain", "don't talk down to marketers"]` |
+
+Never ask for the last three and never fill them with a guess. A `must_mention` term the customer didn't say is a claim we made for them.
+
+Skip the question when the opening already names a goal ("…a video ad for our summer sale") or a format ("…an iMessage video ad"). With a format named, go to the table with that format first and marked, then step 4.
+
+### 3. Suggest formats in a table, best fit first
+
+`video_catalog_list { kind: "formats", brand_id }`, then **always a markdown table in your message**.
+
+Order the rows by how well each format fits their answer. Judge fit from `card.description`, `card.best_for` **and the format's `ask[]` options** against what they said. An option can make a format fit: a cartoon explainer whose `ask[]` offers `arc: hero-helper` fits "a friendly hero mascot, no villain"; one without that option does not, because its card says the character is the problem and loses. **A format whose card contradicts what they asked for is never Suggested**, however well its keywords match. When nothing fits, say so before the table ("None of our formats does X; the closest is Y, which gives up Z") and still show the table. Mark **exactly one** row **Suggested** with a few words on why ("real results → before/after"); a close second can be **Also good**. One suggestion keeps "the suggested one" unambiguous. With no goal given, put the formats that have demos first.
+
+| | Format | What it looks like | Price | Demo |
+|---|---|---|---|---|
+| **Suggested** | iMessage chat reveal | Two friends texting; ends on your product | ~60 credits | [watch](https://…) |
+| **Also good** | Apple Notes reveal | A diary-style note typed out; ends on your product | ~15 credits | [watch](https://…) |
+| | Kinetic type explainer | Bold on-brand text timed to a voiceover | ~80 credits | [watch](https://…) |
+
+- **Demo** is `examples[].output_url`. When a format has none, write "no demo yet" in the cell; never leave it blank.
+- **"What it looks like" is `card.description`, quoted.** Copy it word for word; you may cut it at a sentence boundary, never re-word it. A paraphrase once turned "narrates how it gets beaten" into "narrates the fix", which made a villain format look right for a no-villain brief. `card.best_for` often carries a dollar figure; never copy it into the table.
+- **When the pick depends on an option, say which.** "Cartoon explainer (as a friendly helper)" in the Format cell, and pre-fill that answer in step 4.
+- **Price** is `default_credits`, written approximately ("~60 credits"). It is a guide for choosing. The price they agree to is the server's quote in step 5.
+- **Say which formats won't take their words.** A format whose `edits.script` is empty writes its own copy and accepts no hand edit; the only lever is a redraft, which rewrites everything. Put "writes its own words" in that row's "What it looks like" cell. A customer who arrives with a script already written needs to know this **before** they pick, not after they hand it over.
+- **Formats the brand may not be able to run** go last, with `card.needs` in plain words, e.g. "needs real before/after photos". Don't hide them; don't suggest them. Judge logo and product photos from the `brand_list` row. For anything else (before/after photos, say) you can't see, treat it as missing rather than make extra calls. `video_project_upsert` returns `ready`/`missing`, which is the real check.
+
+**Print the table in your message, THEN ask which one** ("Want the suggested one, or another?"). Never put the formats only inside a structured question control: it renders plain option labels, not links, so the customer would be picking a format they were never able to watch. That happened on the first real run: the picker appeared, the demos didn't, and the customer had to ask where they were. A question control may follow the table to capture the answer; it never replaces it.
+
+### 4. Ask the picked format's questions (only these)
+
+Its `ask[]` list is the whole question set. Anything with `source: "recipe"` is the recipe's call, never the customer's. **An empty `ask[]` means no questions**: say so ("This one needs nothing else from you") and go straight to step 5.
+
+Ask them all in **one message**, the choice tables first. Put yes/no questions that have a default at the end as a statement they can override ("Music on and a selfie in the thread; say if you want either off"). Every question with an optional answer gets a "leave it to the writer" option.
+
+**The rule most easily got wrong:** anything the customer should *see or hear before choosing* goes in a **markdown table in your message**. The structured question control only captures the answer afterwards; it cannot render a link, so a demo or a voice sample placed only in the widget is a choice nobody can actually evaluate. Table first, question second. Yes/no questions need no table, and a choice with no sample (an angle list) is still a table, just without that column.
+
+| Angle | The thread | Demo |
+|---|---|---|
+| friend-asks-friend | A friend notices something and asks | [watch](…) |
+| setup-flex | You send a photo, the friend reacts | [watch](…) |
+| swap-moment | You quit something worse for this | [watch](…) |
+| feature-as-punchline | The product's own mechanic is the reveal | [watch](…) |
+
+Same for voices: `video_catalog_list { kind: "voices" }` gives name, gender, accent and a `preview_url`. Put the name in a link so it plays. This was the clearest moment of the first real run: a voice table with playable samples. Do the same for any avatar or style choice a format exposes.
+
+A choice with an `enum` and no samples (the cartoon explainer's `style`, say) is still a table: one row per value, described in the words of the field's own `description`, with "no demo yet" in the sample column. Don't invent what a style looks like.
+
+Never ask for a promo code.
+
+### 5. Draft and price
+
+`video_project_upsert { brand_id, name, format, brief: { …answers, prompt, audience?, must_mention?, avoid? } }` is free. `brief` holds the picked format's `ask[]` answers **plus** the step-2 intent. Leave out any intent field the customer never gave. If `ready` is false, **stop** and relay `missing` in plain words.
+
+The server refuses any other key with `invalid_brief` and names every key it accepts. Fix the brief from that message; never drop the customer's intent to make the error go away.
+
+**If `questions` is not empty, ask them now, in one message, before showing the price.** Each one says which brief field its answer fills (`fills`). Save the answers with `video_project_upsert { project_id, patch: { brief: { <fills>: <their answer> } } }`. The bounds:
+- **One round.** Never ask a follow-up, and never ask the same thing twice.
+- **Never required.** If they skip them or say "just make it", carry on with the draft as it is.
+- **Empty `questions` means ask nothing.** The server skips it when the brief already says what the ad is for and who it's for, and never asks what the brand record already knows. "Make me a video ad for X" stays a complete request.
+
+Show the price the draft returned (the `quote`), **never a number from this page or the catalogue**. If it differs from the table's "~N", the quote is right. Convert at **100 credits = $1**.
+
+### 6. Write the script and show it, before the expensive work
+
+`video_render_run { brand_id, project_id, kind: "partial" }`.
+
+This reserves the credits and writes the script only: **no video is rendered.** It returns immediately with `status: "previewing"` and no script yet; the writing happens in the background. Poll `video_project_read` every 20 seconds (it lands in about 40) and read `order.preview`. Calling `kind: "full"` while it is still `previewing` is refused with `preview_in_progress`.
+
+`order.preview` is shaped by the format, and **every** orderable format has one. A preview was chat-only until 2026-09-25, and a kinetic-type customer approved a price and first saw the copy in the finished video.
+
+**A chat format** (iMessage / ChatGPT / Notes) fills `thread` (the message list), `angle`, `cta_text` and `selfie_url`. Show it as a readable transcript, not JSON:
+
+> **them:** wait why do you look so into your phone rn 😭
+> **me:** I literally just chose to betray the duke
+> **them:** omg is this a game or a book
+
+**`selfie_url` is a generated face — show it as a link.** These formats draw the selfie INSIDE the script step, so it never appears in `anchor_images` and `stage` stays `"script"`. It is still a face that will be in the ad, so it still needs their yes.
+
+**Any preview with `order.preview.stage: "image"`** stopped after the **picture**, not just the words, so they judge the face before paying for the video. Go by that field, never by a list of format names — it follows what the recipe's steps produce, so a format joins this branch without a skill edit. Today: the animated character, the reaction selfie, the podcast hosts, the UGC creator, and the voiceless dance story (four to six stills, and no spoken script at all — its stills and `detail` ARE the draft, so say that rather than reporting an empty script).
+
+Show every URL in `order.preview.anchor_images` as a link (the podcast format has two, one per host), alongside the script. Then say plainly, in this order: what they are looking at; that **nothing has been rendered yet and the pause is deliberate**, because the video is generated FROM this picture and changing the face now is cheap; that **approving starts the render and commits the credits already held**; and that cancelling instead releases the whole hold, so the picture costs them nothing. A pause with no reason given reads as a broken order.
+
+**A voiceover format** (kinetic type) fills `beats` instead, and `thread` is null. Each beat has `vo_lines` (what is spoken) and a `beat` label. `detail.hyperframe.plan.slates[].props` holds the words that go **on screen**, which for this format is most of the ad. Show both columns, in order:
+
+| # | On screen | Voiceover |
+|---|---|---|
+| 1 | Sunscreen that pills | Most sunscreens pill under makeup. |
+| 2 | Myth: all SPF is greasy → Fact: not a fluid one | This one is a fluid. It sinks in. |
+
+Read the spoken lines out as one paragraph underneath, so they can hear the pacing.
+
+Whatever the format, **quote it back verbatim.** Do not paraphrase, tidy or shorten the copy; they are approving the exact words that will be rendered.
+
+If `order.preview.brief_check` is present, read it before asking for approval:
+- `missing_mentions`: terms they asked for that the script never says. Tell them which, plainly ("It doesn't mention ChatGPT yet").
+- `endorsement_flags`: lines that make another brand sound like it endorses, partners with or ranks theirs. Show the line and say it has to change: a listed name may appear as "works with", never as "recommends" or "#1 for".
+
+If `order.brief_changed_since_draft` is present, the brief was changed after this draft was written. **Approving renders the draft as shown**, so redraft first (no reason needed), or tell them the change won't be in this video.
+
+Then ask: **use this, change it, or stop?**
+
+**One question decides how to change it: did they give you the actual WORDS, or did they tell you what is wrong?** Only the first route below keeps their words. The other two write new ones — which is right when the customer wants something different, and is a silent rewrite when they wanted what they wrote.
+
+- **They gave you the words** ("use these lines", "the end card must say Meet Goose", "keep this but change the second bubble") → `video_render_run { kind: "edit", edit: { script: { … } } }`. **This is the only route that keeps copy verbatim.** It puts their text through the format's own guards and costs nothing extra before approval. Send the shape the preview handed you: `script.thread` for a chat format, `script.beats[i].vo_lines` (one entry per beat, `{}` for a beat you are not changing) for a voiceover format, `script.slates[{ beat_idx, props }]` for on-screen words, `script.cta_text` for the end card, `ingredient: "character"` + `script.character.description` for the character itself.
+  - **An edit before approval IS the approval**: it applies the copy and starts the render at once (status → `running`). So show the exact words you are about to send, get a yes, and only then send it. An unapproved fix stays a proposal in the chat.
+  - Refused with `script_not_editable` → this format writes its own copy and takes no hand edit. **Say so, and do not paraphrase their lines into a redraft** — that hands them a video that is not what they wrote. Their real options are a redraft (new words, not theirs), a re-order with different answers, or cancel.
+  - Refused with `script_rejected` → a line makes a claim the brand's facts don't support. Relay the reason and offer a rewrite; never argue it through.
+- **They changed the BRIEF, not the copy** — the problem it shows, who it's for, a name to say, something to avoid, a note like "keep it dry" → save it with `video_project_upsert { project_id, patch: { brief } }` (use `notes` for anything that isn't one of the other fields; keep their original `prompt`), then `video_render_run { kind: "redraft" }` with no `reason`. The new draft is written from the updated brief, so **the words will be new** — this changes the instructions, not the script. Same cost wording as below: no new order, no new hold, a few credits inside the hold.
+- **They only said what's wrong** ("too salesy", "the character looks like a mug") → ask **why** in one line, then `video_render_run { kind: "redraft", reason: <their words> }`. **A redraft RE-RUNS the writer: every word, and the picture on a character format, is replaced.** Their reason steers the next draft; it is not copied into it. Never put exact lines in `reason` expecting them back. Say what it costs, precisely: "no new order and no new hold; it adds about N credits to what this video costs, inside the hold" (N from the response's `redraft.credits_estimate`). **Never call it free.** Poll `video_project_read` until `preview` again and show the new draft plus `order.spend` (what each draft added, how much of the hold is left). A `redraft_exceeds_hold` or `redraft_limit` refusal means: approve a draft or cancel.
+- Different answers altogether (another format, another angle) → a fresh project, and cancel this one.
+- Stop → `job_cancel { job_id: <order id> }`. The whole hold is released and they pay nothing. Cancel only works while the order is `queued`, `previewing` or `preview`; once they approve and it is `running`, it is being made and cannot be refunded.
+
+This is the review. It happens here, not in the app.
+
+**If the server answers `preview_not_available`,** that is a bug: every sold format has a script preview. Say plainly "I can't show you the script for this one before it's made", and stop. Do not quietly skip the step and charge as if the gate had passed.
+
+### 7. Finish it
+
+Only after they approve the script: `video_render_run { brand_id, project_id, kind: "full" }`.
+
+Poll `video_project_read { brand_id, project_id }` **every 30 seconds.** Done means `order.status` is `done`; the same response then carries `video_url` (the project page) and `mp4_url` (the file).
+
+**How long depends on the format.** One number is wrong by 2x across the catalogue, and a customer told "about 5 minutes" at minute 9 thinks it has failed:
+
+| Format | Typical | Give up after | Why |
+|---|---|---|---|
+| iMessage / ChatGPT / Notes chat reveal | ~5 min | 10 min | No video is generated; a browser renders the phone UI, then ffmpeg cuts it |
+| Kinetic type explainer | **~10 min** | 20 min | Two AI b-roll clips, a voiceover, a music bed, HTML slides and a stitch |
+
+An unlisted or new format: assume the longer budget. Say the number you are working to up front ("this takes about ten minutes; I'll keep checking"), and say something at the halfway mark rather than going silent. Waiting is not failing; silence feels like it.
+
+### 8. Deliver in the chat
+
+**Lead with `video_url`** — the project page, where the video plays and they can come back to it. Give `mp4_url` second and name it as the file ("and the raw MP4, if you want to download or upload it"). Never hand over the CloudFront `.mp4` on its own: it is a file, not a place — nothing to return to, nothing to edit from, and it reads like a debug artifact rather than a delivery. If `video_url` is missing, poll once more; never substitute the mp4 for it silently.
+
+Say what the video is: length, ratio, what's in it. This is delivery **in the chat** — the link is the video, not an instruction to go to the app. If they want a change, offer to make another with different answers. That is a new order and a new charge; say so.
+
+The only reason to send someone to the app is **payment**: not enough credits, or a plan without video.
+
+## Decision Rules
+
+- **One sentence is a complete request.** Never answer "make me a video ad for X" by asking which format, which tool or what to do next. Run steps 1–3 and let the table do the asking.
+- **One brand in the org → never ask which brand.** State the one you used.
+- **Open question first, table second.** Don't lead with the whole catalogue. The goal question comes before any list, and the table comes ordered, with one suggestion.
+- **No approval of the SCRIPT → do not call `kind: "full"`.** The price gate is not the script gate. They approve a number in step 5 and the actual ad in step 6.
+- **More than two options → table in the message.** Every time. Options with a sample or demo the customer can't hear or see are not really choices. A question control may capture the answer after the table, never instead of it.
+- **`ready: false` → stop.** Ordering anyway fails and wastes their time.
+- **Unsure whether an order went through → read `video_project_read` first.** Never use the charging tool as a status probe. Only if the project shows nothing at all, re-call `video_render_run` on the SAME `project_id` (idempotent per project). Never create a second project; that is a second charge.
+- **Quote cards, never paraphrase them.** The card is the server's promise about the format. A reworded card can promise something the format cannot do.
+- **A contradiction with the card outranks every keyword match.** Check what they asked for against what the card and the `ask[]` options say the format does; a format that can't do the ask is never Suggested.
+- **They asked for a format that isn't in the catalogue** → it isn't available yet. Say so, show the table, and don't improvise a lab recipe.
+- **Run failed → say so plainly.** The credits are released automatically. Offer a retry; never retry unasked.
+- **Their words go in an `edit`, never in a `redraft` reason.** A `reason` steers the next draft; it is not copied into it. The moment a customer gives you actual copy, the only honest routes are `kind: "edit"` or telling them this format will not take it.
+- **Deliver the page, not the file.** `video_url` leads, `mp4_url` follows. A bare CloudFront link is not a delivery.
+- **The brief is the customer's words, not yours.** `prompt` is their answer, verbatim or close to it. `audience`, `must_mention` and `avoid` hold only what they said. Another brand in `must_mention` means they asked for it; it can be named as "works with", never as an endorsement or ranking.
+
+## Output
+
+The finished video in the chat: `video_url` (the project page) first, `mp4_url` (the file) second, with its length and ratio.
+
+The credits leave the balance when the order is placed (a hold). They are **captured** on success or **released** on failure or cancellation. A balance that dropped does not prove a charge, so don't describe it to the customer that way.
+
+## Quality Checks
+
+- A one-sentence opening got: the brand resolved (unasked when there is one), one open goal question, then a format table with demo links and one suggestion.
+- The table was ordered by the customer's goal, not the catalogue's order.
+- Every "What it looks like" cell is the card's own words. No Suggested format's card contradicts what the customer asked for; when nothing fit, you said so and named the closest with its trade-off.
+- Every multi-option question was a table in the message, with a demo or sample column wherever one exists.
+- Only the picked format's `ask[]` questions were asked.
+- The step-2 answer went into the order as `brief.prompt`, and no intent field held anything the customer didn't say.
+- They approved the **script**, not just the price, before the expensive work ran: the thread for a chat format, the on-screen words *and* the voiceover for a kinetic-type one.
+- You told them how long the render would take **for the format they picked**, and said something at the halfway mark instead of going quiet.
+- The quote you showed came from the server, never from memory or the catalogue.
+- Every line of copy the customer wrote is in the finished video word for word — it went through `kind: "edit"`, or you told them plainly that this format would not take it. No supplied copy was ever paraphrased into a `redraft` reason.
+- The video was delivered in the chat as `video_url` first and `mp4_url` second. You did not send them to the app for anything but payment.
+- You asked for no promo code or reference video, and made no product claim the brand's own facts don't support.
+
+## Failure Modes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| "Make me a video ad for X" got back "which format / what would you like?" | Treated the one-liner as incomplete | Run steps 1–3 unprompted: resolve the brand, ask the goal, show the table |
+| Asked which brand in a one-brand org | Skipped the count check in step 1 | Use the only brand and say which |
+| Opened with the full format list | Skipped the goal question | Ask what the ad is for first; order the table by the answer |
+| Demo links invisible to the customer | The choices went only into the structured question control | Table in the message first; the control only takes the answer |
+| `format_not_available` | Not an orderable format | Re-read the catalogue; offer what's in it |
+| `brand_not_ready` | Brand has no product photos or logo | Relay `missing` in plain words; stop |
+| `invalid_brief` | The brief carried a key this format doesn't accept (e.g. another format's question, or a made-up field like `tone`) | The message lists what is accepted. Move the customer's words into `prompt`/`audience`/`must_mention`/`avoid`; never drop them |
+| The script ignores what they asked for | The step-2 answer wasn't sent (it only sorted the table), or they added something later that never reached the brief | Send it as `brief.prompt` in step 5. Anything they add later goes in with `patch.brief` (`notes`) and then a redraft. The preview's `brief_check` shows missing must-mention terms |
+| Video not on this plan | Lite and trial have no video entitlement | Say so and point at the upgrade; this is the one app trip that's allowed |
+| Insufficient credits | Wallet short | Nothing was created or charged; report the shortfall |
+| Preview looks wrong | The script or the picture isn't what they wanted | They gave you the words → `kind: "edit"`. They changed the brief → `patch.brief` then a redraft with no reason. They only said what's wrong → `kind: "redraft"` with their reason. Same order, no new hold, a few credits inside it; never "free". Or `job_cancel` this one |
+| **The customer wrote the script and the finished video says something else** | Their lines went into a `redraft` `reason`. A redraft re-runs the writer: the reason steers the next draft, it is never copied into it. Seen on staging — "Keep this exact draft, use these lines: …" came back paraphrased, twice, and was paid for both times | Copy goes in `kind: "edit"`. If the format refuses it (`script_not_editable`), say so and let them choose a redraft, a re-order or cancel — knowing the words will be new |
+| Video started rendering before the customer approved | `kind: "edit"` on a preview applies the copy **and** starts the full render (status → `running`) | Show the exact words you're about to send, get a yes, then send the edit. An unapproved fix stays a proposal in the chat |
+| `draft_is_your_copy` on a redraft | The current draft is the customer's own edited copy; another draft would replace their words | Correct behaviour. Edit their copy again with `kind: "edit"`, approve it, or cancel |
+| `script_rejected` on an edit | A line makes a claim the brand's facts don't support | Relay the reason verbatim and offer a rewrite; nothing was charged |
+| The customer was sent a raw `cloudfront.net/….mp4` | Delivered `mp4_url` (or `order.output_url`) instead of `video_url` | `video_url` leads and `mp4_url` follows. Both come back from `video_project_read` once `order.status` is `done` |
+| `recipe_brief_locked` | You patched `script_drafts` raw on a format project, which would have skipped the brief's checks | Send the change as `patch.brief` instead |
+| `format_answers_locked` | After ordering, you tried to change the format's own answer (voice, angle, selfie) through the brief | Those change what the run costs. Use `kind: "edit"` where the format lists it, or start a new project |
+| Asked the customer three rounds of questions before anything was made | Treated `questions` as a form, or asked your own follow-ups | Ask what `questions` holds, once, in one message. Nothing else. Skipping is fine |
+| `preview_in_progress` | You called `full` while the script was still being written | Keep polling `video_project_read` until `order.preview` appears |
+| Cancel refused | The order is already `running`; they approved it | Say it's being made; a refund isn't possible now |
+| No render after the format's budget (10 min chat, 20 min kinetic) | The worker didn't pick the run up | Credits are held, not spent. Say it's queued and you'll follow up; don't re-order |
+| `preview_not_available` on an orderable format | A bug; every sold format has a script preview | Say so and stop. Do not order without showing the script |
+| An edited script is refused (`script_not_editable`) | This format's writer takes no hand edit (its `edits.script` is empty). Only some formats do | Should have been said at the table. Their words cannot be rendered verbatim here: offer a redraft (new words), a re-order with different answers, or cancel — and never quietly paraphrase their copy into the redraft reason |
+| A "hero, no villain" brief got the villain cartoon | The card was paraphrased ("narrates the fix") and the fit check never read what the format can't do | Quote `card.description`; check the ask against the card and `ask[]`; never Suggest a contradiction |
+| Two videos, two charges | A second project was created instead of continuing the first | Continue on the SAME `project_id` |
+