product-demo-director

---
name: product-demo-director
description: Turn product evidence, narration, and footage into a single-focus announcement, dramatic Save-the-Cat, causal investor, sales, or short-form demo with narration-safe cuts, exact-frame deterministic QA, and an advisory AI judge loop.
---

# Product Demo Director

Give it product evidence, footage, and a JSON production contract. It can make a single-focus
announcement film, a dramatic Save-the-Cat product story, or a continuous causal product film, with
per-shot TTS, one continuous generated performance, or one locked human narration master.
It binds every render to source hashes and integer frame boundaries, runs deterministic delivery QA,
then lets a Gemini judge review story and taste.

Before writing narration, choose the buyer's question and the recorded change that answers it.
Inspect the strongest proof at delivery size, then build the shortest causal path to it. Preserve
the initiating action and enough settled time to read the result. If the footage cannot support
the intended claim, capture the missing evidence or narrow the claim; a zoom cannot supply it.
Compare narrated quantities and absolute wording with the actual counts and limitations in the
filmed evidence. A source reference or an approved claim label does not resolve a visible contradiction.

Plan native capture density against the largest **delivery-frame** magnification, not only the
phone preview. A 1080p export does not make a twice-enlarged 1× screenshot HD. Use `captureScale`
2–4 for product footage that needs close-ups; retain that raster through normalization. Inspect
thin glyph strokes at 100% and check the small-screen composition separately. A complete panel
can be sharp yet too small to understand.

When reconstructing an existing case with native product components, declare
`visualTreatment: "replay"`, `liveState: false`, and a `replayProvenance` manifest listed in
`production.sourceManifests`. Label the reconstruction visibly. Bind the frozen data **and the
matching product revision**: updated business logic can change historical counts even when the
packet is identical. Never portray a replay as a fresh recording or a new recorded decision.

For a centered composition, opt into `direction.align: "center"` and place the complete product
unit on a symmetric `screenRect` (`x + width / 2 = 50`). Keep one clear reading axis and reserve
separate space for the product, the buyer's question, and a concise readout. The story should
connect the pain to an observable workflow and its bounded outcome; centered decoration alone
does not explain the product.

## Motion-graphics films (no footage)

When the ask is a launch, brand or "slick, punchy, studio-level" ad rather than a footage demo, use the
motion-graphics track: read `docs/MOTION_GRAPHICS.md` completely, then follow its method in order.
**Style frames first**: design 2 to 3 contrasting directions as stills (hook, proof, close), show them, and
animate only the direction the founder picks. Build with `motion/kit.js` (hits `pop()`, flows `glide()`,
measured `callout()`, colour-block `sceneWipes()`), keep a locked scene timeline for music and cues, and
deliver through `tools/motion.py all` (motion-blurred render, mix, QA). Study
`examples/motion-pdd-self/` before designing: it is the worked example. Never fall back to busy
product screenshots, a TTS narrator, AI-generated footage, or generic dark/light UI themes for this track.

The motion engine is a single props-driven Remotion composition, so one pipeline renders many
cuts (teaser, walkthrough, race, full demo) from the same assets.

## When to use

- Producing a launch announcement, dramatic Save-the-Cat product story, causal live-product demo, or
  sales walkthrough.
- Re-cutting one set of footage into multiple lengths/formats.
- Narration-locked investor demos where exact claims, frames, continuity, and source framing matter.

Not for: editing arbitrary cinematic footage, or anything where you don't control the shot list.

## Setup (once)

```sh
cd engine && npm install && cd ..
python -m venv .venv && . .venv/bin/activate && pip install -r tools/requirements.txt
playwright install chromium          # only if you use tools/capture.py
export GEMINI_API_KEY=...             # judge (gemini-3.1-pro-preview) + non-auto-paced Gemini TTS + Lyria 3.5
export ELEVENLABS_API_KEY=...         # required for auto-paced narration maps; also VO + music
```

New announcement scaffolds use `narration.fromMap=true` and `production.autoPaceNarration=true`;
they require `ELEVENLABS_API_KEY` because `pace.py` consumes ElevenLabs character timestamps.
With only `GEMINI_API_KEY`, `vo.py` still speaks non-auto-paced and legacy scripts through Gemini
TTS (`--provider gemini`, voice via `gemini_voice`/`tts_direction`), while `music.py` composes
through Lyria 3.5 and `judge.py` can review the final cut. ElevenLabs is selected automatically when
its key is present.

## Run the pipeline

A *project* is a folder with `script.json` + an `assets/` dir of clips (and, ideally, a
`brand.json` and a `product.json`). Start one with
`./pdd new projects/my-demo --name "My Product"`. The source-only
`examples/save-the-cat/` project documents how this repository created its own announcement; its
generated media remains ignored. The first three steps below onboard a brand, let the director
capture footage, and draft the script from the product brief:

```sh
# 0a. ONBOARD — auto-extract the brand (palette/font/logo) from the product site, confirm, write brand.json
python tools/onboard.py --project projects/my-demo --url https://yourproduct.com   # or --template / --manual

# 0b. SHOOT — the director records the footage itself -> assets/<name>.mp4 (web app and/or terminal/CLI)
python tools/shoot.py --project projects/my-demo                                  # reads shoot.json
#   (one-shot web:  python tools/shoot.py --url https://app.x.com --goal "tour it" --out assets/web.mp4)

# For a Claude/Codex-operated product, turn a committed whitelisted session into one workbench
# clip with prompt, tool actions, preview, timeline, render, and QA states. The result is a curated
# replay and must be labeled as such; it is not a proprietary agent-UI screen recording.
python tools/workbench.py --project projects/my-demo \
  --session projects/my-demo/_src/codex-workbench.json \
  --out projects/my-demo/assets/codex-workbench.webm

# 0c. DRAFT — choose the story grammar explicitly. Use launch-film for a public announcement.
python tools/script.py --project projects/my-demo --format launch-film --seconds 60

# For a 30-second dramatic product story:
# python tools/script.py --project projects/my-demo --format save-the-cat --seconds 30

# For a three-minute causal product story:
# python tools/script.py --project projects/my-demo --format causal-workflow --seconds 175

# 1. voiceover -> per-shot audio/manifest.json, or one generated narration master. For an
#    announcement, set narration.fromMap=true and author one exact thought + shotN per map entry;
#    ElevenLabs is required and writes character-level timing beside the master.
python tools/vo.py --project projects/my-demo

# 1b. narration pacing -> move each picture cut to a safe frame between complete spoken thoughts
python tools/pace.py --project projects/my-demo --write

# 2. music bed  -> <project>/music.mp3 (sized to the paced runtime, picked up by build.py)
python tools/music.py --project projects/my-demo

# 2b. (optional) regenerate the bespoke SFX palette (a model listens and keeps the best/cue)
python tools/sfx.py

# 2c. DIRECTION — new drafts already use studio. Preview or enable it on an existing script.
./pdd direct projects/my-demo
# ./pdd direct projects/my-demo --write
# Read docs/STUDIO_DIRECTION.md before authoring camera, type, transitions, annotations, or cues.
# Give moves a visible reason; arrive, then hold. Never invent product coordinates or score values.

# 2d. EDITORIAL — after narration pacing, anchor each important thought to an inspected source frame.
./pdd editorial projects/my-demo --write
# Read docs/EDITORIAL_DIRECTION.md for sourceBeats and sourceTimeline. Capture wall-clock marks
# are not source timestamps. Keep actions in real time; compress only identified navigation.
# Audit warnings prompt picture review. Unknown proof timing is not a quality pass.

# 3. PREFLIGHT — block source, story, authority, claim, camera, and narration violations
python tools/preflight.py --project projects/my-demo --strict

# 4. ASSEMBLE + RENDER — exact frames, compiled direction-plan.json, props, build plan, artifact
python tools/build.py --project projects/my-demo --contracts strict

# 5. FINISH — preserve exact frames while creating a two-pass loudness-normalized, BT.709 web master
python tools/finish.py --input projects/my-demo/out/demo.mp4 \
  --out projects/my-demo/out/demo-final.mp4 --require-artifact

# 6. FINAL-MEDIA QA — bind and decode the exact MP4; check frames, streams, audio, black/silence,
#    and generate review sheets. This gate is deterministic, not a model opinion.
python tools/qa.py --video projects/my-demo/out/demo-final.mp4 \
  --project projects/my-demo --require-artifact --strict

# 6b. REVIEW — local film playback, searchable shots, narration, and bound delivery findings
./pdd review projects/my-demo
# Use --serve to review at a loopback URL with frame-accurate media seeking.
# Return out/review.html alongside the final video. Regenerate after any source or story edits;
# an old review page is a snapshot, not a fresh delivery check.

# 7. JUDGE STORY/TASTE — only after deterministic QA; require the artifact manifest so a stale
#    or similarly named MP4 cannot be reviewed by mistake.
python tools/judge.py --video projects/my-demo/out/demo-final.mp4 \
  --require-artifact --all-lenses --runs 1 --fps 6 --context "what this demo is"

# For requested motion review, submit the complete actual video at 24 fps, then verify
# the temporal findings in playback. Use the requested model; static sheets are insufficient.
python tools/judge.py --video projects/my-demo/out/demo-final.mp4 \
  --require-artifact --model gemini-2.5-pro --lens motion --fps 24 --runs 1

# 7a. BEFORE an improve loop: compare the bundled bad fixture with your approved local master
python tools/judge.py --probe --probe-good projects/my-demo/out/demo-final.mp4

# 8. OPTIONAL SCORED EXPERIMENT — compare both display orders after candidate QA.
#    This command's 2–0 gate is an experiment policy, not a measure of viewer engagement.
python tools/compare.py \
  --champion projects/my-demo/out/champion.mp4 \
  --champion-artifact projects/my-demo/out/champion-artifact.json \
  --candidate projects/my-demo/out/candidate.mp4 \
  --candidate-artifact projects/my-demo/out/candidate-artifact.json \
  --candidate-qa projects/my-demo/out/candidate-qa/qa-report.json
```

Steps 0a-0c are optional conveniences to *generate* `brand.json` and `script.json` automatically.
The scaffold and source example include authored JSON, while footage, narration, music, renders,
and QA output are generated locally and ignored. `brand.json` is the brand source of truth — its
palette, font, and logo flow into the **engine theme** (not just the CTA wordmark), so the whole cut
adopts the brand. See `docs/CAPTURE.md` for autonomous shoot planning + terminal footage and
`docs/PRODUCTION_CONTRACT.md` for profiles, causal beats, source locks, human narration, claims,
cursor safety, exact-frame artifact binding, and shipping gates.

For final delivery, do a separate technical finishing pass after render when needed: voice isolation
or mastering belongs in the project's `audio/` files, and web-safe video normalization belongs in the
export MP4. Keep these distinct from creative grading, and verify with `ffprobe`, `volumedetect`, and
contact sheets before calling the artifact final.

To iterate, verify `judge.py`'s specific notes against the actual picture and sound before editing.
Judge scores are advisory; do not tune a film to maximize them or claim measured engagement from
them. Improve
`script.json`, `brand.json`, skill docs, rubrics, or engine code directly; do not treat a binary MP4
as the editable source of truth. Every candidate must pass deterministic gates first. When using
the optional scored comparison, review both display orders and retain the champion on a split or
noise-level change. Evaluate comprehension, evidence timing, readability, and continuity directly.
After repeated in-point/zoom/pacing changes fail to resolve the same note, revisit the narration,
story structure, or capture. Builds retain exact input snapshots so prior decisions stay inspectable.

For phone viewing, judge the film in a **320px-wide player**, with 390px as a second check; use a
different width when the brief supplies one. A readable desktop render can become miniature UI at
that size. Phone readability is necessary, but a frame of enlarged, severed UI fragments is still a
weak composition. Choose a complete meaningful unit: the button with its label, a full status card,
or the menu with its selected value. Keep qualifiers, units, consequences, and source labels visible.

Use connected camera moves when the viewer needs the relationship between an action and its result.
For new measured camera plans, include `framing.motion` (`{}` uses 1.5 screens/second and
1.2 zoom octaves/second). Resolve infeasible moves with less travel, a wider view, justified extra
time, or a cut that preserves source truth; preserve reading holds and actions. Source native FPS or 1× playback
does not constrain rendered camera velocity, so diagnose those separately.
For a complete inspected component at a natural story/state boundary, `framing.presentation="detail"`
mounts its native source rectangle on a clean brand canvas. It requires one fixed rectangle for the
whole shot; it does not justify cutting a sentence or inventing a state change. Reserve an actual
settled reading hold after arrival. Use `framing.entranceSec: 0` when the plate should already be
stationary on the first frame; omit it for the restrained default entrance. A detail plate retains
source timing and pixels, with editorial title/context outside it; it does not recreate product text
or hide a duplicate desktop behind it.

Presentation ratio follows visual meaning, not the file extension: generated/slide clips count,
and external encoded graphics need `visualTreatment: "presentation"` plus appropriate provenance
labels. Native recordings and designed explanations can coexist when the brief warrants them;
declare and assess that balance honestly. For motion review, inspect the whole exported sequence
with sound and the requested 24 fps Google review. Its receipt records submitted sampling and model
usage; neither static frames, model scores, nor passing QA establish production timing quality.

Measure glyph ink height when available and inspect the rendered motion, not just the size estimate.
If the complete unit cannot fit, choose a smaller complete unit or recapture a responsive layout with
larger UI. Higher capture density improves sharpness, not the amount of information a small player
can hold; enlarging soft text cannot recover missing detail. The review room's actual-width previews
and bound framing reports support this inspection. Neither geometric checks nor delivery QA certify
studio quality or engagement. See `docs/SMALL_SCREEN_FRAMING.md` for both presentation grammars and
`docs/STUDIO_DIRECTION.md` for connected motion and the legacy OpenScreen timing behavior.

## Script schema

`script.json` is both a timeline and, for final-delivery work, a production contract. Each shot is
one of `title | clip | split | stat | cta | score | bars | strip`. The default announcement
contract is generated by `pdd new`; the minimal shape below shows the additional evidence fields
used by a causal live-product profile:

```json
{
  "fps": 30,
  "production": {
    "profile": "yc_3m",
    "hardMaxSec": 180,
    "productBySec": 15,
    "requiredStoryBeats": ["input", "contradiction", "test", "decision", "receipt", "outcome"],
    "requireLiveProgression": true,
    "maxHumanDecisions": 1,
    "enforceSameScreenContinuity": true,
    "requireClaimEvidence": true,
    "sourceManifests": ["_src/codex-workbench.json"]
  },
  "claims": [
    { "id": "measured-result", "status": "verified", "evidence": ["evidence/result.json"] }
  ],
  "narration": {
    "file": "audio/final-human-master.wav",
    "sha256": "<sha256>",
    "expectedDurationSec": 169.62839,
    "durationToleranceSec": 0.01
  },
  "shots": [
    {
      "n": 1,
      "kind": "clip",
      "src": "live-case.mp4",
      "durSec": 18,
      "storyBeat": "test",
      "sourceType": "product",
      "liveState": true,
      "stateId": "test-running",
      "continuityId": "hero-case",
      "actor": "agent",
      "actionRisk": "low-friction",
      "claimIds": ["measured-result"]
    }
  ]
}
```

For an explicitly requested legacy before/after promo, the lighter timeline remains valid. `score` is an animated count-up,
`bars` visualizes sourced take scores clearing a pass line, and `strip` pans a filmstrip of shots:

```json
{
  "fps": 30,
  "music": "calm confident minimal corporate underscore, soft pulse, no drums",
  "brand": { "name": "Product Demo ", "accent": "Director" },
  "pronounce": { "ACME": "Ack-me" },
  "voice_settings": { "stability": 0.32, "style": 0.75, "similarity_boost": 0.85, "use_speaker_boost": true },
  "shots": [
    { "n": 1, "kind": "title", "title": "Your demo is a flat screen recording.", "durSec": 2.6, "vo": "..." },
    { "n": 2, "kind": "clip",  "src": "raw.mp4",      "inSec": 2, "chapter": "BEFORE", "scale": 1.0, "startScale": 1.0, "endScale": 1.18, "focusX": 50, "focusY": 68, "captionTop": 160, "vo": "..." },
    { "n": 3, "kind": "clip",  "src": "raw.mp4",      "chapter": "AFTER", "flash": true, "scale": 1.2, "accentAtSec": 1.4, "captionBottom": 150, "vo": "..." },
    { "n": 4, "kind": "split", "srcL": "raw.mp4", "labelL": "Raw", "srcR": "directed.mp4", "labelR": "Directed", "durSec": 4, "vo": "..." },
    { "n": 5, "kind": "stat",  "title": "Scored 92 / 100.", "durSec": 2.5, "vo": "..." },
    { "n": 6, "kind": "cta",   "title": "the demo your product deserves", "durSec": 3, "vo": "..." }
  ]
}
```

Notes:
- When a shot has `vo`, the on-screen caption defaults to that exact line. Override with an explicit
  `caption`, or set `caption: false` when subtitles would cover the live product. Any visible
  subtitle must match the spoken words.
- Use `narration.fromMap=true` plus exact `narrationMap[].text` and `shotN` for a generated master.
  When `production.autoPaceNarration=true`, configure `ELEVENLABS_API_KEY`: ElevenLabs character
  alignment fills the cue times, then `pace.py --write` moves the cuts before music/render. Gemini
  TTS remains valid when auto-pacing is disabled. A strict cut may occur only between complete
  mapped thoughts, and picture must retain the declared narration tail. Keep per-shot VO for short
  promos. Never globally accelerate supplied narration.
- `storyBeat`, `stateId`, and `liveState` describe causal progress. A final answer that is already
  visible before its initiating event fails the live-product contract.
- `actor` is `agent`, `human`, or `system`; `actionRisk` is `low-friction` or `consequential`.
  Low-friction work should not wait for human approval. Consequential work stays human unless the
  production contract explicitly authorizes autonomy.
- Keep one `continuityId` in one clip while the same screen and action continue. Put connected
  `zooms` inside that shot; split only on a declared route, application, or major state change.
- Lock human and other composition-sensitive sources with `preserveFraming` or
  `production.sourceLocks`. A locked source cannot be cropped or pushed in.
- Bind repo-native capture/replay files with `production.sourceManifests`. Each entry must be a
  project-relative file; its hash becomes a `capture-source` artifact input and changes the build ID.
- `focusX`/`focusY` are percentage anchors for the zoom origin. Use them to land motion on the
  thing the viewer must read or click, while keeping its context and cursor visible.
- `startScale`/`endScale` create a controlled push-in without changing the base `scale`; keep UI
  text legible and avoid zooming away from the narrated action.
- `captionTop` and `captionBottom` are pixel offsets. Use them when captions would cover a text
  field, CTA, report card, or browser/player controls.
- `accentAtSec` delays a sound effect until the actual completion event inside a shot. Use it for
  "report finished" or "purchase confirmed" moments instead of firing the sound at shot start.
- `clickX`/`clickY`/`clickAtSec` (clip) spring-zoom into a real click — `capture.py` overlays a
  visible eased cursor with a click ripple during web shoots and writes `<clip>.events.json`
  (click coords + timestamps), so these values come from the recording, not guesswork.
- `takes` + `passLine` (+ optional `takeLabels`) on a `bars` shot render REAL take scores clearing
  a pass line — feed it the judge history of the video itself.
- `sound: true` (clip) plays the clip's own audio — for UGC talking heads or a finished-demo excerpt.
- A narrated card (`title`/`stat`/`score`/`bars`/`cta`) holds for exactly VO + ~0.7s and is then cut
  (dead-air ceiling); opt out with `"hold": true`. The music bed ducks under every VO line and
  fades out at the end automatically.
- `accent` on a shot fires a palette sound on that beat (`click`, `data_tick`, `success_chime`,
  `confirm_cash`, `pivot_boom`); the pivot also gets a `riser` + boom automatically.
- `production.profile="announcement"` enables single-focus shots, required continuity IDs,
  narration-map coverage, between-thought cut enforcement, and protected end padding. Split-screen
  fails unless the production explicitly opts into the legacy treatment.
- `flash: true` (or `chapter: "AFTER"`) marks a legacy before/after pivot. It is not required or
  desirable merely because a causal workflow advances to a new state.
- `pronounce` rewrites spellings for the TTS audio only; captions keep the real spelling.
- `brand.name` + `brand.accent` render the CTA wordmark (accent tail colored).

## Craft rules

The methodology — each rule was a real mistake first — lives in `docs/EDITING.md` (the edit),
`docs/CAPTURE.md` (capturing live-app footage), and `docs/COLOR_GRADING.md` (color correction
and grading). Read them before authoring a script. Highlights:

- **Choose one causal unit of work.** Follow input → evidence → hypothesis → test → result →
  bounded decision → durable outcome. If the beats can be reordered, the cut is a feature list.
- **Make progress appear.** Reasoning, recommendations, and results arrive after their initiating
  events. Do not reveal a complete answer in the first frame and call it live AI.
- **Make authority visible.** The agent owns reversible, low-friction work; the accountable human
  appears only at a consequential boundary. Restraint under uncertainty is proof of judgment.
- **Escalate with a falsifiable test.** When one signal is inconclusive, show what evidence would
  change the decision, run the lowest-friction check, and update the case from the result. Another
  feature panel does not create the same causal pressure.
- **Use live takes for causality.** Stills and slides may explain sourced context, but they cannot
  prove that the product initiated work, changed state, learned, or completed a queue.
- **Show evidence, not only counters.** A scale claim needs events, receipts, or at least one
  completed packet. Rows disappearing quickly demonstrate motion, not casework.
- **Captions are optional; subtitles are exact.** Suppress duplicated text when it obscures dense
  UI. If text functions as a subtitle, it must match the spoken words.
- **One spoken action per visible step.** Use language a real operator would say, not an inventory
  of capabilities or API-like status prose. For an approved human master, the recording outranks an
  older written draft.
- **Pace by meaning.** Remove inert time, but retain the setup and decision holds that make the
  causal story legible.
- **Keep the camera connected.** One screen/session gets one clip and connected focus regions, not
  jumpy same-screen crop resets. Keep target, context, status, safeguard, and cursor visible.
- **Preserve people.** Moving customer, founder, or teammate footage retains its recorded framing
  unless the brief explicitly authorizes a punch-in.
- **Make integrations inhabited.** A Slack/email/case-system handoff lands in the customer's named
  operational context and reports completed work, exceptions, and evidence. Avoid generic internal
  channels or codenames the viewer has never met.
- **Introduce people after they speak.** Let the first complete sentence land, then use a brief
  freeze-frame name/role treatment if useful; return to the original moving composition afterward.
- **Show the work.** Open from the real entry point and include one click-to-evidence beat.
- **Redact identifiers, never the value.** Hide client marks; keep the proof sharp and legible.
- **Be honest.** Only verified claims; neither invent autonomy nor add unnecessary human gates.
- **End once.** After the operational payoff, show only necessary proof, one fresh forward-looking
  state, and one CTA.
- **Correction before look.** Product demos must preserve trust: neutral UI whites, legible text,
  stable brand colors, plausible skin, and matched adjacent shots. Do not apply a decorative
  color grade by default. UGC/founder footage should stay authentic unless the brief explicitly
  asks for a stylized commercial look; avoid global vignettes, blurred side-fill, saturation
  pushes, and brightness tweaks as defaults.

## Proof beats (the YC/PG canon rules)

How the proof shot earns belief — distilled from the YC/PG canon; violating these reads as
AI-washing to professional evaluators:

- **Proof hierarchy.** Rank what you show: real paying usage with exact numbers > pull signals
  (demand outpacing supply, users asking for features, word-of-mouth) > benchmark wins >
  pilot logos > polish. Never present pilots as product-market fit — name them as exactly what
  they are ("paid pilot, live" is strong *because* it claims nothing more).
- **Exact numbers beat adjectives.** "$11.4k in 3 months" beats "strong early traction";
  "68 → 84 in 8 iterations" beats "dramatically better". If the footage can show the number
  moving, never say the adjective at all.
- **Survive the AI-washing gauntlet.** One uncut real run on screen, exact figures, and a
  test-on-your-own-data ask in the CTA ("point it at yours"). A demo that only shows curated
  moments invites the question it can't answer.
- **Formidable register.** Plain, concise, matter-of-fact narration; confidence through
  substance, never asserted ("blazing fast" is banned; a visible timer is not).
- **Show the real authority boundary plainly.** A consequential payout, block, or policy decision
  may require one accountable signature; a reversible evidence request or research step may run
  automatically. Adding a reviewer to every step makes a real autonomous product look like a
  presentation tool, while hiding a consequential reviewer makes the demo untrustworthy.
- **Earnest beats polished.** A rough real run with real numbers outranks a beautiful
  simulation — polish only ever amplifies proof, it never substitutes for it.

## When it breaks

- **Preflight rejects a low-friction human gate** → model the real workflow. Let the agent or system
  execute reversible evidence gathering automatically; reserve the human action for the actual
  consequential boundary.
- **Preflight rejects a same-screen cut** → combine the adjacent source excerpts into one clip and
  use connected camera motion. A deliberate context/detail edit may use `presentationCut` only with
  continuous source time, a complete native unit, and a concrete reason. Do not invent application
  state changes to silence a check. An existing aligned narration master can continue across the
  picture cut with `continuous-audio` and a cue's consecutive `shotNs` span.
- **A crop makes text readable but leaves fragments of labels, controls, or sentences** → recompose
  around the complete meaningful UI unit. Preserve spatial context with a connected camera move,
  or use a complete native detail plate at a real story/state boundary. If that unit remains too
  small or soft, change the capture. For a short recorded fact, an exact source-bound typeset excerpt
  is also available through `term.py --focus-spec`; keep its explicit recorded/typeset label and
  verify every word against the source. More zoom cannot supply missing context or source detail.
- **A locked customer/founder source is cropped or punched in** → remove camera transforms and use
  `objectFit: "contain"`. Preserve the recorded framing unless the source owner approved a change.
- **Global narration hash/duration fails** → restore the approved human master or deliberately
  update its contract and audit. Do not stretch, speed, or silently replace it to make the timeline
  pass.
- **No ElevenLabs key** → an auto-paced narration map stops in `vo.py` before synthesis because
  Gemini TTS does not return the character alignment required by `pace.py`. Configure
  `ELEVENLABS_API_KEY`, or deliberately disable `production.autoPaceNarration` and author timing
  another way. Gemini TTS / Lyria remain valid for non-auto-paced and legacy narration/music
  (`GEMINI_API_KEY`), and projects with supplied or locally cached audio can still render. A 401
  is deterministic—replace the key; do not retry it.
- **A VO line fails or renders empty** → `vo.py` exits non-zero (a silent shot must never ship).
  Re-run after fixing; unchanged lines are cached and not re-billed.
- **Footage shorter than the VO line** → the clip freezes on its last frame (build floors clip
  duration at VO + 0.2s). Shorten the line or cut a longer excerpt — never ship the freeze.
- **Type renders as serif** → the brand font isn't installed; `build.py` appends the bundled
  Inter stack automatically, but always check captions in extracted frames.
- **Judge scores swing between runs on identical content** (±10 documented) → median-of-3 is the
  default; confirm `--probe` passes, use order-reversed pairwise comparison, and frame-verify any
  specific claim the judge makes before acting on it. A split does not beat the champion.
- **Judge is pointed at the wrong or stale MP4** → require `artifact.json`. The
  `judge.py --require-artifact` gate rejects a path or hash that does not match the bound output.
- **The cut passes the judge but contains a black frame, silence, cropped cursor, or incomplete error
  page** → the judge cannot waive delivery evidence. Run `qa.py --require-artifact --strict` and
  inspect opening/ending, every-five-second, cut-boundary, and configured critical-range sheets.
- **Three plausible zoom, in-point, or pacing candidates lose or split** → restore the champion and
  stop mechanical recutting. Recapture a missing action/state, revise narration, or change the story.
- **Identifier discovered in a rendered frame** → fix the source excerpt (crop or trim — never
  blur-patch the render), re-render, then re-verify the excerpt's boundary seconds at ~1fps.
  A folder or file named "redacted" is not evidence of redaction.

## License

MIT licensed. See [`LICENSE`](./LICENSE) and [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md).