@officexapp/vidfarm-devcli 0.21.51 → 0.21.53

package/experimental/meme-recaption.md

@@ -0,0 +1,1756 @@
+---
+name: meme-recaption
+video_type: Meme recaption — one borrowed meme clip, one new caption, aimed at the problem space of the offer (TikTok / Reels / Shorts)
+checks:
+  duration_sec: 4-15
+  aspect: 9:16
+  first_frame_visual: required
+  first_frame_text: required
+  text_by_sec: 0          # the caption IS the video. It is up at frame 0 or the format did not happen
+  captions: optional      # the caption is a static CARD, not a subtitle track. See "Typography DNA"
+  audio: required         # the meme's own audio is usually the punchline — see "Audio DNA"
+  font_regime: required
+  safe_zone: required
+  scenes: 1-2
+  max_scene_sec: 15
+  max_text_cards: 3       # the caption, the offer handle, and (rarely) a second-beat turn
+  max_simultaneous_text: 2
+  max_words_per_cue: 22   # a meme caption is ONE read, not a paged subtitle
+  max_dead_air_sec: 15    # there is no dead air in a meme — a hold IS the joke
+  max_tail_sec: 0.8
+  forbid_text:
+    - link in bio
+    - sign up
+    - free trial
+    - get started
+    - book a demo
+    - download now
+    - learn more
+    # the bait lives in the POST caption, never on the meme:
+    - comment below
+---
+
+# Meme Recaption
+
+> A public Vidfarm prompt. Read it end to end before you build. It assumes the offer has a
+> **problem space** — a recurring, annoying, nameable experience the product removes. If it does
+> not, this format has nothing to write about and you should use `ugc-reaction-greenscreen`.
+
+You are not making an ad. You are making **a meme that happens to be about the thing the product
+fixes.** The distinction is the whole file. A meme that is secretly an ad gets read as an ad in
+about 400ms and dies. A meme that is actually a meme gets shared by people who have never heard of
+the product, and a fraction of them go looking.
+
+Two ingredients, no more:
+
+| Ingredient | What it is | Where it comes from |
+|---|---|---|
+| 🎬 **The meme** | A borrowed clip everyone already half-recognises, doing one absurd physical thing | `vidfarm.cc/explore` → public raws, `sourceType: MemeScreens` (851 of them, once you page past what the CLI shows you) |
+| ✍️ **The caption** | One sentence naming a specific lived experience, in the second person or the first | You. This is the only original work in the video, and it is 90% of the outcome |
+
+**The offer is named on the video.** First choice: inside the caption, as a character in the setup
+(`dishcover.io watching me open 10 tabs since 7pm…`). Fallback when that will not read elegantly: a
+small dimmed handle under the caption plate. Rule 1 is the whole decision.
+
+**What the offer never is: the answer.** No logo, no screenshot, no feature, no CTA, and never in
+the caption's final clause. The product can stand in the joke; it cannot end it. The *experience the
+caption names* is the one the product removes, and that stays implicit — that is the format's entire
+mechanism, and every failure mode below is a variation on breaking it.
+
+## The one test — the three-way lock
+
+Three questions. **All three must be yes** or you have not got a meme recaption yet.
+
+| # | Question | If no |
+|---|---|---|
+| 1 | **Standalone** — Show it to someone who has never heard of the offer. Do they laugh? | You wrote an ad with a meme stapled on |
+| 2 | **Problem space** — Is the experience it names one the product actually removes? | You wrote a meme. Funny, worthless. Post it from a personal account |
+| 3 | **Enactment** — Is the meme's *physical action* the literal body of the feeling the caption names? | You wrote a caption over stock footage |
+
+Test 3 is the one editors skip, and it is the one that separates a meme that lands from a caption
+sitting on top of a clip. The meme is not an illustration of the caption. **The meme is what the
+caption's subject is doing with their body.** If the caption says "quietly giving up" and the clip
+is someone dancing, the joke has no floor, and no amount of caption polish will give it one.
+
+---
+
+## Part 0 — who this is for
+
+**Not the customer's buyer in general — the customer's buyer at one specific bad moment.** Before
+you write anything, put two lines at the top of your build log:
+
+```
+WHO:    <the person, in six words>
+MOMENT: <the exact 30 seconds of their life the product exists to delete>
+```
+
+Everything below is decided by the second line. A meme recaption is a **compressed complaint**, and
+you cannot compress a complaint you have not located.
+
+- **Register:** a peer, posting at 11pm, mildly annoyed, not selling anything.
+- **Never a brand voice.** No "we", no "introducing", no feature words. The offer's *name* may be in
+  the caption as a character (Rule 1); brand *voice* never is.
+- **The joke is on the shared situation, or on you. Never on the viewer**, and never on a named
+  real competitor.
+
+---
+
+## Structural DNA — there are no beats
+
+This is the rule every agent breaks, so it goes first and in bold.
+
+> **A meme recaption is ONE shot with ONE caption, and both are on screen at frame 0.**
+
+No hook beat, no concession beat, no payoff beat, no bait card. No cuts. No build. The four charges
+(hook / loop / payoff / bait) still exist, but they **fire simultaneously**, not in series:
+
+| Charge | Where it lives in a meme recaption |
+|---|---|
+| 🪝 Hook | The caption's first three words, plus the fact that the visual is instantly weird |
+| 🔄 Loop | The ~0.8s gap between finishing the caption and the clip's action landing. That is the entire loop |
+| 😍 Payoff | Recognition — "this is literally me". Not a product reveal. There is no product |
+| 🎣 Bait | **The post caption, not the video.** An on-screen "comment below" turns a meme back into an ad. The handle is attribution, not bait |
+
+The read order the viewer actually performs, in about 1.2 seconds:
+
+1. **Frame 0** — sees a weird image, starts reading the caption on reflex.
+2. **~0.6s** — finishes the caption, now holds a specific situation in their head.
+3. **~1.0s** — the clip's action lands and *is* that situation. This is the laugh.
+4. **The rest** — they are already deciding whether to send it to someone.
+
+**So the clip's funniest frame must not be frame 0.** If the meme's peak action happens
+immediately, the caption has not been read yet and the joke fires into an empty room. Trim the clip
+so there is **0.6–1.0s of the subject existing** before the action, and no more than that.
+
+### Length
+
+**4–15 seconds, target 7.** A meme recaption is short because the joke is instantaneous and every
+second after the laugh is a second in which someone scrolls. If the clip is 30s, you are using 7s
+of it. Loop it if it is shorter than 4s — a 3s clip looping twice reads as intentional, a 3s clip
+that ends reads as a mistake.
+
+---
+
+## The caption — the only thing you actually write
+
+### First, pick a pole: PAIN or WIN
+
+Every meme recaption points at one of two feelings. **Decide which before you write a word**, because
+the pole changes the casting, the caption grammar, whether the offer is named, and what the gate
+allows.
+
+| | 😖 **Pain** | 🎉 **Win** |
+|---|---|---|
+| What it names | the annoying, tedious, humiliating or absurd moment in the audience's day | the small win, the relief, the flex, the moment something finally worked |
+| What the clip supplies | the reaction they wish they could have | the celebration |
+| Where the offer sits | absent, or a **witness** to the mess | named, and it is **what worked** |
+| Does it resolve? | **No.** The video ends on the problem | **Yes, by design.** The resolution is the joke |
+| Example | *"me at 1am realising the receipts folder is just 40 photos of receipts"* | *"me watching the reconciliation finish in 4 seconds after 3 years of spreadsheets"* |
+| Travels | furthest — everyone in the niche has had that day | less far — it is closer to an ad and reads like one sooner |
+| Converts | slowly, to cold viewers | better, to warm ones |
+| The bar | low. Pain is easy to make funny | **high.** See below |
+
+**Run both poles in every batch.** They do different jobs, and which one your market responds to is
+the single most useful thing bulk generation can tell you.
+
+#### The win pole is allowed, and it is harder
+
+A win meme shows the product working, so it is one bad sentence away from a testimonial ad. Three
+things keep it a meme:
+
+1. **The comedy is the SIZE OF THE RELIEF, never the feature.** *"3 years of spreadsheets"* is the
+   joke; *"auto-reconcile v2"* is a changelog. The exaggeration lives in how much suffering just
+   ended, not in what the software does.
+2. **The win must be one the niche has ached for.** If the audience has never felt the pain, the
+   relief is meaningless and the meme is an announcement.
+3. **It still has to pass the cold-viewer test.** Cover the brand and the feature names — does it
+   still read as a true, funny moment from their week?
+
+**If you cannot make the win funny in one line, write the pain instead.** A flat win meme is an ad
+with a reaction GIF on it; a good pain meme is always available and always travels.
+
+### The grammar
+
+The caption names **somebody's experience**, in one of eight frames. Pick one. Do not invent a
+ninth, and do not mix two.
+
+| Frame | Shape | Who the joke is about | Use when |
+|---|---|---|---|
+| `When I …` | first person, past or present | you | The complaint is embarrassing and you're owning it |
+| `Me when …` / `Me trying to …` | first person, present | you | The clip is a single sustained face or posture |
+| `When you …` | second person | the viewer, flatteringly | The experience is near-universal in the niche |
+| `My friend when …` / `Why my friend …` | third person, affectionate | someone you love | The behaviour is irrational and you're not defending it |
+| `<Entity> when they …` | personified institution | the villain | Something non-human keeps doing this to you |
+| `<Entity> with …` / `<Entity> after …` | personified institution | the villain | The villain's *state*, not their action |
+| `<Entity> watching me …` | a personified observer — **including the offer itself** | you, seen | **The tier-1 naming frame** (Rule 1). Something is watching you fail |
+| `us after …` / `my clients when …` | first person plural, or the customer's customer | the group | A shared win or a shared groan. The natural **win-pole** frame |
+
+**`<Entity> watching me …` is how you get the offer into the caption without the joke resolving.**
+The product becomes a witness to your dysfunction rather than the cure for it — it is present, named
+and powerless, which is both funnier and safer. See Rule 1.
+
+**`<Entity>` is the format's sharpest tool.** Personify the thing that causes the pain — the group
+chat, my calendar, the algorithm, my landlord's portal, the 47 open tabs, every delivery app, the
+search bar. An institution behaving like an idiot person is funnier than a person behaving like an
+idiot person, and it moves the blame off the viewer, which is what makes them comfortable enough to
+share it.
+
+> ⚠️ **`<Entity>` is also where Rule 8 gets broken, every time.** The funniest villain is always a
+> real company by name, and naming one doing something stupid is exactly what Rule 8 forbids. The
+> first draft of the worked example in Appendix D personified **Resy** — a real, named, adjacent
+> booking company — and it took a reader to catch it, because on the page it just looked like a
+> good specific joke.
+>
+> **Personify the CATEGORY or the OBJECT, never the company.** "every delivery app", "the search
+> bar", "10 tabs" are all jokes. A named company is a letter, and it also makes the customer look
+> like they are punching at a competitor rather than describing a life.
+
+**Hard rules on the sentence itself:**
+
+- **Subject first.** Never open with a verb, never open with "POV" (dated), never open with a
+  question.
+- **One sentence. One clause of setup, one clause of collapse.** The collapse is the last four
+  words and it must be the last four words.
+- **8–20 words.** Under 8 and it's a slogan; over 20 and it isn't read before the clip lands.
+- **No punctuation at the end.** No period, no exclamation mark, no emoji. A meme caption that
+  punctuates itself reads as written *at* you.
+- **Lowercase or sentence case. Never ALL CAPS**, which reads as a 2013 image macro.
+
+### The specificity ladder — the single biggest lever
+
+Generic captions get nothing. Specific captions get "how did you film me". Climb the ladder until
+it hurts, then stop one rung earlier.
+
+| Rung | Example (a "can't find where to eat" problem space) | Result |
+|---|---|---|
+| 0 — a feeling | `when you're hungry` | Nothing. This is not a situation |
+| 1 — a situation | `when you can't decide where to eat` | Nothing. True of everyone, felt by no one |
+| 2 — a situation with a number | `when you've had 10 tabs open for an hour` | Starting to work |
+| 3 — **+ a named object and a real outcome** | `when i've had 10 tabs open since 7pm for one scallop roll and we're getting pizza again` | This is the rung. Ship this |
+| 4 — too far | `when i've had 10 tabs open since 6:47 for the scallop roll from that place on ludlow` | Now it's your story, not theirs |
+
+**Rung 3 is: a number, a concrete named object, and a deflating outcome.** The number makes it true,
+the object makes it real, the outcome makes it funny. Miss any one of the three and you are on
+rung 2, where nothing lives.
+
+> **"Named object" means a THING, not a BRAND.** `scallop roll`, `the 7am standup`, `row 400 of the
+> spreadsheet` — all rung 3. A company name feels like it does the same job and it does not; it does
+> Rule 8's job instead, which is to get you a letter. See the warning under `<Entity>` above.
+
+### The cold-viewer test — cover the brand and read it again
+
+The specificity ladder tells you to get *more* specific. This is the rule that stops you getting
+specific about the **wrong thing**.
+
+> Read the caption as somebody who works in the niche but has **never heard of the offer** — not the
+> brand, not the feature names, not the category jargon. If they cannot get the joke in one read,
+> the caption failed, however clever it is to the team.
+
+**Write about the NICHE, not the FEATURE.** A meme about a product feature needs product context to
+land, so it lands only on people who already bought — which defeats the point of a meme ad. A meme
+about the niche's lived experience lands on everybody in the niche.
+
+- ❌ *"me after the auto-reconcile v2 sync finally clears"* — "auto-reconcile v2" means nothing cold.
+- ✅ *"me at 1am matching bank lines to receipts by hand"* — every bookkeeper has had that night.
+
+**The test, mechanically:** cover the brand name and every feature word. If the caption still reads
+as a true, funny moment from the audience's week, keep it. If it collapses into nonsense, rewrite it
+around the **feeling** instead of the feature.
+
+**No invented vocabulary, no inside jokes, no setups that only the founder's demo explains.** Slang
+the niche already uses is fine; slang only the product uses is not. This is the difference between
+a rung-3 specific (`scallop roll`, `the 7am standup`) and a rung-0 nothing (`the v2 sync`) — both
+feel specific when you write them, and only one survives being read by a stranger.
+
+> This test is also **elegance-test question 5** (Rule 1). It is listed twice on purpose: it decides
+> whether the caption works at all, *and* whether the offer can be named inside it.
+
+**Get the specifics from the customer, not from your imagination.** Their testimonials, their
+support inbox and their landing-page copy are full of rung-3 sentences written by actual users. In
+the worked example in Appendix D, the shipped caption is a lightly compressed version of a
+testimonial printed on the customer's own homepage — which also happens to satisfy Rule 6.
+
+### Banned captions
+
+- **The product as the thing that WORKS.** The name may appear as a subject in the setup (Rule 1,
+  tier 1); it may never appear in the payoff or as the fix. Checked by `offer_not_in_payoff` and
+  `caption_does_not_resolve`.
+- **Category nouns and feature words**, even when the brand name is allowed. `dishcover.io` is a
+  character; "dish search app" is a description.
+- Anything that resolves. `when i couldn't find X … so now i just` — the meme is the complaint. The
+  solution is not in the video. **Ever.**
+- "POV:" — dated, and it forces present tense on a clip that is usually past tense.
+- Two-part setups split across a cut. That is a different format and it is weaker.
+- Anything naming a real competitor doing something bad. Personify a *category* ("every delivery
+  app"), not a company you can be sued by.
+
+---
+
+## Casting the meme
+
+### Browse the shelf. Do not search it.
+
+> ⚠️ **The descriptions on this shelf were written by a model that has never heard of the meme.**
+> This is not a small problem — it is the defining fact of sourcing this format.
+>
+> `my-brain-every-10-seconds` is described as *"A man in a suit gestures and looks at the camera
+> with a neutral expression."* `jonah-jameson-laugh-you-serious` is described as *"A solid green
+> screen background."* A semantic query for `hungry food eating` returns **zero results** on a shelf
+> that contains a dozen clips of people eating.
+>
+> **The `slugId` is the index. The description is noise.** Pull the whole shelf as JSON, read the
+> slugs, and only look at descriptions to break a tie.
+
+```bash
+vidfarm public-raws --categories                       # the shelves + live counts
+vidfarm public-raws --category greenscreen --limit 200 # 193 of these 200 are MemeScreens
+                                                       # ...and this is only the FIRST 200. See below
+vidfarm public-raws --category text-graphics --limit 200
+vidfarm public-raws --category lifestyle --limit 200   # also almost entirely MemeScreens
+```
+
+> 🚨 **`vidfarm public-raws` shows you 200 clips and stops, and it does not tell you.** The server
+> caps a shelf at 200 per call and returns a `next_cursor` — but the CLI has **no `--cursor` flag**,
+> so raising `--limit` to 1200 still returns exactly 200. Paging the same shelves through
+> `vidfarm api GET` instead turns **200 clips into 959** (851 of them MemeScreens). Cast from the
+> first 200 and you are picking from under a quarter of the library, with nothing anywhere saying so.
+>
+> **Build the full index once (Appendix C) and cast from the TSV, not from the CLI.**
+
+**Every shelf the CLI exposes is dominated by MemeScreens** — `b-roll`, `lifestyle` and
+`text-graphics` all come back as greenscreen memes. Good news for this format, bad news for
+backgrounds (see below).
+
+### The enactment test, in practice
+
+You are casting for a **verb**, not a mood. Write down the verb your caption's subject is doing
+with their body, then find the slug that does that verb:
+
+| The caption's verb | Slugs that enact it |
+|---|---|
+| deflating / accepting a bad outcome | `my-disappointment-is-immeasurable-and-my-day-is-ruined`, `jonah-hill-sigh`, `girl-eyerolls` |
+| not understanding at all | `huh-cat`, `hangover-dog`, `zoolander-staring`, `nervous` |
+| the same thought on a loop | `my-brain-every-10-seconds`, `monkey-cymbal-jolly-chimp`, `zoning-out` |
+| smug, having solved it | `gigachad`, `chad-head-bopping`, `check-out-the-big-brain-on-brad` |
+| overreacting to something tiny | `neon-screaming`, `jontron-nooooooo`, `girl-fake-crying` |
+| telling you you're wrong | `jonathan-frakes-telling-you-youre-wrong-for-47-seconds`, `women-mocking` |
+| unbothered while it burns | `my-favorite-thing-in-the-world-to-do-is-nothing`, `boss-baby-chilling` |
+
+**Then confirm by eye.** Build a contact sheet before you commit — a slug promises an action the
+clip does not always deliver, and half these clips are 16:9 with the subject small at the bottom:
+
+```bash
+ffmpeg -v error -i meme.mp4 -vf "fps=1,scale=240:-1,tile=7x1" -frames:v 1 sheet.png
+```
+
+### Match the INTENSITY, not just the verb
+
+The enactment test gets you the right action. This gets you the right *size* of it — and it is
+where the comedy actually comes from.
+
+> **The joke is the MISMATCH between the size of the feeling and the size of the reaction.**
+
+- A **tiny pain** + a wildly over-the-top reaction clip. (Someone screaming into the void because a
+  meeting could have been an email.)
+- A **small win** + a stadium-scale celebration. (Confetti and a trophy lift because a build
+  passed.)
+- Matching a big feeling to a big reaction is not a joke, it is a re-enactment. Matching a small
+  feeling to a small reaction is not anything at all.
+
+**Choose the pain or win that the clip's energy already fits, rather than fighting the footage.**
+You have 851 clips and one caption you have not written yet; it is far cheaper to pick the feeling
+that suits a great clip than to hunt for a clip that suits a feeling you are attached to. When a
+strong clip and a strong line refuse to sit together, keep the clip and rewrite the line — the
+clip is the part you cannot edit.
+
+### 🚨 Rights tiers — read this before you cast for a paying customer
+
+The MemeScreens shelf is **keyed celebrities, studio characters, TV clips and music-sync memes.**
+That is completely normal for a meme repost from an owned account. It is a different thing entirely
+on a customer's promoted ad. Sort every candidate into a tier and **put the tier in the build log**:
+
+| Tier | What's in it | Client work? |
+|---|---|---|
+| 🟢 **Safe** | Animals, babies, anonymous adults, generic dancers, abstract/original animation. `huh-cat`, `hangover-dog`, `cat-kung-fu`, `monkey-cymbal-jolly-chimp`, `nanalan`, `girl-eyerolls` | ✅ Default for client work |
+| 🟡 **Named individual** | A real, identifiable, non-famous-brand person. `my-disappointment-is-immeasurable…`, `hey-vsauce-michael-here`, `mutahar-laughing` | ⚠️ Organic owned accounts only. Flag it to the customer in writing |
+| 🔴 **Studio / celebrity** | SpongeBob, Naruto, JoJo, Mr. Krabs, Joker, John Cena, Charli D'Amelio, Game of Thrones, Rick Astley | ❌ Not on paid placement. Not on a customer's account without their lawyer |
+| ⛔️ **Reputation** | Figures who bring their own controversy regardless of rights — e.g. `tate-evil-laugh`, `jordan-belfort`, political slugs | ❌ Never on client work. The clip's politics become the customer's politics |
+
+**The tier is the customer's decision, not the editor's.** Default to 🟢. If a 🟡 or 🔴 clip is the
+only one that enacts the verb, build it, ship it with the tier named in the handoff, and build the
+🟢 alternate alongside it so they have something to say yes to.
+
+---
+
+## The two production classes
+
+Every meme on the shelf is one of these, and they are built completely differently. **Decide the
+class before you write a single ffmpeg command.**
+
+| | 🟩 **Class A — Keyed** | 🎞 **Class B — Baked** |
+|---|---|---|
+| What it is | Subject on a flat chroma plate. `sourceType: MemeScreens`, plate is usually pure `#00FF00` | A finished clip with its own world, often with text already burned in |
+| What it needs | **A background.** Ships green otherwise | **Text removal or avoidance.** Ships someone else's caption otherwise |
+| Layout | Layout B — the world | Layout A — the plate-and-band |
+| Where the caption goes | On the background, above the subject | On a plate above the clip, outside the picture |
+| Share of the shelf | The large majority | A minority — check for burned-in text on the contact sheet |
+
+**Check the plate colour before you key anything.** These clips are re-encodes and the plate is not
+always what it looks like:
+
+```bash
+python3 -c "
+import subprocess,numpy as np
+p=subprocess.run(['ffmpeg','-v','error','-i','meme.mp4','-vf','fps=1,crop=200:200:20:20',
+                  '-pix_fmt','rgb24','-f','rawvideo','-'],capture_output=True)
+a=np.frombuffer(p.stdout,np.uint8).reshape(-1,200,200,3)
+m=a.reshape(-1,3).mean(0).astype(int); print('plate rgb',m,'hex %02X%02X%02X'%tuple(m))"
+```
+
+A pure `00FF00` reading means a digital plate: key tight (`0.18:0.03`) and **skip despill.** A
+reading like `1F D3 1F` means a filmed plate: key looser and despill lightly. Getting this backwards
+is the first defect in the list below.
+
+### Class B — dealing with the burned-in text
+
+The clip arrives carrying somebody else's joke. Three options, best first:
+
+1. **Crop it out.** The original caption is nearly always in a top or bottom band. Crop the band
+   off, then put your caption on your own plate above the picture. Free, clean, no artefacts.
+2. **Cover it.** Only when the text overlaps the picture. Put an opaque plate over it — sampled
+   from the pixels beside it, not a guessed grey — and your caption on top of the plate. A plate
+   that doesn't match reads as a censor bar.
+3. **Never blur it.** A blurred rectangle is the single most recognisable "this is a reposted ad"
+   tell on the platform.
+
+---
+
+## Visual DNA
+
+### The canvas
+
+**1080×1920, 30fps, 9:16, one canvas, no letterboxing of the canvas itself.** The clip inside it is
+a different question — see below.
+
+### ⚠️ Do NOT crop the meme to 9:16
+
+Most of this shelf is 16:9 (the worked example is 1280×720). The instinct is to crop to fill the
+tall frame. **Don't.** Cropping a 16:9 meme to 9:16 throws away the sides, where the joke usually
+is, and it takes away the empty space the caption needs.
+
+The empty space above the clip is **not a defect to be filled — it is the format's signature.** A
+meme in a band with a caption on a plate above it is what a meme looks like on this platform. A
+meme cropped edge-to-edge looks like a video someone re-uploaded.
+
+### Layout A — the plate-and-band (Class B, and any clip with its own world)
+
+```
+┌──────────────────┐ 0
+│                  │
+│   CAPTION PLATE  │   flat white (#FFF) or the meme's own black
+│   black text     │   height: whatever the caption needs, 22–34% of frame
+│                  │
+├──────────────────┤ ~30%
+│                  │
+│    THE MEME      │   full canvas width, native aspect, 1080×608 for a 16:9 source
+│                  │
+├──────────────────┤ ~62%
+│                  │
+│   (plate colour  │   the plate colour continues. Do NOT put anything here
+│    continues)    │
+└──────────────────┘ 1920
+```
+
+The clip sits **high**, not centred: its top edge at ~30–34% of frame height. Centring it drops the
+picture behind the platform's own UI chrome at the bottom of the screen.
+
+### Layout B — the world (Class A, keyed)
+
+```
+┌──────────────────┐ 0
+│  background      │   fills the whole canvas
+│                  │
+│   the caption    │   on a translucent plate, y ≈ 12–30%
+│                  │
+│                  │
+│      ██████      │   the keyed subject, bottom-anchored,
+│     ████████     │   full canvas width, running off the bottom edge
+└──────────────────┘ 1920
+```
+
+**Bottom-anchor the subject and let it run off the bottom edge.** These clips are torsos framed
+small in the middle of a big green field, and the measured subject box in the worked example was
+676×536 inside 1280×720 — 53% of the width, already touching the bottom of frame. Crop to the
+subject's own box plus a margin, scale it to the full canvas width, and sit it on the floor. A
+keyed subject floating in the middle of a background with air under it reads as a sticker, and a
+sticker is not a person.
+
+Appendix A measures the box and does all of this in one pass.
+
+### Backgrounds — a keyed meme needs a WORLD, not a colour
+
+> **A keyed meme without a background is not finished.** The subject was cut out of a green field;
+> if you drop it on a flat plate you have a sticker floating in a void. The background is what makes
+> the joke *happen somewhere*, and "somewhere" is half the comedy.
+
+> ⚠️ **There is no background shelf in public-raws.** Every category — `b-roll`, `lifestyle`,
+> `food` — comes back as MemeScreens greenscreen clips. Do not spend an hour looking for the clean
+> stock library. It is not there. Use the ladder.
+
+**Pick the world before you search.** One line, written down: *where is this person when this
+happens to them?* Then search for that, not for the product's category.
+
+| # | Source | Cost | Licence | When |
+|---|---|---|---|---|
+| 1 | **`vidfarm media image "<the world>"`** — Openverse + Pixabay stock | **$0** | ✅ Pixabay is royalty-free, **no attribution** | **The default in `minimize`.** This is the free-tier answer and it is genuinely good |
+| 2 | **A still from the customer's own capture**, blurred and darkened | $0 | ✅ theirs | When the joke's world really is the product's world |
+| 3 | **`vidfarm image-search "<the world>"`** — Google Images | ~$0.0003/call, **paid plans only** | ⚠️ **none — these are LINKS** | Pro accounts. Best for finding the *look*. See the warning below |
+| 4 | **`vidfarm handoff image --theme "…" --single`** → the human pastes into a free web generator | $0, human in the loop | ✅ | `mode interactive`. The best-looking result on the ladder |
+| 5 | **`vidfarm generate image` / `create-overlay`** | billed | ✅ | `rich-ai` only. **Refused in `minimize` without `--yes`** |
+| 6 | A flat brand plate from `capture/extracted/tokens.json` | $0 | ✅ | Fallback only. Honest, clean, and the least funny option on this list |
+
+#### Tier 1 — the free path, in full
+
+```bash
+vidfarm media image "dark empty restaurant interior night" --provider pixabay --limit 8 --json
+```
+
+- **Force `--provider pixabay`.** Openverse results are largely **CC-BY**, which requires a credit
+  line on screen — and a credit line is brand chrome this format forbids. The CLI prints
+  `⚠ credit:` next to every one of them. Pixabay needs none. If you must use a CC-BY image, the
+  attribution goes in the **post caption**, never on the video.
+- **Download with a browser user-agent.** Pixabay's CDN answers a bare `urllib`/`python-requests`
+  fetch with **HTTP 403**: `curl -sL -A "Mozilla/5.0" -o bg.jpg "<url>"`.
+- **Look at the candidates as one sheet** before you pick, exactly as you do for the meme.
+
+#### Tier 3 — what the pro path actually returns
+
+`vidfarm image-search` is Google Images, and the CLI says so itself: *"These are LINKS with no
+licence attached."* A real run for `empty restaurant interior night` returned **iStock and Vecteezy
+preview JPEGs** — watermarked comps that you cannot ship on a customer's ad.
+
+> **So use tier 3 to find the LOOK, then get the asset from tier 1.** It is a fast, cheap art
+> director. It is not an asset source. Shipping an iStock preview because it appeared in a search
+> result is the one mistake on this page that ends in a letter.
+
+#### Push the background down — always
+
+The background loses. It is a backdrop for a joke, not a picture. **Blur it, darken it, desaturate
+it**, and crop it to 9:16 deliberately rather than letting a centre-crop pick for you:
+
+```bash
+# crop the interesting part -> 9:16 -> blur into a set -> take it down under the caption
+ffmpeg -y -i cand3.jpg -vf \
+  "crop=480:853:230:0,scale=1080:1920,gblur=sigma=18,eq=brightness=-0.06:saturation=0.8,setsar=1" \
+  -update 1 bg.png
+```
+
+Two failures, both real, both from the run that produced this file:
+
+- **Too little grade** and the background competes with the caption. `meme-qa.py` measures this
+  (`background_pushed_down`) in the strip *above* the caption.
+- **Too much grade** and you get a black rectangle. The first attempt here used `sigma=28` +
+  `brightness=-0.22` on a default centre-crop and produced an image with no readable content at all
+  — and it still passed every check that existed at the time, because "dark" and "pushed down" look
+  identical to a naive metric. **Look at the background on its own before you composite.**
+
+### Everything else
+
+- **One shot. No cuts, no transitions, no zoom, no shake, no "meme" whip.**
+- **The clip runs at native speed.** Speeding a meme up destroys the timing that made it a meme.
+- **At most one piece of brand chrome: the handle** — and only when the caption is not already
+  carrying the name (Rule 1). No logo, no end card, no CTA, no progress bar, no second mark.
+- **No B-roll, no cutaway, no second clip.** If you feel the video needs one, the caption is weak.
+
+---
+
+## Typography DNA — a card, not a subtitle track
+
+> **This is the one harness in the set where kinetic word-by-word captions are WRONG.**
+
+Every other format in this repo wants TikTok-native word-pop subtitles. This one does not, and the
+reason is structural: a meme caption must be **read in one gulp, before the clip acts.** Words that
+arrive one at a time cannot be read ahead, so the action lands before the setup exists and the joke
+has no floor.
+
+- **The whole caption is on screen at `data-start="0"`, in its final state, and never changes.**
+  `text_by_sec: 0` grades the frame, not the intent.
+- **One text object. No animation. No fade-in, no pop, no typewriter.**
+- **Weight 600–700, not 900.** A meme caption is typed, not shouted. 900 is an ad.
+- **Sizing:** ~52–62px on the 1080 canvas for a 3-line caption. It should look like a person typed
+  it into the app, because that is the look the platform's own caption tool produces.
+- **Font:** the platform's own caption face (`TikTok Sans`), or Helvetica/Arial. **Self-host it** —
+  a fallback chain means a missing font silently renders as a different font and the video just
+  quietly stops looking native.
+- **Never Impact. Never a drop shadow. Never an outline. Never gradient text.**
+- **Plate, always.** Black on white for Layout A; white on `rgba(0,0,0,0.55)` with ~24px padding for
+  Layout B. An unplated caption over a busy background is unreadable on half of frames, and you will
+  not notice because you already know what it says.
+
+### Placement — centre the block, left-align the words
+
+The commonest way this format looks amateur is not the font or the colour. It is a caption plate
+sitting **flush against one edge** with a lake of dead space on the other side.
+
+> **The BLOCK is horizontally centred. The WORDS inside it are left-aligned.**
+
+These are two different decisions and they pull in opposite directions, which is why they get
+collapsed into one and why the result is always wrong:
+
+- **Centred words** read as a title card — a designed, corporate thing. Wrong for a meme.
+- **A left-pinned block** reads as an accident, because the plate is an `inline-block` that hugs its
+  longest line. Give it `left:7%` and it does *not* fill that width — it sits at 7% and ends
+  wherever the text ends, leaving the frame visibly lopsided.
+
+So: a full-width container with `text-align:center`, an `inline-block` plate riding that centre, and
+`text-align:left` inside the plate. Appendix B is the exact CSS.
+
+- **Hand-break the lines to NEAR-EQUAL length**, at the clause, with the collapse on its own line.
+  This is what makes a left-aligned block look balanced instead of ragged — and it is checked
+  (`caption_lines_balanced`, raggedness < 45%).
+- **2–4 lines.** One line is a slogan; five is a paragraph.
+- **Vertical: `top` around 12–16%, not 8–10%.** Pinned to the very top the caption reads as a
+  platform overlay rather than as part of the picture. In Layout B it must also clear the subject's
+  head — the caption sits in the upper third, the subject occupies the lower half, and the gap
+  between them is what makes the frame breathe.
+- **Safe zone 8–85%.** In Layout A the caption lives in the top plate; in Layout B keep it clear of
+  the top 8% (platform UI) and well above the subject's head.
+- **Side margins ≥ 4%.** A plate that touches either edge reads as a crop error.
+
+**None of this is a matter of taste, and none of it is checked by `vidfarm qa`.** `meme-qa.py`
+(Appendix E) measures the rendered frame: block centre within 3% of 50%, side margins, vertical
+band, and line balance. If the numbers are wrong the frame is wrong, whatever it looked like at 2am.
+
+### The handle — typography
+
+The offer's name is the one piece of brand chrome allowed (Rule 1), and it is styled to be *skipped*:
+
+- **Directly under the caption plate, on the same centre.** A corner mark works too, but under the
+  plate is safer — the bottom of frame is platform UI, and in Layout B the subject owns it.
+- **≤72% of the caption's size.** 34px against a 54px caption reads as a byline; parity reads as a
+  second headline, which is a CTA wearing a small font.
+- **Alpha ≤0.85**, on its own faint plate so it stays legible over a busy background.
+- **Lowercase, the bare domain or handle.** `dishcover.io`, not `Visit Dishcover.io →`, not
+  `www.`, not a tagline. The moment it acquires a verb it is a CTA.
+- **Static, present at frame 0, never animated.** It is furniture.
+- **One mark. Never a logo AND a handle** — pick the words, because words survive a re-encode and a
+  screenshot at 30% scale, and a logo does not.
+
+---
+
+## Audio DNA
+
+> **Keep the meme's own audio.** This is the opposite of every other harness here, and it is not
+> negotiable.
+
+For a large share of these clips the sound **is** the meme. Muting `never-gonna-give-you-up` or
+`jonah-jameson-laugh` leaves you with a stranger moving silently. The audio is the half of the
+recognition you did not have to build.
+
+- **Normalise it, don't replace it.** `loudnorm=I=-16:TP=-1.5:LRA=11`.
+- **Measure the render**, not the stem: `ffmpeg -i out.mp4 -af ebur128=peak=true -f null -`.
+- **No voiceover. No TTS. No added music bed** on top of the meme's own audio — two audio ideas at
+  once is noise, and the meme's audio was going to win anyway.
+- **The exception:** a clip that was silent, or one whose audio is a copyrighted music track you
+  cannot ship. Then go silent and let the poster attach trending audio in the platform's own
+  editor. **Say which of the two it is in the handoff** — it is a different decision for them.
+
+> ⚠️ **A lot of this shelf ships a silent AAC track, not no track.** `ffprobe` reports an audio
+> stream, `loudnorm` runs without complaint, the render has audio metadata, and `vidfarm qa`'s
+> `audio: required` passes — on a video nobody can hear. Of the two clips in Appendix D, one
+> measured -26 LUFS and the other **-70 LUFS, which is digital silence.**
+>
+> **Measure the SOURCE before you build, and the RENDER before you ship:**
+> ```bash
+> ffmpeg -v info -i <clip>.mp4 -af ebur128 -f null - 2>&1 | grep -A2 "Integrated loudness"
+> ```
+> Below about -50 LUFS the clip is silent. That is not a defect — it is a fact that decides the
+> handoff, and the one thing you cannot do is not know it.
+- **A music-sync meme is a 🔴 rights clip** even when the picture is fine. The track is the part
+  that gets the video muted.
+
+---
+
+## The rules
+
+### Rule 1 — name the offer in the CAPTION if it reads; fall back to the handle if it doesn't
+
+**The offer is named on the video, always.** A meme nobody can trace builds someone else's page, and
+this format gets screenshotted and reposted more than anything else in the set.
+
+There are two ways to name it, and they are a **priority order, not a choice**:
+
+| Tier | How | Reach | Use when |
+|---|---|---|---|
+| **1 — in the caption** ✅ *try this first* | The offer is a word in the sentence: `dishcover.io watching me open 10 tabs since 7pm for one scallop roll` | Strongest. The name is inside the thing people screenshot and re-type | The offer can be a **character** in the setup without bending the joke |
+| **2 — the subtext handle** | The offer sits under the caption plate, small and dimmed, as a byline | Good. Survives a repost, but the eye skips it | Tier 1 would be forced, wordy, or would make the joke resolve |
+
+**Tier 1 is better and should be the default attempt.** Fall back to tier 2 the moment it stops
+being elegant — a forced brand mention in a meme caption is more damaging than no mention at all,
+because it announces that the meme is an ad before the joke gets a chance.
+
+#### Where the offer may stand in the sentence
+
+This is the whole discipline, and it is one line:
+
+> **The offer belongs in the SETUP, as a subject. Never in the PAYOFF, as the solution.**
+
+| | Example | Why |
+|---|---|---|
+| ✅ **Witness** | `dishcover.io watching me open 10 tabs since 7pm for one scallop roll` | The product observes your dysfunction. The collapse is still yours |
+| ✅ **Interlocutor** | `me explaining to dishcover.io that i've had 10 tabs open since 7pm` | You are confessing to it |
+| ✅ **Reactor** | `dishcover.io when i've had 10 tabs open since 7pm and we're getting pizza again` | It is disappointed in you |
+| ❌ **Solution** | `…and then dishcover.io found it` | The joke resolves. This is an ad |
+| ❌ **Sponsor** | `10 tabs open since 7pm — try dishcover.io` | A CTA with a meme attached |
+
+**The payoff — the caption's last clause — must always land on the person, never on the product
+working.** `for one scallop roll` is a payoff. `and dishcover.io found it` is a press release. Both
+are checked (`offer_not_in_payoff`, `caption_does_not_resolve`).
+
+#### The elegance test — five questions, any "no" means fall back to tier 2
+
+1. Does the caption still fit one of the **eight frames**, with the offer as the entity?
+2. Is it still **≤20 words** with the offer in it?
+3. Does the offer read as a **character**, or as a sponsor who bought a slot?
+4. Does the **collapse still land on the person**?
+5. Would it still be funny to someone who has **never heard of the offer**?
+
+Question 5 is the one that catches most failures. If the joke needs the reader to know what the
+product does, the product is not a character — it is an explanation, and explanations are not funny.
+
+#### The handle (tier 2), specced
+
+- Directly under the caption plate, on the same centre. Corners work; bottom-of-frame does not.
+- **≤72% of the caption's font size** — 34px against 54px reads as a byline; parity reads as a
+  second headline, which is a CTA in a small font.
+- **Alpha ≤0.85**, on its own faint plate so it stays legible over a busy background.
+- **Lowercase, the bare domain.** `dishcover.io`, not `Visit Dishcover.io →`, not `www.`, not a
+  tagline. The moment it takes a verb it is a CTA.
+- Static, present at frame 0, never animated. It is furniture.
+- **One mark only.** Never a logo *and* a handle — pick the words. Words survive a re-encode and a
+  screenshot at 30% scale; a logo does not.
+- **When tier 1 succeeds, the handle is optional.** Keep it only if the caption uses the brand word
+  and you also want the domain (`dishcover` in the sentence, `dishcover.io` underneath). Two
+  identical mentions is one too many.
+
+**The deletion test, either tier:** remove the offer's name. Is it still a complete joke? If yes,
+you have a meme with a byline. If no, the offer is load-bearing and you have written an ad.
+
+### Rule 2 — on the PAIN pole, never resolve. On the WIN pole, the relief IS the joke
+
+This rule is pole-dependent, and reading it without the pole is how a good pain meme gets a
+"…and then we fixed it" bolted onto the end.
+
+**Pain pole — the meme is the complaint.** The video ends on the problem. It does not turn, it does
+not resolve, and it does not hint. A pain meme that resolves is an ad with extra steps, and the
+resolution is reliably the least funny part of every draft you will write. The offer may stand in
+the setup as a witness; it may never be in the last clause.
+
+**Win pole — the meme is the relief, so it resolves by definition.** The product is named and it is
+what worked. What still must not happen is the joke's weight moving off the *feeling* and onto the
+*mechanism*: the comedy is three years of spreadsheets ending, not the sync clearing. Say what the
+relief felt like, never what the feature is called.
+
+| | Pain | Win |
+|---|---|---|
+| Last clause may name the offer | ❌ never | ✅ that is the point |
+| Last clause may name a **feature** | ❌ | ❌ |
+| Comedy comes from | the absurdity of the problem | the scale of the relief |
+| Gate | `caption_does_not_resolve` enforced | pass `--pole win` to relax it; `no_feature_words` still enforced |
+
+Rule 1 and Rule 2 meet at the payoff. On the pain pole the offer may be in the sentence but never in
+the last clause; on the win pole it may be in both, and the discipline moves to keeping features out
+of it. **If you did not decide the pole, you are on the pain pole** — it is the safer default and the
+one that travels.
+
+### Rule 3 — cast for the verb, not the mood
+
+Written above as the enactment test; repeated here because it is the rule most often lost between
+casting and the timeline. Name the physical action in the build log before you open the shelf.
+
+### Rule 4 — the action lands AFTER the caption is read, and frame 0 has a person on it
+
+0.6–1.0s of the subject existing, then the action. Trim the clip to make this true. If the meme's
+peak is at frame 0 of the source, start later — or if the peak *is* the first frame and cannot be
+moved, that clip is not castable for this format.
+
+> ⚠️ **These clips open and close on empty plate, and keyed empty plate is an INVISIBLE frame.**
+> The clip in Appendix D is pure green for its first 0.4s and again from 6.4s to its 7.1s end.
+> Keyed, that ships a **blank thumbnail and a blank tail** — and nothing reports it. `vidfarm qa`
+> passes (the markup is fine), the duration is right, the audio is right, and a contact sheet built
+> at `fps=1` samples at 0.5s and shows you a perfect first frame that is not the first frame.
+>
+> Two separate causes, both of which produce the identical blank frame 0:
+>
+> 1. **The source is empty at its head.** Measure the subject's *presence window* and trim to it —
+>    Appendix A does this automatically and prints the window.
+> 2. **`overlay` emits one background-only frame at t=0**, because after `-ss` the keyed stream's
+>    first PTS is a hair above zero. Fix with `setpts=PTS-STARTPTS` on the keyed chain. Without it
+>    the trim looks like it did nothing, which sends you hunting the wrong bug.
+>
+> **Check frame 0 as a frame, never as a sample:**
+> ```bash
+> ffmpeg -v error -i scene.mp4 -vframes 1 -update 1 f0.png   # then LOOK at it
+> ```
+> `-vf fps=N` gives you the middle of the first interval, not frame 0. That is how this defect
+> survives a review.
+
+### Rule 5 — one caption, one clip, one shot
+
+No cuts. No second beat. No text card at the end. If the joke needs two beats, it is a different
+format.
+
+### Rule 6 — the rung-3 specifics are traceable
+
+Every number and proper noun in the caption comes from the customer's own copy, testimonials, or
+support inbox — not from you. It keeps the joke true, it keeps the customer defensible, and it is
+also, reliably, funnier than what you would have invented.
+
+### Rule 7 — the rights tier is declared, and it is the customer's call
+
+Every build log names the tier. 🟢 is the default for client work. A 🟡 or 🔴 build ships with a 🟢
+alternate beside it. ⛔️ never ships.
+
+### Rule 8 — no real competitor is named doing something bad
+
+Personify the category, not the company. "every delivery app" is a joke. A named company is a
+letter.
+
+### Rule 9 — the bait is in the post caption
+
+Ask one question, in the post caption, in the same voice as the meme. Never on screen. The
+north-star metric is comments, and a meme's comment section is people adding *their* version of the
+same complaint — so ask for exactly that.
+
+> Post caption pattern: `<the caption's situation, restated in one line>. <one question inviting
+> their version>`
+
+---
+
+## Cost-saving mode — the whole build at $0
+
+This format is the cheapest one in the set, and it is the one to reach for when `cost-mode` is
+`minimize`. **Nothing below costs anything.**
+
+```bash
+vidfarm cost-mode                 # confirm: minimize
+vidfarm mode                      # interactive raises quality here; autonomous still works
+```
+
+| Step | Tool | Cost |
+|---|---|---|
+| Source the meme | `vidfarm public-raws --category greenscreen` | $0 |
+| Background | ladder tier 1–3 (brand plate / blurred capture / frozen frame) | $0 |
+| Key + composite | local ffmpeg, one pass (Appendix A) | $0 |
+| Caption | a static layer in the composition | $0 |
+| Audio | the meme's own track, normalised locally | $0 |
+| Render | `hyperframes render` locally | $0 |
+
+> ⚠️ **Do not key to an alpha intermediate.** `vidfarm remove-greenscreen --local` is free and it
+> works, but on a machine whose ffmpeg cannot encode VP9-alpha it silently writes a **ProRes 4444
+> `.mov` — 75MB for a 7-second clip** — which the browser-based renderer cannot play. Nothing errors;
+> you find it at render time.
+>
+> **Composite straight to an opaque MP4 in one ffmpeg pass instead** (Appendix A). It is free,
+> smaller, browser-safe, and one command. `remove-greenscreen --cloud` gives you a real transparent
+> WebM, but it is billed and this format does not need transparency in the output at all.
+
+**Interactive mode is worth it here.** One background image from a free web generator is the single
+biggest quality jump available at $0, and it costs one copy-paste:
+
+```bash
+vidfarm handoff image --theme "<the joke's world>" --single
+```
+
+---
+
+## Bulk generation — this format is built for it
+
+A meme recaption is two independent variables, which makes it the best format in the set for the
+hold-three-constant-vary-one discipline. **Build the matrix, not the video.**
+
+| Vary | Hold | What it measures |
+|---|---|---|
+| **Pole** (pain vs win) | same clip, same problem | Whether the market wants to be *seen* or wants *relief*. Run this first — it is the biggest split |
+| Caption frame (`When I` vs `<Entity> when they`) | same clip | Whether the audience wants to be seen or wants a villain |
+| Specificity rung (2 vs 3) | same clip, same frame | Almost always: rung 3 wins, by a lot |
+| The clip | same caption | Enactment. The clearest signal you can buy |
+| The problem | everything else | Which pain the market actually feels |
+
+**Enumerate the pains and the wins ONCE, then recaption across the whole list.** This is the
+highest-output, lowest-cost loop in the format and it is why the pole matters: sit down with the
+customer's testimonials and support inbox, write ten pains and ten wins from the niche's real week,
+and you have twenty videos before you have opened the shelf. The list is the asset; the clips are
+interchangeable.
+
+**One caption × five clips is five videos and about twenty minutes of work**, because the composite
+is one ffmpeg command and the caption layer does not change. Do that before you write a second
+caption — you will learn more from five castings of one joke than from five jokes.
+
+Keep the index (Appendix C) and a `captions.tsv` of rung-3 lines. The pairing is the creative act;
+everything downstream is a loop.
+
+---
+
+## Quality gates — what is ENFORCED, and by what
+
+A rule nobody measures is a rule nobody follows. This format has three gates, and they check
+different things. **Running only the first one is the same as running none.**
+
+| Gate | Tool | Sees | Catches |
+|---|---|---|---|
+| 1. Markup | `vidfarm qa <dir> --harness ./experimental/meme-recaption.md` | the composition DOM | duration, aspect, font regime, banned strings, layer counts. **22 checks, zero pixels** |
+| 2. Render | `python3 meme-qa.py <render>.mp4 <composition>.html` (Appendix E) | the finished MP4 | blank thumbnail, empty tail, residual green, caption centring/balance/placement, background not pushed down, silent audio, caption grammar |
+| 3. Human | your eyes | the joke | the three-way lock. **No script will ever check whether it is funny** |
+
+> 🚨 **Gate 1 passes on a broken video.** Every defect this format actually produces is invisible to
+> a DOM check. During the run that produced this file, a build passed `vidfarm qa` **19/19 while
+> shipping a completely blank thumbnail** — correct duration, correct frame count, correct audio
+> metadata, clean markup, and no subject on frame 0. That is not a criticism of `vidfarm qa`; it is
+> a static check and it says so itself. It is the reason gate 2 exists.
+
+> **`vidfarm qa` stops answering after one revision of `composition.html`.** It prints *"REVISION
+> LIMIT REACHED"* and withholds its findings — a deliberate anti-loop guard, not a failure. On a
+> second pass use `--reset-revisions` (or `--max-revisions 2`). Read it as the tool telling you that
+> what is left is usually taste; if you know it is not, reset and carry on.
+
+**Gate 2 is not advisory. It exits non-zero.** Wire it into the build:
+
+```bash
+vidfarm qa work/<job>/v001 --harness ./experimental/meme-recaption.md
+python3 meme-qa.py renders/<job>-v001.mp4 work/<job>/v001/composition.html \
+        --offer dishcover.io || exit 1
+```
+
+What gate 2 enforces, and the number it uses:
+
+| Check | Threshold | The defect it exists for |
+|---|---|---|
+| `first_frame_has_subject` / `last_frame_has_subject` | lower-band stdev > 12 | Blank thumbnail / empty tail from un-trimmed plate |
+| `no_residual_green` | < 0.5% green pixels | A key that was too tight |
+| `caption_horizontally_centred` | block centre 50% ± 3% | The flush-left plate with a lake of dead space |
+| `caption_side_margins` | > 4% and < 96% | A plate touching an edge |
+| `caption_vertical_placement` | inside 8–85% | Under the platform UI, or on the subject's face |
+| `caption_lines_balanced` | raggedness < 45% | Lines not hand-broken to near-equal length |
+| `background_pushed_down` | detail above the caption < 6.0 | A background competing with the joke |
+| `background_not_blown_out` | top-strip luma < 150 | A bright background eating a white caption |
+| `audio_level` | −20…−13 LUFS, **or** < −50 with `--silent-ok` | A silent clip shipped as if it had sound |
+| `caption_word_count` | 8–20 words | Slogan, or unreadable in 0.6s |
+| `caption_uses_a_frame` | one of the six | A caption that is a statement, not an experience |
+| `caption_no_cta_or_resolution` | no CTA strings, no `so i` / `then i found` | Rules 1 and 2 — the ad leaking back in |
+| `caption_lines_hand_broken` | a `<br>` is present | Renderer wrap landing mid-thought |
+| `offer_named_somewhere` | in the caption **or** in the handle | An untraceable meme that builds someone else's page. Also prints which tier you are on |
+| `offer_not_in_payoff` | offer absent from the caption's **last clause** | Rules 1+2 — the joke resolving into a pitch |
+| `caption_does_not_resolve` | *(pain pole only)* the offer's name followed by a success verb, or a turn phrase (`so i`, `then i`, `finally`, `turns out`) | Rule 2 — a pain meme resolving into a pitch. Pass `--pole win` when the relief IS the joke |
+| `no_feature_words` | *(both poles)* no `v2` / `sync` / `integration` / `api` / `dashboard` / `workflow` / `platform` … | The cold-viewer test, mechanised. A feature only parses for people who already bought |
+| `handle_is_subordinate` | ≤72% of the caption's font size *(only if a handle exists)* | A handle that has become a second headline |
+| `handle_is_dimmed` | alpha ≤0.85 *(only if a handle exists)* | Same |
+| `single_shot` | exactly 1 `<video>` | "There are no beats" |
+| `no_animation_on_caption` | no `animation` in `.memecap` | Kinetic captions, which break the read order |
+
+**Pass `--offer <domain>`** or the handle checks are skipped silently — an unset offer is not a
+passing offer. **Pass `--pole win`** only when the caption is deliberately a win meme; the gate
+defaults to `pain`, the stricter of the two, so nobody accidentally ships a resolution.
+
+**Two things gate 2 deliberately does NOT check**, because a script cannot: whether the meme enacts
+the caption's verb, and the rights tier. Those stay on the human checklist below, and the rights
+tier stays in the build log in writing.
+
+**Calibrate a checker before you trust it.** Two of these thresholds were wrong on their first
+version and fired on a correct build — `caption_lines_balanced` measured pixel rows instead of text
+lines (a row clipping an apostrophe made every caption "100% ragged"), and `background_pushed_down`
+measured a strip that included the caption plate's own hard edges. A gate that cries wolf gets
+switched off within a day, which is worse than not having it. **Run any new check against a build
+you have already looked at and agree is good, and make it pass before you let it fail anything.**
+
+---
+
+## Pre-flight checklist
+
+Run this **before** you build. An unchecked box is a rewrite, not a fix in the edit.
+
+**The joke**
+- [ ] **Pole chosen and written down** — pain or win (default pain)
+- [ ] If win: the comedy is the size of the relief, not the feature
+- [ ] `WHO:` and `MOMENT:` are written at the top of the build log
+- [ ] Test 1 — someone who has never heard of the offer laughs
+- [ ] Test 2 — the experience named is one the product removes
+- [ ] Test 3 — the meme's physical verb IS the caption's feeling
+- [ ] The clip's INTENSITY mismatches the feeling's size (that mismatch is the joke)
+- [ ] Cold-viewer test — cover the brand and every feature word; does it still read?
+- [ ] The caption is on rung 3: a number, a proper noun, a deflating outcome
+- [ ] The numbers and proper nouns are traceable to the customer's own copy
+- [ ] One of the eight frames, unmixed, subject first, 8–20 words, no end punctuation
+- [ ] The caption does not resolve, and does not contain the product
+
+**The clip**
+- [ ] Rights tier declared. 🟢 for client work, or a 🟢 alternate is built alongside
+- [ ] Plate colour sampled, not assumed
+- [ ] Contact sheet built and looked at
+- [ ] The action lands 0.6–1.0s in, and frame 0 has the subject on it (`-vframes 1`, looked at)
+- [ ] Native speed, no cuts, 4–15s
+
+**The background** (Class A / keyed only)
+- [ ] The joke's **world** is named in one line before searching
+- [ ] Sourced from tier 1 (`vidfarm media image --provider pixabay`) or tier 2, not from a Google
+      Images link
+- [ ] Licence recorded in the build log. No CC-BY image without the credit in the **post caption**
+- [ ] Cropped to 9:16 **deliberately**, not centre-cropped by default
+- [ ] Blurred and darkened, and **looked at on its own** before compositing
+
+**The build**
+- [ ] 1080×1920, 30fps
+- [ ] The meme is NOT cropped to 9:16
+- [ ] Layout A or B chosen deliberately; in B the subject is bottom-anchored and full width
+- [ ] Caption **block centred**, words left-aligned, lines hand-broken to near-equal length
+- [ ] Caption fully legible at frame 0, static, plated, clear of the subject's head
+- [ ] Poster layer present, so frame 0 is never bare background
+- [ ] **Tier 1 attempted first** — the offer named inside the caption, as a subject in the setup
+- [ ] Elegance test run; if any of the five answers was "no", fell back to tier 2 and said so
+- [ ] The offer is NOT in the caption's last clause, and nothing resolves
+- [ ] If tier 2: handle subordinate (≤72%), dimmed, centred with the caption, up at frame 0
+- [ ] Deletion test: remove the offer's name — is it still a complete joke?
+- [ ] No logo, no CTA, no end card, no second brand mark
+- [ ] Audio kept and normalised, measured on the render — or deliberately silent and said so
+- [ ] **Gate 1:** `vidfarm qa <dir> --harness ./experimental/meme-recaption.md`
+- [ ] **Gate 2:** `python3 meme-qa.py <render>.mp4 <dir>/composition.html` exits 0
+- [ ] **Gate 3:** you watched it
+- [ ] Post caption written, carrying the one comment ask
+
+---
+
+## Diagnosing a flop
+
+Diagnose by charge. Do not declare the video bad.
+
+| Symptom | The weak charge | The actual cause, in order of likelihood |
+|---|---|---|
+| Almost no views | Hook | The first three words are generic · the frame-0 image is not weird enough · the caption is too long to read in 0.6s |
+| Views, everyone leaves at 3s | Loop / enactment | The action landed before the caption was read (Rule 4) · the meme does not enact the verb (Test 3) |
+| Watched to the end, no reaction | Payoff / specificity | Rung 2. Add the number and the proper noun · or the joke resolves (Rule 2) |
+| Good watch time, dead comments | Bait | No post caption ask · or the ask is a poll, not an invitation to add their own version |
+| Comments are "what is this an ad for" | Rule 1 | The product leaked in — a logo, a screenshot, a category noun in the caption |
+| Reach collapsed after 2 hours | Audio / rights | A music-sync meme got muted · a 🔴 clip got claimed |
+
+---
+
+## Appendix A — `meme-composite.py`
+
+Class A (keyed) in one pass: measure the subject's real box, crop to it, scale to canvas width,
+key, bottom-anchor onto the background, keep the audio. No alpha intermediate, no cloud, $0.
+
+```python
+#!/usr/bin/env python3
+"""
+Composite a keyed MemeScreens clip onto a background, straight to an opaque MP4.
+
+Why not `vidfarm remove-greenscreen` + a transparent layer: on a machine whose
+ffmpeg lacks VP9-alpha, the local key silently writes a 75MB ProRes 4444 .mov
+that the browser renderer cannot play. Nothing errors. You find out at render.
+Compositing in one pass avoids the intermediate entirely and is free either way.
+
+The two things this does that a hand-written filter_complex forgets:
+
+  * It MEASURES the subject's bounding box instead of assuming the subject
+    fills the frame. These clips frame a torso small in a big green field —
+    676x536 inside 1280x720 in the clip this was written against. Scaling the
+    whole frame to canvas width leaves the subject about half the size it
+    should be, floating, reading as a sticker.
+  * It reads the PLATE COLOUR off the corners instead of assuming 0x00FF00.
+    A pure digital plate wants a tight key and NO despill; a filmed plate wants
+    a looser key and a light despill. Backwards, and either green survives at
+    the edges or the despill eats the subject's skin tones.
+  * It TRIMS to the subject's presence window. These clips routinely open and
+    close on several frames of empty plate — the clip this was written against
+    is empty for 0.0-0.3s and again from 6.3s to its 7.1s end. Keyed, empty
+    plate is a fully transparent frame, so the video ships with a blank
+    thumbnail and a blank tail and nothing anywhere reports it.
+
+usage: meme-composite.py <meme.mp4> <background.png|mp4> <out.mp4>
+                         [--start auto] [--dur auto] [--width-frac 1.0]
+                         [--bottom 0] [--tolerance auto]
+"""
+import subprocess, sys, numpy as np
+
+meme, bg, out = sys.argv[1], sys.argv[2], sys.argv[3]
+
+def opt(flag, default, cast=float):
+    if flag not in sys.argv:
+        return default
+    v = sys.argv[sys.argv.index(flag) + 1]
+    return default if v == "auto" else cast(v)
+
+START      = opt("--start", None)       # None = auto, from the presence window
+DUR        = opt("--dur", None)
+WIDTH_FRAC = opt("--width-frac", 1.0)   # subject width as a fraction of canvas width
+BOTTOM     = opt("--bottom", 0, int)    # px of air under the subject. 0 = on the floor
+CANVAS_W, CANVAS_H, FPS = 1080, 1920, 30
+
+def probe(path):
+    r = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0",
+                        "-show_entries", "stream=width,height", "-of", "csv=p=0:s=x", path],
+                       capture_output=True, text=True).stdout.strip()
+    return [int(v) for v in r.split("x")[:2]]
+
+W, H = probe(meme)
+
+def frames(path, w, h, vf):
+    p = subprocess.run(["ffmpeg", "-v", "error", "-i", path, "-vf", vf,
+                        "-pix_fmt", "rgb24", "-f", "rawvideo", "-"], capture_output=True)
+    n = len(p.stdout) // (w * h * 3)
+    return np.frombuffer(p.stdout, np.uint8)[:n * w * h * 3].reshape(n, h, w, 3).astype(np.int16)
+
+# --- 1. read the plate colour off the top-left corner, which is always plate ---
+corner = frames(meme, 200, 200, "fps=1,crop=200:200:20:20")
+plate = corner.reshape(-1, 3).mean(0).astype(int)
+digital = bool(plate[1] > 240 and plate[0] < 40 and plate[2] < 40)
+key_hex = "0x%02X%02X%02X" % tuple(plate)
+tol, soft, despill = (0.18, 0.03, False) if digital else (0.30, 0.08, True)
+print(f"plate {key_hex} ({'digital' if digital else 'filmed'}) "
+      f"-> chromakey {tol}:{soft}, despill={despill}")
+
+# --- 2. sample at 10fps: the subject's PRESENCE WINDOW and its bounding box ---
+FPS_S = 10
+sw, sh = 320, int(320 * H / W) // 2 * 2
+fr = frames(meme, sw, sh, f"fps={FPS_S},scale={sw}:{sh}")
+r, g, b = fr[..., 0], fr[..., 1], fr[..., 2]
+subject = ~((g > 90) & (g - r > 40) & (g - b > 40))
+coverage = subject.mean(axis=(1, 2))
+
+# "present" = at least a third of this clip's own peak coverage. A fixed
+# threshold fails on clips where the subject is genuinely tiny.
+present = np.nonzero(coverage > max(0.02, coverage.max() * 0.33))[0]
+if len(present) == 0:
+    sys.exit("no subject found — is this really a keyed clip?")
+t_in, t_out = present[0] / FPS_S, (present[-1] + 1) / FPS_S
+print(f"subject present {t_in:.2f}s -> {t_out:.2f}s")
+if START is None:
+    START = round(t_in + 0.05, 2)       # a hair inside, so frame 0 has a person on it
+if DUR is None:
+    DUR = round(min(t_out - START - 0.05, 15.0), 2)
+if DUR < 3.5:
+    print(f"WARNING: only {DUR}s of subject — loop it or cast something else")
+
+X0, Y0, X1, Y1 = sw, sh, 0, 0
+for i in present:
+    ys, xs = np.nonzero(subject[i])
+    if len(xs) < 50:            # a frame that is all plate tells us nothing
+        continue
+    X0, X1 = min(X0, xs.min()), max(X1, xs.max())
+    Y0, Y1 = min(Y0, ys.min()), max(Y1, ys.max())
+
+pad = 20
+cx0 = max(0, (X0 * W // sw) - pad)
+cx1 = min(W, (X1 * W // sw) + pad)
+cy0 = max(0, (Y0 * H // sh) - pad)
+cy1 = min(H, (Y1 * H // sh) + pad)
+cw, ch = (cx1 - cx0) // 2 * 2, (cy1 - cy0) // 2 * 2
+print(f"subject box {cw}x{ch} at {cx0},{cy0}  (source {W}x{H})")
+
+target_w = int(CANVAS_W * WIDTH_FRAC) // 2 * 2
+
+# --- 2b. AUTO-TUNE the key radius against the subject, not against the plate ---
+# chromakey works on CHROMA distance, so a pale, low-saturation subject (white
+# fur, grey hoodie, a blown-out cheek) sits closer to the plate in chroma space
+# than it looks. A radius chosen to kill the plate then makes those pixels
+# PARTIALLY transparent, and over a dark background they composite muddy — the
+# dog this was written against lost more than half its brightness (peak 228 ->
+# 108) and read grey-green, while the plate looked perfectly keyed.
+#
+# Nothing catches this: the key "worked", the alpha is doing what it was asked.
+# So: probe one mid-clip frame at each radius and keep the LARGEST one that
+# still retains the subject's brightness.
+def probe_key(tol_try, soft_try, despill_try, t):
+    chain_p = (f"[0:v]crop={cw}:{ch}:{cx0}:{cy0},scale={target_w}:-2,setpts=PTS-STARTPTS,"
+               f"chromakey={key_hex}:{tol_try}:{soft_try}")
+    if despill_try:
+        chain_p += ",despill=type=green:mix=0.35:expand=0"
+    chain_p += ("[k];color=c=black:s=%dx%d[bgp];[bgp][k]overlay=0:0:shortest=1,format=rgb24[v]"
+                % (target_w, target_w))
+    p = subprocess.run(["ffmpeg", "-v", "error", "-ss", str(t), "-i", meme,
+                        "-filter_complex", chain_p, "-map", "[v]", "-vframes", "1",
+                        "-pix_fmt", "rgb24", "-f", "rawvideo", "-"], capture_output=True)
+    n = target_w * target_w * 3
+    if len(p.stdout) < n:
+        return None
+    a = np.frombuffer(p.stdout[:n], np.uint8).reshape(target_w, target_w, 3).astype(np.int16)
+    flat = a.reshape(-1, 3)
+    lum = flat.mean(1)
+    lit = flat[lum > max(lum.max() * 0.75, 1)]          # the subject's bright side
+    green_left = ((flat[:, 1] - flat[:, 0] > 40) & (flat[:, 1] - flat[:, 2] > 40)).mean()
+    return lit.mean(), green_left
+
+t_probe = START + DUR / 2
+# chromakey's similarity floor is 1e-05, not 0 — a literal 0 is a hard filter error
+src_lit, _ = probe_key(1e-5, 0.0, False, t_probe)       # ~nothing keyed = the truth
+best = None
+for tol_try in (0.34, 0.28, 0.22, 0.18, 0.14, 0.10, 0.07):
+    r = probe_key(tol_try, soft, despill, t_probe)
+    if r is None:
+        continue
+    lit, green_left = r
+    keep = lit / src_lit if src_lit else 1.0
+    ok = keep > 0.88 and green_left < 0.02              # subject intact AND plate gone
+    print(f"  tol {tol_try:.2f}: brightness kept {keep*100:5.1f}%, "
+          f"green left {green_left*100:4.1f}%  {'ok' if ok else ''}")
+    if ok:
+        best = tol_try
+        break
+if best is None:
+    print("  no radius satisfies both — keeping the sampled default, CHECK THE FRAME")
+else:
+    tol = best
+if "--tolerance" in sys.argv and sys.argv[sys.argv.index("--tolerance") + 1] != "auto":
+    tol = opt("--tolerance", tol)
+print(f"key radius {tol}")
+
+# --- 3. one pass: crop -> scale -> key -> bottom-anchored overlay, audio kept ---
+# setpts=PTS-STARTPTS is load-bearing: after -ss the keyed stream's first frame
+# carries a PTS a hair above 0, so overlay emits one BACKGROUND-ONLY frame at
+# t=0 — and t=0 is the thumbnail. Rebasing to zero is the whole fix.
+chain = (f"[1:v]crop={cw}:{ch}:{cx0}:{cy0},scale={target_w}:-2,setpts=PTS-STARTPTS,"
+         f"chromakey={key_hex}:{tol}:{soft}")
+if despill:
+    chain += ",despill=type=green:mix=0.35:expand=0"
+chain += "[k];[0:v]scale=%d:%d:force_original_aspect_ratio=increase," % (CANVAS_W, CANVAS_H)
+chain += f"crop={CANVAS_W}:{CANVAS_H},setsar=1[bgv];"
+chain += f"[bgv][k]overlay=(W-w)/2:H-h-{BOTTOM}:shortest=1,format=yuv420p[v]"
+
+bg_in = ["-loop", "1", "-i", bg] if bg.lower().endswith((".png", ".jpg", ".jpeg")) else ["-i", bg]
+cmd = (["ffmpeg", "-y", "-v", "error"] + bg_in +
+       ["-ss", str(START), "-t", str(DUR), "-i", meme,
+        "-filter_complex", chain,
+        "-map", "[v]", "-map", "1:a?",
+        "-af", "loudnorm=I=-16:TP=-1.5:LRA=11",
+        "-r", str(FPS), "-t", str(DUR),
+        "-c:v", "libx264", "-crf", "20", "-pix_fmt", "yuv420p",
+        "-c:a", "aac", "-b:a", "128k", out])
+subprocess.run(cmd, check=True)
+print("wrote", out)
+```
+
+Then look at it before you build the composition — always:
+
+```bash
+ffmpeg -v error -i out.mp4 -vf "fps=1,scale=200:-1,tile=7x1" -frames:v 1 check.png
+```
+
+**Green surviving at the edges** → the plate was filmed, not digital; raise `--tolerance`.
+**Grey, lifeless skin** → despill ran on a digital plate; it should not have.
+
+---
+
+## Appendix B — the caption layer
+
+A static, plated card: block centred, words left-aligned, no animation, `data-start="0"`.
+This is the exact markup from the worked example, which measures 49.8% block centre.
+
+```html
+<!-- Layout B: caption on a translucent plate over the background, above the subject.
+     The WRAPPER is full width and centres; the PLATE is an inline-block that rides
+     that centre. left:7% would pin the plate to 7% and leave the frame lopsided. -->
+<div id="caption" data-start="0" data-duration="5.9" data-end="5.9"
+     data-track-index="2" data-layer-kind="text" data-layer-mode="publish"
+     style="position:absolute; left:0; top:13%; width:100%;">
+  <div class="capwrap"><div class="memecap">when i've had 10 tabs open<br>since 7pm for one scallop roll<br>and we're getting pizza again</div><br><span class="handle">dishcover.io</span></div>
+</div>
+
+<style>
+@font-face { font-family:"TikTok Sans"; src:url("media/fonts/TikTokSans-700.woff2") format("woff2");
+             font-weight:700; font-display:block; }
+.capwrap{ text-align:center; }        /* centres the BLOCK and the handle under it */
+.handle{                              /* the offer, as a BYLINE — see Rule 1 */
+  display:inline-block;
+  margin-top:16px;
+  font-family:"TikTok Sans";
+  font-weight:700;
+  font-size:34px;                     /* 63% of the caption — must stay <=72% */
+  letter-spacing:.02em;
+  color:rgba(255,255,255,.72);        /* alpha <=0.85 */
+  background:rgba(0,0,0,.42);
+  padding:8px 18px;
+  border-radius:10px;
+}
+.memecap{
+  font-family:"TikTok Sans";          /* no fallback chain on purpose — see Typography DNA */
+  font-weight:700;
+  font-size:54px;
+  line-height:1.26;
+  color:#fff;
+  text-align:left;                    /* keeps the WORDS ragged-right, not title-carded */
+  background:rgba(0,0,0,.58);
+  padding:26px 32px;
+  border-radius:18px;
+  display:inline-block;
+  max-width:88%;
+  /* no text-shadow, no -webkit-text-stroke, no animation, no transition */
+}
+</style>
+```
+
+For **Layout A**, the same block with `background:#fff; color:#111;` sitting in the top plate, and
+the meme on its own layer below it at `top:30%`.
+
+**Break the lines yourself** with `<br>`, at the clause, to **near-equal length**. The collapse
+(`and we're getting pizza again`) starts its own line. Never let the renderer wrap a meme caption —
+its break lands mid-thought about half the time and the joke reads as two half-jokes.
+
+The `<br>` before the handle is deliberate: it drops the byline onto its own line under the plate
+rather than beside it, and it inherits the wrapper's centring so plate and handle share one axis.
+
+**Add the poster layer.** A one-shot composition renders frame 0 before the video element has
+decoded, so frame 0 ships as bare background — and frame 0 is the thumbnail:
+
+```html
+<img id="poster" class="clip" data-start="0" data-duration="5.9" data-end="5.9"
+     data-track-index="0" data-layer-kind="image" data-layer-mode="publish"
+     src="media/poster.png" style="width:100%;height:100%;object-fit:cover">
+```
+
+```bash
+ffmpeg -i media/scene.mp4 -vframes 1 -update 1 media/poster.png   # frame 0 of the same clip
+```
+
+**Symlink `index.html` → `composition.html`** or `hyperframes render` exits with
+*"No composition found."*
+
+---
+
+## Appendix C — build the shelf index once
+
+The shelf pages at 200, the CLI cannot follow the cursor, and the slugs are the index — so pull the
+whole thing once through the REST route and grep the file instead of re-querying.
+
+```python
+#!/usr/bin/env python3
+"""meme-index.py — pull every MemeScreens raw into one greppable TSV.
+
+The `--query` filter on this endpoint is thin and inconsistent (a search for
+"hungry food eating" returns nothing on a shelf full of people eating), and the
+AI descriptions are blind to the meme's identity. So: pull it all, index by slug.
+
+Paging note: `vidfarm public-raws` has NO --cursor flag and the server caps a
+shelf at 200 per call, so the CLI alone can only ever show you the first 200 of
+a 1000-clip shelf — silently, with a next_cursor you cannot use. Go through
+`vidfarm api GET` instead, which does take one.
+"""
+import json, subprocess, re
+
+SHELVES = ("greenscreen", "text-graphics", "lifestyle", "b-roll", "reaction", "scroll-stopper")
+
+def fetch(cat, cursor):
+    path = f"/api/v1/public-raws?category={cat}&limit=200"
+    if cursor:
+        path += f"&cursor={cursor}"
+    out = subprocess.run(["vidfarm", "api", "GET", path],
+                         capture_output=True, text=True).stdout
+    brace = out.find("{")          # first line is a coloured "GET … → 200" status line
+    if brace < 0:
+        return None
+    try:
+        return json.JSONDecoder().raw_decode(out[brace:])[0]
+    except ValueError:
+        return None
+
+rows, seen = [], set()
+for cat in SHELVES:
+    cursor, pages = None, 0
+    while pages < 20:              # backstop; a shelf that never ends is a bug, not a shelf
+        d = fetch(cat, cursor)
+        if not d or not d.get("raws"):
+            break
+        for x in d["raws"]:
+            if x["rawId"] in seen:
+                continue
+            seen.add(x["rawId"])
+            name = re.sub(r"-[0-9a-f]{6,}$", "", x["slugId"] or "").replace("-", " ")
+            dur = x.get("durationSeconds")      # nullable on some rows — do not assume
+            rows.append((x["rawId"], x.get("sourceType") or "?",
+                         round(dur, 1) if dur else "?",
+                         name, (x.get("description") or "").replace("\t", " ")))
+        cursor, pages = d.get("next_cursor"), pages + 1
+        if not cursor:
+            break
+    print(f"  {cat}: {pages} page(s), {len(rows)} unique so far")
+
+with open("meme-index.tsv", "w") as f:
+    f.write("rawId\tsourceType\tsec\tslug\tdescription\n")
+    for r in rows:
+        f.write("\t".join(str(v) for v in r) + "\n")
+print(len(rows), "raws -> meme-index.tsv")
+```
+
+```bash
+python3 meme-index.py
+grep -iE "confus|huh|stare|blank" meme-index.tsv | cut -f1,3,4    # cast by VERB, on the slug
+```
+
+The preview URL is derivable from the id, so downloading is a loop:
+
+```
+https://vidfarmprodstack-vidfarmbucket335ee12f-0vsvtd5earqy.s3.us-east-1.amazonaws.com/users/system/public-raws/<rawId>/source.mp4
+```
+
+---
+
+## Appendix D — a worked example
+
+**Offer:** Dishcovery (dishcover.io) — search NYC restaurants **by dish**, not by restaurant. Its own
+homepage says *"Don't search for a restaurant. Search for dinner."*
+
+```
+WHO:    someone in NYC who already knows what they want to eat
+MOMENT: the 40 minutes between the craving and giving up on it
+```
+
+| | |
+|---|---|
+| Frame | `When I …` — the complaint is embarrassing, so first person |
+| Verb cast for | *deflating; accepting a bad outcome* |
+| Caption | `when i've had 10 tabs open` / `since 7pm for one scallop roll` / `and we're getting pizza again` |
+| Clip (🟡) | `my-disappointment-is-immeasurable-and-my-day-is-ruined` · 1280×720 · plate `0x00FF00` digital · key 0.34 |
+| Clip (🟢) | `hangover-dog` · 2160×3840 · plate `0x00DA00` filmed · key **0.22** |
+| Background | tier 1 — Pixabay, *"dark empty restaurant interior night"*, royalty-free, no attribution. Cropped to the window and table, `gblur=18`, `brightness=-0.06` |
+| Handle | `dishcover.io` — 34px against a 54px caption (63%), alpha .72, under the plate, up at frame 0 |
+| Audio | 🟡 clip: its own, −15.9 LUFS. 🟢 clip: **source is silent (−70 LUFS)** — ships silent, trending audio at upload |
+
+**Rung 3, and not invented.** A testimonial on the customer's own homepage reads *"Do you realize I
+had 10 tabs open on Resy trying to find a sushi place with a scallop roll?"* — so the number (10)
+and the object (scallop roll) are the customer's own words, per Rule 6.
+
+> ⚠️ **The first draft of this caption kept "resy" in it, and that was a Rule 8 violation** —
+> a real, named, adjacent company personified as the villain. It survived a full build, two renders
+> and a review, because a named brand *reads* like good rung-3 specificity. It was caught by a
+> human, not by a check. The fix keeps the specificity (`10 tabs`, `7pm`, `scallop roll`) and drops
+> the company. **When a real brand name is what makes your caption feel sharp, that is the signal to
+> replace it, not to keep it.**
+
+**Three-way lock:** *standalone* — 10 tabs since 7pm ending in pizza is funny with no context;
+*problem space* — deleting that hour is the product's entire pitch; *enactment* — both clips hold a
+deadpan while something disappointing is already true.
+
+**The background is the joke's world, not the product's.** An empty restaurant at night is the place
+they never got to. Blurred so it reads as a set, dark so the plate and the keyed subject both pop.
+
+**Gates:** `vidfarm qa` 18/18 · `meme-qa.py` **26/26** on both builds (block centre measured at
+**49.8%**). The 🟢 build needs `--silent-ok`, and fails without it — which is the check working.
+
+**Naming the offer — both tiers, built and measured.**
+
+| | **v003 — tier 1** ✅ preferred | **v001 / v002 — tier 2** |
+|---|---|---|
+| Caption | `dishcover.io watching me` / `open 10 tabs since 7pm` / `for one scallop roll` | `when i've had 10 tabs open` / `since 7pm for one scallop roll` / `and we're getting pizza again` |
+| Frame | `<Entity> watching me …` — the offer as witness | `When I …` |
+| Naming | in the sentence, 12 words | subtext handle, 34px @ alpha .72 |
+| Handle | none — the caption already carries it | `dishcover.io` under the plate |
+
+Tier 1 reads cleanly here because the meme is a face **looking at you**: the dog *is* dishcover.io,
+watching you fail. The payoff is `for one scallop roll` — the person's own dysfunction — so the
+offer is named and the joke still does not resolve. That is the whole trick.
+
+**Elegance test on v003:** eight frames ✅ · 12 words ✅ · reads as a character not a sponsor ✅ ·
+collapse lands on the person ✅ · funny without knowing the product ✅. Five yeses, so tier 1 ships
+and the handle comes off.
+
+**Six negative controls confirm the gates bite.** Tier 2: domain in the sentence, handle at 52px,
+handle deleted. Tier 1: offer moved into the payoff (`and dishcover.io found it`), resolution
+language (`so i finally found it`), and the offer removed from both places — each produces fatal
+failures, none silent.
+
+The bait is in the post caption:
+
+> 10 tabs open since 7pm and we ordered pizza again. what's the one dish you can never find who
+> serves it
+
+---
+
+## Appendix E — `meme-qa.py` (gate 2: enforce it on the RENDER)
+
+Exits 1 on any fatal failure. Run it after every render, in CI if you have one.
+
+```bash
+python3 meme-qa.py renders/job-v001.mp4 work/job/v001/composition.html --offer dishcover.io --pole pain
+python3 meme-qa.py renders/job-v002.mp4 work/job/v002/composition.html --offer dishcover.io --pole win --silent-ok
+```
+
+```python
+#!/usr/bin/env python3
+"""
+meme-qa.py — enforce the meme-recaption harness on the RENDER, not on the markup.
+
+`vidfarm qa` reads the composition DOM. It has never seen a pixel, so every
+defect this format actually produces walks straight past it: a blank thumbnail,
+an empty tail, a subject eaten by a loose key, a caption pinned flush-left, a
+background that competes with the joke, a silent audio track, a caption that
+names the product. All of those pass `vidfarm qa` today.
+
+This checks the finished MP4 and the composition text together, and EXITS 1.
+
+usage: meme-qa.py <render.mp4> <composition.html> [--offer dishcover.io]
+                  [--pole pain|win] [--silent-ok] [--json]
+"""
+import json, re, subprocess, sys
+import numpy as np
+
+render, comp = sys.argv[1], sys.argv[2]
+SILENT_OK = "--silent-ok" in sys.argv
+OFFER = (sys.argv[sys.argv.index("--offer") + 1].strip().lower()
+         if "--offer" in sys.argv else None)
+# The pole changes what the payoff is allowed to do (Rule 2). Default to PAIN:
+# it is the stricter of the two, so an unset pole can never silently pass a
+# resolution that nobody decided to allow.
+POLE = (sys.argv[sys.argv.index("--pole") + 1].strip().lower()
+        if "--pole" in sys.argv else "pain")
+html = open(comp).read()
+results = []
+
+
+def check(name, ok, detail, fatal=True):
+    results.append({"check": name, "ok": bool(ok), "detail": detail, "fatal": fatal})
+
+
+def probe(path, vf, w, h, pre=(), post=("-vframes", "1")):
+    # -ss/-sseof are INPUT options and go before -i; -vframes is an OUTPUT option
+    # and goes after. Getting that backwards decodes nothing and reports no frame.
+    p = subprocess.run(["ffmpeg", "-v", "error", *pre, "-i", path, "-vf", vf, *post,
+                        "-pix_fmt", "rgb24", "-f", "rawvideo", "-"], capture_output=True)
+    n = len(p.stdout) // (w * h * 3)
+    if n == 0:
+        return None
+    return np.frombuffer(p.stdout, np.uint8)[:n * w * h * 3].reshape(n, h, w, 3).astype(np.int16)
+
+
+W, H = 1080, 1920
+dur = float(subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=duration",
+                            "-of", "csv=p=0", render], capture_output=True,
+                           text=True).stdout.strip())
+
+# ---------------------------------------------------------------- 1. duration
+check("duration_4_15s", 4.0 <= dur <= 15.0, f"{dur:.1f}s")
+
+# ------------------------------------------- 2. frame 0 and the last frame LIVE
+# Sampled with -vframes 1, never with fps=N: `fps` hands you the middle of the
+# first interval, so a genuinely blank frame 0 renders as a perfect still.
+first = probe(render, "scale=270:480", 270, 480)
+last = probe(render, "scale=270:480", 270, 480, pre=("-sseof", "-0.3"))
+for label, fr in (("first", first), ("last", last)):
+    if fr is None:
+        check(f"{label}_frame_decodes", False, "no frame decoded")
+        continue
+    a = fr[0]
+    # "alive" = real spatial detail, not a flat plate with a caption pasted on it
+    band = a[int(480 * 0.42):, :]              # below the caption zone = the subject's half
+    check(f"{label}_frame_has_subject", band.std() > 12,
+          f"lower-band stdev {band.std():.1f} (>12)")
+
+# ------------------------------------------------------ 3. no residual green key
+mid = probe(render, "scale=270:480", 270, 480, pre=("-ss", str(dur / 2)))
+if mid is not None:
+    a = mid[0]
+    r, g, b = a[..., 0], a[..., 1], a[..., 2]
+    green = ((g - r > 45) & (g - b > 45) & (g > 80)).mean()
+    check("no_residual_green", green < 0.005, f"{green*100:.2f}% green pixels (<0.5%)")
+
+# ------------------------------------- 4. caption block is horizontally CENTRED
+# Find the caption plate in frame 0 by its own darkness against the background,
+# then compare its horizontal centre to the canvas centre.
+if first is not None:
+    a = first[0]
+    top = a[: int(480 * 0.42)]                        # the caption zone
+    lum = top.mean(2)
+    text = lum > 170                                  # white type on a dark plate
+    cols = np.nonzero(text.any(0))[0]
+    rows = np.nonzero(text.any(1))[0]
+    if len(cols) < 5:
+        check("caption_visible_at_frame_0", False, "no bright text found in the top zone")
+    else:
+        check("caption_visible_at_frame_0", True, f"{len(cols)} text columns")
+        x0, x1 = cols.min(), cols.max()
+        centre = (x0 + x1) / 2 / 270
+        off = abs(centre - 0.5)
+        check("caption_horizontally_centred", off <= 0.03,
+              f"block centre at {centre*100:.1f}% of width (target 50%, tol 3%)")
+        # margins: the block must not run edge to edge, and must not hug one side
+        check("caption_side_margins", x0 / 270 > 0.04 and x1 / 270 < 0.96,
+              f"left {x0/270*100:.1f}%, right {x1/270*100:.1f}%")
+        # vertical: inside the safe zone, and not jammed against the very top
+        y0, y1 = rows.min() / 480, rows.max() / 480
+        check("caption_vertical_placement", 0.08 <= y0 and y1 <= 0.85,
+              f"spans {y0*100:.1f}%-{y1*100:.1f}% (safe zone 8-85%)")
+        # Balance: hand-broken lines should be near-equal so the ragged edge is
+        # shallow. Measure per LINE, not per pixel row — a row clipping the top of
+        # an apostrophe is 3px wide and makes any caption look 100% ragged.
+        rowhas = text.any(1)
+        lines, run = [], None
+        for i, on in enumerate(rowhas):
+            if on and run is None:
+                run = i
+            elif not on and run is not None:
+                lines.append((run, i)); run = None
+        if run is not None:
+            lines.append((run, len(rowhas)))
+        lines = [(a_, b_) for a_, b_ in lines if b_ - a_ >= 4]     # drop stray marks
+        widths = []
+        for a_, b_ in lines:
+            c = np.nonzero(text[a_:b_].any(0))[0]
+            if len(c):
+                widths.append(c.max() - c.min())
+        if len(widths) >= 2:
+            rag = 1 - (min(widths) / max(widths))
+            check("caption_lines_balanced", rag < 0.45,
+                  f"{len(widths)} lines, raggedness {rag*100:.0f}% (<45%)", fatal=False)
+
+# ------------------------------------------ 5. the background is PUSHED DOWN
+# A background that competes with the caption is the format's quietest failure.
+# Measure high-frequency detail in the top corners — the part that is background
+# on every layout — and require it to be soft.
+if mid is not None:
+    a = mid[0].mean(2)
+    # Measure ABOVE the caption (top 11%), never through it — the plate's own hard
+    # edges read as background detail and the check fires on a correct build.
+    strip = a[: int(480 * 0.11), :]
+    lap = np.abs(np.diff(strip, axis=1)).mean()
+    check("background_pushed_down", lap < 6.0,
+          f"detail above the caption {lap:.2f} (<6.0 — blur/darken it)", fatal=False)
+    check("background_not_blown_out", strip.mean() < 150,
+          f"top-strip luma {strip.mean():.0f} (<150)", fatal=False)
+
+# ------------------------------------------------------------------- 6. audio
+out = subprocess.run(["ffmpeg", "-v", "info", "-i", render, "-af", "ebur128", "-f", "null", "-"],
+                     capture_output=True, text=True).stderr
+m = re.search(r"Integrated loudness:\s*\n\s*I:\s*(-?[\d.]+)\s*LUFS", out)
+lufs = float(m.group(1)) if m else None
+if lufs is None:
+    check("audio_measured", False, "could not measure loudness")
+elif lufs < -50:
+    check("audio_level", SILENT_OK,
+          f"{lufs:.1f} LUFS = SILENT. Declare it in the handoff and pass --silent-ok")
+else:
+    check("audio_level", -20 <= lufs <= -13, f"{lufs:.1f} LUFS (target -16, band -20..-13)")
+
+# ------------------------------------------------- 7. the caption, as written
+cap = re.search(r'class="memecap"[^>]*>(.*?)</div>', html, re.S)
+if not cap:
+    check("caption_found", False, "no .memecap block in the composition")
+else:
+    check("caption_found", True, "")
+    text_raw = re.sub(r"<br\s*/?>", " ", cap.group(1))
+    text_cap = re.sub(r"<[^>]+>", "", text_raw).strip()
+    words = text_cap.split()
+    check("caption_word_count", 8 <= len(words) <= 20, f"{len(words)} words (8-20): {text_cap!r}")
+    check("caption_no_end_punctuation", not re.search(r"[.!?]$", text_cap),
+          f"ends {text_cap[-12:]!r}")
+    check("caption_not_all_caps", not text_cap.isupper(), "casing")
+    # NOTE the entity frame allows . and - so a domain can BE the subject
+    # ("dishcover.io watching me ..."), which is the tier-1 naming vehicle.
+    FRAMES = (r"^when i\b", r"^when you\b", r"^me when\b", r"^me trying\b",
+              r"^my \w+ when\b", r"^why my\b",
+              r"^[\w][\w'.\- ]{0,24} (when|with|after|watching|reading|seeing|hearing) ")
+    check("caption_uses_a_frame", any(re.search(f, text_cap, re.I) for f in FRAMES),
+          f"must open with one of the seven frames — got {' '.join(words[:4])!r}")
+    check("caption_is_lowercase_start", text_cap[:1].islower(),
+          "meme captions are typed, not headlined", fatal=False)
+    # the product must not be in the video (Rule 1), and it must not resolve (Rule 2)
+    BANNED = ("link in bio", "sign up", "free trial", "get started", "book a demo",
+              "download now", "learn more", "comment below", "so i", "so now",
+              "until i found", "then i found")
+    hit = [b for b in BANNED if b in text_cap.lower()]
+    check("caption_no_cta_or_resolution", not hit, f"found {hit}")
+    # hand-broken lines are required — the renderer's own wrap lands mid-thought
+    check("caption_lines_hand_broken", "<br" in cap.group(1),
+          "use <br> at the clause; never let the renderer wrap a meme caption")
+
+# ------------------------------------------------- 7b. naming the offer
+# The offer IS named on the video. Two ways, in priority order:
+#   tier 1 — inside the caption, as the SUBJECT of the setup
+#   tier 2 — the subtext handle, when tier 1 will not read elegantly
+# At least one must be true. What must NEVER be true is the offer appearing in
+# the PAYOFF — the caption's final clause — because that is the joke resolving
+# into a pitch, and a meme that resolves is an ad with extra steps (Rule 2).
+if OFFER:
+    stem = OFFER.split(".")[0]
+    hnd = re.search(r'class="handle"[^>]*>(.*?)</', html, re.S)
+    handle_txt = hnd.group(1).lower() if hnd else ""
+    has_handle = bool(hnd) and OFFER in handle_txt
+    cap_txt = text_cap.lower() if cap else ""
+    in_caption = stem in cap_txt
+
+    check("offer_named_somewhere", in_caption or has_handle,
+          f"tier 1 caption={in_caption}, tier 2 handle={has_handle} — name it in one of them")
+    if in_caption:
+        print(f"  · pole: {POLE.upper()}  ·  naming strategy: TIER 1 (in-caption)")
+    elif has_handle:
+        print(f"  · pole: {POLE.upper()}  ·  naming strategy: TIER 2 (subtext handle)")
+
+    # THE line that must not be crossed on the PAIN pole: the offer in the payoff.
+    # On the WIN pole the relief IS the joke, so the offer belongs in the last
+    # clause and this check is deliberately not run.
+    if in_caption and cap and POLE == "pain":
+        raw_lines = [re.sub(r"<[^>]+>", "", l).strip()
+                     for l in re.split(r"<br\s*/?>", cap.group(1))]
+        raw_lines = [l for l in raw_lines if l]
+        payoff = raw_lines[-1].lower() if raw_lines else ""
+        check("offer_not_in_payoff", stem not in payoff,
+              f"payoff is {payoff!r} — the offer belongs in the SETUP, not the collapse")
+        # ...and the offer must not be the thing that WORKS.
+        # Matching literal phrases ("found it") is not enough: "dishcover.io found
+        # the scallop roll" resolves just as hard and contains none of them. So
+        # look for a SUCCESS VERB anywhere after the offer's name, plus the
+        # generic turn phrases that resolve without naming anything.
+        SUCCESS = (r"found|fixed|saved|solved|cleared|handled|sorted|caught|nailed|"
+                   r"works?|worked|delivered|got it|did it|sent|booked|showed me|told me")
+        turn = [r for r in (r"\bso i\b", r"\bthen i\b", r"\buntil i\b", r"\bnow i\b",
+                            r"\bfinally\b", r"\bturns out\b")
+                if re.search(r, cap_txt)]
+        after = cap_txt.split(stem, 1)[1] if stem in cap_txt else ""
+        verb = re.search(rf"\b({SUCCESS})\b", after)
+        hit = turn + ([f"{stem} … {verb.group(1)}"] if verb else [])
+        check("caption_does_not_resolve", not hit,
+              f"resolution language {hit} — on the pain pole the meme is the complaint "
+              f"(use --pole win if the relief IS the joke)")
+
+    # Both poles: the joke may name the OFFER, never a FEATURE. A feature needs
+    # product context to parse, so it lands only on people who already bought —
+    # which is the cold-viewer test, mechanised.
+    if cap:
+        FEATURE = (r"\bv\d+\b", r"\bversion \d", r"\bbeta\b", r"\bapi\b", r"\bdashboard\b",
+                   r"\bintegration\b", r"\bsync\b", r"\bplugin\b", r"\bworkflow\b",
+                   r"\bplatform\b", r"\bfeature\b", r"\bpremium\b", r"\bpro plan\b",
+                   r"\bautomation\b", r"\bAI-powered\b")
+        fhit = [f for f in FEATURE if re.search(f, cap_txt, re.I)]
+        check("no_feature_words", not fhit,
+              f"feature language {fhit} — write the niche's experience, not the product's mechanism")
+
+    # If a handle is present it is a BYLINE: subordinate and dimmed, or it is a CTA.
+    if hnd:
+        fs = {c: int(m.group(1)) for c in ("memecap", "handle")
+              for m in [re.search(rf"\.{c}\s*\{{[^}}]*font-size:\s*(\d+)px", html, re.S)] if m}
+        if "memecap" in fs and "handle" in fs:
+            ratio = fs["handle"] / fs["memecap"]
+            check("handle_is_subordinate", ratio <= 0.72,
+                  f"handle {fs['handle']}px vs caption {fs['memecap']}px = {ratio*100:.0f}% (<=72%)")
+        dim = re.search(r"\.handle\s*\{[^}]*color:\s*rgba\([^)]*?,\s*([\d.]+)\s*\)",
+                        html, re.S)
+        check("handle_is_dimmed", bool(dim) and float(dim.group(1)) <= 0.85,
+              f"handle alpha {dim.group(1) if dim else 'opaque'} (<=0.85)", fatal=False)
+
+# --------------------------------------------- 8. one shot, no brand chrome
+check("single_shot", len(re.findall(r"<video\b", html)) == 1,
+      f"{len(re.findall(r'<video', html))} video layer(s) — a meme recaption is ONE shot")
+check("no_animation_on_caption",
+      not re.search(r"\.memecap\s*\{[^}]*animation", html, re.S),
+      "the caption is a static card — no animation, no word-pop")
+
+# ----------------------------------------------------------------- verdict
+fails = [r for r in results if not r["ok"]]
+hard = [r for r in fails if r["fatal"]]
+if "--json" in sys.argv:
+    print(json.dumps(results, indent=1))
+else:
+    for r in results:
+        mark = "PASS" if r["ok"] else ("FAIL" if r["fatal"] else "WARN")
+        print(f"  [{mark}] {r['check']:32s} {r['detail']}")
+    print(f"\n{len(results)-len(fails)}/{len(results)} passed"
+          f"{'' if not fails else f' — {len(hard)} fatal, {len(fails)-len(hard)} warning'}")
+sys.exit(1 if hard else 0)
+```