---
reliability: 4.2 # 5 − image gen .3 − i2v .6 − music .2 − dual-format stage over 5 (.2) + proven E2E showcase (THE ROAD, 36+36+1 all first-pass) .5
---

# History journey — agent playbook ⭐ flagship

> Paste this whole file (with the BRIEF filled in) into Claude cowork, chat, or Code. **This is the ultimate-showcase flagship: a single 90-second cinematic time-travel reel.** Build a Netflix-quality history journey through N era beats, all unified by ONE evolving through-line — a road, a coastline, a kitchen counter, a tailor's mirror, a piano keyboard, whatever connects your eras. Each beat is a 5-second clip. Dual format (cinema 2.35:1 + vertical 9:16). One continuous instrumental score that builds across the full arc. The artifact a museum or a streaming service would put in front of their opening title sequence.

## What you'll get

A flagship-grade two-format history journey reel, structured the way a prestige documentary opening sequence works:

- **A single through-line that evolves** — the connecting visual element (a road, a coastline, a piano keyboard, a recipe surface) is the protagonist of the reel. It ages across centuries with each beat.
- **N era beats** (default 18 — granular enough for 5,500 years of history with one beat every ~300 years) — each beat is a 5-second cinematic shot showing the subject of that era against the evolved through-line.
- **Cinema 2.35:1 anamorphic cut** — 1920×1080 (or 1920×820 letterboxed), the format a film festival or Netflix-tier streamer would accept.
- **Vertical 9:16 TikTok cut** — 1080×1920, natively reframed (NOT center-cropped from the cinema version), the format a Gen Z audience will share.
- **One unified instrumental score** — `music` generated (`[Instrumental]` default), ~15s seed looped under the full 90s via `ffmpeg-mux` + `audio_fill: "loop"`, builds from era-1 instrumentation through to era-N at the finale. Native per-clip audio ducked to 22% so the score is the throughline.
- **Showcase HTML page** — single shareable page with both video formats embedded, era-by-era breakdown, pipeline trace + cost summary, ready for press kit / pitch deck / showcase.

**Time**: ~15 minutes wall clock (highly parallelized). **Your attention**: ~10 minutes across 3 gates (storyline approval, mid-render check, final QC). **Cost**: $25–35 end-to-end for 18 beats × 2 aspects. *This is the maximalist flagship* — the playbook for a single artifact that demonstrates the full range of the MCP stack: gpt-image at era-accurate fidelity, `seedance-i2v` for cinematic motion (`ltx-q-i2v` fallback if a beat fails upstream), `music` for the unified score, `ffmpeg-concat` → `ffmpeg-mux` → `ffmpeg-export` for the dual-format stitch.

## Tell the agent about the journey

```yaml
journey_title:            # e.g. "THE ROAD" — bold, all-caps, the reel's name. Used in title card + showcase.
journey_subtitle:         # e.g. "A History of Human Transportation" — descriptive secondary line.
through_line:             # The ONE visual element that connects all N beats. Examples:
                          #   "a single dirt-to-asphalt-to-smart road"
                          #   "a coastline at the same harbor across centuries"
                          #   "a kitchen counter that ages from stone to butcher-block to quartz"
                          #   "the same piano keyboard in the same room across 300 years"
                          #   "the same tailor's full-length mirror reflecting the room behind it"
era_span:                 # e.g. "3500 BC to 2050 AD" — start and end eras. Drives the date stamps.
beat_count:               # 12 (default tight) / 15 / 18 (granular) / 24 (very-granular). 5s per beat.
beats:                    # Ordered list of N era beats. Each item:
                          #   - year: 1885 AD
                          #     subject: Karl Benz Motorwagen (the world's first gasoline car)
                          #     through_line_state: cobblestone German town street
                          #     mood: astonishment, pedestrians watching from the sidewalk
                          # Agent will compose the gpt-image prompts from these structured beats.
camera_rule:              # e.g. "eye-level wide shot, 35mm equivalent, subject approaches from middle-distance"
                          # This is the CONTINUITY rule — same camera across all N beats.
lighting_arc:             # The one-day-arc that ties the eras together. Default:
                          #   "earliest era = frosty dawn; mid eras = golden noon → afternoon; modern = dusk;
                          #    near-future = twilight; finale = sunrise"
                          # The earth turns once across 90 seconds.
music_brief:              # The score's mood evolution. Example:
                          #   "Builds from medieval lute + soft drones (beats 1-3) → orchestral hammer percussion
                          #    of the industrial revolution (4-6) → full strings + jazz rhythm peak (7-9) →
                          #    synth pads + electronic pulse (10-11) → choral lift at the aerial finale (12)."
formats:                  # ["cinema" (2.35:1), "vertical" (9:16)] — default both
                          # Drop "vertical" if you only need cinema (saves ~$10 + 5 min)
journey_slug:             # kebab-case for output filenames + showcase page. e.g. the-road / history-of-fashion.
```

---

## How the agent should run this (interaction contract)

1. **CONFIRM (one message, ≤1 question):** restate in 1 line ("<journey_title>: N beats, <through_line>, dual format, ~$25–35, ~15 min") + the real choices: full 18-beat dual-format · lean 12-beat cinema-only (~$10, −5 min) · drop the vertical cut (−$10). Ask only if `through_line` or `beats` are missing; otherwise state assumptions and start.
2. **PREVIEW CHECKPOINT:** two cheap gates before the expensive 2×N i2v wave — the N-beat treatment (text, $0) and the Wave-1 keyframe contact sheet (~$5–8). Invite re-fires of off-era/off-continuity beats at the contact sheet; never animate unreviewed keyframes.
3. **NARRATE:** 1 line + ETA per wave ("i2v wave 2/5: beats 5–8 cinema, ~3–4 min, jobs …"); poll `get_create_media` every 10–15s, ≤4–5 i2v in flight, update at least every 2 min.
4. **FAIL GRACEFULLY:** seedance-i2v hang/"fetch failed" → retry once → `ltx-q-i2v` (`num_frames: 241`, resolution "auto") → `ltx-i2v`; gpt-image 422 → soften the era phrasing → `nano-banana`; music fail → retry once, else ship with ducked native clip audio + a note. 1-line WHAT/WHY/fallback; ≤2 retries per beat; an (N−1)-beat reel with the gap named beats nothing.
5. **DELIVER:** both cuts + one honest line ("beats 14–15 signage slightly soft — i2v style-drift ceiling; through-line held across all 18") + ONE next step ("publish the showcase page, or re-fire beat 14").

## What can disappoint (cap ceilings)

- **Era anachronisms** — even with named period details, expect 1–2 keyframes per 18 to need a re-fire for zippers/modern fonts/wrong vehicles.
- **Through-line continuity is ~90%, not exact** — the road/coastline reads as the same place, but pixel-level geography shifts beat to beat.
- **i2v half-motions** — a 5s clip can end mid-gesture despite the completion-emphasis prompt; the cut hides most of it.
- **Looped score seam** — a 15s bed looped under 90s can have an audible join; the build-arc brief mitigates, doesn't eliminate.

## Quality controls (auto-applied)

This playbook is built on the closed quality loop. The agent applies these by default — the QC is what separates this from "a slideshow of AI images":

- **Storyline approval first.** Before any MCP fires, the agent shows you the full N-beat treatment (year × subject × through-line state × mood × lighting). You approve or redirect; only then does Wave 1 fire.
- **Same camera, same direction, same focal length** — every keyframe prompt enforces the `camera_rule`. Continuity through the cuts is the load-bearing creative choice; without it the reel becomes a slideshow.
- **The through-line never breaks** — every prompt includes a phrase like "the same road, now paved" / "the same coastline, now containerized" so the gpt-image model knows the connecting element is invariant across centuries.
- **One continuous color grade across the full reel** — the `lighting_arc` ensures the earth turns ONCE across the 90 seconds rather than each beat being its own random sky.
- **Era-accurate vehicle/subject AND architecture** — every prompt names specific period details (1908 Ford Model T, NOT "generic old car"; Roman basalt slabs, NOT "ancient stones"). The agent researches era specifics if any beat is under-specified.
- **NO readable text on signs** — every era-modern prompt explicitly says "sign shapes only, no readable text" because AI text rendering is the hardest known failure mode and breaks the documentary illusion.
- **Dual-format parity** — each beat is rendered TWICE (cinema 2.35:1 + vertical 9:16) using the playbook's `aspect_ratio` parameter so neither format is a center-crop of the other. Native composition both ways.
- **i2v completion-emphasis** — every `create_media({ action: "animate", model_override: "seedance-i2v", resolution: "auto", duration: 5 })` prompt includes "the subject drives/moves toward the camera, eye-level holding shot, era-appropriate motion" + "complete the motion within 5s" so the clip doesn't produce a half-done animation. Lesson learned from BLOOMWORKS Stagger/Mustang first-pass.
- **i2v fallback chain** — `seedance-i2v` → `ltx-q-i2v` → `ltx-i2v` if any single beat fails upstream. The agent doesn't ship a hole in the reel. **Cap in-flight i2v at ≤4–5 and poll to `done` before the next batch** (BYOC video caps are capacity ~2 behind one dispatch worker).
- **One unified music score** — `create_media({ model_override: "music", prompt: "[Instrumental] …" })` (omit `lyrics_prompt` for an instrumental bed). Muxed under the full reel with `ffmpeg-mux` + `audio_fill: "loop"`; native per-clip audio ducked to 22% so the score is the listener's throughline.
- **Mid-render check.** After all keyframes land (Wave 1), the agent surfaces a contact-sheet of all N images for your review. You can re-fire any that look off-era or off-continuity before the more-expensive i2v wave fires.
- **End-of-render QC.** After the dual-format reels stitch, the agent runs a final visual check: cinema + vertical both play end-to-end, music sync is correct, no clip is shorter than expected, no clip is blank or moderation-failed. Surfaces any defect with a one-click retry.

> **Why the through-line works:** the human eye holds continuity across cuts by anchoring to ONE persistent element. A road that ages from mud to asphalt to smart-LED across centuries reads as continuous time travel even when everything else changes. Without the through-line you have a slideshow; with it you have a film. This is the single creative choice that makes the playbook work — pick a through-line that genuinely evolves with your subject (transportation → road; food → counter; music → keyboard; fashion → mirror; communication → desk; warfare → battlefield horizon).

## Output structure

```
public/chapters/<journey_slug>/
  beat-01-3500bc-cinema.png          ← keyframe pairs per beat
  beat-01-3500bc-vertical.png
  ... × N beats × 2 aspects ...
  beat-01-cinema.mp4                 ← i2v animations per beat
  beat-01-vertical.mp4
  ... × N beats × 2 aspects ...
  music.mp3                          ← unified score, looped under the reel
  the-road-cinema.mp4                ← final 90s cinema reel
  the-road-vertical.mp4              ← final 90s vertical reel

public/chapters/<journey_slug>-example.html  ← showcase page
public/case-studies/<journey_slug>.html      ← optional showcase entry
```

The example for this playbook is **THE ROAD** — A History of Human Transportation: 18 beats × 5s = 90 seconds, 3500 BC → 2050 AD, the road as the through-line. **Live example shipped 2026-05-30**: [`/chapters/the-road-example.html`](https://storyboard.daydream.monster/chapters/the-road-example.html) — dual-format reels (cinema 1920×1080 + vertical 1080×1920), 36 keyframes + 36 i2v + 1 score, all first-pass success, ~$28 end-to-end.