@officexapp/vidfarm-devcli 0.21.42 → 0.21.43

package/experimental/unique-product-explainers.md

@@ -0,0 +1,855 @@
+# Unique Product Explainer Videos — reusable prompt & method
+
+Turns **N customer URLs → N product-introduction videos that do not look like each other**,
+for **$0.00**. Proven on 32 videos (2026-08-03, `vidfarm-testing/bespoke5/`).
+
+The hard part is not making one good video. It's making thirty good videos that don't read
+as thirty runs of the same template. Everything below exists to prevent convergence.
+
+> ## ⚠️ Read this first
+>
+> **This is a GENERAL FLOW, not a fixed script.** It was captured from one specific run on
+> one machine. Expect it to differ depending on your **machine** (paths, Chrome location,
+> core count, ffmpeg build), your **harness** (how subagents are spawned, whether they can be
+> resumed, background-task behaviour, context limits), and the **AI model** driving it
+> (stronger models need less prescriptive briefs and catch more of their own defects; weaker
+> ones need the checklists spelled out and more revision rounds).
+>
+> Treat the _structure_ as the durable part — split deterministic from judgement work, assign
+> differentiation as an input, review by looking at frames, verify by measurement. Treat the
+> exact commands, flags and file paths as things to re-derive locally. If a step fails, the
+> reasoning behind it is written down so you can adapt rather than guess.
+> use vidfarm.cc/skill.md in cost saving mode with kokoro tts and if image gen is needed, give me the prompt and i will manually generate the images for you to use.
+>
+> **In cost-saving mode, stickers come from IconScout, not from an image model.** `vidfarm
+> iconscout "<thing>" --free` is a $0 designer catalog that needs no key and returns a finished
+> transparent SVG — so the sticker requirement below costs nothing and needs no manual
+> image-gen round trip. **Search with no `--style` filter**: `--style sticker` is nearly empty
+> on the free tier and will fool you into thinking the catalog is bare (§8a has the numbers).
+> Illustrated PEOPLE are the exception — those want `--asset illustration --premium` at ~$0.02.
+> Reach for `sticker-pack --generate` only when the catalog genuinely has nothing that fits.
+> Details and the free-tier credit caveat: §8a.
+
+---
+
+## ⭐ THE GOLDEN RULE — first 3 seconds & first frame
+
+If you remember nothing else from this document, remember this. It is the single biggest
+driver of view-through, and it is the rule that most often has to be enforced against an
+agent's instincts.
+
+1. **The first 3 seconds must be visual eye candy.** Something is **moving and visually
+   interesting from frame 1** — not motion that begins at 1.5s. Lead with the most arresting
+   visual the brand has, not with exposition.
+2. **Never open on a wall of static text** — not a paragraph, not a dense document, not an
+   inert title card, not a table sitting still.
+3. **Frame 0 must work as a thumbnail**, because it will be used as one. That means a
+   **complete headline** — never a half sentence, never a fragment mid-animation.
+4. **These two are compatible:** a striking, already-moving visual _with_ a short complete
+   line over it. That is the target for every single video.
+5. **Say what the product IS by t=5s.** On a *product explainer* the hook is not enough. A
+   viewer who has never heard of the brand must be able to state what it does, in plain
+   English, within the first five seconds — said in the VO and shown on screen. An abstract
+   mood piece that only pays off at 15s fails, however beautiful the motion is. This is
+   compatible with rule 1: lead with the arresting visual **and** land the plain what-it-is
+   under it. (Explainers only — a sizzle reel or a brand film is not bound by this.)
+6. **If the concept genuinely needs a dense or static surface, earn it** — arrive at it
+   through motion instead of cutting to it cold.
+7. **Test it every time:** extract t=0, 1, 2, 3, 4, 5 and look at them. If a viewer would
+   swipe past any of them, **or still could not say what the product is at t=5**, redo the open.
+
+---
+
+## ⭐⭐⭐ THE OPEN MUST BE SIMPLE, AND IT SHOULD CARRY A STICKER (customer directive, 2026-08-14)
+
+The customer's words: *"anytime we make explainer videos the start looks simple and no wall of
+text, and ideally uses relevant stickers if budget allows."*
+
+Rules 1–2 above already say "no wall of static text", and videos kept failing anyway — because
+agents read "wall of text" as "a paragraph" and then open on a **dense interface**, a **six-field
+form**, a **detailed table**, or **three stacked cards each carrying a sentence**. That is a wall of
+text with a layout. This section is the enforceable version.
+
+### 1. Count the text runs in frame 0. Three or fewer.
+
+A **text run** is any contiguous piece of copy the eye has to read: a headline, a label, a field
+value, a caption, a footer URL. Frame 0 gets **at most three**, and one of them is the
+plain-English line. If your open has a headline, a sub-line, four form labels and a footer, it has
+seven, and it will be sent back.
+
+Practical consequences, all learned the hard way:
+
+- **One subject, read large.** One voice letter at 80 px beats four at 40 px. One control lit in a
+  quiet panel beats a form of a dozen fields. When something is removed, **make what remains
+  bigger** — a simplification that leaves the type the same size just creates dead space.
+- **Never open on a form, a settings panel or a table.** If the product's landing state is one,
+  open on the single row that matters and let the rest arrive later, dimmed.
+- **Supporting surfaces carry no readable copy in the open.** Cards behind the subject are shapes,
+  colour fields or one word — not sentences competing with the line.
+- **The footer/URL band does not count as content.** If it is the only thing in the lower third,
+  the frame is empty, not simple.
+
+### 2. A relevant sticker belongs in the first beat
+
+**Put a sticker on screen in the opening beat, ideally in frame 0**, and make it the thing the
+first spoken line is about. It does three jobs at once: it is a moving object for rule 1, it says
+what kind of product this is before any copy is read, and it gives the thumbnail a focal point that
+type alone never gives it.
+
+- **Relevant, not decorative.** The sticker is the subject of the sentence being spoken — an
+  envelope for "send them a link", a football for "fixtures", a receipt for "photograph a receipt".
+  A generic sparkle or checkmark is decoration and does not count.
+- **If the subject is a person or an audience, show them as an illustrated die-cut figure.** The
+  Families Echo cut opens on a grandmother in frame 0, the grandfather joining at 1.2 s and the
+  grandchild at 2.7 s; the family then recurs through the film. That single change did more for
+  that video than any motion work.
+- **Budget: the opening sticker is now nearly always FREE — there is no excuse for not having one.**
+  Look it up first: `vidfarm iconscout "<the thing>" --free` costs $0 and needs no key (credit
+  line required — §8a; search with NO `--style` filter, and use `--asset illustration --premium`
+  at ~$0.02 for an illustrated person). If the catalog has nothing that fits, a generated sheet is
+  ~$0.01–0.05 against a $0.10 cap, so buy it. Authored CSS/SVG is the last fallback, for when the
+  pack comes back wrong or the sticker is really a word-mark.
+- **Recur, do not decorate once.** If a motif is worth opening on, bring it back through the film.
+  Aim for the subject to be present for most of the runtime with no gap longer than ~4 s.
+
+### 3. One sticker on screen at a time — and mind the handover
+
+Two stickers in one place read as a rendering fault, not a transition. Clamp every sticker exit to
+`min(out, nextIn − 0.18)` and **ease `power2.out`, never `power2.in`**. A slow-leaving ease is what
+causes the overlap: with a 0.18 s gap and a cubic ease-in, the outgoing pill is still at ~0.42
+opacity when the next one pops. Sample the sticker band at 0.1 s intervals across every handover and
+confirm exactly one is legible.
+
+### 4. The check
+
+Extract t=0 and count the text runs out loud. More than three, or no sticker in the first beat, is a
+redo — before anything else about the open is discussed.
+
+---
+
+## ⭐⭐ THE PLAIN-ENGLISH LINE — enforce rule 5 as a written input (customer directive, 2026-08-12)
+
+Rule 5 above was in this document already and **two of four videos still failed it** in batch 17.
+The customer's words: *"they need to be more clear on what it is, early asap."* Rule 5 as prose is
+not enough — agents read it, agree with it, and then open on their concept anyway, because the
+concept is the interesting part and the plain line feels like a downgrade. Make it a **deliverable
+you write for them, not a principle you ask them to honour.**
+
+### 1. You write the line. In the brief. Verbatim.
+
+Before you launch the agent, write the sentence yourself into the brief:
+
+> **PLAIN-ENGLISH LINE (must be understood by t=5s):** "Paste a YouTube link, get an MP3 file."
+
+Not "explain what the product is". The actual sentence. One clause, no metaphor, no brand voice, a
+noun and a verb. If you cannot write it in one clause, you do not understand the product yet and
+neither will the agent.
+
+### 2. It must land in BOTH channels, and it must be the FIRST thing said
+
+- **In the VO**, as the **first or second spoken line** — not the third, not after the hook.
+- **On screen**, as type, in the same window.
+- Captions alone do not count as "on screen" if they are just transcribing the VO — that is one
+  channel wearing two hats. There must be an anchor in the art.
+
+### 3. The metaphor is the failure mode — name it in the brief
+
+Every failure looked the same: a strong, ownable **concept** occupying the first five seconds while
+the product went unnamed. Both batch-17 failures were metaphors that pay off beautifully at t=10
+and say nothing at t=3:
+
+| Brand | What the open actually said | What a first-time viewer could NOT say |
+| ----- | --------------------------- | --------------------------------------- |
+| AudioFetcher | "One link in… audio come out", over abstract machine hardware | that it converts a YouTube video into an MP3 file, free, in the browser |
+| IdeaBoxd | "Finish the idea without losing the idea" · "one sentence, typed badly, at a red light" | that it is a place to capture a rough thought and build it into a plan |
+
+Both are *good lines*. Neither is an answer to "what is this?".
+
+**The concept and the plain line are not in competition** — the concept is what makes it worth
+watching, the plain line is what makes it worth installing. Run them together: the metaphor is the
+picture, the plain line is the type over it. Say so in the brief, in those words, or the agent will
+assume you want one or the other.
+
+### 4. Check it on the frames, not on the script
+
+The script always looks like it explains the product, because you already know what the product is.
+Extract t=0–5, read them as images, and **ask the question as a stranger**: from these six frames
+and nothing else, what does this thing do? If the honest answer is "something about audio" or
+"something about ideas", the open fails, whatever the VO says.
+
+A useful harsher version: cover the frames and read only the caption text for the first 5 seconds.
+If that text alone does not identify the product, it is not landing.
+
+### 5. Fixing it later costs a re-record
+
+Unlike the visual defects in §6, this one cannot be fixed by editing the generator — the plain line
+has to be **spoken**, so the VO is re-recorded and every caption timing moves. That is still cheap
+($0, Kokoro + whisper), but it is a full pass rather than a re-render. **Cheaper to write the line
+into the brief than to add it in revision.** This is the single highest-value line in the brief.
+
+---
+
+## 🚀 Slim prompt (start here)
+
+For a quick run, or to hand to another agent, this is the whole method compressed. Expand
+into the full document when you need the commands or hit a bug.
+
+```text
+Build N bespoke product-introduction videos, one per customer URL, for $0.
+They must NOT look like each other — no shared template.
+
+MAIN LOOP (you, deterministically — costs no agent capacity):
+1. For each URL: headless DPR-2 capture of 1440x900 scroll slices, pull the raw HTML,
+   build a 3x3 contact sheet, and sample the palette from the RENDERED hero
+   (luminance < 110 = dark-themed brand → build the video dark; else light).
+2. Write a DIFFERENTIATION list: every concept + motion device already used, plus the
+   generic shapes they occupy (rail through stages, filling a container, tessellating
+   lattice, text morphing, funnel, travelling scan line, cards flying apart, pinned
+   element with swapping background, rings aligning).
+
+PER BRAND (one subagent each, in parallel):
+Give each an ASSIGNED format (9:16 / 16:9 / 4:5 / 1:1), theme (light/dark + temperature),
+energy, type system and VO voice (**default `af_heart`** on Kokoro — assign a different one
+only when the brand gives you a reason) — but make it DERIVE ITS OWN CONCEPT from the brand's own
+words and assets, checking the differentiation list first. Name the predictable answer it
+must avoid. Tell it the palette you sampled is a hypothesis to verify against real CSS.
+
+HARD RULES for every video:
+- First 3 seconds = visual eye candy, motion from frame 1, never static body text.
+- Frame 0 = complete headline, works as a thumbnail.
+- THE OPEN IS SIMPLE: at most THREE text runs in frame 0, one of them the plain-English line.
+  One subject read LARGE — never a form, a settings panel, a table, or three cards each
+  carrying a sentence. Removing an element means enlarging what remains, not leaving a hole.
+- A RELEVANT STICKER IN THE FIRST BEAT, ideally in frame 0 — the subject of the first spoken
+  line, not decoration. If the subject is a person or an audience, use an illustrated die-cut
+  figure. LOOK IT UP FIRST: `vidfarm iconscout "<thing>" --free` is a $0 designer catalog, no
+  key, finished transparent SVG, no keying work (credit line required). Search with NO --style
+  filter (--style sticker is nearly empty on the free tier); for an illustrated PERSON use
+  --asset illustration --premium (~$0.02). Only generate a sheet (~$0.01-0.05 against a $0.10
+  cap) when the catalog has nothing that fits. Then recur the motif.
+- One sticker on screen at a time: clamp exits to min(out, nextIn-0.18), ease power2.OUT
+  (power2.in leaves the outgoing pill at ~0.42 opacity when the next pops — two stickers, one
+  spot, reads as a render fault).
+- By t=5s the viewer must be able to say WHAT THE PRODUCT IS, in plain English.
+  YOU write that sentence into the brief verbatim ("Paste a YouTube link, get an MP3 file"),
+  it is the FIRST or second spoken line, and it appears as type in the art, not only in the
+  captions. Say explicitly that the concept and the plain line run TOGETHER — metaphor as the
+  picture, plain line as the type over it — or the agent ships the metaphor alone.
+- No large flat dead regions; compose for the whole frame.
+- Never let two contradictory numbers share a frame.
+- CTA settled >= 2s before the end.
+- Claim only what the site claims. No real third party named in a negative context.
+- Budget: <= $0.10 per video, and most videos should now land at $0.00. Local Kokoro TTS,
+  local whisper word timings, local render, CC0 music beds, the customer's own graphics AND
+  `vidfarm iconscout --free` stickers are all free. The only sanctioned spend is 1-2
+  `vidfarm sticker-pack --generate` sheets (~$0.01-0.05 each) for stickers the catalog lacks,
+  or `iconscout --premium` (~$0.02 each) when a customer deliverable can't carry the free
+  tier's credit line. Never `vidfarm generate image`.
+- USE STICKERS GENEROUSLY: 5-8 across the video, one per beat, each carrying the meaning of
+  the line being spoken. SEARCH BEFORE YOU GENERATE — `vidfarm iconscout "<thing>" --free`
+  (no --style filter) already has the envelope, receipt, football, calendar and person, in the
+  hundreds-to-thousands, for $0 and with no keying/despill/sheet-splitting work at all. A
+  generated die-cut pack is for objects only this brand has; CSS/SVG stickers are the last
+  fallback, and best for word-marks.
+- Deliver work/<slug>/<slug>.mp4 + NOTES.md. No watermark (applied centrally).
+
+REVIEW (you, not the agent — agents pass their own broken work):
+Extract ~6 frames per video into a contact sheet and LOOK at it. Send back anything with
+dead space, a placeholder that reads as a missing asset, contradictory numbers, superimposed
+headlines, or an unlanded CTA. Then read t=0-5 AS A STRANGER: from those frames alone, what
+does this thing do? "Something about audio" = the open failed, however good the VO reads. Verify audio by measurement (12-15 dB separation, peak < 0).
+
+WATERMARK + DELIVER:
+Tiled diagonal mark, embossed two-tone, two variants (dark pass stronger on light videos,
+light pass weaker on dark videos). Apply with ffmpeg overlay using `-loop 1` on the PNG and
+`-c:a copy`. Then verify each watermarked frame against its OWN clean frame (tiny diff)
+while consecutive frames still differ a lot (motion preserved) — a missing `-loop 1`
+silently freezes the whole video while duration, frame count and audio hash all still pass.
+Keep the un-watermarked masters. Present the cumulative delivery list every time.
+```
+
+---
+
+## 0. The core idea
+
+> **Differentiation is an INPUT, not a hope.**
+> Agents given "make it good" converge. Agents given an assigned format, theme, energy,
+> type system and voice — plus an explicit list of concepts already used — do not.
+
+Split the work:
+
+| Layer                                                            | Who does it                             | Why                                                                                                              |
+| ---------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Deterministic** — capture, palettes, contact sheets, HTML pull | **Main loop**                           | Costs no agent capacity, is identical for every brand, and lets agents spend their whole budget on creative work |
+| **Judgement** — concept, layout, motion, script                  | **One subagent per brand, in parallel** | This is the part that must differ                                                                                |
+| **Review** — frame sheets, defect calls                          | **Main loop**                           | Agents self-report "verified, looks good" on defects that are obvious in a frame                                 |
+| **Watermark + delivery**                                         | **Main loop**                           | Central, uniform, verifiable                                                                                     |
+
+---
+
+## 1. Prerequisites
+
+```bash
+export HYPERFRAMES_PYTHON="<repo>/vidfarm-testing/.venv-kokoro/bin/python"
+export HYPERFRAMES_SKIP_SKILLS=1 HYPERFRAMES_NO_TELEMETRY=1
+```
+
+- `vidfarm` + `hyperframes` on PATH; `.venv-kokoro` holding `kokoro-onnx` + `soundfile`
+- `fonts/*.woff2` (self-host; a Google Fonts `<link>` trips lint)
+- `bgm/hp_c*.wav` — CC0 beds, already high-passed 200 Hz ×2
+- Copy in: `capture.mjs`, `audio.sh`, `watermark.py`, `PLAYBOOK.md`, `DIFFERENTIATION.md`
+
+Everything else is local and keyless: Kokoro TTS, whisper timings, local render, CC0 music.
+**IconScout sticker search is also free and needs no key** (`vidfarm iconscout "<thing>"
+--free`, no `--style` filter) — it is the first place to look for any generic object, and it is
+what keeps a `$0.00` run at `$0.00`. The remaining sanctioned spend is the generated sticker
+pack (§8a) at **<= $0.10 per video**, for the stickers the catalog does not have.
+**Never** call `vidfarm generate image` — that is a different, unbudgeted job. If a full AI
+image would genuinely help, write the prompt to `AI_PROMPTS-<slug>.md` and ship without it.
+
+---
+
+## 2. Phase 1 — recon (main loop, ~10 min for 12 sites)
+
+Run in **waves of 4–5**; more than that and headless Chrome starts timing out.
+
+```bash
+# a) headless DPR-2 capture — 1440x900 scroll slices (already 16:10, so one slice = one
+#    "browser card" with zero crop tuning)
+LOCALE="en-US,en;q=0.9" node capture.mjs <slug> <url> > cap-<slug>.log 2>&1
+
+# b) raw HTML for every site (server-rendered copy, CSS tokens, asset URLs)
+curl -sL -A "<desktop UA>" -H "Accept-Language: en-US,en;q=0.9" --max-time 45 "$url" \
+  -o "recon/<slug>.html"
+
+# c) contact sheet per site — ONE image read instead of 8
+ffmpeg -y -pattern_type glob -i "shots/<slug>/home-s*.png" \
+  -vf "scale=440:-1,tile=3x3:margin=6:padding=6:color=0x888888" -frames:v 1 "sheets/<slug>.png"
+
+# d) palette sampled from the RENDERED hero (not the CSS) — this is what reveals dark vs light
+```
+
+Palette sampler: most-common colours of `home-s00.png` downsampled 8×; luminance < 110 = DARK.
+
+**Treat the sampled palette as a hypothesis, not fact.** Across 32 videos agents overturned
+it perhaps a third of the time and were right every time — it had been sampled off a hero
+_photograph_, a seasonal login page, or Google Play's own chrome. Always tell the agent to
+confirm against the compiled CSS custom properties and to say so if it overturns.
+
+**Special cases seen in the wild:**
+
+- **Blank/tiny capture** → it's an app whose landing state is a form. The agent must _drive_
+  it headlessly (adapt `capture.mjs` into `work/<slug>/drive.mjs`; never edit the shared one).
+- **Tiny HTML shell** → SPA. Harvest the JS bundle for asset paths + verbatim copy, and the
+  compiled CSS for tokens. **Check `manifest.json` → `screenshots[]` FIRST** — it repeatedly
+  held ten real store screenshots on apps I'd written off as unreachable.
+- **No website at all** (Play/App Store listing only) → the listing IS the asset base. Pull
+  every screenshot at max resolution. **Do not use the store's chrome colour as the brand.**
+- **Animated WebP/GIF on the site** → free motion footage. Extract frames with Pillow → build
+  a sprite sheet → drive it off the paused timeline. Unlike `<video>` it can be base64-inlined
+  and stays seek-safe.
+- **A real screen recording in the bundle** → that's your A-roll. Best asset find of the run.
+
+---
+
+## 3. Phase 2 — the differentiation matrix
+
+Maintain `DIFFERENTIATION.md` across the whole engagement. Two sections:
+
+**(a) Concepts already used** — a table of brand → concept → motion device, appended after
+every batch. Agents must read it and must not reuse or reskin any row.
+
+**(b) Forbidden generic shapes** — the abstractions those concepts occupy. After 20 videos
+this list was:
+
+> a progress rail advancing through N labelled stages · items dropping/filling a container ·
+> a grid/lattice tessellating as a transition · text morphing into other text · a funnel
+> narrowing many to one · a scan/sweep line travelling across a surface and changing it ·
+> cards flying apart and snapping back together · one element pinned while the background
+> swaps · concentric rings resolving into alignment
+
+Also steer each agent off **its own most predictable answer** by name: no waveform for a
+music app, no node-graph for something called Nodebase, no word-flip-to-translation for a
+language app, no stage-rail for a project tool.
+
+**Where good concepts come from:** every strong one came from something the brand already
+said or showed — umadum's own "No more FOMO", SkillDiscs' "two front doors", Halvy's "split
+costs right down the middle", Sync.camera's "reveal live, or at the end". Tell the agent to
+find the one idea that is _theirs_ and build the motion around it.
+
+---
+
+## 4. Phase 3 — the agent brief (THE REUSABLE PROMPT)
+
+One subagent per brand, all launched in parallel. Template:
+
+---
+
+> Build ONE bespoke product-introduction video for **<BRAND>** (<URL>). Slug: `<slug>`.
+>
+> Read FIRST, in this order: `PLAYBOOK.md` (the $0 pipeline, the **first-3-seconds hard
+> requirement**, and the renderer-bug section) then `DIFFERENTIATION.md` (concepts already
+> used — do not reuse; you derive your own concept from the site).
+>
+> Set up: `export HYPERFRAMES_PYTHON="$PWD/../.venv-kokoro/bin/python" HYPERFRAMES_SKIP_SKILLS=1 HYPERFRAMES_NO_TELEMETRY=1`
+>
+> ## Recon done for you
+>
+> - `sheets/<slug>.png` — contact sheet of all N slices. **Read this first** (one image read),
+>   then read only the 2–4 slices you actually want from `shots/<slug>/`.
+> - `recon/<slug>.html` — raw HTML. Mine for verbatim copy, asset URLs, compiled CSS tokens.
+> - Palette sampled from the rendered hero: stage `<hex>`, panels `<hex>`. **<DARK|LIGHT>.**
+>   Verify against the real CSS and overturn it if it's wrong — say so if you do.
+> - <any special-case note: SPA / drive-the-app / store-listing-only / animated WebP>
+>
+> ## Assigned direction — the other agents in this batch have very different briefs; do not converge
+>
+> - **Format: <1080x1920 | 1920x1080 | 1080x1350 | 1080x1080>.**
+> - **Theme: <LIGHT|DARK>** <+ the specific temperature: warm charcoal vs cold slate vs pure black>
+> - **Energy: <one line>.** <Name which other videos in the batch are calm/punchy so this one
+>   leans the right way.>
+> - **Type:** <2–3 candidate faces from `../fonts/`>, matched to the site's real faces.
+> - **VO: `af_heart`** (the default — see §4a) _or_ `<bf_emma|am_adam|am_michael|bm_george>`
+>   when the brand calls for it — <why this brand is an exception, if it is>.
+> - **Concept: derive it yourself** from the site's own strongest idea. Check
+>   `DIFFERENTIATION.md` first. <Name the predictable answer to avoid.>
+>
+> ## Accuracy (non-negotiable)
+>
+> Claim only what the site claims — platform, price, ratings, compliance. Don't upgrade
+> "built on X guidelines" into an endorsement. Never let two contradictory numbers share a
+> frame. <Any brand-specific care: no fear-selling, no medical authority, no named third
+> party in a negative context, keep humour off real identifiable businesses.>
+>
+> Aim <20–30>s. Deliver `work/<slug>/<slug>.mp4` + `NOTES.md` (concept in one sentence, VO
+> script, assets and where they came from, bed id, customer flags). **Do not apply a
+> watermark** — that happens centrally. Do not publish or approve.
+>
+> Report back: path, duration, what the product actually is, your concept in one sentence,
+> and anything you'd flag.
+
+---
+
+## 4a. Voice — `af_heart` is the default
+
+**Use `af_heart` on local Kokoro (`--engine local`) unless there is a specific reason not
+to.** It is warm, even, and unobtrusive; it sits under a wide range of brands without
+fighting them, and it does not editorialise the copy. Assigning it as the default also
+removes one more axis on which agents can make an arbitrary choice.
+
+**Deviate when the brand gives you a reason**, not for variety's sake. Real reasons:
+
+| Voice        | Reach for it when                                                          |
+| ------------ | -------------------------------------------------------------------------- |
+| `af_heart`   | **default** — warm, even, unobtrusive; correct for most brands              |
+| `bf_emma`    | bright and brisk — a utility product sold on speed, a punchy high-key piece |
+| `bm_george`  | dry, measured, understated — editorial restraint, confidence without a pitch |
+| `am_michael` | low and unexcited — severe, clinical, instrument-like reads                  |
+| `am_adam`    | plain and neutral — when the copy must carry everything itself               |
+
+The test is whether you can state the reason in one clause in the brief. "The read should
+move because the product is sold on speed" is a reason. "For variety across the batch" is
+not — differentiation is carried by format, theme, energy, type and concept, which is far
+more visible than voice. A batch where three of four videos use `af_heart` is fine.
+
+**Whatever you pick, these still apply:**
+
+- **Say the reason in the brief.** The agent should know why it has that voice.
+- **Check the brand name's pronunciation** and spell it phonetically in the TTS input if
+  needed — Kokoro said "Jenki" for *Genki* until the input was respelled "Ghenki". Confirm
+  with a whisper round-trip, since you are also running whisper for word timings anyway.
+- **For a calm, unhurried read, render line-by-line** — separate Kokoro takes concatenated
+  with measured silences — so the pauses are real instead of TTS filler. One continuous
+  pass reads rushed however slow the copy is.
+- **Non-English needs `--model large-v3 --language <code>` on whisper.** The default model
+  is English-only and will hallucinate fluent English over another language (see §10).
+
+---
+
+**Sandbox discipline:** each agent owns `work/<slug>/`, `assets/<slug>/`, `shots/<slug>/`,
+`recon/<slug>.*`. Shared read-only: `bgm/`, `../fonts/`, `capture.mjs`, `audio.sh`, the two
+markdown files. Tell them explicitly never to edit another slug's files or the shared scripts.
+
+**Scale:** 5 agents at a time is comfortable; 10–12 works. Recon in waves regardless.
+
+---
+
+## 5. THE FIRST 3 SECONDS — hard requirement (enforcement detail)
+
+This restates the ⭐ Golden Rule at the top of this document, in the form that goes into
+`PLAYBOOK.md` for the agents. It is repeated deliberately — it is the rule most often lost.
+
+- **Never open on a wall of static text** — not a paragraph, not a dense document, not a
+  full-width headline sitting still, not a table.
+- **Something must be MOVING from frame 1**, not motion that starts at 1.5s.
+- **Lead with the most arresting visual you have, not with exposition.**
+- **Frame 0 must still work as a thumbnail** — a complete headline, never a half sentence.
+  These two requirements are compatible: a striking visual _with_ a short complete line.
+- If the concept genuinely needs a dense/static surface, **earn it** — arrive at it through
+  motion. (The "jargon → plain English" video flies the radiology page in at 62° with motion
+  blur under a hook line, then sweeps a scan line across it. Concept intact, hook fixed.)
+- **Test it:** extract t=0, 1, 2, 3. If a viewer would swipe past any of them, redo the open.
+
+---
+
+## 6. Phase 4 — the review loop (this is what makes them good)
+
+**Every single first-pass video in batch 1 had a real defect that its own agent reported as
+"verified, looks good."** Do not skip this.
+
+```bash
+for t in 0 5 10 15 20 25; do ffmpeg -y -ss $t -i <slug>.mp4 -frames:v 1 qa/f$t.png; done
+ffmpeg -y -pattern_type glob -i "qa/f*.png" \
+  -vf "scale=360:-1,tile=3x2:margin=6:padding=6:color=0x999999" -frames:v 1 qa/sheet.png
+# then READ qa/sheet.png as an image
+```
+
+What this catches, in observed frequency order:
+
+0. **The product is never plainly named in the first 5 seconds** — the open is a metaphor.
+   Two of four in batch 17. See the PLAIN-ENGLISH LINE section; this is the one defect that
+   costs a VO re-record, so catch it in the brief instead.
+1. **Large flat dead regions** — content top-anchored with an empty band below. Agents do
+   this constantly and never notice.
+2. **A placeholder empty state that reads as a missing asset** — a big empty dashed rectangle
+   held for 2s looks like the render failed.
+3. **Two contradictory numbers in one frame** (~200px apart, on a data product).
+4. **A CTA still building when the video ends** — it must be settled ≥2s before the last frame.
+5. **Two headlines superimposed at a scene handoff** — see the clamp rule below.
+6. **Type colliding with a busy background layer** (pins, particles) exactly as it's spoken.
+
+If a frame looks empty, **check whether it rests there**: sample at 0.2–0.25s intervals
+through the transition. A transient near-empty wipe frame is fine; >0.5s is not.
+
+**Verify audio by measurement, not by ear** (you can't hear it):
+speech RMS over whisper word spans, minus bed-alone RMS. Target 12–15 dB, peak < 0 dBFS.
+Note `audio.sh`'s printed "delivered separation" measures the **music-only tail**, not
+in-speech separation — it over-reports. Don't "fix" a mix based on it.
+
+---
+
+## 7. Phase 5 — revision agents
+
+**A completed subagent could not be resumed** (`SendMessage` failed by both id and name).
+Spawn a _fresh_ fix-agent instead. This works well because every agent leaves a `NOTES.md`.
+
+Fix-brief template:
+
+> A previous agent built a finished video for <BRAND>. It's good — you are making <N>
+> targeted fixes, nothing else. Read `PLAYBOOK.md` and `work/<slug>/NOTES.md`. Edit the
+> **generator**, not the generated `composition.html` (check one exists — some are hand-authored).
+> **Back up to `work/<slug>/<slug>-v1.mp4` before overwriting.**
+> Keep VO, script, captions, bed and duration identical — re-running the audio step reuses
+> the existing `vo.wav`/`words.json` so audio stays bit-identical; no re-record, no retiming.
+> <the defects, each with the timestamp and what's wrong>
+> Then sweep the whole video for the same class of problem and report what else you found.
+> Verify by extracting the same timestamps and **reading them as images**.
+
+Give the agent the _problem_, not just your proposed solution — three times an agent found a
+better fix than the one I specified (using an app's own collapsed UI state instead of
+redacting; a type safe-zone solver instead of a scrim; making a document's _arrival_ the
+spectacle instead of cutting the document).
+
+---
+
+## 8. Phase 6 — watermark (two variants)
+
+`watermark.py <W> <H> <autolight|autodark> <out.png> [opacity] [fs_frac] [gapx_frac] [gapy_frac]`
+
+Tiled diagonal text at 30°, offset every other row into a diamond lattice, scaled to the
+frame's **short edge** so it reads the same at 9:16, 16:9, 4:5 and 1:1.
+
+**Embossed two-tone** — a dark pass offset one pixel under a light pass — because every one of
+these videos mixes light and dark surfaces. A single-tone mark vanishes over content of its
+own polarity (black-on-white disappeared over a dark screenshot sitting in a light frame).
+
+- `autolight` — dark pass ×1.7, light pass ×1.0. Black needs more alpha to read on white.
+- `autodark` — light pass ×0.55, dark pass ×1.2. White-on-near-black is the highest-contrast
+  pairing there is and _glares_ at equal alpha.
+
+Shipped settings: `0.10 opacity, 0.048 size, 0.20/0.105 gaps` (~52px type on a 1080 frame).
+
+```bash
+cp work/$s/$s.mp4 work/$s/$s-clean.mp4          # preserve the un-watermarked master
+ffmpeg -y -i work/$s/$s-clean.mp4 -loop 1 -i wm/$s.png \
+  -filter_complex "[0:v][1:v]overlay=0:0:shortest=1:format=auto[v]" \
+  -map "[v]" -map 0:a -c:v libx264 -crf 17 -preset slow -pix_fmt yuv420p \
+  -c:a copy -movflags +faststart work/$s/$s.mp4
+```
+
+> ### The `-loop 1` is not optional — I shipped 5 broken videos without it
+>
+> A single-frame PNG as a plain second input made the frame-sync **collapse every video onto
+> one frozen frame**. Duration, frame count and audio hash all survived, so a naive check
+> passed. **Always verify by comparing each watermarked frame against its OWN clean frame**
+> (difference should be tiny — the mark only) **while consecutive frames still differ a lot**
+> (motion preserved). Never verify a video by one frame.
+
+---
+
+## 8a. Stickers — use them GENEROUSLY (customer directive, 2026-08-12)
+
+> *"use stickers to help explain where possible"* — and the follow-up: **be more generous with
+> them.** The budget was raised from $0.00 to **$0.10 per video** specifically to pay for this.
+
+### How many
+
+**5–8 stickers across a 20–30 s video — roughly one per beat.** One or two per video is the old,
+too-timid setting; it reads as decoration rather than as a way of explaining. The ceiling is one
+sticker on screen at a time, not one per video.
+
+A sticker **carries the meaning of the line being spoken at that instant**. It is not garnish. If
+the VO says "spam recovery", the sticker is the thing that says *spam recovery* — and then the
+caption tile and the sticker between them are the whole frame, with no headline needed.
+
+### Where they come from
+
+**In cost-saving mode, look them up on IconScout before you generate anything.** A designer
+already drew the envelope, the receipt, the football and the grandmother. `vidfarm iconscout`
+searches that catalog and hands back a finished transparent SVG or PNG on the first try — no
+prompt loop, no keying, no despill, no off-by-one item naming, and none of the sheet-splitting
+work in the next section. **Search costs nothing and needs no key**; vidfarm's own IconScout
+account serves it.
+
+```bash
+vidfarm iconscout "envelope" --free                      # search — $0, no wallet cost
+vidfarm iconscout get <uuid> --format svg --out stickers/envelope.svg
+```
+
+### Do NOT lead with `--style sticker` on the free tier — it is nearly empty
+
+This is the one trap, and it is counter-intuitive because `sticker` is the style this document
+wants. Measured against the live catalog (2026-08-16), free `icon` results:
+
+| query | free, no style | free `sticker` | free `flat` | free `colored-outline` | **premium** `sticker` |
+| --- | --- | --- | --- | --- | --- |
+| envelope | **1629** | 1 | 214 | 226 | 539 |
+| receipt | **727** | 3 | 109 | 116 | 314 |
+| calendar | **3462** | 12 | 445 | 494 | 1090 |
+| person | **8259** | 54 | 1103 | 1166 | 3934 |
+| grandmother | **77** | 0 | 46 | 3 | 32 |
+
+**Search free with no `--style` first.** An agent that runs `--style sticker --free`, gets one
+result, and concludes "IconScout has nothing" will fall straight back to generation — which is
+exactly the waste this section exists to prevent. Narrow with `--style flat` or
+`--style colored-outline` if the raw list is too varied; both keep hundreds of results and both
+read well die-cut. Save `--style sticker` for `--premium` — the last column above is why.
+
+### Illustrated figures are the premium case
+
+The doc's own hero example — the grandmother in the Families Echo open — is the weakest free
+query there is: **0** free sticker-style icons, **4** free illustrations, but **3013** premium
+illustrations. Free `illustration` is thin across the board (envelope 16, grandmother 4) while
+premium is enormous (envelope 9087, person 158k). So:
+
+- **Objects** (envelope, receipt, calendar, football) → `--free`, no style filter. Plenty.
+- **People and illustrated scenes** → `--asset illustration --premium`, ~$0.02. This is the
+  right place to spend the cap, and it is cheaper than a generated sheet.
+- `--asset 3d` for a prop with real depth (free is moderate: envelope 33, person 357),
+  `--asset lottie` for something already animated.
+
+**Which tier:**
+
+| | Cost | Credit line | Use it when |
+| --- | --- | --- | --- |
+| `--free` | **$0** | **required** | Generic OBJECTS, no `--style` filter. The `$0.00` mode. |
+| `--premium` | ~$0.02 each on the wallet | none | People, illustrated scenes, `--style sticker`, or any customer deliverable that can't carry a credit line. ~4 fit inside the $0.10 cap. |
+| `sticker-pack --generate` | $0.01-0.05 per sheet of 3-4 | none | Nothing in the catalog fits, or the sticker is bespoke to the brand |
+
+> **⚠️ Confirm the free-tier credit obligation before shipping a customer deliverable.**
+> IconScout's free tier carries an attribution requirement, and the download response returns
+> the credit string in `attribution` with `attribution_required: true`. I could not read
+> IconScout's own licence page to pin down the exact wording or where the credit has to appear
+> (it is behind Cloudflare), so **check it yourself before a paid customer video ships with a
+> free asset in it.** If the credit is awkward for the brand, spend the ~$0.02 on `--premium`
+> — that is four premium stickers inside the same cap that buys two generated sheets, and it
+> is still the cheapest thing in this pipeline.
+
+**Then fall through to generation.** A generated die-cut pack is the answer when IconScout has
+nothing that fits — a brand-specific object, a made-up device, a character that has to match a
+particular illustration style. One billed image job produces a whole sheet:
+
+```bash
+vidfarm sticker-pack --generate "<style line>" \
+  --items "a;b;c;d" --key-color "#FF00FF" --out-dir stickers
+```
+
+All of the following is generation-only housekeeping — an IconScout asset arrives already
+die-cut and needs none of it:
+
+- **3–4 items per sheet.** The sheet is 1024x1024 whatever you ask for, so 8 items is ~200 px each
+  and mush on a 1080-wide canvas. 3–4 gives ~400 px. **Buy two sheets** — that is what the cap is for.
+- **Pick the key colour off the BRAND hue.** Magenta eats a purple brand; use orange. Never green.
+- Put **"NO texture, NO grain, NO paper effect, NO shadows"** in the style line.
+- **Always eyeball a LABELLED contact sheet and rename before use.** Item names go off-by-one
+  whenever a count mismatch is reported, and several items regularly segment as one blob — split
+  it with `scipy.ndimage.label` on a dilated alpha.
+- **Expect soft alpha** and harden it: `a = clip((a-25)/(110-25))*255`, plus a despill
+  `spill = max(min(r,b) - g, 0)*0.85; r -= spill; b -= spill`, then re-crop to the new bbox.
+  Un-hardened stickers look like a faint watermark over footage, not like a keying bug.
+- **Recolour to the exact brand hex** — mask the saturated pixels and remap scaled by each pixel's
+  own brightness, so the shading survives and only the hue changes.
+
+**CSS/SVG stickers remain a legitimate fallback** (now the third option, after IconScout and a
+generated sheet) — a shape on a flat brand blob with a 6–10 px
+white die-cut rim, a drop shadow and a −8°..+8° rotation. Use them when the pack came back wrong,
+when the budget is spent, or when the sticker is really a word-mark (`32 TOOLS`, `FREE €0`,
+`ZERO ACCOUNT REQUIRED` all worked better as authored type than they would have as generated art).
+A mixed pack is fine and usually best: **IconScout for anything generic** (envelope, receipt,
+football, calendar, person), generated art for objects only this brand has, authored type for
+word-marks.
+
+### How they move
+
+Pop in with overshoot — `back.out(2.2)`, 0.28–0.34 s — and give every sticker a slow idle drift so
+nothing on screen is ever dead still. Never place one over the caption band, over a face, or over a
+number the viewer has to read.
+
+### Stickers as masks
+
+A sticker silhouette can be a window onto a real screenshot crop — but only at **≥ 440 px**, and
+only over a **dense, colourful** crop (a whole product card, not page whitespace), or the shape
+reads as a broken asset. Two stacked layers: the sticker as generated behind (keeps the white rim),
+the screenshot in front masked by an **eroded** copy of the alpha (fill holes → erode ~13 px →
+gaussian 1.2) so the rim survives.
+
+---
+
+## 9. Phase 7 — delivery
+
+- Final = **watermarked** `work/<slug>/<slug>.mp4`; keep `-clean.mp4` masters for customers.
+- Copy out with numbered, brand-named files so they sort in delivery order.
+- Verify each copy for dimensions, duration and **presence of an audio stream**.
+- **Present the cumulative list every time** — every job shipped so far, not just this batch.
+- Tag anything language-specific in the filename (e.g. `24-cap-horizon-FR`).
+
+---
+
+## 10. Renderer gotchas (all found the hard way)
+
+**Silent failures — the render "succeeds" and is wrong:**
+
+- **Assets outside the composition root → timeline never runs.** Only `<style>`/`<script>`
+  _inside_ the `data-composition-id` root execute, and sibling relative files don't resolve —
+  fonts, images and **GSAP itself** may need inlining. Symptom: every frame identical, but
+  frame 0 looks fine. _Compare two frames from different scenes, never one._
+- **~450 tweens broke timing globally** — every `.to()` rendered 1.0s early in stills _and_
+  the real render; `.set()`s stayed exact. Reducing the tween count fixed it (one clipped
+  fully-lit duplicate riding a mask, not one tween per element).
+- **GSAP suppresses `onUpdate` while seeking a paused timeline** — counters lag or never fire.
+  Pre-bake values and reveal with `tl.set`.
+- **Timed `<video>` gets no z-index from `data-track-index`** — a sibling with CSS `z-index`
+  paints over it and it renders as a blank card.
+
+**SVG transforms are unsafe — treat CSS transform props on SVG as broken:**
+
+- `transform-box: fill-box` fights GSAP's user-space origin: nodes scale in 20–40px off
+  position. Pass explicit `svgOrigin`.
+- `scaleY` on an `<rect>` with `transform-box` **translates it out of position** rather than
+  scaling about centre. Tween `attr:{y,height}` instead.
+
+**Layout / compositing:**
+
+- Smooth alpha ramps in CSS gradients mis-composite into banded colour with black wedges —
+  use flat opaque shapes and hard stops.
+- `#root`'s own CSS `background` is never painted — add a full-bleed `<div>`.
+- `clip-path: inset()` is relative to the **element's** border box, not the page.
+- GSAP scale/x tweens break `transform:translateX(-50%)` centring — centre structurally.
+- `<video>` projects need `HF_VIDEO_COVERAGE_THRESHOLD=0` (the gate false-positives at ~94%).
+
+**Media:**
+
+- Relative `img/*` paths render as broken placeholders in the multi-worker renderer even
+  though `stills` looked fine → **base64-inline every image** before the real render.
+- Transparent RGBA PNGs go **black** when encoded as JPEG — composite onto the stage colour first.
+- `<video>` cannot use a data URI at all.
+- A root `<audio>` tag fails the local render — strip it and mux audio on afterwards.
+
+**Timing / audio:**
+
+- **Never `adelay` the VO** — whisper timings (and your captions) are relative to raw `vo.wav`.
+  Use `apad` + `atrim`.
+- Clamp caption fade-out against the next tile: `outAt = max(inAt+.22, min(end+.12, nextIn-.17))`.
+  The same rule fixes superimposed scene headlines — exit at `nextIn − 0.18`, duration 0.24,
+  ease `power2.out` (a slow-leaving `power2.in` is what causes the overlap).
+- Scene handoffs can leave ~0.3s empty frames — extend each clip ~0.35s into the next.
+- `vidfarm tts` reads stdin — always `</dev/null` inside a loop.
+- Whisper's default model is **English-only** and will hallucinate fluent English on other
+  languages — non-English needs `--model large-v3 --language <code>`.
+- Beat-locking: measure the bed's BPM and first downbeat, then trim the bed at a **measured
+  downbeat** — `audio.sh`'s default `-ss 2` will knock it out of phase.
+
+---
+
+## 11. Accuracy & judgement rules
+
+These protect the customer, and several came from real near-misses:
+
+- **Claim only what the site claims.** Not a shipped iOS app if the site says "iOS in the
+  works". Not an endorsement if they say "built on X guidelines". No install counts or
+  ratings unless quoted exactly.
+- **Never name a real third party in a negative or bias-implying context** in a customer's
+  marketing asset — even when the product's own output does it. Find the product's own
+  neutral state instead.
+- **Keep humour aimed at the problem, not at a real identifiable business or person.** Use a
+  fictional example on an IANA-reserved `.example` domain.
+- **No fear-selling** on safety/family/health products; no medical authority beyond the claim.
+- **Licence obligations stay on screen** (e.g. OpenStreetMap attribution) for the full runtime.
+- **Flag personal data** — real names, faces, emails in a customer's own screenshots are
+  already public but should be a conscious decision, not an accident.
+- **Read the whole asset before calling a customer's data inconsistent.** "519 hexes" vs
+  "312 hexes" was a national total vs a row inside the same card; the bug was ours.
+- **Collect what's broken on their site as a deliverable.** Across 32 brands we found
+  contradictory stats, a demo dataset that undercut the product's own pitch, plaintext API
+  keys in a JS bundle, an invisible store badge, a `vercel.app` preview URL in production
+  marketing, typos, and an app icon that reads as the wrong country's flag. Customers value
+  this more than the video sometimes.
+
+---
+
+## 12. Cost
+
+**Budget: <= $0.10 per video** (raised from $0.00 on 2026-08-12, customer directive).
+
+Everything except stickers is still free and stays that way: Kokoro TTS (`--engine local`),
+whisper timings, local render, CC0 beds already on disk, the customer's own graphics.
+
+**Stickers can now be free too.** `vidfarm iconscout "<thing>" --free` is a $0
+designer catalog that needs no key — so a video whose stickers are all generic objects
+(envelope, receipt, calendar, person) can go back to costing **$0.00** with no loss of quality.
+The price of the free tier is a credit line; see the warning in §8a before putting one in a
+customer deliverable.
+
+Spend, in the order you should reach for it:
+
+| | Cost | Buys |
+| --- | --- | --- |
+| `iconscout --free` | **$0.00** | generic objects, unlimited, credit line required |
+| `iconscout --premium` | ~$0.02 each | illustrated people/scenes, ~4 inside the cap, no credit line |
+| `sticker-pack --generate` | $0.01-0.05 per sheet | 3-4 bespoke stickers per sheet, no credit line |
+
+The cap still buys two generated sheets if you need them — but on most videos you will not,
+because the catalog already has the object. **Search before you generate.**
+
+Still never `vidfarm generate image` — a full AI image is a different, unbudgeted job. If one
+would genuinely help, write the prompt to `AI_PROMPTS-<slug>.md` and let the human run it.
+
+---
+
+## 13. What "unique" actually looked like
+
+For calibration — 32 concepts, no reuse, all derived from the brand's own material:
+
+evidence chain · knowledge graph forking into two front doors · ink bleeds · hex fill ·
+one spectrum bar transformed seven ways · jargon dissolving into plain English · organic
+bloom · map pins dropping · a 3-gate signal funnel · buckets filling 50/30/20 · one pinned
+query bar with the world swapped beneath · a light-sweep painting a blank room · a skills
+orbit collapsing inward · a wardrobe reading you back · two calendars colliding into a rest
+shadow · overlapping arcs interlocking into one morning · a screen recording receding into
+an annotated spec sheet · three silos snapping into one story · brand palettes flipped like
+a record crate · a mountain mirrored in a lake · a table for two widening to seat four · a
+group chat settling up · a thread you send to yourself · a navigator's horizon with three
+bearings · two plates snapping into perfect register · latent prints developing in place ·
+a word prompter on the downbeat · an empty seat at the boardroom table · call and response ·
+a waveform as the only constant while the pictures are disposable · a lock screen waking
+five times across one day · the frame itself split down the middle.