topic-to-video
Skill3 starsChanged 2 days agoMITView on GitHub
Turn ANY topic — or a slide deck — into a narrated explainer short video, automatically: researches the topic, writes and voices the script, designs and builds the visuals (cinematic Remotion tier or HTML pages; a deck's slides full-frame with gentle motion and timed callouts) and burns in captions. Any language; can voice a deck in a different language than its slides. Use whenever the user wants a short video about a subject or from slides — e.g. "make a video explaining how MRI works", "make a launch video for this product", "做一个讲解视频介绍X", "turn these slides into a video", "narrate my pptx", "add a voiceover to my slides", "把幻灯片做成视频", "把英文幻灯片配成中文解说视频". Accepts a topic, .pptx, .pdf, an image folder, or a hand-off from slide-maker. Free by default (edge-tts + ffmpeg); optional cloud TTS. Editable storyboard, a sample for sign-off, then the full video. Trigger even without the word "skill".
- Reads credentials
- Installs packages
1 other project uses a version of this.
Adopted by
Most recently taken up by
- tamtree-ai/stick-stagetheir own version, first seen Nov 15, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- tamtree-ai/stick-stage★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. About 0 are common, 6 are distinctive, and 17 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 29
Never trade quality for less work: No shortcut because a step is long: re-cut a part, rebuild a shot, re-render.
- Distinctive: line 30
Use what the skill has built: Before building, list the capabilities this film can use and put each to work where the content admits it:
- Very specific: line 65
Every clip is mastered in place (EBU R128 I=-14, trailing dead air trimmed, word times stay valid.
- Very specific: line 81
Run it after ingest and BEFORE the shot-director.
- Very specific: line 176
The cut has to be authored: No seam reaches a film unless something writes transition_in, so run python3 scripts/seam_plan.py <out_dir>.
- Very specific: line 212
One structure, many beats: When the argument IS one structure (a pipeline, a system), name it once in meta.maps and build it with LivingMap …
- Very specific: line 221
Reach: After the forms and ideals, each beat's argument is read against the table of shapes the library has a BUILT tool for …
- Very specific: line 232
Only the film's own content goes on screen: Every word and every number comes from a prop, or is declared part of the form (INTRINSIC_TEXT, …
- Distinctive: line 290
MUST still-render each chosen shot at that aspect and fix or swap what does not reflow.
- Distinctive: line 292
BEFORE promising a vertical or square film.
- Very specific: line 302
Finish: Every render is dithered (a static ±2-level dither.
- Very specific: line 336
references/stage-runs.md: before declaring a run; the per-beat gates measure a run on the Film's own frames of it. - Very specific: line 348
ONLY gate that sees a cued animation cut mid-flight, so set the duration it reports.
- Very specific: line 427
Always sample late at a fixed fraction, because mid-clip grabs show animation in flight and produce confident wrong readings.
- Very specific: line 491
OPTIONS-FIRST (the interview's prime directive): EVERY ask is an AskUserQuestion menu by default — issue it as an actual AskUserQuestion …
- Distinctive: line 505
ONLY what is genuinely undetermined — ⑥ Grounding when a deck is the only material, ⑦ Brand when the topic triggers it — and is skipped …
- Very specific: line 514
No-deck (make-from-scratch) runs — capture the topic FIRST: if the user has a deck (pptx/pdf/images) SKIP this (the deck IS the topic).
- Very specific: line 551
Put "(Recommended)" on the tier it returns, and its why in that option's description.
- Very specific: line 564
A REAL PRODUCT → the product film: When the video is a launch / promo / pitch / overview OF a product the user can point at (a URL, an app, …
- Very specific: line 656
Never confirm the spend with a free-text "proceed?" prompt.
- Very specific: line 685
Provider: if the codex CLI is installed, generate via Codex's native image-gen (NO key — uses the user's Codex plan.
- Distinctive: line 767
Either way, stay faithful: every claim and number in the narration must trace to the material or a verified source — never invent results, …
- Very specific: line 971
Theme (HTML and programmatic tiers): run scripts/theme.py <out_dir> [--style <meta.visual_style>] AFTER the design plan and BEFORE …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Topic to Video
You turn a topic — or a slide deck — into a narrated short video. Source of truth is storyboard.json — you edit
text/timing; the scripts render the media.
Full effort, every time (binding)
The user, 2026-11-14: "我要你在skill中确定任何时候你都不要嫌麻烦,发挥你的最大潜力和创意,做了这么多优化,都展示出来呀".
- Never trade quality for less work. No shortcut because a step is long: re-cut a part, rebuild a shot, re-render.
- Use what the skill has built. Before building, list the capabilities this film can use and put each to work
where the content admits it:
- staging and composition variety;
- material and light (
LitStage, the craft kit'ssurface,runtime/material,slide.optic); - time grammar, camera, marked seams and the reach tools. An improvement nobody uses is not an improvement.
- Judge the film as a sequence. Tile every beat's settled frame on one sheet before handing it over. One layout repeated, one ground everywhere, a flat fill where a material belongs: any of these is a redesign, not a delivery.
- Skip a capability only for a stated reason.
python3 scripts/capability_reach.py <dir>lists what the film uses and names each unused family that has no reason. Record a reason inmeta.capability_waivers({family: why};waiversin a promo table). promo_film's check and the remotion tier's delivery steps run it.
Tools (all free; verify with scripts/_common.have_tool)
soffice (pptx→pdf), PyMuPDF fitz, python-pptx, edge-tts (preferred neural voice, free, cross-platform — needs network), macOS say (offline fallback), ffmpeg, PIL.
Captions burn via PIL + a bundled font (no libass needed). Optional: OpenAI/ElevenLabs
TTS if the user gives an API key.
Pipeline scripts
This is an index. Each line gives what a script is for, when to run it, and the rules that apply at the moment
you run it. The full entry for each script is in references/pipeline-scripts.md: every flag, what each
meta.*/slide.* field means in detail, the measured incident behind each rule, and the library-maintenance
tooling. Open a script's entry there before you set a field this index does not explain, pass a flag not
shown here, act on a gate finding you do not understand, or edit the library (a register, runtime/, a gate).
Ingest, voice, palette
scripts/doctor.py [--json]: environment preflight, run once at the START (step 1). It exits non-zero only when a REQUIRED dependency (ffmpeg/ffprobe/PIL) is missing, and prints the stage each missing optional tool gates.scripts/ingest.py <input> <out_dir>: pptx/pdf/image folder →frames/+ skeletonstoryboard.json(pulls pptx speaker notes).scripts/tts.py <out_dir> [--only N]: narration →audio/+ measured durations. edge-tts writes.mp3+audio/NN.words.json(per-word times, which karaoke, cues and the sync gate need); macOSsaywrites.wavand no word times.tts.pyREWRITESstoryboard.json, so run it (and any duration-editing pass of your own, e.g. tail-padding) BEFORE you hand-set per-scene fields liketransition, or a later re-synth silently clobbers them. Order: finalize audio & durations → THEN set transitions/motion → validate → render (render only READS the board). A scored remotion film's clips also get their tails snapped to the beat grid (see Sound; words.json untouched). Every clip is mastered in place (EBU R128 I=-14, trailing dead air trimmed, word times stay valid;meta.audio_master: falseopts out).meta.scene_pause(default 0.55 s) is the pause the viewer HEARS between scenes, not the pad.tts.pyconverts it per tier (remotion adds the 0.40 s cross-dissolve overlap, so both tiers sound the same) and targets the film's own 75th-percentile sentence pause PLUS a 0.45 s breath, floored atscene_pauseand capped at 1.5 s; it prints the number.meta.audio_breathsets a RAW pad, only for a board that deliberately wants one. Keepscene_pause≤ ~0.9 s: it is a pause, not a reading buffer (a long tail reads as the video hanging); reading time goes into a slowermeta.tts_speed.scripts/theme.py <out_dir> [--mode light|dark] [--accent #hex] [--accent2 #hex] [--bg #hex] [--style <key>] [--brand-logo <png>]: topic palette →<out_dir>/theme.css, which HTML pages link and the programmatic renderers parse (one colour world). Run it before authoring pages OR programmatic scenes. Contrast is gamma-correct WCAG: fg/bg ≥7:1, a SAMPLED accent nudged toward ≥3:1, an explicit--accentnever touched.--brand-logo, ormeta.brand.logowhen no accent flag is passed, makes the logo's hue the accent. Re-run it on an out_dir themed before the contrast fix. Printed/filmic styles get fixed-seed grain; a data-heavy page opts out with<body class="no-grain">.- What the voice names is shown as itself. A list the narration names (three or more objects: "a report, a spreadsheet, a deck") is declared per beat in
shot_fit.shows{item: [words the frame carries] | {"by": "picture"|"voice", …}};scripts/named_objects_qa.py(fast delivery tier) reads each off the rendered frame above the caption, and validate warns of an undeclared list and of a list told twice that does not agree. A blank stand-in is never a named object. A device shown in two plates is drawn by ONE model (validate errors otherwise; the kit's when there is one). scripts/brand_mark.py <out_dir>: reads every brand mark the film uses (OCR, light and dark ground) and records whose name it spells in its sidecar; validate refuses one never read, changed since, naming another product, or a symbol nobody confirmed. Name the product inmeta.product(ormeta.brand.name); a third-party mark names its owner in its sidecar's"brand". Run it before deriving anything (a palette first) from a fetched mark: a docs site can serve a sibling product's logo.scripts/dna_from_deck.py <out_dir> [--pptx deck.pptx] [--mode light|dark] [--dry-run] [--force]: remotion tier. Writesmeta.design_dna(with aprovenanceblock) from the deck's OWN pptx theme (scripts/pptx_theme.py) and frames. Run it after ingest and BEFORE the shot-director. It never overwrites an authored DNA without--forceand fails loudly when there is nothing to derive from. The html tier'stheme.pyis untouched.scripts/taste_ledger.py add|list|retire|brief|check: what the user taught about taste, in their words, kept OUTSIDE this public repo (~/.topic-to-video/taste-ledger.json). Directors readbrief --stage S; when the user corrects a design,addit (their words verbatim) before fixing the film;retireit once a gate enforces it.critic_ledger --finalrefuses a film while an active rule has nometa.taste_reviewanswer pinned to a file of the film (a user waiver by name,meta.delivery_waivers.taste_ledger, passes it).scripts/sketch_sheet.py <out_dir>: the remotion tier's picture BEFORE building — each beat'sslide.sketch(metaphor, one hero, 2-6 rects in frame fractions, camera, environment) as greyboxes in_sketch_review.pngon the Desktop, with findings (no sketch, small hero, sparse, repeated layout, caption band). The user approves it at 3.6.
Imagery
scripts/imagegen.py <out_dir> [--key KEY]: OPTIONAL paid step. Generates AI atmosphere art for scenes carrying animage_prompt, cached under.assets/. It acts only whenmeta.image_source == "openai"(meta.image_providerauto/codex/openai; the Codex CLI path needs no key). The images are backplanes BEHIND HTML pages: never a slideshow of generated stills, never text or data, never a stand-in for a real named subject (that isdocumentary).validate.pyenforces all three.scripts/imagefetch.py <query> <out_path> [--prefer W] [--min-width PX] [--require TERM...] [--duotone SHADOW HIGHLIGHT]: the FREEdocumentarytier. Fetches a license-clean Wikimedia Commons image of the ACTUAL named subject and writes a<out_path>.jsonsidecar with licence + attribution + which field of the file's record named each query term. A candidate is taken only when its title, object name or categories attest EVERY key term of the query (or its description holds the whole phrase); otherwise it is refused, and when all are refused the reasons and a hint print to stderr — rephrase, or pass--requirewith the terms that are the subject when the rest only qualify it. Helpers:fetch()returns None when nothing relevant and license-clean exists,attribution_line()gives the on-screen.credit,duotone()tones the image into the palette. Reach for it on CONCRETE topics; the design-director picksmedia.treatment: none|atmosphere|documentaryper beat. Take the credit FROM the sidecar, never from memory:validate.pyERRORS when a beat shows amedia/*file without crediting its sidecar's author.
Render: html / image tier (scripts/render.py)
scripts/render.py <out_dir> [--sample N] [--only N] [--vertical] [--reduced-motion] [--preview]: storyboard →out.mp4out.srt.--previewis the cheap iteration render (12 fps, its own cache, writespreview.mp4, never touchesout.mp4). Use it while experimenting, and DELIVER the full render. The fields it reads:
- Transitions are SEMANTIC.
meta.transition(dip|none) +meta.transition_seconds; per sceneslide.transition(dip|in|out|none) +slide.transition_seconds. Map the beat'srelation: continuation → hard cut; new-topic/payoff/close → an in-edge on the opener PLUS an out-edge on the predecessor (a dip needs both sides; validate lints an unpaired edge).meta.transition_style(dip|fadethrough|drift|push|lift|wipe|blur) is chosen ONCE per deck from the register. A transition is a claim about how two beats relate, never decoration: budget ~2-3 marked seams per video, never random, no spins,bluronce per film at most. Both tiers share one seam vocabulary, andvalidate.pyERRORS on a seam word the renderer cannot resolve (references/motion-grammar.md"Transition rhythm" / "Transition STYLE"). - Captions.
meta.caption_modedefaults tooverlay: the subtitle sits directly on the frame's own ground, with no strip and no white/black halo. Its ink is the deck's own content colour for that ground, and its outline is the sampled ground. Authors MUST keep content out of the bottom caption band (caption_band_px: 200 px ≈ 18.5% at 16:9, 257 px on 9:16/1:1/4:5 — keyframe_qa's finding prints the exact edge); keyframe_qa gates it.bandis the opt-in footer strip (canvas grows;meta.caption_bandflush|contrast).meta.caption_scaledefaults to 1.0. Karaokemeta.captions_karaoke(auto|off) needs edge word times (CJK matched by char-span) and falls back to line chunks without them. The remotion tier follows the same rule with no scrim (references/captions.md). A 9:16 film uses the platform-safe profile on this tier too (meta.safe_zone, default"social";"none"opts out;bandmode is left as it was): each page is drawn in the scaled frame ofruntime/safeZone.ts, its edges dissolving into a margin of its own ground (or, for a photo/gradient edge, its own edges extended and blurred), the caption is a size larger, ends short of the button column and sits above the platform's description, the brand bug sits below the tabs, and the full render writesout.cover.png. Pages are authored and gated exactly as before (keyframe_qa measures the page; its caption band lands under the caption). - Timed callouts. A callout with a
cueanchor phrase (orat0..1) appears as its region is spoken and holds to the clip end. Untimed callouts show for the whole slide. - Motion.
meta.intensity/slide.intensity(subtle|balanced|boldor a non-negative multiplier) scale the Ken Burns move, clamped under the zoom/pan caps.shotis authoring shorthand: translate it intomotion.from/to/zoom, because render readsmotion, notshot. meta.audacity(conservative|balanced|bold|experimental) is the register's RISK BUDGET and the register-contest width (skip / 3 / 5 / 7 candidates). It NEVER relaxes the floor: clarity, faithfulness, WCAG and every gate are the same at every level. A register move that breaks one is redone in-bounds.--reduced-motion/meta.reduced_motion: the accessibility variant (static frames, opacity-only reveals). It busts the clip cache.
scripts/scenes.py: animated programmatic scenes (typetitle/keypoints/chart/timeline/compare/html+ a typedprops;typedefaults toslide). They render ONLY theirprops, so they are faithful by construction, and they readtheme.css.props.climax:truelands a counter at ~68% and holds it.props.cue(one anchor phrase per element, in spoken order) lands each bar/node/row as it is spoken. Cues change only WHEN an element appears, never the final frame.- HTML pages tier:
scenes.py:render_htmlcaptures pages authored onassets/html/base.css(references/html-pages.md) in headless Chrome. For audio-synced reveals, tag each pointdata-cue-index="N"(spoken order) +data-cue="<spoken anchor>".scripts/cues.pyresolves the anchors from edge word times, or estimates them from text position when there are none. Capture runs over CDP (scripts/_cdp.py) and falls back to per-frame screenshots on its own; tune it withmeta.capture(cdp|screenshot),meta.chrome_workers,meta.jpeg_quality.
Render: product promo / real-product beats (references/promo-film.md)
scripts/promo_capture.py <dir> <url> --name=ncaptures a product or page at 2x with every element's box and its own title and description;--evalreaches a state first (and__ttv.fillwrites the film's demo content into it);--parts="name=css:..|text:.."captures single COMPONENTS at 4x, whichobject/wallshots stage as objects in the film's own world (references/promo-film.md § Staging — the default way to film a product).--boxes=<png>finds the boxes in a screenshot with no DOM, and--mark=cuts the logo.scripts/promo_record.py <dir> <url> --name=n --seconds=6 --script=steps.jsonrecords the product IN MOTION (clicks, drags, scrolls, typing, its own animations) frame-exact on its own frame clock; a page shot plays it withrecording:. Async work (loading, workers) goes in--setup, which runs and is awaited first.scripts/promo_film.py <dir>renders a launch/promo film with no narration, written as a shot table (promo.json): the product AS ITSELF under a 2.5D page camera, chapter cards, carried cuts, a recall outro, and SFX pinned to the table.--checkrefuses what would render wrong (zoom past the capture's density, a box off its capture, low-contrast accent ink);--stills=comes before the full render.- In a narrated film the same craft is two registers:
ProductPage(a capture acting, cued to the voice) andChapterCard(a chapter's statement, numbered). scripts/picture_glide_qa.py <dir>checks whether a picture under a moving camera glides or steps (抖动), read from the pixels. promo_film runs it on every render; run it on a narrated film that has ProductPage beats.
Render: remotion cinematic tier (meta.renderer:"remotion")
scripts/tier_advice.py: decides from purpose + topic whether a film warrants this tier (interview ③). Remotion is for launch / promo / story films, NOT every video.scripts/render_remotion.py <out_dir>: renders the bespoke-shot library (remotion/LIBRARY.md) one beat at a time and keeps unchanged beats in.remotion_segments/.python3 scripts/remotion_segments.py <out_dir>lists which beats the next render would redo. A visual edit re-renders that beat and the next; a narration edit re-renders every later beat; a LIBRARY edit re-renders only the beats whose registers reach the edited file (Film and the runtime it imports still reach every beat). A render that dies resumes;--whole,meta.segment_cache: falseorREMOTION_SEGMENTS=0render in one pass."remotion-legacy"errors (that tier was removed). Runcd remotion && npm installonce. Rules on this tier:- The cut has to be authored. No seam reaches a film unless something writes
transition_in, so runpython3 scripts/seam_plan.py <out_dir>. From each beat'srelationit derives ~2-3 MARKED seams (≥5 beats apart, luminance-safe) and ~2-4 motivatedslide.cameramoves, and cuts the UNMARKED seams by the film's tempo: a launch or promo (meta.purpose) cuts every one hard (cut), a scored film half, a calm explainer keeps the dissolve (meta.cutsnames it). An authoredtransition_inalways wins. validate WARNS on a ≥12-beat film with no mark, or more than ~1-in-8 marked. Onlycarry,focus,through-dark,drift,blur,containerandcutmay sit on a dark↔light seam; any other mark there (portalincluded) is silently forced to a fade. The ANCHORED seams —container(an element carried across the cut),grow,through-window,punch(once, the payoff) — and the camera hand-off (camera.handoff) are inreferences/motion-grammar.md; an anchor istransition_in.carry, andpython3 scripts/carry_anchors.pylists what each register draws. A bespoke direction must declaremeta.design_dna.seam(e.g.{type:'wipe',direction:'from-bottom'}or{type:'fade'}), or its unmarked seams fall through to an anonymous cross-fade. - Camera is per beat and motivated:
slide.camera:{move:'push'|'pull'|'hold'}(payoff → push, close/opener → pull, else hold;handoff: truecarries a push across a continuation cut). A subject with a geography — scales, distances, layers — is aWorldStagerun instead (Continuous stage, below).meta.camera_driftstays off. The camera bed is OFF by default (meta.camera_bed: trueopts in) and never coexists withcamera_drift. On a beat of 10 s or more an authored push/pull arrives in steps on the voice's clauses instead of an invisible creep, and on a beat that shows a LIST the item the voice names leads while its peers recede (render_remotion.attach_phrases;meta.phrase_camera: falseor a beat's"phrase_camera": falseturns both off). Neither adds a camera to a beat nobody gave one: that was measured to make type tremble (pipeline-scripts.md,phrase_steps.py). - The cut carries. On a film that cuts hard by tempo (kinetic or scored;
meta.cut_carrysays so outright) every hard cut carries one move through the cut frame (runtime/cutCarry): the leaving beat drifts and leans in, the arriving one comes out of the same drift already mid-entrance.scripts/seam_ledger.py <out_dir>measures each cut on out.mp4 and fails a kinetic film whose cuts join still frames. - Footage is shown as itself.
FilmScreenplays a delivered film or a recording at its own pixels (a close-up region — whichfocusTrack: [{t, x, y}]moves along the action, smoothed, at its own pixels — the film's beats running beneath, a counted reel); a film's own pictures go in withworkshop.py <out_dir> media add <file> [--at s], andworkshop.py <out_dir> motion <Name>says whether a built shot keeps moving after its reveal. - The hidden cut.
transition_in: {type: "sweep"}(aliashidden-cut): a panel passes the lens and the beat changes behind it — two stops of one journey, "and on we go" (motion-grammar.md). - Time is grammar too, per beat and named by the words:
slide.time: {hits: [{cue}], hold: 2}freezes the drawing on an impact (hit-stop),freeze: {at: {cue}, hold: s}holds a moment for a look,sakuga: {until: {cue}, every: 2|3}moves on held drawings until the climax and on ones from it (runtime/timeGrammar; every pause is repaid within a few frames, so the beat stays on its voice; validate and Film refuse a hold past the bounds). Use it where the beat has an impact, a moment to look at, or a climax — not as texture on every beat. A hit lands on a word where something ARRIVES: on a still frame it shows nothing. - One structure, many beats. When the argument IS one structure (a pipeline, a system), name it once in
meta.mapsand build it withLivingMapbeats (shot_props: {map, add, focus}): laid out once, added to beat by beat, the camera moving through it, every map cut invisible (remotion/cards/LivingMap.md). - Bookends. A launch/promo film of 6+ beats may open COLD (
ColdOpen: 2-4 of its own later beats flash past, then the title) and any film that long may end on aCallback(its earlier beats gather as cards round the closing line);shot_director.pyproposes both by position,shot_props.beatsnames the beats (1-based). - Places (styled films,
style.surface.world: place): each beat may name theworldits subject is in —orbit,sky,field,room(remotion/src/runtime/places.json) — and is drawn inside it; a beat about an idea names none. Named per beat from the subject, never one place for the film. - Reach. After the forms and ideals, each beat's argument is read against the table of shapes the library has a
BUILT tool for (
references/remotion-shot-authoring.md§F): a derivation →EquationMorph, a curve →FunctionPlot, one shape becoming another →GrowingFigure, a conserved flow →FlowSankey, a ranking over time →RankRace, one moving figure →FlowCounter, where →GlobeFocus, a route →FlightArcs, words that ARE the picture →HeadlineReveal/WordRoll/CroppedType/TypeOnPath(held to reading time), the medium →LitMedium, light as content →slide.optic, a journey → aWorldStagerun.shot_director.pyrecords the matches inshot_fit.reachand prints the world runs, shared elements (container) and cut tempo the board implies. - Forms come from the subject, not the catalogue. The shot-director derives 6–10 forms BEFORE opening
LIBRARY.md(meta.form_vocabulary). Each beat names its form inshot_fit.form, andmeta.idiom_worlddeclares the provenance worlds the film may draw from. validate ERRORS on a missing or undeclared form or world. A derived form with no register gets BUILT (register_shot.py, the workshop), not approximated. - Only the film's own content goes on screen. Every word and every number comes from a prop, or is declared part of
the form (
INTRINSIC_TEXT,INTRINSIC_READOUT). Never invent a number: a measurement prop has NO default. A register that shows a NUMBER (ChartLive/BeforeAfterSlider/VelocitySnap) MUST get a SOURCED figure. validate ERRORS on a missing/unknownshot, and on a partly-filled beat that leaves a copy prop at its demo default (scripts/demo_copy_qa.py <out_dir>lists them). The evidence registers PhotoPlate/ScanReconstruct/RealVersus/MuseumLabel refuse to render without a real image. A label beside a point is clamped into its box withplaceLabel()(runtime/layout). - Every picture at its own resolution. A raster (screenshot, product UI, photo, frame sequence) is never drawn
larger than its own pixels, including at the peak of a camera push. Product UI is REBUILT natively in the
register (DOM/SVG, sharp at any size) or rendered from the product's own vector/code at 2-3x, not scaled up from
a README GIF; logos come from the source's largest PNG/SVG; frame sequences are PNG, never JPEG.
scripts/media_res_qa.py <out_dir>(a blocking delivery gate) measures every picture on every 3rd frame of the Film and ERRORS past 1.25x — a film shipped its hero UI at 2.9x with every type gate green. - Blender plates (
slide.blender,references/blender-plates.md— read it before routing a beat there): a 3D render under a workshop shot, ONLY where 3D physicality is the content (why: real-world, material, physics, optics, space, ordevice: the product's interface on a real MacBook,scene: "kit:laptop_screen"+screen{shot, props, px}), compared against a register's still first.scripts/blender_plate.py <out_dir>builds it LAYOUT FIRST: the ID pass alone, judged byscripts/plate_qa.py, and pictures only once the layout is clean (exit 4 = move the type or the object; nothing expensive was rendered). Look at ONE--still Fbefore the build; never rebuild a whole plate to check a layout or a look. Overmeta.blender_budget_minit exits 3: ask the user. - Authoring. Each scene gets
shot_fit{ideal, form, verdict: fit|adapt|build, why, ref?, shares?}— the ideal picture FIRST (no register named), then the route;shareson every as-is beat — plusshot(a register id or a workshop shot) +shot_props+shot_adaptation{changes: [{aspect: layout|encoding|structure, what, why}], kept, redesigned, topic_idea, theme_cues}. An ADAPTED beat'schangesmust also show in its props (a structure-affecting prop set away from the register's default); a re-worded register is as-is. Vary the FAMILY: no two adjacent beats should read as one look.python scripts/shot_director.py <out_dir>proposes registers as MATERIAL after the ideals are written — never the assignment. On a concrete topic,PhotoPlategives a real photograph the whole frame. Icons are the default on a labelled list (iconper entry; shot_proof WARNS when there are none). A shot is standalone-renderable withcd remotion && npx remotion still src/index.ts <Id> out.png --frame=N --gl=angle, and--propsmust be ASCII only. Authoring detail:references/remotion-shot-authoring.md. - Design DNA (
meta.design_dna) is the film's whole visual system. The shot-director expands it first, or a preset-mappedshot_templateauto-applies one. Only 2-3 ANCHOR beats show the style container, and every shot is ASSIMILATED into the DNA.design_dna.motifis the subject's material: keep it near 0.05.design_dna.finishis on by default for themed films;"none"turns it off. A DRAWING STYLE the user names (cartoon, 水墨, "like Kurzgesagt", a screenshot) is
meta.style. It is not a register and not a palette: it is values on fixed drawing axes (line, fill, shade, shadow, form, surface, type, motion), and one engine applies them to every beat and object. Readreferences/style-engine.mdand follow its procedure:- references saved in
style_refs/(the user's first); - the spec, validated by
scripts/style_spec.py; - the palette read from the references by
scripts/dna_from_refs.py, and registers cast for the film's ground (validate names a beat whose register keeps a ground of the other tone); scripts/style_sample.py <out_dir>: 2–3 beats beside the references plus a clip, delivered to the Desktop;- the user's yes, and only after it
style_sample.py <out_dir> --signoff. The full render refuses a styled film without a current sign-off; scripts/style_qa.pyat delivery: it fails a style that only recoloured, a beat left unstyled, or a medium that shifts the tone. Look at its sheet.
scripts/style_coverage.py <out_dir>names the beats a style cannot reach (photographs, canvases). A drawing property no axis has is a recorded shortfall, never a per-film workaround.- references saved in
- CJK. The renderer bundles Noto Sans SC / Noto Serif SC (a GB2312 subset). validate refuses a board holding a
character outside the subset, and warns when a CJK film's DNA lists system families only. The stack must NAME the Noto faces.
Two CJK DISPLAY voices sit beside them for
fontDisplayonly (subsets of OFL faces, renamed — assets/fonts/ TTV-SC-SUBSET-NOTE.txt):"TTV Display"(from 得意黑, geometric oblique: launches, products, tech) and"TTV Kai"(from 霞鹜文楷, warm and hand-set: people, history, learning). Choose withmeta.cjk_display(notokeeps the stack) by the film's voice, never by habit — validate asks for it on a CJK remotion film, and the renderer puts the voice after the DNA's Latin face and before Noto. Body and captions stay on Noto. Han/Latin and Han/digit gaps are set by the browser on every beat (text-autospace;meta.cjk_autospace: falseturns it off) — do not type them by hand. - Aspect. Set
meta.aspect(16:9|9:16|1:1|4:5|4:3) or pass--vertical. On a non-16:9 film the shot-director MUST still-render each chosen shot at that aspect and fix or swap what does not reflow. About one register in six is unsafe in portrait, so runpython3 scripts/text_safe_qa.py --library --aspect=9:16(or--all-aspects,--only=Id,Id) BEFORE promising a vertical or square film. - Platform-safe portrait. A 9:16 film keeps its caption, title and labels out of the platform's own UI
(bottom 19%, the right button column, the top tabs) by default —
meta.safe_zone: "none"opts out; registers are drawn in a scaled frame whose margin is the beat's own GROUND carried to the canvas edge — never a copy of its content (the register's root ground drawn again with everything on it hidden, over its measured ground token;meta.safe_echo: falsekeeps the token alone and saves that second rendering;frame_safe_qaWARNs on a margin with object-scale structure or a step at the frame's edge), stages lay out in the safe area, andtext_safe_qa --glideERRORS on type in those zones. The render also writes a 3:4 feed cover,out.cover.png(scripts/cover.py;meta.cover: {"beat": N}). A 4:5 or 3:4 film is a feed post, not a full-screen one, and keeps its own layout. - Finish. Every render is dithered (a static ±2-level dither;
meta.dither: falseturns it off) from JPEG-95 frames: dark gradients measured CAMBI 12-22 — visible rings — without, 0.0 with.scripts/banding_qa.py <out_dir>measures banding on the delivered file (an advisory delivery gate on both tiers). Stage surfaces take a layered key-light shadow, a sheen as they turn and motion blur when they move fast; push / slide / lift / return seams ease in and out with shutter blur. - Music follows the purpose (
tier_advice.PURPOSE_MUSIC): teach / how-to / research films are NOT scored by default (the voice is the content), launch / promo are, pitch / overview follow the material.tier_advice.pyreturnsmusic, and validate notes a board whosemeta.bgmfights its purpose (advice, never a block). - Sound.
meta.sound_design:trueis an opt-in SFX bed.meta.bgm(a path or"auto") scores the film, and a scored film also shipsout.nobgm.mp4; the music ducks under the voice (sidechain, ≥10 LU under speech)."auto"is a generated score on the film's BEAT GRID (scripts/score.py):tts.pypicks the grid and stretches each scene's tail pad (≤0.3 s, never under the pause floor) so its cut lands on a beat, writingbeats.json(python3 scripts/beatgrid.py <out_dir>prints every cut before/after). An author track is beat-detected and shifted, never stretched.meta.music: {bpm?, snap?: "beat"|"off", key?, seed?}. The mix is two-pass loudness-normalised to -14 LUFS / -2 dBTP at 48 kHz, every cue aligned by its PEAK (≤1 frame early), andcheck_avrefuses a delivery over 48 kHz. The pipeline cannot hear, so audition it before delivery.python3 scripts/sfx.py --calibratemeasures the cue offset through the real filtergraph and exits non-zero past half a frame. A register can own its sounds (export const SOUNDS, runtime/sound.ts; a board'sslide.soundsor"none"; a stage step'ssound), andmeta.close_sound: full | soft | nonesets how the film ends — a calm film settles (soft) by default (references/building-blocks.mdsound). - Light in a volume. An aurora, a sunbeam, a nebula, fire:
runtime/volumedraws it as a line-of-sight integral (WebGL, one pinned backend, bit-identical by determinism_qa) —AuroraCurtain,LightShafts,NebulaField, or a WorldStagevolumeobject (references/building-blocks.mdvolume). - Devices.
DeviceDemo/DeviceHeroshow the product's own screens. The step script goes inshot_props.stepsand is checked byscripts/device_script.py(format:remotion/cards/DeviceDemo.md"Step script"). A phone, watch, tablet or laptop capture is drawn on the real model it came from (read off its pixel size;scripts/device_models.py) — never hand-draw a device in a workshop shot: validate warns, andscripts/device_fidelity_qa.pysays why. - Sync.
render_remotionwarps each beat so register entrances land on their words (sync_warp.json). A board or slide can set"sync": "off"or{"anchors": [[voice_s, register_s], …]}. - Continuous stage. Consecutive beats with the same
stage.runand a stage shot (CardStage,WorldStage) are ONE scene with no cut: one card acted on across them (turned, lifted apart, clicked with a sound, marked, zoomed into, counted beside), or —WorldStage— one WORLD a camera travels through (dolly, crane, tilt, orbit, and the powers-of-tenscale-zoomthrough nested scales), the film's photographs, shapes and words standing in it. Each beat and each of itssteps(timed byat: a cue phrase or 0..1) says what changes. Readreferences/stage-runs.mdbefore declaring a run; the per-beat gates measure a run on the Film's own frames of it.
- The cut has to be authored. No seam reaches a film unless something writes
- Before authoring or critiquing a remotion beat — and ALWAYS when a film measures as inert, when a gate blocks a
full-bleed / cropped-type frame, or when you are about to argue about what "cinematic" means — read
references/launch-film-study.md. - Editing the library itself (a register,
runtime/, or a gate): walkreferences/engineering-case-law.mdbefore committing, reported asEn ✓/En ✗ (where). Runtime helpers a register author reaches for (glide(),springAt,radians()/life(),<Plane>,focusAt,<Voice>) are described in the reference andreferences/remotion-shot-authoring.md.
Pre-render gates and helpers
scripts/validate.py <out_dir> [--pre-tts] [--vertical] [--json]: the ~1 s storyboard gate (contract, assets, caption craft, motion sanity, reveal↔voice alignment, figure traceability, CJK/cue/pacing/anti-slop). Run it BEFORE every render, and with--pre-ttsright after authoring. Errors block; warnings don't. Its animation-TRUNCATION check is the ONLY gate that sees a cued animation cut mid-flight, so set the duration it reports. Keep each element to onestyle=(a second is silently discarded), and use semantic vars, not raw#hex. UI chrome text opts out of figure traceability viadata-ui; never mutate chrome text to dodge the lint. Before you dispatch an agent to re-pick registers, runvalidate.pyand read it: it names the beats cast on resemblance rather than meaning.scripts/pace.py <out_dir>|--budget <seconds> --lang <code>: the ONE spoken-length model (fitted on measured beats; counts the ~1.2 s pause after every beat). It predicts the film's length againstmeta.target_secondsbefore any voice is made, and says how much narration a beat holds; validate warns past ±15%. The planner, scriptwriter and critics use it — a bare chars-per-second rate undercounts every beat.scripts/split_beats.py <out_dir> [--beat N]: a remotion beat over 8 s on one shot holds still (51-100% of 311 measured beats past 3 s). validate names each with where it splits; this lists them, and--beat Nsplits one at sentence ends BEFORE tts. The new beats get NO shot (validate refuses that) — design each, then run tts.scripts/surface_qa.py <out_dir> [--json]: remotion, after the render — the share of frames whose subject is a LIT SURFACE (a modelled luminance ramp) rather than a flat fill, beside the published product-film band (advisory; applies to a physical subject — references/craft-study.md P0).scripts/cut_rhythm_qa.py <out_dir> [--json]: remotion, after the render — the delivered film's cut rhythm (shot-length p90/p10, share under 1.5 s) and scale range beside the band 26 published films sit in (references/craft-study.md); coverage cuts (scripts/coverage_plan.py) are counted only when the pixels confirm them. Advisory.scripts/rhythm_qa.py <out_dir> [--json]: pacing gate. Run after tts, before the full render. It is advisory except for a MEASURED static frame held past ~16 s. It names a remotion beat over 8 s on one shot: measured on 311 beats, those held a frame still past 3 s in 51-100% of cases. Split it, have the voice walk a list it shows, or author a push/pull (stepped from 10 s).scripts/pedagogy_qa.py <out_dir> [--json]: teaching-order gate overcontent_plan.json. It ERRORs on a concept used before it is introduced. Run at step 9 alongside validate and rhythm_qa.scripts/voice_qa.py <out_dir> [--json]: narration voice signals (AI-slop vocabulary + rhythm). It is advisory and always exits 0. Run it after the script step and after any rewrite, in every language, and readreferences/anti-ai-voice.mdbefore writing narration. The last pass is always a human read-aloud.scripts/audio_demo.py cancel <out.wav>: a sound the viewer HEARS (a synthesized A/B, marked so) for a beat whose point is a sound;slide.audio_demo: {clip}andtts.pyappends it after the beat's voice at its own level.scripts/progress.py <out_dir>: where a long step is — plates, render and gates write_progress.jsonand a self-reloading_progress.html(open it once and watch).scripts/sources.py add|list|verify <out_dir>: captures the source text behind each claim intosources/, so asource_ref(<sid>#<literal quote>) resolves.--tier primary|secondary|community|self(defaultsecondary) records where the support comes from;--as-ofdates a time-sensitive fact.scripts/brief_qa.py <out_dir> [--json]: structural gate onbrief.json. It ERRORs on a missing required key, asource_refthat does not resolve, or a non-singularthe_one_thing, and WARNs on evidence hardness. Run it at step 3.5, BEFORE dispatchingcontent-planner.scripts/keyframe_qa.py <out_dir> [--p N] [--json]: HTML-tier visual QA over each page's real cue timeline (filmstrip sheets,_keyframes/all.png). It blocks a blank opening, a blank page, canvas overflow, in-box clipping, caption-zone occlusion and text RENDERED under the remotion tier's type floor (2.2% of the short side, ~24 px at 1080; under 2.75%, ~30 px, warns) — measured from the computed size × transforms, so an invalidfont:shorthand that fell back to 16 px is caught;data-small="why"and the.creditline are exempt. Its layout notes are advisory. A scene it could not probe is UNVERIFIED, neverok. Run it after authoring the pages, BEFORE the full render.scripts/snapshot.py <page.html> <out.png> [--p 1.0] [--vertical] [--no-captions] [--motion clip.mp4]: renders one page and runs keyframe_qa's floor probe; this is the register-contest primitive. Exit 0 clean · 2 floor issues · 3 rendered but NOT probed (unusable as a contest verdict) · 1 could not render.scripts/contest_diversity.py <frameA.png> <frameB.png> …: flags two contest candidates that are "two skins of one idea" (exit 2). A flag means rediverge OR keep with a NAMED justification; it never auto-kills a topically right pair.scripts/register_ledger.py record <out_dir> | show: cross-deck register memory. The contest reads it; the delivery step records it.- Remotion pre-render, all run after the shot-director and before the render:
scripts/shot_proof.py <out_dir> [--no-stills]is the proof sheet (demo defaults, duplicate pictures, overflow, caption-band ink, off-palette colour, dead frames, unreadable captions). Fix everything it reports; passing is a FLOOR, not a verdict.scripts/energy_skeleton.py <out_dir>checks declared energy against measured register motion.scripts/cjk_type_qa.py <out_dir>is required on a CJK film; run it serially, because parallel shards report false failures.scripts/caption_breaks_qa.py <out_dir>checks a CJK film's burned caption lines as Film.tsx breaks them (ERROR on a break inside a word or a number, a line opening with closing punctuation or a one-glyph last line;references/captions.md; on an HTML film it reads render.py's own lines, and validate.py runs that check too).scripts/density_advice.py <out_dir>names starved beats and denser same-family registers; these are candidates, never instructions.scripts/text_safe_qa.py <out_dir>is the TEXT-SAFE gate (type cut by the canvas; full-bleed graphics and container-cropped type are legal; an intentional bleed layer carriesdata-bleedwith a written reason). It also runs as--glide(type crawling in whole-pixel jumps; fix throughglide(); type on a 3D or composited layer is handed toscripts/jitter_qa.py, which judges every line from the delivered pixels — a camera over a panel is a<SurfaceView>) and--sync(text readable late vs. its spoken word; ERROR past 1.5 s). On a film it also measures TYPE SIZE as rendered (font-size × every transform): under ~24 px at 1080 (2.2% of the short side) is an ERROR on the film's own shots and a warning on a library register (the library's debt,remotion/type_debt.json, regenerated by--library --type-size --write-debt); under ~30 px warns; texture that is not copy opts out withdata-small="why". And it warns when most beats put their TITLE (their largest type) in the same ninth of the frame. scripts/critic_brief.py <out_dir>: assembles_critic_brief.md+_contact_sheet.pngfor the rendered review — shot-critic on remotion, design-critic's delivery section on HTML (which also gets_frames/, one delivered frame per beat). Run it before dispatching the critic.scripts/contact_sheet.pybuilds the sheet alone.--gatesruns only the tier's delivery gates, records their exit codes for this render and exits 1 on a failure — the check before the review-depth question, and the record anoneanswer is delivered on. A later brief of the same render reuses those results while nothing they read has changed (_gate_runs.json), instead of re-running them.scripts/object_closeups.py <out_dir>:_object_closeups.png— EVERY object in the film (each device the kit draws, each screen on one, each element a shot marksdata-object="<name>") at the frame where it is largest, cropped at 100% from out.mp4 and labelled with its beat and timecode. Mark every real or built thing a shot draws withdata-object. The maker looks at it before delivery, the critic gives every object on it a verdict (S16), and device_fidelity_qa reads its screen boxes for the DEAD-SCREEN warning (a device showing nothing).scripts/settled_frame.py <clip.mp4|out_dir> <out.png|dir/> [--at 0.90] [--beat N]: the frame to JUDGE a design on. Always sample late at a fixed fraction, because mid-clip grabs show animation in flight and produce confident wrong readings. Use--beat N, since the board's running duration is not the film's clock.
Post-render gates and delivery
scripts/check_av.py <out_dir>: A/V gate (duration drift > 0.3 s, non-uniform clip rates). Run AFTER the full render, before delivery.scripts/flash_qa.py <out_dir>: FLASH gate, both tiers — a run of 1-2 frames unlike both of its agreeing neighbours (a layer that drops out or re-sorts for one frame). Every other gate reads a frame, a beat or a line of type; a film shipped three such flashes (near-coplanar translateZ layers re-sorting) with all of them green. Cuts and fades never trip it.scripts/film_energy_qa.py <out_dir>: remotion FILM-ENERGY gate (motion p75, ink, luminance span against floors derived from four launch films). A deliberately quiet film declaresmeta.energy_waiverwith a REASON. The waiver is PER-AXIS: an object waives only the axis it names; a plain string waives all four and says so. Waive the axis you actually reasoned about. ACOVERAGEerror (the file was decoded short) is never waivable: re-render or repair the file. A MOTION finding names the beats holding the film under the floor — seconds under it and, of those, FROZEN (no pixel changed); a small thing moving is under the floor but never frozen. Fix those beats before waiving.scripts/craft_qa.py <out_dir>: remotion CRAFT read (advisory), by beat: the longest still hold, the motion peak and whether one element leads the frame, against numbers measured on 28 published launch films (references/craft_reference.json, numbers only). Our films held still 5.0 s against 2.5 s and let 3 elements share the frame against 2. A hold it names is either a decision (a closing lockup) or a missing reveal or camera move.--typeadds one census of the film and names SMALL CROWDED TYPE: the largest line under 6% of the short side among 5+ lines with nothing else leading (launch films lead with ~7% type over ~3 lines). A beat led by its drawing keeps its small labels — the rule does not touch it. Measured on 6 films: it named 8 terminal beats of one (4.2-4.9% type, 6-18 lines) and nothing in the other five.scripts/shake_qa.py <out_dir>: remotion SHAKE gate (travelling vs vibrating camera). It is paired with film_energy_qa, because jitter is the cheapest way to clear the motion floor. A frame it cannot lock onto is UNJUDGED.scripts/critic_ledger.py <out_dir> --final: the independent-review gate on both tiers (workflow step 9);--render-idprints the id every review pin uses.scripts/deliver.py <out_dir> [--what sample|preview]is the hand-off, for EVERY render the user is asked to watch (sample, preview, final cut). It copiesout.mp4+out.srt(orsample.mp4/preview.mp4with--what) to~/Desktop(else~/Downloads) and prints the path. Give the user THAT path, never one inside this skill,~/.claude, or a temp folder. The film is checked first (scripts/deliver_check.py, its FAST tier, ~30 s, reused while the film is unchanged): a failing gate refuses the hand-off; waive one by name with a reason (meta.delivery_waivers) or pass--anyway(delivered as "(unchecked)"). Rundeliver_check.py <out_dir> --fullonce for the cut that ships (+ media_res, text_safe, jitter: ~10 min).
Library maintenance (not part of a film run; full entries in the reference)
scripts/register_shot.py <Id> <Family> --use-when "…"scaffolds a new register at every sync point (--checkverifies one). A new register carries an ARGUMENT SHAPE with the topic arriving through props.scripts/onscreen_text_qa.pyreports hardcoded text, unfed numbers, dead props and literal-duplicated defaults. It always exits 0, and tests hold the counts at zero.scripts/stale_measurements.py: run it after ANY edit underremotion/src(a register OR a runtime file it imports), BEFORE committing. No renders, ~7 s. It names every register whose measured rows (energy, prop reach, ground reach, ground luma) no longer describe its source and prints the re-measure command for each manifest. One runtime edit staled five registers in all four manifests, and the suite only caught it after a push.scripts/measure_ground_luma.py --checkis the GROUND-TOKEN gate (~15 min, 160 renders). Run it after changing any register's ground. Also run--luma --checkforSHOT_LUMA, which must be MEASURED, never guessed.gen_dna_ground.pyis RETIRED and exits 2.scripts/dna_audit.py [--depth|--type] [--check]reports DNA reach.scripts/dna_smoke.py: run it after any bulk shot change.scripts/font_gate.pyproves declared faces load.scripts/clock_qa.pylists stalled cyclic drivers; these are candidates, and a fix is kept only if a render shows it.scripts/null_dna_pixel_gate.py: run--saveBEFORE your change and--checkafter.scripts/determinism_qa.py <Id> | --film <out_dir>asks whether a frame is the same however and whenever it is rendered (advisory for a new register that keeps any state;references/pipeline-scripts.md).scripts/type_specimens.py,scripts/dna_migrate.py/dna_migrate_bg.py/dna_migrate_type.pyare codemods and specimens.
Workflow (follow in order)
Preflight + Interview. First run
python scripts/doctor.pyonce: it reports any missing tool/library and the stage it gates. A REQUIRED dep missing (ffmpeg/ffprobe/PIL) → stop and have the user install it; optional gaps (edge-tts/soffice/Chrome/…) just narrow the tiers available — fold them into the interview (e.g. no Chrome → the promoted HTML tier is unavailable and the deck falls back to the flat programmatic renderers, the no-Chrome safety net). Then run the interview — a small set of selectable questions that capture the user's whole intention up front. OPTIONS-FIRST (the interview's prime directive). EVERY ask is anAskUserQuestionmenu by default — issue it as an actualAskUserQuestiontool CALL, never as a question typed into your chat reply. A menu = 2–4 labeled options + the automatic "Other". The ONLY asks that may be a plain prompt are ones whose ANSWER is an irreducible free-text VALUE with no decision wrapped around it: the topic sentence, a file/dir PATH, an API key. Everything else — including do you have source material? and do you have brand assets? — is a DECISION, therefore a menu; the free-text VALUE it then needs (a path, a hex) is a follow-up you collect ONLY AFTER the option is picked. If you are about to type a?into your reply instead of callingAskUserQuestion, stop and convert it to a menu. Rendering rule for options:AskUserQuestionshows at most 4 selectable buttons per question (and up to 4 questions per call); when a menu is richer, spell out the FULL menu in the question text, make the most-common items the ≤4 buttons, and let the automatic "Other" free-text accept any listed item by name — a menu that is naturally ≤4 shows every item as a button. Ask a question at the moment the user can actually answer it. Screen A (①–④) is asked every run; screen B carries ONLY what is genuinely undetermined — ⑥ Grounding when a deck is the only material, ⑦ Brand when the topic triggers it — and is skipped when both are settled; ⑤ Voice is asked at the script audition, where the user HEARS the voice instead of choosing an engine in the abstract. Batches 2–3 still fire only when an answer triggers them. A common free/default run is ONE option screen, with zero mandatory free-text beyond the single topic line on a no-deck run (why:references/engineering-case-law.mdW1).Batch 1 — core intent + essentials. Screen A = ①–④, every run. Screen B = ⑥ Grounding (only when undetermined) + ⑦ Brand (only when triggered) — skip it when neither applies. ⑤ Voice is asked at the script audition (step 5). No-deck (make-from-scratch) runs — capture the topic FIRST: if the user has a deck (pptx/pdf/images) SKIP this (the deck IS the topic); with no input deck, before screen A ask ONE plain-text line for the topic sentence — a plain prompt ONLY because the topic is an irreducible free-text VALUE (like a path or a key), not a decision. Keep it to that one line: the goal/takeaway is captured by the ① Purpose menu (don't re-ask it as free-text here), and the sentence becomes the source the content-planner + design-director build the deck from. (If the conversation has ALREADY surfaced candidate topics/angles, offer THEM as an
AskUserQuestionmenu with "Other" for the user's own — only a contextless from-scratch run needs the bare plain line.)- ① Purpose (→
arc_kind+meta.purpose+ the planner's tone/audiencedirector_note) — what the video is for, and roughly who watches. Menu: Teach/explain (expository) · Pitch/persuade (narrative) · How-to/walkthrough (howto → expository) · Research briefing (reference → expository) · Overview/intro (→ expository) · Launch/announcement (→ narrative) · Promo/hype (→ narrative). Every Purpose maps to anarc_kind(narrative = builds to a payoff; expository = even-weight walkthrough) — never leave it undefined. (Other → another goal, or a specific audience/register note the planner should honour.) - ② Language (→
meta.language) — ALWAYS ask this explicitly; never silently default the language. The language the narration AND captions are written in (it drives the caption font + the default TTS voice). Menu: Match the slides (auto-detect the deck's language — the safe default) · English (en) · 中文 (zh) · plus any BCP-47 via Other (ja/ko/es/fr/de/… — or a cross-language voiceover where the narration language ≠ the slide language). Setmeta.languageto the resolved code (never leave it"auto"at render). On a no-deck run 'Match the slides' has nothing to detect — default the highlighted option to the topic sentence's own language instead. The narration voice engine is question ⑤, asked at the script audition below. ③ Tier (→
meta.renderer+meta.image_source, and whether pages are authored at all) — which renderer makes THIS video. It is recommended from the PURPOSE and the TOPIC, not offered as three looks — the tiers are three different trade-offs, every one of them measured:tier what it is best FOR what you give up 原样配音 / Voice my deck as-is — FREE a finished deck that just needs a voice; nothing redesigned no new design; points do not appear as they are spoken Designed HTML — FREE (+AI backdrops: PAID) explainers, how-tos, research briefings, data-heavy material: each point appears the moment it is said ( data-cueon the spoken word) and any table/chart/code/equation is laid out as the content needs; editing one beat re-renders one beat; needs only Chromeless cinematic motion Cinematic (Remotion) — FREE of money, NOT of machine launches, promos, story and brand: 227 hand-designed shot languages, cinematic seams, one design DNA points animate on the shot's own clock, not the voice (only the registers that import runtime/cuetime items to it); a visual edit re-renders that beat and the next (43 s on a 37-beat film, against 6:20 for the whole film) but a narration edit re-renders every later beat; the first render costs ~25% more than one pass (7:55 vs 6:20); needs Node + its own Chrome + real memory (the same film's one-pass render failed repeatedly at ~1 GB free — per beat, a failure keeps the finished beats)How to recommend (do this before showing the menu): ① is on the same screen, so infer the likely purpose from the user's request and material, then ask the rule rather than restating it:
python3 scripts/tier_advice.py --purpose <p> --lang <②> [--deck] [--data-dense yes|no] [--no-remotion] [--product]. Put "(Recommended)" on the tier it returns, and itswhyin that option's description. When the user's ① answer is a different purpose, re-run with it; if the tier they picked then fights the purpose, say thetradeONCE, in their words, and let them keep it — this is advice, never an override. Record the purpose asmeta.purpose(the ① key: teach/howto/research/overview/pitch/ launch/promo);validate.pyrepeats the trade-off once as atier:warning if the two disagree. Options, in this order (max four): 原样配音 (ONLY when the user supplied a deck —--keep-deck; the board keepstype:"slide"and step 4d is skipped entirely) · Designed HTML — FREE (image_source:none+renderer:local) · HTML + AI backdrops — PAID (image_source:openai+renderer:local; Batch 3 then confirms the spend + style) · Cinematic (Remotion) (renderer: remotion; the shot-director assigns each beat ashot+shot_props, reviewed by the shot-critic — show it ONLY whendoctor.pyreports the remotion tier installed). Make FREE-vs-PAID visible in every label and never enable the generator without the user picking the AI tier here. (Other → a brand/theme/CSS to match.) A REAL PRODUCT → the product film. When the video is a launch / promo / pitch / overview OF a product the user can point at (a URL, an app, its screenshots), runtier_advice.py --purpose <p> --product --lang <②>. It returnspromo; offer Product film (Recommended) first in place of the AI-backdrop option. Picked, the storyboard workflow below does NOT run: followreferences/promo-film.md"The loop" end to end (explore and capture → record the proof → the four → the arc →compose.py→promo.json→ check → stills → render → deliver). Narration is decided per film there (say/narrate), so do not ask the voice question; ② Language still sets the voice's language when the film speaks, and ④ Length sets the table'saspectand total length. These ride ALONGSIDE the tier — NOT menu items (don't cram them into the option prompt): • Image doctrine (paid tier): the generator only ever makes backgrounds/atmosphere behind HTML pages — never a bare slideshow of generated stills; DATA always stays in real HTML/charts (the "AI = background, code = data" split). • No Chrome? the HTML tiers are unavailable; the deck falls back automatically to the flat programmatic renderers (title/chart/timeline/compare/keypoints,scripts/scenes.py) — a no-Chrome SAFETY NET, NOT a promoted look, so never offer it as a menu option. • Real (documentary) images — FREE, no API: independently of the tier, for a CONCRETE topic (a city, place, real system/product/organism/event) the design-director may pull REAL license-clean photos/maps/diagrams from Wikimedia Commons (scripts/imagefetch.py) to DEMONSTRATE the subject directly (a real rail map, a real cityscape) — treated to match the deck. Decided PER-BEAT, not asked here; mention it when the topic is concrete (an abstract topic stays typographic/atmosphere). • Per-beat template FORMS (hero-stat, before/after, timeline rail, system map, metric wall, results table, figure focus, funnel, dashboard, case story, flywheel —references/html-templates.md) are chosen by the design-director per beat, NOT asked here. • Audacity (meta.audacityconservative/balanceddefault/bold/experimental) — the RISK BUDGET for the video's whole-video expressive register (how far look + MOTION + type push).balanced(solid base + one register that genuinely carries the video) is right for most runs; raise or lower it ONLY if the user asks for a bolder/more restrained feel — the floor (clarity/faithfulness/AV/gates) is identical at every level. Set it from a stated preference or leave the default; NOT a menu item here.- ④ Length (→
meta.target_secondsANDmeta.aspect— one decision) — the finished runtime, which also fixes orientation/platform. Menu: Vertical short ~30–45s (9:16 — Shorts/Reels/TikTok) · Quick explainer ~60–90s (16:9) · Standard ~2–3 min (16:9) · In-depth ~5 min+ (16:9) · Vertical long-form (9:16, longer) · Custom exact. Map the pick tometa.target_seconds(~40 / ~75 / ~150 / ~300; an explicit "4 minutes"→240 via Other) andmeta.aspect(9:16 for a vertical option, else 16:9). Captions are burned in by default (captions:true,caption_mode:"overlay"— the subtitle sits on the frame's own background, no strip, no white halo, content kept clear of the bottom caption band; see "Captions" under Pipeline scripts andreferences/captions.md"Placement"); (Other → captions OFF, per-word karaoke highlight,caption_mode:"band"for a separate footer strip, or a reduced-motion accessibility variant).meta.target_secondsis exactly the field the content-planner turns into beat count (beats ≈ target_seconds/4, with per-beatest_secondssummed to the target) and the design-director reads to scale hero/climax cadence — so it SUBSUMES the old per-slide pace ask (a per-slide ceiling, if ever wanted, is justtarget_seconds / beats). - ⑤ Voice engine (→
meta.voice; asked AT THE SCRIPT AUDITION, step 5, where its menu lives) — until thenmeta.voicestays"auto", which resolves to a language-matched edge-tts voice (free), so the audition has a voice to speak in; at the audition the user has just heard one and can say "keep it" or "try another". A cloud engine (MiniMax/OpenAI) picked there triggers Batch 2. - ⑥ Grounding material (→ how step 3 gets its facts; ASKED ONLY WHEN UNDETERMINED) — how to ground + fact-check the narration (slides/topic alone rarely say enough to narrate well — step 3 depends on this). Most runs already answer it: the user supplied source files/paths/a repo → use them, do not ask; ONLY a topic line, no deck → web research is the only way to narrate it well, so do not ask — SAY you will research it and that anything they send takes precedence; a deck and nothing else → ASK, because "the deck is enough" vs "research the rest" is a real choice. Menu: I'll share source material (a paper/PDF, a code repo, a report, notes) · Web-research it for me (no material — I confirm the facts/numbers/names from the latest sources, as of today, and fact-check the script) · Both (I have some — research the rest) · (deck runs only) The deck is enough (rare; say the script will be thinner). When the purpose is a how-to or a launch of a real product, ask for screenshots or a screen recording of the flow the film describes — the device registers draw the product's OWN screens and will not invent one. Other → describe what grounding exists. On "I'll share"/"Both", the ONLY surviving free-text is the file/repo PATH(s) — a one-line follow-up asked AFTER that option is picked (the path is an irreducible value, not a decision).
- ⑦ Brand assets (a MENU on screen B; asked ONLY when the topic is company/institution/
product-related or the user mentions a logo) — "有品牌资产吗?/ Any brand to match?" Menu: Yes —
logo + brand colour · Accent colour only (no logo) · No brand (default; never fabricate a
brandblock). Other → usage rules / light-dark variants. On "Yes"/"Accent", the ONLY surviving free-text follow-up is the logo file PATH(s) and/or the brand hex: copy the logo file(s) to<out_dir>/assets/brand/(so themeta.brandpaths stay out_dir-relative), record them asmeta.brand(block in Guardrails; doctrine split in the "Brand assets" section), and feed a stated brand colour totheme.py --accent(an explicit accent is never nudged) — with NO stated colour,theme.pyauto-samples the accent frommeta.brand.logo(see its--brand-logoentry), so just recording the block is enough. No assets ⇒ nobrandblock — never fabricate one.
Batch 2 — cloud-voice setup (ONLY if the voice picked at the audition ⑤ is MiniMax or OpenAI). First get the API key OUT OF BAND — have them
export MINIMAX_API_KEY=…/export OPENAI_API_KEY=…in their own shell (they can type! export …in this session) or put it in~/.minimax_key/~/.openai_key. Do NOT ask them to paste it into chat; if they paste it anyway, warn it lands in the transcript and tell them to rotate it afterward. Never write a key intostoryboard.json, a script, a log, or any committed file —tts.pyreads it from env / the key file only. Then, by provider:- MiniMax → ask gender as an
AskUserQuestionmenu (Female · Male · Either — it selects which samples to synthesize). Once the key is set, runpython scripts/voice_sample.py <out_dir> --gender <female|male>— it synthesizes a short sample per curated human-sounding candidate (natural/conversational, never theatrical) into<out_dir>/voice_samples/. The user LISTENS out-of-band, then PICKS via anAskUserQuestionmenu whose buttons are the candidate NAMES (≤4 as buttons, the full list in the question text, "Other" accepts any name); setmeta.voice = "minimax:<the pick>"(andmeta.voice_gender). Bareminimaxuses the catalog default for the gender. Do NOT show OpenAI voice names to a MiniMax user. - OpenAI → pick a preset voice directly (gender is implicit in the pick — don't ask it):
buttons Nova · Onyx · Shimmer · Alloy; Echo · Fable via Other → set
meta.voice = "openai:<name>".
Batch 3 — AI imagery (ONLY if Batch 1 ③ = "HTML + AI backdrops", i.e.
image_source:openai). The spend is confirmed by the Image cost menu itself — one of its options is "Use free HTML instead" (flip ③ back toimage_source:none, no spend), so PICKING a paid tier IS the go-ahead. Never confirm the spend with a free-text "proceed?" prompt. Ask (oneAskUserQuestioncall, two questions):- Visual style (→
meta.visual_style; sets the whole deck's aesthetic register — seereferences/visual-styles.md). First DERIVE the most suitable style for THIS topic (the selection contest: domain · data-dense vs narrative · audience · purpose, minus the guardrail vetoes), then offer the FULL menu in the question text — Swiss · Editorial · Bauhaus · Brutalism · Glassmorphism · Claymorphism · Manga · Risograph · Memphis · Noir · Cyberpunk · Vaporwave · Watercolor · Art-Deco · Cinematic · Blueprint · Terminal · Cartographic — with the ≤4 buttons = your recommended pick + the 3 next-best FOR THIS TOPIC (so the default is topic-derived, not a hardcoded "Editorial"). Other → a free-text brief ("custom") or any listed style by name. If the user picks a style that COLLIDES with a somber/sensitive topic, don't silently render it — surface the restrained alternative via a follow-up question. Persists asmeta.visual_styleand overrides the director's auto-pick. - Image cost + spend gate (
meta.image_quality) — the menu that CONFIRMS the spend. Options: Low ~$0.01/img · Medium ~$0.04 (default) · High ~$0.17 (worth it for a hero cover) · Use free HTML instead (declines the spend → setimage_source:none, drop Batch 3). Picking a paid tier is the go-ahead; there is no separate "proceed?" ask. Setmeta.image_sizeFROM the aspect — 9:16 →1024x1536, else1536x1024— so a vertical deck gets portrait imagery, not landscape. Imagery doctrine: generated imagery is generic b-roll — no logos, faces, named things, or in-image text; it NEVER carries a fact (real content stays text/charts). BUT generic ≠ topic-neutral: every cover/background MUST visually evoke the VIDEO'S OWN SUBJECT — a database- index talk gets abstract index/lookup imagery, a reef talk gets reef imagery, a slide-design deck gets blank panels/layout grids; a pretty-but-unrelated texture (random paper, generic gradient, stock desk) is a MISS. Derive the prompt's motif from the topic + comprehension brief. Visual style: the deck's chosenmeta.visual_style(references/visual-styles.md) is applied UNIFORMLY as an atmosphere treatment —imagegen._apply_styleprependsmeta.style_preambleto EVERY generated prompt (sandwiched subject → style → hard faithfulness tail), so all images read as one coherent style and the style can NEVER leak into the data. It doesn't change the generic/no-text/topical rules above; it's HOW the atmosphere looks, not WHAT is shown. Provider: if thecodexCLI is installed, generate via Codex's native image-gen (NO key — uses the user's Codex plan; slower, ~min/image); else the OpenAI key (OPENAI_API_KEY/~/.openai_key, requested out-of-band).meta.image_providerisauto(default, Codex-first),codex, oropenai. The skill-wide default stays flat/free — AI imagery is opt-in.
Notes. Reduced motion (accessibility variant — no zoom/pan, opacity-only reveals) is off by default; only set
meta.reduced_motionif the audience needs it or the user asks via Batch 1 ④ Other. Language (②) drives the caption font (CJK needs a CJK font — the bundled Latin one tofus) and the default voice, so a wrong code yields mojibake captions or mispronounced audio downstream.- ① Purpose (→
- Ingest — run
ingest.py. Report slide count and whether speaker notes were found. SKIP on a no-deck / from-scratch run (ingest.pyrequires an input deck): just create<out_dir>;storyboard.jsonis built at step 3.6 by merging the two plans — and remember to write the interview's meta (language/voice/aspect/audacity/…) into it there. - Understand the material DEEPLY — never narrate from the slides alone. A good
voice-over explains why, connects ideas, and is precise — that requires real
understanding the bullets don't carry. This step is what makes the script good.
- Material provided → read it properly, not skimmed: a paper end-to-end (intro →
method → every results figure/table → conclusion); a codebase via its README + the
key modules; a doc in full. Then write a structured comprehension brief and SAVE it to
<out_dir>/brief.json(mirror a readablebrief.md). It's the most decision-carrying artifact in the pipeline, so it must be understanding-shaped, not summary-shaped. Required keys:thesis— the ONE claim the material argues, a full sentence with a verb + object ("X cuts Y by Z via M"), never a topic label ("about X").mechanism— the causal how/why: ≥1 because/therefore chain, the load-bearing reason it works, in your OWN words (not copied verbatim off one slide — that's paraphrase, not understanding).evidence— array: each thesis/contribution → the specific figure/table/number/result that proves it, each with asource_ref.why_it_matters— the stakes the hook will use ·the_one_thing— a single sentence the viewer must leave with (the whole arc serves IT) ·misconceptions— what a smart viewer would get wrong / what the material is NOT claiming.per_unit— per slide: what it is really showing + the point to land ·unknowns— what you couldn't determine (flag for extra fact-check) ·source_health—coherent|thin|contradictory- a
conflictsarray of{what, resolution}.brief_qa.pygates this structurally before planning;critic-contentC0 audits it for DEPTH.
- a
- CAPTURE THE SOURCE TEXT as you read —
scripts/sources.py. For every passage a claim will rest on, persist the extract verbatim:python scripts/sources.py add <out_dir> --sid <slug> --origin <url|path> --kind web|pdf|doc|code|notes|transcript --title … --tier primary|secondary|community|self --fetched <today> [--as-of <date>] --text-file <extract>Then write each evidencesource_refas<sid>#<a literal quote from that extract>— or a list of such refs when a claim is cross-sourced. Tier every source as you capture it, and reach for the PRIMARY one on anything load-bearing: the real failure this catches is a figure every third-party guide repeats while the official page says something else — both quotes resolve, only the tier separates them. Put--as-ofon any price / version / count / "currently" claim: it dates the FACT, where--fetchedonly dates your reading, and a page fetched today can still be quoting last quarter. Why this is not optional on a WEB-RESEARCHED deck: the brief is otherwise the only record of what the material said, and nothing downstream can verify it — a content critic reviewing a real deck could auditbrief.jsonas an artifact but could not re-verify its web-sourced figures. That is the one place a wrong INPUT yields a fully-green output: the gates check the brief's internal consistency, the plans inherit it, and every beat carries the error. With extracts captured,brief_qaERRORs on a ref whose quote is absent from the text or whose source was never captured — an invented figure is stopped at step 3.5 instead of shipping. Know the boundary: the match proves the passage EXISTS in what you read, not that the source ASSERTS it (a quote lifted out of a negation still resolves), and not that the source is RIGHT. The mechanical gates stop fabrication and surface weak sourcing; whether the source actually claims the thing, and whether it deserved to be believed, remaincritic-content's judgement — which is why the extract, not just the citation, is what gets persisted. When a hardness warning fires and you cannot find a primary source, the honest fix is usually to say it as reported ("据报道…") or cut the number, not to silence the warning. - Record
coveragein the brief:read_in_full/sampled/skipped.unknownssays what you could not determine; coverage says what you never opened — the more dangerous of the two, because nothing else in the brief reveals that a chapter was skipped. - Before you plan — comprehension self-check (record PASS/FAIL per gate in the brief): ①
explain-back — state thesis+mechanism from memory, slides closed; if you can only reword the
bullets, re-read. ② causal — the mechanism has ≥1 because/therefore link not printed verbatim on
any slide. ③ evidence-map — every thesis/contribution maps to a specific evidence item. ④
one-thing — you can state
the_one_thingin ONE sentence and the arc serves it. ⑤ confusion — you actively looked for a contradiction (slides vs source, source vs source) and named+resolved it insource_health.conflicts(or flagged it). - No material →
WebSearch/WebFetchthe topic to ground and enrich: confirm the facts, numbers, names and framing the slides imply, and fold in current context. Research the LATEST, up to today — put the current year / "latest" in your queries, prefer the most recent sources, and verify every figure is current as of today's date (not a stale older number); for a time-sensitive fact, note its as-of date. Treat it as a fact-check, not flavour — with no source, you are the only thing standing between a confident-sounding wrong claim and the viewer. - Material provided but confusing / thin / contradictory → (i) resolve internal contradictions by
deferring to the primary source (paper > slides > notes), recording each in
source_health.conflicts; (ii) when slides and source disagree, narrate the more authoritative source and NOTE the discrepancy — never silently pick one; (iii) when the source is too thin to reveal the mechanism,WebSearchto fill the gap and mark it your own verified addition; (iv) when a load-bearing contradiction can't be resolved, STOP and ask the user (AskUserQuestion). Never narrate over an unresolved contradiction. - Either way, stay faithful: every claim and number in the narration must trace to the
material or a verified source — never invent results, numbers, or citations the
slide/paper doesn't support. A forward-looking aside is fine only if flagged as your
own addition. (Faithfulness is TRACE-TO-SOURCE; the brief above is the orthogonal
UNDERSTANDING layer — a script can be 100% faithful and still shallow.)
3.5. Content plan (director) — design the video as CONTENT before design/authoring. Dispatch
agents/content-planner.mdon the comprehension brief + material AND pass the interview's Purpose→arc_kind+director_note(tone/audience) — the planner ADOPTS that arc_kind (it may override only with a one-line justification indirector_note), so the user's Purpose choice isn't silently re-derived. It returns an ordered set of content beats — each with a learning point (traced to the material), a COARSEvisual_intent(metric/contrast/sequence/list/structure/statement/section— NOT a concrete layout), a narration intent,est_seconds, per-beatcontinuity(inherits-from / hooks-into) andrelation, and the narrative markersclimax: true(one beat ~75–80% through — the payoff) andhold: true(final beat, sparse). Plus top-levelarc,director_note,anti_slop(faithfulness bans), andrhythm(the pacing arc). It designs WHAT the video teaches — not how it looks. Concept ledger (build understanding, not just tension): each beat also carriesintroduces(the single NEW concept it teaches, or null — never a list),builds_on(already-introduced concepts it depends on), and a learningstage(hook|ground|build|why|land); plus top-levelassumed_known. Save the returned plan to<out_dir>/content_plan.json—pedagogy_qa.pywalks the ledger for a concept-used-before-introduced ERROR, andcritic-contentreads it for the prerequisite gate. 3.55. Register CONTEST — the divergence half (designed decks; audacity-gated). A register written once regresses to the safe mean: the register system (D2e) can REFUSE blandness, but only sampling several genuinely different registers and SELECTING can produce the striking one. So on a from-scratch designed deck (HTML or AI tier — skip on the 原样配音 tier, where the ingested pptx/pdf already owns the look, and skip atmeta.audacity: conservative), run the contest BEFORE the full design plan. Width by audacity:balanced3 candidates ·bold5 ·experimental7. Bounded cost: ONE authored page + ONE snapshot per candidate — never a full render. Procedure: ⓪ Read the register ledger first:python scripts/register_ledger.py show— pass any recent registers into the Phase A dispatch ("recent decks used: 「…」— do NOT clone them by default") so consecutive videos don't converge on one look. ① Dispatchagents/design-director.mdin CONTEST mode →register_candidates(forced-divergent angles; see its "Register CONTEST — Phase A"). ② Per candidate<key>: make<out>/_contest/<key>/, runpython scripts/theme.py <out>/_contest/<key> --style <its visual_style> [--accent …]for its own theme.css (branded deck: pass the brand hue as--accentfor EVERY candidate — the_contestdirs have no storyboard so the auto-seed can't fire there; candidates diverge on style family/motion/type/silhouette, never on the mark's colour), author ONE representative page from itsframe_spec— linking<out>/_contest/<key>/theme.css, NOT<out_dir>/theme.css(which doesn't exist yet; the html-pages boilerplate's theme link is substituted with the candidate's) — thenpython scripts/snapshot.py <page> <out>/_contest/<key>/frame.png(add--verticalwhenmeta.aspectis 9:16,--no-captionswhen captions are off orcaption_modeisband— the same exemptions keyframe_qa reads from the meta) — exit 2 = floor issues: repair ONCE in-register or disqualify; exit 3 = rendered but floor NOT probed (CDP unavailable): do NOT record arenderedfloor verdict — fix Chrome/CDP or drop the whole contest to paper mode. ②b Mechanical diversity check:python scripts/contest_diversity.py <out>/_contest/*/frame.png— a flagged pair (same mode + clustered palette + clustered silhouette) means the divergence was theater: REDIVERGE the pair, or keep it ONLY with a named justification recorded in the contest notes ("brand-locked accent" is PRE-AUTHORIZED on ameta.branddeck — the shared palette is a mandate; a flag there means look at mode+silhouette, which must still diverge). ③ Dispatchagents/design-critic.mdin judge mode (give it the PNG paths + specs +meta.audacity): floor-breakers out, survivors ranked, ONE winner (or REDIVERGE once — never twice). ③b Motion snippets for the finalists: re-run snapshot with--motion <out>/_contest/<key>/motion.mp4for the winner + runner-up (~2s each) — the judge CONFIRMS its ranking against the moving frames (a motion-led register may overtake a still-photogenic one), and the user gets the clips to watch. ④ Surface the winner + runner-up to the USER viaAskUserQuestion(winner first with "(Recommended)"; include the frame paths so they can look) — their pick is FINAL: record it asregister_contest.winner(+user_pick: true). When the ledger has a recent register, the pick MUST also offer a house option ("延续上一条的 register" — continuity is a legitimate choice, distinctness is never auto-imposed) and name what the last deck(s) looked like so the user chooses distinct-vs-house consciously. ⑤ Continue to the design plan (3.6) with the director committed to the selected register, recordingregister_contest {mode: "rendered", candidates, winner, user_pick}indesign_plan.json—validate.pywarns at bold/experimental when a register ships with NO contest recorded, and when the committeddesign_register.nameisn't the recorded winner's. No Chrome / no HTML pages: run the contest on PAPER (judge mode ranks the specs; recordmode: "paper") — weaker than pixels, say so, but still divergence+selection. 3.6. Design plan (art director) — give the content its visual language. Skip on the 原样配音 tier (the user's own slides,type:"slide"— the deck IS the design). Dispatchagents/design-director.mdon the content plan + comprehension brief +meta. It returns a SEPARATE design plan keyed by beat id: top-levelmotif(the CONCEPT motif — one topic-derived visual idea),theme(mode/accent/accent2/bg),design_anti_slop; and per beat the concretevisual.type+props+form(the form ledger, via its Concept→Visual dictionary — a cycle, pyramid, tree, morph or Sankey has no stock class: BUILD it, as an inline SVG or a workshop component),motion_intent,transition(mapped from the beat'srelation; seereferences/motion-grammar.md"Transition rhythm"),icons,media(image_prompt+motion: kenburns/bg-live/bg-drift), and acueanchor array for any multi-pointhtmlbeat AND any programmatic multi-element beat (chart/timeline/compare/keypoints— one anchor per element in spoken order, so the build is word-synced, not a blind timer). It also carries a per-beat reasoning trace (narrative_job/content_shape/rejected_default), a deckrhythm_map, and acolor_ledger— the operational design intelligence (block-dependency audit, expanded concept→visual dictionary with use/avoid/failure, evenness penalty, minimum deck-level variation) lives inreferences/design-intelligence-addendum.md, which both the design-director and the design-critic apply. It also carries a top-levelsignature_concept(ONE named, apt-but-unexpected content→visual encoding — the deck's creative idea, realized in a named beat as a BUILT workshop component) andstyle_thesis(the deck's distinctive aesthetic POV that fits THIS subject); and a top-leveldesign_register— the ONE whole-video expressive IDENTITY the video is designed in (name+motion_personality+type_attitude+how_distinct+carried_by), which BINDS visual_style/style_thesis/motif/ signature into a single register and, crucially, commits the video's MOTION character (not the default uniform whisper-zoom — two registers must MOVE differently). A coherent whole-video register is where the video's 差异感 (distinctiveness) lives; because it's ONE committed language carried across every beat, it's both bolder AND lower-variance than a single wild beat. Its risk budget is themeta.audacitydial (conservative|balanceddefault|bold|experimental) — which scales how far the register/motion/type push but NEVER relaxes the floor. Save the design plan to<out_dir>/design_plan.json—validate.pyflags a content_shape↔form mismatch + a missingsignature_concept/style_thesis/design_register(and an invalidmeta.audacity), and the design-critic (D1 fit, D2c creativity floor, D2e whole-video register + motion personality) judges them. 🔴 THE HTML DESIGN-FIRST FLOOR — meet it in THIS plan, before a single page is written (agents/ design-director.md "Design first";validate.pymeasures it from the page source and ERRORs at 9a, after the sample sign-off, which is the expensive place to learn it): per beat an ideal picture (ideal, no archetype named) and a route; at least HALF of the non-exempt pages BUILT or BESPOKE, at least ONE BUILT — the signature beat, a workshop component — and every AS-IS page writesideal+shares. BESPOKE means the page's own real layout (grid placement, a multi-track grid, positioning, a transform) or an SVG that draws the beat — notdisplay:flexaround stock cards, not a reference template's SVG copied. Exempt: the open/close title card, a real-photo plate with its provenance,type:"slide"beats. CINEMATIC films (meta.renderer:"remotion"— the bespoke-shot tier): the design step isagents/shot-director.md, not the design-director, and there is nodesign_plan.json. When the film came from a pptx whose theme is not Office's default, first runpython3 scripts/dna_from_deck.py <out_dir>so the film carries the deck's own brand rather than a direction's preset (validate.pywarns when it did not). The shot-director's file holds each procedure; the sequence is: ① The shot-template CONTEST — divergence + selection, the remotion analogue of 3.55. A direction is a whole-film ATMOSPHERE (a named look + a lean toward certain register FAMILIES + a hero; each beat is still its own language). Width bymeta.audacity(conservativeskips ·balanced3 ·bold5 ·experimental7):python scripts/shot_templates.py --route "<topic>" --audacity <a> --out <out>. The 6 templates are SEEDS — material, never a direction (why: case-law W6). Each direction is DESIGNED FIRST, like every beat: itsideal(the film's signature picture, no register named), itspalette_source([{colour, from}], every colour traced to the subject's own world — a GPS film's first contest put satellites on signal red and the user rejected all three directions as existing templates) and its HERO BUILT in the film's workshop (workshop.py new-shot); library registers may only follow the hero, adapted. Render a short SAMPLE VIDEO per direction so the user can SEE its look + MOTION:python scripts/contest_sample.py --route "<topic>" --audacity <a> --out <out> --conceived <file.json> --render—[{key, pitch, ideal, palette_source, dna, seam, shots: [[BuiltHero, {props}], ...]}]; it refuses a direction missing any of the three, and writes_contest_<key>.mp4+_contest_<key>.png(the hero settled) for the diversity gatescripts/contest_diversity.py <out>/_contest_*.png(rediverge a clustered pair); JUDGE withagents/shot-critic.mdin judge mode (floor-break + rank → winner+runner-up); surface the finalists' sample videos to the USER viaAskUserQuestion; recordmeta.shot_template+meta.shot_template_contest {candidates, winner, user_pick, width, audacity, judge_ranked, directions: {<key>: {ideal, hero, palette_source}}}— validate refuses a contest without them. The judge ranks FIT (palette and picture true to the subject) before meaning and craft, and boldness last.validate.pyERRORS a bold/experimental film with NO contest and checks width-vs-audacity. ② Per beat — DESIGN FIRST; the library is material, not a menu (the one flow, defined in shot-director Step 0.55). Readreferences/remotion-shot-authoring.mdFIRST (the frame-craft floor, the meaning mandate, the real-imagery tier, the anti-pattern catalogue — where films fail silently). In this order: (a) the form vocabulary (Step 0.5), then each beat's ideal picture —shot_fit.ideal, one line, no register named — written BEFORE any register is in view; (b) only thenpython scripts/shot_director.py <out_dir> --template <seed-key>, a deterministic family-varied skeleton that PROPOSES a register per beat as MATERIAL (shot_fit.material, verdictunjudged) — something to adapt or borrow from, never the beat's assignment; it keeps the ideals and leaves routed beats alone; (c) a route per beat against its ideal — BUILD (an object in a template's slot, or a film-local shot), ADAPT (layout/encoding/structure changed, recorded inshot_adaptation.changesAND visible in the props: a structure-affecting prop set away from the register's default), or AS-IS only when the register already IS the ideal (shot_fit.sharesnames the encoding it shares) — then assembles from runtime blocks and checks. Each beat getsshot+ faithfulshot_props+shot_adaptation(never a raw text-swap), ENCODES its beat (hide the caption — does the visual still carry THIS idea?), coheres with the direction (palette/motion/motif, not a random stack), keeps family variety, and reaches past the obvious register as audacity allows (note itsrejected_default).validate.pyERRORs when fewer than HALF of the non-exempt beats are BUILT (a workshop shot, or the film's own crafted object held in a frame's slot — adapting re-props a template, so it does not count toward this half), or none is built (the film's signature beat, designed to surprise); half is the floor, a strong film is mostly built. Every built thing goes onmeta.build_listwith itsmeansandaccept, is written in the film's own workshop (scripts/workshop.py new-object | new-shot | still | check; what to build with:references/building-blocks.md; how to make it mean something:references/object-authoring.md) and never touches the library. A built thing that depicts a real thing is TRUE to it (object-authoring.md rule 7): references collected first (a real photo viaimagefetch.pyor the product's own asset, and a spec or drawing you read), true proportions with their source, every defining part present and attached (data-part), real materials, one geometry, detail that holds at 100% — declared in itsfidelityrecord and judged onworkshop.py <out_dir> fidelity <Name>'s sheet (critic S16). Stylised ≠ inaccurate. Real imagery where the topic is concrete stays the documentary tier's. Ashot-based scene on the local renderer is a validate ERROR. Type that moves by the letter, word or line is drawn withruntime/kinetic(useKinetic+KineticText), never a hand-rolled per-character split — it keeps kerning and Chinese punctuation compression (0 px from one text node), every type gate reads it as its lines, andshot_proof.pyholds each must-read line to its reading time. Before routing, read each beat's argument against the reach table (references/remotion-shot-authoring.md§F) — the shapes the library already has a built tool for, including aWorldStagerun for a journey. Parallel build (four or more built shots): the lead designs every beat, the DNA and the kit and builds one reference shot; 3–4agents/shot-builder.mdbuilders, dispatched in ONE message, each build the shots they own and write a part file (never the board);python3 scripts/design_merge.py <out_dir>joins them (refusing any conflict), and the lead runs the gates once. Renders queue behind one machine-wide lock, so builders never starve each other's frames (shot-director "Parallel build — the lead's part"). ③ Then runpython scripts/seam_plan.py <out_dir>— the film's CUTS and CAMERA. A verify-and-fill pass, not a competitor: it SKIPS every beat the shot-director already marked, so authored intent always wins. It adds what an author cannot do by reading — it mirrors the renderer's luminance guard (a kinetic mark across a dark↔light boundary is silently downgraded, so a mark spent there vanishes), proposes the anchored seams where two beats' registers draw one anchor, cuts the unmarked seams by the film's tempo (launch/promo → hard cuts), and derives 2-4 MOTIVATED camera beats from each beat'srelation(payoff → push, close/opener → pull, else hold; a push into a continuation hands off). Never skip it (why: case-law W2).validate.pywarns when a film of ≥12 beats carries no marked seam at all, and when a declareddesign_dna.seammakes so many cuts kinetic that the marks stop being punctuation. ④ Look at the whole film on one page, then show it.python3 scripts/shot_proof.py <out_dir>renders every beat's settled frame and tiles them into<out_dir>/_design_review.png(beat · route · shot). Read the SHEET, not the board, against the per-beat checklist (shot-director Step 0.55): does the composition change with the idea (wide, close-up, the object itself, a diagram plane — not one page layout repeated), does the film's subject appear as a crafted OBJECT the camera can get close to (name three of its parts that are drawn — a shape you cannot is a pictogram), is every label readable at phone size, is every frame full? The compound-interest test passed every gate with nine flat ledger pages in a row; only the sheet showed it. And does it MOVE:python3 scripts/energy_skeleton.py <out_dir>renders each built beat with its props (~5 s a beat, cached) and names the ones that settle and stop under the motion floor — 6 of that film's 11. Fix, re-run, then copy the sheet to the Desktop and show it at the checkpoint below. The review after the render (agents/shot-critic.md, its ledger,critic_ledger.py --final) and promotion of built things are steps 9d–9f. From scratch, start the board from the content plan:python3 scripts/storyboard.py <out_dir> --from-plan language=zh renderer=remotion aspect=16:9 target_seconds=70 …writes one slide per beat carryingrelation,energy,stage,climax,hold— the fields seam_plan, energy_skeleton and rhythm_qa read from the slides — and the plan'spurpose(→meta.purpose) and anytempo(→meta.cuts), which set how the film cuts. Build the storyboard by MERGING the two plans: the design'svisual.type+propsbecome each scene; itstransitionbecomes the per-scene edges; aclimaxbeat's scene carriesprops.climax:true— the climax MARKER (rhythm_qareads it); it also drives the key-number landing hold only on achartcounter (a harmless no-op on any other form); itsicons/media/cueshape the authored page (.icon-tilerows perreferences/icons.md). Copy the content plan'sarc_kindtometa.arc_kindsorhythm_qarelaxes the persuasive-arc checks on an expository (tutorial/reference) video. Also persist the interview's audacity intometa.audacity—validate.py's register-contest lints read it from the storyboard meta; left unset it defaults tobalancedand a bold run's missing-contest warning would silently never fire. Persist the interview's brand assets intometa.brandat this merge too (and copy the files toassets/brand/if not already) — the theme auto-seed, the render bug, and every brand lint read the STORYBOARD meta; a brand recorded only in conversation notes never reaches any of them. Keep BOTH plan files — the script critic (step 5) receives them: thecritic-content/critic-narrativelenses audit the content plan (continuity, relation, faithfulness); the design-critic lens audits the design plan (motif, form diversity, transitions, icons, whitespace, rhythm, colour, motion).- Theme (HTML and programmatic tiers): run
scripts/theme.py <out_dir> [--style <meta.visual_style>]AFTER the design plan and BEFORE authoring pages or programmatic scenes — it samplesframes/for a curated light/dark palette fitting the topic (or pass--mode/--accent/--accent2/--bgfrom the design-director'sthemewhen there are no frames — EXCEPT the accent on a branded deck: whenmeta.brandis set, OMIT--accentso the brand auto-seed fires, or pass the brand hue itself; the director's topic-derived accent would silently override the mark's colour — the exact deck class the seed exists for is the from-scratch designed one with no frames). Pass--style <the deck's visual_style>(fromreferences/visual-styles.md) so the chosen style seeds the palette + emits style-hint vars. base.css/motifs.css AUTO-consume--radius(card + data-component corners),--font-display/--font-body(the style's bundled TYPE — see below),--border-weight+--border-ink(the--hairlineborder),--grid-strength(.bg-griddensity) — so every HTML frame follows the style with no per-page effort;--motif-inkis an author hint for the.bg-motiflinework. Style TYPE: the style maps to a bundled SIL-OFL FACE (Bangers for comic/manga, Space Grotesk for grotesque/geometric, Playfair Display for serif/editorial, JetBrains Mono for mono/technical —@font-face'd fromassets/fonts/, CJK+generic fallback) on--font-display(every headline + hero-number/value role) and a readable--font-body, so a comic deck reads comic and a Swiss deck reads grotesque;--font-kindlets the programmatic tier use the same face. An explicit--accent/--mode(and a frame-sampled BRAND palette) still win, and the WCAG floors run after, so a style can never make an unreadable palette. The style applies on EVERY tier (flat/HTML + the programmatic renderers read--font-kindto pick the same bundled title face), not just AI imagery. Pages linkbase.css→theme.css→motifs.css; the programmatic renderers parse the same vars. The plan checkpoint below shows the palette + mode + visual style. - Re-conceive, don't mirror: the content-planner designs a video arc (hook + throughline + resequencing), not the slide order — faithful to the substance.
- Illustrated pages: build a beat's design-plan
mediaas a.splitpage (text + a STATIC image panel, seereferences/html-pages.md; Ken-Burns is disabled inside.splitso it doesn't compete with revealing bullets — Ken-Burns is for full-bleed hero.bg-photoonly); generate the image viaimagegen(codex/key); keep it a generic broll. Most pages stay typographic. 🔴 CHECKPOINT · 🛑 STOP: show the content plan (arc + beats + coarse visual intents + the continuity through-line) AND the design plan (motif + theme palette + per-beat forms), and get the user's OK before authoring narration. On the remotion tier the design plan is SHOWN as_design_review.png(3.6 ④, on the Desktop) — the user judges composition, type and the subject on the picture; a list of form names is not a design they can approve. Before that, and before any shot is built, the user approves_sketch_review.png(scripts/sketch_sheet.py: each beat'sslide.sketchas a greybox — metaphor, the one hero, the layout; validate refuses a remotion beat with no sketch). If the user changes the register/style HERE (after a contest), re-recordregister_contest.winner(user_pick: true) to match — the committed register and the recorded winner must agree.
- Theme (HTML and programmatic tiers): run
- Material provided → read it properly, not skimmed: a paper end-to-end (intro →
method → every results figure/table → conclusion); a codebase via its README + the
key modules; a doc in full. Then write a structured comprehension brief and SAVE it to
- Write the manuscript — dispatch
agents/scriptwriter.md(the WRITE specialist). Give it the content plan + the design plan (motion_intentlives in the design plan now;est_seconds/continuityin the content plan) — or, with no plan, the per-slide intent + slide text — the comprehension brief + material,meta.language, and the pace ceiling. It returns the final spoken line per beat ({id → narration}) + aflagslist of any beat it could not source. Write those lines into each scene'snarration; resolve every flag (drop or repair the unsourced beat) before proceeding. It may also returnduration_estimate(if a beat's estimate exceeds itsest_secondsbudget, swap in itstoo_densefallback line or tighten it) andpronunciation_notes(already folded into how a term is SPELLED in the line — the renderer has no SSML). The scriptwriter followsreferences/narration-writing.md(the style basis). The on-screen captions are auto-derived from the narration, so its words are also the subtitle. (PLAN → DESIGN → WRITE → CHECK: content-planner plans, design-director designs, scriptwriter writes, the script critic of step 5 checks.) 4b. Image prompts (AI-backdrop look only —image_source:"openai"). The generated art is ALWAYS a background/atmosphere layer behind an HTML page (a soft.bg-softtexture or a hero.bg-photo/.splitcover), never a standalone image scene: for each page that wants a backdrop, author a groundedimage_promptfrom the narration + the chosen style, taggedimage_tag:"broll"andfit:"cover"; keep DATA in real HTML/chartcomponents (never AI). Generic/atmospheric prompts only — no real logos, faces, named vehicles, or text in-image. Topical AND (for image-forward media) on-beat, not decorative: the prompt's central motif MUST come from the VIDEO'S subject (derive it from the comprehension brief). For an image-forward scene (the image carries the beat — a cover/.split/kenburns), the motif must ALSO fit THIS beat's point — through an abstract quality (sparseness, motion, density), NEVER by depicting the beat's literal named subject (the generic rule still binds). Litmus: "hide the caption — (a) can a viewer sense what the VIDEO is about, and (b) does the image fit what THIS beat says?" — rewrite the motif from the brief + narration if either fails. The low-opacity.bg-softtextures rotated behind content pages are deck-level atmosphere and MEANT to be reused — only litmus (a) applies to them. (critic-contentR1e enforces this split.) The script critic (step 5;critic-contentR1e) reviews the prompts. 🔴 CHECKPOINT · 🛑 STOP: present every prompt + the estimated cost (imagegen.cost_estimate(n, quality)) and get sign-off BEFORE spending. Then runimagegen.py <out_dir>(the paid step; cached after). No key / API error → fall back to the free HTML tier (drop theimage_promptbackdrop, keep the page on its flat theme surface) and tell the user. HTML-tier per-beatmediaimages: generate each by calling imagegen directly —imagegen.generate(prompt, out_path, key)(key path) orimagegen._generate_codex(prompt, out_path)(Codex) — then reference the file byfile://in the page. Theimagegen.py <out_dir>CLI path generates any deck-levelimage_promptbackdrops/cover in one pass; these direct calls cover the per-beat page media. 4c. Documentary (REAL-image) fetch — FREE, no key. Skip on the 原样配音 tier (see 3.6). For every beat the design plan marksmedia.treatment:"documentary"(the design-director's per-beat imagery DECISION — see its "IMAGERY TREATMENT" procedure:nonefor data beats,atmospherefor mood,documentaryto SHOW a real concrete subject), fetch the real image at authoring time:imagefetch.fetch(doc_query, out_path, prefer=doc_prefer)→ returns an attribution dict (or None if nothing relevant and license-clean matched — the refused candidates and why print to stderr; read them before degrading, since a query that names the subject differently from Commons' records is fixed by rephrasing it, not by giving up the image). Then: treat it to match the deck on a non-photographic style —imagefetch.duotone(raw, out_path, shadow=<--fg rgb>, mid=<--accent rgb>, highlight=<--bg rgb>); reference it as a full-bleed.bg-photo(+.scrim) or a.splitpanel; and add a.creditline withimagefetch.attribution_line(meta)— placed as a DIRECT CHILD of<body>(a sibling of.stage, NOT inside it, so it can't tripkeyframe_qa's content-overflow probe). Fallback: iffetchreturns None, degrade per the design plan —atmosphereif the beat wanted mood, elsenone(never ship a blank). AFetchError(the CLI's exit 2) is NOT that case: Commons did not answer — a rate limit, a server error, the network — after the retries. It says nothing about which images exist, so run it again after a minute; never degrade the beat on it. No spend + no checkpoint (it's free + real), but the script critic (R1e) still checks the query matched the subject and the credit is present. Keep it to the 2–4 most physical beats. 4d. Author the pages (HTML tiers). Skip on the 原样配音 tier (see 3.6). This is where the deck'spages/scene_NN.htmlare actually written — one page per beat from the design plan (form + props + cue anchors + media), onbase.css+theme.css(+motifs.css;vertical.csslast on 9:16), perreferences/html-pages.md, faithful (real content only), each DESIGNED FIRST: the beat's ideal picture (shot_fit.ideal, from the design plan), then its route — BUILT (a workshop component), BESPOKE (the page's own composition: real layout of its own classes, or an SVG that draws the beat), or a stock form /references/html-templates.mdtemplate AS-IS only when it already IS the ideal (shot_fit.shares). A template is material to start from and change, not the composition to keep. A full-bleed backdrop may gently breathe (seek-frozen.bg-live/.bg-drifton a sparse hero/hold beat; deterministic, off under reduced motion). Setmeta.chrome_pathif Chrome isn't at the default macOS location. Immediately after authoring, runpython scripts/keyframe_qa.py <out_dir>(~1 min, no audio) to catch a blank page / canvas overflow while it's a one-edit fix, then hand_keyframes/all.pngtoagents/design-critic.mdfor its D11 rendered pass (focal dominance, repeated layout, crowding, figure-ground) — fix what it flags while pages are cheap to edit, before the script critic. BUILD — the same build-list step as the Remotion tier. For each beat, write the ideal picture first; when it is a THING or a form no stock class draws as the idea needs (a coffee puck in section, a scale's load cell, a cycle, a tree) — and always for the signature beat — build a COMPONENT, a custom element in the film's own workshop, instead of settling for the nearest stock form or hand-drawing it into one page: add itsmeta.build_listentry (kind: "component",id= its PascalCase name,beats,meansthat holds with the caption covered,accept,slot: "page"), thenpython3 scripts/workshop.py <out_dir> new-component <Name> --means "…", draw it perreferences/html-pages.md"Building a component", look at it (workshop.py <out_dir> still <Name>), andworkshop.py <out_dir> checkmust be clean before the page uses it.validate.pyholds the build list and the pages to each other. Promotion into the library is the user's choice at delivery (step 9f). - Script critic — ONE combined critic, ONE round, by default. Dispatch ONE subagent carrying all three
lenses — hand it
agents/critic-narrative.md,agents/critic-content.mdandagents/design-critic.mdas its brief (on the 原样配音 tier, the first two only: there is no authored design to judge; on a remotion film the design lens isagents/shot-critic.md's per-beat rows that read the board — S1 fit, S5 copy, S10 meaning — judged onshot_fit/shot_propsand_design_review/_proofstills, since design-critic.md's D-rules assume html pages) — for ONE round, reporting the top issues by impact; apply its EDITS and go on. Every lens estimates length withscripts/pace.py, never a bare chars-per-second rate. The user's own script + audition checkpoint below is what follows it, and that checkpoint never moves. The full 3-critic PANEL instead (the loop below, until all three PASS) when EITHER the user has asked for a careful or thorough review by this point (the post-render review-depth question of step 9d has not been asked yet, so this is only what they volunteered), OR the stakes are high — a defense, a launch the user called important, an external/paying audience, or anything they said must not go wrong. Decide it from what the user SAID (interview answers, the purpose they gave), record it asmeta.script_review = {"mode": "combined"|"panel", "why": "..."}, and say which you ran at the checkpoint. Never fewer than the combined critic; the floors below (faithfulness, sourcing, the human checkpoint) are the same either way. The panel: dispatchagents/critic-narrative.md,agents/critic-content.md, ANDagents/design-critic.mdconcurrently — in ONE message with three Agent calls — on the storyboard plus the comprehension brief / source material AND both plans (the content plan carriescontinuity/relation/faithfulness; the design plan carriesmotif+form+theme+ therelation→transitionmapping — each critic needs the plan that owns what it checks), so the panel checks facts, structure, AND design, not just style.critic-narrativeverifies: narration is precise and faithful (no wrong, vague, or invented facts/numbers); subtitle text matches spoken words, segments into clean readable lines, fits on screen, no typos or garbled text; narration is inmeta.languageandmeta.voicematches that language (a wrong-language voice would garble the audio).critic-contentverifies: audio↔visual alignment per beat (R2), script faithfulness and claims traceability (R1d/R1e including AI image prompts), scene/visual selection quality (R3/R5/R6), continuity, pace and cuts.design-criticverifies: form fit + layout diversity (D1), the concept-motif swap test (D2), creativity floor (D2c) + named visual style (D2d) + whole-video register & motion personality (D2e — the up-pushing 差异感 axis: name the register in one phrase, is it CARRIED across the video, does the motion actually vary, did it survive build/fix; blandness = a finding, but it only pushes UP and never overrides a floor), per-beat MEANING (D2f — hide the caption: does the design ENCODE THIS idea, not just decorate on-topic? applies to conceptual/statement beats too), transition rhythm vsrelation(D3), icons (D4), composition/whitespace (D5), visual rhythm + a WOW beat (D6), squint/cover-text (D7), semantic colour (D8), motion discipline / no-GIF (D9), visual anti-slop (D10). Panel mode: overall PASS only when ALL THREE critics return PASS. Apply the UNION of their required EDITS to the storyboard, then re-dispatch the critics (or just the failing one) until all return PASS. Either mode — a faithfulness or sourcing finding is never "top issues only": every one is fixed before the checkpoint. THEN: BOTH TIERS — THEN MAKE IT AUDIBLE, BEFORE the checkpoint —python3 scripts/script_audition.py <out_dir>. It speaks five beats (hook, climax, close and two consecutive middles) through the board's OWN voice, joined by the film's own measured pause, intoaudition.mp3in seconds. Listen to it in order, and send it to the user with the script. Never skip it: every check in this pipeline READS the narration, and the defect that ships is AUDIBLE (why:references/engineering-case-law.mdW1). Auditioning five beats is not the full synth; the full run still waits for approval. Ask ⑤ Voice HERE, right after they have heard it. Menu: keep this voice (edge-tts, the free default — natural, needs network, accent-matched, and the ONLY engine with per-word timings, so html reveals and karaoke captions land on the exact word) · MiniMax (paid, most natural, especially Chinese; needs a key) · OpenAI (paid, premium neural; needs a key) · macOSsay(offline, robotic fallback). (Other → an accent or gender preference.) State the trade-off aloud: with say/MiniMax/OpenAI, HTML reveals use the text-position estimate (tracks the voice's pacing, not word-exact). A paid pick triggers Batch 2 (key + a voice-sample pick), then re-runscript_audition.py <out_dir> --allow-paidin the new voice before sign-off — the user signs off on the voice they will actually get. (The flag is the consent: without it the audition refuses a paid engine and says how many characters it would send, so a board that merely CARRIES a paid voice never spends on a key nobody chose.) The audition speaks through the film's own voice path (tts.film_voice+tts.speak): same language detection, same pronunciation layer, no silent fallback — what is heard here is what the film will say. 🔴 CHECKPOINT · 🛑 STOP: present the full, critic-reviewed script and the audition audio, and get the user's edits/approval before the full TTS run. A script nobody has HEARD has not been checked, whatever the metrics say.
- Motion — read
references/motion-grammar.md. Default motion is a gentle centered zoomfrom:[0.5,0.5,1.0] → to:[0.5,0.5,1.12](keep zoom delta ≤0.20). Callouts are OFF by default — do NOT add emphasis boxes. They are easy to mis-place and a translucent box over a dark slide reads as a muddy coloured blob; the slide already shows the content. Add a callout ONLY if the user explicitly asks to emphasise a named region — then exactly one, tightly placed on that region, and confirm its position from the rendered sample. Timed callout (opt-in): to sync the highlight with the narration, give the callout acue(a phrase the narration says) — it appears when that phrase is spoken and holds to the clip end — or an explicitat(0..1 fraction) override. Leave both off for a whole-slide highlight.validate.pywarns if acueisn't found in the narration or lands past ~85%. - TTS — optionally first catch structural problems early with
python scripts/validate.py <out_dir> --pre-tts(skips the audio checks, so it's safe to run before synth): a missing image/page/asset or a wall-of-text caption is cheaper to fix now than after rendering. Then, before synth, ifmeta.voiceisautooredge:*, check edge-tts is installed:python -c "import edge_tts". If it's missing, offer to install it once (pip install edge-tts) for natural neural voices; if the user declines, setmeta.voiceto asay:fallback and continue. Then runtts.py(use--only Nwhile iterating on one slide). edge-tts emits.mp3;sayemits.wav— both fine. - Sample sign-off —
render.py <out_dir> --sample N, then showsample.mp4to the user (deliver.py <out_dir> --what sample). No critic runs on the sample: the A/V review (agents/critic-av.md) moved to the review depth the user picks after the first clean full render (step 9). Look at the sample frames yourself first — caption legibility, glyphs, nothing cut off — before you hand it over. A styled film (meta.style) also shows its STYLE SAMPLE (style_sample.py <out_dir>: the sheet + clip on the Desktop). Record--signoffonly after the user says yes to it;render_remotion.pyrefuses the full render until then. 🔴 CHECKPOINT · 🛑 STOP: get explicit approval of the style (voice/pace/motion/ captions) BEFORE the full render. Iterate on the sample until they approve — never batch-render all slides unsigned-off. Full render — gate, render, review, deliver, in this order (9a → 9f). 9a · Pre-render gates. First
python scripts/validate.py <out_dir>. A non-zero exit means a referenced image/audio/page/asset is missing, an index is duplicated,theme.cssis absent, or a caption is a wall of text — fix every ERROR before rendering (it catches in ~1s what would otherwise waste a multi-minute render). WARNING TRIAGE — required, not "skim the warnings too". An exit code of 0 is a floor, not a verdict: GROUP the warnings by kind (they repeat) and put every kind in one of three buckets — fix · accept, with a one-line reason · can't fix here — then TELL THE USER the accepted ones and why. A warning silently swallowed is a defect you chose and hid; one accepted out loud is a design decision (why: case-law W3). BOTH TIERS — also runpython scripts/rhythm_qa.py <out_dir>(needs the real durations, so after tts) — it flags flat pacing: uniform scene lengths, a mis-placed or missing climax, a non-sparse closer, an over-held static image, or no attention reset for >~35s. Fix the ERRORs; treat the WARNs as direction (varyest_seconds, place the climax at ~75–80%, split a long image hold). BOTH TIERS — and runpython scripts/pedagogy_qa.py <out_dir>— the teaching-order gate: it ERRORs on a concept used before it is introduced (walkscontent_plan.json's concept DAG). Fix every ERROR; it no-ops ifcontent_plan.jsonwasn't persisted. BOTH TIERS — runpython scripts/voice_qa.py <out_dir>— the VOICE gate (seereferences/anti-ai-voice.md); the narration is the one thing the two tiers share outright (why this says BOTH TIERS: case-law W4). It reports the vocabulary tells AND the rhythm distribution (sentence-length CV, balanced-pair share, connective share, antithesis share, and how many beats hold a single sentence). Treat each number as a place to look, not a target: fix the beats that genuinely read as template, leave the ones that trip a check and still sound like a person, and say out loud which you accepted. Then READ THE WHOLE SCRIPT ALOUD — the metrics catch distribution, only the read catches deadness. Remotion film — three more, none of which costs a render of the film: •python scripts/shot_proof.py <out_dir>— catches in ~3 minutes the mechanical findings that otherwise cost a full render (6–8 minutes for a 37-beat film) plus a shot-critic pass: a leftover register default, two beats rendering the same picture, action-safe overflow, ink in the caption band, an off-palette colour, a dead frame. Fix every ERROR and triage the warnings out loud, exactly as with validate. •python3 scripts/energy_skeleton.py <out_dir>— reads the plan's declaredenergyper beat against each register's measured motion (a climax on a register UNDER the delivery motion floor is the defect it catches). Fix the beats it names or re-declare them. •python3 scripts/cjk_type_qa.py <out_dir>— required whenmeta.languageis CJK; run it serially. The library is authored with short English demo copy, and a face set atline-height: 0.82is confident Latin typography and a collision in Chinese.text_safe_qacannot see it (nothing is cut off — the copy sits inside the frame and is unreadable). HTML-tier deck — also runpython scripts/keyframe_qa.py <out_dir>: it screenshots every page at several reveal states into<out_dir>/_keyframes/and flags any BLANK page or content overflowing the 1080 canvas (open_keyframes/all.pngand eyeball for tofu / off-theme / mistimed reveals). Fix any FAIL before the full render — cheaper than finding it inout.mp4. 9b · Render.render.py <out_dir>(HTML/image tiers) orrender_remotion.py <out_dir>(remotion; it writesout.srt+_keyframes/scene_NN.pngitself). For 9:16 setmeta.aspect:"9:16"— render and validate both honor it, captions auto-scale off the narrow dimension, and HTML pages must be RE-AUTHORED vertically (top-anchored, single-column restacks, vertical timeline rail;references/html-pages.md"9:16 vertical pages"); the--verticalflag also forces it on both. 9c · Post-render gates.python scripts/check_av.py <out_dir>on both tiers: a non-zero exit means A/V drift or non-uniform clip rates — fix the root cause (clear.clips/, fix audio or regenerate failing clips, and re-render) before delivering. On a remotion film the html-onlykeyframe_qa.py(which returns 0 there) is replaced by:keyframe_qa_remotion.py <out_dir>(a deterministic blank-frame backstop on the keyframes) ·text_safe_qa.py <out_dir>— the FRAME-CRAFT gate: it ERRORs when any TYPE is cut off by the canvas, asked of the DOM rather than inferred from border ink (its entry inreferences/pipeline-scripts.md) ·film_energy_qa.py <out_dir>— the FILM-ENERGY gate: motion, density and light measured against real launch films, the only gate that judges the FILM rather than a frame, so the only one that catches a delivery correct in every frame and inert as a film ·shake_qa.py <out_dir>— paired with film_energy_qa: the first refuses a film that does not move, the second one that moves without going anywhere, and passing the first by tripping the second is a failure this tier has shipped.frame_safe_qa.py <out_dir>is an ADVISORY read — a flooded border and a brightness OUTLIER scene (a white/bright shot in a dark film = palette clash) are worth seeing, never worth blocking; say which of its warnings you accepted.rhythm_qa/pedagogy_qastill apply (they readcontent_plan.json).Hand the film over before chasing sub-visible findings. When gates still fail after ONE fix round and what remains is below what a viewer sees — sub-pixel tremble, energy a hair under its floor, a caption a second late — deliver the film (
deliver.py), list each remaining finding with its size, and ask before another full re-render: a promo spent four ~45-minute rounds on 0.17 px and a 0.0003 motion gap, and the user called it too long. 9d · 🔴 THE REVIEW-DEPTH QUESTION — asked after the FIRST clean render, with the film in front of the user (modelled on slide-maker's post-build review question). When every machine gate is green —python3 scripts/critic_brief.py <out_dir> --gatesexits 0: it runs the tier's delivery gates once on this render (remotion: validate, check_av, keyframe_qa_remotion, text_safe incl.--glide/--sync, jitter_qa, caption_contrast_qa, cjk_type_qa on a CJK film, film_energy_qa, shake_qa, style_qa on a styled film, rhythm_qa, pedagogy_qa, shot_proof; HTML: keyframe_qa, validate, check_av, jitter_qa, caption_contrast_qa, rhythm_qa, pedagogy_qa) and records each exit code against the render id, andcritic_ledger.py --finalrefuses a render whose record is missing a gate or holds a failure, on every path,noneincluded; LOOK at_motion_events.jpg(the advisorymotion_events_qain that run: every sharp change off the planned cuts — a still or a contact sheet shows none of them) and at_review/beats_NN.jpg+_review/ends.jpg(scripts/review_sheet.py: every beat at 30/60/90% plus the film's first and last second; the shot-critic's checklist reads them), by eye — gates are a floor (W8.7: a caption letter on a bezel, a cropped numbered set, a blank pill over a title, both ends flashing, all found that way); a RE-render of a delivered film (a refresh, a re-light) is handed over on the same terms, not on a contact sheet (references/engineering-case-law.md W8) — FIRST hand the film over — and, on a remotion film, BEFORE handing it over runpython3 scripts/object_closeups.py <out_dir>and LOOK at_object_closeups.pngyourself: every object in the film (each device, each screen, eachdata-object) at its largest, cropped at 100%; fix what is not refined and accurate, or name it to the user — thenpython3 scripts/deliver.py <out_dir>and give the user that path — THEN ask ONE question (AskUserQuestion; on a host with no choice UI, one typed question in the user's language, listing the four options with their text below):option what runs rough cost (qualitative — no measured numbers exist for this skill) fast(default)ONE combined critic ( shot-criticcarryingcritic-av's lens; HTML tier:design-critic's delivery review carryingcritic-av's lens as H7), ONE round; only its top issues by impact are FAIL rowsone subagent pass + one re-render if it finds something standardshot-critic+critic-av(HTML:design-critic+critic-avbeside it), up to TWO rounds, round 2 a full fresh reviewabout two to four subagent passes + re-renders thoroughthe full loop: REVISE → fix → re-render → fresh independent review, until PASS open-ended; each round is a re-render plus a fresh review noneno critic — the user's own viewing is the review, recorded as user-waived nothing further Pre-select
fast— always; the user may pick any tier (python3 scripts/critic_ledger.py <out_dir> --preselectprints it, andcritic_ledger.py --finalrequiresmeta.review.preselectedto equal it). A waived machine-gate finding does not raise the tier: standard adds critic-av and a second round, and neither re-judges the waived finding. Instead the critic confirms each waiver in its own ledger row — every non-emptymeta.*_waiverbutreview_waivergets awaiversrow{key, holds: true|false, evidence: <a keyframe or frame>}saying whether its stated reason is true of the rendered film (one row per key, judging every axis it names), andholds: falsemust come with a FAIL on the dimension that owns the finding, on every reviewing tier. Today only remotion'sfilm_energy_qaconsumes a waiver (meta.energy_waiver, owned by S12); no HTML gate does, but a waiver recorded on an HTML board is confirmed the same way (H6). An advisory warning you argued for in 9a's triage is not a waiver.thoroughis never pre-selected (the user asks for it), andnoneis NEVER pre-selected and never inferred from silence, a "looks fine", or a green gate — only the user's explicit pick. In auto mode, or when the user does not reply, the pre-selectedfastapplies and is recorded as such ("user_answer": "no reply","preselected": "fast"). Record the answer asmeta.reviewinstoryboard.json:"review": {"tier": "fast", "user_answer": "<the option or words the user gave, or \"no reply\">", "preselected": "fast", "render_sha256": "<the render id — only for none, on a remotion or HTML film>"}On the 原样配音 tier (every beat a supplied slide) and a programmatic-only board there is no ledger and no contact sheet, so no
render_sha256applies: recordtier,user_answerandpreselected; the review at that depth iscritic-avalone onout.mp4(andnoneis still only the user's word).critic_ledger.py --finalreads it, and refuses a film with NOmeta.review("ask the review question"). The ROUND is derived from the render historycritic_brief.pyrecords, never self-reported. A PASS must be pinned to the CURRENT render. When a capped tier (fast1 round,standard2) has spent its rounds and the last one said REVISE, every failed row is resolved one of two ways: its fix is applied in a re-render (recordapplied; re-runcritic_brief.pyso the sheet and history match the new render), or — for a finding you did not fix — it goes back to the USER: list the open findings and offer one more round or accept as-is. You never decline a finding yourself. An acceptance is the user's, recorded per finding with their words, pinned to the render the critic reviewed:"review": {..., "accepted": [{"id": "S8", "user_answer": "<their words>", "render_sha256": "<the ledger's pin>"}]}The film then ships marked "reviewed at
<tier>, not a PASS". What never moves with the tier: every machine gate above, the faithfulness and sourcing rules (an S3 finding on remotion, H1 on HTML, is always FIXED — never declined, never accepted, by anyone), the human script/audition checkpoint, an independent reviewer, every ledger row, the route rows (below), the waiver rows, and the render pin.nonewaives the review — and only the user may choose it.meta.review = {"tier": "none", "user_answer": "<what the user said>", "render_sha256": "<the render id, which you compute>"}(the oldermeta.review_waiver = {reason, render_sha256}form is still read the same way). Pin it withpython3 scripts/critic_ledger.py <out_dir> --render-id— it builds the contact sheet from the keyframes when there is none, so anoneanswer needs no full brief. The render id is what every pin in the review is pinned to — the ledger's, anoneanswer's, each accepted finding's and the render history's:--render-idprints it, a sha256 over_contact_sheet.png(the picture the review read),out.mp4(picture, sound and burned captions as delivered) andout.srt. The step-8sample.mp4and the HTMLpreview.mp4are not the delivered film and are not in it.critic_ledger.py --finalthen exits 0 without a ledger — once the--gatesrecord for this render is complete and green (re-runcritic_brief.py <out_dir> --gatesafter any re-render) — says REVIEW WAIVED on every run, and rewritesNOT_DELIVERED.mdinto a record that the film shipped unreviewed and why — a waiver is not a PASS, andlsmust keep answering "was this ever looked at?" truthfully.Three things bind you here:
- Never author it on your own behalf. Not to save time, not because the gates are green, not because
you think the film is good. It is the one judgement in this pipeline you are structurally the wrong
party to make (
critic_ledger.py's own header: the maker has confirmation bias about their own output). If the user has not said it, there is no waiver. - It expires with the render. The pin covers the cut the user actually watched. Change one beat, one colour, one line of narration, re-render — the render id moves, the waiver stops applying, and the gate asks again. That is deliberate: "fine once" must not become a licence over everything changed afterwards. When that happens, show the user the NEW cut and ask again; do not re-stamp the pin.
- It waives taste, not correctness.
check_av,keyframe_qa_remotion,text_safe_qa,cjk_type_qa,film_energy_qa,shake_qaandvalidate.pyall still run and still gate delivery:--finalreads their exit codes from the--gatesrecord of this render. A waived film is one nobody judged for register fit, meaning, frame-craft or boldness — not one nobody checked plays.
9e · The review, at the depth chosen. On a remotion film, run
python3 scripts/critic_brief.py <out_dir>, then dispatchagents/shot-critic.mdon the keyframes + thecheck_av+keyframe_qa_remotion+text_safe_qa+film_energy_qa+ (advisory)frame_safe_qareports. It judges register fit, family variety, faithful copy (no demo-number/WorkBuddy leftover), decodability, MEANING (S10 — does each shot's design ENCODE its beat's idea, not just look good?), boldness (S8, audacity-scaled) and direction adherence, and REVISEs failing beats (the shot-director re-assigns → re-render). Its verdict is a LEDGER: every dimension gets a row in<out>/_critic_ledger.json— the clean ones too, each citing the keyframe or brief line it rests on — plus oneroutesrow per beatvalidate.pycredits as ADAPTED or BUILT, saying whether that route is VISIBLE in the rendered frame (a route nobody can see fails S14), plus onewaiversrow per waived machine-gate finding (9d) — andpython3 scripts/critic_ledger.py <out_dir>must exit 0. Every review round starts withcritic_brief.py, and so does--finalafter you apply fixes: it rebuilds the contact sheet from the new keyframes and records the render, which is what the round count and the render pin are checked against (a sheet older than the keyframes is refused, and so is a film re-rendered — picture, sound or captions — after the last brief: an audio-only fix moves the render id too, so it counts asapplied). The delivery pass is a fresh subagent whose ENTIRE input is the<out_dir>path — no rationale, no summary of what you fixed, no steer about where to look — thenpython3 scripts/critic_ledger.py <out_dir> --final(exit 0 required; it refuses an in-context ledger, a ledger missing any dimension, a PASS pinned to an earlier render, and one pinned to a render this film never had) (why: case-law W7). On an HTML-tier film (not remotion, at least onetype:"html"page) the SAME method runs with the HTML critics:python3 scripts/critic_brief.py <out_dir>(it re-runskeyframe_qafirst, pulls one delivered frame per beat out ofout.mp4into_frames/— the burned caption is on it — builds_contact_sheet.pngfrom the page filmstrips and records the render) → dispatchagents/design-critic.md's delivery section ("Rendered review — the delivery ledger", the H-dimensions; atfastit carriescritic-av's lens as H7, atstandard/thoroughcritic-avruns beside it) as the same fresh subagent, which fills_critic_ledger.json— one row per H-dimension plus oneroutesrow per pagevalidate.pycredits BUILT or BESPOKE (a route nobody can see fails H8) and onewaiversrow per waived machine-gate finding (9d) — thenpython3 scripts/critic_ledger.py <out_dir> --final, exit 0 and its verdict read, exactly as above. The 原样配音 tier (every beat a supplied slide) and a programmatic-only board have no authored page: their review at the chosen depth iscritic-avalone onout.mp4, with no ledger (critic_ledger.pysays it does not apply, exit 2). 9f · DELIVERY CRITERION — every gate, not two (why: case-law W5). Deliverout.mp4,out.srt, and the editablestoryboard.jsononly aftervalidate.py,check_av.py,keyframe_qa.py,rhythm_qa.pyandpedagogy_qa.pyALL exit 0 (voice_qa.pyis ADVISORY and always exits 0 — read its signals and say which you accepted; failing a build on them would produce the "rule voice" its reference warns about). On a remotion film,keyframe_qa_remotion.py+text_safe_qa.py+cjk_type_qa(CJK film) +film_energy_qa.pyshake_qa.pyexit 0 and the review at the user's chosen depth (critic_ledger.py --final) REPLACEkeyframe_qa.py, which no-ops there;frame_safe_qa.pyis advisory. Both lists arecritic_ledger.DELIVERY_GATES— whatcritic_brief.py --gatesruns and records, and what--finalchecks for this render. On an HTML-tier film the review at the user's chosen depth is part of the criterion too:critic_ledger.py <out_dir> --finalexits 0 and its verdict is read (step 9e) —render.py's full render leavesNOT_DELIVERED.md, and only that review removes it. Also readkeyframe_qa's deck advisories (silhouette repetition, content-band uniformity) and any scene reported UNVERIFIED — an unverified scene is not a passing scene, it is a scene nothing measured. Then record the deck's register into the cross-deck ledger:python scripts/register_ledger.py record <out_dir>(feeds the next video's contest with "what the last decks looked like"). PROMOTION IS THE USER'S CHOICE, AT DELIVERY (both tiers). List the film's built things (meta.build_list) — each with its settled frame (workshop/_stills/) and its gate results — and ask the user withAskUserQuestion(multiSelect) which, if any, to promote into the library. For each one chosen:python3 scripts/promote.py <out_dir> <Name>(an object or an HTML component: it joins the library and the catalogue) or... --family <X> --use-when "…" --motion "…"(a remotion shot: registered at every sync point and measured in the right order). Nothing is promoted without the user's pick; nothing a film builds reaches another film until it is. A film the user shipped with reviewnonepromotes too, once--finalpasses on it; its library entry says it was never critic-reviewed. Then hand the user the video WHERE THEY LOOK FOR IT — always, for every render they are asked to watch (a sample, a preview, the final cut):python3 scripts/deliver.py <out_dir>copiesout.mp4(andout.srtbeside it, same name) to~/Desktop, or to~/Downloadswhen the Desktop cannot be written, and prints the path — give the user THAT path, and send the file too when the session can. Never point the user at a file inside this skill's folder,~/.claude, a.superpowers/or other hidden work folder, or a temp directory: nobody browses there. If neither folder can be written (macOS can withdraw access mid-session), ask the user for a folder and pass--to.
- Never author it on your own behalf. Not to save time, not because the gates are green, not because
you think the film is good. It is the one judgement in this pipeline you are structurally the wrong
party to make (
- Iterate — any change = edit
storyboard.json, then re-run render (the per-slide clip cache re-renders only changed slides) and tts (--only N). For DESIGN experiments (register/theme/caption changes that bust many clips), iterate withrender.py --preview(12fps, own cache,preview.mp4) and only run the full render once the look is settled. Never hand-edit the video. A film made before design-first (no beat carriesshot_fit.ideal— a board built on the normal path writes them at step 3.6) fails the design-first floor on any re-render, so a one-word edit would force a half-film redesign.validate.pyreplaces the floor's errors on such a board with ONE that asks the USER (AskUserQuestion): bring it up to design-first (write each beat's ideal and meet the floor) or keep its existing design for this edit. Record a keep withpython3 scripts/validate.py <out_dir> --keep-design "<what the user said>": it writesmeta.design_first = {"legacy": true, "user_answer", "kept": [...]}for every beat on the board at that moment (refused for a non-answer — auto mode cannot keep a design — and for a board where any beat already has an ideal). A kept beat stays exempt while it keeps its shot (HTML: its page) and carries no ideal — writing a kept beat's ideal means redesigning it, so it leaves the keep, and a hand-written keep over beats that carry ideals keeps nothing; a beat added or changed later follows the normal rules — its ideal, a route,sharesfor as-is — and those beats as a group must be at least half built, so a single new beat is built. Writing a new beat's ideal never voids the keep. validate prints one WARN naming the kept beats, the critic's route rows are owed only for the others, andcritic_ledger.py --finaland the brief say what was kept. Dates prove nothing here and are not read.
Guardrails
durationalways comes from rendered audio (tts.py sets it) — never guess timings.- Set
meta.voice,meta.captions,meta.language, andmeta.audacityin the storyboard, not via flags.meta.voiceis one of:auto(default — tts.py prefers edge-tts, elsesay),edge:<id>(e.g.edge:en-GB-SoniaNeural),say:<voice>,openai:<voice>, orminimax:<voice_id>(or bareminimax→ a catalog voice bymeta.language+meta.voice_gender). MiniMax region is auto-detected (tries internationalapi.minimax.iothen mainlandapi.minimax.chat, caches the one that works) — an int'l or mainland key just works. Tunables:meta.tts_model(defaultspeech-02-hd),meta.minimax_base(pin one host, disables auto-retry),meta.minimax_group_id(only if a mainland setup needs it); key viaMINIMAX_API_KEY/~/.minimax_key. - Write English terms as they are READ, not spelled for the voice.
tts.pysends a Chinese edge voice "A-I" / "T-T-S" for a standalone 2-3 letter initialism (measured: without it the voice drags the syllable before the letters and pauses) and maps the word timings back, so the caption and karaoke keep "AI". Never hand-write "A G P L" / "T T S". Anything else pronounced wrong goes inmeta.tts_lexicon({"AgentHalo": "Agent Halo"}— spoken text only);meta.tts_spell_initialisms: falseturns the spelling off. - The film opens and closes on a held picture:
tts.pymakes the first word waitmeta.open_hold(default 1.0s) and the last word endmeta.close_hold(1.2s) before the film does, shifting the first clip's word times with it; 0 turns either off. meta.tts_speed(default1.0) tightens or loosens the narration PACE without cutting content — a multiplier applied to BOTH edge-tts (mapped to itsrate±%, e.g.1.25→+25%) and MiniMax (itsspeed). Clamped[0.5, 2.0]; for edge, keep within ~±30% (0.8–1.3) — beyond that the neural voice sounds unnatural. Per-word timings scale WITH the rate, so captions + audio-synced reveals stay in sync. Reach for1.2–1.3when a faithful script overruns the target runtime. The knob is BIDIRECTIONAL, and slowing DOWN is the fix for a video that feels rushed or whose scene-ends read as abrupt. The instinct — "give the viewer more time to read" — must NOT be paid for by padding a long SILENT, STATIC tail onto each clip: a frame frozen and silent for 2–3 s then hard-cut reads as the video HANGING, not as breathing room (a viewer called every such scene-end "a stiff obvious gap"). Reading time belongs INSIDE the narration — settts_speedto ~0.9–0.92so the whole delivery is unhurried and the reveals land leisurely — leaving only the SHORT heard pause ofmeta.scene_pause(default 0.55 s, keep ≤ ~0.9 s; seetts.pyunder Pipeline scripts) after the last word.meta.audio_breathis a RAW pad that overrides it — set it only deliberately. Slow-voice + short-breath + a gentle seam beats fast-voice + long-dead-tail at the same total runtime, every time. (Rule of thumb: if any page's on-screen text exceeds ~28 characters/second of its own duration it will feel too fast — lowertts_speedor split the page, don't just freeze the tail.)meta.image_sourceisnone(default, free) oropenai(gpt-image-2, paid). AI images are generated once byimagegen.pyand CACHED under.assets/— re-renders are free + offline.meta.brand(OPTIONAL — user-supplied REAL assets; the mirror of the no-fabricated-logos imagery doctrine, which stays untouched):{"logo": "assets/brand/logo.png", "logo_dark": "assets/brand/logo_dark.png", "name": "ACME Institute", "placement": ["cover","endcard"], "bug": {"corner":"tr","opacity":0.5,"height_frac":0.045,"margin_frac":0.02}}.logois REQUIRED whenbrandis present — path relative to out_dir (svg ok for HTML lockups; the render bug needs raster — and since it picks its variant BY THEME GROUND, every declared variant must be raster when "bug" ∈ placement);logo_darkis an OPTIONAL variant for dark grounds (falls back tologo);nameis the OPTIONAL end-card byline;placementis a subset of {"cover","endcard","bug"} — DEFAULT when absent:["cover","endcard"];bugis read only when "bug" ∈ placement (defaults as shown). Semantics: "cover"/"endcard" lockups are AUTHORED into the first/last HTML pages (design-director doctrine —render.pydoes NOT draw them; the pages fingerprint themselves). "bug" is the RENDER-level persistent corner mark: drawn on EVERY scene EXCEPT scene 1 when "cover" ∈ placement and the last scene when "endcard" ∈ placement (double-brand on one frame is a craft fail). Top corners only ("tr"/"tl"— the bottom is the caption zone); height =height_frac·H (default 4.5%), margin =margin_frac·W, opacity via alpha; useslogo_darkwhen the parsed theme bg's relative luminance < 0.5, elselogo; height scales by the NARROW canvas dimension (so 9:16 doesn't balloon it) and a banner wordmark is clamped to ~35% of the frame width (aspect kept); OVERLAID onto the composite (not baked into the frame — it must not ride the Ken Burns move) BEFORE the edge/transition filter so it dips with the seam (a bug floating over a bg dip is wrong). The remotion tier ALSO draws the logo — as a persistent corner bug (Film.tsxBrandMark, on every scene subject toplacement), served from the out_dir; it has no AUTHORED cover/endcard lockup page (that's an html-tier concept), so a remotionbrandshows only the bug. The logo is NEVER stretched (preserve aspect), never recolored, no effects.- HTML pages tier cache: a page's clip re-renders when the page file,
theme.css(re-theming), oraudio/NN.words.json(new edge run) changes. - Anti-slop (design-critic D10 / AV-critic): no emoji in titles; no hardcoded hex — use semantic vars
(
var(--bg),var(--accent), etc.;validate.pylints raw#hexin style/SVG colors,design-criticD10 fails it); no gradient-mesh backgrounds; no player-chrome / progress bars / timecodes / page counters; no more than 2 consecutive beats with the samevisual.typeamong the PROGRAMMATIC types (htmlscenes are exempt — vary those by form family, not type). - Layout diversity (HTML tier): no single form family (cards/flow/scorecard/quadrant/hubspoke/
blocks/timeline/compare) above ~45% of html scenes —
validate.pywarns,design-criticD1 fails it. - Concept (design-critic D2) + continuity (critic-content). The video must express THIS topic — the
DESIGN plan carries the top-level
motif(the CONCEPT motif — distinct from theimage_tag: motifimagery class); a name-swappable design (swap the topic → still works) is a template, not a design, and gets revised (design-critic D2). And beats must connect (eachcontinuity: inherits from the prior, hooks into the next) so the video argues a case rather than listing slides (critic-content). - Audio-synced reveals (HTML tier) — content must not lead the voice. Make multi-point pages
audio-synced by DEFAULT: tag each point
data-cue-index="N"(spoken order) +data-cue="<spoken anchor>"(a phrase the narration says); the design-director emits a per-beatcuearray for this. When edgeaudio/NN.words.jsonexists,render_htmlreveals each point exactly when its phrase is spoken. If a page is NOT cued, LEAVEanim_secondsunset —render_htmldefaults it to spread the reveals across ~0.7× the scene (tracking the speaking pace) instead of cramming them at the start; a smallanim_secondson a long content page makes content appear before it's spoken.validate.pywarns on that, andcritic-content(R2) fails an uncued multi-point page whose reveals lead the audio. Per-point alignment (leads/lags).validate.pyalso estimates, for each point, WHEN it is spoken (itsdata-cueanchor's position in the narration) vs WHEN it is shown (the resolved word-cue time if edgewords.jsonexists, else the paced stagger) and warnspoint N spoken at ~X% but shown at ~Y% — reveal leads/lags the voice by ~Ns. This catches misalignment in both directions and for both audio paths — important for a paced voice (say/openai/MiniMax, no per-word timings): a linear stagger only aligns if the narration introduces the points at roughly even intervals; otherwise cue it with edge-tts, restructure the narration, or tuneanim_seconds.critic-contentR2 confirms the fix. - Theming: one colour world — html pages link
theme.cssand the programmatic scenes parse the SAME vars (dark palette only when notheme.cssexists), so mixing the two in one deck is fine. Pick a palette/mode that fits the TOPIC (not always dark); never raw hex. Re-runningtheme.pybusts ALL cached clips. (When to run it: step 3.6 "Theme".) - Image provider: Codex-first, else the OpenAI key (Batch 3 "Provider"); Codex and OpenAI images cache separately (keyed by provider).
- API key — never persist it. Applies to the OpenAI key (gpt-image / openai TTS) AND the
MiniMax key (
MINIMAX_API_KEY/~/.minimax_key). Request it fresh each run and pass it ONLY via the env var (orimagegen.py --key) for that one call. NEVER write any key intostoryboard.json, any script, the.assets/manifest, a log, or any committed file — the scripts keep it only in the request header, nowhere on disk. If the user pasted a key into the chat, remind them to rotate it (the transcript retains it). - Pacing — keep cuts moving. Prefer MANY short beats (~3–6s, one idea each; ≈
target_seconds/4beats) and roughly ≤8s per scene, especially image/b-roll (a held static image reads as sluggish even with Ken Burns). If a scene's narration runs long, split it into shorter beats rather than holding one frame; the animated renderers' internal reveals keep the screen moving. - Informative-first visuals. A beat that states a fact or concept uses an INFORMATIVE
visual —
chart,compare(split/versus breakdown),keypoints(kinetic labeled points), ortimeline— never a decorative photoreal image. AI photoreal (image_prompt/broll) is allowed as a rare atmospheric opener/closer OR as illustrative accompaniment on a content beat where the fact stays as on-page text (e.g. a.splitpage); never as the sole carrier of a claim. - Audio↔visual. Each narration line must MATCH what is on screen (its beat's visual) — the
critic-content(R2) fails a mismatch. - Language is set once, in
meta.language— write the narration in that language, and letmeta.voicematch it. tts.py auto-picks a matchingsayvoice when the language is non-English and you left the default (seereferences/tts-voices.mdfor the per-language table). render.py auto-swaps to a system CJK font for Chinese/Japanese/Korean captions; if a glyph still tofus, setmeta.fontto a.ttc/.ttfthat covers the script. Confirm the captions look right on the rendered sample (step 8) — that's where mojibake shows.
Imagery faithfulness (AI / b-roll / documentary)
Every on-screen visual is one of four classes; critic-content (R1e) enforces them:
motif— a generic programmatic vector. Always allowed; asserts no fact.broll— a generic illustrative image, including an AI-generated one (image_prompt). Allowed ONLY as generic/atmospheric backdrop — no real logos, faces, named vehicles, or in-image text, and it must not sit as "evidence" beside a specific factual claim. It must also be TOPICALLY RELEVANT to the video — its motif evokes the subject (the "generic" rule forbids fabricated specifics, not the subject itself). Topic-neutral filler (random paper, a generic gradient, an unrelated stock scene) is a defect even though it is "faithful"; the imagery should look like it belongs to this video, not any video.documentary— a REAL, license-clean image (photo/map/diagram) of the ACTUAL named subject, fetched from Wikimedia Commons viascripts/imagefetch.py(CC/Public-Domain only). BECAUSE it is real + sourced, it is allowed to DEPICT the real thing and demonstrate the point directly (a real rail-network map, a real cityscape, a real crowded station) — the one image class that may show a named real subject. Requirements: (1) a genuinedoc_querynaming the subject (a wrong image is a faithfulness break); (2) an on-screen.creditattribution line (CC-BY requires it; the sidecar.jsoncarries license/artist); (3) numbers/claims still live in on-page TEXT — the image shows the subject, the text asserts the fact. Reach for it on CONCRETE topics; treat it to match the deck (imagefetch.duotone) on a non-photographic style. Not for abstract topics (usebroll/none).asserted— an AI image FABRICATING a specific named vehicle/mission/person/event/figure. NOT allowed (that's precisely whatdocumentaryexists for — fetch the real one instead of inventing it). DATA always stays in faithful HTML/chartcomponents — never render numbers/figures as an AI image. The full-AI escape hatch (image_source:"openai"with data as AI) is the user's call, but thecritic-contentflags every data-bearing AI scene.
Brand assets (user-supplied real logos — the DOCTRINE SPLIT)
meta.brand (Guardrails has the block) places the user's OWN real logo. Two complementary rules,
not in tension: user-supplied real logos are placed VERBATIM — never stretched (preserve
aspect), never recolored, no shadows/effects, clear space respected — while generated imagery
still NEVER fabricates a logo (broll stays logo-free, exactly as the imagery doctrine says).
Cover/endcard lockups are authored into the first/last HTML pages (references/html-pages.md
"Brand lockups"; the design-director owns placement); the corner bug is the only render-drawn
brand mark. Slide-image tier (pptx ingest): master-slide logos arrive already baked into
frames/ — render adds NO cover/endcard branding there; the bug is the only brand path render
adds on that tier.
When a step fails (if → then → still-failing)
| Trigger | First fix | If it still fails |
ingest.py: soffice missing / hangs | Kill stale soffice; ask user to export the deck to PDF and feed the .pdf | Feed a folder of exported slide PNGs instead |
| pptx has no speaker notes | Generate narration from visible slide content + any source docs | Ask the user for the deck's intent per section |
tts.py: cloud voice errors / no OPENAI_API_KEY | It auto-falls back to the language-matched say voice (e.g. say:Tingting for zh) and prints a notice — continue | Set meta.voice to an explicit local say: voice |
tts.py: MiniMax error / no MINIMAX_API_KEY | It auto-falls back to the language-matched say voice and prints a notice — continue | Verify MINIMAX_API_KEY (region is auto-detected across both hosts); 2054=voice_id not on account, 1008=no balance (top up), 2049=key invalid on both regions; check voice_id/tts_model exist for your account |
tts.py: ⚠️ MIXED-VOICE RUN warning (cloud/edge engine fell back to say on SOME scenes) | A systemic mid-run failure (MiniMax 1008, expired key, network) split the deck between two voices — do NOT ship it. Fix the engine and re-run tts.py, OR set meta.voice to edge:<id> (free, consistent) / say:<voice> so EVERY scene uses one engine | If the cloud engine can't be fixed, switch meta.voice to edge:* and re-run so the whole deck is one voice (meta._tts_mixed_voice records which scenes fell back) |
tts.py: edge-tts not installed | The workflow offers pip install edge-tts once; on decline, set meta.voice to a say: fallback | tts.py auto-falls back to say at synth time and prints a notice — continue |
tts.py: edge-tts network error / endpoint down | tts.py catches it and falls back to the language-matched say voice (e.g. say:Tingting for zh) and prints a notice — continue | Switch meta.voice to an explicit say: voice (fully offline) |
imagegen.py: no OPENAI_API_KEY | It prints a notice and leaves those scenes for free-tier fallback — convert them to programmatic/slide and continue | Set the key (export OPENAI_API_KEY=...) and re-run imagegen.py |
imagegen.py: image API error / rate limit | Per-scene catch → free-tier fallback for that scene; cached scenes unaffected | Retry later; cached images never re-charge |
imagegen.py: Codex run fails / makes no image | _generate_codex raises → that scene falls back to the free tier; other cached scenes unaffected | Force meta.image_provider:"openai" + provide a key, or use the free programmatic/HTML tier |
| Image tier on but no codex AND no key | Each scene falls back to the free tier with a notice | Install codex, or set OPENAI_API_KEY / ~/.openai_key, then re-run imagegen.py |
render.py: concat -c copy errors (codec/timestamp) | Re-encode the concat (-c:v libx264 -c:a aac) — see references/ffmpeg-recipes.md | Render per-slide with --only N and report the failing slide |
| Captions/text look wrong or font missing | render.py falls back to PIL's default font (still draws) | Confirm the bundled faces exist — DejaVuSans.ttf/DejaVuSerif.ttf AND the style faces (SpaceGrotesk-VF/JetBrainsMono-VF/PlayfairDisplay-VF/Bangers-Regular, which a themed deck's captions now use; a missing one silently falls back to DejaVu) |
| Captions show tofu boxes / □□□ (non-Latin language) | Set meta.language so render.py picks a system CJK font (zh→PingFang, ja→Hiragino, ko→AppleSDGothicNeo) | Set meta.font to an explicit .ttc/.ttf that covers the script |
| Narration mispronounced / wrong-language voice | Set meta.language; tts.py auto-picks a matching say voice (zh→Tingting, ja→Kyoko, …) when you left the English default | Set meta.voice explicitly to an installed voice for that language (say -v '?' lists them) |
Narration overruns the beat's est_seconds budget (≈ target_seconds / beats) | Tighten wording (references/narration-writing.md) | 🔴 STOP and propose splitting the dense slide |
| A/V out of sync (one slide) | Never guess timing — duration comes from ffprobe; re-run tts.py --only N | Re-render that slide with --only N |
| A/V drift across the WHOLE video (audio runs longer than the video, worse later) | Mixed audio sample rates across clips (e.g. a partial edge-tts run left some scenes as say .aiff @22050 and others edge .mp3 @24000) → the -c copy concat desyncs. render.py pins -ar 48000 -ac 1 per clip to prevent this; clear <out_dir>/.clips/ and re-render so every clip re-encodes uniformly | Regenerate ALL audio with one engine (delete audio/, re-run tts.py) so the voice is consistent too, then clear .clips/ and re-render |
step 9e critic-av (or the combined fast critic) finds an A/V issue | Read the issue (illegible/mistimed burned caption / off-theme or tofu render / player-chrome) → fix the cause (fix the page/theme, clear .clips/, re-render) → re-run critic_brief.py; the review depth decides whether a fresh critic round follows (step 9d) | A finding the rounds left open goes back to the user — one more round, or accept as-is (never on a faithfulness or sourcing finding — S3 / H1, which critic_ledger.py refuses to accept — those are fixed; A/V sync drift is not the review's to leave open either: check_av.py must exit 0 before delivery whatever the review says) |
step 1 doctor.py reports a REQUIRED dep missing (ffmpeg/ffprobe/PIL) | Install it (e.g. brew install ffmpeg, pip install pillow) before proceeding | Optional gaps (edge-tts/soffice/Chrome) only narrow the tiers — adjust the interview, don't block |
step 9 gate fails: validate.py exits non-zero before render | Read each ERROR (missing image/audio/page/file:// asset, duplicate index, absent theme.css) → fix in storyboard.json / regenerate the missing asset (run theme.py/imagegen.py/tts.py) | Re-run python scripts/validate.py <out_dir> until exit 0 before calling render.py |
step 9 gate fails: check_av.py exits non-zero after full render | Read the issue (A/V drift / non-uniform clip rates) → fix the cause (clear .clips/, regenerate audio with ONE engine, re-render) | Re-run python scripts/check_av.py <out_dir> until exit 0 before delivering out.mp4 |
keyframe_qa.py exits non-zero (BLANK page / canvas overflow / type under the floor) | Open _keyframes/scene_NN.png — BLANK → the reveal never fired (broken page / cue never resolves); OVERFLOW → shorten the text or split the beat; TYPE → read the computed size it prints (16 px = a declaration that never applied), set it larger or cut words | Re-run until exit 0; the centered-paragraph advisory never blocks |
validate.py: "only ~N% complete when the render cuts" (a connector/bar frozen mid-flight) | The element's cue fires too late for its animation-duration to finish. Set the inline duration validate prints (= remaining − 0.15s), e.g. style="animation-duration:1.1s" on that .draw path — prefer this to re-anchoring, since a connector drawn BEFORE its phrase spoils the payoff | If the shortfall is large (<60%), the beat is over-stuffed: move the anchor phrase earlier in the narration so the line still has ~1s to run after it. Confirm on _keyframes/scene_NN_shipped.png, NOT the ?p= sheet — the blind sheet always shows animations complete |
| Timed callout appears at the wrong moment / never appears | Check validate.py's cue warnings — the cue must be a phrase the narration says (with a non-edge voice the time is a text-position estimate); at ≥ 1.0 puts it exactly at clip end (invisible) | Set an explicit at fraction, or drop cue/at for a whole-slide highlight |
| Reduced-motion render flagged as static / tools still assume zoom | Set meta.reduced_motion: true in the storyboard (the CLI flag isn't persisted) and STATE the mode when dispatching critic-av — static frames are correct there, not a defect | validate.py skips its zoom warnings when the meta flag is set |
| Text trembles / steps a pixel at a time during a slow camera move, drift or reveal (remotion / HTML) | Skia snaps a moving line's baseline to whole pixels under a plain scale/translate — NOT the image tier's Ken Burns; text_safe_qa.py <out_dir> --glide names the beat and the line | Pass the moving transform through glide() (runtime/glide.ts) over its span, inside any blur/drop-shadow; the HTML reveal/float classes already carry it |
| Slide "shivers"/jitters during the zoom | The move is a float-window Lanczos resample per frame (render._kenburns_frames), jitter-clean by construction; meta.motion_ss is retired (ignored, validate warns). jitter_qa.py <out_dir> judges every image slide's tiles against the exact move | A jitter_qa finding on an image slide is a renderer defect — report it; a zoom delta > 0.20 is a lurch, not jitter (validate warns) |
| Caption is one static line per slide | Captions auto-derive from narration — split into sentence chunks timed across the slide; a single full-span entry in captions is overridden by the narration track | For custom timing, supply a multi-segment captions array |
render.py: no Chrome for an html scene | render_html errors clearly; set meta.chrome_path, or switch those scenes to the free programmatic tier (title/chart/keypoints/compare) | Install Google Chrome, then re-render |
html page renders blank / unstyled | Confirm the page links assets/html/base.css + theme.css (from out_dir) + seek.js by ABSOLUTE file:// path; no external/network assets | Open the page in a browser to debug, then re-render (the cache busts on edit) |
For anything else, read references/troubleshooting.md before guessing.
Red lights — never do this
- ❌ Render audio/video before the user signs off script/sample (honor the 🔴 checkpoints) — but
the five-beat
script_audition.pyproof is REQUIRED before that sign-off, not forbidden by it: the checkpoint is a listen, and a script nobody heard has not been checked. - ❌ Narrate from the slides alone, or invent facts/numbers — ground in the material (or a web fact-check) and stay strictly faithful (step 3).
- ❌ Skip the script critic (step 5) — the combined critic runs on every run (the 3-critic panel when step 5 calls for it, shipping only when all three PASS), and every faithfulness or sourcing finding is fixed, never cut to the top few.
- ❌ Read slide bullets aloud verbatim — write spoken narration (
references/narration-writing.md). - ❌ Guess a slide's
duration— it must come from ffprobe viatts.py. - ❌ Hand-edit
out.mp4; changestoryboard.jsonand re-render (--only N). - ❌ Tell the user to watch a file inside this skill's folder,
~/.claude, a hidden work folder or a temp directory — runscripts/deliver.py <out_dir>and give them the Desktop/Downloads path it prints. - ❌ Add callouts/emphasis boxes by default — they're OFF unless the user asks; never stack them.
- ❌ Write the OpenAI API key into the storyboard, a script, the manifest, or any persisted/
committed file — request it fresh each run, pass it only via
OPENAI_API_KEY/--key, and remind the user to rotate a key they pasted into the chat. - ❌ Let a single static frame linger (one long held image reads as sluggish) — keep cuts moving (~≤8s/scene), splitting a long scene into shorter beats rather than over-holding.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

