@officexapp/vidfarm-devcli 0.21.43 → 0.21.46

package/SKILL.md

@@ -1,152 +1,194 @@
 ---
 name: vidfarm
-description: Thin entry point for agentic video editing with Vidfarm. An AI agent lands here (vidfarm.cc/SKILL.md), learns what Vidfarm is in one screen, and is routed to the full director skill, the devcli, and the HyperFrames authoring suite. Fetch the deeper skill files listed below rather than guessing.
+description: Entry point for making, editing, and rendering short-form video with Vidfarm. Use when the task is to create a video, ad, explainer, or social clip; to edit or re-theme an existing composition; to source footage or audio; or to run a batch of video variants. Routes to the full director skill and the `vidfarm` CLI.
 ---
 
-# Vidfarm — start here
+# Vidfarm — agent entry point
 
-**You are an AI agent that was pointed at `https://vidfarm.cc/SKILL.md` to get your human started with agentic video editing.** This page is deliberately thin. It tells you what Vidfarm is, how to get hands-on in the next two minutes, and exactly which deeper files to fetch. Read this, then pull the full director skill — don't improvise Vidfarm's workflows from this page alone.
+Vidfarm builds video from HTML. You fork a published template, edit it on a timeline, render to MP4, and share. Because the source is a DOM, every edit is deterministic, diffable, re-themeable, and scriptable.
 
-**Do these three things first, before anything else:**
+This page is the router. It holds the setup, one worked example, the standards, and the file index. It does **not** hold the workflows — fetch those from the index at the bottom when a task needs them.
 
-0. **Agree on a working folder.** Ask the user to keep **one folder for all their Vidfarm work**, named after their offer or brand (`./acme-skincare/`; if they have no preference, propose `~/vidfarm/<brand>/` and create it). Run every `vidfarm` command from it, or pass `--dir`. Everything lands there — the strategy documents (`OFFER.md`, `CONTEXT.md`, `ad-hooks.md`, `content-ideas.md`), `STORYBOARD.md`, `brand-assets/`, `raws/`, `renders/` — so a later session, in a new terminal weeks from now, reads the whole history back instead of asking the same questions again. If the folder already exists, **read `CONTEXT.md` and `OFFER.md` before you ask anything.**
-1. **Install the `vidfarm` devcli** — `npm i -g @officexapp/vidfarm-devcli`. It wraps every REST route, runs a free local editor + render loop, and is by far the smoothest way to drive Vidfarm.
-2. **Log in** — `vidfarm login <email>` (one-time email code), or if you already hold a key: `vidfarm login --api-key <key>` / set `VIDFARM_API_KEY` and run `vidfarm login`. This persists the credential so every later command and `vidfarm serve` just work.
+## 1. Setup
 
-Vidfarm is a video composition studio you drive as a **director**. You fork a published template, edit it on a timeline in the Trackpad Editor (Premiere/DaVinci-style), render to MP4, and share. Videos are built from HTML, so every edit is deterministic, re-themeable, and scriptable end-to-end.
+```bash
+npm i -g @officexapp/vidfarm-devcli   # `vidfarm` — wraps every REST route
+npm i -g hyperframes                  # Vidfarm's own render engine (whitelabel; reach it via `vidfarm hf`)
+vidfarm login <email>                 # one-time email code; or --api-key <key>, or VIDFARM_API_KEY
+vidfarm doctor                        # verifies vidfarm + ffmpeg + hyperframes + Chrome
+vidfarm skills add vidfarm            # install the full director skill on disk — do this
+vidfarm serve                         # free local editor + render loop at localhost:3000
+vidfarm browser setup                 # optional: drive the user's own Chrome — FREE footage sourcing
+```
 
-## The one idea that matters: three paintbrushes
+**Image generation you already pay for is free — check before you spend or go without.** If the agent driving this terminal includes image generation in its own subscription (Google Antigravity / Gemini CLI, OpenAI Codex / ChatGPT — **Claude Code does not**, Anthropic ships no image model), generating a graphic bills Vidfarm $0 and the provider $0 extra. That makes it legal in cost mode `minimize`, with no `--yes`. `vidfarm agent-image --check` answers "do I have it here?"; `vidfarm agent-image "<subject>" --items "a,b,c"` prints the prompt, the key-plate rules and the cut + import commands. Free stock and IconScout still come first. Full page: `references/agent-included-imagegen.md`.
 
-Every visual on the timeline is painted with one of three brushes. Reach for them in this order — it is combinatorially cheaper and usually better:
+**`vidfarm browser setup` is the one optional install worth offering unprompted.** It installs [browser-harness](https://github.com/browser-use/browser-harness), which attaches you to the user's running Chrome over CDP. That makes `vidfarm browse videos|images|news|page "<query>"` a **$0 substitute for the paid `video-search` / `image-search` / `news-search` / `download-video` primitives** — the routes a free-plan user otherwise hits a 402 on. Offer it to every free-plan user and everyone in cost mode `minimize`, ask before installing (it drives their personal browser), and read `references/browser-harness.md` before the first browse.
 
-1. **Raw clips** — cut/remix existing footage. Cheapest; the workhorse. Check the **public raws catalog by category** before you hunt or generate anything: `vidfarm public-raws --categories` lists free, pre-tagged shelves (scroll-stoppers, greenscreen, reaction, b-roll, …) with live counts, and `--category <shelf>` pulls one. A shelf is also a ready-made clip pool for **bulk scripting** — fan one composition into N variants without a single download or generation call. Then your own library, then hunted from a URL/VOD.
-2. **HTML/JS hyperframes** — video-from-HTML: CSS/GSAP/anime.js motion, animated text + image elements, data-viz. Cheap, deterministic, infinitely re-skinnable.
-3. **Pure AI generation** — AI image/video/voice/music. Most expensive (AI *video* especially). Use last, only where the first two genuinely can't cover the beat.
+**Do not install ffmpeg first.** The devcli bundles `ffmpeg-static` and a per-platform
+ffprobe, so ffmpeg is already there on macOS, Linux, and Windows x64. Run `vidfarm doctor`
+and install a system ffmpeg **only if it reports ffmpeg missing** (`brew install ffmpeg`,
+`apt install ffmpeg`, `winget install Gyan.FFmpeg`).
 
-Default to the cheapest approach that works, and surface cost before any expensive generation. This is founder-friendly by design — a capable coding agent can replicate a template on the **free tier**, no wallet required.
+**Windows** — the two things worth knowing before the first install:
 
-## Save the user money — ask their cost mode first
+- Use **PowerShell**, not Git Bash or cmd. Node >= 22 is required (`winget install OpenJS.NodeJS.LTS`).
+- If the install is slow, exclude the npm folders from Defender's real-time scan. It scans
+  every extracted file, which dominates first-run setup time:
+  ```powershell
+  Add-MpPreference -ExclusionPath "$env:APPDATA\npm", "$env:APPDATA\npm-cache", "$env:LOCALAPPDATA\npm-cache"
+  ```
+- `better-sqlite3` is an **optional** native module. If it fails to build, that is not a broken
+  install — only `vidfarm clips` (the local clip library) is unavailable. Everything else,
+  including local render, works. To enable it, install "Desktop development with C++" from
+  the Visual Studio Installer and reinstall.
+- Windows on ARM has no prebuilt ffmpeg/ffprobe. Install a system ffmpeg and put it on PATH.
 
-Before spending any AI credits, ask which posture they want and **quote the per-video cost**:
+Work in **one folder per brand or offer** (`~/vidfarm/<brand>/`). Run every command from it, or pass `--dir`. Strategy documents, `STORYBOARD.md`, `brand-assets/`, `raws/` and `renders/` all land there, so a session weeks later reads the history back instead of re-interviewing the user.
 
-| Mode | Cost per video | What it means |
-|---|---|---|
-| **minimize** | **$0 — explicitly free** | free local compute + free stock media; no AI spend at all |
-| **hybrid** *(recommended)* | **~$0.01–$1** | free where free, pay AI only where it clearly wins |
-| **rich-ai** | **$1+** | AI video gen buys **reusable greenscreen raws** — keyed once, animated/remixed in hyperframes HTML/CSS, then **saved to the library** so later videos reuse them for ~$0 |
-| **pure-videogen** | **$5+** | every shot is generated: text script → image storyboard → frame-by-frame scene generation. No reuse, no HTML motion |
+**If that folder already exists, read `CONTEXT.md` and `OFFER.md` before you ask the user anything.**
 
-The last two are production *methods*, not just budgets. **rich-ai**: generate the cast and props on greenscreen (`vidfarm avatar "<who>" --say "<line>"`, `vidfarm create-overlay "<subject>"`, or `generate video` on a flat key-color plate), key them, animate in HTML over your other raws, and **persist every asset** (`vidfarm put-file … --folder greenscreen/<name> --notes "…"` or `vidfarm clipper … --folder <name>` for `/raws`) — local under `~/.vidfarm` by default, and mirrored to the cloud with `vidfarm sync push /files` + `sync push /raws` on a paid/Pro plan. Search `vidfarm raws search` and `vidfarm public-raws --category greenscreen` before generating anything. **pure-videogen**: approve the script in text and the look as storyboard stills (cheap `generate image`, `--ref` for character lock) *before* generating any footage, then generate scene by scene off those keyframes (chaining each scene's last frame into the next for continuity) — and quote the number first, since it's ~5× rich-ai.
+No CLI? The REST API covers the same surface. Auth header is `vidfarm-api-key`. Loop is fork → `PUT composition.html` → `render` → poll. Map: `references/rest-api.md`.
 
-**Those charges go to the user's own AI provider keys (BYOK)** — saved via `vidfarm add-provider-key <provider> <key>` or **Settings → Bring your own keys** (<https://vidfarm.cc/settings/developer>). The providers bill those keys directly; Vidfarm wallet credits only apply when the user deliberately runs on the platform key. That's why `minimize` is genuinely $0, not just cheap. With the devcli, persist it via `vidfarm cost-mode <choice>` (billed commands then respect it; `minimize` refuses billed ops without `--yes`). **Narration follows the mode automatically**: in `minimize` and `hybrid`, plain `vidfarm tts "…"` uses the free local Kokoro voice — ask for a premium voice explicitly (`--style`/`--voice`/`--provider`/`--cloud`) when the piece needs one, and tell the user which tier they're hearing. Then ask if they want it remembered across sessions — save to the agent's own memory (Claude Code → `CLAUDE.md`; Codex/OpenCode/others → `AGENTS.md`; or a note they name), asking first. In the **web app UI** there's no memory file to write, so just ask each time unless they state a standing preference. Full guidance is in the director skill.
+## 2. The core model: three paintbrushes
 
-**Even in `minimize`, you can still get custom images — for free, manually.** When stock and masking existing art won't cover a bespoke graphic, don't say "not possible" and don't quietly spend: ask the user once whether to **default to free manual image generation**, then write the prompt and have them run it in <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space, and hand the PNG back (`vidfarm put-file`, or drag into My Files). Ask for **one image containing every graphic you need**, gridded on a **flat chroma plate** with no text (`#00FF00` green by default — but pick a different plate when the art itself is green, or the key will punch holes through it) — one round trip instead of many, which is the token-efficient move. Then split it locally at $0 in one command: `vidfarm sticker-pack ./sheet.png --items "a,b,c" --out-dir ./stickers` keys the green out, finds each item in the sheet automatically, and writes a snug transparent sticker per item. Prompt template + full loop in the director skill.
+Every visual on the timeline comes from one of three sources. Try them in this order — it is cheaper and usually better.
 
-**"Make me a sticker pack" = one greenscreen sheet, then masked apart.** A pack is a *set* that has to share one art style, so never generate the items one by one — generate a single image holding all of them on a flat `#00FF00` plate, then split it: `vidfarm sticker-pack --generate "<theme>" --items "a,b,c,d"` (one billed image job for the whole set, then free local keying + automatic alpha segmentation + per-item trim + a `stickers.json` manifest). **The key is connectivity-based, so the art is far freer than a chroma key implies:** the plate is flood-filled inward from the sheet's edge and only background that *reaches* the edge is removed, so plate-colored detail inside an item and hollow/outline shapes survive, and the plate is un-mixed out of each edge pixel individually (no green fringe). What still matters is the **silhouette** — an item's outer edge must differ from its plate and must be crisp (nothing glowing/blurring/shadowing into the background) — plus clear gaps between items. **And you can give every sticker its OWN plate color:** `--sheet-mode zoned` asks for a grid of solid color *panels*, one item per panel, each panel's plate picked against that item (a green frog on magenta beside a pink flower on green), keyed panel-by-panel, with names pinned to panels instead of guessed from reading order. It's the default for 2+ named items; `--sheet-mode flat` (or a model that just ignores the grid — detected automatically, re-keyed as one plate) falls back to the classic single-color sheet. `--key-mode flat` restores the plain chromakey, and `--refine` re-cuts each item with local ONNX matting for painterly/soft/furry art. Stickers are **not necessarily small** — a full-frame landscape or backdrop is as valid an item as an icon — and they're normally **animated on the canvas** (`vidfarm place` + `vidfarm keyframes` presets: pop-in, float, shake, grow, slide-in, drift). A sticker whose own art moves is a **transparent WebM** (`vidfarm remove-greenscreen <video>`), and for GIF-only surfaces both paths can emit **transparent GIFs** (`sticker-pack --output-format gif`, `remove-greenscreen --gif`, 1-bit alpha). Full recipe in the director skill.
+1. **Raw clips** — cut and remix existing footage. Cheapest, and the workhorse. Check `vidfarm public-raws --categories` (free pre-tagged shelves) before hunting or generating anything.
+2. **HTML/JS hyperframes** — motion from CSS/GSAP/anime.js, animated text, image elements, data-viz. Cheap, deterministic, infinitely re-skinnable.
+3. **AI generation** — image, video, voice, music. Most expensive, AI *video* especially. Use only where the first two genuinely cannot cover the beat.
 
-## Ask the second question too — interactive or autonomous?
+A capable agent can replicate a template entirely on brush 1 and 2, on the free tier, with no wallet.
 
-Cost mode says how much MONEY to spend. It doesn't say how much of the user's own HANDS you may use — and that moves quality more. **Ask both, up front**, and persist the answer with `vidfarm mode interactive|autonomous` (the twin of `vidfarm cost-mode`). The axes are independent: every cost mode runs either way.
+## 3. Worked example — one video, end to end
 
-- **interactive** — at checkpoints you hand the user a copy-paste brief and they hand files back: an **image prompt** they run in a *free* frontier web generator (meta.ai / ChatGPT / Gemini / a HF Space), or a **keyword list** they use to search TikTok/YouTube and download clips with a free downloader. Costs them a few minutes; the free web models usually beat what an API budget buys, and a human eye picks better footage than a keyword scan. The third checkpoint is the cheapest: **let them pick the voice** — `vidfarm voices --sample` (premium) or `vidfarm voices --free --sample` ($0 local) writes listenable clips to `./voice-samples`, **free on both tiers**, so offer it in `minimize` exactly as readily as in `hybrid`.
-- **autonomous** — you finish end-to-end with zero steps from them: source clips yourself (browser control → `vidfarm clipper`/`raws scan` → public raws), generate within budget, or do without.
+```bash
+vidfarm ideas --topic "cold email tool for agencies"     # free, offline → content-ideas.md
+vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"   # plan first — free to redo
+vidfarm templates search "ugc testimonial"               # find a published template
+vidfarm fork <templateId>                                # → forkId
+vidfarm pull <forkId> --dir ./work                       # composition.html + .harness/ to disk
+vidfarm public-raws --category greenscreen --limit 20    # source footage, $0
+# edit ./work/composition.html — parse, edit, re-serialize the DOM; never string-concat
+vidfarm tts "Your cold emails are landing in spam." --dir ./work    # free local voice
+vidfarm qa ./work                                        # optional free local slop check
+vidfarm render <forkId> --dir ./work                     # renders on THIS machine — $0.00
+vidfarm stills ./work --sheet                            # contact sheet → review as one image
+vidfarm publish <forkId>                                 # push edits back to the cloud
+```
 
-**Premium voices don't need an ElevenLabs account.** Vidfarm carries its own ElevenLabs connection, so the full premium catalog is available to any user for **vidfarm wallet credits** (pennies per narration) — no signup, no API key, no subscription. Put that on the table when you offer voices instead of letting the user assume premium narration is a door they have to unlock elsewhere; `--own-key` is only for people who already have a key and want to bill their own account.
+**Plan before you build.** `STORYBOARD.md` is part of the composition format, not a scratch file: ordered frames with `duration`, `status`, `src`, `scene`, `voiceover`. The Vidfarm editor renders it as a Storyboard view with a contact sheet and per-frame comments, so it is the cheapest place to get approval. A plan is free to redo; a rendered scene is not.
 
-`minimize + interactive` is the sweet spot: **$0 videos that still get custom art.** `minimize + autonomous` means no custom art at all — say so before defaulting to it. Mint the briefs with `vidfarm handoff image --theme "<what>" --items "a,b,c"` (defaults to a sticker pack) and `vidfarm handoff raws --keywords "<kw>,<kw>"` (only after browser control and cloud scan are ruled out).
+`vidfarm render <forkId> --target cloud` is the explicit billed cloud render (~$0.01–$0.10). Everything above without `--target cloud` runs locally and free.
 
-**Storyboard before you build.** The plan lives with the project as `STORYBOARD.md` (ordered frames: `duration`, `status`, `src`, `scene`, `voiceover`) plus an optional `SCRIPT.md`, and the Vidfarm editor renders it — a Storyboard view with a contact sheet, per-frame comments, and `outline → built → animated` progress. Draft it with `vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"`, read it with `vidfarm storyboard ./work`, and get approval there: a plan is free to redo, a rendered scene is not.
+## 4. Router
 
-## Get hands-on now — pick your surface
+| The user asks for | Do | Read |
+|---|---|---|
+| "Help me figure out what to make" | `vidfarm ideas --grid --topic "<offer>" --count 30` first — the list beats an interview | `references/onboarding.md` |
+| "Give me a consultation" | the `brainstorm/*` chain: cold-start → awareness stages → angles → hooks. No AI key: `vidfarm consult` prints the prompt for **you** to answer, $0 | `references/onboarding.md` |
+| "Find a template and start" | `vidfarm templates search` → `fork` → `pull` | `references/core-workflows.md`, `recipes/find-and-fork-template.md` |
+| "Change / re-theme this video" | timeline edits, decompose, captions | `references/editor-workflows.md`, `recipes/retheme-template.md` |
+| "Find footage / a clip of X" | public raws → own library → `vidfarm browse videos "<the shot>"` (free, your Chrome) or `vidfarm video-search` (paid, $0.0003/call) → generate last | `references/assets-and-sourcing.md` |
+| "Make a graphic / sticker / illustration" in cost mode `minimize` | free stock → IconScout → `vidfarm mask` → **generate it with YOUR OWN image tool if this subscription includes one** (Antigravity / Gemini CLI, Codex / ChatGPT — Claude Code has none): `vidfarm agent-image "<subject>"`. $0, and no `--yes` needed | `references/agent-included-imagegen.md` |
+| A free plan / a 402 / cost mode `minimize` on any search or download | `vidfarm browser setup`, then `vidfarm browse videos\|images\|news\|page "<q>"`. Never answer a sourcing ask with "that needs a paid plan." | `references/browser-harness.md` |
+| "Make a video about what just happened" | two stages: `vidfarm news-search "<topic>" --fresh w` for the STORY, then `video-search` for the VISUALS | `vidfarm.cc/experimental/google-news-to-video.md` |
+| "Download this video from `<url>`" | `vidfarm download-video <url>` (paid). Free plan gets a 402 — `vidfarm browse page "<url>"` and save it from their Chrome yourself, else have them download it, then `vidfarm put-file`. Never answer "I can't." | `references/browser-harness.md` |
+| "Turn this thread / subreddit / profile into a video" | `vidfarm recycle <source>` — returns the raw decomposition, unranked; you pick the hook (paid) | `references/assets-and-sourcing.md` |
+| "Create an avatar / spokesperson / talking head" | `vidfarm avatar "<who>" --say "<line>"` — a greenscreen talking-head video, keyed in the same job | `references/primitives.md` |
+| "TTS / music / captions / background removal" | the primitive catalog | `references/primitives.md` |
+| "Sticker pack" / cutout-art explainer | one greenscreen sheet holding every item, then split it: `vidfarm sticker-pack --generate "<theme>" --items "a,b,c"`. Never generate items one at a time. | `recipes/cutout-graphics-for-explainers.md` |
+| "Post this again / to several accounts" | `vidfarm dedupe <mp4> --variants N` on the **exported file** — free, local, no re-render | `references/core-workflows.md` |
+| Anything with the word "harness" | a named process, not a metaphor. `vidfarm harness derive <forkId>` for "the harness for this template_id" | `harnesses/README.md` |
+| "Script / batch / 50 variants" | scripting mode: a pinned base fork, a loop varying ONE thing, plus a `HARNESS.md` | `references/automation-and-local-dev.md`, `recipes/bulk-scripting-with-a-harness.md` |
+| "Which ad wins?" / "test these angles" | capacity → epochs/rounds → creative vs structured → `EXPERIMENTS_DIARY.md`. Do not improvise a testing plan. | `vidfarm.cc/experiments.md` |
+| "Update / upgrade vidfarm" — or any 404 on a documented route | update the skill pack and the devcli **together** | `vidfarm.cc/update.md` |
+
+## 5. Two questions to ask before you spend
+
+Ask both once, early, then persist them. They are independent axes.
+
+**Cost mode** — `vidfarm cost-mode <choice>`. Billed commands respect it; `minimize` refuses billed operations without `--yes`.
+
+| Mode | Per video | Method |
+|---|---|---|
+| `minimize` | $0 | free local compute + free stock media only |
+| `hybrid` *(default)* | ~$0.01–$1 | free where free, pay AI only where it clearly wins |
+| `rich-ai` | $1+ | generate reusable greenscreen assets, key them, animate in HTML, save to the library for later reuse |
+| `pure-videogen` | $5+ | script → storyboard stills → scene-by-scene generation. No reuse |
 
-**Local coding agent (recommended for real work — Claude Code / Codex / any agent with a shell):**
+AI charges go to the user's own provider keys (`vidfarm add-provider-key`), not to Vidfarm credits, unless they deliberately run on the platform key.
 
-```bash
-npm i -g @officexapp/vidfarm-devcli   # the `vidfarm` command wraps every REST route
-npm i -g hyperframes                  # Vidfarm's open-source render/animation engine (whitelabel)
-brew install ffmpeg                   # or apt install ffmpeg — the media engine (a system ffmpeg is honored; ffmpeg-static is bundled)
-vidfarm login <email>                # or: vidfarm login --api-key <key> (also honors VIDFARM_API_KEY)
-vidfarm doctor                        # verify the trio (vidfarm + ffmpeg + hyperframes) + Chrome
-vidfarm serve                        # free local editor + render loop at http://localhost:3000
-vidfarm skills add vidfarm  # install the full director skill locally
-```
+**Hands mode** — `vidfarm mode interactive|autonomous`.
+
+- `interactive` — at checkpoints you hand over a copy-paste brief and they hand a file back: an image prompt they run in a free web generator, or a keyword list for footage. Mint them with `vidfarm handoff image` / `vidfarm handoff raws`. Costs minutes, usually beats what an API budget buys.
+- `autonomous` — you finish end to end with zero steps from them.
+
+Two consequences worth stating out loud: `minimize + interactive` still gets custom art, for $0. `minimize + autonomous` gets none. Voice samples (`vidfarm voices --sample`, `--free --sample`) are free on both tiers — offer them either way.
+
+## 5b. Production has phases — plan, collect, build
+
+**Do not open the timeline before you know what footage you have.** Building to a shot you assumed existed is the most expensive mistake available: you either pay to generate it or rewrite a beat you already built. Four phases, in order — plan the shot list (`vidfarm storyboard --init`), collect assets for **every** beat in one pass, build, then review and cut.
+
+The collection phase is where the cost mode actually bites:
+
+- **`minimize`** — collection *is* the job, and being cheap is not being worse. Work the ladder: `public-raws --categories` → `media search` / `iconscout --free` → `raws search` (what they already own) → **browser control** (`vidfarm browse videos "<the shot>"`, $0) → mine it with `raws scan` / `clipper`. One long source cut eight ways beats one generated clip.
+- **`minimize` + `interactive`** — buy quality with the user's hands, not their wallet. Direct them like an editor: hand over the shot list and let them pick clips themselves (`vidfarm handoff raws`), and hand over ONE prompt for a free web image generator to get a whole sticker sheet back (`vidfarm handoff image` → `vidfarm sticker-pack`). Both beat anything autonomous, at $0.
+- **`hybrid`** — collect free first, then spend on the gaps only. AI image generation for the hero graphic, `vidfarm avatar` for a presenter; keep AI *video* for beats nothing static can carry.
+- **`rich-ai` / `pure-videogen`** — collection becomes generation, and moves earlier. `rich-ai` mints reusable greenscreen raws that get keyed once and saved to the library; `pure-videogen` runs script → storyboard stills → scene-by-scene (`vidfarm sequence`). Even here, search what already exists before generating it.
+
+Say the phase out loud when you switch. Deciding to source mid-build is how a $0 video turns into a $3 one.
+
+## 6. Standards — these override your defaults
+
+The standards themselves are not optional. `vidfarm qa <dir>` is — it is a free local checker for most of them, feedback rather than a gate. Nothing calls it, skipping it is fine, and it allows one fix round by default. **Watching the render is the review that counts.** Full reasoning: `references/hooks-and-virality.md` and `references/reviewing-renders.md`.
 
-**Local Vidfarm is a trio — install and use all three together:** the **`vidfarm`** devcli (orchestrator), **`ffmpeg`** (media engine it shells out to for greenscreen/demux/clips/stills — a hard requirement), and **`hyperframes`** — *Vidfarm's own render/animation engine, open-source under a whitelabel.* **Vidfarm renders ARE hyperframes renders**, so adopt it as part of Vidfarm's toolchain (reach it via `vidfarm hf <args…>`); using it locally is using Vidfarm, not going around it. Never point it at an external vendor account.
+- **Write the four charges before the timeline.** Hook: first line is a complete clause naming a situation, on screen at `start:0`. Loop: one open question by 0:10, closing inside this video. Payoff: shown, not summarized. Bait: one ask, final beat. Banned openers — throat-clearing, a logo, a title card, a fade from black.
+- **No HTML slop.** Test: could you have made this element inside TikTok's own editor? If you reached past that — a padded capsule, border, gradient fill, blur panel, card, CTA "button", benefit chips, feature grid — cut it. Nothing in a video is clickable. Emphasize with size, weight, caps, an accent colour, or a drawn mark.
+- **No layout templates — judge the whole frame.** The stack is the tell, not the box: headline + subheadline + CTA centred in a well is a landing page even with every border, fill and capsule stripped off. Banned at frame level — a modal/dialog floating over a dimmed or blurred backdrop, a full-frame wash used to stage a floating block, nav/hero/feature-row sections, a blurred website screenshot as the background plate, document margins. Unstack it into time: hook at t=0, support line on the next cut, CTA spoken or a bare caption. Are you arranging words relative to each other, or relative to the picture? Two text runs at once is the ceiling.
+- **Captions**: imported display font (Montserrat 700–900 default), ~36–64px on a 1080 frame, inside the 8%–85% safe zone, and within that band placed in the **emptiest part of the frame**. Long narration pages into 3–5-word cues. Exactly one of four backgrounds: `outline`, `plain`, active-word `spotlight`/`karaoke`, or a tight `highlight-solid` band.
+- **The first frame is the thumbnail.** A real visual and the hook words at `start:0`. No fade-up, no entrance transition on the first clip. Check with `vidfarm stills <dir> --at 0`.
+- **Cut ruthlessly.** First assembly is 30–50% too long. Delete every beat that the video survives without, then ripple the hole closed. Length is an output, not a target.
+- **Review the whole video, never one frame.** Tile ~12 stills with `vidfarm stills <dir> --sheet` and read it as an image — one type scale, one palette, deliberate pacing, clean joins. Verify audio by measurement (~12–15 dB speech-over-bed, peak <0 dBFS). Report what you measured separately from what you judged. Your own "looks good" is the least reliable signal here.
+- **Use the real trending song.** The render is a review artifact; the user 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. Exception: a paid ad placement is not covered — say so once and offer `vidfarm music "<same vibe, same BPM>"`.
+- **Ask about deduplication before the render, not after.** "Is this going out more than once?" Answering early keeps it at render once → dedupe N.
 
-`vidfarm serve` runs a local, free edit/render loop (data mirrors `https://vidfarm.cc` when logged in; the editor's Render button and `vidfarm render <forkId>` both render **on this machine via the bundled hyperframes engine — $0.00**). `vidfarm render <forkId> --target cloud` is the explicit, billed cloud render (~$0.01–$0.10). `vidfarm pull <forkId>` writes a composition + its `.harness/` grounding bundle to disk so you can edit, `vidfarm render <forkId> --dir <dir>` free locally, and `vidfarm publish` back. When a timeline reuses windows of one long source, render prep downloads it once and cuts the segments — don't pre-slice by hand. Anything else hyperframes can do locally is exposed via `vidfarm hyperframes <args…>` (alias `vidfarm hf`).
+## 7. Hard constraints
 
-**Cloud REST (any HTTP client, no CLI):** auth with the `vidfarm-api-key` header (never `Authorization: Bearer`). The headless loop is fork → `PUT composition.html` → `render` → poll. Full route map is in the director skill below.
+- Auth header is `vidfarm-api-key`. Not `Authorization: Bearer`.
+- Never build composition HTML by string concatenation. Parse, edit, re-serialize the DOM.
+- Render only through `POST /api/v1/compositions/:forkId/render`. Never call the renderer directly.
+- Submissions are **not** idempotent. Every render and primitive POST charges again — check status before retrying.
+- In the web editor, CSS/declarative motion only; JS animation adapters are stripped on save. Locally via `vidfarm serve`, the full adapters work.
+- Treat `forkId` as an unguessable bearer token. Never put provider secrets in composition HTML or JSON.
 
-## Fetch the real knowledge (do this next)
+## 8. Deeper knowledge — fetch on demand
 
-This page does not contain the workflows. **If the devcli is installed, you already have all of it on disk** — a full copy of the pack ships in the npm tarball, pinned to that CLI version:
+If the devcli is installed, the whole pack is already on disk, pinned to that CLI version — no network, no account:
 
 ```bash
-vidfarm skill ls                   # every file, with sizes
-vidfarm skill search "greenscreen" # grep all of it — find the paragraph, then open that file
-vidfarm skill show primitives      # shorthand or an exact path
+vidfarm skill ls                    # every file with sizes
+vidfarm skill search "greenscreen"  # grep it all, then open the file it names
+vidfarm skill show primitives       # shorthand or exact path
 ```
 
-No account, no network. It is documentation, not entitlement — the free-local half (clips, hyperframes, `serve` render, `qa`, harnesses, `dedupe`, local TTS/STT) runs offline; AI generation, hosted render, `recycle`, `download-video` and marketplace still need `vidfarm login` and a cloud call.
-
-Otherwise, pull it over the network and load only the reference you need:
-
-- **Full director skill (rollup):** `https://vidfarm.cc/skill/vidfarm`
-- **Individual files** (load on demand, not all at once) — `https://vidfarm.cc/skill-pack/vidfarm/files/<path>`. **Any path in the pack works**, not just `references/`; the full index with sizes and "read it when" lives in the rollup's *File Index* section. The whole inventory:
-  - `references/core-workflows.md` — discovery, auth, fork/publish/share, cost spectrum, dedupe-before-publish
-  - `references/editor-workflows.md` — timeline editing, decompose, captions, the three paintbrushes & two replication harnesses *(the biggest read)*
-  - `references/assets-and-sourcing.md` — raws hunts, My Files, recurring characters, downloading media off a URL
-  - `references/automation-and-local-dev.md` — REST + `vidfarm` devcli command table + scripting mode + local serve loop
-  - `references/hooks-and-virality.md` — **the four charges. Read before writing any hook, caption script, or re-theme**
-  - `references/reviewing-renders.md` — **the holistic pass. Read before reporting a video as done**
-  - `references/onboarding.md` — "help me figure out what to make" interview, and the **consultation** flow
-  - `references/primitives.md` — TTS, STT, music, avatars, overlays, background removal, product placement
-  - `references/rest-api.md` — complete REST map (load only for direct HTTP integration)
-  - `recipes/` — `find-and-fork-template.md` · `retheme-template.md` · `local-edit-render-approve.md` · `onboard-a-new-director.md` · `bulk-scripting-with-a-harness.md` (volume/N-variant work) · `cutout-graphics-for-explainers.md` (sticker-art explainers)
-  - `harnesses/` — `README.md` (**start here for anything harness-shaped**: the three director phrasings, the format, the DNA strands) plus the bundled bases `short-form` · `hooks` · `ugc-testimonial` · `explainer` · `product-demo`, each as `<name>.HARNESS.md`
-- **Running ad experiments (finding the winning ad):** `https://vidfarm.cc/experiments.md` — **fetch this whenever the ask is about performance rather than one video**: "which ad should I run", "test these angles", "what's working", "we post daily on N channels", or any campaign that runs for weeks. It primes you as a short-form ad scientist: the KPI interview (default north star = **comments**), channel count → testing capacity, **epochs** and **rounds**, **Creative Mode** (N free-form videos, the default, ideal for gigworkers) vs **Structured Mode** (one variable, everything else pinned by a harness, your own agents only), the composition params, and the standalone `EXPERIMENTS_DIARY.md` ledger. Plan → user approval → one static handoff document per video.
-- **Crowdsourcing the editing:** `https://vidfarm.cc/crowdsourcing.md` — the client-vs-gigworker router for agentic clipper loops (a Dollar Platoon vending machine, recruiting editors, claiming tasks, proofs and payouts). This is how a Creative Mode batch gets produced in bulk.
-- **Updating Vidfarm:** `https://vidfarm.cc/update.md` — **fetch this file whenever the user asks to update/upgrade Vidfarm**, says their skill or devcli is out of date, or hits a command/route that "used to work". It's the clean uninstall→reinstall runbook for BOTH halves (the `vidfarm` skill pack and `@officexapp/vidfarm-devcli`), and it carries the current breaking-change notes — read it live rather than improvising an `npm i -g`, because the notes are exactly what a blind reinstall misses.
-- **Experimental prompts (index):** `https://vidfarm.cc/experimental` — methods under live testing. They are **not** part of the router and nothing above depends on them: read one only when the user asks for experimental prompts, or names one. Current list:
-  - **Unique Product Explainer Videos** — `https://vidfarm.cc/experimental/unique-product-explainers.md` — N customer URLs → N product-introduction videos that do not look like each other. Differentiation as an input, frame-level review, measured verification.
-- **Skill pack index (what else is installable):** `https://vidfarm.cc/skill-pack/index.json`
-- **Platform architecture (how it all fits together):** `https://vidfarm.cc/skill/vidfarm-platform`
-
-For composition *authoring* craft (motion, keyframes, scene design), Vidfarm ships the **HyperFrames** suite — route broad "make me a video" requests through `https://vidfarm.cc/skill/hyperframes` first, then load only the workflow skill it selects.
-
-## Router — where to go from the user's ask
-
-1. "Help me figure out what to make" **or "give me a consultation"** → `references/onboarding.md`. **Lead with content ideas, not the interview**, unless they said "consultation": ask for their offer in one line, run `vidfarm ideas --topic "<line>"`, and hand back 20+ titled videos saved as `content-ideas.md` — offline, free, keyless, about a minute. It is the easiest first win, and what they say about the list is better interview material than an interview. A consultation *is* the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks. Run the primitives; don't improvise the strategy in chat. **On devcli with no AI key or no credits, run it keyless: `vidfarm consult` prints the same prompt for YOU to answer, for $0** — never tell a keyless director the consultation is unavailable. Offer `vidfarm consult coldstart --short` (six fixed questions) to anyone who just wants a video today, tell them any question is skippable before you ask the first one, and keep every answer in `CONTEXT.md` in their working folder so the next session starts warm.
-2. "Find a template and start" → `references/core-workflows.md`
-3. "Change / re-theme this video" → `references/editor-workflows.md`
-4. "Find footage / use our assets" → `references/assets-and-sourcing.md`
-4b. **"Download this video/audio from <a website URL>"** → Vidfarm fetches it for you on a **paid plan**: `POST /api/v1/primitives/videos/download` (or `/audio/download`); devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. Works on YouTube, TikTok, Instagram, X, and other supported posts; returns a durable Vidfarm file (photo/carousel posts → an ordered slideshow). **Free plan gets a 402 — don't call it. Tell the user (or, with browser automation, do it yourself) to open the URL in Chrome and download it from the page, then `vidfarm put-file ./the-file.mp4` to bring it in for $0.** Never answer "I can't download that." Details: `references/assets-and-sourcing.md`.
-4b-ii. **"Tweet to TikTok" / "Reddit to TikTok" / "make a video out of this thread / subreddit / account"** → `vidfarm recycle <source>` (devcli), or `POST /api/v1/primitives/social/recycle` with `{ tracer, payload: { source_url, max_records } }`. It **decomposes** a Reddit thread (post + comments), a subreddit (its threads), an X thread (tweet + replies), or an X profile (their posts) into raw JSON — text, comment tree, media URLs, author avatar, engagement stats — and hands it back **unranked and unsummarized** so you pick the hook, the punchline comment, the stat. Auto-paginates via `nextCursor`; `max_records` is the spend ceiling. Brokers the reddit-lead-gen / x-lead-gen OfficeX apps and waits out their async job for you. **Paid plan.** Details: `references/assets-and-sourcing.md`.
-4c. **"Create an avatar"** (spokesperson / presenter / host / UGC creator / talking head) → always a **talking-head VIDEO with spoken audio**, generated on an exact-key-color **greenscreen** plate and keyed off it in the same job → a **transparent presenter** you layer over any background. `vidfarm avatar "<who they are>" --say "<their line>" [--ref headshot.png]` / `POST /api/v1/primitives/videos/create-avatar`. Details: `references/primitives.md` → "Primitive: talking_avatar".
-4d. **"Post this again / to several accounts / on another platform"** → **deduplication**. Platforms fingerprint uploads; the second copy of the same render gets suppressed as duplicate/reused content. `vidfarm dedupe <mp4> [--variants N]` runs on the **exported file** — free, local ffmpeg, **no re-render** — nudging skew/zoom/rotate/speed/saturation/grain a couple of percent and stripping container metadata, invisibly to a viewer. `--variants N` mints N copies distinct from the original *and from each other*, one per account/slot. Cloud twin: `POST /api/v1/primitives/media/dedupe`. Details: `references/core-workflows.md` → *Deduplicate before you publish*.
-4e. **Anything with the word "harness"** — "create me a harness", "update the harness for this format", "give me the harness for this template_id" → a known, named process. `harnesses/README.md` for the three phrasings and the format; `recipes/bulk-scripting-with-a-harness.md` if it's a batch. The third phrasing means the **decomposition**: `vidfarm harness derive <forkId>`.
-5. "Script / batch / render loop" → `references/automation-and-local-dev.md`
-5b. **"Explainer with cutout/sticker art"** (flat illustrations on a stage, sticker sheets, "like those animated explainer videos") → `recipes/cutout-graphics-for-explainers.md`
-6. "I need TTS / music / captions / background removal" → `references/primitives.md`
-6b. **"Which ad wins?" / "test these angles" / "we post every day and want results"** → fetch <https://vidfarm.cc/experiments.md> and run the experimentation method (capacity → epochs/rounds → creative vs structured → `EXPERIMENTS_DIARY.md`). Do not improvise a testing plan; a round with two variables teaches nothing. To produce a bulk batch with gigworkers, pair it with <https://vidfarm.cc/crowdsourcing.md>.
-7. **"Update / upgrade vidfarm"** (or anything that smells like a stale install — a missing command, a 404 on a documented route, a version mismatch) → fetch <https://vidfarm.cc/update.md> and follow it. Update the skill pack and the devcli **together**; updating one alone is the usual cause of "the skill says to do X but it fails."
-
-## Non-negotiables
-
-- Auth header is `vidfarm-api-key` — **not** `Authorization: Bearer`.
-- Never build composition HTML by string concatenation — parse, edit, re-serialize the DOM.
-- Render only through `POST /api/v1/compositions/:forkId/render`; never call the renderer directly.
-- Submissions are **not idempotent** — every render/primitive POST charges again. Check status before retrying.
-- **No HTML slop.** Compositions are HTML, but a video is not a web page. The test: *could you have made this element with the tools inside TikTok's own editor* (font, color, stroke, shadow, tight text box, rotation, animation presets, stickers, emoji, drawn marks)? If you reached past that — a padded capsule, a border, a gradient fill, a blur panel, a card — cut it. So: no CTA "buttons", no benefit chip/badge rows, **no single pill around a static stat or label** (`( 10 hrs / week )`, `( STEP 2 )` — the only legitimate capsule is the active-word `spotlight`/`karaoke` highlight), no frosted/bordered cards holding a headline + URL, no gradient text, feature grids, or bullet lists. Nothing in a video is clickable. Say it as timed text on the footage; emphasize with size, weight, ALL-CAPS, an accent color, or a drawn circle. Arrows, scribble/underline marks, italics, color pops, emoji, cut-out stickers, and mock social UI are fine.
-- **Structure before polish — the four charges, written before the timeline.** 🪝 **Hook**: the first line is a complete clause naming a *situation*, not a label; on screen at `start:0` (chunk 1 is read before any audio). 🔄 **Loop**: one open question by 0:10, stated on screen, **closing inside this video**, with an answer the viewer can't guess. 😍 **Payoff**: shown, not summarized, before the final beat. 🎣 **Bait**: one ask, final beat + post caption. Banned openers: throat-clearing, a logo, a title card, a fade from black. Full harness: `references/hooks-and-virality.md`; checkable form: `vidfarm harness show hooks`.
-- **Then cut ruthlessly — every second is precious.** First assembly is ~30–50% too long. **Deletion test** on every beat (delete it; if the video survives, it stays deleted); what's left must serve a charge. Cut intros, the wind-up before the claim, restatement, >0.35s silences, real-time process, establishing shots, and any tail after the last word — then **ripple the hole closed** or fluff becomes dead air. Not speed: keep the comedic beat, the payoff, and readable cue time. Length is an output. `vidfarm qa` flags `dead-air` / `dead-tail` / `slow-scene`.
-- **The first frame is the thumbnail.** Frame 0 is one frame of ~30 in the first second, but it's the poster every feed and share link freezes on — so it's seen by more people than the video is. Never open on black, an empty frame, or a fade-up: a real visual at `start:0`, the hook words already up, and no *entrance* transition on the first clip (junction transitions between later clips are fine). Check it with `vidfarm stills <dir> --at 0`.
-- **On devcli, `vidfarm qa <dir>` before every render.** Free, instant, local-only blocklist for the slop above + the first frame + the font regime. Feedback, not a gate (exits 0, never automatic). No REST/web equivalent. **It stops after 2 revisions of the same composition** — at the limit it withholds the finding list and tells you to ship or ask the human, because qa→fix→qa has no natural base case and some findings are deliberate style you will never "clear". Re-running qa without editing costs nothing; `--max-revisions <n>` (0 disables) and `--reset-revisions` are the escape hatches.
-- **Review the finished video as a WHOLE, and never by one frame.** Agents build scene by scene, so every scene passes alone while the video drifts as a sequence — shifting margins, three type sizes, a wandering accent colour, N identically-long beats, a jarring join, a dead band under top-anchored content. Tile ~12 stills into one contact sheet — one command, `vidfarm stills <dir> --sheet` — and **read it as an image**: balance, spacing, one type scale, one palette, deliberate pacing, clean joins — then fix the *system*, not the one odd scene. Compare frames from two different scenes (a frozen render passes duration, frame-count and audio-hash checks), verify audio by measurement (~12–15 dB speech-over-bed, peak <0 dBFS) rather than "sounds fine", and report what you measured separately from what you judged. Your own "verified, looks good" is the least reliable signal here — it was wrong on every video of a 32-video batch. Method: `references/reviewing-renders.md`.
-- **Ask about deduplication before you publish or bulk-produce.** "Is this going out more than once — several accounts, another platform, a re-post later? How many copies?" Ask *before* the render or the batch, not after: dedupe is a post-render ffmpeg pass, so answering early keeps it at **render once → dedupe N** instead of paying for a second render per slot. Then post each variant to a **different** account — two accounts posting the same variant defeats the point.
-- **Ask one-time vs bulk before you build.** Volume = **scripting mode**: a pinned base fork, a loop varying ONE thing, and a **`HARNESS.md`** — the director's own written standard, because a fifty-video loop has no human watching every frame. `vidfarm harness init short-form --out ./work/HARNESS.md` (bases: `short-form`, `hooks`, `ugc-testimonial`, `explainer`, `product-demo`), then `vidfarm qa ./work --harness <name|path>` — stackable, any user file valid, auto-discovered from the work dir. Its `checks:` are machine-settled; its `- [ ]` items come back for **you** to answer honestly.
-- **Caption regime is mandatory**: an imported display font (Montserrat default / TikTok Sans), weight 700–900, ~36–64px on a 1080-wide frame, inside the 8%–85% safe zone — and **inside that band, placed in the emptiest part of the frame** (look at a still; text over open sky beats a lower third over the subject, and usually needs no plate at all). Long narration is paged into 3–5-word kinetic cues, never one static wall of text. Exactly one of four backgrounds — `outline`, `plain`, an active-word `spotlight`/`karaoke` pill, or a tight-hugging `highlight-solid` band (radius ≤8px, no border/shadow/gradient/blur).
-- In the web editor, CSS/declarative motion only (JS animation adapters are stripped on save); locally via `vidfarm serve` the full JS adapters work.
-- Treat `forkId` as an unguessable bearer token. Never put provider secrets in composition HTML/JSON.
-
-**Next step:** fetch `https://vidfarm.cc/skill/vidfarm`, then act — prefer a concrete first move (fork a template, hunt a clip, open the local editor) over more explanation.
+Otherwise fetch `https://vidfarm.cc/skill-pack/vidfarm/files/<path>`. Load one file, not the set. The full rollup is `https://vidfarm.cc/skill/vidfarm`.
+
+| Path | Read it when |
+|---|---|
+| `references/core-workflows.md` | discovery, auth, fork/publish/share, cost spectrum, dedupe |
+| `references/editor-workflows.md` | timeline editing, decompose, captions, the replication harnesses *(largest file)* |
+| `references/assets-and-sourcing.md` | Google search for footage, raws hunts, My Files, recurring characters, downloads |
+| `references/agent-included-imagegen.md` | free custom art — image generation the AGENT's own subscription already includes, and why cost mode `minimize` allows it |
+| `references/browser-harness.md` | free-plan sourcing and cost mode `minimize` — driving the user's Chrome as the $0 substitute for the paid search/download primitives |
+| `references/automation-and-local-dev.md` | REST + devcli command table, scripting mode, the local serve loop |
+| `references/hooks-and-virality.md` | before writing any hook, caption script, or re-theme |
+| `references/reviewing-renders.md` | before reporting a video as done |
+| `references/onboarding.md` | "help me figure out what to make", and the consultation flow |
+| `references/content-ideas.md` | the idea banks — 50 frames × 5 awareness stages × 44 angles |
+| `references/primitives.md` | video/image/news search, TTS, STT, music, avatars, overlays, background removal |
+| `references/rest-api.md` | direct HTTP integration only |
+| `recipes/*.md` | `find-and-fork-template` · `retheme-template` · `local-edit-render-approve` · `onboard-a-new-director` · `bulk-scripting-with-a-harness` · `cutout-graphics-for-explainers` |
+| `harnesses/README.md` | anything harness-shaped — start here. Bases: `short-form` · `hooks` · `ugc-testimonial` · `explainer` · `product-demo` · `product-explainer` |
+
+Also served at `vidfarm.cc`: `/experiments.md` (ad testing), `/crowdsourcing.md` (producing a batch with gigworkers), `/update.md` (upgrade runbook), `/experimental` (methods under live testing), `/skill/vidfarm-platform` (architecture), `/skill/hyperframes` (composition-authoring craft — route broad "make me a video" asks here first).