@officexapp/vidfarm-devcli 0.21.54 → 0.21.56

package/experimental/flash-harness.md

@@ -0,0 +1,549 @@
+---
+name: flash-harness
+video_type: NOT A FORMAT — the production PROCESS for a weak / small / fast model. Start from an already-decomposed /discover template, adapt it. Wraps whichever format harness applies.
+---
+
+# Flash Harness — build from a decomposed template, not from a blank page
+
+> Served at `https://vidfarm.cc/experimental/flash-harness.md` and, because it is the one
+> harness you may need before you have network, at `vidfarm harness show flash-harness`.
+
+**This is not a video format.** Every other file in `/experimental` tells you what a
+*specific kind of video* looks like. This one tells you *how to work* when the model
+reading it is not a frontier model. It sits **above** the format harnesses: you still read
+the format harness, you just reach it by a different road.
+
+**Who this is for.** Gemini Flash, DeepSeek, Kimi, GLM, MiniMax, Grok, Qwen, Llama, any
+distilled or fast tier, any model unsure whether it is one of these. If you are on this
+list, **stop reading `vidfarm.cc/experimental/*` as a build instruction and read it as a
+grading rubric instead.** Those files ask you to author a format from its written
+description. That works on Opus/Fable/GPT-5-class agents and reliably fails below them.
+
+The road that works below that line is short: **a video that already went viral has already
+been taken apart for you. Take the parts.**
+
+---
+
+## THE CONTRACT
+
+Twelve rules. Follow them in order. The reasons are in **Why these rules** at the bottom —
+read them after, not during. A reason next to a rule is something to negotiate with.
+
+1. **Never start from a blank composition.** Every build starts as a fork of a
+   **decomposed** template from `/discover`.
+2. **Pick the template by the client's ANGLE, not by how the template looks.** Search
+   `vidfarm discover --query "<the client's offer, in their words>" --json`.
+3. **A template is decomposed if its `/discover` row carries `summary`, `keywords` and
+   `promotions`.** No `summary` → not decomposed. Do not guess from the preview.
+4. **If nothing decomposed fits, decompose one.** Paid: `vidfarm decompose <forkId>`.
+   Free tier: `vidfarm decompose <forkId> --local`. Never skip this to save a step.
+5. **Derive the harness before you plan:** `vidfarm harness derive <forkId> --out ./HARNESS.md`.
+   That file is your plan's source of truth, not the rendered video.
+6. **Write `STORYBOARD.md` before you open `composition.html`.** One row per beat, carrying
+   the beat's `src`, `duration`, `voiceover`, and where its asset will come from.
+7. **Procure every asset for every beat in ONE pass, before you edit anything.** A beat with
+   no asset in hand is not planned, it is hoped for.
+8. **Walk the asset ladder in order and stop at the first rung that answers:** client's
+   shared folder → client's website → public raws → free stock (Pixabay/Openverse) →
+   IconScout → your own subscription's generator → billed generation.
+9. **Keep the load-bearing DNA. Replace everything else without mercy.** Load-bearing =
+   the beat count, the cut rhythm, the hook shape, the payoff position, the caption
+   identity. Every word, every image, every voice line gets replaced.
+10. **Overfitting to this one template is CORRECT.** Do not add originality on top. The
+    template is the originality; your job is the transplant.
+11. **Run the gate as a command, not from memory:** `vidfarm qa ./work --harness ./HARNESS.md`,
+    then `vidfarm stills ./work --sheet`, then look at the sheet.
+12. **Print the summary line from §8 last, verbatim, filled in.** A report without it is an
+    unfinished job.
+
+---
+
+## 0. Which model am I, and what does my subscription include?
+
+Two independent questions. Answer both once, out loud, at the start of the session. Write
+the answers into `CONTEXT.md` so the next session does not re-derive them.
+
+### 0a. Strong or weak?
+
+| You are | If you are | Then |
+|---|---|---|
+| **strong** | Claude Opus / Sonnet (4.5+), GPT-5 class, Gemini Pro (3+ thinking), Fable | Build the normal way. Read `https://vidfarm.cc/skill.md` and the format harness directly. This file is optional. |
+| **weak** | Gemini Flash / Flash-Lite, DeepSeek, Kimi, GLM, MiniMax, Grok, Qwen, Llama, any "-mini" / "-lite" / "-turbo" / distilled tier | **Follow this file.** |
+| **unsure** | you cannot name your own model, or you are a router that may swap tiers mid-task | **Treat yourself as weak.** |
+
+**Unsure is not a tie — it resolves to weak.** A strong model that follows this harness
+loses a little freedom and still ships a good video. A weak model that skips it ships
+something the client rejects. The costs are not symmetric.
+
+Two honest self-tests, if the label does not settle it:
+
+- Have you, in this session, written more than ~80 lines of HTML/CSS/GSAP that rendered
+  correctly on the **first** `vidfarm render`? If no — weak.
+- Can you hold the whole composition, the format harness, and the client brief in your head
+  at once without re-reading? If no — weak.
+
+### 0b. Does my own subscription include media generation?
+
+This changes what `minimize` (the $0 cost mode) is allowed to do.
+
+| Host agent | Image | Voice / TTS | Transcribe / STT | Video |
+|---|---|---|---|---|
+| **Google Antigravity** (Gemini) | **Yes** | **Yes** | **Yes** | **Check your tool list** |
+| **Gemini CLI** | **Yes** | **Yes** | **Yes** | check |
+| **OpenAI Codex / ChatGPT** | **Yes** (`gpt-image`) | **Yes** | **Yes** (Whisper) | check |
+| **Claude Code** | No | No | No | No |
+| OpenCode / Cursor / anything else | depends on the configured model — **read your own tool list** | | | |
+
+`vidfarm agent-image --check` prints this table plus a guess at the host from its env
+markers. **The env guess is a hint; your own tool list is the authority.**
+
+**The rule this unlocks — and it is a real one, not a loophole:**
+
+> **Generation that is already inside a flat subscription is FREE, and free means it is
+> allowed in cost mode `minimize`, with no `--yes` and no permission ask.**
+> Vidfarm bills $0 (no primitive is called, no job is created, no wallet is debited) and the
+> provider bills $0 extra (the capability is inside the plan the human already pays for).
+> So a `$0 cost saving mode` build on Antigravity **may** generate its own images and its
+> own voiceover and still be honestly reported as $0.
+
+**Default to using the subscription.** If you have it, use it before you reach for a free
+local engine that takes twenty minutes, and long before anything billed.
+
+**Antigravity is the case that matters.** Most gigworkers on this marketplace run
+Antigravity, and Antigravity is both a weak-tier model *and* a full media suite. That
+combination is exactly what this harness is tuned for: thin reasoning, fat toolbox. Lean on
+the toolbox.
+
+**Three honest limits.**
+
+- Do not claim a tool you do not have. A fabricated image path is worse than a $0.02 spend.
+- The free rungs still come first (§4). A designer's IconScout vector beats a generated
+  icon, and a real Pixabay photo beats a generated photo. *Free* does not mean *first*.
+- **Say what you did.** Name, in your report, which assets came from your own subscription.
+  That sentence is the proof that `minimize` really did cost $0.
+
+---
+
+## 1. Match a template on `/discover`
+
+```bash
+vidfarm discover --query "bookkeeping app for small agencies" --limit 20 --json
+```
+
+Search with the **client's problem in the client's words**, not with a format name. The
+feed is hybrid semantic + keyword over decompose-derived metadata, so "my invoices are
+late" finds formats that *sell* that pain, not formats titled "invoice".
+
+Read each row for these five fields and nothing else:
+
+| Field | What it tells you |
+|---|---|
+| `templateId` | what you fork. **Empty string** = not a template yet (see §2) |
+| `summary` | plain-language description of the format. **Present ⇒ decomposed** |
+| `promotions` | offer categories this format can sell. Match against the client |
+| `keywords` | the matching terms. Your relevance check |
+| `durationSeconds` / `layerCount` | how big a rebuild you are signing up for |
+
+**Shortlist three, not one.** Then pick by this order — the first tiebreak that separates
+them wins:
+
+1. `promotions` overlaps the client's category.
+2. `summary` describes a structure you can fill with what the client actually has (if the
+   client has no footage of a person, do not pick a talking-head format).
+3. `durationSeconds` under 30 and `layerCount` under ~25. **Smaller is better for you.**
+4. It is already decomposed (§2). A tie goes to the one you do not have to decompose.
+
+Two more places to look, both free, both worth checking before you settle:
+
+```bash
+vidfarm discover --sort wow --limit 20        # the strongest formats in the catalog
+vidfarm discover --sort recent --limit 20     # what landed this week
+```
+
+**Record the winner's `template_id` in `STORYBOARD.md` under `source_template`.** You will
+cite it in your report and, on the marketplace, in the proof's `private_note`.
+
+---
+
+## 2. Make sure it is decomposed
+
+Fork it. Forking is free.
+
+```bash
+vidfarm fork <template_id>          # → forkId
+vidfarm pull <forkId> --dir ./work  # composition.html + .harness/ to disk
+```
+
+Now check what actually came down:
+
+```bash
+ls ./work/.harness/          # context.json present ⇒ you have the decomposition
+```
+
+| What you see | State | Do this |
+|---|---|---|
+| `.harness/context.json` exists, with `viral_dna` populated | **decomposed** | Go to §3. Nothing to pay, nothing to run. |
+| the fork is one `<video>` layer and `.harness/context.json` is thin or absent | **not decomposed** | Decompose it (below) |
+| the `/discover` row had `templateId: ""` and an `inspirationId` | **an inspiration, not a template yet** | `vidfarm inspiration-decompose <inspirationId>` mints the template, then fork that |
+
+**Decomposing, by tier:**
+
+```bash
+# PAID plan — the cloud decompose. One call, ~30-60s, ~$0.10, the licensed method.
+vidfarm decompose <forkId>
+
+# FREE tier / local devcli — decompose on your OWN tokens, $0.
+vidfarm decompose <forkId> --local --dir ./work
+#   → stages HARNESS.md (the guide), a task file, and smart-decompose.template.json
+#   → you watch the source, fill smart-decompose.json, and that is your decomposition
+#   (paid accounts can then `--sync` it back so the whole network reuses it free)
+```
+
+**Weak models: prefer a template that is ALREADY decomposed over one you have to decompose
+yourself.** A free-tier `--local` decompose is a second hard reasoning task stacked on top
+of the build, and it is the step most likely to go wrong. Spend the extra minutes in §1
+finding a decomposed match instead. Re-run `vidfarm discover` with a different phrasing of
+the client's problem before you accept an undecomposed template.
+
+**Never re-decompose a template that is already decomposed.** It costs money and produces a
+worse answer than the crowdsourced one you already have.
+
+---
+
+## 3. Read the DNA and write the plan
+
+```bash
+vidfarm harness derive <forkId> --out ./work/HARNESS.md
+```
+
+That distils the decomposition into one editable file, keyed the same way the decompose
+JSON is. Read these two strands first; the CLI will print one at a time:
+
+```bash
+vidfarm harness show ./work/HARNESS.md --dna viral    # hook / retention / payoff / emotional_punch
+vidfarm harness show ./work/HARNESS.md --dna visual   # cut rhythm, typography, b-roll, transitions
+```
+
+### What each strand decides
+
+| Strand | Answers | You may change it? |
+|---|---|---|
+| **Viral DNA** — hook, retention, payoff, `emotional_punch` | *why it worked* | **The SHAPE stays. The SUBJECT changes.** Rebuild each charge for the client. Never flatten the loop into a product statement. |
+| **Visual DNA** — cut rhythm, caption style/placement, b-roll, transitions | *how it looks and moves* | Keep. This is the cheapest thing to keep and the most expensive thing to get right yourself. |
+| **Structural DNA** — the beats, and which are load-bearing | *the skeleton* | Keep the count and the order. Beats marked critical / `must_keep` are untouchable. |
+| **Audio DNA** — voice, bed, comedic timing | *the delivery* | Keep the timing and the energy. **Replace every word and every track.** See the warning below. |
+| **Build DNA** — which paintbrush per beat | *what each beat is made of* | Keep. It already tells you which beats are clips, which are HTML, which need generation. |
+
+> ### ⚠️ The single most expensive mistake in this harness
+>
+> **Replace the audio.** A fork carries the source brand's voiceover and the source brand's
+> music. It is easy to rewrite all 57 captions, render clean, pass every check — and ship a
+> video narrating **another company's product** over your client's captions. This has
+> happened. It passed every automated gate at the time, because the gates only looked at
+> captions.
+>
+> So before you render, run this and read every row:
+>
+> ```bash
+> vidfarm qa ./work --harness ./HARNESS.md
+> grep -o 'data-src="[^"]*"' ./work/composition.html | sort -u
+> ```
+>
+> **Every audio `data-src` must point at a file YOU put there.** If any audio asset still
+> resolves to the source template's storage, you are not done. Ticking this off from memory
+> does not count — paste the command's output into your report.
+
+### Then write `STORYBOARD.md`
+
+```bash
+vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"
+```
+
+One row per beat from the Structural DNA. Fill, per row:
+
+- `scene` — what the beat shows, in the client's world
+- `duration` — **copy the source beat's duration.** Do not re-time. The rhythm is the DNA.
+- `voiceover` — the new line, written for the client
+- `src` — **which rung of §4 this asset is coming from.** Leave it blank and §4 has no
+  work-list.
+
+A plan is free to redo. A rendered beat is not.
+
+---
+
+## 4. Procure every raw — one pass, before you edit
+
+**This is the half of the job that decides whether the video is good, and it is the half
+weak models skip.** You are not authoring pixels; you are *casting*. Casting is a search
+problem, and search is something you are good at.
+
+Do not open `composition.html` until every `src` cell in `STORYBOARD.md` names a file on
+disk or a durable vidfarm URL.
+
+### The ladder — visuals
+
+Walk it top to bottom. **Stop at the first rung that answers the beat.** Rungs are ordered
+by quality-per-cost, not just cost.
+
+| # | Rung | Command | Cost |
+|---|---|---|---|
+| 1 | **The client's shared folder** — footage, logo, product shots they already handed you | `vidfarm shared ls "$ASSETS_LINK"` · `vidfarm shared search "$ASSETS_LINK" "founder talking head"` · `vidfarm shared get "$ASSETS_LINK" --all --out ./work` | $0 |
+| 2 | **The client's own website** — screenshots, UI states, mascots, spot art, palette, their own words | `vidfarm capture <url>` then `vidfarm mask <image> --crop x,y,w,h` to cut one element into a transparent PNG | $0 |
+| 3 | **The client's vidfarm library** — anything they uploaded before | `vidfarm raws search "<meaning>"` · `vidfarm files` | $0 |
+| 4 | **Public raws** — free, cleared, pre-tagged B-roll shelves | `vidfarm public-raws --categories` first, then `--category greenscreen --limit 20` | $0 |
+| 5 | **Free stock** — Pixabay, Openverse, Iconify | `vidfarm media image "<meaning>"` · `vidfarm media video "<meaning>"` | $0 |
+| 6 | **IconScout** — designer icons, stickers, illustrations, 3D props, Lottie | `vidfarm iconscout "<meaning>" --free` | $0 |
+| 7 | **Your own subscription's image generator** (§0b) | `vidfarm agent-image "<subject>" --items "a,b,c"` → generate with your tool → `vidfarm sticker-pack ./sheet.png --items "a,b,c"` | **$0 — allowed in `minimize`** |
+| 8 | **The human's hands** (interactive mode only) | `vidfarm handoff image` / `vidfarm handoff raws` — they run a free web generator, or pick clips themselves | $0, costs minutes |
+| 9 | **Billed generation** | `vidfarm generate image` / `vidfarm generate video` | $0.01–$0.05 image, more for video. **`minimize` refuses without `--yes`** |
+
+Rung 2 deserves its own note: **if the client gave you a URL, that site is your first asset
+library.** Harvest the *assets* — product screenshots, brand illustrations, mascots, icons,
+the palette, any animated WebP/GIF, and best of all a screen recording in the JS bundle
+(that is A-roll). Never harvest the landing-page *furniture*: no CTA capsules, no feature
+grids, no pricing cards. A video is not a web page.
+
+### The ladder — voiceover
+
+| # | Rung | Command | Cost |
+|---|---|---|---|
+| 1 | **The client's own recording**, if the shared folder has one | `vidfarm shared get …` | $0 |
+| 2 | **Your subscription's TTS** (Antigravity / Gemini CLI / Codex — §0b) | generate the WAV/MP3 with your own tool, then `vidfarm put-file ./vo.mp3` | **$0 — allowed in `minimize`** |
+| 3 | **Local Kokoro** — free, keyless, on-device | `vidfarm tts "<line>" --dir ./work` | $0, but **slow on weak hardware** |
+| 4 | **ElevenLabs** — platform key or the client's own key | `vidfarm tts "<line>" --cloud` | billed |
+
+**On weak hardware, rung 2 beats rung 3.** Local Kokoro on a 4 GB laptop does not fail, it
+just takes twenty minutes and loses the deadline. Both are $0; pick the fast one.
+
+Sample voices before you commit — free on every tier: `vidfarm voices --sample`.
+
+### The ladder — music
+
+1. **The real trending song.** The render is a review artifact; the human re-attaches the
+   same track from the platform's in-app music library at post time, where it is licensed.
+   Pull it with `vidfarm download-audio <post-url>`, keep it on its own `<audio>` layer at
+   its own `data-volume`, and **name the track in your report.**
+2. **Free stock BGM** — `vidfarm media bgm "<vibe>"` (Openverse CC music, keyless).
+3. **Generated** — `vidfarm music "<same vibe, same BPM>"`. Billed; no free local engine.
+
+The exception to rule 1 is a paid ad placement, which the platform music library does not
+cover. Say so once and go to rung 3.
+
+### Before you leave §4
+
+Every `src` cell in `STORYBOARD.md` is filled. Count them. If the count of filled cells is
+less than the count of beats, **you are not finished with §4** — going to §5 now is how a
+$0 video turns into a $3 one, or into a beat you rewrite twice.
+
+---
+
+## 5. Adapt the composition
+
+Now open it. Parse, edit, re-serialize the DOM — **never build composition HTML by string
+concatenation.**
+
+```bash
+vidfarm serve --fork <forkId>   # free local editor + render loop at localhost:3000
+```
+
+### What you are doing, precisely
+
+You are running a **transplant**, beat by beat, down `STORYBOARD.md`. For each beat:
+
+1. Find the source layer (`vidfarm pull` printed the scene/layer keys).
+2. Swap its `data-src` for your procured asset.
+3. Rewrite its text for the client.
+4. **Leave `start` and `duration` alone** unless the Structural DNA says that beat is free.
+
+### Keep vs replace — the line
+
+| Keep — this is the DNA | Replace — this is the dressing |
+|---|---|
+| beat count and beat order | every clip, every image, every sticker |
+| each beat's `start` and `duration` | every caption word |
+| the cut rhythm and the transitions | the palette, if the client has a brand |
+| the caption identity — font, size, placement, background style | the voiceover, every line of it |
+| the hook's *shape* and the payoff's *position* | the music bed |
+| any beat marked critical / `must_keep` | the offer, the handle, the CTA |
+
+### "It is okay to heavily alter it"
+
+Yes. Cut a beat that the client's story does not have. Merge two. Replace a live-action
+beat with a sticker beat because that is what you could procure. **What you may not do is
+alter the *structure* casually** — if you drop a beat, drop it deliberately, and say in
+your report which one and why.
+
+### Overfitting is the goal, not the risk
+
+You will produce something that looks a lot like one specific existing template. **That is
+the correct outcome.** The catalog holds thousands of decomposed templates and the client
+sees one video. The variety lives in the *catalog*, not in your improvisation — so import
+variety by picking a different template next time, never by inventing on top of this one.
+
+### The standards still bind
+
+Everything in `https://vidfarm.cc/skill.md` §6 applies and overrides your defaults. The
+four that weak models break most often:
+
+- **The first frame is the thumbnail.** A real visual and the hook words at `start:0`. No
+  fade-up, no title card, no logo. Check it: `vidfarm stills ./work --at 0`.
+- **No HTML slop.** Could you have made this element inside TikTok's own editor? If you
+  reached past that — a padded capsule, a border, a gradient fill, a blur panel, a card, a
+  CTA "button", a feature grid — cut it. **Nothing in a video is clickable.**
+- **Captions: five fonts only** — TikTok Sans, Montserrat (700–900), Abel, Source Code Pro,
+  Yesteryear. Anything else falls back to a web sans at render and the video looks generic.
+  Specimens: <https://vidfarm.cc/fonts>.
+- **Cut ruthlessly.** First assembly is 30–50% too long.
+
+---
+
+## 6. Render, gate, look
+
+```bash
+vidfarm qa ./work --harness ./HARNESS.md      # free, local, machine-settled checks
+vidfarm render <forkId> --dir ./work          # renders on THIS machine — $0.00
+vidfarm stills ./work --sheet                 # contact sheet → read it as ONE image
+```
+
+**Run the gate as a command. Do not tick it off from memory.** A check you transcribe into
+your report instead of running is not a check, and this is the failure mode weak models hit
+hardest: reporting a pass on the half the CLI never judged.
+
+Three things the CLI cannot judge, which you must answer honestly:
+
+- **Audio provenance.** Paste the `grep` output from §3. Every audio `data-src` is yours.
+- **The contact sheet.** One type scale, one palette, deliberate pacing, clean joins. If
+  two beats look like they came from different videos, they did — fix it.
+- **The first three seconds.** Play only those and stop. A stranger should be able to say
+  what kind of thing this is and roughly who it is for. "Something about audio" is a fail.
+
+If `qa` reports a defect, fix it and re-run. One fix round is normal.
+
+---
+
+## 7. Where this hands off
+
+| You are | Go to |
+|---|---|
+| making a video for your own client / your own brand | `https://vidfarm.cc/skill.md` §6 for the standards, then ship |
+| an **Agentic Clipper** earning on the marketplace | `https://vidfarm.cc/agentic-clipper.md` — the review gate, the watermarked proof, and the clean master in `private_note` |
+| a **buyer** commissioning videos | `https://vidfarm.cc/marketplace-buyer.md` |
+
+**If the task named a `format_harness`, that file still wins over your own judgement.** This
+harness tells you *how to work*; the format harness tells you *what to build*. Read the
+format harness as your **grading rubric** — its `checks:` block, its forbidden text list,
+its safe-zone rules — and get there by the road in §1–§6 rather than by authoring it from
+the prose.
+
+---
+
+## 8. The summary line — print this LAST, filled in
+
+Copy it, fill every field, and put it at the end of your report. A field you cannot fill is
+a step you did not do.
+
+```
+FLASH-HARNESS RESULT
+  model_tier:          weak | strong        (§0a)
+  subscription_media:  image=Y/N tts=Y/N stt=Y/N   (§0b)
+  cost_mode:           minimize | hybrid | rich-ai | pure-videogen
+  source_template:     template_...
+  decomposed_by:       already | cloud | local | inspiration-mint
+  format_harness:      <name or "none — freestyled">
+  beats:               <kept>/<source total>   dropped: <which, and why>
+  assets_by_rung:      shared=<n> website=<n> raws=<n> stock=<n> iconscout=<n> subscription=<n> billed=<n>
+  audio_replaced:      <n>/<n> audio data-src now point at my own files
+  voiceover_source:    client | subscription-tts | kokoro-local | elevenlabs
+  music_source:        trending "<track name>" | stock | generated | none
+  qa:                  <pass count>/<total> from `vidfarm qa`
+  render:              local $0.00 | cloud $<amount>
+  billed_total:        $<amount>
+  i_looked_at:         contact sheet Y/N   first-3-seconds Y/N
+```
+
+---
+
+## Why these rules
+
+Read this section **after** you have followed the contract, not while.
+
+**Why start from a decomposed template (rules 1–5).** Four rounds of work went into making
+small models author vidfarm formats from written descriptions. All four were rejected. The
+finding was not that the models are bad at video — it is that a 300-line prose harness asks
+for a kind of held-in-mind synthesis that is exactly what the small tiers gave up in
+exchange for speed. A decomposition is that synthesis, already done, by a frontier model,
+and paid for by someone else. Taking it is not cheating; it is the product.
+
+**Why the decomposition is worth money.** Decomposing one video into its scene-by-scene
+viral DNA costs $1+ in AI spend if you do it yourself. Vidfarm's library is crowdsourced and
+already decomposed, so you pull that breakdown for $0. That is the single largest saving
+available to you, and it compounds across every video you make.
+
+**Why "procure before you edit" is a rule and not advice (rules 6–8).** Building to a shot
+you assumed existed is the most expensive mistake available: you either pay to generate it
+or you rewrite a beat you already built. Deciding to source mid-build is how a $0 video
+turns into a $3 one.
+
+**Why the ladder is ordered the way it is (rule 8).** It is ordered by *quality per unit
+cost*, not by cost alone. A designer's finished transparent vector from IconScout beats a
+generated icon on both axes. A real photo beats a generated photo. Free does not mean first
+— *best free* means first.
+
+**Why overfitting is fine (rules 9–10).** A weak model's improvisation has a wide variance
+and a low mean. A decomposed template has a narrow variance and a high mean. Across a batch
+of thirty videos the client sees, the template path wins on every percentile that matters —
+and the diversity the client experiences comes from you picking thirty *different*
+templates, which is a search task, not a creative one.
+
+**Why the gate must be run, not remembered (rule 11).** Every previous attempt at this
+produced a report whose checks were green on exactly the axis that attempt was built to
+improve, and silent on the axis that decided the verdict. The audio warning in §3 is the
+canonical example: five videos, 57/57 captions correctly rewritten, every gate green, all
+five narrating another company's product. **A green gate has been weak evidence about a
+video every single time.** Looking at the render is the review that counts.
+
+**Why the summary line is last (rule 12).** A summary printed first gets written from
+intention. A summary printed last gets written from what happened.
+
+---
+
+## The commands, in one block
+
+```bash
+# 0 — who am I
+vidfarm agent-image --check
+vidfarm cost-mode                                     # minimize | hybrid | rich-ai | pure-videogen
+vidfarm mode                                          # interactive | autonomous
+
+# 1 — match
+vidfarm discover --query "<client's problem, their words>" --limit 20 --json
+
+# 2 — fork and make sure it is decomposed
+vidfarm fork <template_id>
+vidfarm pull <forkId> --dir ./work
+vidfarm decompose <forkId>                            # paid, cloud, ~$0.10
+vidfarm decompose <forkId> --local --dir ./work       # free tier, your own tokens, $0
+
+# 3 — plan
+vidfarm harness derive <forkId> --out ./work/HARNESS.md
+vidfarm harness show ./work/HARNESS.md --dna viral
+vidfarm harness show ./work/HARNESS.md --dna visual
+vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"
+
+# 4 — procure (one pass, every beat)
+vidfarm shared ls "$ASSETS_LINK"
+vidfarm capture <client-url>
+vidfarm public-raws --categories
+vidfarm media image "<meaning>"
+vidfarm iconscout "<meaning>" --free
+vidfarm agent-image "<subject>" --items "a,b,c"        # your own subscription, $0
+vidfarm tts "<line>" --dir ./work                      # or your subscription's TTS
+vidfarm download-audio <post-url>                      # the real trending song
+
+# 5-6 — adapt, gate, look
+vidfarm serve --fork <forkId>
+vidfarm qa ./work --harness ./HARNESS.md
+vidfarm render <forkId> --dir ./work
+vidfarm stills ./work --sheet
+vidfarm publish <forkId>
+```

package/experimental/google-news-to-video.md

@@ -1,3 +1,12 @@
+---
+name: google-news-to-video
+video_type: Timely newsjack — a recent real event turned into a short video. Two searches, never one: news-search finds the STORY, video/image-search finds the VISUALS
+# No `checks:` block on purpose. This harness governs the SOURCING method, not one
+# fixed cut, so the shape of the finished video is set by whichever format harness
+# you build it in (short-form, wall-text-pov-ugc, …). Stack them: `--harness
+# google-news-to-video --harness short-form`.
+---
+
 # Google News to Video — reusable prompt & method
 
 Turns **a recent real event → a timely short video**, using two searches instead of one.

package/experimental/unique-product-explainers.md

@@ -1,3 +1,11 @@
+---
+name: unique-product-explainers
+video_type: Bulk product explainers — N customer URLs into N product-introduction videos that do not look like each other. Differentiation as an input, frame-level review, measured verification
+# No `checks:` block on purpose. This harness governs a BATCH and its anti-convergence
+# rules; the per-video shape comes from the format harness each variant is built in.
+# Stack them: `--harness unique-product-explainers --harness product-explainer`.
+---
+
 # Unique Product Explainer Videos — reusable prompt & method
 
 Turns **N customer URLs → N product-introduction videos that do not look like each other**,