@officexapp/vidfarm-devcli 0.21.27 → 0.21.29

package/.agents/skills/vidfarm/references/onboarding.md

@@ -1,18 +1,18 @@
-## Getting started / onboarding a new director
+## Getting started / onboarding / consultation
 
-Only run this flow when the director signals they **don't know where to start** ("getting started", "help me set up", "I don't know where to begin"). If they already know what they want, skip straight to it — never force onboarding. Directors can also jump to any single step (e.g. "just find me a good template for X" → go straight to template discovery).
+Run this flow when the director signals they **don't know where to start** ("getting started", "help me set up", "I don't know where to begin") **or asks for a "consultation"** ("give me a consultation", "consult me on my offer", "I want a strategy consultation"). **"Consultation" is a first-class trigger for the brainstorm chain** — treat it as a request for the full run: the cold-start interview → awareness stages → angles → hooks (steps 1-4 below), driven by the `brainstorm/*` primitives rather than brainstormed in chat from memory. If they already know what they want, skip straight to it — never force onboarding. Directors can also jump to any single step (e.g. "just find me a good template for X" → go straight to template discovery, or "consult me on hooks" → run `brainstorm/hooks` alone).
 
 The point of onboarding is to build **durable, reusable context** in My Files, namescoped under the director's product/offer folder, so future chats and agents can read it back. Save each artifact as Markdown with `browse_files` write (web copilot) or `vidfarm put-file` (devcli):
 
-1. **Product context** → `About.md` (basic offer/product) or a deeper `Interview.md` if they want depth. Drive the interview questions with `brainstorm/coldstart`.
+1. **Product context** → **`OFFER.md`** (or `OFFER_<NAME>.md` — e.g. `OFFER_ACME_SKINCARE.md` — when the director runs more than one offer). Drive the interview questions with `brainstorm/coldstart` and **recommend the director save their answers into that file**, either locally next to their project or in cloud My Files. This is the durable artifact every later step reads back; `About.md` / `Interview.md` are legacy names — prefer `OFFER*.md` for anything new.
 2. **Awareness level** (Eugene Schwartz — problem-aware, solution-unaware, …) → `awareness-levels.md`. If it's genuinely unknown after thinking it through, note that ads for **every** level should be made and tested. Use `brainstorm/awareness_stages`.
 3. **Persuasive angles** → `persuasive-angles.md`, via `brainstorm/angles`.
-4. **Hooks** → `ad-hooks.md`, via `brainstorm/hooks`.
+4. **Hooks** → `ad-hooks.md`, via `brainstorm/hooks`. **Grade what comes back against `references/hooks-and-virality.md`** — the three gates, situation-vs-label, and the unguessable test — instead of shipping the raw list. And never rank a generated batch with the same reasoning that wrote it; the rubric catches defects, it doesn't pick winners.
 5. **Brand assets & demos** — ask if they have logos/mascots/themes (suggest a `/brand-assets/` folder, e.g. `/brand-assets/logo.png`) or product demos / screen recordings (suggest a `/product-demos/` folder). `browse_files list` / `vidfarm files` first to see what they already uploaded; filenames should be descriptive and every asset worth finding later should get **notes** (`annotate-file` / `browse_files annotate`) so `files --search` works months from now. If they have a recurring character/mascot, set up its `/files/characters/<slug>/` trio now — `<character_id>.json` (e.g. `character_zara.json`) + `character_sprite_card.png` + `character_about.md` (see "Recurring characters are first-class").
 6. **Budget** — ask roughly what they want to spend per video, and map it to the Cost spectrum (free reuse+local render → pennies for cloud render → ~$1 for some AI scenes → $10+ for heavy AI gen). This sets which approach you default to and whether AI **video** generation is on the table (ask permission before using it; image gen is cheap and fine). Budget can also be revisited per editor project.
 7. **Recommend & adapt a template** — pair what you now know about the offer against the decomposed template catalog (`GET /discover/feed?q=<offer>`, read each result's `promotions`/`keywords`/`summary`), recommend the best 3-6, then fork and **modify** the winner to fit their offer. Prefer already-decomposed templates so the director skips the ~$0.10 decompose cost.
 
-**Assume multiple offers.** My Files is multi-offer (see the My Files section) — namescope every onboarding artifact under the right product/offer/region folder (`acme-skincare/About.md`, not a bare `About.md`) so one brand's context never bleeds into another's.
+**Assume multiple offers.** My Files is multi-offer (see the My Files section) — namescope every onboarding artifact under the right product/offer/region folder (`acme-skincare/OFFER.md`, not a bare `OFFER.md`) so one brand's context never bleeds into another's. When a director keeps several offers in one flat folder, name the files `OFFER_ACME_SKINCARE.md` / `OFFER_ACME_SUPPLEMENTS.md` instead.
 
 ## Default assistance pattern
 

package/.agents/skills/vidfarm/references/primitives.md

@@ -314,7 +314,11 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/audio/transcribe" \
 
 ## Brainstorm primitives
 
-The `brainstorm/*` primitives are the strategy toolkit. They are reusable, billable AI reasoning steps — the same family the AI Copilot exposes as chip suggestions. Treat **product placement** as a first-class member of this family, right alongside angles and hooks:
+The `brainstorm/*` primitives are the strategy toolkit. They are reusable, billable AI reasoning steps — the same family the AI Copilot exposes as chip suggestions. Treat **product placement** as a first-class member of this family, right alongside angles and hooks.
+
+When a director asks for a **"consultation"**, that is this toolkit: run the chain `coldstart` (the interview) → `awareness_stages` → `angles` → `hooks`, saving each output to My Files as you go (see `references/onboarding.md`). Never improvise a consultation from memory when these routes exist. "Consult me on hooks/angles" → run just that primitive.
+
+`coldstart` returns *questions*, not answers — always recommend the director write their answers into an **`OFFER.md`** (or `OFFER_<NAME>.md` when they run several offers), locally or in cloud My Files. That file becomes the `offer_description` you feed into `awareness_stages`, `angles`, `hooks`, and `product_placement`.
 
 - `POST /api/v1/primitives/brainstorm/coldstart` — `{ payload: { user_message } }` → foundational questionnaire for a customer starting from zero.
 - `POST /api/v1/primitives/brainstorm/awareness_stages` — `{ payload: { offer_description } }` → which Eugene-Schwartz awareness stages to target first.

package/.agents/skills/vidfarm/regimes/README.md

@@ -0,0 +1,77 @@
+# QA_REGIME.md — the per-style quality contract
+
+`vidfarm qa`'s built-in rules are **universal**: no HTML slop, the caption font regime, the thumbnail frame. They're the same for every video anyone makes, so they live in code.
+
+A **QA_REGIME.md is the opposite**: it's what makes *your* format good — your audience, your hook shape, your banned vocabulary, your pacing, your compliance line. That changes per account, per offer, per campaign, so it can't be hard-coded. It lives next to the work as Markdown you own, edit, and version.
+
+**It matters most in scripting mode.** One video gets human eyes on every frame; fifty variants generated in a loop do not. The regime is what the batch is graded against — the thing that keeps variant #37 as good as variant #1.
+
+## Using one
+
+```bash
+vidfarm regime list                                   # what ships with the CLI
+vidfarm regime show hooks                             # read one
+vidfarm regime init short-form --out ./work/QA_REGIME.md   # copy it next to your work, then EDIT it
+
+vidfarm qa ./work                                     # auto-uses ./work/QA_REGIME.md if present
+vidfarm qa ./work --regime hooks                      # a built-in by name
+vidfarm qa ./work --regime ./brand/HOUSE_RULES.md     # any file, anywhere
+vidfarm qa ./work --regime short-form --regime ./work/QA_REGIME.md   # they STACK
+vidfarm qa ./work --json                              # checks + review items, for a scripted batch
+```
+
+Regimes compose: a shared house regime plus a per-campaign one is the intended shape. `--no-regime` skips auto-discovery; `VIDFARM_QA_REGIME` sets a default for a whole scripting run.
+
+## The format
+
+Plain Markdown, with two machine-readable affordances:
+
+**1. Optional front matter with a `checks:` block** — the assertions the CLI settles deterministically from the composition, instantly, with no AI and no network:
+
+```markdown
+---
+name: my-house-style
+video_type: what this regime is for
+checks:
+  duration_sec: 8-34        # also "<=34", ">=8", or "30"
+  aspect: 9:16              # "9:16|1:1" to allow several
+  first_frame_visual: required
+  first_frame_text: required | forbidden
+  hook_words_max: 7
+  text_by_sec: 1.0
+  audio: required | forbidden
+  captions: required
+  font_regime: required
+  safe_zone: required
+  scenes: 3-12
+  max_scene_sec: 8
+  max_text_cards: 3
+  max_simultaneous_text: 2
+  forbid_text: ["link in bio", "comment below"]
+  require_text: []
+---
+```
+
+Unknown keys are reported and ignored, never silently dropped.
+
+**2. Any `- [ ]` checkbox line** in the body becomes a **review item** — a question handed back for the agent or the human to answer. "Is the withheld answer one the viewer can't supply themselves?" is a judgment call; pretending a linter settles it would be a lie.
+
+Everything else is prose the agent reads for context. That split is the whole design: the CLI is honest about which half it can enforce, and it never passes a video on the strength of the half it can't.
+
+## Writing your own
+
+Start from the closest built-in (`vidfarm regime init <name>`), then **delete what doesn't apply and add what makes your format yours**. A regime you didn't edit isn't about your videos.
+
+Good regimes tend to have: a **Part 0** naming the viewer in one line (the thing that decides everything else), an **anatomy** section for the beats your format needs, **rules** with the reason attached — a rule whose "why" is missing gets argued away by the next agent that reads it — and a **pre-flight checklist** of `- [ ]` items, which is the part the CLI hands back on every run.
+
+Keep the checklist short enough that answering it honestly is cheaper than skipping it.
+
+## Built-ins
+
+| Name | For |
+|---|---|
+| `short-form` | The general default: the four charges (hook / loop / payoff / bait) + the standalone rule. Start here |
+| `hooks` | Hook-variant batches — chunk-1 legibility, the unguessable test, the anti-patterns that only appear at volume |
+| `ugc-testimonial` | A person vouching for a product. Mostly rules about what NOT to add |
+| `explainer` | Faceless educational video: one claim, invented visuals |
+| `product-demo` | Real product doing a real thing — the highest slop-risk format in the catalog |

package/.agents/skills/vidfarm/regimes/explainer.QA_REGIME.md

@@ -0,0 +1,82 @@
+---
+name: explainer
+video_type: faceless explainer / educational — one idea, invented visuals, narrated
+checks:
+  duration_sec: 20-180
+  first_frame_visual: required
+  first_frame_text: required
+  captions: required
+  audio: required
+  font_regime: required
+  max_scene_sec: 8
+  max_simultaneous_text: 1
+---
+
+# Explainer QA Regime
+
+For faceless educational video: one idea, explained, with visuals that are *invented* (typography, diagrams, data, abstract motion) rather than captured. No presenter, so the structure has to carry everything a face would.
+
+## The one test
+
+> **Can you say what single thing the viewer knows at the end that they didn't know at the start — in one sentence, without using the word "and"?**
+
+If it takes an "and," you have two videos. Split them. The dominant failure of the format is not being boring — it's being *about a topic* instead of being *about one claim*.
+
+## Structure
+
+| Beat | Job |
+|---|---|
+| **The claim** (0:00–0:03) | State the surprising conclusion first. Not "today we'll look at X" |
+| **The stakes** | Why it matters to the viewer specifically. One sentence |
+| **The mechanism** | The actual explanation, in 3–5 steps that each earn their scene |
+| **The turn** | The part that isn't obvious — the reason the video exists |
+| **The consequence** | What the viewer does or thinks differently now |
+
+**Conclusion first, not last.** Educational-video instinct is to build to the reveal; feed instinct is that nobody stays for a reveal they weren't promised. Say the conclusion in the first three seconds, then spend the video *earning* it. Retention comes from "how could that be true?", not from suspense.
+
+## Rules
+
+### Rule 1 — one idea, and the scene count proves it
+
+3–5 steps in the mechanism, each with a scene that shows something the narration doesn't say. If a scene only re-renders the words being spoken, it isn't a scene — it's a slide, and slides are where retention dies. `max_scene_sec` is checked above for exactly this reason: a static hold is the visual form of "I ran out of things to show."
+
+### Rule 2 — visuals carry information, not decoration
+
+Every invented visual should be doing one of: showing a quantity (chart, count-up, comparison), showing a relationship (diagram, flow, before/after), showing a scale (physical comparison), or showing a process (step, progress, transformation). Ambient loops and abstract gradients under narration are the explainer equivalent of stock footage — they cost time and buy nothing.
+
+### Rule 3 — numbers get their own moment or they get cut
+
+A figure spoken over a busy frame doesn't land. If a number matters, it appears on screen, alone, long enough to read. If it doesn't deserve that, it doesn't belong in the script.
+
+### Rule 4 — no unsourced authority
+
+"Studies show", "experts agree", "it's well known" — either name the source on screen or state it as your own reasoning. The format's whole currency is that it sounds like it knows; borrowed authority with no name is what makes an explainer feel like content farming.
+
+### Rule 5 — narration is written to be heard, not read
+
+Short clauses. One idea per sentence. No subordinate clause stacking. Read it aloud once — if you run out of breath or have to re-read a line, rewrite it. TTS in particular will happily deliver an unreadable sentence at a perfectly even pace, which is how a script defect ships.
+
+### Rule 6 — production floor
+
+Captions verbatim in the font regime and safe zone · frame 0 states the claim (it is the thumbnail, and for this format it's usually pure typography, which makes it the *easiest* format to get a good thumbnail from — no excuse for a black open) · no HTML slop: an explainer's subject matter drags authors toward feature grids, comparison tables, and card layouts, and those are exactly the banned web furniture. A comparison is an animated before/after, not a two-column table.
+
+## Bulk-generation notes
+
+The variant axis is **the claim**, not the topic: ten videos each making a different one-sentence claim about the same subject beats one video making ten points. It also gives you clean attribution — you learn which claim travels, which is the only thing you can act on.
+
+Reuse across variants: the mechanism scenes are often identical, so build them once as reusable assets and vary the claim + stakes + turn. That's the cheap path — HTML/CSS motion over a fixed asset set, no per-variant generation spend.
+
+## Pre-flight checklist
+
+- [ ] The one thing the viewer learns fits in a single sentence with no "and"
+- [ ] The conclusion is stated in the first 3 seconds, not saved for the end
+- [ ] The stakes are named — why this viewer specifically should care
+- [ ] The mechanism is 3–5 steps and each has a scene that adds information
+- [ ] No scene is a slide that just re-renders the narration
+- [ ] Every visual shows a quantity, relationship, scale, or process
+- [ ] Every number that matters gets its own readable moment
+- [ ] No unsourced "studies show" / "experts agree"
+- [ ] The narration was read aloud and survived it
+- [ ] Frame 0 states the claim and works as a standalone thumbnail
+- [ ] No comparison tables, feature grids, or card layouts (`vidfarm qa` clean)
+- [ ] In a batch: this variant makes a genuinely different claim, not a rephrased one

package/.agents/skills/vidfarm/regimes/hooks.QA_REGIME.md

@@ -0,0 +1,117 @@
+---
+name: hooks
+video_type: short-form hook test — cold-algorithm survival into a funnel
+checks:
+  duration_sec: 6-45
+  aspect: 9:16
+  first_frame_visual: required
+  first_frame_text: required
+  hook_words_max: 7
+  text_by_sec: 0.5
+  font_regime: required
+  max_simultaneous_text: 1
+---
+
+# Hooks Regime
+
+Operating rules for short-form hooks that have to survive a cold algorithm and convert into a funnel. Use this regime when the thing you are bulk-generating **is the hook** — same body, N openings — which is the highest-leverage variant axis there is.
+
+Copy this file next to your work (`vidfarm regime init hooks --out ./work/QA_REGIME.md`) and edit it. The parts that matter most to you are the parts you add.
+
+*(Craft reference: the vidfarm skill's `references/hooks-and-virality.md`. This file is its checkable form — copy and edit it per account.)*
+
+## The three gates
+
+A hook clears three gates in order. They fail in order too, and each fails *silently* — the view count never tells you which one killed you.
+
+| # | Gate | Question | Where it lives | Failure looks like |
+|---|---|---|---|---|
+| 1 | **Legibility** | Can a stranger *understand* this? | Caption chunk 1 | Never leaves the test batch |
+| 2 | **Tension** | Is there something they don't know? | The withheld final clause | Views and likes, no clicks |
+| 3 | **Relevance** | Is this person a buyer? | Chunks 2–3 and the body | Clicks and opt-ins, no sales |
+
+**The order is the whole insight.** Almost everyone writes for gate 3 first, because relevance is what marketing training optimizes. But a hook that is maximally relevant and minimally legible never reaches a relevant person.
+
+## Gate 1 — Legibility
+
+The platform's first test batch is a few hundred essentially random viewers, of whom your buyer is 1–2%. If the opening only parses for someone already living the exact situation, ~98% of the batch swipes without comprehending, watch time craters, and the video never escapes the batch to reach the people who *would* have understood it. **A hook that only works on a perfectly-targeted viewer never gets a perfectly-targeted viewer.**
+
+**The unit is caption chunk 1, not "the first 3 seconds."** Captions render in phrase chunks of ~2–6 words, and the viewer reads chunk one *before hearing any audio*. The real hook unit is words 1–5 on screen — which is why `first_frame_text` and `hook_words_max` are machine-checked above.
+
+> **Chunk 1 must be legible to everyone and relevant to few.**
+
+Three constraints:
+
+1. **Complete clause — subject plus verb.** Not a noun phrase, not a bare number, not a label. This one rule fixes most failures, because a clause forces context in.
+2. **No jargon.** A domain term in chunk 1 kills the cold start even inside a valid clause. Jargon belongs in chunk 2+, where it *qualifies* instead of excluding.
+3. **The cold-viewer test.** Would a random person with no interest in the category understand what situation is described? Not *would they care* — *would they understand*.
+
+**The cheapest predictor: situations, not labels.** A situation is a thing that happened, with a subject and an outcome — *someone deleted my message · she refused my money · they stopped replying · tracking said delivered*. A stranger parses all of it instantly, because humans are built to parse events. A label is a concept with a name — *anonymity · distribution · platform risk · seeding* — and it carries meaning only for someone who already holds the category, which is exactly the person the cold-start batch does not contain. If your opening names a concept rather than an event, assume it fails until proven otherwise.
+
+| Fragment (fails) | Complete clause (passes) |
+|---|---|
+| `SIX STARTS, ZERO FINISHES` | `I'VE QUIT SIX BUSINESSES` |
+| `FOURTH APP` | `I SHIPPED MY FOURTH APP` |
+| `ANONYMITY` | `I'VE NEVER SHOWN MY FACE` |
+| `$50,000 IN SALES` | `THEY WANTED $50,000 FIRST` |
+| `TWO HOURS A WEEK` | `THIS TAKES TWO HOURS A WEEK` |
+
+**Banned chunk-1 openers:** *So I was thinking · There's a reason · Here's the thing · A lot of people · If you're a… · Let me tell you* — any throat-clearing. The first words are the most expensive real estate you own.
+
+## Gate 2 — Tension
+
+**Identification and curiosity are different jobs.** Identification ("that's me") earns a like, a save, a follow. Curiosity ("wait, what?") earns **a click**. If the hook's job is a click into a funnel, the loop matters more than the resonance.
+
+**The mechanical fix:** most weak hooks state the insight *and its resolution* in one line, so there is nothing left to find out. Move the payoff out of the line and into the video body — same insight, same specificity, the last clause just stops answering itself.
+
+| Closes | Opens |
+|---|---|
+| "I paid three creators. I ended up teaching all three how to hook." | "I paid three creators. The third one told me why the first two ghosted." |
+| "Every customer I have, I'm renting." | "I asked my lead company one question. Their answer told me I don't own a single customer." |
+| "Launch day: three upvotes, two of them mine." | "Fourth launch, three upvotes. The problem was never the product." |
+
+> **Tension in the first chunk. Withheld answer in the last chunk.**
+
+**The answer must be unguessable.** A structurally valid loop whose answer the viewer can supply themselves **is not a loop** — the withhold happens on the page, the resolution happens in their head before their thumb moves. This is the most dangerous failure in this document, because it passes every mechanical check above and dies in the field. Two ways out: withhold something only you know (the other side of a transaction, what the gatekeeper actually checks), or send them to check rather than telling them (*"Go and look at who's still watching at eleven at night"*) — an unresolved belief they can't close from the sofa.
+
+**Don't force it.** When a line lands in one beat and withholding would break it, keep it and *label it an identification hook*. Tagged, those become the control group that tells you whether loops actually beat identification for your audience.
+
+## Gate 3 — Relevance
+
+- **Offer adjacency.** The hook should be the "before" of the offer's "after." A hook that fully solves the problem, or creates a desire the offer doesn't resolve, is *worse* than a weak hook: it fills the funnel with people who will never buy. Symptom — great opt-in rate, lead→paid under ~5%, visible only after you've scaled it.
+- **Deliverability.** Aggression isn't the problem, undeliverability is. A promise the offer can't keep buys front-end conversion with churn. Point the aggression at what you can demonstrate.
+- **Guarantees are proof, not headline.** Leading with the guarantee attracts guarantee-shoppers who churn at the boundary.
+- **Sell the entry promise, not the offer.** The hook's job is to match what the *next screen* says. A hook that pitches the end offer desyncs the sequence.
+
+## Anti-patterns for bulk generation
+
+Read these before you loop — they are the failure modes that only appear at volume.
+
+- **Never point a generator at your grader.** A model writing hooks scored by a model converges on whatever the rubric measures, not on what works. The rubric is a check on a hook you already believe in, **never a ranking function**. Use it to catch defects, not to pick winners.
+- **A different noun is not a different hook.** If two variants could be filmed from one script by changing one word, you have one hook — and a batch of 20 of those teaches you nothing. This is the dominant failure mode when bulk-generating for a category that spans verticals.
+- **Specificity is observed detail, not generated nouns.** `Boston window cleaner` is a generated token; `comment posted 9:14, video finished 9:55` is an observation. One sounds invented, the other sounds witnessed.
+- **Obscurity is not qualification.** A hard-to-parse opening filters for nobody, because the video never reaches anyone. Qualification is the body's job.
+
+## The measurement regime
+
+- **The cluster is the unit, not the hook.** A single hook at low view counts tells you nothing — variance dominates. A cluster is a bet on one buyer insight and one emotional lever; that's what you kill or scale. One attribution slug per cluster, one cluster per account.
+- **Judge on the metric that pays rent.** In increasing order of truth: views → completions → profile visits → **funnel completions per post** → **revenue per 1,000 views**.
+- **Read the retention curve:** cliff in the first 2–3s = chunk 1 failed · gentle decline with low completion = the body doesn't pay off the hook · good completion but no profile visits = you built identification, not curiosity · good clicks but no sales = offer adjacency.
+- **Then play the power law.** ~2% of videos produce ~90% of results. When one hits, make ten more of exactly it. Iterate on winners; never fix losers.
+
+## Pre-flight checklist
+
+- [ ] Chunk 1 is a complete clause with a subject and a verb
+- [ ] Chunk 1 names a **situation**, not a label or concept
+- [ ] Chunk 1 contains no domain jargon
+- [ ] A stranger with no interest in the category understands the situation
+- [ ] No throat-clearing in the first words
+- [ ] The final clause withholds
+- [ ] **The withheld answer is one the viewer cannot supply themselves**
+- [ ] Frame 0 works as a standalone thumbnail — subject in frame, caption legible
+- [ ] The promise can be cashed, honestly, every time
+- [ ] The person this attracts is someone who would buy
+- [ ] It matches what the next screen actually says
+- [ ] It is a genuinely different video from every other hook in the batch
+
+Twelve checks. Two carry most of the weight and are the two almost everyone skips: **situation, not label** predicts cold-start survival before you write a word, and **unguessable** is the only item a hook can fail while passing every other item — which is why it gets shipped.

package/.agents/skills/vidfarm/regimes/product-demo.QA_REGIME.md

@@ -0,0 +1,92 @@
+---
+name: product-demo
+video_type: product / SaaS demo, feature reveal, launch clip
+checks:
+  duration_sec: 10-90
+  first_frame_visual: required
+  first_frame_text: required
+  captions: required
+  font_regime: required
+  max_text_cards: 3
+  max_simultaneous_text: 1
+  forbid_text:
+    - sign up for a free trial
+    - get started today
+    - book a demo
+    - learn more
+---
+
+# Product Demo QA Regime
+
+For showing a real product doing a real thing. This is the format with the **highest slop risk in the entire catalog**, because the subject matter is a website — so the author's web instincts and the product's own design language both push toward putting a landing page on the timeline.
+
+## The one test
+
+> **Does the video show the product doing something, or does it describe the product?**
+
+A demo shows the screen changing. Everything else — the value prop, the pricing, the benefits, the logos — is a landing page that happens to be rendered as video, and it converts like one (i.e. it doesn't, in a feed).
+
+## Structure
+
+| Beat | Job |
+|---|---|
+| **The before** (0:00–0:03) | The painful version of the task, shown. Not stated |
+| **The move** | The one action that changes it. A click, a paste, a command |
+| **The after** | The result, on screen, uncut, long enough to be believed |
+| **The scope** | What it doesn't do / what it costs. One line, honest |
+| **The close** | Where to find it — *said*, not rendered as a button |
+
+**Open on the pain, in the product, not on the logo.** A logo open spends the thumbnail and the first second on the one thing the viewer has no reason to care about yet.
+
+## Rules
+
+### Rule 1 — the demo is real, uncut, and at real speed
+
+Speed-ramping through the boring parts is fine and expected; **cutting away at the moment the product does its work is not** — that's the exact beat the viewer is deciding on. If the real thing takes 40 seconds, show a compressed version and say it took 40 seconds. A demo that hides its latency reads as a mockup.
+
+### Rule 2 — no landing page on the timeline
+
+This is the banned list, and it's not stylistic — every one of these is web furniture that appears in zero real feed videos:
+
+- CTA buttons and capsules ("Sign Up for a Free Trial →"). Machine-checked above via `forbid_text`.
+- Benefit chip / badge rows ("✓ No credit card needed").
+- Pricing cards, feature grids, comparison tables, "as seen in" logo strips.
+- Frosted/bordered cards holding a headline + URL, gradient text fills.
+
+**Nothing in a video is clickable.** The CTA is spoken, or it's a plain caption line, or it's an arrow pointing at the real UI.
+
+### Rule 3 — one feature per video
+
+The launch-post instinct is to cover everything shipped. A feed video that covers four features teaches none of them and gets remembered for zero. Ship four videos.
+
+### Rule 4 — the UI must be legible on a phone
+
+Full-screen browser captures are unreadable at phone scale. Crop to the region that changes, scale it up, and let the rest go. If the viewer can't read the thing that changed, the demo didn't happen. Zoom on the change, not on the chrome.
+
+### Rule 5 — say the price or say nothing
+
+Pricing teased ("starting at…"), asterisked, or implied does more damage than a number that's higher than expected. Either the price is part of the story and it's stated plainly, or the video isn't about price.
+
+### Rule 6 — production floor
+
+Captions verbatim, font regime, safe zone · frame 0 shows the product mid-task with a caption up, never a logo or a title card · brand colors are fine, brand *layouts* are not · no music that fights the click sounds if the interaction is the point.
+
+## Bulk-generation notes
+
+The variant axis is **the before**: the same feature demoed against N different starting pains, one per audience segment. Same move, same after, different opening 3 seconds — which is also the cheapest possible variant to generate, since only the head of the timeline changes.
+
+Resist the temptation to fan out on visual style instead. Ten themes of one video is one video; ten pains is ten videos.
+
+## Pre-flight checklist
+
+- [ ] The video shows the product doing something, not describing it
+- [ ] It opens on the pain inside the product, not on a logo or title card
+- [ ] The moment the product does its work is on screen, uncut
+- [ ] Exactly one feature is covered
+- [ ] The changing UI region is cropped and scaled to be legible on a phone
+- [ ] There is one honest scope line (what it doesn't do, or what it costs)
+- [ ] No CTA button, benefit chip row, pricing card, feature grid, or logo strip
+- [ ] The CTA is spoken or a plain caption line — nothing on screen looks clickable
+- [ ] Price is either stated plainly or absent entirely
+- [ ] Frame 0 shows the product mid-task and works as a standalone thumbnail
+- [ ] In a batch: this variant opens on a genuinely different pain, not a restyled one

package/.agents/skills/vidfarm/regimes/short-form.QA_REGIME.md

@@ -0,0 +1,163 @@
+---
+name: short-form
+video_type: general short-form social video (TikTok / Reels / Shorts) — the default base regime
+checks:
+  duration_sec: 8-90
+  aspect: 9:16
+  first_frame_visual: required
+  first_frame_text: required
+  text_by_sec: 1.0
+  captions: required
+  font_regime: required
+  max_text_cards: 3
+  max_simultaneous_text: 2
+  max_scene_sec: 8
+---
+
+# Short-Form QA Regime
+
+The default base. Start here, copy it next to your work, then **delete what doesn't apply and add what makes your format yours** — a regime you didn't edit is a regime that isn't about your videos.
+
+> **Part I** is the anatomy: the four charges that decide whether a video travels.
+> **Part II** is the rules that keep it credible.
+> Run the pre-flight checklist before you build, and `vidfarm qa <dir> --regime ./QA_REGIME.md` before you publish. An unchecked box is a rewrite, not a fix in the edit.
+
+## Part 0 — who this is for (fill this in yourself)
+
+**Write your viewer in one line, at the top of your copy of this file, before anything else.** A perfectly-built video aimed at the wrong person is the most expensive mistake available, and it fails *silently* — nobody comments "this wasn't for me," they just scroll.
+
+Name: who they are, what they're choosing between (their real alternatives, which are rarely your competitors), the beliefs the video has to land, and the register you speak in. Every rule below is executed differently depending on that answer, which is exactly why this section can't be shipped pre-filled.
+
+## Part I — the anatomy
+
+*(The craft behind every rule below — the three gates, situations-vs-labels, loop mechanics, diagnosis by charge — is the vidfarm skill's `references/hooks-and-virality.md`. This file is the checkable form.)*
+
+**Four charges, in series, like a firework.** Each is loaded separately, and each can be weak while the others are strong — which is why you diagnose a flop *by charge*, never by declaring the whole video bad.
+
+| Charge | Job | Where it fails | Symptom when it's the weak one |
+|---|---|---|---|
+| 🪝 **Hook** | Stop the scroll | First 3 seconds | Almost no views at all |
+| 🔄 **Curiosity loop** | Hold to the end | ~0:08 → the payoff | Views, but everyone leaves at 5s |
+| 😍 **Payoff** | Tap the desire | Last third | Watched to the end, no reaction |
+| 🎣 **Bait** | Provoke a comment | Final beat + post caption | Good watch time, dead comments |
+
+**Hold three constant, vary one, post, compare.** That is the only reliable way to learn which charge is your weak one — and it's the reason bulk generation is worth doing at all.
+
+### 🪝 Hook — the first 3 seconds
+
+Three seconds, not five. The decision is made before you finish the first sentence, so **the first sentence must be the whole claim**, not the run-up to it.
+
+**Stack three hooks simultaneously** — most videos fire only one:
+
+1. **Verbal** — the spoken line.
+2. **Text** — a caption already on screen at frame 0, readable before a word is said.
+3. **Visual** — motion, an unusual angle, a face already mid-sentence, hands already working.
+
+**Muted autoplay is the default viewing condition, so the text hook does more work than the verbal one.** If the video only works with sound on, it doesn't work.
+
+**Banned openings:** throat-clearing ("Hey guys", "So I wanted to talk about…") · a logo, title card, fade from black, or a beat of silence · any sentence whose subject arrives in the second half · context before the claim (context is beat 2).
+
+⚠️ **Frame 0 is the hook AND the thumbnail.** No black open, no fade, subject in frame, caption already legible. See the `hooks` regime for the full chunk-1 craft.
+
+### 🔄 Curiosity loop — retention
+
+An open question planted early and paid off late. **The charge most videos skip entirely**, and the one that separates 200 views from 30,000.
+
+- **Open it by 0:10.** After that you're re-hooking someone who already decided to leave.
+- **Say the loop on screen**, not just out loud — a timer, a running counter, a caption that persists.
+- **One loop.** Two open questions dilute both.
+- **The loop opens and closes inside THIS video.** Withholding for forty seconds is retention; deferring the answer to another upload is a broken video (see Rule 1).
+- **Never bait-and-switch the payoff.** If you promised a number, give the real number.
+
+Mechanics, ranked: the withheld number (strongest — a real number is a promise you can keep, and a timer sustains it visually) · the withheld part ("one part of this nobody explains") · the numbered list ("three reasons, the third is the only one that matters") · the unresolved visual (works muted, zero words) · the contradiction/concession ("X pays better, and I'm still going to explain this").
+
+### 😍 Payoff — tap the desire
+
+The moment the video pays what the hook promised, landing on **what they actually want**, not on what you're selling.
+
+- **Show it, don't summarize it.** The result plays, full frame, ≥5 uninterrupted seconds. Description is not payoff.
+- **The payoff is not the CTA.** Pitching where the payoff belongs is the most common way a good video converts nothing.
+- **Land it before the final beat.** Payoff, then bait, then close — a payoff in the last second gets cut off by the loop-around.
+- **Go past the functional layer.** The satisfying beat is usually the honest limit named out loud, not the feature list.
+
+### 🎣 Bait — comments are distribution
+
+A video with replies gets shown again; a video with none dies at its first audience regardless of watch time. **Bait is a deliberate beat, not something you hope for.** One ask, in the final beat, **and in the post caption** (many people reply from the caption without finishing).
+
+Works: the confession invite ("tell me which one you already quit") · the guess ("guess how long it took, I say it at the end" — pairs perfectly with a withheld-number loop) · the named omission ("I left one thing out on purpose, ask me") · the soft disagree (a true concession people want to argue with) · a specific question, never "thoughts?".
+
+Doesn't: ragebait or a deliberate error to farm corrections (works once, costs the positioning permanently) · "follow for part two" (breaks Rule 1) · DM funnels · anything that makes bait the price of the payoff. **Pay off first, then ask.**
+
+### 📝 Captions — the delivery system for three of the four charges
+
+Not an accessibility afterthought: captions are how the hook, the loop, and the payoff reach a muted viewer.
+
+- **Verbatim, every word.** Paraphrased captions desync from the voice and read as fake.
+- **Weight 700–900, inside the 8–85% safe zone.** Below 700 disappears against footage.
+- **One to three words per line, one line at a time.** A block of full sentences doesn't get read.
+- **Cards are timed text over footage** — never a card UI, table, chip row, or frosted panel (`vidfarm qa` flags those as slop).
+- **Max ~3 standalone cards per video:** one for the loop, one for the payoff, one for the bait.
+
+## Part II — the rules
+
+### Rule 1 — every video is standalone. There is no part two.
+
+A viewer arriving mid-scroll with zero context must get a complete, useful video. **You do not control the order** — your video 12 is most people's video 1, and if one breaks out it breaks out *alone*. A cross-video cliffhanger converts your one winner into a dead end. Sharing an angle, a look, or a set of beliefs across the catalog is the strategy; *dependency* is what's banned. Test: hand it to someone who knows nothing — "wait, what is this?" and "where's the rest?" are both failures.
+
+### Rule 2 — re-establish the premise every time, and don't apologize for it
+
+One jargon-free sentence inside the first eight seconds, **after** the hook. It feels redundant to you and is load-bearing for a viewer who has heard it zero times. Vary the phrasing so the feed doesn't read as copy-paste.
+
+### Rule 3 — claim the mechanism, never the outcome
+
+Say how the thing works and what it costs. Don't promise the result — it's the claim you can't cash, and on money/health/appearance topics it's also the one that draws platform enforcement. An explicit refusal beat ("I'm not going to tell you what you'd make") reads as credibility, not as a disclaimer, and is often the strongest beat in the video.
+
+### Rule 4 — concede something true and unflattering, early
+
+Credibility is bought, and the currency is a concession they didn't expect — in the first ten seconds, so everything after inherits it. At the end it reads as a disclaimer. It doubles as a hook shape and as a loop opener ("so why bother?").
+
+### Rule 5 — show the work, not a claim
+
+Real screen capture > POV/hands > on camera > kinetic text. **Real numbers only** — rounding in your favor is the same category of lie as an outcome claim, and the audience does the arithmetic in about four seconds.
+
+### Rule 6 — production floor
+
+Verbatim captions in the font regime and the safe zone · frame 0 works as hook and thumbnail · no HTML slop (no CTA buttons, pricing cards, feature grids, benefit chips, frosted panels) · no URL or brand chrome on screen unless the angle *is* the offer.
+
+## Pre-flight checklist
+
+**Anatomy**
+- [ ] 🪝 The claim is complete inside 3 seconds — no throat-clearing, no context first
+- [ ] 🪝 Verbal + text + visual hooks all fire; a caption is legible at frame 0
+- [ ] 🪝 Frame 0 works as a standalone thumbnail a stranger would stop on
+- [ ] 🔄 One curiosity loop, opened by 0:10 and stated on screen
+- [ ] 🔄 The loop closes in this video, and the payoff is the thing that was promised
+- [ ] 😍 The payoff is shown, not summarized, and lands before the final beat
+- [ ] 🎣 One bait ask, in the final beat and in the post caption
+- [ ] 🎣 The bait is not ragebait, a DM funnel, or a follow-for-part-two
+
+**Standalone**
+- [ ] A stranger seeing only this video understands what it's about
+- [ ] Premise re-established in one sentence within 8 seconds, after the hook
+- [ ] Zero references to other videos; the close resolves here
+
+**Credibility**
+- [ ] Mechanism claimed, outcome not promised; every number on screen is real
+- [ ] One true, unflattering concession in the first ten seconds
+
+**Production**
+- [ ] Verbatim captions, weight 700–900, safe zone, one line at a time
+- [ ] ≤3 standalone cards, no slop furniture, `vidfarm qa` otherwise clean
+- [ ] In a batch: this variant differs from its siblings by more than one noun
+
+## Diagnosing a flop — read the charges, not the video
+
+| What the numbers say | Weak charge | Fix |
+|---|---|---|
+| Barely any views | 🪝 Hook | Rewrite the first 3s. New opening line, new frame 0 |
+| Views, mass exit at 3–8s | 🔄 Loop | No open question. Plant one by 0:10 |
+| Watched to the end, no reaction | 😍 Payoff | Landed on features, not desire |
+| Good retention, no comments | 🎣 Bait | No ask, or the ask was "thoughts?" |
+| Comments, but hostile | 🎣 Bait | Ragebait or an over-claim |
+
+**Vary one charge at a time.** A batch where everything changed at once teaches you nothing — which is the entire point of running scripting mode against a regime instead of just generating volume.