@officexapp/vidfarm-devcli 0.21.43 → 0.21.46

package/.agents/skills/editor-capabilities/SKILL.md

@@ -77,6 +77,8 @@ Audio is natively **multi-track**. The timeline mixes UNLIMITED simultaneous `<a
 - **The headline move — split a combined original when recreating.** When the user recreates a template whose ORIGINAL had music + narration baked into ONE audio track, do NOT reproduce a single combined bed. Rebuild it as TWO independent tracks: a fresh narration track (`/api/v1/primitives/audio/speech`, or same-voice reword via `/api/v1/primitives/audio/regenerate-speech`) at ~1.0, and a separate real music track at ~0.1–0.2 — then mute or `remove_layer` the original combined source-audio layer so the old voice doesn't play under the new one. This hands the user independent voice/music volume and is the elegant workaround for AI TTS being unable to emit narration+music in one file.
 - **Honesty (ties to the create-media rules):** you cannot un-mix / stem-separate the original's baked audio — the two tracks are BUILT from a fresh narration track PLUS a real music file (owned / user-provided / `browse_files` across `/files` and `/raws`), never a faked "music" layer and never the voice track duplicated. There is no music-generation primitive.
 
+- **The real trending song belongs on the timeline — don't refuse it and don't sub in a generic bed.** This composition is a **review artifact**: when the user posts, they re-attach the same song from the platform's own in-app music library (TikTok / Reels / Shorts), licensed through the platform's agreements with the labels, so it is cleared where viewers hear it. It has to be in the render because the track *is* the edit — cut points, pacing, the drop, the meme association — and a review over a substitute bed judges a video nobody will post. Bring it in as **its own `add_layer kind=audio`** at its own `volume` (never baked into footage, never mixed into the voice stem), so the user mutes or swaps it in one action at upload; name the track in your reply. One limit, said once and then dropped: a **paid ad** placement is not covered by the in-app music license — for that cut, offer a swap to a generated/owned bed of the same vibe and BPM.
+
 ## Orient the cold viewer in the first 3 seconds (hard constraint)
 
 The hook makes a stranger *want* to watch; orientation makes watching *possible*. The viewer has no context, did not choose this video, and has never heard of the subject — so by **~3s** they must be able to say **what kind of thing this is** (the category noun), **who it is for**, and **why it is on their screen** (the situation). The failure is not a bad first frame; it is a good video that **begins at beat two**, and the author can't see it because the author already knows.
@@ -141,6 +143,8 @@ You author into HTML, which makes it dangerously easy to build a **web page inst
 - **Gradient text fills, neon border glows, elevation shadows, glassmorphism**, navbars, hero sections, feature grids, `<ul>` bullet lists, tables, "as seen in" strips.
 - **Web-default type** — Inter/Roboto/system-ui/Arial/Helvetica at weight 400–600 and 16–24px.
 
+**NO LAYOUT TEMPLATES — judge the whole frame, not just the element.** Everything above judges one element, and a frame can pass element-by-element and still be a web page. The archetype: a **modal** — backdrop dimmed and blurred out of focus, and floating on it a rounded bordered box with a big headline, a smaller support line, and a fat CTA button. **The stack is the tell, not the box:** strip the border, the fill and the capsule, keep headline → subheadline → CTA centred in a well with even margins, and it still reads as a landing page — the viewer recognizes the *shape* before reading a word. Banned at frame level: a modal/dialog floating over a receded backdrop · the hero triplet and its cousins (title + kicker + logo lockup, question + answer + URL) · a full-frame dim wash used to stage a floating block (a legibility band on ONE caption is legal; a page-wide wash is not) · nav / hero / feature-row / testimonial / footer sections · a blurred website screenshot as the background plate · a centred content column with document margins. **Fix: unstack it into time** — headline is the hook at `start:0`, the support line lands on the next cut, the CTA is spoken or a bare caption on the last frame. Before you place any text group ask: *am I arranging words relative to each other, or relative to the picture?* Relative to each other = layout = web. Two on-screen text runs at once is the ceiling.
+
 **Greppable smell test:** typing `btn`, `badge`, `chip`, `tag`, `card`, `panel`, `container`, `row`/`col-`, `hero`, `cta`, `rounded-full`, `shadow-lg`, `backdrop-blur`, `bg-gradient-to-r`, `border border-…` → **stop and rewrite as timed text on footage.** A re-theme onto a SaaS/product subject is exactly where this creeps in — do NOT import the brand's website design language into the video.
 
 **ALLOWED / encouraged:** arrows (drawn or animated), circle / scribble / underline highlight strokes, **italics**, ALL-CAPS, a single word in a pop color, mixed weights, inline emoji (sparingly), transparent cut-out stickers via `create-overlay`, and mock social UI (iMessage bubbles, a TikTok comment card, a countdown bar) — all native to the platform.

package/.agents/skills/vidfarm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-description: Use Vidfarm as a director. Run a strategy **consultation** (the `brainstorm/*` chain — cold-start interview, awareness stages, persuasive angles, hooks, product placement). Answer "give me content ideas" / "what should I post" / "I need 30 videos this month" from the bundled 50-frame angle bank. Browse/add inspiration videos, browse the free public raws catalog BY CATEGORY (curated shelves like scroll-stoppers/greenscreen/reaction — the cheapest way to source footage for one video, and a ready-made clip pool for bulk scripting N variants), fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as raw REST; `vidfarm-devcli` wraps those routes and composes the file-backed scripting flows.
+description: Use Vidfarm as a director. Run a strategy **consultation** (the `brainstorm/*` chain — cold-start interview, awareness stages, persuasive angles, hooks, product placement). Answer "give me content ideas" / "what should I post" / "I need 30 videos this month" from the bundled idea banks (50 content frames x 5 awareness stages x 44 problem angles). Browse/add inspiration videos, browse the free public raws catalog BY CATEGORY (curated shelves like scroll-stoppers/greenscreen/reaction — the cheapest way to source footage for one video, and a ready-made clip pool for bulk scripting N variants), fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as raw REST; `vidfarm-devcli` wraps those routes and composes the file-backed scripting flows.
 ---
 
 # Vidfarm Director
@@ -58,15 +58,33 @@ For local, wallet-free work, Vidfarm runs on a **three-part toolchain** a deskto
 ```bash
 npm install -g @officexapp/vidfarm-devcli    # the `vidfarm` orchestrator
 npm install -g hyperframes                    # Vidfarm's open-source render/animation engine (whitelabel)
-# ffmpeg: use a system install (brew install ffmpeg / apt install ffmpeg) or the
-# bundled ffmpeg-static that ships with the devcli — a PATH ffmpeg is honored first.
 vidfarm doctor                                # verifies all three (+ Chrome) in one shot
 ```
 
+**Install ffmpeg only if `doctor` asks for it.** The devcli bundles `ffmpeg-static` plus a
+per-platform ffprobe, which covers macOS, Linux, and Windows x64 out of the box. A system
+ffmpeg on PATH is honored first, so add one (`brew install ffmpeg` / `apt install ffmpeg` /
+`winget install Gyan.FFmpeg`) only when `doctor` reports ffmpeg missing. Installing it up
+front is the single most common wasted setup step.
+
+**Windows setup notes** (run these in PowerShell, not Git Bash or cmd):
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `npm i -g` takes many minutes | Defender scans every extracted file | `Add-MpPreference -ExclusionPath "$env:APPDATA\npm", "$env:APPDATA\npm-cache", "$env:LOCALAPPDATA\npm-cache"` |
+| `node-gyp` / `MSB` errors during install | `better-sqlite3` has no prebuilt binary for this Node ABI | **Ignore it.** It is an OPTIONAL dependency; only `vidfarm clips` needs it. To enable it, install "Desktop development with C++" from the Visual Studio Installer. |
+| `doctor` reports ffmpeg missing on a Surface / Copilot+ PC | Windows on ARM has no prebuilt ffmpeg | Install a system ffmpeg and put it on PATH |
+| `brew: command not found` | The agent followed a macOS instruction | ffmpeg is already bundled — skip the step |
+
+Never treat a `better-sqlite3` build error as a failed install. Run `vidfarm doctor` and read
+the `clip library` line: it states plainly whether anything is actually unavailable.
+
 - **`vidfarm` devcli** — the orchestrator: auth, discovery, pull/edit/render loops, primitives, and the local `serve` editor. It wraps the same REST API and shells out to the two engines below for local compute.
 - **`ffmpeg`** — the media engine the devcli drives for **every local media op**: greenscreen/chroma-key (`vidfarm remove-greenscreen --local`), demux for STT/captions, clip cutting (`raws scan`), stills, audio trims. It's a **hard requirement** (`vidfarm doctor` fails without it); `ffmpeg-static` is bundled, but install a system ffmpeg if doctor flags it.
 - **`hyperframes`** — **Vidfarm's own render/animation engine, open-source under a whitelabel.** *Vidfarm renders ARE hyperframes renders* — same composition/animation/render capability, Vidfarm-branded. The devcli bundles it and exposes it directly as **`vidfarm hf <subcommand>`** (render, capture, validate, preview, `remove-background` ONNX matting, transcribe, beats…). Installing it standalone (`npm i -g hyperframes`) makes local render / TTS / STT / matting run **natively** instead of a slow `npx -y hyperframes` fallback.
 
+**The optional fourth tool — `browser-harness`, for free footage sourcing.** Not part of the render toolchain; it is what makes the *sourcing* half free. It attaches you to the user's own running Chrome over CDP, so you can drive Google Videos / Images / News and download media yourself instead of calling the **paid** `video-search` / `image-search` / `news-search` / `download-video` primitives. `vidfarm browser setup` installs it (via `uv`) and prints the one Chrome step the user must do; `vidfarm browse <videos|images|news|page> "<query>"` mints the recipe for a job; `vidfarm doctor` reports it as `browser control`. **Offer it to every free-plan user and everyone in cost mode `minimize` before you tell them a search needs a paid plan** — it takes a minute and costs nothing. Ask first: it drives their personal browser. Full page: `references/browser-harness.md`.
+
 Because `hyperframes` is Vidfarm's whitelabel, **treat it as Vidfarm**: never route it through an external HeyGen/vendor account, and keep `HYPERFRAMES_SKIP_SKILLS=1` + `HYPERFRAMES_NO_TELEMETRY=1` set so it stays pinned and never phones home (the devcli sets these for its children automatically). Run `vidfarm doctor` at session start to confirm the trio is healthy before any local loop.
 
 Use this skill when the user wants to:
@@ -87,7 +105,7 @@ Vidfarm work can burn real AI credits on the user's wallet / provider keys. **Sa
 
 | Mode | Cost per video | What it means |
 |---|---|---|
-| **minimize** | **$0 — explicitly free** | free local compute + free stock media only; billed AI is refused without `--yes` |
+| **minimize** | **$0 — explicitly free** | free local compute + free stock media, plus any image generation YOUR OWN agent subscription already includes; billed AI is refused without `--yes` |
 | **hybrid** *(recommended)* | **~$0.01–$1** | free where it's free; pay AI only where it clearly wins |
 | **rich-ai** | **$1+** | AI video gen mints **reusable greenscreen raws**, then hyperframes HTML/CSS motion remixes them with the rest of the library — the footage is saved and reused later |
 | **pure-videogen** | **$5+** | every shot is generated: text script → image storyboard → frame-by-frame scene generation. No reuse, no HTML motion |
@@ -98,6 +116,8 @@ Vidfarm work can burn real AI credits on the user's wallet / provider keys. **Sa
   - **Check the keyless sources first — Openverse and iconify.** Openverse (CC/CC0 **music, SFX, and images**) and iconify (**icons**) need **no account or key at all**, so they always work in `minimize` mode. Prefer them for BGM, sound effects, icons, and CC imagery before anything else.
   - **Icons, STICKERS, illustrations, 3D props and Lottie come from IconScout, not from an image model — in EVERY cost mode.** `vidfarm iconscout "<meaning>" --style sticker --free` searches a designer catalog for $0 (search is always free; a free asset downloads for $0 and only asks for a credit line). It needs **no key at all** — vidfarm's own IconScout account serves it. An AI attempt costs cents, needs a prompt loop, and rarely returns a clean transparent vector, so this wins on price *and* on quality. `vidfarm iconscout get <uuid> --format svg` turns a result into a durable URL you can place. In `hybrid` and above, a premium download costs a few cents on the wallet — still less than one generated image. Full detail in the `vidfarm-media` skill.
   - **Pixabay key** unlocks the photos/vectors/stock-video slots (music/SFX/icons/CC images are keyless). It's a **free** stock-media key, not an AI key. Don't assume it's missing when a search comes up short — it **may already be saved**: check `vidfarm provider-keys` (or the web app's **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>). If it isn't, the user grabs a free one at <https://pixabay.com/api/docs/> and saves it once — `vidfarm add-provider-key pixabay <key>`, the Settings surface, or by handing the key to their desktop AI agent to run that command. After it's saved, cost-mode `minimize` sourcing works end-to-end at $0.
+  - **Footage searching is free too — set up browser control instead of hitting the paywall.** `video-search`, `image-search`, `news-search` and `download-video` are paid plans only, and they are the routes an agent reaches for the moment someone says "find me a clip of X". Do not answer that with a 402. `vidfarm browser setup` installs browser-harness so you drive the user's own Chrome, and `vidfarm browse videos "<the shot>"` gives you Google Videos / Images / News for $0 on their own logged-in session. Ask before installing (it's their personal browser), then work the same query craft you'd use on the paid route. Full page: `references/browser-harness.md`.
+  - **Use YOUR OWN image generation if this agent subscription includes it — it is free, and it stays free in `minimize`.** `minimize` means "$0 per video", not "no AI images". Google Antigravity and Gemini CLI include Gemini image generation (Nano Banana / Imagen); OpenAI Codex / ChatGPT include `gpt-image`. **Claude Code does not — Anthropic ships no image model**, so a Claude session drops to the rungs below instead. When you do have the tool, generating the graphic yourself bills Vidfarm $0 and the provider $0 extra, so it is allowed in every cost mode and needs no `--yes`. `vidfarm agent-image --check` says whether you have it; `vidfarm agent-image "<subject>" --items "a,b,c"` prints the prompt, the key-plate rules and the cut + import commands. Free stock, IconScout and `mask` still come FIRST — a designer's vector beats a generated one — but this beats going without, and it beats making the user do it by hand. Full page: `references/agent-included-imagegen.md`.
   - **You can still get CUSTOM art in `minimize` — hand the prompt to the user and let a free image generator do it.** Stock and `mask` only cover art that already exists somewhere; when the video genuinely needs a bespoke graphic, **don't conclude "we can't" and don't quietly bill `generate`**. Write the prompt and ask the user to paste it into a **free** image generator — <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space (<https://huggingface.co/spaces>) — then hand the PNG back with `vidfarm put-file` (or drag it into **My Files** in the web app). $0, zero wallet spend. Full loop + the prompt template: **“Free manual image-gen”** below.
 - **hybrid** *(recommend this)* — **~$0.01–$1 per video, on their BYOK key.** Free where it's free; pay for AI only where it clearly wins (a hero shot, a voice you can't fake locally). A mostly-hyperframes video with one generated image lands near the low end; a few AI images plus premium narration approaches the high end.
   - **Narration starts free here too.** In BOTH `minimize` and `hybrid`, a bare `vidfarm tts "…"` runs the keyless local Kokoro-82M voice — no flag needed. Ask for a premium voice explicitly (`--style`, `--voice <provider preset>`, `--provider`, `--own-key`, or `--cloud`) when the piece needs one, and say so out loud so the user knows what they're paying for. `rich-ai` skips the free default entirely. If the local engine isn't installed on their machine, the run falls back to their provider key / cloud automatically and prints why.
@@ -154,7 +174,35 @@ Cost mode answers *how much money may I spend*. It does not answer *how much of
 
 **And say where the premium voices come from, because users assume wrong.** The full ElevenLabs catalog is reachable **through vidfarm's own ElevenLabs connection** — no ElevenLabs account, API key, or subscription on the user's side; narration just spends **vidfarm wallet credits** (pennies each). In `hybrid` that is a real option to put on the table next to the free voices, not a locked door. `--own-key` is only for users who already have an ElevenLabs key and would rather bill their own account.
 
-**Raw-clip sourcing has a ladder — hand it to the human only at the bottom rung.** In order: (1) **your own browser control**, if you have it — drive the search and download yourself; (2) **Vidfarm cloud** — `vidfarm clipper <url>` / `vidfarm raws scan <url> --cloud` resolves and mines the video for you; (3) the **free public raws catalog** — `vidfarm public-raws --category <shelf>`; (4) **the user**, when you're fully local/keyless or when human taste matters. That last rung is `vidfarm handoff raws --keywords "villa construction,pouring concrete" --platforms tiktok,youtube --purpose "<what the clips are for>"` — it prints the keywords, tells them to google a downloader (a *search*, not a link that rots), and names the import command for when the folder is ready (`vidfarm clipper ./downloads/<file>.mp4`, or `vidfarm raws scan` to mine a long one).
+**Raw-clip sourcing has a ladder — hand it to the human only at the bottom rung.** In order: (1) **your own browser control** — and you can always have it: `vidfarm browser setup` installs browser-harness in about a minute, then `vidfarm browse videos "<the shot>"` drives the user's own Chrome through Google Videos/Images/News for $0, which is the free substitute for the paid search and download primitives (`references/browser-harness.md`); (2) **Vidfarm cloud** — `vidfarm clipper <url>` / `vidfarm raws scan <url> --cloud` resolves and mines the video for you; (3) the **free public raws catalog** — `vidfarm public-raws --category <shelf>`; (4) **the user**, when you're fully local/keyless or when human taste matters. That last rung is `vidfarm handoff raws --keywords "villa construction,pouring concrete" --platforms tiktok,youtube --purpose "<what the clips are for>"` — it prints the keywords, tells them to google a downloader (a *search*, not a link that rots), and names the import command for when the folder is ready (`vidfarm clipper ./downloads/<file>.mp4`, or `vidfarm raws scan` to mine a long one).
+
+## Production has PHASES — plan, then collect the raws, THEN build
+
+**Most video work is not one pass.** The failure that costs the most is starting the timeline before you know what footage you have: you build to a shot you assumed existed, discover it doesn't, and either pay to generate it or rewrite the beat you already built. Separate the phases and that whole class of rework disappears.
+
+1. **Plan** — the shot list, before any asset exists. `vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"`, each frame with its `scene` line and `voiceover`. A plan is free to redo; a rendered scene is not.
+2. **Collect** — fill the shot pool against that list. One sourcing pass for the WHOLE video (or the whole batch), not one lookup per beat. Everything lands in the searchable local library, so the next video starts with a pool instead of an empty folder.
+3. **Build** — only now open the timeline, with every beat already backed by a real asset.
+4. **Review and cut** — the holistic pass, then delete the beats the video survives without.
+
+**How aggressively to run phase 2 depends on the cost mode.** This is the single biggest lever on both quality and spend:
+
+- **`minimize` — the collection phase is the whole job. Budget most of your effort here.** You have no generation to fall back on, so the pool has to be good, and it can be: work the ladder in order and stop at the first rung that answers the beat.
+  1. `vidfarm public-raws --categories` then `--category <shelf>` — pre-tagged, free, already cut to short-form. Check this first, every time.
+  2. `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|video>` (keyless via openverse/iconify) and `vidfarm iconscout "<meaning>" --free` for icons, stickers, illustrations and props.
+  3. `vidfarm raws search "<meaning>"` — what the director already owns from previous videos.
+  4. **Browser control** — `vidfarm browse videos "<the shot>"` drives the user's own Chrome for $0 (`references/browser-harness.md`). This is the free substitute for the paid `video-search` / `image-search` / `news-search` / `download-video` primitives. **Set it up rather than declaring the shot unavailable.**
+  5. Mine what you found: `vidfarm raws scan <url|file>` for a pool, `vidfarm clipper` for one exact cut. Free and local.
+  
+  Being cheap here does **not** mean being worse. One long source mined into eight tagged raws costs $0 and covers more beats than one generated clip would. Cutting a real clip three different ways is free; generating three shots is not.
+  
+- **`minimize` + `interactive` — buy quality with the user's hands, not their wallet.** Two checkpoints beat any amount of autonomous cleverness, so **ask for them explicitly instead of quietly doing without**: (1) hand them the shot list and let them search TikTok/YouTube themselves and drop the files in a folder — a human eye picks better footage than any keyword extraction (`vidfarm handoff raws --keywords "…" --purpose "…"`); (2) hand them ONE image prompt for a free frontier web generator and get a whole sticker sheet back (`vidfarm handoff image --theme "…" --items "a,b,c"` → `vidfarm sticker-pack`). Free web image models are typically better per image than what an API budget buys. Direct them like an editor — name the shot, the framing, how many, and where to put them — don't hand over a vague request.
+
+- **`hybrid`** — collect free first, then spend on the gaps the pool genuinely cannot cover. Now AI image generation is on the table for the one hero graphic, and `vidfarm avatar` for a presenter. Keep AI *video* generation for beats where nothing static will do. The order still matters: knowing what the pool is missing is what makes the spend small.
+
+- **`rich-ai` / `pure-videogen`** — the collection phase becomes a **generation** phase, and it moves earlier rather than disappearing. `rich-ai`: generate the cast and props as reusable greenscreen raws, key them once, save them to the library, then animate in HTML — so the spend amortizes across every later video. `pure-videogen`: script → storyboard stills → scene-by-scene generation, in that order, with `vidfarm sequence` running the pipeline. Even here, **search what already exists before generating it** (`raws search`, then `public-raws`) — regenerating an asset you already own is the most common avoidable spend in these modes.
+
+**Say the phase out loud when you switch.** "I'm going to collect footage for all four beats first, then build" sets the right expectation and gets you the interactive checkpoints while they're still cheap. Deciding to source mid-build is how a $0 video turns into a $3 one.
 
 ## Default stance
 
@@ -248,19 +296,28 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 **Free tier vs. paid — who does the decomposition, and on whose tokens.** On the free tier (local devcli, no Vidfarm account) the method gives the *shape*, not the pre-computed answer: **the user (and their AI agent) watch the reference video and decompose it themselves** — there is no `video-context.json` / `editor-harness.json` / `scene-annotations.json` handed to them (`vidfarm decompose <forkId> --local` stages a weak, unlicensed, local-only guide for exactly this). **Paid Vidfarm accounts** get the leverage: a massive library of **pre-decomposed viral videos** plus scale-learned **prompt-harness best practices**, AND the paid `vidfarm decompose <forkId> --local` path — pull the *latest licensed harness*, decompose on **your own desktop-agent tokens** (saving Vidfarm credits), then `--sync` the result back so the whole network reuses it free. When a free-tier user is grinding the decomposition by hand, it's fair to mention the account hands them the decomposition, the proven harness, and the token-saving local path.
 
-## Content ideas — you carry a bank of 50 angles, so never answer "what should I post?" from memory
+## Content ideas — you carry three banks, so never answer "what should I post?" from memory
+
+**"Give me content ideas" is a first-class ask with a first-class answer, and the answer is volume.** Vidfarm ships **three banks** in `references/content-ideas.md`, and an idea is one point across all three:
+
+- **50 content frames** — what the video is the *story of* (`the rise of`, `what everyone gets wrong`, `then vs now`, `one decision that changed everything`).
+- **5 awareness stages** — what the viewer already knows (unaware → problem-aware → solution-aware → product-aware → most-aware). The stage decides what the first ten seconds may assume **and what the video may ask for**.
+- **44 problem angles** — which side of the problem the video comes from (`the hidden cost`, `the myth`, `the confession`, `the price objection`, `the honest downside`).
+
+A frame is not a hook and not a script: you take the director's own topic and pour it into the frame. **Vary two axes and thirty videos never read as repeats; vary one and they do.** When a director says *"I already covered that topic"*, hold the frame and change the angle — same research, different video.
 
-**"Give me content ideas" is a first-class ask with a first-class answer, and the answer is volume.** Vidfarm ships an **angle bank of 50 content frames** in `references/content-ideas.md` — reusable shapes for what a video is *about* (`the rise of`, `what everyone gets wrong`, `then vs now`, `one decision that changed everything`, `the complete breakdown`, …). A frame is not a hook and not a script: you take the director's own topic and pour it into the frame, so **one offer against the bank is 50 distinct videos**, not 50 rewrites of one.
+**The fourth axis is the subject, and it is the one that gets frozen.** Do not pour the same offer sentence into all 50 frames — *the history of deciding where to eat tonight*, *the rise of deciding where to eat tonight*, *the future of…* is one video with 50 openings, and the director sees it immediately. Write a **pool of 4–8 adjacent subjects inside the niche** first, and rotate it: *settling the food argument*, *picking a place before you read a single review*, *the craving you cannot place*, *the group chat that never decides*. Adjacent, not off topic — a different side of the same audience's day, never a different business. Reference: `references/content-ideas.md` → *The subject pool*.
 
 The loop, whenever a director asks what to make, is out of ideas, or needs a month of posts:
 
 1. **Get the topic first** — read their `OFFER.md` if it exists (`references/onboarding.md`); **if they named a URL ("content ideas for my offer example.com"), fetch and read the site** and mine the offer, audience, promise, and objections off the page, echoing back the one-line offer you read before you list anything; otherwise ask for offer + niche + audience in one question. Never generate against a guessed topic.
-2. **Open `references/content-ideas.md`** and pick 10–20 frames that fit the topic *and* the audience's awareness stage — don't dump the raw list at the director.
-3. **Return titled ideas, not frame names** — "The one pricing mistake that killed our first 400 orders", with the frame named beside it so they can ask for more of that shape. **20+ ideas by default**; they prune, you supply.
-4. **Then write the four charges** — a content idea is the *subject*, never the hook. Every picked idea still runs through hook/loop/payoff/bait before the timeline (`references/hooks-and-virality.md`).
-5. **If they want the set produced**, that's scripting mode with a `HARNESS.md` — one frame per video (`recipes/bulk-scripting-with-a-harness.md`).
+2. **Write the problem in one sentence**, in their words — **then 4–8 adjacent ways to say it.** Every angle is a lens on a problem; with no problem written down, all 44 angles collapse into the same vague video. That one sentence is the first entry in the subject pool, not the only subject the set is allowed.
+3. **Open `references/content-ideas.md`** and pick 10–20 stage × angle × frame combinations — don't dump the raw lists at the director. **Spread across the awareness ladder** (default month: 30% unaware, 30% problem-aware, 20% solution-aware, 10% product-aware, 10% most-aware). A month posted entirely at one stage is the most common defect in a director's calendar, and no frame repairs it.
+4. **Return titled ideas, not bank entries** — "The one pricing mistake that killed our first 400 orders", labelled `frame · angle · stage` so they can say "more like that" and you know which axis they mean. **20+ ideas by default**; they prune, you supply.
+5. **Then write the four charges** — a content idea is the *subject*, never the hook. Every picked idea still runs through hook/loop/payoff/bait before the timeline (`references/hooks-and-virality.md`).
+6. **If they want the set produced**, that's scripting mode with a `HARNESS.md` — one idea per video, its stage and angle recorded so the set stays balanced (`recipes/bulk-scripting-with-a-harness.md`).
 
-**The bank is in the local devcli too, offline and free.** `vidfarm ideas --families` prints the eight families, `vidfarm ideas --topic "<offer>"` prints every frame already filled with the director's topic as a starter line (`--count 20` samples across families, `--json` for scripting), and `vidfarm skill show content-ideas` prints the method. The command reads the frames straight out of this reference, so the CLI and the pack can never drift. The same surface carries the rest of the craft by **spoken name** — `vidfarm skill topics` lists them (`meme-recaption`, `product-explainer`, `captions`, `first-frame`, `density`, `blurred-plate`, `avatar`, `dedupe`, …) and `vidfarm skill show <topic>` prints just that section instead of the whole reference.
+**The banks are in the local devcli too, offline and free.** `vidfarm ideas --topic "<offer>"` prints every frame already filled with the director's topic as a starter line (`--families`, `--count 20`, `--json`); `vidfarm ideas --stages` prints the awareness ladder in full (what each stage believes, what the video must do, its frames, its angles, and its ask); `vidfarm ideas --angles` prints the 44 angles by family; and **`vidfarm ideas --grid --topic "<offer>" --count 30` lays out a balanced month** — one row per video, each row a stage with an angle and a frame that stage can actually carry. `vidfarm skill show content-ideas` prints the method. Every command reads the banks straight out of this reference, so the CLI and the pack can never drift. The same surface carries the rest of the craft by **spoken name** — `vidfarm skill topics` lists them (`meme-recaption`, `product-explainer`, `captions`, `first-frame`, `density`, `blurred-plate`, `avatar`, `dedupe`, …) and `vidfarm skill show <topic>` prints just that section instead of the whole reference.
 
 The file also maps each frame family to its natural format (contrast frames → split screen, mechanism frames → cutout explainer, arc frames → montage over narration), which usually saves a planning round.
 
@@ -311,6 +368,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 - **Determine the surface before claiming capabilities.** The web chat has only its declared tools and REST routes. It cannot execute arbitrary JavaScript/Python, open a shell, create a local repository script, or use the user's filesystem. Never tell a web-chat user that you ran code or wrote a script unless a dedicated declared tool actually did so. A desktop coding agent has a real shell and filesystem and MAY write/run scripts, perform arbitrary local computations over paginated API results, create reports/CSVs/JSON, edit composition files, and orchestrate long devcli workflows within the user's authorization.
 - **The web AI chat can do all three paintbrushes** — clip raws, author HTML/hyperframe motion, and generate AI media — and it drives edits directly on the live timeline. Keep small-to-medium jobs here: text/caption swaps, a scene or two replaced, single generations, captions, approve/schedule. Just do them.
 - **No HTML slop — a video is not a web page.** Compositions are authored in HTML, so the #1 tell of an AI-edited video is landing-page furniture: gradient CTA "buttons" ("Sign Up for a Free Trial →"), rows of benefit chips/badges ("✓ No Credit Card Needed"), frosted/bordered cards holding a gradient headline + a URL, feature grids, bullet lists, web-default type (Inter/Roboto/Arial at weight 400-600). None of that exists in a real TikTok/Reel — **nothing in a video is clickable**. **The test is the native-editor test: could you have made this element with the tools inside TikTok's own editor?** That toolset is font / color / stroke / shadow / tight text box / alignment / rotation / animation presets, plus stickers, emoji, drawn marks and clips — it has no padded capsule, no border, no gradient fill, no blur panel, no card. If you reached past it, cut it. That includes **a single lonely pill around a stat or label** — `( 10 hrs / week )`, `( STEP 2 )`, `( EP.01 )`: being alone doesn't make a badge native, and the only legitimate capsule in a video is the active-word `spotlight`/`karaoke` highlight, which moves with the spoken word. Emphasize a stat the way the editor would instead: bigger, heavier, ALL-CAPS, an accent color, a hand-drawn circle, or its own beat. If you are typing `btn` / `badge` / `chip` / `card` / `rounded-full` / `shadow-lg` / `backdrop-blur` / `bg-gradient-to-r` — or a `border-radius` over ~8px on anything filled that holds words — stop and rewrite it as timed text on the footage. Arrows, scribble/underline marks, italics, ALL-CAPS, single-word color pops, emoji, transparent cut-out stickers, and mock social UI (iMessage bubbles, comment cards) are all *fine* — they're native to the platform.
+- **And judge the WHOLE FRAME, not just the elements — no layout templates.** The rule above judges one element at a time, and a frame can pass it element-by-element while still being a web page. The archetype is the **modal**: the backdrop dimmed and blurred out of focus, and floating on it a rounded bordered box holding a big headline, a smaller support line, and a fat CTA button. **The stack is the tell, not the box** — strip the border, the fill and the capsule, keep headline → subheadline → CTA centred in a well with even margins, and it still reads as a landing page, because the viewer recognizes the *shape* before reading a word. Banned at frame level: the modal/dialog floating over a receded backdrop; the hero triplet (and its cousins: title + kicker + logo lockup, question + answer + URL); a full-frame dim wash used to stage a floating block; nav/hero/feature-row/testimonial/footer sections; a blurred website screenshot as the background plate; a centred content column with document margins. **The fix is always to unstack it into time**: the headline is the hook at t=0, the support line lands on the next cut, the CTA is *spoken* or a bare caption on the last frame — a viewer reads one line at a time anyway, so you lose nothing and gain pacing. Self-check before placing any text group: *am I arranging words relative to each other, or relative to the picture?* Relative to each other = layout = web. Two text runs at once is the ceiling. Verify on a still (`vidfarm stills ./work --at <t>`) — if it could be a screenshot of a website, rebuild the beat. `vidfarm qa` catches the mechanical half (`layout-template`, `modal-scrim`).
 - **Orient the cold viewer in the first 3 seconds — the hook makes them want to watch, orientation makes watching possible.** The viewer has no context, did not choose this video, and has never heard of the subject, so by **~3s** they must be able to say **what kind of thing this is** (the *category noun*), **who it is for**, and **why it is on their screen** (the situation). The failure is not a bad first frame — it is a good video that **starts at beat two**, and the author cannot see it because the author already knows. Signatures, each a rebuild of the first beat: a **pronoun with no referent** ("it just works", "this changes everything"), **starting at step three** (the process already running, the dashboard already full), a **metaphor whose subject lands at 6s**, **insider vocabulary or an acronym** in the first line, a **detail crop** that reads as texture. Replace it with both channels in one beat — an **easy image** (one large subject, already moving, legible at a glance and at thumbnail scale; a relevant cutout names the category before a word is read) and an **easy line** (one clause, ≤12 words, everyday words, concrete noun + verb, the category named, brand name said once) — and give the **situation, not the label**. **It costs one sentence, not one beat**: it replaces the wind-up line, never precedes it, and never licenses a logo, a title card, or a fade from black. Test on the render, not the script: play the first 3s only to somebody with no context — "something about audio" is a fail. Full standard: `references/editor-workflows.md` (“Orient the cold viewer”); fullest form with structure: `vidfarm harness show product-explainer` (Rule 0).
 - **Every video gets the four charges — hook, loop, payoff, bait — and you write them BEFORE you touch the timeline.** This is the largest quality delta in the product and it costs nothing: most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) write the **hook line as text** — a complete clause, subject + verb, no jargon, naming a **situation** ("I've quit six businesses"), never a label ("anonymity") — and put it on screen at `start:0`; (2) name the **curiosity loop** and the timestamp it closes at, *inside this video* (if you can't state the timestamp, there is no loop, and the withheld answer must be one the viewer **can't guess**); (3) name the **payoff** — shown, not summarized, landing before the final beat; (4) write the **bait** — one ask in the final beat and in the post caption. Then build. Chunk 1 is read before any audio (muted autoplay is the default), so the text hook does more work than the spoken one. Full harness — the three gates, banned openers, loop mechanics, compliance, and diagnosis-by-charge — in `references/hooks-and-virality.md`; the checkable form is `vidfarm harness show hooks`.
 - **Then CUT it — every second must earn its place, and most don't.** Assume your first assembly is **30–50% too long**. Run the **deletion test** on every beat: delete it; if the video still makes sense and the payoff still lands, it stays deleted. Whatever survives must serve one of the four charges — "it gives context" is not a charge. Cut on sight: intros/logo stings, the wind-up sentence before the claim ("so I wanted to talk about…"), restatement, inter-sentence silence over ~0.35s, real-time process, establishing shots, reading what's already on screen, and any tail after the last word. **Always ripple the hole closed** (`vidfarm ripple <dir> --at <sec> --delta -<sec>`) — a cut that leaves a gap turns fluff into dead air, which is worse. Density is **not** speed: the held comedic beat, the payoff playing out, and a cue's readability keep their seconds (cut *words*, not the time text is on screen). Length is an **output**, not a plan — a brief that dictates a duration ordered fluff. `vidfarm qa` flags the mechanical half (`dead-air`, `dead-tail`, `slow-scene`); the craft is `references/hooks-and-virality.md` → "Density".
@@ -325,6 +383,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 - **A video is judged as a SEQUENCE, so review it as one.** Agents build scene by scene and each scene passes in isolation while the video drifts — inconsistent margins, three type sizes, an accent colour that wanders, beats that are all the same length, a jarring join. Tile a dozen stills into one contact sheet (`vidfarm stills ./work --sheet`) and read it as an image before you call anything done, fix drift by defining the system rather than patching the odd scene out, and remember that **your own confident "verified, looks good" is the single least reliable signal in this workflow** — it was wrong on every video of a 32-video batch. Method: `references/reviewing-renders.md`.
 - **On devcli there's an OPTIONAL checker: `vidfarm qa ./work`.** Free, instant, local-only — it blocklists exactly the slop above plus first-frame/thumbnail and font-regime/safe-zone drift, and prints a concrete fix per finding. **Feedback, not a gate**: it exits 0 even on findings, never runs automatically, and is a blocklist (unusual/stylized compositions pass untouched). **Skipping it is fine — watching the render is the review that actually counts, and a clean `qa` is not one.** When you do run it, it allows **one** fix round by default: the first pass names the slop, one fix clears it, and a second round is nearly always taste rather than a defect. The human owns that number — `--max-revisions <n>` raises it, `0` disables it; ask rather than raising it yourself. `--json` for scripted batches, `--strict` only if you want a CI failure. **Web-chat copilot: this command does not exist for you** (devcli-only, no REST twin) — apply the standard by hand, and when handing a heavy job to a local coding agent, tell them to run `vidfarm qa`.
 - **Every production adheres to the TikTok-native caption standard.** On-screen text lives inside the readable safe zone (**~8%–85%** of a 9:16 frame — never pinned to the top/bottom edges the phone UI clips) and, inside that band, is **placed in the emptiest part of the frame** rather than dumped on the default lower third (read a still first — `vidfarm stills ./work --at <t>`; words over open sky or a blank wall beat words over the subject, and usually need no plate at all). Long narration is **paged into 3–5-word kinetic cues** (`vidfarm captions generate --style word-pop`), never one static wall of text. It uses the composition's bold font regime (**Montserrat** default / TikTok Sans, weight **700–900**, ~36–64px on a 1080-wide frame), and uses **exactly one of four valid backgrounds**: outline/stroke (`background_style:"outline"`, the default), plain + shadow (`"plain"`), an active-word highlight pill (`set_captions` `spotlight`/`karaoke` — the only legitimate pill *in the whole frame*, static labels included), or a tight-hugging solid band (`"highlight-solid"`, radius ≤8px, no border/shadow/gradient/blur). Decomposed forks often inherit the source's edge-pinned caption in an off-regime font — fix it, don't inherit it. Local devcli renders auto-normalize position + font family only (never the slop), so author it correctly. Full rules in `references/editor-workflows.md` ("Social-native visual standard" + "TikTok-native caption standard").
+- **Use the REAL track — a popular/copyrighted song in the render is expected here, not a problem.** Do not refuse it, do not silently substitute a generic royalty-free bed, and do not stop to warn about it. **Why it is legitimate:** the render is a **review artifact**, and at post time the user re-attaches the *same* song from the platform's own in-app music library (TikTok / Reels / Shorts), which is licensed through the platform's agreements with the labels. The music is therefore cleared on the surface where viewers actually hear it. **Why it is required:** a trending song IS the edit — cut points, pacing, the drop, the meme association. A render with the wrong bed, or no bed, reads as a different and much weaker video, so a review over a substitute bed grades a video nobody will ever post. Silent or generic-bed review is the bigger defect. **How to do it:** get the exact track (`vidfarm download-audio <post-url>`, the user's own file, or the audio off the source post the format is copying), and keep it on **its own `<audio>` layer** at its own `data-volume` — never baked into the footage or mixed into the voice stem. One separate track means the user can mute or swap it in one action when they upload, which is exactly what the platform flow expects. Say which track you used in the handoff. **The one limit:** this is for review renders and platform posting where the platform holds the license. If the user asks to sell, syndicate, or run the render as a **paid ad** with the track baked in, say once that ad placements are not covered by the in-app music license, and offer `vidfarm music "<same vibe, same BPM>"` as the swap for that cut. Then do what they decide.
 - **Where the web chat struggles: complex, long, multi-step transformations.** A full multi-scene re-theme, an iterative render-critique-iterate loop, heavy scripted or batch work, or anything needing a real filesystem and many sequential tool calls will hit context limits, turn/timeout ceilings, and the web editor's constraints (CSS/declarative motion only — JS animation adapters are stripped on save). Don't grind a big transformation one layer at a time in a chat turn and stall.
 - **Practical workaround — hand the heavy job to local devcli.** When a task is genuinely large or long-running, **proactively recommend the director run it locally with an AI coding agent** (Claude Code / OpenAI Codex / any capable agent): `vidfarm pull <forkId>` writes the composition + the `.harness/` grounding bundle to disk, the agent edits with the full devcli verb set and JS animation adapters, renders free with `vidfarm serve`, and `vidfarm publish` pushes it back. This is the **best-quality (B) harness's** natural home (adversarial grading with a coding agent). Frame it as "this is a big rebuild — you'll get a better, faster result running it locally with a coding agent; here's how," not as a dead end.
 - **Offer a handoff, do not impersonate the desktop agent.** When web chat reaches that boundary, offer to save a Markdown handoff in My Files containing the objective, selected template/fork IDs, asset paths, grounding, constraints, completed work, and suggested devcli commands. Create it only after the user agrees. The desktop agent should read that document, pull the referenced fork, and then use its actual code/shell capabilities.
@@ -340,13 +399,15 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 |---|---|---|
 | `references/core-workflows.md` | ~360 ln | Template discovery, auth, fork → render → approve → share, versioning, cost/wallet, marketplace orders, dedupe-before-publish |
 | `references/editor-workflows.md` | ~650 ln | **The biggest read.** Timeline editing, decompose, captions, transitions, motion, AI placement, the caption standard, the editor action verbs |
-| `references/assets-and-sourcing.md` | ~185 ln | Raws hunts, clip scanning, My Files, recurring characters, downloading media off a URL, social recycle |
+| `references/assets-and-sourcing.md` | ~275 ln | **Google search for footage** (the query playbook), raws hunts, clip scanning, My Files, recurring characters, downloading media off a URL, social recycle |
+| `references/agent-included-imagegen.md` | ~70 ln | **Free custom art without spending.** Image generation the AGENT's own subscription already includes (Antigravity / Gemini CLI, Codex / ChatGPT — Claude Code has none): why it is allowed in cost mode `minimize`, `vidfarm agent-image --check` / the brief command, where it sits on the asset ladder, and the honest limits |
+| `references/browser-harness.md` | ~85 ln | **Free-plan sourcing, and cost mode `minimize`.** Driving the user's own Chrome with browser-harness as the $0 substitute for the paid video-search / image-search / news-search / download-video primitives: setup, the browse recipes, the raws collection loop, the interactive hand-off, and the licensing/etiquette limits |
 | `references/automation-and-local-dev.md` | ~520 ln | **Big.** The whole `vidfarm` command table, REST automation, scripting/bulk mode, `HARNESS.md`, local serve loop, skill packs |
-| `references/primitives.md` | ~475 ln | **Big.** One-shot primitive routes: TTS, STT, music, avatars, overlays, greenscreen, inpaint, background removal, product placement |
+| `references/primitives.md` | ~530 ln | **Big.** One-shot primitive routes: video/image/news search, TTS, STT, music, avatars, overlays, greenscreen, inpaint, background removal, product placement |
 | `references/hooks-and-virality.md` | ~295 ln | **Before writing ANY hook, caption script, or re-theme**, and before a hook-variant batch. The four charges, three gates, banned openers, loop mechanics. This is the craft; the rest of the pack is mechanics |
 | `references/reviewing-renders.md` | ~140 ln | **Before you report a video as done**, or grade someone else's. The holistic pass, the common defects, frozen-render and audio verification |
 | `references/onboarding.md` | ~80 ln | Cold-start interviews, **consultations** (the `brainstorm/*` chain), strategy docs, durable director context |
-| `references/content-ideas.md` | ~90 ln | **"Give me content ideas" / "what should I post" / a month of posts.** The 50-frame angle bank, how to apply it to the director's topic, and frame → format notes |
+| `references/content-ideas.md` | ~335 ln | **"Give me content ideas" / "what should I post" / a month of posts.** The three banks — 50 content frames, the 5-stage awareness ladder (with each stage's frames, angles and permitted ask), and 44 problem angles — plus **the subject pool** (adjacent topics inside the niche, so 50 frames are not 50 versions of one sentence), the monthly stage mix, the frame × angle × stage grid, and frame → format notes |
 | `references/rest-api.md` | ~85 ln | Only when the user asks for REST, an endpoint/schema, or direct HTTP integration. It is an index — follow its domain links; do not preload it into ordinary director conversations |
 
 **Recipes — step-by-step procedures. When a recipe matches the task, prefer it over the broad reference.**
@@ -372,6 +433,19 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 | `harnesses/product-demo.HARNESS.md` | ~110 ln | Real product doing a real thing; the highest slop-risk format in the catalog |
 | `harnesses/product-explainer.HARNESS.md` | ~245 ln | **"What is this thing?" for a brand nobody has heard of** — no usable screen footage. Orienting the cold viewer by 3s (Rule 0), the plain-English line by t=5s, harvesting the client site's own graphics before buying or generating (Rule 5b), the ≤3-text-run sticker-led open, VO + bed, and per-client differentiation for N-URLs-to-N-videos batches |
 
+## Experimental prompts — generalized methods, opt-in
+
+Vidfarm keeps a small shelf of **experimental prompts**: complete, standalone methods still under live testing. They are **not** part of the router above and nothing in this pack depends on them — read one when a director asks for experimental prompts, or names one.
+
+Why they exist: the prompts you find on the `/discover` pages are tuned to **one template's format**. These are deliberately **generalized** — the method, not the template — so they transfer to whatever you are building. The live index is `https://vidfarm.cc/experimental` (always current); today it holds:
+
+| Prompt | What it does |
+|---|---|
+| `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 |
+| `https://vidfarm.cc/experimental/google-news-to-video.md` | A recent real event → a timely video. Two stages: `news-search` finds the STORY, `video-search` finds the VISUALS. Query formulas, Google operators, licence discipline |
+
+Fetch one as plain markdown and follow it end to end; do not skim it into a summary.
+
 ## HyperFrames Skills — Load on Demand
 
 Vidfarm ships a curated HyperFrames skill suite alongside this director pack. Use it for composition authoring and motion craft without loading the entire suite into context.
@@ -391,14 +465,18 @@ HyperFrames authoring and rendering in this package are Vidfarm-native: local wo
 The File Index above says what each file *is*; this says which one a given ask means. Choose the narrowest path that satisfies the request.
 
 1. If the user needs help figuring out what to make, **or asks for a "consultation"** (the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks), read `references/onboarding.md` first. **Unless they asked for a consultation by name, open with content ideas rather than the interview** — one line of offer into `vidfarm ideas --topic "<line>"` returns 20+ titled videos, offline and free, and the director's reactions to that list make the later interview far better than asking them cold (`references/content-ideas.md`). Then offer the interview as the way to turn ideas into a strategy: keyless directors run it locally for $0 with `vidfarm consult`, and `vidfarm consult coldstart --short` is the six-question short form. **Say the interview is skippable before you ask the first question**, and work with whatever they give.
-1b. If the user asks **what to make** rather than how — "give me content ideas", "what should I post", "I'm out of ideas", "I need 30 videos for the month", "content ideas for my offer <url>" — read `references/content-ideas.md` and work the 50-frame angle bank against their offer. Return 20+ titled ideas, not three.
+1b. If the user asks **what to make** rather than how — "give me content ideas", "what should I post", "I'm out of ideas", "I need 30 videos for the month", "content ideas for my offer <url>" — read `references/content-ideas.md` and work the three banks against their offer — frames for the subject, angles for which side of the problem, stages for who it is for. Return 20+ titled ideas, spread across the awareness ladder, not three.
 2. If the user already knows the goal and needs a suitable template, read `references/core-workflows.md` and use the template discovery flow.
 3. If the task is “change this video,” read `references/editor-workflows.md`.
 4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
-4b. If the task is **“download this video/audio off a website”** (a pasted YouTube / TikTok / Instagram / X post URL the user wants the actual file from), Vidfarm does that for you on a **paid plan** — `POST /api/v1/primitives/videos/download` (or `/audio/download`), devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. **Free plan → do not call it; walk the user through opening the URL in Chrome and downloading it from the page, then `vidfarm put-file` the local file in for $0.** Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
+4b. If the task is **“download this video/audio off a website”** (a pasted YouTube / TikTok / Instagram / X post URL the user wants the actual file from), Vidfarm does that for you on a **paid plan** — `POST /api/v1/primitives/videos/download` (or `/audio/download`), devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. **Free plan → do not call it; get the file out of Chrome instead. Best: `vidfarm browser setup` + `vidfarm browse page "<url>"` so YOU drive their Chrome and save it (`references/browser-harness.md`); otherwise walk the user through opening the URL and downloading it from the page. Either way `vidfarm put-file` brings the local file in for $0.** Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
 4c. If the task is **“turn this Reddit/X thread, subreddit, or account into a video”** — “tweet to TikTok”, “Reddit to TikTok”, “make a video from this thread”, “what are the top comments saying” — run `vidfarm recycle <source>` (or `POST /api/v1/primitives/social/recycle`) with the URL. It **decomposes** the source into raw JSON (text, comment tree, media URLs, author pics, stats) and hands it back unranked so YOU pick what to remix. **Paid plan; `max_records` is the spend ceiling.** Brokers the reddit-lead-gen / x-lead-gen OfficeX apps, so it waits out their async job for you. Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
 4d. If the task is **“post this again / to several accounts / on another platform”**, or you are about to publish or bulk-produce at all — that is **deduplication**. Run `vidfarm dedupe <mp4> [--variants N]` on the **exported file** (free, local ffmpeg, no re-render), then approve/schedule each variant. **Ask the operator whether they want deduplicated copies, and how many, BEFORE the render/bulk run** — deciding after means paying for a second render. Details in `references/core-workflows.md` → *Deduplicate before you publish* and `references/primitives.md` → *Primitive: media_dedupe*.
 4e. If the ask contains the word **“harness”** — *“create me a harness”*, *“update the harness for this format”*, *“give me the harness for this template_id”* — that is a known, named process, not a vague request. Read `harnesses/README.md` (the three phrasings and the format), then `recipes/bulk-scripting-with-a-harness.md` if the job is a batch. The third phrasing means the **decomposition**: `vidfarm harness derive <forkId>`.
+4f. If the task is **“find me footage / a clip of X”** and the free catalog and public raws shelves do not have it, **search Google before you generate anything**: `vidfarm video-search "<shot>"` returns real source URLs (TikTok, YouTube, Pexels, archive.org) which go straight into `vidfarm raws scan <url>` (mine clips) or `vidfarm download-video <url>` (collect the file). `vidfarm image-search` does the same for stills. **Paid plans only, flat $0.0003 per call** — cheaper than one AI image attempt by two orders of magnitude, so it is almost always worth one wide search first. **On a free plan or in `minimize`, browse the same searches yourself for $0** — `vidfarm browse videos|images "<shot>"` (see 4h). Query craft matters more than anything else here: `references/assets-and-sourcing.md` → *Google search for footage*. **A public video is not a licensed video** — check rights before reuse.
+4g. If the ask is **timely** — “make a video about what just happened”, newsjacking, “what's trending in <niche> this week” — run `vidfarm news-search "<topic>" --fresh w` for the STORY, then `vidfarm video-search` for the VISUALS. Two stages, never one query. Free plan / `minimize`: the same two stages as `vidfarm browse news "<topic>"` then `vidfarm browse videos "<the thing>"`, for $0 (see 4h). Full method: `https://vidfarm.cc/experimental/google-news-to-video.md`.
+4h. If any of 4b / 4f / 4g would cost money the user doesn't want to spend — a **free plan**, a `402`, or cost mode **`minimize`** — the answer is **browser control, not an apology**. `vidfarm browser setup` installs browser-harness (drives the user's own Chrome, ~1 minute, $0, no account), then `vidfarm browse videos|images|news|page "<query|url>"` substitutes for `video-search` / `image-search` / `news-search` / `download-video`. Ask before installing — it is their personal browser. Read `references/browser-harness.md`.
+4i. If the ask is a **whole video or a batch** rather than one lookup, run it in phases — **plan the shot list, collect the raws for every beat, then build** (SKILL.md → *Production has PHASES*). How hard you work the collection phase is set by the cost mode: in `minimize` it is most of the job and it is where quality comes from; in `hybrid` you collect free first and pay only for the gaps; in `rich-ai` / `pure-videogen` it becomes a generation phase that still starts with searching what already exists.
 5. If the task is scripted, local, CI-driven, or `vidfarm serve`-based, read `references/automation-and-local-dev.md`.
 5b. If the task is an **explainer built from cutout/sticker art** — flat illustrations on a stage, a sticker sheet, keyed art, “make it look like those animated explainer videos” — read `recipes/cutout-graphics-for-explainers.md`. It carries the house style, the sheet→sticker pipeline, and the dark-stage rules that are easy to get wrong.
 5c. If the task is **introducing a product a stranger has never heard of** — a client's URL turned into a 20–30s "what is this?" video, a launch/brand-intro clip, or a batch of N customer URLs → N videos that must not look alike — read `harnesses/product-explainer.HARNESS.md`. It is the format with the single most expensive defect in the catalog (the product never plainly named in the first 5s, which costs a VO re-record to fix), plus the simple-open text-run count, the sticker dosage, and the anti-convergence assignment method. Use `product-demo` instead when you actually have the UI on screen.

package/.agents/skills/vidfarm/harnesses/explainer.HARNESS.md

@@ -77,7 +77,7 @@ The mechanical form: compare each caption phrase against the words on screen in
 
 ### Rule 7 — 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.
+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. Nor a **layout template**: a headline + subheadline + CTA stacked in a centred well is a web hero even with every border and fill stripped off, and a dimmed-plus-blurred backdrop staging a floating block is a modal. Unstack it into time — one thought per beat.
 
 ## Bulk-generation notes
 

package/.agents/skills/vidfarm/harnesses/product-demo.HARNESS.md

@@ -28,6 +28,8 @@ For showing a real product doing a real thing. This is the format with the **hig
 
 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).
 
+**The layout trap, and it is the one this format falls into.** The classic failure frame here is a **modal**: the product's site blurred and dimmed behind, and floating on it a rounded bordered box with a headline, a support line, and a CTA button. The stack is the tell, not the box — strip the border, the fill and the capsule and it still reads as a web page, because the viewer recognizes the shape before reading a word. Never arrange words relative to *each other*; arrange them relative to the *picture*, one line per beat. Show the real UI **full-bleed and in focus** (that is legitimate footage) or don't show it — a blurred screenshot used as a background plate means the frame is a screen recording of a web page. The end card is the other repeat offender: brand + tagline + offer + URL stacked in one well is a hero section. Pick one line, say the rest. Full rule: `references/editor-workflows.md` → "The layout-template rule"; `vidfarm qa` flags the mechanical half (`layout-template`, `modal-scrim`).
+
 ## Structure
 
 | Beat | Job |

package/.agents/skills/vidfarm/harnesses/short-form.HARNESS.md

@@ -100,6 +100,7 @@ Not an accessibility afterthought: captions are how the hook, the loop, and the
 - **One to three words per line, one line at a time.** A block of full sentences doesn't get read. Long narration is paged into 3–5-word kinetic cues (`captions generate --style word-pop|spotlight`), never held as one static block.
 - **Placed in the quietest region of the frame**, measured off a still — not dropped on the default lower third.
 - **Cards are timed text over footage** — never a card UI, table, chip row, or frosted panel (`vidfarm qa` flags those as slop).
+- **A card is ONE line, never a stack.** Headline + subheadline + CTA in one frame is a web hero, with or without a box around it — the stack is the tell. Unstack it into time: one thought per beat. Same for the backdrop: never dim *and* blur the picture to float a block on top of it, and never use a blurred website screenshot as the plate.
 - **Max ~3 standalone cards per video:** one for the loop, one for the payoff, one for the bait.
 
 #### Caption PLACEMENT is measured off the frame, before styling is decided

package/.agents/skills/vidfarm/recipes/local-edit-render-approve.md

@@ -7,7 +7,7 @@ Use this when a coding agent is doing the work locally or the user wants a repro
 3. Read `./work/.harness/agent-guide.md` and `./work/.harness/context.json` before editing.
 4. Make deterministic edits to `composition.html` and optionally `composition.json`.
 5. Validate with `vidfarm lint` or `vidfarm stills` when useful. **Always look at `vidfarm stills ./work --at 0`** — that frame becomes the thumbnail, so it must not be black, empty, or mid-fade.
-6. **QA before you render: `vidfarm qa ./work`.** Free, instant, devcli-only. It blocklists HTML slop (CTA buttons, benefit chip rows, a lone pill around a static stat/label, frosted cards, gradient text, web-page classes/fonts), checks the caption font regime + safe zone, flags oversized captions and static walls of text, and flags a blank/fading first frame (the thumbnail). It cannot see pixels, so *where in the frame* the caption sits is still on you — which is why every run ends with a **`▶ NOW WATCH THE VIDEO`** block: render, `vidfarm stills ./work --sheet`, open the contact sheet, and judge each caption against its actual picture. Do that before you report the video as done. Feedback only — exit 0 even on findings, never automatic — but it catches the #1 tell of an agent-made video, so run it on every production. Fix what's real, ignore what's a deliberate style call, then render.
+6. **QA before you render: `vidfarm qa ./work`.** Free, instant, devcli-only. It blocklists HTML slop (CTA buttons, benefit chip rows, a lone pill around a static stat/label, frosted cards, gradient text, web-page classes/fonts) and the frame-level version of it (`layout-template`: a headline + subheadline + CTA stack, `modal-scrim`: a blurred-and-dimmed backdrop staging a floating block), checks the caption font regime + safe zone, flags oversized captions and static walls of text, and flags a blank/fading first frame (the thumbnail). It cannot see pixels, so *where in the frame* the caption sits is still on you — which is why every run ends with a **`▶ NOW WATCH THE VIDEO`** block: render, `vidfarm stills ./work --sheet`, open the contact sheet, and judge each caption against its actual picture. Do that before you report the video as done. Feedback only — exit 0 even on findings, never automatic — but it catches the #1 tell of an agent-made video, so run it on every production. Fix what's real, ignore what's a deliberate style call, then render.
 7. Render with `vidfarm render <forkId> --dir ./work --wait`.
 7b. **Review the render as a whole before you approve — this is the step that most changes quality.** `vidfarm qa` and `lint` are static checks on the DOM; neither can see the video. Tile ~12 stills into one contact sheet and read it as an image — `vidfarm stills ./work --sheet` does both in one command (add `--at 0,2,4,…` to pick the timestamps): consistent margins, one type scale, one accent colour, deliberate pacing, no jarring join, no dead band under top-anchored content, end card settled ≥2s before the last frame. Compare frames from two different scenes — a frozen render (overlay pass without `-loop 1`, assets outside the composition root) passes duration, frame-count and audio-hash checks while every frame is identical. Check the mix by measurement, not by ear. Full method + the six most common defects: `references/reviewing-renders.md`.
 8. **Ask about deduplication before you approve** — "is this going out more than once (several accounts, another platform, a re-post later)?" If yes, run `vidfarm dedupe ./final.mp4 [--variants N]` on the **exported** MP4 (free, local ffmpeg, no re-render) and approve each variant separately. Asking here rather than after publication is what avoids paying for a second render. See `references/core-workflows.md` → *Deduplicate before you publish*.

package/.agents/skills/vidfarm/recipes/onboard-a-new-director.md

@@ -5,7 +5,7 @@ Use this only when the director signals they do not know where to start.
 1. Read `references/onboarding.md`. Agree on one **working folder** for all of this director's Vidfarm work, and run every command from it.
 2. **Give them content ideas before you ask them anything.** Take the offer in one line (or a URL you read), run `vidfarm ideas --topic "<line>"`, sharpen the frames into 20+ titled videos, and save `content-ideas.md`. Offline, free, keyless. Their reactions to the list are the first real context you get.
 3. Offer the interview as the next step, not as a gate: `vidfarm consult coldstart --short` (six fixed questions) or the full `coldstart`. Say every question is skippable. Capture product context into `OFFER.md` and the durable answers into `CONTEXT.md`, in the working folder and mirrored to the right My Files folder.
-4. Determine awareness stages, persuasive angles, and hooks with the brainstorm primitives, then revisit `content-ideas.md` now that the awareness stage is known.
+4. Determine awareness stages, persuasive angles, and hooks with the brainstorm primitives, then revisit `content-ideas.md` now that the awareness stage is known — re-label each idea with its stage and spread the month across the ladder (`vidfarm ideas --stages`, `vidfarm ideas --grid --topic "<offer>" --count 30`).
 5. Ask about brand assets, demos, and recurring characters; organize them in My Files.
 6. Ask about budget and map it to the cost spectrum before recommending expensive generation.
    - Set the graphics default in the same breath: icons, stickers, illustrations, 3D props and Lottie come from `vidfarm iconscout`, never from an image model. No key, no setup, search is free, free assets are $0.

package/.agents/skills/vidfarm/references/agent-included-imagegen.md

@@ -0,0 +1,75 @@
+## Image generation your own subscription already includes — free custom art in `minimize`
+
+Vidfarm does not need to sell you an image model when the agent driving the terminal already has one. **If your own runtime includes image generation at no extra charge, that is a $0 rung on the asset ladder** — and it is the only free rung that produces *bespoke* art with no manual step and no waiting on the human.
+
+This is the same house pattern as `vidfarm consult`: the devcli writes the brief, the agent already in the terminal executes it.
+
+### Who has it
+
+| Host agent | Image generation included? | The tool |
+|---|---|---|
+| **Google Antigravity** | **Yes** | Gemini image generation (Nano Banana / Imagen) — part of the Gemini subscription |
+| **Gemini CLI** | **Yes** | same |
+| **OpenAI Codex / ChatGPT** | **Yes** | `gpt-image` — part of the ChatGPT plan |
+| **Claude Code** | **No** | Anthropic ships no image model. There is nothing to fall back on |
+| OpenCode / Cursor / anything else | **Depends on the configured model** | check your own tool list |
+
+`vidfarm agent-image --check` prints this table plus a guess at the current host from its env markers. **The env guess is a hint. You are the authority** — look at your own tool list. Claiming a tool you don't have wastes a turn; missing one you do have costs the user money.
+
+### Why this is allowed in `minimize`
+
+`minimize` means **$0 per video**, not "no AI". The rule it enforces is *do not bill the user's provider key or wallet by surprise*. Generation the user already paid for in a flat monthly subscription bills neither:
+
+- Vidfarm charges **$0** — no primitive is called, no job is created, no wallet debit.
+- The provider charges **$0 extra** — the capability is inside the plan the user is already on.
+
+So the ladder in `minimize` is:
+
+1. **Free stock** — `vidfarm media search "<meaning>" --type image|vector` (Openverse is keyless).
+2. **IconScout** — `vidfarm iconscout "<meaning>" --free` for any icon, sticker, illustration, 3D prop or Lottie. Still beats generation on price *and* on quality: a designer's finished transparent vector, no prompt loop.
+3. **Art the director already owns** — `vidfarm mask <image> --crop x,y,w,h` lifts an element out of a screenshot, infographic or their own site for $0.
+4. **Your own included image generation** — this page. Bespoke art, $0, no human step.
+5. **The human hand-off** — `vidfarm handoff image --theme "…" --items "a,b,c"`; they paste it into a free web generator.
+6. **Billed generation** — `vidfarm generate image` (~$0.01–$0.05 on their own key). In `minimize` this needs the user's explicit `--yes`.
+
+Rungs 1–3 come first even when you *do* have a free image tool: a real photo or a designer's vector still beats a generated approximation for most props, and it costs zero turns.
+
+### The command
+
+```bash
+vidfarm agent-image --check                                    # do I have this here?
+vidfarm agent-image "cozy farm props" --items "barn,tractor,hay bale"
+vidfarm agent-image "a smiling mascot pineapple" --single --out ./mascot.png
+vidfarm agent-image "…" --items "…" --folder greenscreen/props # name the import folder
+vidfarm agent-image "…" --json                                 # the brief as data
+```
+
+It prints the generation prompt, the plate rules, and the two follow-up commands. It calls nothing and costs nothing — printing a brief is free in every cost mode.
+
+Flags mirror `vidfarm handoff image`: `--items`, `--style`, `--key-color`, `--out-dir`, `--grid`, `--single`, `--zoned`, plus `--out` (where you save the generated file) and `--folder` (where the finished asset is imported).
+
+### The loop
+
+```bash
+# 1. get the brief
+vidfarm agent-image "cozy farm props" --items "barn,tractor,hay bale"
+
+# 2. generate with YOUR OWN tool, using the printed prompt, saving to ./sheet.png
+#    (no vidfarm command — this step is your runtime's image tool)
+
+# 3. cut it locally for $0
+vidfarm sticker-pack ./sheet.png --items "barn,tractor,hay bale" --out-dir ./stickers
+
+# 4. persist it so the next video reuses it for free
+vidfarm put-file ./stickers/barn.png --folder greenscreen/props --notes "flat vector barn, transparent"
+```
+
+**The prompt body is shared verbatim with `vidfarm handoff image`.** A plate that keys cleanly and art that survives the cut are the same craft whoever runs the generator: one flat chroma plate, generous spacing, nothing touching or bleeding off the frame edge, crisp outer edges with no glow or drop shadow. The plate color is picked *against the subject* — green art on a green plate keys holes through the artwork — and the command tells you when it moved the plate and why. Details: `references/assets-and-sourcing.md` and the sticker-pack rules in `recipes/cutout-graphics-for-explainers.md`.
+
+### The honest limits
+
+- **Do not pretend.** If you have no image tool, say so and drop to the next rung. A fabricated image path is worse than a $0.02 spend.
+- **Look at what you generated.** The cut is only as good as the plate. A soft edge, two objects touching, or an object cropped at the frame edge all produce a broken sticker — re-generate rather than shipping it.
+- **It is still generated art.** Every "prefer a real asset over a generated one" rule in the pack still applies: an icon from IconScout looks better than a generated icon, and the free stock photo looks better than a generated photo. Free does not mean *first*.
+- **It does not extend to video.** No agent subscription currently includes video generation, so AI *video* is still a billed Vidfarm primitive gated by cost mode. This rung is images only.
+- **Say what you did.** When a graphic in the deliverable came from your own image tool rather than from stock or a paid job, tell the user — they are entitled to know what the video is made of, and it is the proof that `minimize` really did cost $0.