0020 — keryx reel make: one-command reel orchestration¶

Status: IMPLEMENTED (2026-06-27). §7 decisions resolved — all per the recommendations: (1) require an existing storyboard, --from-post is a fast-follow; (2) --takes N>1 still auto-picks take 1 + notes audition; (3) [y/N] plan confirmation + --yes + --dry-run; (4) idempotency keyed on the selection existing; (5) fail-fast + resumable; (6) cover off unless --cover <scene>.) Date: 2026-06-27 Depends on: the existing stage cores it composes — gencmd (VO/music/card gen via GenerateInto), takescmd (pick + the now-fixed media wiring, B-2), internal/takes (selection state), pkg/cmd/reel/build (RunBuild/RenderInto), and the B-1 fix (gen creates its dirs). No new generation behaviour — pure orchestration.

1. Goal & scope¶

Producing one reel today is ~25 commands (voice gen ×N, voice pick ×N, music gen+pick, cards gen+pick ×N, reel build). keryx reel make -w <slug> collapses that into one pass: for a workspace that already has a storyboard, generate every missing artefact, auto-select it, and build the reel — re-runnable and only generating what's missing.

reel make is the "just make it" fast path; the per-stage gen/pick commands remain the audition loop (generate N candidates, pick the best). make defaults to one take and auto-picks it.

In scope: orchestrating VO + music + cards (+ optional cover) gen→auto-pick→build over an existing storyboard, idempotently, with a spend plan. Out of scope: drafting the storyboard (a separate, human-reviewed step — storyboard draft), the multi-take audition loop (the per-stage commands), posting.

2. The pipeline¶

reel make -w <slug> runs these stages in order, skipping any whose output already exists (idempotent re-runs — no re-spend):

1. Validate the storyboard (the same reel.Validate build uses) — fail early.
2. VO — for each card with narration, if vo/NN.mp3 is absent: gen --takes T then auto-pick. (Skipped under --silent.)
3. Music — if music.mp3 is absent: gen a bed then auto-pick. (Skipped under --silent / --no-music.)
4. Cards — for each overlay card with a scene, if its media isn't selected: gen --takes T (with --avatar/--theme as passed) then auto-pick (which wires Card.Media, B-2).
5. Cover — only when --cover <scene> is given and no cover exists: gen + select.
6. Build — reel build (VO-timed, or --silent) → reel-<slug>.mp4.

A --dry-run prints the plan (which stages would run + how many provider calls) and spends nothing.

3. Auto-pick + idempotency¶

• Auto-pick = select take 1. With the default --takes 1 it's the only take; with --takes N>1 make still selects take 1 and notes "audition with voice/cards pick for a better choice". (make is the fast path; auditioning is the per-stage loop.)
• Idempotent: a stage is skipped when its selected artefact already exists (vo/NN.mp3, music.mp3, the card's Media, cover.png). So a failed/partial run is cheap to resume — re-running only generates what's still missing. (Candidate takes in */takes/ don't count as "done" — only a selection does.)
• No silent overwrite: make never re-generates over an existing selection; use the per-stage commands (or reel prune) to redo one.

4. Flags¶

5. Reuse map (composition, no new gen)¶

reel make is a thin sequencer over these — each is already context-timed + bounded; make adds the loop, the skip-if-selected guard, the plan, and the confirmation.

6. Spend & safety (it's PAID + multi-call)¶

reel make fans out many paid provider calls (VO per line + music + cards), so: - It prints the plan first — the stages it will run + the count of provider calls (e.g. "8 VO + 1 music + 5 cards = 14 generations") — and requires confirmation (a [y/N] prompt, or --yes for unattended). --dry-run prints the plan only. - Fail-fast: stop on the first stage error; the partial selections persist, so a re-run resumes (idempotency). The error names the failed stage + remediation. - Honours the same bounds as the per-stage commands (the --takes safety cap, the per-call timeout). No new spend path — just more calls in sequence.

7. Decisions to confirm before building¶

1. Storyboard prerequisite. Require an existing storyboard (rec — drafting is a separate, human-reviewed step) vs a --from-post <md> that drafts first. Confirm require-existing for v1 (a --from-post convenience is a fast-follow).
2. Auto-pick policy with --takes N>1. Select take 1 + note (rec) vs refuse (require --takes 1 for make) vs stop-after-gen-for-audition. Confirm take-1-default.
3. Spend confirmation. A [y/N] plan confirmation + --yes to skip (rec) vs always run (no prompt) vs always require --yes. Confirm the prompt + --yes.
4. Idempotency key. Skip a stage when its selection exists (rec) — confirm that candidate takes alone don't mark a stage done.
5. Failure mode. Fail-fast + resumable (rec) vs continue-and-report-per-stage.
6. Cover default. Off unless --cover <scene> (rec) — most reels bookend with the cover art only when one's authored.

8. Testing / DoD¶

Failing test → code → green just ci. The gen/build cores are faked (no spend, no ffmpeg) behind their seams; unit-test the orchestration: stage ordering, the skip-if-selected idempotency (a second run generates nothing), --silent/--no-music stage skipping, --dry-run spends nothing, the plan/confirmation, fail-fast + resume. A godog scenario drives reel make end-to-end through the fakes (board → fake gen → auto-pick → build), asserting the mp4 + that a re-run is a no-op. The real provider path stays INT_TEST=1-gated. Docs: a reel make command page + a how-to ("make a reel in one command"). Scaffold with gtb generate command --name make --parent reel.