@officexapp/vidfarm-devcli 0.21.56 → 0.21.58

package/experimental/engaging-chat-convo.md

@@ -0,0 +1,1370 @@
+---
+name: engaging-chat-convo
+video_type: Chat-thread slideshow — a text conversation told in N still screenshots, one story, one product beat. Ships as a photo carousel; a 3s-per-slide MP4 is the proof copy (TikTok / Reels / Shorts)
+checks:
+  duration_sec: 24-45      # the VIDEO version. N slides x 3.0s exactly. 8 slides = 24s, 15 = 45s
+  aspect: 9:16
+  first_frame_visual: required
+  first_frame_text: required
+  text_by_sec: 0           # slide 1's first bubble is up at frame 0. There is no build-on
+  captions: optional       # there is no narration to caption. The bubbles ARE the content
+  audio: optional          # the carousel is silent; the poster adds sound in-app
+  font_regime: required
+  safe_zone: required
+  # NO `scenes:` LINE, ON PURPOSE. `scenes` counts VISUAL clips, and this format has
+  # exactly one for the whole video — the black canvas layer. Every slide is a TEXT
+  # layer, so a `scenes: 8-15` line fails every legal build with "got 1". The slide
+  # count (8-15) is enforced by build-thread.py before render and thread-qa.py after,
+  # both of which can actually count slides.
+  max_scene_sec: 3.2       # 3.0 is the number. The 0.2 is render tolerance, not licence
+  max_text_cards: 16       # one per slide, plus tolerance
+  max_simultaneous_text: 1 # one stack per slide. A second text layer is a caption, and
+                           # a caption on a chat screenshot destroys the whole illusion
+  # A "cue" here is a whole slide of bubbles, not one bubble. The number that
+  # actually matters is PER BUBBLE (<=22 words) and it is enforced by thread-qa.py,
+  # not by this line. Set high on purpose so gate 1 stays useful for everything else.
+  max_words_per_cue: 90
+  max_dead_air_sec: 1.0    # there is never a frame without a bubble, except a skip card
+  max_tail_sec: 0.5
+  forbid_text:
+    - link in bio
+    - sign up
+    - free trial
+    - get started
+    - book a demo
+    - download now
+    - download the app
+    - learn more
+    - swipe up
+    - visit our website
+    # the bait lives in the POST caption, never inside the thread:
+    - comment below
+    - part 2 in my bio
+    - follow for part
+    - follow for more
+---
+
+# Engaging Chat Convo
+
+> A public Vidfarm prompt. Read it end to end before you build.
+
+## The reference thread — read it first
+
+**Open it before you write a line of dialogue.**
+
+| | |
+|---|---|
+| **Template** | `template_019f4ab5e3af77e8b90f8e8286a9cf6a` |
+| **Title** | "Slideshow Chat Convo" |
+| **Watch it** | <https://vidfarm.cc/discover/templates/feed?template=template_019f4ab5e3af77e8b90f8e8286a9cf6a> |
+| **Fork it** | `vidfarm serve template_019f4ab5e3af77e8b90f8e8286a9cf6a` |
+| **Origin** | vt.tiktok.com · `popularGroup: Slideshows` · featured |
+| **Shape** | 39.0s · 13 slides · 2 of them skip cards · `mediaKind: slideshow` |
+
+**It runs at exactly 3.0s per slide** — 39.0/13. That is where the 3.0s constant comes from, and it
+is the same constant as `sticker-slideshow-tips`. The two formats share a chassis and share nothing
+else.
+
+**The reference story, beat by beat.** Read this table against the slides; it is the spine of
+everything below.
+
+| Slide | What happens | What it is doing |
+|---|---|---|
+| 1 | `hey its marc` → "I don't actually know a Marc." The number was smudged ink on his hand | **The wrong foot.** Opens mid-mistake, no set-up |
+| 2 | She is kind about it. They say goodbye | **The turn.** The stranger does not leave |
+| 3 | `>>>` | **Skip card.** Buys a month of story for free |
+| 4 | She comes back — is his Anna the Anna in her class? | The stranger *chose* to text first |
+| 5 | Names, finally: Beck and Marc | Names arrive LATE, and are a beat |
+| 6 | `u go to HARVARD?` / "I just worked hard and got super lucky" | **Reveal 1** — she is out of his league |
+| 7–9 | He is a firefighter. Mutual encouragement. `i try` | The warmth that makes the last act land |
+| 10 | `>>>` | **Skip card 2** |
+| 11 | 3am: "Hi I am so sorry but can I please call you?" → "How the fuck are you supposed to change the battery in a smoke alarm" | **The break.** The polite one swears |
+| 12 | Meltdown, then `MARCUS.` — she knows his real name | **The payoff.** One word |
+| 13 | `ur helpless, this will be easier if we facetime` / "THANK YOU" / `lol give me a sec` | **The cliffhanger.** It never resolves |
+
+**Nothing in it is filmed, drawn, sourced or licensed.** Thirteen slides of type on black. That is
+why this is the cheapest format in the catalog and the fastest one to produce at volume.
+
+## The one test — the three-way lock
+
+Three questions. **All three must be yes** or you do not have a chat thread yet.
+
+| # | Question | If no |
+|---|---|---|
+| 1 | **Screenshot-worthy** — would a real person screenshot one slide and send it to a friend, with no caption? | You wrote dialogue, not a scene. Nothing here travels |
+| 2 | **Two voices** — recolour every bubble grey. Can you still tell who is speaking, from the typing alone? | You wrote one person twice. This is the failure that kills the format |
+| 3 | **Unfinished** — does the last slide leave something the reader wants and does not get? | You wrote an ending. Endings do not get comments |
+
+Test 2 is the one that gets skipped and the one that decides everything. **The colours are a
+convenience, not the characterisation.** In the reference you know who is talking with the colour
+covered, because one of them types `ur` and `bc` and `lol` with no capital letters and no full
+stops, and the other one writes complete sentences with commas and a period at the end. Get that
+right and the thread reads as real. Get it wrong and it reads as one AI playing both parts, which
+is exactly what it is.
+
+---
+
+## Part 0 — who this is for
+
+**Write your viewer in one line, at the top of your build log, before you write any dialogue.**
+This format is read by someone who is *already reading strangers' texts for fun* — the audience for
+wrong-number threads, group-chat screenshots and comment-section drama. They are not looking for
+your product and they have no problem you can name.
+
+That is the whole reason the format works as an ad: **the reader is unaware, and a story is the
+only thing an unaware reader will accept.** It is also the reason it is easy to ruin — the moment
+the thread becomes about the product, they are being sold to by a stranger's text messages, which
+is worse than a normal ad, not better.
+
+Put these four lines at the top of your build log:
+
+```
+STORY:     A wrong number that turns into a friendship, then a 3am smoke-alarm crisis
+ENGINE:    comedy   (one of: comedy | drama | gossip | wholesome-cringe — pick ONE)
+VOICES:    A = lowercase, no punctuation, deflects with jokes
+           B = full sentences, capitals, periods, emoji, earnest
+OFFER:     <product> — <the one mechanism it automates>
+SHILL:     slide 7 of 12
+```
+
+- **Register: two private people, neither performing.** Nobody in a chat thread explains the world
+  to the reader. If a bubble exists to inform the audience, delete it.
+- **They read with sound off, holding the swipe.** A carousel reader sets their own dwell time —
+  which is why this format may carry far more text per slide than any other in the catalog.
+
+---
+
+## Structural DNA — the thread
+
+**N slides, 3.0 seconds each, no exceptions. 8 is the floor, 15 the ceiling, 12 is the number to
+aim at.** Fewer than 8 and there is no story, only an exchange. More than 15 and the drop-off
+happens before your payoff.
+
+| Slot | Beat | Job |
+|---|---|---|
+| **1** | **The wrong foot** | Open mid-mistake. A message that should not have been sent, to a person it should not have reached |
+| **2** | **The turn** | The other one does not leave. This is the promise the rest of the thread pays |
+| **3** | **`>>>` skip card** | Buy weeks of story for the price of one slide |
+| **4 – ⌈N/2⌉** | **The escalation** | Each slide raises what is at stake between them by exactly one notch |
+| **middle** | **The shill beat** | The product enters as a PLOT FACT, said once, by a character, about themselves |
+| **⌈N/2⌉+1** | **The reveal** | One fact that recasts every slide before it. The reference uses "you go to Harvard?" |
+| **N-3** | **Second `>>>` skip card** | The jump into the last act |
+| **N-2 … N-1** | **The break** | Someone acts against their own register. The polite one swears. The joker goes quiet |
+| **N** | **The cliffhanger** | Mid-action, unresolved, no goodbye, no bow |
+
+**The two skip cards are the format's whole economy.** A `>>>` slide is a black frame with three
+grey chevrons on it, it costs nothing to make, and it buys you a time jump of any length. Without
+them you would spend six slides getting from "wrong number" to "3am crisis". With them you spend
+one. **Two skip cards in a 12-slide thread. Never three, never zero** — zero means the story
+happens in one sitting and cannot escalate; three means the reader has lost the thread of who these
+people are.
+
+### Slides DO build here — the inversion
+
+`sticker-slideshow-tips` bans slides that depend on each other. **This format is the exact
+opposite, and the two must never be confused.** A thread is linear, forced and cumulative: slide 9
+is meaningless without slide 5, and that is correct.
+
+What survives from the sibling format is the *frame-level* rule, not the sequence-level one:
+
+- **Every slide is a complete still**, exported as a PNG at start+1.5s. Nothing may be revealed by
+  motion, no bubble may fade in after the export point, no meaning may live in the transition.
+- **No slide may be a fragment of a sentence.** A bubble that starts on slide 6 and finishes on
+  slide 7 is a broken slide, even though the story continues across the cut. Break your slides at
+  **conversational** boundaries — after a reply lands, never mid-exchange.
+
+### Length and read budget
+
+`N × 3.0s`, exactly. `data-duration` on the root is `N * 3.0`, every slide layer is `3.0`.
+
+**4 to 8 bubbles per slide.** Below 4 the slide is empty air; above 8 the column overflows the safe
+zone and the last bubble is cropped by the platform's UI. The reference sits at 5–8.
+
+**The 3-second read is not the constraint you think it is.** In the MP4 the viewer cannot read
+eight bubbles in three seconds — and that is fine, because the MP4 is the *proof copy*. The
+carousel is the deliverable and its reader holds the slide. Do not thin your slides to fit the
+video; that is optimising for the wrong artifact.
+
+**Identical beat lengths are the FORMAT, not the defect.** The whole-video review pass in
+`references/reviewing-renders.md` flags "N identically-long beats" as a machine-made tell. It is
+right about every other format and wrong about this one. Do not vary the durations to look
+hand-made. Say so in the handoff so the next reviewer does not "fix" it.
+
+---
+
+## The two voices — the single biggest lever
+
+Everything else in this file is production. **This is the craft.** Two voices that are
+typographically distinct carry a mediocre story; two voices that type identically kill a great one.
+
+Assign these before you write a single bubble, and hold them for the entire thread:
+
+| Axis | Voice A (the reference's `me`, blue) | Voice B (the reference's `them`, grey) |
+|---|---|---|
+| **Capitals** | never, except for shouting a whole word (`HARVARD?`) | always — sentence case, proper nouns |
+| **Full stops** | none | every sentence |
+| **Commas** | none | correct |
+| **Contractions** | `dont`, `im`, `whats` | `don't`, `I'm`, `what's` |
+| **Abbreviation** | `ur`, `bc`, `rn`, `thx`, `probly` | written out in full |
+| **Laughing** | `lol`, `lmao`, `haha` inline | `haha.` as a sentence, or 😂 |
+| **Emoji** | rare, and ironic (`😇` after an insult) | frequent, sincere (`😊 :( 😅`) |
+| **Message length** | short, then a second short one — thinks in bursts | one complete paragraph — thinks then sends |
+| **Under pressure** | goes quiet, gets literal | breaks register entirely (swears, all-caps) |
+
+**The two rows that do the most work are the last two.** Voice A sends two bubbles where B sends
+one — that alone makes the column read as two people before you have read a word. And the *break*
+in the last act only exists because B was consistent for nine slides: "How the fuck are you
+supposed to change the battery in a smoke alarm" is funny **only** because that person has written
+`I'm so sorry. :(` since slide 1.
+
+### The devices, and when each one is allowed
+
+| Device | What it is | Rule |
+|---|---|---|
+| **The double-send** | two bubbles from the same speaker, back to back | The core rhythm. Only the LAST of a run carries a tail |
+| **The one-word bubble** | `i try` · `MARCUS.` · `THANK YOU` | The payoff shape. **At most two in a thread**, and one of them is the punchline |
+| **The jumbo emoji** | a reply that is only emoji, sent at ~4× bubble size with **no bubble** | The reference does this once, on slide 11. Once per thread, never twice |
+| **The skip card** | `>>>` centred, small, grey, on black | Exactly two per thread |
+| **The typing indicator** | three grey dots in an empty bubble | **Final slide only**, as the cliffhanger. Never mid-thread |
+| **Read receipt** | a small grey `Delivered` / `Read 3:41 AM` under the last bubble | At most once. Its only legitimate use is showing a message that was seen and not answered |
+
+Everything not on this list — avatars, timestamps on every bubble, reactions, a status bar, a
+carrier name, a battery icon, a keyboard, a name at the top of the screen — is **banned**. See
+Rule 3.
+
+---
+
+## Writing the thread
+
+### The grammar of a bubble
+
+- **≤22 words per bubble, ≤3 lines.** Longer and it is a monologue with a rounded rectangle on it.
+- **A bubble does one thing:** ask, answer, joke, escalate, or land. Two jobs in one bubble means
+  you needed two bubbles, which you are allowed to have.
+- **Nobody recaps.** "So anyway, like I said yesterday, when you told me…" is you talking to the
+  reader in a character's voice. The reader is reading over a shoulder; they get to be confused for
+  half a slide.
+- **No stage directions.** No `*laughs*`, no `[3 days later]` written into a bubble. That is what
+  the skip card is for.
+- **Typos belong to Voice A only**, at most two in the whole thread, and never on the payoff line.
+  A typo is a characterisation, not a texture.
+
+### The specificity ladder — the same lever, aimed at story
+
+Same beat, four rungs. Rung 1 is scrolled past. Rung 4 is screenshotted.
+
+| Rung | Line | Why |
+|---|---|---|
+| 1 | `sorry wrong number` | Happens to everyone. No scene |
+| 2 | `sorry, i think i typed it wrong` | A reason, but a generic one |
+| 3 | `sorry, i got the number off a napkin` | A real object enters |
+| 4 | **`ah damn lol she wrote it on my hand bc my phone was dead and the ink smeared`** | An object, a cause, and an image. This is the rung |
+
+**Rung 4 is a detail nobody would invent.** It is also the rung that makes a thread feel found
+rather than written, and it costs the same number of words as rung 2.
+
+### The four engines — pick ONE
+
+The brief says the thread may be funny, dramatic, gossipy or anything else that holds. It may not
+be **two of them at once**. A thread that is a comedy for six slides and a tragedy for four is a
+thread the reader stops trusting.
+
+| Engine | What holds the reader | The payoff shape | Where it fails |
+|---|---|---|---|
+| **Comedy** *(the reference)* | Escalating absurdity between two people who like each other | One word, or a total register break | The joke arrives on slide 2 and there is nothing left to escalate |
+| **Drama** | An unequal exchange — one person knows something the other does not | The moment the imbalance is named out loud | Melodrama. Nobody in a real thread announces their feelings in full |
+| **Gossip** | A third person, never present, discussed by two | The screenshot-within-the-screenshot, or the third person appearing | It becomes bullying. See Rule 8 |
+| **Wholesome-cringe** | Someone being sincere past the point of comfort | The other one drops the guard and matches it | Sentimentality with no jokes reads as an insurance advert |
+
+**Whichever engine you pick, the thread must be about the RELATIONSHIP, not the topic.** The
+reference is not about smoke alarms. It is about two people who now text each other at 3am, and the
+smoke alarm is the excuse.
+
+### Banned openings
+
+Each of these fails on slide 1, which is the thumbnail:
+
+- **`Hey` / `hey whats up` / `you up?`** — no situation, nothing wrong yet.
+- **Any slide 1 that starts at the start.** Open on the mistake, not on the introduction.
+- **A bubble that explains who the characters are.** Names arrive late — the reference gets to
+  slide 5 without them, and the real name is the punchline on slide 12.
+- **A question the reader cannot care about yet.** Slide 1 is a situation, not a hook line.
+- **Any brand, product, price or URL on slide 1.** That is not an opening, it is a banner.
+
+---
+
+## The shill beat
+
+The slide that pays for the work. It obeys every rule above **plus** six of its own.
+
+```
+them   How do you have time to post that much? You work 24s.
+me     i dont lol
+me     i make one and the ai turns it into like 30 versions overnight
+me     vidfarm. i just approve the good ones in the morning
+them   That feels like cheating.
+me     it is
+```
+
+1. **The product is a PLOT FACT, never a recommendation.** It exists because a character *does* it,
+   in answer to a question the other character asked about their life. Nobody says "you should try",
+   nobody links anything, nobody thanks anyone for the tip.
+2. **It is named once, lowercase, mid-bubble.** `vidfarm`, not `Vidfarm.cc ✨`, not a URL, not on
+   its own line, not in the last bubble of the slide.
+3. **It sits in the MIDDLE.** At least three story slides before it and three after it. Earlier and
+   the reader concludes the thread was written to hold the ad, which it was, and they are right to
+   leave. Later and the story *resolves into* a pitch.
+4. **It is the answer to a question about the character, not about the product.** "How do you have
+   time" is a question about a person. "What do you use for editing" is an ad reading itself aloud.
+5. **The other character does not endorse it.** In the example above she calls it cheating. A
+   sceptical, funny or indifferent reaction is the single strongest signal that the thread is real —
+   an enthusiastic one is a testimonial, and this format cannot survive a testimonial.
+6. **The story does not need it.** Delete the shill slide. Does the thread still work? It must.
+   That is the test, and it is the reason the product beat cannot also be the reveal, the break or
+   the payoff.
+
+**Exactly one shill in a thread.** No second-mention exception. A callback to the product in the
+last act converts the whole thread into an ad retroactively, and the reader feels the switch even
+if they cannot name it.
+
+**When the product will not fit.** If there is no honest way for a private person to mention your
+offer inside a personal conversation — most B2B tooling, anything with a procurement cycle, anything
+a character would have no reason to have an opinion about — **this is the wrong format.** Use
+`sticker-slideshow-tips` or `ugc-reaction-greenscreen`. Forcing it produces the one failure mode
+this format cannot recover from: a fake conversation that is visibly a script.
+
+---
+
+## Visual DNA
+
+### The canvas
+
+**Pure black, 1080×1920, edge to edge.** `#000000`, not `#0B0B0F`, not a gradient.
+
+The reason is structural, not aesthetic: the reference's slides are variable-height crops of a real
+dark-mode screenshot, centred on a black field. **Because the crop and the canvas are the same
+black, the seam is invisible** — the reader perceives one continuous phone screen, not a picture of
+one pasted onto a slide. Any canvas that is not exactly the bubble field's black puts a visible
+rectangle around every slide and the illusion is gone.
+
+| Token | Value | Notes |
+|---|---|---|
+| Canvas | `#000000` | Also the tail cut-out colour. They must match exactly |
+| Voice A bubble | `#0A84FF` | iOS dark-mode blue. Right-aligned |
+| Voice B bubble | `#2C2C2E` | iOS dark-mode grey. Left-aligned |
+| Bubble text | `#FFFFFF` | Both bubbles. Never grey-on-grey |
+| Skip card / meta | `#8E8E93` | `>>>`, `Delivered`, typing dots |
+
+**Do not restyle the bubbles to the brand.** A purple bubble is a brand asset wearing a message
+app, and it announces the ad two slides before the shill does. The colours above are the ones
+readers do not see, which is the entire point.
+
+### The column
+
+```
+column       left 5.5%, width 89%, vertically CENTRED in the frame
+bubble       max-width 78% of the column
+padding      20px 30px
+radius       36px
+gap          14px between speakers · 8px within one speaker's run
+font-size    46px · line-height 1.30
+tail         on the LAST bubble of each run only
+```
+
+**Vertically centred, never top-aligned.** A 4-bubble slide and an 8-bubble slide are both centred,
+so the column grows in both directions — exactly what a variable-height screenshot crop does. Top-
+aligning makes short slides look broken and is the fastest way to reveal that the slides were
+generated.
+
+**The safe zone is a hard cap, not a guideline.** Nothing in the top 14% or the bottom 20%: that is
+where the platform puts the caption, the handle and the swipe UI, and a cropped bubble is the
+defect readers actually notice. `build-thread.py` estimates the column height and warns before you
+render; `thread-qa.py` measures it on the exported PNG and fails.
+
+### The tail
+
+The tail is what makes a rounded rectangle read as a message. It is two pseudo-elements: a
+same-colour blob at the bottom outer corner, and a **canvas-black** mask further out that carves the
+curve. Both are in Appendix A.
+
+**Only the last bubble of a run gets one.** In the reference, slide 9's `lmao nah, ur boy is just a
+probie rn` has no tail and `hoping to make chief someday` does — that is what tells the eye the two
+bubbles are one turn. Tail every bubble and the column reads as eight separate people.
+
+### What is not on the screen
+
+No status bar. No battery. No carrier. No time at the top. No contact name, no avatar, no back
+chevron, no text field, no keyboard, no send button, no timestamps between bubbles, no `iMessage`
+label, no reaction bubbles.
+
+**Every one of those is a real-app detail that will be WRONG**, and a reader who spots one wrong
+detail re-reads the whole thread as fake. The crop that contains nothing but bubbles cannot be
+wrong about anything.
+
+---
+
+## Typography DNA
+
+**One self-hosted family, one weight, one size, for every bubble.** This format has no headline
+tier and no emphasis system.
+
+- **The family:** a UI grotesque with real quotes and a proper `'` — SF Pro, Inter, Helvetica Now,
+  or TikTok Sans. Self-hosted woff2, **no fallback chain**: a font that fails to fetch substitutes
+  silently and the whole illusion collapses into Times New Roman.
+- **One weight (400/regular) and one size (46px) for all bubble text.** No bold, no italic, no
+  colour change, no size change. Emphasis is spelled: `HARVARD?`, `MARCUS.`, `THANK YOU`. That is
+  how emphasis works in a real thread and it is the only tool you get.
+- **No stroke, no text shadow, no letter-spacing tweak.** White on `#0A84FF` and white on `#2C2C2E`
+  are both above 4.5:1 already.
+- **Emoji render from the system font.** Do not recolour them, do not substitute SVGs, do not size
+  them per-emoji — except the one jumbo-emoji reply, which is sized as a whole layer.
+- **Straight quotes are a tell.** `don't` with a typewriter apostrophe reads as a text file, not a
+  phone. Use `’` in Voice B. Voice A may omit the apostrophe entirely, which is its own
+  characterisation.
+
+---
+
+## Motion DNA
+
+**The default is no motion at all.** The reference has none. Still slides, hard cut every 3.0s.
+
+Allowed, and only in the MP4:
+
+- **A bubble-stack entrance**, if and only if it **completes within 0.5s** of the slide's start. The
+  still export is taken at start **+1.5s** for exactly this reason.
+
+Banned:
+
+- **Bubbles popping in one at a time.** It is the most tempting animation in this format and it is
+  the one that breaks it: the PNG export at +1.5s would catch a half-populated column, and the
+  carousel — the deliverable — would ship with bubbles missing.
+- **Any transition between slides.** Hard butt cuts only. A carousel swipes; it does not dissolve.
+- **An entrance transition on slide 1.** `vidfarm qa` errors on this (`thumbnail-fade-in`) and it is
+  right: frame 0 is the thumbnail and the first slide of the carousel.
+- **A scrolling column**, a typing animation, a message "sending" animation, or a moving typing
+  indicator. All three reveal information the still does not carry.
+
+---
+
+## Audio DNA
+
+**The carousel is silent.** There is nothing to author.
+
+**The MP4 may carry a music bed and nothing else.** No voiceover — a voice reading both parts turns
+the thread into a radio play and the slides into subtitles, which inverts the format.
+
+- Free and keyless: `vidfarm media search "<mood>" --type bgm` (Openverse, CC/CC0).
+- **Never load-bearing.** No beat-matched cuts, no sting on the payoff slide.
+- A notification SFX on each cut is banned. It sounds like the idea it is, and it makes the MP4
+  the master.
+
+The poster adds a trending sound in the platform's own editor. Say so in the handoff.
+
+---
+
+## The two deliverables
+
+**One composition. Two exports. The slides are the master.**
+
+| Deliverable | What it is | How it is made | Where it goes |
+|---|---|---|---|
+| 📸 **The thread** *(the real one)* | N PNGs, 1080×1920, in order | `vidfarm stills` at each slide's start+1.5s | Durable My Files → N ordered URLs → posted as a photo carousel |
+| 🎬 **The video** *(the proof)* | One MP4, N×3.0s, hard cuts | `vidfarm render` on the same composition | The marketplace proof; also postable to a video surface |
+
+### ⚠️ Name the file BOTH ways before you export anything
+
+The two halves of the toolchain disagree about the filename, and each fails with an error that
+sounds like a missing project rather than a missing alias:
+
+| Tool | Wants | Error when it's absent |
+|---|---|---|
+| `vidfarm stills` / `vidfarm qa` / `vidfarm render` | `composition.html` | *"No composition.html inside … Run `vidfarm pull` first"* |
+| `vidfarm hf …` (the hyperframes passthrough) | `index.html` | *"No composition found … Run npx hyperframes init"* |
+
+```bash
+ln -sf composition.html ./work/index.html
+```
+
+### Exporting the slides
+
+```bash
+# 12 slides at 3.0s -> settled-state stills at 1.5, 4.5, 7.5, …, 34.5
+vidfarm stills ./work --at 1.5,4.5,7.5,10.5,13.5,16.5,19.5,22.5,25.5,28.5,31.5,34.5 \
+  --out ./slides --sheet
+
+# If `stills` dies with "Cannot find package '@hyperframes/producer'", the devcli's
+# bundled engine is incomplete on this machine. Do NOT go hunting — the passthrough
+# is the same renderer and it works:
+vidfarm hf snapshot ./work --at 1.5,4.5,7.5,10.5,13.5,16.5,19.5,22.5,25.5,28.5,31.5,34.5 \
+  --no-end -o ./slides --describe false
+```
+
+`build-thread.py` prints the exact `--at` list. `--sheet` is not optional: the contact sheet is the
+only view in which this format's real defects are visible — a voice that drifted, a column that
+wobbles between slides, a run of four slides where one speaker vanishes.
+
+### Uploading and ordering
+
+The slides must live in **durable** My Files, not the 30-day temp store. A carousel that 404s in a
+month is worse than one that never shipped.
+
+```bash
+for f in ./slides/slide-*.png; do
+  vidfarm put-file "$f" --folder threads/wrong-number \
+    --notes "$(basename "$f") — wrong-number thread"
+done
+vidfarm files --search "wrong-number thread"     # confirm all N, in order
+```
+
+Write the ordered URLs to `slides.json` beside the composition. **Order is data**, and in this
+format it is more load-bearing than in any other: a shuffled tip deck is a worse deck, a shuffled
+thread is nonsense.
+
+### Submitting to the marketplace
+
+```bash
+vidfarm render ./work --wait                       # -> final.mp4
+
+vidfarm shared put <upload-link> ./final.mp4   --subfolder <your-handle>/wrong-number
+vidfarm shared put <upload-link> ./slides.json --subfolder <your-handle>/wrong-number
+for f in ./slides/slide-*.png; do
+  vidfarm shared put <upload-link> "$f" --subfolder <your-handle>/wrong-number/slides
+done
+
+vidfarm gigs submit <gig-id> --task <task-id> --proof https://…/final.mp4
+```
+
+**Say in the submission that the deliverable is the carousel and the MP4 is the preview**, and that
+the slide order is the story. A client who posts these out of order posts gibberish.
+
+---
+
+## The rules
+
+Every rule has its reason attached. A rule without its reason gets argued away by the next agent
+that reads this file.
+
+### Rule 1 — two voices, typographically separable with the colour removed
+
+The colours are a convenience for the reader; the typing is the characterisation. Test 2 of the
+three-way lock is this rule, and it is the difference between a thread that reads as found and one
+that reads as generated. **Enforced:** by you, cold, on the contact sheet with the colour off.
+
+### Rule 2 — one shill, in the middle, as a plot fact
+
+Any other placement changes what the thread *is*. Early makes it an ad with a story on it, late
+makes the story resolve into a pitch, twice makes it a brochure. **Enforced:** `thread-qa.py`
+counts the brand token in the manifest and fails on anything but exactly one.
+
+### Rule 3 — no phone chrome, ever
+
+No status bar, avatar, contact header, timestamp row, keyboard or reaction. Every one is a detail
+that can be *wrong*, and one wrong detail makes the reader re-read the thread as fake. The crop
+that contains only bubbles cannot be wrong. It is also, not coincidentally, the cheapest thing to
+build.
+
+### Rule 4 — the canvas black and the tail-mask black are the same black
+
+`#000000` on both. A one-value mismatch draws a visible notch at every tail and a visible rectangle
+around every slide. It is invisible on a monitor at 50% zoom and obvious on a phone.
+
+### Rule 5 — every slide is a complete still at start+1.5s
+
+The PNG **is** the slide. Nothing may arrive after the export point and nothing may be carried by a
+transition. The video is a rendering of the carousel, never the other way round.
+
+### Rule 6 — no slide breaks mid-exchange
+
+Slides may — must — build on each other, but they break at conversational boundaries: after a reply
+lands, never mid-question. A slide that ends on half a joke is a slide nobody screenshots.
+
+### Rule 7 — the thread never resolves
+
+No goodbye, no "anyway", no bow, no summary. The last slide is mid-action. **The bait is the
+unresolved state**, and it is why this format gets comments instead of saves.
+
+### Rule 8 — no real person, no real brand, no identifiable target
+
+No real names, no handles, no employers, no screenshots of anyone's actual messages, and no third
+party discussed in a way that would harm them if they were real. The gossip engine is about
+*characters*. This is a legal exposure and a credibility loss in the same line, and on a gossip
+thread it is the one that will actually bite.
+
+### Rule 9 — the bait is in the post caption
+
+The thread ends unresolved. The comment prompt, the "part 2?" and the follow prompt all live in the
+caption where the platform expects them. A bubble that says `comment below` is a character breaking
+frame, and the frame is the only thing the format has.
+
+### Rule 10 — production floor
+
+1080×1920, 30fps, `N × 3.0s` exactly, hard cuts, `#000000` canvas, one text layer per slide, first
+bubble legible at frame 0, `data-duration` on the root equal to the sum, nothing in the top 14% or
+bottom 20%.
+
+---
+
+## Cost-saving mode — the whole thread at $0
+
+**This is the cheapest format in the catalog, and it is cheap in `minimize` without a single
+compromise.** It has no footage, no cutouts, no stickers, no image generation and no licensed
+asset. There is nothing in it that can cost money.
+
+| Ingredient | `minimize` ($0) | `hybrid` |
+|---|---|---|
+| Canvas + bubbles | Hand-authored HTML. Free, forever | same |
+| Dialogue | Written. That is the whole job | same |
+| Fonts | Self-hosted woff2, already on disk | same |
+| Slides export | `vidfarm stills` — local, in-process | same |
+| Video render | `vidfarm render` local | same |
+| Music bed | `media search --type bgm` (Openverse, keyless) | same |
+| **Total** | **$0** | **$0 — there is nothing to upgrade** |
+
+**There is no rich-ai rung here and you should not invent one.** Generating a face for either
+character, or an AI "screen recording" of the thread, makes the format worse and costs money to do
+it: the reference works *because* there is nothing on screen but type, and the reader supplies both
+people.
+
+The only money this format can spend is a cloud render you did not need. Render locally.
+
+---
+
+## Bulk generation — this format is built for it
+
+A thread is a TSV plus a builder. Once the first one exists, the tenth costs the time it takes to
+write dialogue.
+
+- **Vary the STORY, hold the chassis.** Same canvas, same voices-table, same 12 slots, same shill
+  mechanism, new situation. Wrong number → a group chat that added the wrong person → a landlord →
+  a delivery driver → an ex → a recruiter.
+- **The shill beat may repeat near-verbatim across a campaign.** It is the product's mechanism and
+  it does not improve by being reworded. Holding it constant also makes it the clean variable when
+  you want to test it.
+- **Never reuse a payoff line across threads on one account.** A follower sees both, and the second
+  one retroactively exposes the first as written.
+- **Rotate which voice is the protagonist.** Six threads where the blue voice is always the funny
+  one reads as a persona; three-and-three reads as a channel.
+- **`vidfarm dedupe` before a RE-post**, not before a first post. The MP4 is what a platform
+  fingerprints; the slides are not.
+- **Batch the QA.** `vidfarm qa ./threads/* --json` grades N compositions in one pass;
+  `thread-qa.py` runs on the exported PNGs, which is where the real defects live.
+
+Sizing a round, capacity and the ledger belong to `vidfarm experiment`, not to this file.
+
+---
+
+## Quality gates — what is ENFORCED, and by what
+
+| Gate | Tool | What it can actually see |
+|---|---|---|
+| **1. Composition** | `vidfarm qa ./work --harness ./engaging-chat-convo.md` | The DOM: font regime, slop, safe zone, frame 0, the `checks:` block above |
+| **2. The stills** | `thread-qa.py ./slides --manifest thread.tsv` *(Appendix C)* | The exported PNGs: blank slides, canvas drift, column overflow, one-sided slides, the one-shill count |
+| **3. The sequence** | **You**, on `slides/contact-sheet.png` | Whether it reads as one conversation between two people. Nothing else can see this |
+| **4. The story** | **You**, cold | Whether anyone would screenshot it. No tool has an opinion here |
+
+Gate 1 is free, instant and does not look at pixels. Gate 3 is the one that catches what actually
+ships broken.
+
+### Three findings that are EXPECTED on this format — do not "fix" them
+
+All three are correct rules firing on a format they were not written for. Record your answer once
+and move on; chasing any of them damages the thread.
+
+- **`wall-of-text` on every slide** (built-in, gate 1). It warns at 14+ words in one static text
+  layer because a scrolling viewer reads none of it. **That reasoning does not hold for a
+  carousel** — the reader sets their own dwell time and the text is the thing they came for. A
+  chat slide is 40–90 words by design. The fix it suggests (page it into 3–5-word kinetic cues)
+  would destroy the format.
+- **`max_words_per_cue` near the ceiling on every slide.** One text layer per slide is deliberate —
+  see Appendix A. The per-bubble limit (≤22 words) is the one that matters, and gate 2 enforces it
+  from the manifest. Do not add a `scenes:` line to make the layer count look normal: `scenes`
+  counts visual clips, this format has exactly one for the whole video, and the check would then
+  fail on every legal build.
+- **"N identically-long beats"** in the whole-video review. 3.0s per slide is the format. A thread
+  that lingers on one slide is a thread that is selling.
+
+### The failure this format actually ships — the drifting voice
+
+Worth stating because it survives a clean render, a clean export, and a per-slide eyeball: **by
+slide 9 both characters are typing the same way.** It happens because you have been writing for
+twenty minutes and the register is expensive to hold, and it is invisible one slide at a time —
+each individual bubble sounds fine.
+
+Catch it two ways, both cheap:
+
+1. **Read only the grey bubbles, top to bottom, across the whole contact sheet.** They must sound
+   like one person having one continuous mood. Then do the blue.
+2. **`thread-qa.py --voices` counts the tells per speaker per slide** (capitals, terminal full
+   stops, abbreviations) and reports the slide where the two distributions converge.
+
+---
+
+## Pre-flight checklist
+
+Run this before you build, and answer it honestly after. An unchecked box is a rewrite, not a fix
+in the edit.
+
+**The thread**
+
+- [ ] N is between 8 and 15, and every slide is exactly 3.0s.
+- [ ] Slide 1 opens on a mistake, mid-situation, with no introduction and no greeting.
+- [ ] Exactly two `>>>` skip cards, and each buys a time jump the story needed.
+- [ ] Names arrive after slide 3, and at least one of them is a beat rather than an admin line.
+- [ ] There is exactly ONE reveal, and it recasts the slides before it.
+- [ ] Someone breaks their own register in the last act.
+- [ ] The last slide is mid-action. There is no goodbye and no summary.
+- [ ] No slide breaks mid-exchange.
+
+**The voices**
+
+- [ ] The voices table is written in the build log BEFORE the dialogue.
+- [ ] With the colour removed, every bubble is attributable to a speaker.
+- [ ] Voice A double-sends; Voice B sends one complete message. Consistently.
+- [ ] Punctuation, capitals, contractions and emoji follow the table on slide 12 as on slide 1.
+- [ ] At most two one-word bubbles, at most one jumbo emoji, at most two typos.
+- [ ] No bubble exceeds 22 words or 3 lines.
+- [ ] No bubble exists to inform the reader.
+- [ ] Every rung-4 detail is a detail nobody would invent.
+
+**The shill**
+
+- [ ] Exactly one, in the middle, with three story slides on each side.
+- [ ] It is a plot fact, in answer to a question about the character's life.
+- [ ] The brand is lowercase, mid-bubble, named once, with no URL.
+- [ ] The other character does not endorse it.
+- [ ] Deleting the shill slide leaves a thread that still works.
+- [ ] The shill slide is visually identical to every other slide.
+
+**The screen**
+
+- [ ] Canvas is `#000000` and the tail masks are the same `#000000`.
+- [ ] Bubble colours are the platform defaults, not the brand's.
+- [ ] No status bar, avatar, header, timestamp, keyboard, reaction or app label anywhere.
+- [ ] The column is vertically centred on every slide, never top-aligned.
+- [ ] Only the last bubble of each run has a tail.
+- [ ] Nothing in the top 14% or bottom 20% on any slide.
+- [ ] One self-hosted family, one weight, one size, no fallback chain, no stroke, no shadow.
+- [ ] 4–8 bubbles per slide.
+
+**The exports**
+
+- [ ] Frame 0 is slide 1, fully settled, first bubble legible — thumbnail AND cover.
+- [ ] No entrance transition on slide 1; no transition between any slides.
+- [ ] N PNGs exported at start+1.5s, each complete on its own.
+- [ ] Slides uploaded to DURABLE My Files, ordered, recorded in `slides.json`.
+- [ ] The MP4 is `N × 3.0s` and the cuts land on the second.
+- [ ] The submission says the carousel is the deliverable, the MP4 is the preview, and the order is
+      the story.
+
+---
+
+## The whole-thread review — do this last, on the contact sheet
+
+Gates 1 and 2 grade slides. This grades the conversation, and it is the only pass that catches what
+actually ships broken. **Open `slides/contact-sheet.png` and read it as one image.**
+
+- [ ] **Read only the grey bubbles. Then only the blue.** Two people, or one person twice?
+- [ ] **Does either voice disappear for two slides in a row?** That is a monologue with a colour on
+      it. Give the silent one a one-word bubble.
+- [ ] **Where does the story actually start?** If slides 1–2 are set-up, delete them and start on
+      slide 3. This is the most common cut and it always improves the thread.
+- [ ] **Is there a slide you would screenshot?** There should be at least two. If there are none,
+      the payoff is not written yet.
+- [ ] **Can you tell which slide is the ad?** If your eye finds it before you read it, it is styled
+      differently or the brand is on its own line.
+- [ ] **Do the columns sit at roughly the same centre?** They will vary in height; they must not
+      wander left or right.
+- [ ] **Does the last slide leave you wanting the next one?** Not "did it end well". Wanting.
+
+Then watch the MP4 end to end at 1× with sound off, which is how the proof will be judged.
+
+---
+
+## Diagnosing a flop
+
+Diagnose by beat, never by declaring the thread bad.
+
+| Symptom | The weak beat | The fix |
+|---|---|---|
+| Almost no impressions | **Slide 1 / the thumbnail** | It opens on a greeting or a set-up. Start on the mistake — usually your current slide 3 |
+| Views, drop-off by slide 3 | **The turn** | The second character had no reason to keep replying. Give them one, on slide 2 |
+| Read to the middle, then out | **The escalation** | Two slides in a row raise nothing. Cut them; the thread is 2 slides shorter and better |
+| Read to the end, no comments | **The ending** | It resolved. Cut the last slide and ship the one before it |
+| Comments say "fake" / "AI wrote this" | **The voices** | Rule 1. Both characters type the same way from some slide onward — find it on the contact sheet |
+| Good numbers, nobody mentions the product | **Nothing is broken** | This format seeds a name inside a story. Judge it on comments and branded search, not clicks |
+| Comments are about the product, not the story | **The shill** | It is too early, too enthusiastic, or on its own line. Bury it deeper and make the other character sceptical |
+
+---
+
+## Appendix A — `build-thread.py` (a thread from a TSV script)
+
+Builds the whole composition from a script file. The TSV is the artifact you iterate on; the HTML
+is generated and should never be hand-edited after the first run.
+
+```
+# thread.tsv — one line per BUBBLE, TAB separated. '#' comments ignored.
+#   col 1: speaker — `me` (blue, right) · `them` (grey, left)
+#                    `skip` (a >>> card) · `typing` (three dots) · `emoji` (jumbo, no bubble)
+#                    `meta` (a small grey line, e.g. Delivered)
+#   col 2: the text. `|` is a hand line break. Empty for `skip` / `typing`.
+# A line containing only --- ends the slide.
+me	hey its marc
+them	Hello, I’m sorry. I don’t actually know a Marc. :(
+me	ur not Anna?
+them	No, I’m so sorry. 😞 I think you got a wrong number.
+me	ah damn lol she wrote it on my hand bc my phone was dead and the ink smeared
+---
+skip
+---
+```
+
+**Why one layer per slide.** A chat column is *flowed* — bubble 5's position depends on how many
+lines bubbles 1–4 wrapped to — and flow cannot be expressed as absolutely-positioned sibling
+layers. So each slide is exactly one text layer holding the whole stack, and the browser lays it
+out. This is why `max_simultaneous_text: 1` and `max_words_per_cue: 90` are set the way they are.
+Do **not** wrap slides in an outer `div.clip`: nesting renders correctly and is invisible to the
+toolchain — `vidfarm qa` reports `scenes: 0` and `first_frame_visual` then fails on a composition
+whose frame 0 is fine.
+
+```python
+#!/usr/bin/env python3
+"""
+Build an engaging-chat-convo composition from a TSV script.
+
+Four things this exists to get right:
+
+  * ONE FLAT LAYER PER SLIDE. A direct child of #root carrying its own
+    data-start / data-duration / data-layer-kind, holding the whole flowed
+    bubble column. Never nest a slide inside another .clip (see above).
+  * THE CANVAS IS A LAYER, NOT A STYLESHEET RULE. The still exporter captures
+    with an alpha channel, so a background set only on <body>/#root comes back
+    TRANSPARENT — white in every viewer, and every tail mask becomes a visible
+    black notch. One full-duration shape layer at z-index 0 is the fix.
+  * THE COLUMN IS CENTRED, NOT PINNED. `.clip{inset:0}` already gives the layer
+    the full frame; the flex centring happens inside it. That is the one case in
+    the catalog where inset:0 is correct rather than something to reset.
+  * TAILS ONLY ON RUN ENDS. The tail is what groups a double-send into one turn.
+    The mask pseudo-element must be the CANVAS colour, exactly (Rule 4).
+  * HEIGHT IS ESTIMATED BEFORE RENDER. A column that overflows the safe zone
+    renders fine, exports fine, passes gate 1, and ships cropped on a phone.
+
+usage: build-thread.py <thread.tsv> <out.html> [--title=…] [--font-px=46]
+                       [--family=Chat] [--brand=<token>]
+"""
+import html, sys
+
+SLIDE_SEC = 3.0
+W, H = 1080, 1920
+BLACK = "#000000"        # canvas AND tail mask. One value, used in both places.
+BLUE, GREY, INK, META = "#0A84FF", "#2C2C2E", "#FFFFFF", "#8E8E93"
+SAFE_TOP, SAFE_BOT = 0.14, 0.20
+
+args = [a for a in sys.argv[1:] if not a.startswith("--")]
+opts = dict(a.split("=", 1) for a in sys.argv[1:] if a.startswith("--") and "=" in a)
+script, out = args[0], args[1]
+title = opts.get("--title", "chat thread")
+fpx = int(opts.get("--font-px", 46))
+family = opts.get("--family", "Chat")
+brand = opts.get("--brand")
+
+# ---------------------------------------------------------------- parse
+slides, cur = [], []
+for raw in open(script, encoding="utf-8"):
+    line = raw.rstrip("\n")
+    if not line.strip() or line.lstrip().startswith("#"):
+        continue
+    if line.strip() == "---":
+        if cur:
+            slides.append(cur)
+        cur = []
+        continue
+    parts = line.split("\t")
+    who = parts[0].strip()
+    text = parts[1].strip() if len(parts) > 1 else ""
+    if who not in ("me", "them", "skip", "typing", "emoji", "meta"):
+        sys.exit(f"unknown speaker {who!r} — me | them | skip | typing | emoji | meta")
+    cur.append((who, text))
+if cur:
+    slides.append(cur)
+
+if not slides:
+    sys.exit("no slides found — did you forget the --- separators?")
+if not 8 <= len(slides) <= 15:
+    print(f"⚠ {len(slides)} slides — the harness range is 8-15", file=sys.stderr)
+
+skips = sum(1 for s in slides if s and s[0][0] == "skip")
+if skips != 2:
+    print(f"⚠ {skips} skip cards — the format wants exactly 2", file=sys.stderr)
+
+if brand:
+    hits = [i + 1 for i, s in enumerate(slides)
+            if any(brand.lower() in t.lower() for _, t in s)]
+    if len(hits) != 1:
+        print(f"⚠ brand {brand!r} appears on slides {hits} — Rule 2 is exactly one",
+              file=sys.stderr)
+    elif not 3 < hits[0] <= len(slides) - 3:
+        print(f"⚠ brand on slide {hits[0]} of {len(slides)} — needs 3 story slides"
+              f" on each side (Rule 2)", file=sys.stderr)
+
+# ------------------------------------------------- geometry + height estimate
+# ~28 characters per line at 46px inside a 78%-of-89% column. Deliberately
+# pessimistic: a warning you can ignore beats a crop you cannot see.
+CPL = 28
+LINE_H = round(fpx * 1.30)
+PAD_V = 40
+
+
+def est_height(slide):
+    h, prev = 0, None
+    for who, text in slide:
+        if who == "skip":
+            return int(fpx * 1.0)
+        if who == "typing":
+            h += LINE_H + PAD_V
+        elif who == "emoji":
+            h += int(fpx * 3.2)
+        elif who == "meta":
+            h += int(fpx * 0.9)
+        else:
+            lines = sum(max(1, -(-len(seg) // CPL)) for seg in text.split("|"))
+            h += lines * LINE_H + PAD_V
+        h += 8 if who == prev else 14
+        prev = who
+    return h
+
+
+limit = H * (1 - SAFE_TOP - SAFE_BOT)
+for i, s in enumerate(slides, 1):
+    e = est_height(s)
+    if e > limit:
+        print(f"⚠ slide {i}: column ≈{e}px vs {int(limit)}px of safe height — "
+              f"move {1 + (e - int(limit)) // (LINE_H + PAD_V)} bubble(s) to the next slide",
+              file=sys.stderr)
+    n = sum(1 for w, _ in s if w in ("me", "them"))
+    if s[0][0] not in ("skip",) and not 4 <= n <= 8:
+        print(f"⚠ slide {i}: {n} bubbles — the format wants 4-8", file=sys.stderr)
+    for who, text in s:
+        if who in ("me", "them") and len(text.replace("|", " ").split()) > 22:
+            print(f"⚠ slide {i}: a {who} bubble runs past 22 words", file=sys.stderr)
+
+# ---------------------------------------------------------------- markup
+TAIL = 44          # tail blob size
+TAIL_R = 36        # its rounded corner
+MASK = 58          # the black mask that carves the curve
+
+CSS = f"""
+ /* Self-hosted, NO fallback chain. A font that fails to fetch substitutes
+    silently, and a chat screenshot in the wrong typeface is not a chat
+    screenshot. One family, one weight, one size — that is the whole regime. */
+ @font-face{{font-family:'{family}';font-weight:400;font-display:block;
+   src:url('media/fonts/chat-400.woff2') format('woff2')}}
+ body{{margin:0;background:{BLACK}}}
+ #root{{position:relative;width:{W}px;height:{H}px;overflow:hidden;background:{BLACK}}}
+ /* inset:0 is CORRECT here — the layer is the frame and the column centres
+    inside it. This is the one format where the reset does not apply. */
+ .clip{{position:absolute;inset:0}}
+ .bg{{background:{BLACK};z-index:0}}
+ .col{{display:flex;flex-direction:column;justify-content:center;align-items:stretch;
+   height:100%;padding:0 5.5%;box-sizing:border-box;
+   font-family:'{family}';font-weight:400;font-size:{fpx}px;line-height:1.30;
+   color:{INK};-webkit-font-smoothing:antialiased}}
+ .b{{position:relative;max-width:78%;padding:20px 30px;border-radius:36px;
+   margin-top:14px;word-wrap:break-word}}
+ .b.run{{margin-top:8px}}
+ .me{{align-self:flex-end;background:{BLUE}}}
+ .them{{align-self:flex-start;background:{GREY}}}
+
+ /* The tail: a same-colour blob at the outer bottom corner, plus a CANVAS-BLACK
+    mask further out that carves the curve. Both blacks must be identical or a
+    notch appears at every tail (Rule 4). */
+ .tail::before,.tail::after{{content:"";position:absolute;bottom:0;
+   width:{TAIL}px;height:{TAIL}px}}
+ .me.tail::before{{right:-14px;background:{BLUE};border-bottom-left-radius:{TAIL_R}px}}
+ .me.tail::after{{right:-{MASK}px;width:{MASK}px;background:{BLACK};
+   border-bottom-left-radius:22px}}
+ .them.tail::before{{left:-14px;background:{GREY};border-bottom-right-radius:{TAIL_R}px}}
+ .them.tail::after{{left:-{MASK}px;width:{MASK}px;background:{BLACK};
+   border-bottom-right-radius:22px}}
+
+ /* Tight, not tracked out: the reference reads ">>>", and 0.3em+ turns it into
+    "> > >", which reads as a design element rather than a time jump. */
+ .skip{{align-self:center;color:{META};font-size:{fpx}px;letter-spacing:0.06em}}
+ .meta{{align-self:flex-end;color:{META};font-size:{round(fpx*0.62)}px;margin-top:10px}}
+ .jumbo{{align-self:flex-end;font-size:{fpx*3}px;line-height:1.1;margin-top:14px}}
+ .dots{{align-self:flex-start;background:{GREY};border-radius:36px;
+   padding:26px 34px;margin-top:14px;color:{META};letter-spacing:0.22em}}
+"""
+
+
+def bubbles(slide):
+    outs, prev = [], None
+    for i, (who, text) in enumerate(slide):
+        nxt = slide[i + 1][0] if i + 1 < len(slide) else None
+        body = html.escape(text).replace("|", "<br>")
+        if who == "skip":
+            outs.append(f'<div class="skip">&gt;&gt;&gt;</div>')
+        elif who == "typing":
+            outs.append('<div class="dots">•&nbsp;•&nbsp;•</div>')
+        elif who == "emoji":
+            outs.append(f'<div class="jumbo">{body}</div>')
+        elif who == "meta":
+            outs.append(f'<div class="meta">{body}</div>')
+        else:
+            cls = [who, "b"]
+            if prev == who:
+                cls.append("run")
+            if nxt != who:                       # tail on the LAST of a run only
+                cls.append("tail")
+            outs.append(f'<div class="{" ".join(cls)}">{body}</div>')
+        prev = who
+    return "".join(outs)
+
+
+total = round(len(slides) * SLIDE_SEC, 3)
+
+# The canvas is a LAYER, spanning the whole thread, under everything. See the
+# module docstring — without it the exported PNGs come back transparent.
+layers = [f'  <div id="bg" class="clip bg" data-hf-id="bg" data-layer-mode="publish" '
+          f'data-layer-kind="shape" data-start="0" data-duration="{total}" '
+          f'data-end="{total}" data-label="canvas"></div>']
+for i, slide in enumerate(slides):
+    t = round(i * SLIDE_SEC, 3)
+    n = i + 1
+    layers.append(
+        f'  <div id="s{n:02d}" class="clip" data-hf-id="s{n:02d}" '
+        f'data-layer-mode="publish" data-layer-kind="text" data-start="{t}" '
+        f'data-duration="{SLIDE_SEC}" data-end="{round(t + SLIDE_SEC, 3)}" '
+        f'data-label="slide {n}" style="z-index:1">'
+        f'<div class="col">{bubbles(slide)}</div></div>')
+
+open(out, "w", encoding="utf-8").write(f"""<!doctype html>
+<html lang="en"><head><meta charset="UTF-8">
+<meta name="viewport" content="width={W}, height={H}">
+<title>{html.escape(title)}</title>
+<style>{CSS}</style></head><body>
+<div id="root" data-composition-id="chat_thread" data-start="0"
+     data-width="{W}" data-height="{H}" data-duration="{total}">
+{chr(10).join(layers)}
+</div></body></html>
+""")
+print(f"{len(slides)} slides · {total}s · {skips} skip cards · {out}")
+print("stills at: " + ",".join(str(round(i * SLIDE_SEC + 1.5, 1))
+                               for i in range(len(slides))))
+```
+
+## Appendix B — `export-thread.sh` (both deliverables from one composition)
+
+```bash
+#!/usr/bin/env bash
+# Export the carousel (the deliverable) and the MP4 (the preview) from one composition.
+# usage: export-thread.sh <work-dir> <n-slides> <folder-slug>
+set -euo pipefail
+WORK="$1"; N="$2"; SLUG="$3"
+
+# Both filenames, always — the two halves of the toolchain disagree (see above).
+ln -sf composition.html "$WORK/index.html" 2>/dev/null || true
+
+# Stills at start+1.5s of each 3.0s slide — the SETTLED state, never the entrance.
+AT=$(python3 -c "print(','.join(str(round(i*3.0+1.5,1)) for i in range($N)))")
+vidfarm stills "$WORK" --at "$AT" --out "$WORK/slides" --sheet \
+  || vidfarm hf snapshot "$WORK" --at "$AT" --no-end -o "$WORK/slides" --describe false
+
+# Rename to an explicit order. The order is DATA: the thread is a story.
+i=1; for f in "$WORK"/slides/*.png; do
+  case "$f" in *contact-sheet*) continue;; esac
+  mv "$f" "$(printf '%s/slides/slide-%02d.png' "$WORK" "$i")"; i=$((i+1))
+done
+
+# DURABLE My Files — the temp store deletes after 30 days and the carousel would 404.
+for f in "$WORK"/slides/slide-*.png; do
+  vidfarm put-file "$f" --folder "threads/$SLUG" --notes "$(basename "$f") — $SLUG"
+done
+
+# The preview copy. Same composition, no second build.
+vidfarm render "$WORK" --wait --output "$WORK/final.mp4" \
+  || vidfarm hf render "$WORK" --output "$WORK/final.mp4"
+
+echo "carousel: $WORK/slides/slide-*.png   preview: $WORK/final.mp4"
+echo "now read $WORK/slides/contact-sheet.png as one image — that is gate 3"
+```
+
+## Appendix C — `thread-qa.py` (gate 2: enforce it on the EXPORTED PNGs)
+
+`vidfarm qa` reads the DOM and cannot see a cropped column, a drifting voice or a one-sided slide.
+This runs on the pixels that ship, plus the manifest that produced them.
+
+```bash
+python3 thread-qa.py ./work/slides --manifest thread.tsv --brand vidfarm --voices
+```
+
+```python
+#!/usr/bin/env python3
+"""
+Grade an exported chat thread on the PNGs and the script, not on the markup.
+
+Six checks, each one a defect that passes every DOM check and every per-slide
+eyeball, and shows up only across the set:
+
+  1. no slide is blank           — an entrance that had not settled at +1.5s
+  2. the canvas is pure black    — a non-#000 layer puts a visible rectangle
+                                   around every slide and a notch at every tail
+  3. nothing in the safe zones   — top 14% / bottom 20% belong to the platform,
+                                   and an overflowing column crops there silently
+  4. no slide is one-sided       — measured from the manifest: a slide with only
+                                   one speaker is a monologue with a colour on it
+  5. exactly ONE brand mention,  — Rule 2, checked against the script rather
+     in the middle                 than by OCR
+  6. the voices stay separable   — --voices scores the typing tells per speaker
+                                   per slide and names the slide where they merge
+
+usage: thread-qa.py <slides-dir> [--manifest thread.tsv] [--brand <token>] [--voices]
+"""
+import glob, os, re, subprocess, sys
+
+d = sys.argv[1]
+flags = [a for a in sys.argv[2:] if a.startswith("--") and "=" not in a]
+opt = {}
+rest = [a for a in sys.argv[2:]]
+for i, a in enumerate(rest):
+    if a.startswith("--") and i + 1 < len(rest) and not rest[i + 1].startswith("--"):
+        opt[a] = rest[i + 1]
+manifest = opt.get("--manifest")
+brand = opt.get("--brand")
+do_voices = "--voices" in flags
+
+W, H = 1080, 1920
+fails, warns = [], []
+
+
+def strip(png, y, h):
+    """Max luma in a horizontal strip, via ffmpeg — no PIL dependency."""
+    # 192x24, not 96x4: a >>> skip card is a handful of small grey glyphs, and a
+    # coarse downscale averages them away into a false BLANK.
+    raw = subprocess.run(
+        ["ffmpeg", "-v", "error", "-i", png, "-vf",
+         f"crop={W}:{h}:0:{y},format=gray,scale=192:24", "-frames:v", "1",
+         "-f", "rawvideo", "-pix_fmt", "gray", "-"],
+        capture_output=True).stdout
+    return max(raw) if raw else 0
+
+
+slides = sorted(f for f in glob.glob(os.path.join(d, "*.png"))
+                if "contact-sheet" not in f)
+if not slides:
+    sys.exit("no slides found")
+if not 8 <= len(slides) <= 15:
+    warns.append(f"{len(slides)} slides — the harness range is 8-15")
+
+# ------------------------------------------------------------ parse the script
+slides_txt = []
+if manifest:
+    cur = []
+    for raw in open(manifest, encoding="utf-8"):
+        line = raw.rstrip("\n")
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        if line.strip() == "---":
+            slides_txt.append(cur); cur = []; continue
+        p = line.split("\t")
+        cur.append((p[0].strip(), p[1].strip() if len(p) > 1 else ""))
+    if cur:
+        slides_txt.append(cur)
+    if len(slides_txt) != len(slides):
+        warns.append(f"manifest has {len(slides_txt)} slides, {len(slides)} PNGs exported")
+
+
+def is_skip(i):
+    """A >>> card is SUPPOSED to be nearly empty. Without the manifest there is no
+    way to tell it from a slide that failed to render, so say so rather than guess."""
+    return i < len(slides_txt) and slides_txt[i] and slides_txt[i][0][0] == "skip"
+
+
+# ------------------------------------------------- 1 + 2 + 3. pixels
+for i, s in enumerate(slides):
+    name = os.path.basename(s)
+    mid = strip(s, int(H * 0.35), int(H * 0.30))
+    if is_skip(i):
+        # the chevrons are small and grey — present, but nowhere near a bubble
+        if mid < 12:
+            fails.append(f"{name}: skip card is EMPTY — the >>> did not render")
+        elif mid > 200:
+            warns.append(f"{name}: skip card has a bubble on it")
+    elif mid < 24:
+        fails.append(f"{name}: BLANK — nothing on the slide at +1.5s"
+                     + ("" if manifest else " (or it is a skip card — pass --manifest)"))
+    # the extreme edges are canvas on every legal slide, skip cards included
+    for label, y, h in (("top", 0, int(H * 0.14)), ("bottom", int(H * 0.80), int(H * 0.20))):
+        if strip(s, y, h) > 30:
+            fails.append(f"{name}: ink in the {label} reserved zone — the column "
+                         f"overflows and the platform UI will crop it")
+    # a corner is always canvas; it must be black, not near-black
+    corner = strip(s, 4, 24)
+    if corner > 6:
+        fails.append(f"{name}: canvas is not #000 (corner luma {corner}) — Rule 4")
+
+# ------------------------------------------------- 4 + 5 + 6. the manifest
+if slides_txt:
+    for i, sl in enumerate(slides_txt, 1):
+        speakers = {w for w, _ in sl if w in ("me", "them")}
+        if sl and sl[0][0] != "skip" and len(speakers) < 2:
+            warns.append(f"slide {i}: only {speakers or '{}'} speaks — a one-sided "
+                         f"slide reads as a monologue")
+        for w, t in sl:
+            if w in ("me", "them") and len(t.replace("|", " ").split()) > 22:
+                fails.append(f"slide {i}: a {w} bubble runs past 22 words")
+
+    if brand:
+        hits = [i for i, sl in enumerate(slides_txt, 1)
+                if any(brand.lower() in t.lower() for _, t in sl)]
+        n = len(slides_txt)
+        if len(hits) != 1:
+            fails.append(f"brand {brand!r} appears on slides {hits} — Rule 2 is exactly one")
+        elif not 3 < hits[0] <= n - 3:
+            fails.append(f"brand on slide {hits[0]} of {n} — Rule 2 wants three story "
+                         f"slides on each side")
+
+    if do_voices:
+        # Four tells, scored per speaker per slide. They are crude on purpose:
+        # the number is not the point, the CONVERGENCE is.
+        def score(t):
+            return (
+                1 if re.search(r"[.!?]$", t.strip()) else 0,          # terminal stop
+                1 if re.search(r"^[A-Z]", t.strip()) else 0,          # opening capital
+                1 if re.search(r"\b(ur|bc|rn|thx|u|lol|lmao)\b", t.lower()) else 0,
+                1 if "," in t else 0,
+            )
+        run = []
+        for i, sl in enumerate(slides_txt, 1):
+            acc = {}
+            for w, t in sl:
+                if w in ("me", "them") and t:
+                    a = acc.setdefault(w, [0, 0, 0, 0, 0])
+                    for k, v in enumerate(score(t)):
+                        a[k] += v
+                    a[4] += 1
+            if len(acc) == 2:
+                m, th = acc["me"], acc["them"]
+                dist = sum(abs(m[k] / m[4] - th[k] / th[4]) for k in range(4))
+                run.append((i, round(dist, 2)))
+        merged = [i for i, dv in run if dv < 1.0]
+        if merged:
+            warns.append(f"voices converge on slide(s) {merged} — read only the grey "
+                         f"bubbles across the contact sheet (Rule 1)")
+        print("voice separation per slide: " +
+              " ".join(f"{i}:{dv}" for i, dv in run))
+
+# ------------------------------------------------------------------- verdict
+for w in warns:
+    print(f"⚠ {w}")
+for f in fails:
+    print(f"✗ {f}")
+print(f"\n{len(slides)} slides · {len(fails)} fail · {len(warns)} warn")
+sys.exit(1 if fails else 0)
+```
+
+## Appendix D — a worked example: vidfarm.cc, the group chat that added the wrong guy
+
+Twelve slides, 36.0s. Cost mode `minimize` — the whole thread costs $0. Engine: **comedy**.
+
+**Build log header**
+
+```
+STORY:     A founders' group chat adds a stranger by mistake; he stays, and out-posts all of them
+ENGINE:    comedy
+VOICES:    A (blue) = the stranger — lowercase, no punctuation, deadpan, double-sends
+           B (grey) = the admin — full sentences, capitals, apologises, 😅
+OFFER:     vidfarm.cc — make one video, get thirty versions of it overnight
+SHILL:     slide 7 of 12
+```
+
+**Post caption** (this is where the bait lives)
+
+```
+he never left the group chat 💀
+do i tell him or do i keep him
+```
+
+**`thread.tsv`** (abridged — slides 1, 2, 3, 7 and 12)
+
+```
+them	Hi! Sorry, quick check — are you the Dan from the accelerator?
+me	no
+me	whos dan
+them	Oh no. 😅 I think I added the wrong number to the founders group.
+me	i did wonder why 40 people were arguing about pricing at 6am
+---
+them	I’ll take you out, so sorry about that!
+me	nah leave me in
+me	best thing thats happened to my week
+them	…okay. But you have to introduce yourself.
+me	i sell garden sheds
+---
+skip
+---
+them	Okay the sheds guy is outposting all of us and I need to know how.
+me	i film one thing on a saturday
+me	then the ai cuts it into like 30 versions overnight
+me	vidfarm. i approve the good ones on sunday with a coffee
+them	That feels illegal.
+me	its sheds mate
+---
+them	MARCUS IS ASKING IF YOU DO CONSULTING
+me	tell marcus i do sheds
+them	He has offered you money.
+me	tell marcus i do sheds
+them	He’s wiring it.
+me	give me a sec
+```
+
+**Slide 7, read against the six shill rules**
+
+- *Plot fact?* Yes — she asked how he out-posts them. He answers about his Saturday.
+- *Named once, lowercase, mid-bubble?* Yes, third bubble, no URL.
+- *Middle?* Slide 7 of 12 — five story slides before, five after.
+- *Question about the character?* "I need to know how" is about him, not about editing software.
+- *Sceptical reaction?* "That feels illegal."
+- *Story survives deletion?* Delete slide 7 and the shed-guy thread still works. Passes.
+
+**Build and export**
+
+```bash
+python3 build-thread.py thread.tsv work/composition.html \
+        --title="vidfarm — group chat thread" --brand=vidfarm
+ln -sf composition.html work/index.html
+vidfarm qa ./work --harness ./experimental/engaging-chat-convo.md
+bash export-thread.sh ./work 12 group-chat
+python3 thread-qa.py ./work/slides --manifest thread.tsv --brand vidfarm --voices
+open ./work/slides/contact-sheet.png     # gate 3 — the pass that actually matters
+```
+
+**What the first pass got wrong** (recorded because it is what this format gets wrong):
+
+1. **Slides 1–2 were set-up.** The original slide 1 was the admin creating the group. Deleted both;
+   the thread now opens on "are you the Dan from the accelerator?", which is a mistake already in
+   progress. This is the most common cut in the format and it always improves the thread.
+2. **The blue voice drifted from slide 8.** He started using commas and capitals under pressure —
+   `thread-qa.py --voices` flagged 8, 9 and 10. Rewritten so he goes *shorter* under pressure, which
+   is his register, not more correct.
+3. **The shill was originally slide 4** and every reader would have known the thread was an ad. Moved
+   to 7 and gave the admin a sceptical line, which is also the funnier version.
+4. **Slide 11 had ten bubbles** and the column cropped at the bottom on a phone. `build-thread.py`
+   warned before render; split into two slides and the thread went from 11 to 12.
+5. **The last slide originally resolved** — he explained the sheds. Cut the explanation and ended on
+   `give me a sec`, which is the same shape as the reference's cliffhanger.
+
+## Appendix E — the harness in one paragraph, for a handoff
+
+> Build a 12-slide chat-thread carousel, 9:16, 1080×1920, on pure `#000000`. Each slide is ONE text
+> layer holding a vertically-centred column of 4–8 iOS-dark-mode bubbles — blue `#0A84FF` right,
+> grey `#2C2C2E` left, white 46px type in one self-hosted family at one weight, 36px radius, a tail
+> on the last bubble of each run only, and no phone chrome of any kind (no status bar, avatar,
+> header, timestamps or keyboard). Two characters who type differently enough to be told apart with
+> the colour removed: one lowercase and unpunctuated who double-sends, one who writes complete
+> sentences with emoji. The story opens mid-mistake, uses exactly two `>>>` skip cards to jump time,
+> reveals something in the middle that recasts what came before, breaks one character's register in
+> the last act, and ends mid-action with no resolution. Exactly one slide names the offer —
+> lowercase, mid-bubble, once, as a plot fact the character mentions about their own life, with the
+> other character reacting sceptically. Ship the twelve PNGs as the deliverable (durable My Files,
+> ordered in `slides.json`, order is the story) and an MP4 at exactly 3.0s per slide with hard cuts
+> as the preview. Costs $0 in `minimize`. Full rules:
+> `vidfarm.cc/experimental/engaging-chat-convo.md`.