@officexapp/vidfarm-devcli 0.21.54 → 0.21.56

package/experimental/animated-sticker-story.md

@@ -0,0 +1,2252 @@
+---
+name: animated-sticker-story
+video_type: Animated sticker story — a narrated paper puppet theater. One parchment stage, a cast of die-cut stickers, every element moved by one GSAP timeline. Narration carries the story, subtitles stay small (TikTok / Reels / Shorts)
+checks:
+  duration_sec: 20-45       # target ~30s. Under 20 the story has no middle; over 45 the stage runs out of new things to do
+  aspect: 9:16
+  first_frame_visual: required
+  first_frame_text: required
+  text_by_sec: 0            # the loud first cue is up at frame 0 — see "The subtitle band"
+  hook_words_max: 9
+  audio: required           # narration IS the spine of this format. A silent build is a different video
+  # `captions: required` looks right and is wrong here. It asserts CAPTION LAYERS —
+  # what `vidfarm captions generate` writes — and that command pages narration into
+  # 3-5-word kinetic cues at caption scale, which is precisely the thing Rule 7
+  # forbids in this format. The band is hand-authored timed TEXT layers instead, so
+  # it can be sized (38px), weighted (500), placed (78-86%) and cut to the ACTS.
+  # The band is still mandatory — and it IS kinetic here, just colour-only. The
+  # pre-flight checklist, gate 2's EMPTY BAND check and gate 2's BAND DOMINANCE
+  # check enforce it together, and they see what this key cannot.
+  captions: optional
+  font_regime: required
+  safe_zone: required
+  # CAREFUL: `scenes` counts CLIPS, and this format is ONE STAGE. Puppets are plain
+  # children INSIDE an act clip, not clips of their own — so a 5-act, 60-sticker story
+  # reports scenes:5, not scenes:60. If qa reports scenes:40 you built forty scenes
+  # instead of one theater, and every cross-act move you wrote is fighting the clip
+  # lifecycle. See "The stage is one clip per act, and puppets are not clips".
+  scenes: 1-8
+  max_scene_sec: 12
+  max_text_cards: 4         # the loud first cue + up to 3 stamps. Subtitle cues are not cards
+  max_simultaneous_text: 2  # one sentence + one number. Never two sentences
+  max_words_per_cue: 8      # subtitles are SUBTLE here. The picture is the show
+  max_dead_air_sec: 1.5
+  max_tail_sec: 1.5
+  forbid_text:
+    - link in bio
+    - sign up
+    - free trial
+    - get started
+    - book a demo
+    - download now
+    - download the app
+    - learn more
+    - swipe up
+    - visit our website
+    - comment below
+    - follow for more
+---
+
+# Animated Sticker Story — the paper puppet theater
+
+> A public Vidfarm prompt. Read it end to end before you build. Reference template:
+> **`template_019f8aadb7cd7958b6c36e6cbb79f2d3`** — "VOX Style", 10.048s, `popularGroup: VOX Style`,
+> sourced from `x.com`. Open it with `vidfarm serve template_019f8aadb7cd7958b6c36e6cbb79f2d3`.
+
+You are building **a puppet theater out of paper**. One stage — an aged parchment surface that never
+changes. A cast of die-cut stickers that walk onto it, do the story, and leave. A narrator over the
+top. Subtitles small at the bottom, because the picture is doing the work.
+
+The reference is a 10-second Vox-style time-lapse: a food stall appears on an old map, cutout people
+walk in along dashed routes from every direction, a queue forms, the stall gets busy. No cuts. No
+footage. No text. Everything that happens, happens *as motion on one surface* — and that single
+constraint is what makes the format read as craft instead of as a slideshow with effects on it.
+
+| Ingredient | What it is | Where it comes from |
+|---|---|---|
+| 🗺 **The stage** | One full-frame parchment surface. It is the floor of every act | One generated plate, or a free paper/map texture |
+| ✂️ **The puppets** | Die-cut stickers with real alpha — figures, props, dishes, storefronts | `sticker-pack --generate` (hybrid) · `iconscout --free` (minimize) |
+| 🎞 **The rig** | One paused GSAP timeline that moves every puppet on one clock | You. This is the actual craft |
+| 🎙 **The narration** | One voice telling a story that has a turn in it | `vidfarm tts` |
+| 🔡 **The band** | Small subtitles at the bottom. Subordinate, always | `vidfarm captions generate --srt` |
+
+**The reference source was AI-generated video, and you are not going to do that.** The original
+prompt (visible on the template) is a Gemini video prompt: ten seconds of generated animation, priced
+in dollars, unrepeatable, unfixable, and un-rebrandable. This harness builds the same *look* out of
+cheap transparent stickers and free HTML motion — which costs cents, renders in seconds, and can be
+re-cut for the next client by swapping four PNGs and six lines of narration. **Buy the assets with
+AI; get the motion for $0.**
+
+## The one test — the three-way lock
+
+Three questions. **All three must be yes** or you have not got a sticker story yet.
+
+| # | Question | If no |
+|---|---|---|
+| 1 | **Silent-legible** — mute it, hide the band. Does a stranger still follow the story? | The narration is carrying the plot and the stage is decoration. Rebuild the stage |
+| 2 | **One surface** — is there a single cut to anything that is not this stage? | You made a slideshow. There are no cuts in a puppet theater |
+| 3 | **Every element is die-cut** — does anything on screen have a straight rectangular edge? | A rectangle is a photograph pasted on paper. It kills the illusion instantly |
+
+Test 1 is the one that gets skipped, and it is the whole format. **The narration is the caption of
+the picture; the picture is never the illustration of the narration.** Write the stage first, and
+then say out loud only the parts of it a viewer cannot see.
+
+Test 3 is mechanical and you can measure it: every PNG on the stage must be a snug transparent cut
+(see *The alpha has to actually be clean*). The stage plate is the only full-bleed rectangle in the
+composition, and it is the floor, not an element.
+
+---
+
+## Part 0 — who this is for
+
+**Someone scrolling who likes watching a thing get built.** Not a buyer, not a reader — a watcher.
+The format's whole appeal is that it is *satisfying*: pieces arrive, a system assembles, and it
+resolves. That is why it travels, and it is also why an ad wearing this costume works — the viewer
+stays for the assembly and takes the mechanism home with them.
+
+Before you write anything, put four lines at the top of your build log:
+
+```
+STORY:     One craving, one city, forty wasted minutes, and the turn
+WATCHER:   Someone who eats out and has had this exact evening
+OFFER:     dishcover.io — search restaurants by DISH instead of by restaurant
+THE TURN:  the map is indexed by restaurant; nobody indexes it by dinner
+```
+
+- **Register: a documentary narrator, not a marketer.** Flat, certain, past or present tense, no
+  hedging, no second-person hype. The Vox register is "here is what happened, and here is why" — and
+  it is what buys you the right to state a mechanism at the end.
+- **They watch muted first, then unmute if the stage earns it.** Which is why test 1 exists, and why
+  the subtitle band is required even though it is deliberately small.
+- **They will watch it twice.** Sticker stories get re-watched more than any other format in this
+  catalog, because there is always a puppet in the corner they missed. Put something there.
+
+---
+
+## Structural DNA — the story
+
+**Five acts, one stage, no cuts.** The reference is one act at 10s; a narrated story needs the full
+arc, and the arc is what stops a beautiful stage from being a screensaver.
+
+| Act | Seconds (of ~29) | Job | The stage |
+|---|---|---|---|
+| **1 — The want** | 0.0–3.4 | Establish one person and one specific desire | Empty stage. ONE figure enters. ONE hero object appears above them |
+| **2 — The grind** | 3.4–10.4 | The time-lapse. Effort accumulating and failing | Routes draw. Props multiply. The X stamps land. This is the act people watch |
+| **3 — The cost** | 10.4–14.4 | The honest, unflattering result | The stage goes quiet. One figure, seated, one grey object |
+| **4 — The turn** | 14.4–21.0 | The mechanism, shown. No brand name yet | The stage RE-DRAWS. The system assembles in two fast gusts |
+| **5 — The resolve + THE PROMO** | 21.0–29.4 | The want, paid — then the offer, by name, last | One route, the hero object in colour, then the wordmark stamps onto the paper |
+
+**Act 2 is the video.** It is the one the algorithm is measuring and the one people describe to their
+friends. Give it a quarter of the runtime and the largest number of moving pieces, and make it
+*visibly a time-lapse* — the same figure repeating the same failure, on a fixed cadence.
+
+**Act 4 shows the mechanism; act 5 names the offer.** The stage rearranges into the thing the offer
+does *before* the offer is mentioned, so the viewer understands the idea while they still think they
+are watching a story. Then the resolve pays the want and the name lands on the last beat. If your
+act 4 is a logo, a screenshot or a UI mock, you have broken the format — see Rule 2.
+
+### Where the promo goes — default is the END
+
+**One promo beat, and by default it is the close.** The video earns attention for 25 seconds and
+spends it in the last four; that ordering is what makes the mention feel like a payoff rather than a
+toll. The alternatives are real but each costs you something, so pick deliberately and write the
+choice in the build log:
+
+| Placement | When it is right | What it costs |
+|---|---|---|
+| **End** *(default)* | Almost always. Cold audiences, awareness plays, anything measured on saves and branded search | Some viewers leave before it. That is the trade, and it is the right one |
+| **Middle** (end of act 4) | A warm audience that already knows the category, or a retargeting cut | The re-draw stops being a story beat and starts being a demo |
+| **Start** | Only when the offer's NAME is the hook — a known brand, a launch, a sequel | You have spent frame 0, which is the most valuable second you own |
+
+**Wherever it goes, it is named ONCE.** An end promo plus a mid-roll mention is two ads in a
+30-second video, and the second one is the one people comment about.
+
+### The stage is one clip per act, and puppets are not clips
+
+This is the structural decision the whole build hangs on, and getting it backwards costs you a day.
+
+```html
+<div id="root" data-composition-id="story" data-duration="30" data-width="1080" data-height="1920">
+
+  <!-- ONE clip per ACT. Five of these, butt-cut, covering 0 → 30. -->
+  <div id="act1" class="clip" data-hf-id="act1" data-layer-kind="image" data-track-index="0"
+       data-start="0" data-duration="5" data-label="act 1 — the want">
+
+     <!-- PUPPETS ARE PLAIN CHILDREN. No .clip, no data-start, no data-duration. -->
+     <div class="rig" id="rig-her">…</div>
+     <div class="rig" id="rig-bowl">…</div>
+  </div>
+  …
+</div>
+```
+
+- **A puppet is not a scene.** Give a sticker `class="clip"` and `data-start` and the HyperFrames
+  clip lifecycle now owns its visibility — which fights every opacity and transform you write, and
+  produces the exact failure this harness's first spike shipped: puppets that exist in the DOM, are
+  `visibility:visible` and `opacity:1`, and are nowhere on screen.
+- **`vidfarm qa` counts clips as scenes.** One clip per act → `scenes: 5`, which is what the
+  `checks:` block above expects. If qa reports `scenes: 40` you built forty scenes.
+- **The act clip carries the stage plate as its own background**, so the parchment is continuous
+  across the butt cuts and no transition is needed or wanted.
+- **A puppet that must survive an act boundary belongs to the act it starts in, duplicated into the
+  next**, at exactly the position and rotation it ended on. There is no cross-clip element. Write the
+  hand-off position down; do not eyeball it.
+
+### Length
+
+`20–45s`, target **30**. Length is an output of the acts, not an input.
+
+- **Act 2 gets ~30% of the runtime.** Every other act is as short as it can be and still land.
+- **Under 20s the turn arrives before the grind has cost anything**, and act 4 reads as a bait and
+  switch rather than as relief.
+- **Over 45s and the stage runs out of new things to do.** The format's failure at length is not
+  boredom, it is *repetition* — the same three moves cycling. If you need 60 seconds, you need a
+  second stage, which means it is a different video.
+
+---
+
+## The narration — the only prose you write
+
+**One paragraph, 55–90 words, read at ~2.9 words/second.** That is the whole script. Write it before
+you source a single sticker, because the nouns in it are your shopping list.
+
+### The grammar
+
+```
+It's seven, and you know exactly what you want.
+So you check one place. Then another. Then four more.
+None of them are searchable.
+Forty minutes later you're eating something you didn't choose.
+The whole city is indexed by restaurant.
+Nobody indexes it by dinner.
+So search the dish, not the restaurant. dishcover.io. 7,502 dishes, one search.
+```
+
+- **Short declaratives.** ≤12 words a sentence, and one idea in each. The line has to fit under a
+  puppet move without either one waiting for the other.
+- **Every sentence names a noun that is on the stage.** If the narration says "four more", four
+  storefronts had better be visible. A noun in the voice with nothing on the paper is the fastest
+  way to break test 1.
+- **The turn sentence is the shortest one in the script.** "Nobody indexes it by dinner." It lands
+  in a hole in the music and it is the line people repeat.
+- **No questions, no "imagine", no "what if", no second-person hype.** "You" is fine as a
+  documentary subject ("you're eating something you didn't choose"); "you'll love" is not.
+- **Name the offer once, lowercase, in the closing lines.** The promo is a *sentence in the same
+  voice*, not a change of register: `So search the dish, not the restaurant. dishcover.io. 7,502
+  dishes, one search.` — never "check out", never "click the link", never an imperative aimed at the
+  viewer's thumb. The mechanism, the name, the number, stop.
+
+### Pace — say it fast
+
+**Generate at whatever tempo the voice gives you, then speed it up and re-measure.** A documentary
+register at natural TTS speed is *slow*, and slow is the failure this format ships when everything
+else is right: the stage is beautiful, the story is sound, and nobody finishes it.
+
+```bash
+ffmpeg -i vo/a2.mp3 -af "silenceremove=start_periods=1:start_threshold=-45dB:start_silence=0.05,\
+areverse,silenceremove=start_periods=1:start_threshold=-45dB:start_silence=0.05,areverse,\
+atempo=1.30,loudnorm=I=-16:TP=-1.5" vo/a2-t.mp3 -y
+```
+
+- **`atempo=1.30` is the number**, measured. This harness's first dishcover build ran 1.12, which
+  read as a documentary *and* read as slow — 37.4s. The same script at 1.30 is 29.4s and does not
+  read as an ad-read. Past ~1.45 the consonants smear.
+- **Trim the silence before you speed it up.** TTS pads both ends, and that padding is dead air the
+  pixel gate will call a frozen window.
+- **Cut words as well as time.** On the same build, deleting one clause from act 2 and three words
+  from act 5 bought 2.5s that no tempo change could have.
+- **Re-measure every clip after processing and paste the real numbers into the act table.** Timings
+  guessed from the pre-trim durations put the narration out of sync with the stage.
+
+### The narration is CUT to the stage, not the other way round
+
+Generate the voice in **one clip per act**, not one clip for the whole script. Then each act's audio
+can slide independently while you tune the puppets, and a re-record of act 3 does not invalidate the
+timings of acts 1, 2, 4 and 5.
+
+```bash
+# one file per act, ONE pinned voice and ONE style string across all five
+npx -y dotenv-cli -e .env -- vidfarm tts "It's seven in the evening and you know exactly what you want." \
+  --voice Leda --style "flat documentary narrator, unhurried, no smile in the voice" \
+  --out vo/a1.mp3
+```
+
+- **One voice, one style string, all five acts.** A style string that drifts act to act is audible
+  and reads as five different narrators.
+- **Leave a real hole where the stage does the talking.** The strongest beat in a sticker story is
+  ~1.2s of no narration while a set piece assembles. Write it into the script as a blank line, not
+  as an afterthought in the edit.
+- **`--engine local` is $0** once `pip install kokoro-onnx soundfile` has run (one ~340MB model
+  download). Until then it fails with an error that names the fix, and the run silently falls back
+  to a provider key. A BYOK gemini key costs a fraction of a cent per act. Both are inside budget;
+  say in the build log which one you used.
+
+---
+
+## The subtitle band
+
+**The band may be beautiful and it may be kinetic. It may never be the loudest thing on screen.**
+Those are compatible, and the way they are compatible is specific: the band is drawn in the stage's
+own palette and its motion is **colour only**. Colour reads as design; geometry reads as motion, and
+motion is the one currency the stage cannot afford to share.
+
+### It is painted from the stage's palette, not styled separately
+
+The band is not a second colour system bolted under the drawing. Every value in it already exists on
+the paper, which is what makes it look designed rather than captioned.
+
+| Property | Value | Why |
+|---|---|---|
+| Size | **34–40px** on 1080×1920 | Half the caption size of the sibling harnesses. Legible at arm's length, not dominant |
+| Weight | **500**, never 800 | 800 competes with the stage |
+| Ink | **one step lighter and warmer than the drawing's** — `#3A2E22` against a `#2A2118` stage | It sits *behind* the stage in the hierarchy without being harder to read. Identical ink makes the type feel like a drawn element competing for the same layer |
+| Highlight | **the stamp colour**, `#8C3B2E` — the exact red the X marks and stamps are drawn in | The palette already contains it, so the highlight reads as the documentary's own annotation. A brand blue or a caption yellow is an import from another video |
+| Plate | **never** — a measured paper WASH instead, when the measurement asks for one | On parchment a plate is a card (Rule 4). A wash is the paper being lighter, not an object on it |
+| Position | A fixed, flex-centred box in the lower half, **measured** by `place-text.py`, outside `.stagewrap` | Under the action, on the calmest ground available, and never dragged by a camera move |
+| Words per cue | **≤8**, one line | Two lines is a paragraph at this size |
+| Letter-spacing | `0.004em` | A hair open. Small warm type on a textured ground needs it; the headline weights do not |
+
+**Six colours in the video, and the band spends none of its own.** If you find yourself picking a
+caption colour, you have left the format — go and sample one off the stage.
+
+### Kinetic captions: the ember
+
+Kinetic is allowed, and the permitted treatment is one **ember** — a single warm highlight that
+travels the line word by word on the voice, and hands each word back to the band's ink behind it.
+
+```js
+/* colour in, colour out. That is the entire kinetic vocabulary. */
+EMBERS.forEach(([id, wordStart, wordEnd]) => {
+  tl.to("#" + id, { color: EMBER,    duration: 0.10, ease: "none" }, wordStart);
+  tl.to("#" + id, { color: BAND_INK, duration: 0.18, ease: "none" }, wordEnd);
+});
+```
+
+**The rules that keep it subordinate.** Each one is the reason a caption steals focus, and together
+they are what "kinetic but not distracting" actually means:
+
+1. **Colour and opacity only. Never geometry.** No translate, scale, rotate, blur or shadow on any
+   word, ever. A moving word is the fastest thing in the frame and the eye goes to it before it goes
+   to a walking puppet — which inverts the format in one cue.
+2. **Never animate font-weight.** It looks like colour's harmless cousin and it is geometry in
+   disguise: with a variable font, tweening the weight axis re-flows the line, so every word after
+   the active one jitters sideways. Verified on this harness's own build — it is why the ember is
+   colour-only rather than colour-and-800.
+3. **The line arrives whole.** Cross-fade the cue in and out at ≤0.18s. No word-by-word entrance, no
+   slide-up, no typewriter. The reader should be able to read ahead of the voice.
+4. **One highlight at a time, one step of change.** Active word = one colour step. Red *and* bold
+   *and* underlined *and* scaled is four steps and it is a karaoke video.
+5. **The ember never lands on the offer's name.** The brand has its own beat (the lockup); a
+   highlight on it turns a sentence into an ad-read.
+6. **The loud first cue and the lockup never animate their words.** The hook is up whole at frame 0;
+   the wordmark is stamped and static.
+
+**Gate it, don't trust it.** Appendix C's *band dominance* check measures the band strip's share of
+the video's total frame-to-frame motion. Colour-only kinetics land around 5–15%; this harness's
+dishcover build measured **9%** against a 35% ceiling. Anything geometric blows past the ceiling
+immediately, which is exactly what the check is for.
+
+### Timings come from whisper; WORDS come from the script
+
+The ember has to key off real word timings or it drifts off the voice by the third line, and
+`vidfarm stt --engine whisper` gives you word-level timestamps locally, free, in about two seconds
+per clip.
+
+```bash
+vidfarm stt vo/a2-t.mp3 --engine whisper --json   # -> words[] with start/end per word
+```
+
+⚠️ **Use whisper's TIMINGS and your script's TEXT.** Never render the transcript. On this build the
+transcriber heard *"Forty minutes"* as **"40"** — colliding with the `40 MINUTES` stamp that should
+own the numeral — and heard *"7,502"* as **"7,000"**, which would have put a wrong number on screen
+in a format whose Rule 8 is that every number is real. Zip the script's tokens onto whisper's
+timings and **fail the build if the counts differ**; the fix is to re-word the script, not to trust
+the machine.
+
+**Chunk on clauses, not on a word count.** Break at a sentence end; if a sentence runs past 8 words,
+back off to its last comma. A bare word cap produces cues like `something you didn't` / `choose.`,
+which reads as a stutter.
+
+**Delete the band cue that carries the brand** when the lockup is going to say it. Otherwise the name
+appears in the band and on the stage 0.2s apart — two mentions in one breath, which reads as an ad
+even though the script says it once.
+
+### The loud first cue
+
+**There is no separate hook card.** The first subtitle cue — and only the first — renders at
+**66px / weight 800** in the upper half, at a position `place-text.py` measures, and it holds for its
+natural duration; the band then drops to subtitle scale in the lower half for the rest of the video
+and never comes back.
+
+This buys you three things at once: `first_frame_text` is satisfied at frame 0, `max_simultaneous_text`
+stays at one sentence, and you do not spend two seconds on a title card before the story starts. It
+is also the honest version of a hook: the first thing the narrator says is the first thing you read.
+
+**The loud cue must be the whole claim.** "It's seven in the evening and you know exactly what you
+want." is a situation and it works. "Ever had this problem?" is a question and it dies.
+
+### The promo lockup
+
+The offer's name, on the last beat. **One text layer, in the stage's own ink at the stage's own
+scale — a wordmark drawn on the paper, not a badge stuck over it.**
+
+```css
+.lockup { font-family:'Montserrat'; font-weight:800; font-size:82px; color:#2A2118;
+          text-align:center; letter-spacing:-0.02em; }   /* box top: MEASURED */
+```
+
+```js
+/* it STAMPS. A promo that fades in is a title card, and a title card is a card. */
+tl.fromTo("#lockup", { scale: 1.9, rotation: -3, opacity: 0 },
+  { scale: 1, rotation: 0, opacity: 1, duration: 0.22, ease: "power4.out" }, 24.2);
+```
+
+- **The name and nothing else.** No logo, no `https://`, no button, no plate, no rule, no tagline
+  under it, no "available now". If the brand's own mark is a wordmark, you are already rendering it.
+- **Same ink as the drawing** (`#2A2118`), not the stamp red and not a brand colour. A coloured
+  wordmark on parchment is a sticker from a different video.
+- **It searches the upper half**, which the loud cue vacated 20 seconds earlier — so the closing
+  subtitle runs in the lower half at the same time and the two never share ground. Wordmark up,
+  stage in the middle, closing line down: that is the one moment two text layers are allowed, and it
+  is why `max_simultaneous_text` is 2.
+- **It holds to the last frame.** Five seconds up is normal here, and it is the one thing in the
+  video that does not need a BEAT — a wordmark that breathes looks broken.
+- **Nothing follows it.** No end card, no "follow", no second beat. The video stops.
+
+### Stamps are not subtitles
+
+A **stamp** is a display-text layer that is a number or a label — `40 MINUTES`, `4 PLACES`,
+`7,502 DISHES`. Up to three in the whole video.
+
+- **A stamp is ≤2 words or one number.** If it is a sentence, it is a subtitle and it belongs in the
+  band.
+- **A stamp lands like a rubber stamp** — see the STAMP move — and it lives **above the 60% line**,
+  so it can coexist with a subtitle without either being a second read.
+- **Every number on a stamp is real.** `7,502 dishes` and `140 restaurants` are dishcover.io's own
+  published numbers. A number invented to sound specific is the one thing a viewer can catch you on.
+
+### Font regime
+
+Two weights of ONE self-hosted family, no fallback chain. `vidfarm qa`'s `font-regime` rule errors on
+Inter / Roboto / Arial / system-ui and warns outside the regime (Montserrat, TikTok Sans, Abel,
+Source Code Pro, Yesteryear). **Montserrat 500/800** is the match for the paper look; a slab or a
+typewriter face reads as a different documentary and fights the drawn stage.
+
+**Montserrat ships as ONE variable woff2 that serves both weights** — Google's CSS returns the same
+file URL for `wght@500` and `wght@800`, so fetching "the 800" separately gets you an HTML error page
+that `@font-face` will silently ignore. Declare the range:
+
+```bash
+curl -sL "https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm459Wlhyw.woff2" \
+     -o media/fonts/montserrat-var.woff2      # 38KB, latin subset
+```
+
+```css
+@font-face{font-family:'Montserrat';font-weight:100 900;font-display:block;
+  src:url('media/fonts/montserrat-var.woff2') format('woff2')}
+```
+
+`file media/fonts/*.woff2` should say *Web Open Font Format*. If it says *HTML document*, the fetch
+404'd and your video is about to render in a system font with nothing telling you.
+
+---
+
+## Casting the puppets
+
+### The art class — one, declared before you source anything
+
+**The loudest possible failure in this format is mixed art classes**, and it is worse here than in a
+slideshow, because the pieces are on screen *simultaneously* and moving. A flat vector person walking
+past a photographic bowl is not a style choice, it is a bug that renders.
+
+| Class | What it is | Use it for |
+|---|---|---|
+| **Paper cutout** *(the reference, and the default)* | Flat, muted, hand-cut edges with a white die-cut border and a soft drop shadow | Everything. Do not mix classes; mix *subjects* |
+| **Hand-drawn mark** | Dashed route, arrow, circle, red X, check | The annotation layer only — see below |
+
+**Hand-drawn marks are punctuation, not cast.** A dashed route between two points, an X over the
+failed storefront, a circle around the one that works. They may appear alongside the cutouts and they
+should — the reference's dashed routes are what turn "people standing near a stall" into "people
+travelling to a stall". Marks are drawn in SVG, not sourced as PNGs, so they can be *drawn on* (see
+the DRAW move).
+
+### The set pieces — go big, deliberately
+
+The user brief for this format asked for large scene and landscape stickers, and it is right: a
+puppet theater needs scenery, not just actors. `vidfarm sticker-pack` supports this directly —
+**`--min-area` has a floor but no ceiling, so a whole landscape can be one sticker.**
+
+A **set piece** is any cutout occupying more than ~25% of the frame: a street block, a storefront
+row, a restaurant interior, a skyline strip, a map inset.
+
+- **A set piece enters ONCE per act and then holds.** It does not bob, it does not float, it does not
+  breathe. Scenery that idles reads as an unstable render.
+- **Only the camera may move a set piece** — the act-level scale/translate on the stage layer.
+- **It must be die-cut against the parchment.** Its own silhouette has to be visible against the
+  paper. A set piece that reaches all four frame edges is a background photo, and test 3 fails.
+- **Two set pieces on screen at once is the ceiling**, and they must not overlap silhouettes.
+- **Set pieces are the cheapest depth you get.** One street-block cutout at 40% opacity behind the
+  action, one at full opacity in front, and the stage has three planes for one extra sticker.
+
+### Sourcing, cheapest first
+
+The ladder, and stop at the first rung that answers the shot:
+
+```bash
+# 1. FREE designer stickers — no key, no account, search is free
+vidfarm iconscout "walking person side view" --style sticker --free
+vidfarm iconscout get <uuid> --format png --size 1024 --out media/stickers/walker.png
+
+# 2. FREE stock photo -> die-cut it locally for $0 (ONNX matting)
+vidfarm media image "storefront awning"
+vidfarm remove-background ./awning.jpg --out media/stickers/awning.png
+
+# 3. Art the director already owns — lift elements out of their own site
+vidfarm capture https://dishcover.io --out ./capture
+vidfarm mask ./capture/screenshot.png --crop 120,340,600,600 --out media/stickers/dish.png
+
+# 4. ONE generated SHEET per cast group — one billed image job, one art style
+vidfarm sticker-pack --generate "<the ART STYLE STRING, identical every time>" \
+  --items "walking figure in olive coat,walking figure in terracotta coat,…" \
+  --out-dir media/stickers --prefix cast
+```
+
+**Rung 4 is the hybrid default, and the unit is the SHEET, not the sticker.** One sheet holding eight
+figures costs one image job and — far more important — guarantees one art class across all eight.
+Eight separate `cutout --generate` calls cost eight times as much *and* produce eight slightly
+different styles.
+
+### The art style string is a constant. Write it down once.
+
+Every `--generate` call in the project passes the **identical** style string. Changing one word
+between sheets is how a deck acquires two art classes.
+
+```
+flat hand-cut paper-collage cutouts, Vox historical-documentary illustration style,
+muted earthy palette (warm brown, terracotta, olive, dusty teal, cream), soft drop
+shadow under each piece, simple stylized shapes, closed solidly filled outlines,
+no text, no lettering
+```
+
+Two clauses in there are load-bearing and are not decoration:
+
+- **"closed solidly filled outlines"** — an open outline lets the item's fill reach the panel edge,
+  the keyer reads that fill as plate, and the sticker comes back as a hollow ring. `sticker-pack`
+  warns about this by name (`N% see-through`).
+- **"no text, no lettering"** — a generated sign with fake words on it is the single most obvious
+  AI tell in an otherwise clean frame, and it is unfixable after the fact.
+
+### ⚠️ Generate the stickers WITHOUT shadows
+
+**Ask the model for "NO drop shadow, NO white sticker border, NO glow" and add the shadow in CSS.**
+
+```css
+.art { filter: drop-shadow(6px 10px 10px rgba(74,60,42,0.22)); }
+```
+
+This is not a style preference, it is the fix for the format's most annoying defect. A baked drop
+shadow is a *soft* edge, so on the sheet it blends with the chroma plate and comes back as a
+coloured halo that is **baked into the pixels, not into the alpha** — which means no tolerance
+setting, no key mode and no matting model removes it. On this harness's dishcover run the pink rim
+survived `--tolerance` 0.12, 0.15 and 0.18, `cutout --key-mode smart`, and a 3px alpha erode.
+
+The CSS shadow also buys you Rule 5 for free: one shadow declaration is one light direction across
+the entire cast, forever, and it scales correctly when the camera moves.
+
+### What `sticker-pack --generate` actually hands back
+
+Measured on this harness's own dishcover run, so you do not rediscover it:
+
+- **The first output is usually the whole sheet.** `cast-01-*.png` came back at 788×922 — the entire
+  keyed 3×3 grid as one "sticker", panel lines included. **Delete it.** Check every output's pixel
+  dimensions: a cast figure is ~110×240; anything ten times that is the sheet.
+- **The names are guessed, not assigned.** `--items` names the outputs in *reading order*, and the
+  model does not always fill panels in the order you asked. On the dishcover run `cast-01` and
+  `cast-05` came back sharing one name. **Open the pack and rename against the picture before you
+  place anything.**
+- **Some panels come back empty.** Two of nine on the first run, with the warning naming the cause
+  (the item touched its panel edge). Ask for 8 items when you need 6.
+- **Budget one re-roll per sheet** into the cost table.
+
+### ⚠️ When the sheet is perfect and the keyer still refuses to split it
+
+The failure that cost this harness the most time, and it looks like a generation failure when it is
+not. `sticker-pack --generate` asks for a **zoned** sheet — a colour-block grid with a *different*
+plate colour under each item — and then keys it. When the model delivers exactly that, the keyer can
+still report:
+
+```
+Zones: Panel 1 keyed 10.8% of itself — there's no plate there, i.e. the sheet isn't
+really a color-block grid, so it was re-keyed as ONE #FFFFFF plate.
+✓ prop-01-small-storefront-with-striped-awning.png (988×988, 1.4 MB)
+Note: you named 8 item(s) but 1 were cut
+```
+
+One 988×988 "sticker" out of eight items — **that is the whole sheet again.** Keying one plate
+colour cannot remove the other, so the magenta panels vanish and the blue ones survive as opaque
+rectangles, and the connected-component pass finds one blob. `--zones 3x3` did not fix it and
+`--sheet-mode flat` produced a sheet that keyed 100% of itself and yielded nothing.
+
+**Do not re-roll. Open the sheet and look at it.** If the grid is there, the art is fine and only the
+split failed — so do the split yourself. You know the layout, so it is arithmetic:
+
+```bash
+# crop the R×C grid into cells, then key each cell against ITS OWN plate colour
+./split-sheet.sh sheet.png 3 3 media/props "storefront,menu-scroll,x-stamp,…"
+```
+
+`split-sheet.sh` is in Appendix F. It insets 4% per cell so a neighbouring panel's colour never
+enters the crop, samples that cell's own corner for the plate hex, and calls `vidfarm mask --flat`.
+
+**Pick the per-cell cutter by SUBJECT, and the two do not substitute for each other:**
+
+| Cell contains | Use | What the other one does |
+|---|---|---|
+| **Flat graphic art** — an X mark, a clock, a storefront, a check | `vidfarm mask --flat "#<hex>" --tolerance 0.10` | ONNX matting reads a flat saturated plate as part of the subject and keeps it |
+| **Organic / painterly** — a bowl of food, a person, a plant | `vidfarm remove-background` (local ONNX) | a chroma key leaves the shadow halo, and `cutout --key-mode smart` ate the whole bowl |
+
+**Tolerance 0.10 is the number**, measured on the dishcover run: `0.05` leaves a visible blue rim,
+`0.18` ate a teal ribbon whose colour sat near the blue plate's hue. Which is also the plate-choice
+rule restated — never put teal art on a blue plate.
+
+### The retro-fix when a halo already shipped into your assets
+
+If the art is already generated with baked shadows, `deshalo.sh` (Appendix F) is the recovery: it
+hard-thresholds the alpha at 215 and erodes 1px, throwing away every partial-alpha pixel. That
+removed the halo completely on flat art. **Do not run it on soft, furry or glassy subjects** — the
+partial alpha there is the subject, not a defect.
+
+### The alpha has to actually be clean
+
+On a near-white parchment stage a bad key shows every defect footage would hide. Check it, don't
+trust it:
+
+```python
+# any sticker: how much of it is actually opaque?
+a = alpha_channel(png)
+print((a == 0).mean(), ((a > 0) & (a < 255)).mean(), (a == 255).mean())
+# healthy: mostly 0 or 255, a percent or two in between.
+# tens of percent "partial" = a bad key, and on paper it WILL show as a grey box.
+```
+
+Match the key mode to the shape — the same trap the greenscreen harness documents:
+
+| Art | Key mode | Why |
+|---|---|---|
+| **Hollow** — a dashed ring, a frame, an arrow outline | `--key-mode flat` | the interior never touches the frame edge, so a connectivity keyer *keeps* it and you get a filled blob |
+| **Solid** — a figure, a bowl, a storefront | `--key-mode smart` *(default)* | flat mode's soft alpha ramp eats a painted edge |
+
+`--refine` re-cuts each item with local ONNX matting (free, ~1–2s each) and is the answer for
+painterly or soft-edged art whose chroma cut looks chewed.
+
+### ⚠️ Attribution
+
+IconScout free assets and most free stock require a credit line, **and a credit line on the frame is
+brand chrome, which is banned.** Put every credit in the **post caption**. Never on the stage, never
+in a corner at 12px, never on a credits beat at the end. If a licence requires the credit to be *on
+the image*, do not use that asset — drop to matted stock or a generated sheet.
+
+---
+
+## Visual DNA
+
+### The stage
+
+**One parchment plate, full frame, and it never changes.** Sampled off the reference: a warm
+cream-beige, roughly `#E7DCC2`, with visible paper grain, faint grid lines and soft creases.
+
+- **The plate is the act clip's background**, repeated identically in every act, so the butt cuts
+  between acts are invisible.
+- **Ink is `#2A2118`**, not black. Palette is earthy and narrow: warm brown, terracotta, olive,
+  dusty teal, mustard, cream. **Six colours, total, across the whole video.**
+- **No gradients, no vignette, no blur, no glow, no glass, no cards.** The one shadow in the video is
+  the soft contact shadow under each cutout, and it comes baked into the sticker.
+- **One light direction.** If the figures' shadows fall to the lower right, so do the storefronts'.
+  Bake it into the art style string and it comes out consistent for free.
+- **No footage. Ever.** A video layer on this stage is a hole cut in the paper.
+
+### Placing the type — measure the stage, then fit the words to it
+
+**The stage art is full-bleed and stays that way.** Cropping a blank margin into it so the captions
+have somewhere to sit throws away the thing the format is for — the drawing filling the frame is the
+format. So the type gets fitted to the art, and that is a measurement, not a taste call.
+
+```
+  0%  ─── platform chrome — nothing lives here ───
+  8%  ┌──────────────────────────────────────────┐
+      │  UPPER HALF — the loud cue, then the     │
+      │  promo lockup. Position MEASURED         │
+ 46%  └──────────────────────────────────────────┘
+      │  the drawing runs edge to edge, behind   │
+      │  everything, all the way down            │
+ 66%  ┌──────────────────────────────────────────┐
+      │  LOWER HALF — the subtitle band.         │
+      │  Position MEASURED                       │
+ 88%  └──────────────────────────────────────────┘
+        platform chrome — nothing lives here
+100%  ──────────────────────────────────────────
+```
+
+**The halves are fixed; the exact position inside each half is measured.** Fixing the halves keeps
+the layout stable — a band that hops from 70% to 84% between cues is worse than a band that sits
+slightly busy. Measuring inside them is what stops the words landing on the one thing that would have
+made them unreadable.
+
+#### The two-pass build
+
+You cannot choose placement off the plate alone: the puppets move, and a strip that is calm on the
+empty map can have a walker standing in it. So build twice.
+
+```bash
+python3 build.py v001 --no-text     # 1. the stage, no captions
+python3 place-text.py v001          # 2. snapshot every cue midpoint, scan, write place.json
+python3 build.py v001               # 3. rebuild, reading the measured placement back in
+```
+
+`place-text.py` (Appendix F) snapshots the stage at the **midpoint of every cue**, scans candidate
+positions inside each zone's allowed range, and scores each by its **worst-case** variation across
+that zone's own frames — worst case, not average, because one busy frame is one unreadable cue. It
+writes `place.json`, which `build.py` reads on the next pass.
+
+#### The treatment ladder — and a wash is not a plate
+
+`vidfarm qa` calls a plate a `card-panel`, and Rule 4 bans it: a rounded slab under the words is a UI
+element pasted on a drawing, and a stroke or a text-shadow is the same defect wearing a different
+hat. What is allowed is a **paper wash** — the sheet's own colour, feathered to nothing at both
+edges, with no border, no corner, no shadow. It is not an object on the paper; it is the paper being
+lighter where the words are, the way a documentary's lower margin is.
+
+| Worst-case variation behind the type | Treatment |
+|---|---|
+| **< 14** | Bare paper. No treatment — and do not add one "to be safe" |
+| **14–20** | Light wash, `α ≈ 0.55` |
+| **20–26** | Wash, `α ≈ 0.70` |
+| **> 26** | `α ≈ 0.82`, and go back and look for a calmer position first |
+
+```css
+/* the box, at its MEASURED top. Full-bleed horizontally so the wash has no
+   left/right edge either; the text measure is set on the inner .ln. */
+background: linear-gradient(to bottom,
+  rgba(242,229,206,0)    0%,     /* ← the PLATE's own paper, sampled, never invented */
+  rgba(242,229,206,0.82) 26%,
+  rgba(242,229,206,0.82) 74%,
+  rgba(242,229,206,0)   100%);
+```
+
+**Sample the paper colour off the plate.** `place-text.py` takes the sheet's 93rd-percentile
+brightness, so the wash is the paper's own cream rather than a white slab. An invented `#FFF` at 80%
+reads as a plate no matter how well it is feathered.
+
+**Boxes are fixed-height and flex-centred, not top-anchored**, so a one-line cue and a two-line cue
+share an optical centre instead of the band creeping down the frame:
+
+```css
+.band, .loud, .lockup { display:flex; align-items:center; justify-content:center }
+.ln                   { display:block }      /* ← see below */
+```
+
+⚠️ **Put the words in ONE inner `.ln` child.** Make the per-word spans direct flex items and the
+browser drops the whitespace text nodes between them — `Soyoucheckoneplace.` — *and* refuses to wrap
+the line, so a long cue is clipped at the box edge. Both failures render, export and pass every DOM
+check. One wrapper element fixes both.
+
+#### How gate 2 grades it
+
+A wash does not *brighten* the strip — on parchment the paper is already near-white, and the 75th
+percentile measures 228 with or without it. What a wash does is **flatten** it. So gate 2 compares
+variation on frames carrying a cue against frames without one, and a drop of more than 4 is the
+signature of a treatment actually being present. On the dishcover build: **23 bare → 19 washed**,
+which passes; with no wash the same band failed at 23.
+
+**Detect a caption by dark AREA, not by the darkest pixel, and sample it fine.** At a 64×8 downsample
+a 38px stem averages away into the paper and every frame reads as empty; at 540×96 cue frames measure
+1.5–2.8% dark against 0.5–1.3% for gaps. Min-luma alone does not work either, because the drawing
+puts thin dark marks in the strip too — a route line, a contact shadow — and one dark pixel is not a
+caption.
+
+### Scale is the depth system
+
+There is no perspective on paper. Scale is the only depth cue you have, so it has to be disciplined.
+
+- **A near figure is ~240px tall; a far figure is ~110px.** Pick two sizes and one mid, and use only
+  those three across the whole video.
+- **Scale tracks the horizon.** A figure at 68% of the frame is near and big; one at 40% is far and
+  small. A big figure high on the stage is the single most common "something is wrong and I can't
+  say what" defect in this format.
+- **Relative scale between subjects must be plausible.** A bowl is not the size of a person. This
+  breaks every time two stickers came from different sheets — which is the other reason for the
+  one-sheet-per-group rule.
+
+---
+
+## Motion DNA — the puppet theater
+
+This is the section the format lives or dies in. Everything above is casting; this is the show.
+
+### Pick the engine once: GSAP, on one paused timeline
+
+| Engine | Verdict for this format |
+|---|---|
+| **GSAP 3.14.2 + MotionPathPlugin** | ✅ **Use this.** HyperFrames' default runtime adapter, seek-driven and deterministic. `MotionPathPlugin` is exactly the "figures travel along dashed routes" primitive, and `stagger` turns one tween into a crowd of thirty. One paused timeline = one clock, which is what a puppet theater *is* |
+| **CSS `@keyframes`** *(via `vidfarm keyframes --preset`)* | ✅ **The cost-saving fallback, and the only option that survives the web editor.** Script-free, previews and renders identically. No path following, no stagger — you hand-write N animations and you will not attempt act 2 with it |
+| **Anime.js** | ⚠️ Works, but you would reimplement motion paths and lose the default adapter. No reason |
+| **Lottie** | ⚠️ A Lottie file is *someone else's finished animation*. You cannot cast your own stickers into it. Legitimate for ONE decorative loop — steam off a bowl, a spinning sun — and nothing else |
+| **Three.js / TypeGPU** | ❌ 3D on a paper stage. Paper is two-dimensional by definition |
+
+**Vendor GSAP into the project; do not rely on the CDN at render time.**
+
+```bash
+mkdir -p vendor
+curl -sL -o vendor/gsap.min.js              https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js
+curl -sL -o vendor/MotionPathPlugin.min.js  https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/MotionPathPlugin.min.js
+```
+
+GSAP 3.14.2 and every plugin including MotionPath are free to use. Two files, 95KB, and the render
+stops depending on a network fetch — which matters because a CDN miss at frame 300 renders a
+composition with no motion in it *and exits 0*.
+
+### The HyperFrames contract, in five lines
+
+```html
+<script src="vendor/gsap.min.js"></script>
+<script src="vendor/MotionPathPlugin.min.js"></script>
+<script>
+  gsap.registerPlugin(MotionPathPlugin);
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+  /* … every move in the video … */
+  window.__timelines["story"] = tl;   // key === data-composition-id on #root
+</script>
+```
+
+- **The registry key must equal `data-composition-id`.** No match, no motion, no error.
+- **Never `tl.play()`.** HyperFrames seeks the timeline; playing it fights the renderer.
+- **Build the timeline synchronously.** Not in a timer, a promise, or a load handler.
+- **Finite repeats only.** `repeat: -1` on a 30s render is undefined behaviour. Compute the count:
+  a 0.26s bob over a 3.2s walk is `repeat: 11`.
+- **Render duration comes from `data-duration` on `#root`**, not from the timeline's length. Do not
+  pad the timeline to match.
+- **Animate transforms and opacity.** `x`, `y`, `scale`, `rotation`, `opacity`, plus `strokeDashoffset`
+  on the SVG marks. Never `top`/`left`/`width`/`height` — they reflow, and on a stage with sixty
+  children a reflow per frame is a slow render for no reason.
+
+⚠️ **A scripted composition is desktop-only.** `vidfarm lint` warns
+`scripts_stripped_on_save`: the web editor strips `<script>` on save as a stored-XSS defence. This
+composition is authored and rendered locally (`vidfarm serve` / `vidfarm hf render`) and it must not
+be round-tripped through the browser editor, or every move in it is silently deleted. Say so in the
+handoff.
+
+### The puppet rig — three nodes, and this is not optional
+
+Every puppet is three nested elements. It looks like ceremony and it is the difference between a rig
+you can direct and one where every new move breaks the last one.
+
+```html
+<!-- TRAVEL node: zero-size, anchored at the canvas origin. Owns motionPath. -->
+<div class="rig" id="rig-her">
+  <!-- BOB node: zero-size. Owns the walk bounce, the breath, the nod. -->
+  <div class="bob">
+    <!-- ART: the sticker, hung off the rig by its FEET. Owns pop-in scale + rotation. -->
+    <img class="art" src="media/stickers/cast-02-walker-olive.png"
+         style="left:-55px; top:-240px; width:110px">
+  </div>
+</div>
+```
+
+```css
+.rig { position:absolute; left:0; top:0; width:0; height:0 }
+.bob { position:absolute; left:0; top:0; width:0; height:0 }
+.art { position:absolute; transform-origin:50% 100% }
+```
+
+**Three nodes because three transforms must not fight.** Travel, bob and pop are three separate
+tweens on three separate properties of what would otherwise be one element — and GSAP resolves them
+onto one matrix, so the last one written wins and your walk cycle cancels your walk.
+
+⚠️ **The trap that cost this harness its first spike: `motionPath: { align: "self" }`.** With
+`align: "self"`, GSAP treats the path as *relative to the element's current position* — so a path
+starting at `M 60 1780` moves the puppet 60 right and 1780 **down from wherever it already is**, and
+a puppet at `top:0` ends up 190px above the frame. Every property reads
+`visibility:visible, opacity:1` and nothing is on screen.
+
+**The fix is the rig:** the travel node is zero-size at the canvas origin `(0,0)`, and the motionPath
+tween carries **no `align` and no `alignOrigin` at all**. GSAP then writes the path's own numbers
+straight into the node's translate — so **path coordinates ARE canvas coordinates**, `M 540 1200`
+means the point 540px right and 1200px down on the 1080×1920 stage, and you can read a route off a
+still with a ruler. The art hangs off the rig by its feet (`left: -width/2; top: -height`), so the
+path traces where the puppet *walks*, not where its chest is.
+
+⚠️ **The same trap, second form: a travelling rig must have `left:0; top:0`.** It is tempting to
+park every puppet with `style="left:300px; top:1500px"` and let the ones that walk start from there.
+They do not. `left`/`top` is layout and the motionPath translate is a transform, so the browser
+**adds** them: a rig at `left:300; top:1500` on a path starting `M 300 1560` renders at
+`(600, 3060)`, which is off the bottom of a 1920px stage. It reads `opacity:1`, `visibility:visible`,
+`display:block`, and it is not on screen. This harness's first dishcover build shipped exactly that
+and the walkers were invisible in acts 2 and 5. **Two constructors, and never one:**
+
+| Puppet | Position from | Constructor |
+|---|---|---|
+| Never travels — scenery, a prop, a seated figure | `left`/`top` | `puppet(id, src, w, h, x, y)` |
+| Travels on a motionPath | the path's first point | `walker(id, src, w, h)` — `left:0; top:0` |
+
+### The seven moves
+
+Every motion in this format is one of these seven, or a stack of two of them. If you are writing an
+eighth, you are probably about to write something that reads as a slideshow effect.
+
+**1. ENTER — paper lands, it does not fade.**
+
+```js
+tl.fromTo("#rig-her .art",
+  { scale: 0, opacity: 0 },
+  { scale: 1, opacity: 1, duration: 0.42, ease: "back.out(1.6)" }, 0.3);
+```
+
+`transform-origin: 50% 100%` means it grows up out of the floor. `back.out` is the paper-weight
+overshoot; `power2.out` reads as digital. **Never cross-fade a puppet in** — a 50%-opacity sticker
+is a ghost, and paper is opaque.
+
+**2. WALK — travel plus bob, on two nodes.**
+
+```js
+const t0 = 0.8;
+tl.to("#rig-her", {                         // TRAVEL: absolute canvas coords, no align
+  motionPath: { path: "M 120 1620 C 260 1440 340 1180 500 1010" },
+  duration: 3.2, ease: "none"
+}, t0);
+tl.to("#rig-her .bob", {                    // BOB: 11 finite half-cycles over 3.2s
+  y: -14, duration: 0.26, ease: "sine.inOut", repeat: 11, yoyo: true
+}, t0);
+```
+
+`ease: "none"` on travel: a person crossing a map walks at a constant speed, and an eased walk reads
+as a slide. Bob amplitude **12–16px on a 240px figure**; more is a cartoon hop. To turn a figure
+around, `scaleX: -1` on the art node at the moment it changes direction — zero duration, not a tween.
+
+**3. CROWD — one tween, N puppets, `stagger`.**
+
+```js
+tl.fromTo(".crowd .art",
+  { scale: 0, opacity: 0 },
+  { scale: 1, opacity: 1, duration: 0.4, ease: "back.out(1.5)",
+    stagger: { each: 0.06, from: "random" } }, 6.0);
+```
+
+This is the reference's whole third act in five lines. **Cap the group so the arrival reads as ONE
+beat: `count × each ≤ ~0.6s`.** Thirty figures at 0.06 is 1.8s and reads as a slow drip; thirty at
+0.02 is one gust of paper, which is the effect you want. `from: "random"` is deterministic in GSAP
+(it is an ordering, not `Math.random()`), so it is render-safe.
+
+**4. BEAT — the puppet's own small life.**
+
+```js
+tl.to("#rig-her .bob", { rotation: 2.5, duration: 0.9, ease: "sine.inOut",
+                         repeat: 3, yoyo: true, transformOrigin: "50% 100%" }, 14.4);
+```
+
+A slow sway, a breath, a head-shake. **This is what stops act 3 looking like a frozen render**, and
+it is the move first-pass builds always forget. Rule: **no puppet on screen for more than 2.0s
+without a BEAT.** The pixel gate in Appendix C measures exactly this.
+
+⚠️ **Amplitude, measured.** A ±2.4° sway on a 190px figure is **too small to register** — it is
+under the pixel gate's 0.2%-of-frame threshold, and it is also under a viewer's. This harness's
+first dishcover build used 2.4° everywhere and gate 2 reported four frozen windows totalling 14.7s
+on a video where every one of those puppets was, technically, animating. **±3.6° plus a 9px rise is
+the floor**; a hero prop wants 4.5–6° and 13–18px.
+
+⚠️ **A BEAT must FILL its hold, not punctuate it.** `repeat: 3` on a 0.9s half-cycle is 3.6s of
+life, and if the puppet is on screen for 5s the last 1.4s are frozen. Size the repeat from the span:
+
+```js
+const IDLE = (sel, at, span, o) => {          // a BEAT sized to fill a hold
+  o = o || {}; const half = o.half || 1.05, n = Math.max(1, Math.round(span / half));
+  tl.to(sel + " .bob", { rotation: o.deg || 3.6, duration: half, ease: "sine.inOut",
+    repeat: n, yoyo: true, transformOrigin: "50% 100%" }, at);
+  tl.to(sel + " .art", { y: -(o.rise || 9), duration: half * 0.86, ease: "sine.inOut",
+    repeat: Math.max(1, Math.round(span / (half * 0.86))), yoyo: true }, at + 0.2);
+};
+```
+
+The two tweens are deliberately on different nodes and slightly different periods, so the sway and
+the rise drift out of phase and the idle never looks like a metronome.
+
+⚠️ **The quiet act needs ambient life, not a bigger idle.** Act 3 has one figure and nothing
+happening, which is the point — so the fix is not to make her wobble harder, it is to **walk two
+background figures across behind her**. Two `walker`s and two motion paths bought act 3 its life in
+the dishcover build, and they cost nothing because the cast sheet was already paid for.
+
+**5. STAMP — a mark lands with weight.**
+
+```js
+tl.fromTo("#stamp-x",
+  { scale: 2.4, opacity: 0, rotation: -9 },
+  { scale: 1, opacity: 1, rotation: -3, duration: 0.18, ease: "power4.out" }, 8.4);
+```
+
+0.18s and `power4.out` — fast in, hard stop. That is a rubber stamp. Anything slower is a fade and
+carries no impact. Land the sound effect on the same frame or drop the sound entirely.
+
+**6. DRAW — the route appears.**
+
+The dashed routes are the reference's signature and they are SVG, not PNG, so they can be *drawn*:
+
+```html
+<svg class="marks" viewBox="0 0 1080 1920" style="position:absolute;inset:0;overflow:visible">
+  <path id="route1" d="M 120 1620 C 260 1440 340 1180 500 1010"
+        fill="none" stroke="#2A2118" stroke-width="4" stroke-opacity="0.45"
+        stroke-dasharray="14 16" stroke-linecap="round"
+        pathLength="1000" style="stroke-dashoffset:1000"/>
+</svg>
+```
+
+```js
+tl.to("#route1", { strokeDashoffset: 0, duration: 1.1, ease: "power2.inOut" }, 0.8);
+```
+
+**`pathLength="1000"` is what makes this reliable.** It normalises the path's length so the initial
+`stroke-dashoffset` is a number you wrote rather than one you had to measure with
+`getTotalLength()` — which is a DOM read, which is exactly the kind of thing that behaves
+differently under a seek than under playback.
+
+**Use the same `d` string for the route and for the walker's motionPath.** One source of truth: the
+line drawn is literally the line walked, and they cannot drift apart.
+
+A menu unrolling, a banner dropping, a bar filling — same family, different property:
+
+```js
+tl.fromTo("#menu", { scaleY: 0 }, { scaleY: 1, duration: 0.5, ease: "power2.out",
+                                    transformOrigin: "50% 0%" }, 5.2);
+```
+
+**7. CAMERA — the stage moves, once per act at most.**
+
+```js
+tl.to("#act2 .stagewrap", { scale: 1.18, x: -60, y: -140,
+                            duration: 2.4, ease: "power1.inOut" }, 9.0);
+```
+
+Put a `.stagewrap` div inside the act clip holding the plate and every puppet, and scale *that*. One
+move per act, **never during a subtitle cue's first 0.4s** (the viewer is reading; moving the world
+under them costs you the line), and never more than `scale: 1.35` — past that the parchment's grain
+resolves into mush and the paper illusion goes with it.
+
+### Choreography — the rules that make it read as one theater
+
+- **One thing is the subject at any moment.** Sixty stickers may be on stage; exactly one is *doing
+  the sentence*. Everything else is BEAT-level idle. A frame where four things start moving at once
+  is a frame nobody can read.
+- **Motion has to overlap the narration, not follow it.** Start the move ~0.25s BEFORE its line. The
+  eye is faster than the ear and a picture that arrives after its words feels like lag.
+- **Use at least three easings across the video.** `none` for travel, `back.out` for arrivals,
+  `power4.out` for stamps, `sine.inOut` for idles. One easing everywhere is the machine tell.
+- **Nothing crosses a butt cut mid-move.** A move ends inside its act. Hand-offs are positional, not
+  motional.
+- **Exits matter as much as entrances.** A puppet that is simply not there in the next act reads as
+  a dropped frame. Walk it off, or shrink it out with the inverse of its ENTER.
+
+### Cost-saving mode: the CSS fallback
+
+When the composition must round-trip through the web editor, there is no script, so there is no
+timeline. You get the `vidfarm keyframes` preset vocabulary and hand-written `@keyframes`:
+
+```bash
+vidfarm keyframes ./work --layer walker-1 --preset slide-in-left --duration 1.2
+vidfarm keyframes ./work --layer bowl     --preset pop-in
+vidfarm keyframes ./work --layer stall    --preset float
+vidfarm keyframes ./work --layer arrow --keyframes \
+  '[{"offset":0,"opacity":0,"scale":2.2},{"offset":1,"opacity":1,"scale":1}]'
+```
+
+What you lose, stated plainly so nobody promises otherwise: **no motion paths** (walks become
+straight-line slides), **no stagger** (a crowd is N hand-written animations), and **no shared clock**
+(each layer's animation is relative to its own clip). ENTER, STAMP, and a straight-line WALK all
+survive; act 2 as specified does not. **Build the CSS version as a 3-act, 20s story with straight
+routes** rather than a degraded 5-act one.
+
+---
+
+## Audio DNA
+
+**Narration is required. The bed is optional and quiet. There are no sound effects unless there are
+at least four of them.**
+
+| Track | Level | Source |
+|---|---|---|
+| Narration | 1.0 | `vidfarm tts`, one clip per act, laid with `place --kind audio` |
+| Music bed | **0.12–0.18** | `vidfarm media bgm "<mood>"` — Openverse, CC/CC0, keyless, $0 |
+| SFX | 0.4–0.6 | `vidfarm media sfx` — only on STAMP and set-piece landings |
+
+```bash
+vidfarm place ./work --src ./vo/a1.mp3 --kind audio --at 0    --volume 1.0
+vidfarm place ./work --src ./vo/a2.mp3 --kind audio --at 5.0  --volume 1.0
+vidfarm place ./work --src ./media/bed.mp3 --kind audio --at 0 --volume 0.15
+```
+
+- **Measure the mix, do not vibe it.** `ffmpeg -i out.mp4 -af volumedetect -f null -` — speech ~12–15
+  dB over the bed, peak below 0 dBFS.
+- **One sound effect is worse than none.** A single stamp thud in a 30s video reads as a glitch. Either
+  every stamp and every set piece lands with a sound, or the video is narration and bed only.
+- **The bed never drives the cut.** Puppet timings come from the narration and the story. If you find
+  yourself moving a walk to hit a downbeat, you are making a music video.
+
+---
+
+## The rules
+
+Every rule has its reason attached. A rule without its reason gets argued away by the next agent that
+reads this file.
+
+### Rule 1 — one stage, no cuts, no footage
+
+Five butt-cut act clips share one identical parchment plate, so no viewer can see a cut. A crossfade,
+a whip, a stock clip or a second background makes it a slideshow with a paper theme, and the entire
+value of the format — that it looks like one continuous handmade thing — is gone in one frame.
+**Enforced:** `transitions list` returns empty; `vidfarm qa` reports one canvas.
+
+### Rule 2 — the turn is a re-draw, and the promo is a wordmark on the last beat
+
+Act 4 states the mechanism by *rearranging the stage into it* — no logo, no screenshot, no UI mock,
+no pricing, no button, and no brand name yet. Act 5 pays the want and then names the offer once, in
+the narration and as one wordmark on the paper. **Default placement is the end**; middle and start
+are allowed variants with the costs listed under *Where the promo goes*.
+
+Two failures this rule exists to stop, and they are opposite. Showing the product in act 4 converts
+19 seconds of goodwill into an ad the viewer has already decided to leave. Never naming the offer at
+all makes a beautiful video that sells nothing — which is the more common one among agents trying to
+be tasteful. **Show the mechanism, then say the name. Once, last, plainly.**
+
+### Rule 3 — silent-legible or rebuild
+
+Mute the video and hide the band. If the story is gone, the narration was carrying the plot and you
+built a podcast with pictures. This is test 1, it is the format, and it is worth the rebuild.
+
+### Rule 4 — everything is die-cut
+
+One rectangle in the composition: the stage plate. Every other element has its own silhouette against
+the paper. A pasted photo, a screenshot, a chart, a card, a rounded panel — all the same defect.
+
+### Rule 5 — one art class, one palette, one light direction
+
+Six colours. One style string across every generated sheet. Shadows all fall the same way. A machine
+assembles a stage from four sources and it looks like a stage assembled by a machine from four
+sources.
+
+### Rule 6 — no puppet holds still for more than 2 seconds
+
+A BEAT — a sway, a breath, a nod — on anything on screen. Scenery is exempt and is the *only*
+exemption. A stage where nothing idles reads as a frozen render, and a frozen render passes every
+duration, frame-count and audio-hash check there is.
+
+### Rule 7 — subtitles stay subordinate
+
+34–40px, weight 500, one line, ≤8 words, in the band at 78–86%. Exactly one cue may be loud, and it
+is the first one. The moment the type is the most interesting thing on screen, you have built a
+kinetic-caption video with wallpaper.
+
+### Rule 8 — every number is real
+
+`7,502 dishes`, `140 restaurants`, `40 minutes`. Stamps are the most believed thing on the stage
+because they look official. A number invented to sound specific is the one claim a viewer can catch
+you on, and a viewer who catches one stops believing the rest.
+
+### Rule 9 — credits and bait live in the post caption
+
+Attribution on the frame is brand chrome. The comment prompt, the save prompt and the follow prompt
+belong in the caption where the platform expects them. The video ends on the offer's NAME, which is a
+statement, not an ask — nothing on the stage ever tells the viewer to tap, follow, save or comment.
+
+### Rule 10 — production floor
+
+1080×1920, 30fps, 20–45s, one paused GSAP timeline registered under `data-composition-id`, GSAP
+vendored locally, `data-duration` on `#root` equal to the act sum, finite repeats, no script
+round-trip through the web editor.
+
+---
+
+## Cost
+
+### `hybrid` — the normal mode for this format
+
+The brief for this harness allows **$1 per video and asks for $0.50 or less.** The measured build
+lands well under both, because **the unit of spend is the SHEET, not the sticker.**
+
+| Ingredient | How | Cost |
+|---|---|---|
+| Stage plate | `vidfarm generate image --aspect-ratio 9:16` — one parchment map | ~$0.05 |
+| Cast sheet | `sticker-pack --generate`, 8 figures, ONE job | ~$0.05 |
+| Prop sheet | `sticker-pack --generate`, 8 props, ONE job | ~$0.05 |
+| Hero sheet | `sticker-pack --generate`, 6 dishes/products, ONE job | ~$0.05 |
+| One re-roll | budget it; you will use it | ~$0.05 |
+| Narration | `vidfarm tts` × 5 acts, BYOK gemini | <$0.01 |
+| Subtitles | `vidfarm captions generate --srt` | $0 |
+| Music bed | `vidfarm media bgm` (Openverse, keyless) | $0 |
+| Motion | GSAP, hand-authored | $0 |
+| Render | `vidfarm hf render` local | $0 |
+| **Total** | **4–5 image jobs** | **~$0.20–0.30** |
+
+**Measured on the dishcover build:** 5 billed image jobs (cast sheet, prop sheet, dish sheet, one
+prop re-roll that failed to key, one parchment stage) and 7 narration clips on a BYOK gemini key —
+**~$0.25**, against a $1.00 ceiling and a $0.50 target. The re-roll is the honest overhead; budget
+it rather than pretending sheets land first time. Everything else — keying, splitting, matting,
+subtitles, motion, render — was local and free.
+
+**The sheet count is the budget.** Four sheets is the number and six is the ceiling. If you need a
+seventh, the story has too many nouns in it — which is a script problem, not a budget problem, and
+cutting a noun will improve the video as well as the invoice.
+
+**Where the money would leak if you let it:** one `cutout --generate` per sticker (30 jobs, ~$1.50,
+and 30 art classes), or a cloud render (~$0.01–0.10 for output identical to the free local one), or
+generated video for a beat HTML motion does for nothing.
+
+### `minimize` — the whole stage at $0
+
+| Ingredient | Free route |
+|---|---|
+| Stage plate | `vidfarm media image "old parchment paper texture"` (Openverse/Pixabay) placed full frame |
+| Cast + props | `vidfarm iconscout "<noun>" --style sticker --free` — designer transparent PNGs, no key needed |
+| Photo cutouts | `vidfarm media image` → `vidfarm remove-background` (local ONNX) |
+| The client's own art | `vidfarm capture <url>` → `vidfarm mask --crop` per element |
+| Narration | `vidfarm tts --engine local` (Kokoro-82M, after `pip install kokoro-onnx soundfile`) |
+| Everything else | already free |
+
+**The honest cost of `minimize` is the art class, not the money.** IconScout free assets come from
+different designers, so a free cast is a mixed class by construction — which Rule 5 forbids. Three
+mitigations, in order:
+
+1. **Search the pack, not the noun.** Find one asset you like, then pull its whole family — one
+   designer's set is one class.
+2. **Unify in CSS.** One identical `filter: drop-shadow(...)` and one `saturate()`/`sepia()` pair
+   applied to `.art` pulls a mixed set into one palette. It is not as good as one sheet and it is
+   dramatically better than nothing.
+3. **In `minimize` + `interactive`, rung 4 is free.** `vidfarm handoff image` mints the sheet prompt,
+   the user runs it in a free web generator, `vidfarm sticker-pack` splits the result locally. Free
+   frontier image models are usually better per image than an API budget buys, so this is frequently
+   the *best-looking* rung, not the compromise one.
+
+**Claude Code has no image model.** `vidfarm agent-image` is genuinely free custom art on Antigravity
+/ Gemini CLI / Codex; in a Claude session it is not available. Use the handoff rung and say so rather
+than pretending.
+
+---
+
+## Bulk generation
+
+The rig is the reusable part. Once one story is built, the tenth is a manifest and a re-record.
+
+- **Hold the stage, the cast and the rig; vary the STORY.** Same parchment, same eight figures, same
+  seven moves, new narration and new hero object. That is a batch.
+- **The hero sheet is the only thing that must be re-generated per story** — the dish, the product,
+  the object the want is about. One image job per variant, ~$0.05.
+- **Acts 4 and 5 may repeat verbatim across a campaign.** They are the product's mechanism and its
+  name, and neither improves by being reworded. It does not
+  improve by being reworded. Holding it constant also makes it the clean variable when you want to
+  test it.
+- **Vary one thing per batch.** Same story with five different act-1 wants teaches you which craving
+  sells. Same want with five different act-4 phrasings teaches you which mechanism lands. A batch
+  that changed both teaches you nothing.
+- **`vidfarm dedupe` before a RE-post**, not before a first post.
+
+Sizing a round, capacity and the ledger belong to `vidfarm experiment`, not to this file.
+
+---
+
+## Quality gates — what is ENFORCED, and by what
+
+| Gate | Tool | What it can actually see |
+|---|---|---|
+| **0. Structure** | `vidfarm lint ./work` | Composition contract, clip timing, track indices, the `scripts_stripped_on_save` warning |
+| **1. Composition** | `vidfarm qa ./work --harness ./experimental/animated-sticker-story.md` | The DOM: font regime, slop, safe zone, frame 0, the `checks:` block |
+| **2. The pixels** | `python3 story-qa.py ./work/out.mp4` *(Appendix C)* | Frozen puppets, stage drift, an empty subtitle band, a popcorn frame, and whether the captions have taken the spotlight |
+| **3. The sequence** | **You**, on `stills/contact-sheet.png` | Whether it reads as one theater. Nothing else can see this |
+| **4. The story** | **You**, cold, muted | Whether it is worth watching. No tool has an opinion here |
+
+Gates 0 and 1 are free and instant and never look at a pixel. **Gate 2 exists because this format's
+signature failure is invisible to gates 0 and 1 and to the agent that built it**: a composition where
+the timeline never registered, or a puppet whose tween silently cancelled, renders a beautiful
+static image for 30 seconds and passes duration, frame-count and audio-hash checks.
+
+### Findings that are EXPECTED on this format — do not "fix" them
+
+Record your answer once and move on; chasing either one damages the video.
+
+- **`scripts_stripped_on_save` (gate 0).** Correct and unavoidable. This composition is desktop-only
+  by design. Note it in the handoff and never open the project in the web editor.
+- **`missing_track_index` on puppets.** Only clips need `data-track-index`. If lint reports it for a
+  puppet, that puppet is a clip and you have made the structural mistake this harness opens with —
+  that one IS a real finding.
+- **Low `scenes` count on `vidfarm qa`.** Five acts reports `scenes: 5` for a video with sixty
+  animated elements. That is correct. It is one stage.
+- **`band motion share N%` (gate 2).** Informational, not a finding. Under 15% is where colour-only
+  kinetics land; the check only fails past 35%.
+- **`SUBTITLE BAND is inked in 100% of samples` (gate 2).** The check is calibrated for formats where
+  the band should rest. This one is narrated end to end by design, so the band is up almost
+  continuously and the warning fires on a correct build. Rule 7 governs the band's *size*, not its
+  duty cycle. Leave it.
+- **`REVISION LIMIT REACHED` from `vidfarm qa`.** The limit is 1 by design, to stop an agent looping.
+  A format this mechanical genuinely needs a few passes — re-run with `--max-revisions 4`, and once
+  that budget is spent, take the hint and ship.
+
+### The other failure this format ships: type on the drawing
+
+Captions parked over the map are the complaint every viewer can feel and nobody can articulate —
+"hard to read", "messy", "the text is in the way". It is never fixed by restyling the type, and it is
+never fixed by cropping the art — **measure where the drawing is quietest, put the words there, and
+lay a feathered paper wash under them if the measurement asks for one.** Two-pass build, treatment
+ladder, both above. Gate 2's *band readable* check is the backstop.
+
+### The failure this format actually ships
+
+**A composition that renders a still.** In order of how often it happens:
+
+1. `window.__timelines` key does not match `data-composition-id`. No error, no motion.
+2. `motionPath: { align: "self" }` — every puppet is off-canvas, every computed style says visible.
+3. A puppet given `class="clip"` — the clip lifecycle owns it and your transforms are overwritten.
+4. A CDN GSAP fetch that failed at render time. Vendored files make this impossible.
+
+All four render cleanly, exit 0, and produce a file of the right length. **Run gate 2 or you will
+ship one.**
+
+---
+
+## Pre-flight checklist
+
+Run this before you build, and answer it honestly after. An unchecked box is a rewrite, not a fix in
+the edit.
+
+**The story**
+
+- [ ] The four build-log lines are written: STORY, WATCHER, OFFER, THE TURN.
+- [ ] Five acts exist, act 2 is the longest, and the whole thing is 20–45s.
+- [ ] Muting the video and hiding the band leaves a story a stranger can follow.
+- [ ] There is a real, unflattering cost in act 3 — not a mild inconvenience.
+- [ ] The turn is a mechanism, not an outcome, and it is stated once.
+
+**The narration**
+
+- [ ] 55–90 words, one paragraph, ≤12 words a sentence.
+- [ ] Every noun in the script is a sticker on the stage.
+- [ ] The offer is named once, lowercase, in the closing lines — and the placement (end / middle /
+      start) is written in the build log with its reason.
+- [ ] The promo is a wordmark in the stage's ink: no logo, no URL, no button, no plate, no tagline.
+- [ ] Nothing follows the promo. No end card, no follow prompt, no second beat.
+- [ ] There is at least one deliberate ~1.2s hole where the stage talks alone.
+- [ ] One voice and one style string across all five act clips.
+
+**The stage**
+
+- [ ] One parchment plate, identical in every act clip. No cuts, no transitions, no footage.
+- [ ] Six colours or fewer in the whole video; one ink; one light direction.
+- [ ] The horizon sits at 55–70% and does not move between acts.
+- [ ] The two-pass build was run: `--no-text` → `place-text.py` → rebuild. Placement came from
+      `place.json`, not from taste.
+- [ ] The stage art is still FULL-BLEED. Nothing was cropped to make room for type.
+- [ ] Where the measurement asked for a treatment, it is a feathered paper wash in the plate's own
+      sampled colour — never a plate, a stroke or a text-shadow.
+- [ ] Nothing rests in the top 8% or the bottom 12%.
+- [ ] Every cue box is fixed-height and flex-centred, with the words in one inner `.ln` child.
+- [ ] At least one set piece over 25% of frame, die-cut, entering once and then holding.
+
+**The puppets**
+
+- [ ] One art class, declared in the build log before anything was sourced.
+- [ ] One art style string, reused verbatim on every `--generate` call.
+- [ ] The whole-sheet artifact was deleted and every sticker renamed against the picture.
+- [ ] Every sticker's alpha is mostly 0-or-255. No grey halo on the paper.
+- [ ] Three sizes only; scale tracks the horizon; relative scale between subjects is plausible.
+- [ ] Every credit is in the post caption. Nothing attributive is on the stage.
+
+**The rig**
+
+- [ ] GSAP is vendored into `vendor/`, not fetched from a CDN at render time.
+- [ ] `window.__timelines["<id>"]` matches `data-composition-id` exactly.
+- [ ] Every puppet is a three-node rig; no puppet has `class="clip"`.
+- [ ] No `align` / `alignOrigin` on any motionPath tween.
+- [ ] Every route's SVG `d` is the same string as its walker's motionPath.
+- [ ] Every repeat is finite and computed from its duration.
+- [ ] At least three different easings appear in the timeline.
+- [ ] No puppet is on screen for >2.0s without a BEAT.
+- [ ] At most one camera move per act, none inside a cue's first 0.4s, none past `scale: 1.35`.
+
+**The band**
+
+- [ ] Exactly one loud cue, and it is the first one.
+- [ ] Every other cue is 34–40px, weight 500, one line, ≤8 words, inside 78–86%.
+- [ ] The band's ink and its highlight were SAMPLED off the stage — no colour in the band exists
+      anywhere else in the video.
+- [ ] Kinetics are colour-only: no translate, scale, rotate, blur, shadow, or font-weight on any word.
+- [ ] Cue timings came from `vidfarm stt --engine whisper`; cue TEXT came from the script, and the
+      build fails if the token counts disagree.
+- [ ] Cues break on clauses, not on a word count.
+- [ ] The ember never lands on the offer's name, and no band cue duplicates the lockup.
+- [ ] Gate 2's band-dominance share is under 35% — ideally under 15%.
+- [ ] ≤3 stamps, each ≤2 words or one number, above the 60% line, every number real.
+- [ ] Two weights of ONE self-hosted family, no fallback chain.
+
+**The output**
+
+- [ ] Frame 0 works as a thumbnail: stage visible, loud cue legible, one subject.
+- [ ] Gate 2 ran and reported no frozen window, no stage drift, no popcorn frame.
+- [ ] Audio measured, not vibed: speech ~12–15 dB over the bed, peak < 0 dBFS.
+- [ ] The handoff says the composition is desktop-only and must not be opened in the web editor.
+
+---
+
+## The whole-video review — do this last, on the render
+
+Gates 0–2 grade parts. This grades the theater, and it is the only pass that catches what actually
+ships broken. **Export a contact sheet and read it as one image**, then watch the file end to end at
+1× with sound off, then again with sound on.
+
+```bash
+vidfarm stills ./work --sheet
+# if `stills` dies with "Cannot find package '@hyperframes/producer'", the devcli's bundled
+# engine is incomplete on this machine. Do NOT go hunting — the passthrough is the same renderer:
+vidfarm hf snapshot ./work --at 1,3,5,7,9,11,14,16,19,23,27 -o ./stills --describe false
+```
+
+- [ ] **Is the parchment the same colour on every still?** A set piece with a near-paper background
+      rectangle makes its act read a different cream, and it only shows up beside its neighbours.
+- [ ] **Do the cutouts look like one set?** Same class, same light, plausible relative scale.
+- [ ] **Is the horizon in the same place on all ten?** Drift here is the "something is off" nobody
+      can name.
+- [ ] **Pick any two adjacent stills — has the stage actually changed?** Two identical stills 3s
+      apart is a frozen window gate 2 should have caught; if it did not, the gate's threshold is
+      wrong for your build.
+- [ ] **Count the type sizes.** There should be two: the loud cue and the band. Stamps share the
+      band's family and may be a third size — no more.
+- [ ] **Which act is the weakest?** There is one. Usually act 3, because it is quiet and got the
+      least attention. Cut it shorter rather than adding to it.
+- [ ] **Is act 4 visibly the ad?** It must not be — it carries no brand name. If your eye finds it
+      before act 5, you styled it differently and Rule 2 is broken.
+- [ ] **Does the promo read at arm's length in one glance?** It is the last thing they see and the
+      only thing they might type into a search box.
+- [ ] **Would you watch it twice?** That is this format's actual bar, and it is a higher one than
+      "is it correct".
+
+---
+
+## Diagnosing a flop — read the acts, not the video
+
+| What the numbers say | The weak act | The fix |
+|---|---|---|
+| Almost no views | **Act 1 / frame 0** | The stage was empty at frame 0, or the loud cue was a question. Open on a figure already mid-move with the claim already readable |
+| Views, mass exit at 4–8s | **Act 2** | The grind is not visibly accumulating. More routes, faster stagger, make the failures repeat |
+| Watched through, no reaction | **Act 4** | The turn was an announcement, not a re-draw. Show the system assembling; say less |
+| Watched through, nobody remembers the brand | **Act 5** | The promo was too short, too small, or shared its beat with a caption. Hold the wordmark ≥3s alone |
+| Exit right at the promo | **The pace before it** | Not the promo. The video was too slow to have earned those four seconds — cut words and raise `atempo` |
+| Good retention, no comments | **The caption** | The bait lives there, and it is missing or generic |
+| "Looks AI-made" in the comments | **The art class** | Almost always two sheets with different style strings, or generated lettering on a sign |
+| Good numbers, no clicks | **Nothing is broken** | This format seeds a mechanism; it does not close. Judge it on saves, re-watches and branded search |
+
+**Vary one act at a time.** A batch where the story, the cast and the turn all changed teaches you
+nothing, which is the entire point of running against a harness instead of just generating volume.
+
+---
+
+## Appendix A — the composition skeleton
+
+Copy this, then fill acts 2–5. It renders as-is.
+
+```html
+<!doctype html>
+<html lang="en"><head><meta charset="UTF-8">
+<meta name="viewport" content="width=1080, height=1920">
+<title>sticker story</title>
+<style>
+  @font-face{font-family:'Deck';font-weight:800;font-display:block;
+    src:url('media/fonts/deck-800.woff2') format('woff2')}
+  @font-face{font-family:'Deck';font-weight:500;font-display:block;
+    src:url('media/fonts/deck-500.woff2') format('woff2')}
+
+  body{margin:0;background:#E7DCC2}
+  #root{position:relative;width:1080px;height:1920px;overflow:hidden;background:#E7DCC2}
+  .clip{position:absolute;inset:0}
+
+  /* The stage plate, identical in every act, so the butt cuts are invisible. */
+  .stagewrap{position:absolute;inset:0;transform-origin:50% 55%}
+  .plate{position:absolute;inset:0;width:1080px;height:1920px;object-fit:cover}
+
+  /* THE RIG. Three nodes so travel / bob / pop never share a matrix. */
+  .rig{position:absolute;left:0;top:0;width:0;height:0}
+  .bob{position:absolute;left:0;top:0;width:0;height:0}
+  .art{position:absolute;transform-origin:50% 100%}
+
+  /* Marks are SVG so they can be DRAWN. pathLength normalises the dashoffset. */
+  .marks{position:absolute;inset:0;overflow:visible}
+
+  .band{font-family:'Deck';font-weight:500;font-size:38px;line-height:1.3;
+        color:#2A2118;text-align:center;letter-spacing:0}
+  .loud{font-family:'Deck';font-weight:800;font-size:76px;line-height:1.18;
+        color:#2A2118;text-align:center;letter-spacing:-0.01em}
+  .stamp{font-family:'Deck';font-weight:800;font-size:56px;color:#8C3B2E;
+         letter-spacing:0.02em;text-align:center}
+  /* NO text-shadow, NO -webkit-text-stroke, NO plate. Ink on paper is already
+     maximum contrast, and a plate on parchment is a card (Rule 4). */
+</style>
+</head><body>
+
+<div id="root" data-composition-id="story" data-start="0"
+     data-width="1080" data-height="1920" data-duration="30">
+
+  <div id="act1" class="clip" data-hf-id="act1" data-layer-kind="image" data-track-index="0"
+       data-start="0" data-duration="5" data-label="act 1 — the want">
+    <div class="stagewrap">
+      <img class="plate" src="media/stage-map.png">
+
+      <svg class="marks" viewBox="0 0 1080 1920">
+        <path id="route1" d="M 120 1620 C 260 1440 340 1180 500 1010"
+              fill="none" stroke="#2A2118" stroke-width="4" stroke-opacity="0.4"
+              stroke-dasharray="14 16" stroke-linecap="round"
+              pathLength="1000" style="stroke-dashoffset:1000"/>
+      </svg>
+
+      <div class="rig" id="rig-her">
+        <div class="bob">
+          <img class="art" src="media/stickers/cast-02-walker-olive.png"
+               style="left:-55px;top:-240px;width:110px">
+        </div>
+      </div>
+    </div>
+
+    <!-- The band is OUTSIDE .stagewrap: the camera must never move the subtitles. -->
+    <div class="loud" id="cue-loud"
+         style="inset:auto;left:8%;width:84%;top:38%;z-index:9">It's seven in the evening<br>and you know exactly what you want.</div>
+  </div>
+
+  <!-- acts 2-5 … same shape, data-start 5 / 14 / 19 / 26 -->
+
+</div>
+
+<script src="vendor/gsap.min.js"></script>
+<script src="vendor/MotionPathPlugin.min.js"></script>
+<script>
+  gsap.registerPlugin(MotionPathPlugin);
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  // ACT 1 -------------------------------------------------------------------
+  tl.fromTo("#rig-her .art", { scale: 0, opacity: 0 },
+            { scale: 1, opacity: 1, duration: 0.42, ease: "back.out(1.6)" }, 0.3);
+  tl.to("#route1", { strokeDashoffset: 0, duration: 1.1, ease: "power2.inOut" }, 0.8);
+  tl.to("#rig-her", { motionPath: { path: "M 120 1620 C 260 1440 340 1180 500 1010" },
+                      duration: 3.2, ease: "none" }, 0.8);
+  tl.to("#rig-her .bob", { y: -14, duration: 0.26, ease: "sine.inOut",
+                           repeat: 11, yoyo: true }, 0.8);
+  tl.to("#cue-loud", { opacity: 0, duration: 0.3 }, 2.4);
+
+  window.__timelines["story"] = tl;   // MUST equal data-composition-id
+</script>
+</body></html>
+```
+
+**The one line in there that is easy to miss:** the band and the loud cue sit **outside**
+`.stagewrap`. A camera move that drags the subtitles with it is disorienting in a way viewers report
+as "it made me feel sick" and authors never notice, because they are watching the puppets.
+
+## Appendix B — `puppet.js`, the move library
+
+Drop this above your timeline and the seven moves become one line each. It is deliberately tiny —
+this is a vocabulary, not a framework, and a framework here would hide exactly the timings you need
+to tune.
+
+```js
+/* puppet.js — the seven moves. Every function takes the timeline and a time.
+   Nothing here reads the DOM, uses Math.random(), or schedules work: everything
+   is deterministic from time alone, which is what a seek-driven renderer needs. */
+
+const P = {
+  // 1. ENTER — paper lands. Never a cross-fade.
+  enter(tl, sel, at, { d = 0.42, from = 0 } = {}) {
+    return tl.fromTo(`${sel} .art`, { scale: from, opacity: 0 },
+      { scale: 1, opacity: 1, duration: d, ease: "back.out(1.6)" }, at);
+  },
+
+  // 2. WALK — travel on the rig, bob on the bob node. Two tweens, never one.
+  walk(tl, sel, at, path, { d = 3.2, bob = 14, step = 0.26, flip = false } = {}) {
+    if (flip) tl.set(`${sel} .art`, { scaleX: -1 }, at);
+    tl.to(sel, { motionPath: { path }, duration: d, ease: "none" }, at);
+    // repeat is COMPUTED, never -1: half-cycles that fit inside the walk.
+    tl.to(`${sel} .bob`, { y: -bob, duration: step, ease: "sine.inOut",
+                           repeat: Math.max(1, Math.round(d / step) - 1), yoyo: true }, at);
+    return tl;
+  },
+
+  // 3. CROWD — one tween, N puppets. Cap the group so it reads as ONE beat.
+  crowd(tl, sel, at, { d = 0.4, each = 0.04, from = "random" } = {}) {
+    return tl.fromTo(`${sel} .art`, { scale: 0, opacity: 0 },
+      { scale: 1, opacity: 1, duration: d, ease: "back.out(1.5)",
+        stagger: { each, from } }, at);
+  },
+
+  // 4. BEAT / IDLE — the small life that stops the stage looking frozen (Rule 6).
+  //    3.6deg is the MEASURED floor: 2.4deg is under the pixel gate's threshold
+  //    and under a viewer's. Pass a SPAN, not a repeat count — a beat that ends
+  //    before its hold does leaves a frozen window nobody sees while authoring.
+  idle(tl, sel, at, span, { deg = 3.6, rise = 9, half = 1.05 } = {}) {
+    tl.to(`${sel} .bob`, { rotation: deg, duration: half, ease: "sine.inOut",
+      repeat: Math.max(1, Math.round(span / half)), yoyo: true,
+      transformOrigin: "50% 100%" }, at);
+    // different node, slightly different period — so the idle never metronomes
+    tl.to(`${sel} .art`, { y: -rise, duration: half * 0.86, ease: "sine.inOut",
+      repeat: Math.max(1, Math.round(span / (half * 0.86))), yoyo: true }, at + 0.2);
+    return tl;
+  },
+
+  // 5. STAMP — 0.18s, power4.out. Slower than this is a fade and carries no weight.
+  stamp(tl, sel, at, { rot = -3 } = {}) {
+    return tl.fromTo(sel, { scale: 2.4, opacity: 0, rotation: rot - 6 },
+      { scale: 1, opacity: 1, rotation: rot, duration: 0.18, ease: "power4.out" }, at);
+  },
+
+  // 6a. DRAW — an SVG route appears. Requires pathLength="1000" on the path.
+  draw(tl, sel, at, { d = 1.1 } = {}) {
+    return tl.to(sel, { strokeDashoffset: 0, duration: d, ease: "power2.inOut" }, at);
+  },
+  // 6b. UNROLL — a menu, a banner, a bar. Same family, different property.
+  unroll(tl, sel, at, { d = 0.5, origin = "50% 0%" } = {}) {
+    return tl.fromTo(sel, { scaleY: 0 },
+      { scaleY: 1, duration: d, ease: "power2.out", transformOrigin: origin }, at);
+  },
+
+  // 7. CAMERA — the stage moves. Once per act, never past 1.35. Give it the
+  //    ACT's duration, not a beat's: a camera that stops mid-act hands the pixel
+  //    gate a frozen window on any act whose puppets are small.
+  camera(tl, sel, at, { scale = 1.18, x = 0, y = 0, d = 2.4 } = {}) {
+    if (scale > 1.35) throw new Error("camera past 1.35 — the paper grain turns to mush");
+    return tl.to(sel, { scale, x, y, duration: d, ease: "power1.inOut" }, at);
+  },
+
+  // 8. LOCKUP — the promo. Same physics as a STAMP, because it IS one: a
+  //    wordmark pressed onto the paper, not a title card fading up.
+  lockup(tl, sel, at) {
+    return tl.fromTo(sel, { scale: 1.9, rotation: -3, opacity: 0 },
+      { scale: 1, rotation: 0, opacity: 1, duration: 0.22, ease: "power4.out" }, at);
+  },
+};
+```
+
+Used:
+
+```js
+P.enter (tl, "#rig-her", 0.2);
+P.draw  (tl, "#route1",  0.6, { d: 0.45 });
+P.walk  (tl, "#rig-her", 0.8, "M 120 1620 C 260 1440 340 1180 500 1010", { d: 6.0 });
+P.idle  (tl, "#rig-her", 4.2, 3.1);
+P.crowd (tl, ".queue",  14.6, { each: 0.013 });
+P.stamp (tl, "#stamp-x", 8.4);
+P.lockup(tl, "#lockup", 24.2);          // the close
+```
+
+## Appendix C — `story-qa.py` (gate 2: enforce it on the RENDER)
+
+`vidfarm qa` reads the DOM and cannot see that the timeline never ran. This runs on the pixels that
+ship, and it is the gate that catches the failure this format actually ships.
+
+```bash
+python3 story-qa.py ./work/out.mp4 --acts 0,3.4,10.4,14.4,21 --duration 29.4
+```
+
+```python
+#!/usr/bin/env python3
+"""
+Grade a rendered sticker story on the pixels, not on the markup.
+
+Four checks, each one a defect that passes every DOM check and every glance at a
+single frame, and shows up only across the whole file:
+
+  1. FROZEN WINDOW  — any stretch >2.0s where consecutive frames are identical.
+                      This is the format's signature failure: an unregistered
+                      timeline, an align:"self" motionPath, or a CDN miss all
+                      render a beautiful still that passes duration, frame-count
+                      and audio-hash checks.
+  2. STAGE DRIFT    — the parchment must read the same colour in every act. A set
+                      piece with a near-paper background rectangle changes its
+                      act's cream and is invisible except beside its neighbours.
+  3. EMPTY BAND     — the subtitle band should carry ink for most of the runtime.
+                      A band that is blank throughout means the caption layers
+                      never rendered, which is silent and total.
+  4. POPCORN        — a frame where too much of the stage changed at once is a
+                      frame nobody can read (the "one subject" rule).
+  5. BAND READABLE  — is the caption band on calm ground, or on the drawing with
+                      no treatment? Type parked on the map is this format's
+                      biggest legibility failure. Two legal fixes: reserve the
+                      zone in the plate, or lay a measured paper wash. A plate,
+                      a stroke and a text-shadow are all cards (Rule 4).
+  6. BAND DOMINANCE — the kinetic band's share of the video's total motion. The
+                      band is allowed to move (a colour highlight travelling the
+                      line) but it may never be the LOUDEST thing on screen. It
+                      occupies ~8% of the frame; if it accounts for more than a
+                      third of the motion, the captions have taken the spotlight
+                      the stage is supposed to hold.
+
+usage: story-qa.py <render.mp4> [--acts 0,5,14,19,26] [--duration 30]
+                                [--band 0.78,0.86] [--fps 6]
+"""
+import subprocess, sys, os
+
+src = sys.argv[1]
+opt = dict(zip(sys.argv[2::2], sys.argv[3::2]))
+acts = [float(x) for x in opt.get("--acts", "0").split(",")]
+dur = float(opt.get("--duration", "30"))
+band = [float(x) for x in opt.get("--band", "0.80,0.884").split(",")]
+fps = float(opt.get("--fps", "6"))
+
+fails, warns = [], []
+
+
+def gray(t, crop=None, size="64:114"):
+    """One frame at t as a small greyscale byte array — no PIL dependency."""
+    vf = (f"crop={crop}," if crop else "") + f"format=gray,scale={size}"
+    return subprocess.run(
+        ["ffmpeg", "-v", "error", "-ss", str(t), "-i", src, "-vf", vf,
+         "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "gray", "-"],
+        capture_output=True).stdout
+
+
+def rgb(t, crop):
+    raw = subprocess.run(
+        ["ffmpeg", "-v", "error", "-ss", str(t), "-i", src, "-vf",
+         f"crop={crop},scale=1:1", "-frames:v", "1", "-f", "rawvideo",
+         "-pix_fmt", "rgb24", "-"], capture_output=True).stdout
+    return tuple(raw[:3]) if len(raw) >= 3 else (0, 0, 0)
+
+
+def diff(a, b):
+    if not a or not b or len(a) != len(b):
+        return 1.0
+    return sum(abs(x - y) for x, y in zip(a, b)) / (255.0 * len(a))
+
+
+# ------------------------------------------------- 1. frozen windows + 4. popcorn
+step = 1.0 / fps
+times = [round(i * step, 3) for i in range(int(dur * fps))]
+frames = [gray(t) for t in times]
+diffs = [diff(frames[i], frames[i + 1]) for i in range(len(frames) - 1)]
+
+run_start, DEAD = None, 0.002          # 0.2% mean change = nothing moved
+for i, d in enumerate(diffs):
+    if d < DEAD:
+        run_start = times[i] if run_start is None else run_start
+    else:
+        if run_start is not None and times[i] - run_start > 2.0:
+            fails.append(f"FROZEN {run_start:.1f}-{times[i]:.1f}s "
+                         f"({times[i] - run_start:.1f}s of no motion) — Rule 6, "
+                         f"or the timeline never registered")
+        run_start = None
+if run_start is not None and dur - run_start > 2.0:
+    fails.append(f"FROZEN {run_start:.1f}-{dur:.1f}s — the tail is a still image")
+
+if diffs and max(diffs) < 0.004:
+    fails.append("NO MOTION ANYWHERE — window.__timelines key almost certainly does "
+                 "not match data-composition-id, or motionPath used align:'self'")
+
+for i, d in enumerate(diffs):
+    if d > 0.16:
+        warns.append(f"POPCORN at {times[i]:.1f}s ({d:.0%} of the stage changed in "
+                     f"one step) — more than one subject is moving")
+
+# ---------------------------------------------------------------- 2. stage drift
+corners = [rgb(t + 0.4, "60:60:20:20") for t in acts if t + 0.4 < dur]
+if corners:
+    base = corners[0]
+    for t, c in zip(acts, corners):
+        if max(abs(a - b) for a, b in zip(base, c)) > 4:
+            fails.append(f"STAGE DRIFT at act t={t}: parchment {c} vs {base}")
+
+# ----------------------------------------------------------------- 3. empty band
+# Detect a cue by the DARKEST pixel in the strip, not by an inked-area fraction.
+# Once the band sits on the plate's blank margin (which is where it belongs),
+# 38px type covers so little of a downsampled strip that an area test reads it
+# as empty — the area test only ever "worked" because it was counting the map's
+# own dark features as ink.
+W, H = 1080, 1920
+by, bh = int(H * band[0]), int(H * (band[1] - band[0]))
+# Detect a cue by the AREA of dark pixels, sampled fine enough that glyph cores
+# survive (540x96; at 64x8 a 38px stem averages away into the paper and every
+# frame reads as empty). Area, not min-luma: the drawing puts thin dark marks in
+# the strip too — a route line, a shadow — and one dark pixel is not a caption.
+# Measured on this build: cue frames 1.5-2.8% dark, gaps 0.5-1.3%.
+def inked_frac(t):
+    raw = gray(t, crop=f"{W}:{bh}:0:{by}", size="540:96")
+    return (sum(1 for b in raw if b < 110) / len(raw)) if raw else 0.0
+
+
+INKED = 0.014
+inked = sum(1 for t in times[::3] if inked_frac(t) > INKED)
+ratio = inked / max(1, len(times[::3]))
+if ratio < 0.25:
+    fails.append(f"SUBTITLE BAND is inked in only {ratio:.0%} of samples — "
+                 f"the caption layers probably never rendered")
+elif ratio > 0.95:
+    warns.append(f"SUBTITLE BAND is inked in {ratio:.0%} of samples — the band never "
+                 f"rests. Narration is probably wall-to-wall (Rule 7)")
+
+# --------------------------------------------------- 5. is the band READABLE?
+# The single biggest legibility failure in this format is type parked on the
+# drawing. There are exactly two legal fixes and a plate is neither of them:
+# reserve the zone IN THE STAGE PLATE, or lay a measured paper WASH under the
+# band (the sheet's own colour, feathered to nothing, no edge/border/shadow).
+#
+# So: measure the BARE background on frames where no cue is up (the glyphs
+# themselves add variation, so a strip with words in it grades your captions,
+# not your background) — then check whether a wash is actually present, by
+# looking for a luma LIFT in the same strip on the frames that do carry a cue.
+import statistics as _st
+
+
+def _p(v, q):
+    v = sorted(v)
+    return v[min(len(v) - 1, int(len(v) * q))]
+
+
+bare, inked_lift = [], []
+for t in times:
+    raw = list(gray(t, crop=f"{W}:{bh}:0:{by}", size="96:12"))
+    if not raw:
+        continue
+    (inked_lift if inked_frac(t) > INKED else bare).append(raw)
+if not bare or not inked_lift:
+    warns.append("band never sampled both ways (with a cue and without) — grade "
+                 "caption placement on the STAGE PLATE instead")
+else:
+    bare_v = sum(_st.pstdev(r) for r in bare) / len(bare)
+    cue_v = sum(_st.pstdev(r) for r in inked_lift) / len(inked_lift)
+    # A wash FLATTENS the strip; it does not brighten it (the paper is already
+    # near-white, so p75 does not move — measured 228 either way on this build).
+    # So the signature of a treatment is cue_v dropping well BELOW bare_v, even
+    # though the glyphs themselves push variation up.
+    treated = cue_v < bare_v - 4
+    if bare_v > 14 and not treated:
+        (fails if bare_v > 22 else warns).append(
+            f"BAND ON THE DRAWING — variation {bare_v:.0f} behind the caption "
+            f"band (calm is <14) and no treatment detected. Reserve the zone in "
+            f"the stage plate, or lay a measured paper wash. Never a plate")
+    elif cue_v > 24:
+        fails.append(f"BAND STILL BUSY — {cue_v:.0f} variation with the treatment "
+                     f"applied. Strengthen the wash or move the band")
+    elif treated:
+        print(f"  · band background {bare_v:.0f} bare -> {cue_v:.0f} with the "
+              f"paper wash (readable)")
+    else:
+        print(f"  · band background variation {bare_v:.0f} (calm, no wash needed)")
+
+# ------------------------------------------------------------- 6. band dominance
+# Measured on the SAME sample grid, band strip vs the stage above it. Colour-only
+# kinetics land around 5-15%; anything geometric (a word popping, sliding or
+# scaling) pushes it past 35% immediately, which is the whole point of the check.
+band_d, stage_d = [], []
+prev_b = prev_s = None
+for t in times:
+    b = gray(t, crop=f"{W}:{bh}:0:{by}", size="64:16")
+    st = gray(t, crop=f"{W}:{by}:0:0", size="64:96")
+    if prev_b is not None:
+        band_d.append(diff(prev_b, b) * bh)        # weight by the area each covers
+        stage_d.append(diff(prev_s, st) * by)
+    prev_b, prev_s = b, st
+tot = sum(band_d) + sum(stage_d)
+if tot > 0:
+    share = sum(band_d) / tot
+    if share > 0.35:
+        fails.append(f"BAND DOMINANCE {share:.0%} of all motion is in the caption "
+                     f"band — the captions are the loudest thing on screen. "
+                     f"Kinetics must be COLOUR ONLY: no word pop, slide or scale")
+    elif share > 0.22:
+        warns.append(f"band carries {share:.0%} of the motion — near the ceiling")
+    else:
+        print(f"  · band motion share {share:.0%} (ceiling 35%)")
+
+# --------------------------------------------------------------------- verdict
+for f in fails:
+    print(f"  ✗ {f}")
+for w in warns:
+    print(f"  ⚠ {w}")
+print(f"\n{len(times)} samples · {len(fails)} fail · {len(warns)} warn")
+print("\n▶ NOW OPEN THE CONTACT SHEET. This checked motion, not whether it reads as one theater.")
+sys.exit(1 if fails else 0)
+```
+
+## Appendix D — a worked example: dishcover.io
+
+Five acts, **29.4s**. Cost mode `hybrid`. Art class: **paper cutout**, four generated sheets.
+
+**Build log header**
+
+```
+STORY:     One craving, one city, forty wasted minutes, and the turn
+WATCHER:   Someone in NYC who eats out twice a week and has had this exact evening
+OFFER:     dishcover.io — 140 restaurants, 7,502 dishes, searched by DISH not by restaurant
+THE TURN:  the whole city is indexed by restaurant; nobody indexes it by dinner
+PROMO:     END (default) — act 4 shows the mechanism unbranded, act 5 names it last
+ART CLASS: paper cutout, one style string, four sheets (stage / cast / props / dishes)
+PACE:      atempo 1.30 on every narration clip
+COST:      hybrid — 5 image jobs + 7 tts clips on a BYOK gemini key, ~$0.25
+```
+
+**Narration** (66 words, one voice, one style string, `atempo=1.30`)
+
+```
+a1   (0.15s)  It's seven, and you know exactly what you want.
+a2   (3.55s)  So you check one place. Then another. Then four more.
+              None of them are searchable.
+a3  (10.55s)  Forty minutes later, you're eating something you didn't choose.
+a4a (14.55s)  The whole city is indexed by restaurant.
+              [1.1s hole — the map re-draws with nobody talking over it]
+a4b (18.05s)  Nobody indexes it by dinner.
+a5  (21.20s)  So search the dish, not the restaurant.
+              Dishcover dot io. Seven thousand dishes, one search.
+```
+
+The offer is named **once, in act 5, last**. Act 4 carries the mechanism and no brand name at all.
+
+**The stage, act by act**
+
+| Act | s | On the paper | The moves |
+|---|---|---|---|
+| 1 | 0.0–3.4 | Parchment Manhattan, empty. One figure enters lower left. A bowl of vodka rigatoni pops above her | ENTER, IDLE, CAMERA |
+| 2 | 3.4–10.4 | Four storefronts appear on a **1.45s cadence** along her route; a menu unrolls at each; a red X stamps on each. The route draws ahead of her. `40 MINUTES` stamps | DRAW, WALK, UNROLL, STAMP ×5, CAMERA |
+| 3 | 10.4–14.4 | The stage empties. One seated figure, one grey sandwich — and two ambient walkers crossing behind, so the quiet act is not a still | ENTER, IDLE, WALK ×2, CAMERA |
+| 4 | 14.4–21.0 | The map RE-DRAWS: 24 pins for the 140 restaurants land in one gust, then 30 dish marks for the 7,502. They dim. ONE dashed route runs straight to one dish. `7,502 DISHES` stamps | CROWD ×2, DRAW, STAMP, CAMERA |
+| 5 | 21.0–29.4 | She walks that one route, the rigatoni is in colour — then **`dishcover.io` stamps onto the paper** and holds to the last frame | WALK, ENTER, IDLE, **LOCKUP** |
+
+**Act 4 read against the lock**
+
+- *Silent-legible?* The island filling with dishes and one straight route is the whole mechanism with
+  the sound off. Passes.
+- *One surface?* No cuts. The re-draw happens on the same parchment. Passes.
+- *Die-cut?* Every mark is SVG or a snug PNG; the plate is the only rectangle. Passes.
+
+**Post caption** (the topic, the bait and the credits live here, never on the stage)
+
+```
+40 minutes to find one dish in a city that has 7,502 of them 🍝
+
+what's the dish you'd search for first?
+```
+
+**Build and export**
+
+```bash
+# 1. the art — FOUR image jobs, one style string, ~$0.20
+npx -y dotenv-cli -e .env -- vidfarm generate image --prompt "<parchment map, 9:16>" --aspect-ratio 9:16
+npx -y dotenv-cli -e .env -- vidfarm sticker-pack --generate "<STYLE>" --items "…" --prefix cast --out-dir media/stickers
+npx -y dotenv-cli -e .env -- vidfarm sticker-pack --generate "<STYLE>" --items "…" --prefix prop --out-dir media/stickers
+npx -y dotenv-cli -e .env -- vidfarm sticker-pack --generate "<STYLE>" --items "…" --prefix dish --out-dir media/stickers
+# delete the whole-sheet artifact, rename the rest against the picture
+
+# 2. the voice — one clip per act, one pinned voice
+for i in 1 2 3 4 5; do
+  npx -y dotenv-cli -e .env -- vidfarm tts "$(cat vo/a$i.txt)" --voice Leda \
+    --style "flat documentary narrator, unhurried" --out vo/a$i.mp3
+  # trim the TTS padding, speed it up, normalise — then RE-MEASURE and paste the
+  # real durations into the act table. Slow is this format's shipping failure.
+  ffmpeg -i vo/a$i.mp3 -af "silenceremove=start_periods=1:start_threshold=-45dB:\
+start_silence=0.05,areverse,silenceremove=start_periods=1:start_threshold=-45dB:\
+start_silence=0.05,areverse,atempo=1.30,loudnorm=I=-16:TP=-1.5" vo/a$i-t.mp3 -y
+  ffprobe -v error -show_entries format=duration -of csv=p=0 vo/a$i-t.mp3
+done
+
+# 3. the rig — hand-authored, Appendix A + Appendix B
+vidfarm lint ./work                 # gate 0 — expect scripts_stripped_on_save
+vidfarm qa   ./work --harness ./experimental/animated-sticker-story.md   # gate 1
+
+# 4. the render — local, free, ~5s per 6s of 1080x1920
+vidfarm hf render ./work --output ./work/out.mp4
+
+# 5. the pixels — gate 2, the one that catches a rendered still
+python3 story-qa.py ./work/out.mp4 --acts 0,3.4,10.4,14.4,21 --duration 29.4
+vidfarm hf snapshot ./work --at 1,3,5,7,9,11,14,16,19,23,27 -o ./stills --describe false
+open ./stills/contact-sheet.png     # gate 3 — the pass that actually matters
+```
+
+⚠️ **`vidfarm render --dir <dir>` refuses a local directory** with *"render requires a fork id (or a
+--dir with composition.html)"* even when `composition.html` is sitting in it. Do not go hunting: the
+hyperframes passthrough is the same renderer and it works — `vidfarm hf render <dir> --output <file>`.
+Keep both filenames on disk regardless, because the two halves of the toolchain disagree:
+
+| Tool | Wants |
+|---|---|
+| `vidfarm qa` / `vidfarm stills` / `vidfarm lint` | `composition.html` |
+| `vidfarm hf …` (the passthrough) | `index.html` |
+
+A symlink is not enough — some passes resolve it and some do not. **Write both files.**
+
+### What the first pass actually got wrong
+
+Recorded because it is what this format gets wrong, and every item below rendered cleanly, exited 0,
+and produced a file of exactly the right length.
+
+1. **Both walkers were off-canvas.** `puppet()` baked `left`/`top` on a rig that was then given a
+   motionPath, so `left:300; top:1560` plus a path starting `M 300 1560` put her at `(600, 3120)`.
+   Acts 2 and 5 had no protagonist in them. Every computed style said `visible`. Fixed by splitting
+   the constructor into `puppet()` and `walker()`.
+2. **Four frozen windows, 14.7s total** — gate 2 caught all four. The BEATs were real tweens at
+   ±2.4°, which is below the threshold at which a viewer or a pixel gate reads motion. Fixed by
+   raising to 3.6–6°, sizing every idle to fill its hold, and walking two ambient figures through
+   act 3.
+3. **A pink halo on every prop.** The generated stickers had baked drop shadows, which blend into
+   the chroma plate and survive every tolerance, key mode and matting model. Fixed for the shipped
+   build with `deshalo.sh`, and fixed properly by generating without shadows and adding one CSS
+   `drop-shadow` to `.art`.
+4. **The prop and dish sheets refused to split** — perfect zoned grids, one 988×988 "sticker" out.
+   Fixed by cropping the grid locally and keying each cell against its own plate colour.
+5. **The `40 MINUTES` stamp landed on the walker's head** at the end of act 2, because the route's
+   last point was high in the frame and the stamp sat at 17%. Fixed by lowering the four stops, not
+   by moving the stamp — the stamp's band is fixed and the puppets move.
+6. **A `scale: 1.16` camera on act 2 drifted the storefronts off the island** and onto the river.
+   Only visible at full zoom, invisible in the unzoomed authoring view. Pulled back to 1.09.
+7. **The loud cue was 10 words** and failed `hook_words_max`. Fixed by shortening the *narration*
+   and re-recording act 1 — not by trimming the cue, which would have desynced the band from the
+   voice.
+
+8. **It was 37.4s and it was boring.** Every gate passed and the video was still too slow to finish
+   — the defect no check in this file could see at the time, which is why the *Pace* section and the
+   `atempo` rule now exist. Fixed by raising the narration to `atempo=1.30`, cutting one clause from
+   act 2 and three words from act 5, and tightening act 2's failure cadence from 2.0s to 1.45s:
+   **37.4s → 29.4s**, same story, same assets, no re-generation.
+9. **The offer was named in act 4 and the video ended on a resolve with no brand in it.** Beautiful,
+   and it sold nothing. Restructured: act 4 shows the mechanism unbranded, act 5 pays the want and
+   stamps the wordmark. The promo is now the close by default.
+
+**Measured result:** gate 0 clean (1 expected warning), gate 1 **23/23** machine checks, gate 2
+**0 fail / 1 expected warning**, audio `mean -17.6 dB / peak -0.6 dBFS`, **29.4s**, render 31s local.
+
+## Appendix E — the harness in one paragraph, for a handoff
+
+> Build a 30s narrated sticker story, 9:16, 1080×1920, on ONE aged-parchment stage that never
+> changes — five butt-cut act clips sharing an identical plate, no transitions, no footage, no cuts.
+> Cast is die-cut paper-collage stickers from four generated sheets (stage / cast / props / hero),
+> all four generated with the SAME art style string, muted earthy palette, six colours total. Every
+> puppet is a three-node rig (travel / bob / art) animated by ONE paused GSAP 3.14.2 timeline
+> registered on `window.__timelines` under the composition id, with MotionPathPlugin for walks —
+> paths in absolute canvas coordinates, never `align:"self"`. Seven moves only: ENTER, WALK, CROWD,
+> BEAT, STAMP, DRAW, CAMERA. Narration is one 55–90 word paragraph, one voice, one clip per act, with
+> one deliberate hole where the stage talks alone; subtitles stay SMALL (38px, weight 500, one line,
+> ≤8 words, band at 78–86%) except the first cue, which is loud at 76px/800 and never returns. The
+> band is painted from the stage's own palette — ink one step lighter than the drawing, highlight in
+> the exact stamp red — and it MAY be kinetic: one ember travelling the line on whisper word timings,
+> animating COLOUR ONLY. No translate, scale, rotate or font-weight on a word, ever; gate 2 measures
+> the band's share of total motion and fails it past 35%. The
+> offer is named ONCE and LAST: act 4 re-draws the stage into the mechanism with no brand name on it,
+> and act 5 pays the want and then stamps the offer's wordmark onto the paper in the stage's own ink
+> — no logo, no URL, no button, no card, nothing after it. Narration runs at atempo 1.30; slow is the
+> failure this format ships. GSAP is vendored locally; the composition is DESKTOP-ONLY and must not be opened in the web
+> editor, which strips scripts. Render with `vidfarm hf render`, then run the pixel gate — a
+> composition whose timeline never registered renders a beautiful still and passes every other check.
+> Full rules: `vidfarm.cc/experimental/animated-sticker-story.md`.
+
+## Appendix F — the two asset scripts
+
+Both are free, local and ffmpeg-only. Both exist because a generated sheet is right and the
+automatic split is wrong, which is a failure mode you will hit and should not spend a day on.
+
+### `split-sheet.sh` — cut a colour-block sheet the keyer refused to split
+
+```bash
+#!/usr/bin/env bash
+# Split a generated COLOUR-BLOCK sticker sheet into cells and key each one locally.
+#
+# Use this when the image model returned a perfectly good zoned grid but
+# `vidfarm sticker-pack` refuses to split it — alternating panel colours defeat
+# the single-plate keyer, so it re-keys the whole sheet as one plate and hands
+# back the sheet as "one sticker".
+#
+# Free: ffmpeg crop + `vidfarm mask --flat`, which chroma-keys each cell against
+# ITS OWN plate colour, sampled from that cell's own corner. ONNX matting is the
+# wrong tool here — it treats a flat saturated plate as part of the subject.
+#
+# usage: split-sheet.sh <sheet.png> <cols> <rows> <outdir> <name1,name2,...>
+set -euo pipefail
+SHEET="$1"; COLS="$2"; ROWS="$3"; OUT="$4"; IFS=',' read -ra NAMES <<< "$5"
+
+W=$(ffprobe -v error -select_streams v -show_entries stream=width  -of csv=p=0 "$SHEET")
+H=$(ffprobe -v error -select_streams v -show_entries stream=height -of csv=p=0 "$SHEET")
+CW=$((W / COLS)); CH=$((H / ROWS)); mkdir -p "$OUT"; i=0
+
+for ((r=0; r<ROWS; r++)); do for ((c=0; c<COLS; c++)); do
+  n="${NAMES[$i]:-item$i}"; i=$((i+1))
+  # inset 4% so a neighbouring panel's colour never enters the crop
+  IX=$((CW * 4 / 100)); IY=$((CH * 4 / 100))
+  CELL="$OUT/_cell-$n.png"
+  ffmpeg -v error -i "$SHEET" \
+    -vf "crop=$((CW-2*IX)):$((CH-2*IY)):$((c*CW+IX)):$((r*CH+IY))" \
+    -frames:v 1 "$CELL" -y
+  # this cell's own plate colour, read off its top-left corner
+  HEX=$(ffmpeg -v error -i "$CELL" -vf "crop=8:8:0:0,scale=1:1" -frames:v 1 \
+        -f rawvideo -pix_fmt rgb24 - | xxd -p | head -c 6)
+  if vidfarm mask "$CELL" --flat "#$HEX" --tolerance 0.10 --out "$OUT/$n.png" >/dev/null 2>&1; then
+    echo "  ✓ $n  (plate #$HEX)"
+  else
+    echo "  ✗ $n  (plate #$HEX)"
+  fi
+  rm -f "$CELL"
+done; done
+```
+
+The ONNX twin, for organic subjects — same crop, `vidfarm remove-background` per cell instead of
+`vidfarm mask --flat`. Keep both and pick per sheet: flat graphics chroma-key, food and people matte.
+
+```bash
+#!/usr/bin/env bash
+# Same grid split, but matte each cell with local ONNX instead of chroma-keying it.
+# usage: split-onnx.sh <sheet.png> <cols> <rows> <outdir> <names,...>
+set -euo pipefail
+SHEET="$1"; COLS="$2"; ROWS="$3"; OUT="$4"; IFS=',' read -ra NAMES <<< "$5"
+W=$(ffprobe -v error -select_streams v -show_entries stream=width  -of csv=p=0 "$SHEET")
+H=$(ffprobe -v error -select_streams v -show_entries stream=height -of csv=p=0 "$SHEET")
+CW=$((W / COLS)); CH=$((H / ROWS)); mkdir -p "$OUT"; i=0
+for ((r=0; r<ROWS; r++)); do for ((c=0; c<COLS; c++)); do
+  n="${NAMES[$i]:-item$i}"; i=$((i+1))
+  IX=$((CW * 4 / 100)); IY=$((CH * 4 / 100)); CELL="$OUT/_cell-$n.png"
+  ffmpeg -v error -i "$SHEET" -vf "crop=$((CW-2*IX)):$((CH-2*IY)):$((c*CW+IX)):$((r*CH+IY))" -frames:v 1 "$CELL" -y
+  vidfarm remove-background "$CELL" --out "$OUT/$n.png" >/dev/null 2>&1 && echo "  ✓ $n" || echo "  ✗ $n"
+  rm -f "$CELL"
+done; done
+```
+
+### `place-text.py` — measure the stage, then place the type
+
+The second pass of the two-pass build. Run it between `build.py --no-text` and `build.py`.
+
+```bash
+python3 build.py v001 --no-text && python3 place-text.py v001 && python3 build.py v001
+```
+
+```python
+import json, os, statistics, subprocess, sys
+
+DIR = sys.argv[1] if len(sys.argv) > 1 else "v001"
+W, H = 1080, 1920
+
+# zone -> (allowed top range %, box height %). The halves are fixed so the layout
+# stays stable: the hook and the promo live above the stage's midline, the band
+# below it. Only the exact position inside each half is measured.
+ZONES = {
+    "loud":   ((12, 44), 13.0),
+    "band":   ((66, 87), 9.0),
+    # the lockup may take the upper half too: the loud cue vacated it 20s earlier
+    "lockup": ((12, 72), 12.0),
+}
+
+# variation behind the type -> the lightest treatment that survives it.
+# A PLATE is banned (Rule 4). A paper WASH is not a plate: it is the sheet's own
+# colour, feathered to nothing at both edges, with no border, corner or shadow —
+# the paper simply being lighter where the words are, like a documentary margin.
+def wash_for(v):
+    if v < 14:
+        return 0.0, "bare paper — no treatment"
+    if v < 20:
+        return 0.55, "light wash"
+    if v < 26:
+        return 0.70, "wash"
+    return 0.82, "strong wash — consider moving the band instead"
+
+
+def snap(times):
+    out = os.path.join(DIR, "stage-frames")
+    subprocess.run(["vidfarm", "hf", "snapshot", DIR, "--at", ",".join(map(str, times)),
+                    "--no-end", "-o", out, "--describe", "false"],
+                   capture_output=True)
+    pngs = sorted(f for f in os.listdir(out) if f.endswith(".png")
+                  and "sheet" not in f)
+    return [os.path.join(out, f) for f in pngs]
+
+
+def strip(png, top_pct, h_pct):
+    raw = subprocess.run(
+        ["ffmpeg", "-v", "error", "-i", png, "-vf",
+         f"crop={W}:{int(h_pct / 100 * H)}:0:{int(top_pct / 100 * H)},"
+         f"format=gray,scale=96:12", "-frames:v", "1", "-f", "rawvideo",
+         "-pix_fmt", "gray", "-"], capture_output=True).stdout
+    v = list(raw)
+    return (statistics.mean(v), statistics.pstdev(v)) if v else (0, 99)
+
+
+def paper_colour(png):
+    """The sheet's own lightest paper, for the wash. Never an invented cream."""
+    raw = subprocess.run(
+        ["ffmpeg", "-v", "error", "-i", png, "-vf", "scale=32:56", "-frames:v", "1",
+         "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], capture_output=True).stdout
+    px = [tuple(raw[i:i + 3]) for i in range(0, len(raw) - 2, 3)]
+    px.sort(key=lambda c: sum(c))
+    hi = px[int(len(px) * 0.93)]                 # bright, but not a specular
+    return ",".join(str(c) for c in hi)
+
+
+cues = json.load(open(os.path.join(DIR, "cues.json")))
+times = sorted({round((c["t0"] + c["t1"]) / 2, 2) for c in cues})
+frames = snap(times)
+if len(frames) != len(times):
+    sys.exit(f"snapshot returned {len(frames)} frames for {len(times)} cues")
+at = dict(zip(times, frames))
+
+place = {"_paper": paper_colour(frames[0])}
+for zone, ((lo, hi), boxh) in ZONES.items():
+    mine = [c for c in cues if c["kind"] == zone]
+    if not mine:
+        continue
+    pngs = [at[round((c["t0"] + c["t1"]) / 2, 2)] for c in mine]
+    best = None
+    for top in range(lo, int(hi - boxh) + 1):
+        worst = max(strip(p, top, boxh)[1] for p in pngs)
+        if best is None or worst < best[0]:
+            best = (worst, top)
+    worst, top = best
+    wash, label = wash_for(worst)
+    place[zone] = {"top": float(top), "wash": wash}
+    print(f"  {zone:7s} top {top:2d}%  worst variation {worst:5.1f}  -> {label}"
+          f"{'' if not wash else f' ({wash:.2f})'}")
+
+json.dump(place, open("place.json", "w"), indent=2)
+print(f"\npaper {place['_paper']} · wrote place.json")
+print("▶ now rebuild WITH text: python3 build.py " + DIR)
+```
+
+### `band-measure.py` — the quick probe
+
+`place-text.py` is the tool that decides. This is the one you reach for when you just want to look at
+a number: what is behind the band, on this plate or on this frame, right now?
+
+```bash
+python3 band-measure.py media/stage-map.png        # the plate, before you build
+python3 band-measure.py v001/out.mp4 12.5          # the render, at a given second
+```
+
+```python
+import subprocess, sys, statistics
+src = sys.argv[1]; t = sys.argv[2] if len(sys.argv) > 2 else None
+W, H = [int(x) for x in subprocess.run(["ffprobe","-v","error","-select_streams","v",
+    "-show_entries","stream=width,height","-of","csv=p=0",src],
+    capture_output=True, text=True).stdout.strip().split(",")[:2]]
+def strip(y0, y1, label):
+    pre = ["-ss", t] if t else []
+    raw = subprocess.run(["ffmpeg", "-v", "error", *pre, "-i", src, "-vf",
+        f"crop={W}:{int((y1-y0)*H)}:0:{int(y0*H)},format=gray,scale=96:12",
+        "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "gray", "-"],
+        capture_output=True).stdout
+    v = list(raw)
+    print(f"  {label:22s} luma {statistics.mean(v):6.1f}   variation "
+          f"{statistics.pstdev(v):5.1f}   darkest {min(v):3d}")
+print(src + (f" @ {t}s" if t else ""))
+for a, b, n in [(0.08,0.20,"top margin 8-20%"),(0.37,0.47,"mid 37-47%"),
+                (0.76,0.87,"band 76-87%"),(0.60,0.72,"lockup 60-72%")]:
+    strip(a, b, n)
+```
+
+### `deshalo.sh` — remove a coloured halo that is already in your assets
+
+```bash
+#!/usr/bin/env bash
+# Kill the soft coloured halo a chroma key leaves around a die-cut sticker.
+# The halo IS the sticker's own drop shadow blended with the plate, so it is baked
+# into the pixels and no tolerance setting removes it. What removes it is throwing
+# away every PARTIAL-alpha pixel: hard-threshold the alpha, then erode 1px.
+# Safe on flat/vector art. Do NOT run it on soft, furry or glassy subjects.
+# usage: deshalo.sh <dir> [threshold 0-255, default 215]
+set -euo pipefail
+D="$1"; T="${2:-215}"
+for f in "$D"/*.png; do
+  ffmpeg -v error -i "$f" -filter_complex \
+    "[0:v]alphaextract,lut=y='if(gt(val,$T),255,0)',erosion[a];[0:v][a]alphamerge" \
+    -frames:v 1 "$f.tmp.png" -y && mv "$f.tmp.png" "$f" && echo "  ✓ $(basename "$f")"
+done
+```