@officexapp/vidfarm-devcli 0.21.39 → 0.21.42

package/SKILL.director.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). 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 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.
 ---
 
 # Vidfarm Director
@@ -95,6 +95,7 @@ Vidfarm work can burn real AI credits on the user's wallet / provider keys. **Sa
 
 - **minimize** — **$0 videos.** Stay on FREE local compute wherever possible (local render, local TTS — `vidfarm tts` already defaults to the free local Kokoro voice in this mode — `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). For assets, reach for the **free stock catalog** before paying to generate anything — `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` pulls royalty-free, commercial-safe music/sound-effects/images/icons/stock-video from pixabay/openverse/iconify at $0 instead of billing AI music/image generation (see the `vidfarm-media` skill). No surprise AI spend.
   - **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.
   - **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.
@@ -201,6 +202,8 @@ Directors also accumulate a **reusable media asset library** — logos, stickers
 - **(A) Cheap & efficient** *(default)* — recaption text; background-video + foreground-video memes; animate HTML/image elements with hyperframes; reuse library media; AI-generate a reusable element **once** then reuse it; greenscreen; raw-clip long-form and remix; lean on the memes/reactions/b-roll/a-roll library and brand media kit; only if genuinely needed, reach for AI image/video/voice/music.
 - **(B) Best quality** — AI video generation by default; storyboard with AI **image** first; then adversarially grade the result with a coding agent (Claude Code / Codex / any capable AI agent) and iterate.
 
+**Meme recaption — the cold-viewer test.** When you rewrite a meme's caption, point it at a **pain or a win the niche knows in its body**, never at a product feature. The line must make sense to somebody who works in the niche but has **never heard of the offer**: cover the brand and the feature names, and the caption must still read as a true, funny moment from their week. Mention the offer lightly or not at all — a joke that needs product context lands only on people who already bought, which defeats the ad. No invented vocabulary, no inside jokes, no setups that only the demo explains. Full method: `references/editor-workflows.md` (“Writing a meme recaption: aim at a pain or a win”).
+
 **When a template is character-driven or a stylized invented world, decompose DETECTS a specific generative workflow** and stamps it on the replication harness as `generative_workflow.applies`. The workflow is deliberately step-gated with human confirmation: **(1) build a character card** (a consistent model sheet to lock the subject on-model) → *pause for the user to correct/confirm* → **(2) lay out a storyboard** of numbered shot panels in the final style → *pause for the user to correct/confirm* → **(3) animate each beat, choosing per scene between cheap ken-burns motion on a static image vs. expensive true AI video**. Bias to ken burns; spend on AI video only where a still genuinely can't carry the beat. "character card of X" / "storyboard of Y" are first-class shorthands in Vidfarm's image tools. Don't assume this workflow — read `generative_workflow.applies` first; for talking-head / clip-remix / kinetic-text templates it's `false` and you rebuild thrift-first instead. Details: `references/editor-workflows.md` (`harness.generative_workflow`).
 
 Present both harnesses to the director, recommend (A) unless they've asked for premium or budget covers it, and explain the tradeoff in these terms. Full methodology: `references/editor-workflows.md` (“The three paintbrushes & two replication harnesses”); cost bands: `references/core-workflows.md` (Cost spectrum).
@@ -226,7 +229,7 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 **Landscape footage in a fullscreen vertical explainer — use the blurred plate, never bars.** When an explainer is built on **real filmed footage** and the source is 16:9 (or 4:3) on a 9:16 canvas, do not `contain` it (hard black letterbox bars read as an unfinished export) and do not blindly `cover` it (a wide shot loses its left and right thirds). Duplicate the clip: a full-canvas `cover` copy behind, heavily **gaussian-blurred and faded dark**, plus the sharp copy centered as a hero band — optionally zoomed ~1.3× — with its **top and bottom edges feathered** into the blur. Same clip, same timecode, so it reads as one continuous image with a shallow-depth-of-field plane, fullscreen edge to edge, nothing cropped, and clean dark space for the header and captions. Bake it once with ffmpeg into a single 1080×1920 file (free, local) and place it as one ordinary full-canvas layer — layer blur is not an editor property, so the pre-bake is the path that works in the editor, `serve`, and cloud render alike. Copy-paste ffmpeg + HTML recipes, tuning table, and the failure modes: `references/editor-workflows.md` (“The blurred plate — landscape footage, fullscreen, on a vertical canvas”).
 
-**Cost-saving move — mask illustrations OUT of a source image the director already has.** (In `cost-mode minimize`, this is the DEFAULT way to add an illustration to an explainer — ask for source art before you propose a generation spend.) When the director can hand you **one** image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — you don't need to pay to generate anything. `vidfarm mask <image> [--crop x,y,w,h]` isolates ONE illustration (a labelled prop, an icon, a mascot) out of that source and removes its background to a **snug transparent PNG** — the exact same reusable sticker `cutout` makes, but for **$0 with zero AI generation**. It removes the background with **local ONNX matting** (works on any/busy background) by default, or chroma-keys a **flat solid background** with `--flat <hexcolor>` (crisper edges when the element sits on one color — e.g. the cream paper behind an infographic's icons). Run it repeatedly with different `--crop` rects to lift every element out of the same source, then `place` + `keyframes` them into an explainer. **Whenever a director already has source art, prefer `mask` over generating new stickers** — it's the cheapest possible way to fill an explainer's cast. Same recipe: `recipes/cutout-graphics-for-explainers.md` (“Mask from an image you already have”).
+**Cost-saving move — mask illustrations OUT of a source image the director already has.** (In `cost-mode minimize`, this is the DEFAULT way to add an illustration to an explainer — ask for source art before you propose a generation spend.) When the director can hand you **one** image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — you don't need to pay to generate anything. `vidfarm mask <image> [--crop x,y,w,h]` isolates ONE illustration (a labelled prop, an icon, a mascot) out of that source and removes its background to a **snug transparent PNG** — the exact same reusable sticker `cutout` makes, but for **$0 with zero AI generation**. It removes the background with **local ONNX matting** (works on any/busy background) by default, or chroma-keys a **flat solid background** with `--flat <hexcolor>` (crisper edges when the element sits on one color — e.g. the cream paper behind an infographic's icons). Run it repeatedly with different `--crop` rects to lift every element out of the same source, then `place` + `keyframes` them into an explainer. **Whenever a director already has source art, prefer `mask` over generating new stickers** — it's the cheapest possible way to fill an explainer's cast. Same recipe: `recipes/cutout-graphics-for-explainers.md` (“Mask from an image you already have”). **A product explainer built from a client URL is the biggest case of this: the site itself is the first asset library.** Harvest it before you buy or generate — product screenshots, brand illustrations, mascots, icons, an animated WebP/GIF (free motion footage), a screen recording in the bundle — `vidfarm capture <url>` then `vidfarm mask --crop` each element into a snug transparent PNG. The order is **harvest → IconScout → generate**, and it holds unless the director says not to use their site art. Full rule with the limits (never paste the landing-page layout; their stock photography is licensed to them): `harnesses/product-explainer.HARNESS.md` → Rule 5b.
 
 **Free manual image-gen — custom art in `minimize` mode for $0, on someone else's tokens.** `mask` only works when the art already exists. When the video needs a **bespoke** graphic and cost mode is `minimize` (or the user said "no spend"), the answer is **not** "we can't" and **not** a silent billed `generate` — it's a **manual handoff**: you write the prompt, the user runs it in a **free** image generator, they hand the PNG back.
 
@@ -244,6 +247,22 @@ 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
+
+**"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 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`).
+
+**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 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.
+
 ## The FIRST FRAME is the thumbnail — treat it as a designed still, always
 
 **Read this as a hard rule, not a style tip. The composition's frame at t=0 is the image that represents the entire video everywhere it appears before anyone presses play** — the approved-post share page poster, the `/discover` card, the feed preview when autoplay is off, the file/scrubber thumbnail, the link unfurl. **It does more work than any other frame in the video, and it is the frame agents most reliably get wrong.**
@@ -291,18 +310,19 @@ 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.
+- **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".
 - **The first frame IS the thumbnail — compose it on purpose.** Frame 0 is a single frame of ~30 in the first second, but it's the poster every feed, share link, and paused player freezes on, so **more people see that one frame than watch the video**. It must never be black, empty, mid-fade, or caught mid-animation: put a real visual at `start:0`, have the hook words already on screen at t=0, and never hang a `fade-black`/`fade-white`/`flash` *entrance* on the **first** clip (junction transitions between later clips are fine — this rule is only about the opening). Verify it, don't assume: devcli `vidfarm stills ./work --at 0` renders that exact frame, and `vidfarm qa` flags a blank or fading open.
 - **Ask early: one-time video, or bulk?** "Make me a video about X" and "I need to post daily / give me 20 hook variants" are different jobs, and directors often don't know the second one has a name. Ask once, up front: *"One video, or should we set this up as a repeatable batch?"* Bulk = **scripting mode** (a pinned base fork + a loop that varies ONE thing per variant; a public-raws shelf is the cheapest source of the N), and every batch gets a **`HARNESS.md`** — because a loop of fifty videos has no human looking at every frame, and the harness is what replaces those eyes. Don't silently ship a one-off when they asked for volume, or drag someone into a harness when they wanted one clip.
 - **"Harness" is a known noun with a known process — recognise it and follow it.** A **harness** is the reusable AI apparatus for ONE format or template: what makes it special, written down as `HARNESS.md` so an agent can reproduce it without the director in the room. It is a first-class artifact — the director owns it, edits it, versions it, and hands it to the next agent. Three phrasings, one artifact:
-  - **"create me a harness"** / "set up a harness for this format" → `vidfarm harness init <base> --out ./work/HARNESS.md` (bases: `short-form`, `hooks`, `ugc-testimonial`, `explainer`, `product-demo`), then **edit it with them**. The bundled file is a starting point, never a house style; the parts that matter are the ones they add — who the viewer is, the banned vocabulary, the compliance line, the pacing this account actually uses. A harness nobody edited isn't about their videos.
+  - **"create me a harness"** / "set up a harness for this format" → `vidfarm harness init <base> --out ./work/HARNESS.md` (bases: `short-form`, `hooks`, `ugc-testimonial`, `explainer`, `product-demo`, `product-explainer`), then **edit it with them**. The bundled file is a starting point, never a house style; the parts that matter are the ones they add — who the viewer is, the banned vocabulary, the compliance line, the pacing this account actually uses. A harness nobody edited isn't about their videos.
   - **"update the harness for this format/template"** → open the existing `HARNESS.md` and write the new rule in, **with its reason on the same line** (a rule whose "why" is missing gets argued away by the next agent). This is what you do every time a batch teaches you something ("the label-framed hooks all died"): the compositions are disposable, the harness is the artifact that compounds.
   - **"give me the harness for this template_id"** → they mean **the decomposition**: `vidfarm harness derive <templateId|forkId>`. It distils the decompose pass's DNA into an editable `HARNESS.md`. If the template hasn't been decomposed, run `vidfarm decompose` first.
   **A harness mirrors the template JSON's own vocabulary** — `## Viral DNA` (hook / retention / payoff / emotion), `## Visual DNA` (cut rhythm, typography, b-roll, transitions), `## Structural DNA` (the beats, and which are load-bearing), `## Audio DNA` (voice, bed, comedic timing), `## Build DNA` (which paintbrush per beat) — the same strands the decompose pass writes as `viral_dna`, `visual_dna`, and friends. `vidfarm harness show <ref> --dna visual` prints one strand instead of the whole doc.
   **Two halves, and only one is machine-checkable.** The `checks:` front matter is settled deterministically by `vidfarm qa` (duration, aspect, `hook_words_max`, `forbid_text`, …); every `- [ ]` line comes back as a **review item you answer honestly in your report** — never claim a video passed the half the CLI can't judge. Harnesses stack and auto-discover: `vidfarm qa ./work` picks up `./work/HARNESS.md`, `--harness hooks --harness ./brand/HOUSE.md` adds more, and any file of theirs anywhere is valid. Format and strand table: `harnesses/README.md`; scripting-mode detail: `references/automation-and-local-dev.md`. *(Formerly `QA_REGIME.md` — same file, and `vidfarm regime …` still works as an alias.)*
 - **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, QA every video you produce: `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), so there's no reason not to run it before every publish. `--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`.
+- **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").
 - **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.
@@ -325,6 +345,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 | `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` | ~30 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/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.**
@@ -348,6 +369,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 | `harnesses/explainer.HARNESS.md` | ~100 ln | Faceless educational video: one claim, invented visuals |
 | `harnesses/ugc-testimonial.HARNESS.md` | ~90 ln | A person vouching for a product — mostly rules about what NOT to add |
 | `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 |
 
 ## HyperFrames Skills — Load on Demand
 
@@ -368,6 +390,7 @@ 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.
+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.
 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`.
@@ -377,6 +400,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 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>`.
 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.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
 7. If the task is the MARKETPLACE (ordering videos from specialist agents): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. Placing/listing orders is the thin REST wrapper in `references/core-workflows.md` (§ Marketplace); anything deeper on a gig (inbox, proofs, payouts) needs the external Dollar Platoon skill — `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`.
 
@@ -812,8 +836,13 @@ How to work it:
 2. **Match the intensity of the clip to the size of the feeling.** The comedy is the mismatch: a tiny pain + a wildly over-the-top reaction clip, or a small win + a stadium-scale celebration. Choose the pain/win that the existing clip's energy already fits, rather than fighting the footage.
 3. **Keep the meme's grammar** — `me when…` / `POV: you…` / `my clients when…` / `us after…`. Swap the subject to whoever owns the feeling (the customer, the founder, the team), keep the frame.
 4. **Never name the product in the line.** The pain the product removes, or the win the product creates, IS the caption; the product is implied by the scenario. A viewer should want to tag a friend, not click "skip ad". Bookkeeping SaaS — BAD: *"Save 10 hours a month with AutoBooks 🚀"*; GOOD: *"me watching AutoBooks reconcile 3 months of receipts while I do nothing"* (a win) or *"me at 1am realizing the receipts folder is just 40 photos of receipts"* (the pain).
-5. **One short punchy line**, matching the original's brevity, tone, and comedic timing. If the original was two stacked lines (setup / payoff), keep two — pain on top, reaction beneath.
-6. **Batch it.** One meme clip + a list of ten pains and ten wins is ten videos. Enumerate the audience's pains and wins once, then recaption the same clip (or a small set of clips) across the whole list — this is the highest-output, lowest-cost loop in Vidfarm.
+5. **The line must make sense to a stranger to the offer — the cold-viewer test.** Before you ship a recaption, read it as a person who works in the niche but has NEVER heard of the product, the brand, the feature names, or the category jargon. If they cannot get the joke in one read, the caption failed, no matter how clever it is to the team. Most of a good recaption is niche **experience** (the day, the client, the tool everyone already uses, the shared annoyance); the offer gets a small implied mention at most, and often none.
+   - **Write about the niche, not the feature.** A meme about a product feature needs product context to land, so it lands only on people who already bought. A meme about the niche's lived experience lands on everybody in the niche — which is the whole point of a meme ad.
+   - BAD (needs product context): *"me after the auto-reconcile v2 sync finally clears"* — "auto-reconcile v2" means nothing to a cold viewer. GOOD: *"me at 1am matching bank lines to receipts by hand"*.
+   - **Test:** cover the brand and the feature names. If the caption still reads as a true, funny moment from the audience's week, keep it. If it turns into nonsense, rewrite it around the feeling instead of the feature.
+   - **No inside jokes, no invented vocabulary, no setups that only the founder's demo explains.** Slang the niche already uses is fine; slang only the product uses is not.
+6. **One short punchy line**, matching the original's brevity, tone, and comedic timing. If the original was two stacked lines (setup / payoff), keep two — pain on top, reaction beneath.
+7. **Batch it.** One meme clip + a list of ten pains and ten wins is ten videos. Enumerate the audience's pains and wins once, then recaption the same clip (or a small set of clips) across the whole list — this is the highest-output, lowest-cost loop in Vidfarm.
 
 If the user insists on explicit ad copy in the recaption, say once that it flattens the joke, then give them the pain/win version alongside what they asked for.
 
@@ -1203,6 +1232,34 @@ Both `<video>` elements carry `class="clip"` with the **same `src`, `data-start`
 
 **Editor-surface caveat:** layer-level blur is not an `editor_action` property, so the two-layer version can't be assembled from the editor alone — **bake the plate with ffmpeg and drop it in as one full-canvas `cover` layer**. That's the path for `set_layer_media` / `vidfarm place` work, and it's why the pre-bake is the recommended default rather than the HTML variant.
 
+### Orient the cold viewer in the first 3 seconds (before the hook does its job)
+
+**The viewer has no context, did not choose this video, and has never heard of the subject.** A video written by somebody who knows the subject starts where *they* are — mid-thought, on the interesting part — and the first three seconds only parse for people who already have the context. This is a different defect from a weak hook: **the hook makes a stranger want to watch; orientation makes watching possible.** A perfect hook on an unoriented open still loses them.
+
+By **~3 seconds** a stranger must be able to answer three questions:
+
+1. **What am I looking at?** — the **category noun** ("a language app", "a receipt scanner", "a fixtures site"). Not the feature, not the brand promise.
+2. **Who is it for?**
+3. **Why is this on my screen?** — the situation.
+
+**The signatures of an unoriented open.** Each is a rebuild of the first beat, not a polish pass:
+
+- **A pronoun with no referent** — "it just works", "this changes everything", "here's how they do it". The viewer cannot resolve *it* / *this* / *they*, so the line carries nothing.
+- **Starting at step three** — the process already running, the dashboard already full, the metaphor already mid-payoff. Show the situation that causes step one.
+- **A late subject** — an abstract open whose meaning arrives at 6s has spent the seconds that decide whether anyone reaches 6s.
+- **Insider vocabulary** — a brand-internal noun, a product's own feature name, a category word only customers use, or an **acronym**. Never open on an acronym.
+- **A detail crop** that reads as texture until you know the whole. Establish, then push in.
+
+**What replaces it — both channels in the same beat:**
+
+- **An easy image.** One subject, large, already in motion, legible at a glance and at thumbnail scale. If a stranger has to *read* the picture to understand it, it is not an orienting image. A relevant die-cut sticker or cutout names the category before a word is read — usually the cheapest orientation there is.
+- **An easy line.** The first spoken sentence is **one clause, ≤12 words, everyday vocabulary, a concrete noun and a verb** — no subordinate clause, no list, no wordplay — and it **names the category**. Say the brand name once, plainly.
+- **The situation, not the label.** "The end of the month, and your receipts are in a shoebox" orients; "expense automation" does not. Same instinct as the hook standard's situations-over-labels.
+
+**Orientation costs one sentence, not one beat.** It *replaces* the wind-up ("so today I want to talk about…"); it never precedes it, and it never licenses a logo, a title card, or a fade from black. Density and the banned-openers list are unchanged — you are making the first sentence do its job, not adding an intro.
+
+**Test it on the render, never on the script** (the script always looks clear to the person who wrote it): play the **first 3 seconds only** to somebody with no context, then stop. They should say what kind of thing this is and roughly who it is for. "Something about audio" is a fail. The fullest form of this rule, with the format-specific structure around it, is `harnesses/product-explainer.HARNESS.md` → Rule 0 (`vidfarm harness show product-explainer`).
+
 ### The opening frame is the post's thumbnail
 
 **The composition's first frame (t=0) is the still that represents the whole video before anyone presses play** — it's the poster on the approved-post share page, the `/discover` card, the autoplay-off feed preview, and the file/scrubber thumbnail. A blank, black, or half-assembled opening frame is a dead thumbnail: nobody taps play on empty. Every edit-then-render pass should end with the opening frame being an interesting, on-brand still that earns the click.
@@ -1278,7 +1335,7 @@ Compositions are authored in HTML, so the single most common way an AI-edited vi
 - **Emoji inline in text** (sparingly), **sticker/cut-out overlays** on transparent PNG (`create-overlay`), mock social UI when the format calls for it (iMessage bubbles, a TikTok comment card, a fake DM, a countdown/progress bar) — these are native artifacts of the platform, not web furniture.
 - **Full-bleed footage** with text sitting directly on it.
 
-**On devcli there's a checker: `vidfarm qa <dir|composition.html>`.** Free, instant, local-only — a blocklist pass for everything above plus the font regime and safe zone, with a concrete fix per finding. **Run it on every video you produce.** It is feedback, not a gate (exit 0 even on findings, never runs automatically, `--strict` only if you want a CI failure) and a blocklist, not an allowlist (stylized/hand-made compositions pass untouched — it will not homogenize your videos). Every run — including a clean one — ends with a **`▶ NOW WATCH THE VIDEO`** block, because the check never rendered or saw the video and a green tick is not a review; do those steps before you tell anyone the video is done. No cloud/REST twin: the web copilot enforces this standard by hand. Details in `references/automation-and-local-dev.md` ("`vidfarm qa`").
+**On devcli there's a checker: `vidfarm qa <dir|composition.html>`.** Free, instant, local-only — a blocklist pass for everything above plus the font regime and safe zone, with a concrete fix per finding. **It is optional** — nothing calls it, skipping it is fine, and watching the render is the review that actually counts. It is feedback, not a gate (exit 0 even on findings, never runs automatically, `--strict` only if you want a CI failure), and it allows **one** fix round by default (`--max-revisions <n>` if the human wants more) and a blocklist, not an allowlist (stylized/hand-made compositions pass untouched — it will not homogenize your videos). Every run — including a clean one — ends with a **`▶ NOW WATCH THE VIDEO`** block, because the check never rendered or saw the video and a green tick is not a review; do those steps before you tell anyone the video is done. No cloud/REST twin: the web copilot enforces this standard by hand. Details in `references/automation-and-local-dev.md` ("`vidfarm qa`").
 
 ### TikTok-native caption standard (position + font + background) — always adhere
 
@@ -2119,7 +2176,7 @@ vidfarm qa ./work --harness hooks --harness ./brand/HOUSE.md # built-in + your o
 
 > Don't confuse `HARNESS.md` with the `.harness/` directory `vidfarm pull` writes. That directory is machine-generated context (`context.json`, `agent-guide.md`), regenerated on every pull — never hand-edit it. `HARNESS.md` is the one the director owns.
 
-Bundled bases (`vidfarm harness list`, files under `.agents/skills/vidfarm/harnesses/`): **`short-form`** (the default — the four charges hook/loop/payoff/bait + the standalone rule), **`hooks`** (hook-variant batches: chunk-1 legibility, the unguessable test, the anti-patterns that only show up at volume), **`ugc-testimonial`**, **`explainer`**, **`product-demo`**. Each is a *starting point to edit*, never a house style to conform to — the parts that matter most are the parts the director adds. A harness can also be any file anywhere: `--harness ./campaigns/q3/RULES.md` is fully supported, and `VIDFARM_HARNESS=./work/HARNESS.md` sets a default for a whole run.
+Bundled bases (`vidfarm harness list`, files under `.agents/skills/vidfarm/harnesses/`): **`short-form`** (the default — the four charges hook/loop/payoff/bait + the standalone rule), **`hooks`** (hook-variant batches: chunk-1 legibility, the unguessable test, the anti-patterns that only show up at volume), **`ugc-testimonial`**, **`explainer`**, **`product-demo`**, **`product-explainer`** (introducing a brand nobody has heard of, with no usable screen footage: the plain-English line by t=5s, the ≤3-text-run sticker-led open, VO + music bed, and the assignment method that stops N client videos converging). Each is a *starting point to edit*, never a house style to conform to — the parts that matter most are the parts the director adds. A harness can also be any file anywhere: `--harness ./campaigns/q3/RULES.md` is fully supported, and `VIDFARM_HARNESS=./work/HARNESS.md` sets a default for a whole run.
 
 **The format is two halves, and the split is deliberate:** a front-matter `checks:` block the CLI settles deterministically (duration, aspect, `hook_words_max`, `forbid_text`, `first_frame_text`, … — full key list in `harnesses/README.md`), and every `- [ ]` checkbox in the body, which comes back as a **review item for you to answer**. "Is the withheld answer one the viewer can't supply themselves?" is a judgment call; a linter claiming to settle it would be lying. **Answer the review items honestly in your report** — the CLI prints them precisely because it can't.
 
@@ -2319,8 +2376,11 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate), spells out what the local keyer actually needs (a crisp silhouette in a different color from the plate, sealed shapes, clear gaps between items — hollow art and plate-colored detail INSIDE a shape are fine now), and carries that `--key-color` into the follow-up. `--single` for one subject. `--zoned` asks instead for a color-block sheet (one panel colour per item) and hands back a `--zones RxC` follow-up — worth it when the pack's own colors fight one plate, but leave it off for a free consumer tool that may not follow a grid. |
 | `vidfarm handoff raws --keywords "a,b" [--platforms tiktok,youtube] [--count N] [--purpose "…"]` | local (pure text) | **The interactive-mode CLIP-SOURCING brief** — the bottom rung of the sourcing ladder (browser control → `clipper`/`raws scan --cloud` → public raws → the human). Prints what to search, how to download (a Google *search* for a downloader, never a link that rots), and the import command for when the folder is ready. |
 | `vidfarm storyboard [dir] [--init] [--frames "Title\|scene,…"] [--json]` | local (`STORYBOARD.md` / `SCRIPT.md`) | **The plan pass, and a core part of the composition format.** Scaffolds/reads the project's `STORYBOARD.md`: ordered frames with `duration`/`status`/`src`/`scene`/`voiceover`. The Vidfarm editor renders this file in its **Storyboard** view (contact sheet + per-frame comments + `outline → built → animated` progress), so it's the cheapest place to get a director's approval before building. Not to be confused with `vidfarm sequence` (which GENERATES storyboard images for the pure-videogen pipeline). Alias: `plan`. |
+| `vidfarm experiment [dir] [--init] [round …] [log <video> …] [--json]` | local (`EXPERIMENTS_DIARY.md`) | **Ad testing over weeks, not one video.** Owns the campaign ledger and ONLY that: sizes each round (`videos ÷ capacity = epochs`, where capacity is the SUM of per-channel posting rates — `--channels "tiktok_a x2, li_a 3/week, fb_a paused"` — and epoch slots are dealt out in proportion, warning on `channel-overposted`), ranks the north-star metric, flags outliers vs the median, and lints the method — two variables in one structured round, a winner promoted off one post, results read at mixed ages, a structured round handed to gigworkers, unspent capacity. Feedback, not a gate (exits 0). Also carries the FORMAT decision into planning: `--init` prints the copywriting-led menu (b-roll / talking head / process / loop background / satisfying / lifestyle / POV quote) and records the pick in Setup, which every round inherits. Two writes: `round --videos N --variable angle …` and `log <video> --comments N --channel <acct> --source flockposter --age 48h` (ALWAYS pass `--channel`: it keeps a per-account median so each video is ranked against its own account, not the fleet — account health moves numbers by multiples — and a second account's reading counts as the retest that clears `account-health-confound`) (or `log <video> --posted --channel <id>`, which only RECORDS a post). It deliberately does not re-wrap `channels` (capacity), `harness`/`qa` (constants), `handoff` (briefs), `dedupe` (per-channel copies) or `approve`+`schedule` (posting). Method: <https://vidfarm.cc/experiments.md>. Alias: `experiments`. |
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only; readable on the free plan too (shows $0.00). Aliases: `spend`, `costs` |
-| `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
+| `vidfarm iconscout "<query>" [--asset icon\|illustration\|3d\|lottie] [--style sticker] [--free\|--premium] [--sort …] [--limit n]` | `GET /api/v1/primitives/iconscout/search` | **The cheap alternative to AI image generation.** Designer-made icons, STICKERS, illustrations, 3D props and Lottie. Reach for this BEFORE `generate image` for any of those: an AI attempt costs cents, needs a prompt loop, and rarely returns a clean transparent vector, while IconScout hands back a finished SVG / transparent PNG on the first try. **Search is FREE and never gates.** Needs **no key** — vidfarm's own IconScout account serves it. Aliases: `icons`, `stickers` |
+| `vidfarm iconscout get <uuid> [--format svg\|png\|…] [--size px] [--out file]` | `POST /api/v1/primitives/iconscout/download` | Download one asset to a durable vidfarm URL you can place. A **free** asset costs $0 (honour the returned `attribution`); a **premium** asset runs on vidfarm's IconScout subscription for a few cents on the wallet — still under one AI attempt. Saving your own `iconscout` key makes downloads free. Idempotent per uuid+format. |
+| `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys. `iconscout` is the one provider that packs TWO values into one secret: `<client_id>:<client_secret>` |
 | `vidfarm upload <file> [--folder <path>]` | presign → S3 PUT → finalize (`.../temporary-files/presign` + `.../temporary-files`) | upload → durable URL (ephemeral, 30-day TTL; prefer `--folder temp` for scratch). Goes direct to S3, so large files (up to **200 MB**) bypass the ~6 MB Lambda body limit |
 | `vidfarm download <url> [dest]` | (streams any URL to disk) | download media from a **direct** media URL. Free — no plan, no job |
 | `vidfarm download-video <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | **download a video FROM A WEBSITE** (YouTube/TikTok/IG/X/other supported posts) into durable Vidfarm media; photo/carousel posts return an ordered slideshow. **PAID PLAN** (wallet-billed resolver; free plans get 402). Aliases: `download-post`, `download-url` |
@@ -2340,11 +2400,12 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm raws preset list\|run\|save` / `raws export <ids…> --to <dir>` | (local library) | saved queries; copy raw MP4s out |
 | `vidfarm lint <dir\|composition.html>` | (local static validation) | pre-publish composition check: timing, overlaps, preset names, media src |
 | `vidfarm stills <dir> [--at 0,2.5,…] [--sheet]` | (local in-process render of PNG frames) | visually verify an edit without a full render. **`--sheet` also tiles them into one contact sheet** (`<out>/contact-sheet.png`, `--sheet-out`/`--sheet-width` to tune) — the whole-video review pass: read it as ONE image and sequence-level drift (uneven margins, three type sizes, a wandering accent colour, N identical beats, a jarring join) becomes obvious where per-scene checks never see it |
-| `vidfarm qa <dir\|composition.html> [--harness <name\|path>…] [--json] [--strict]` | (local static QA — **devcli-only**, no cloud/REST twin) | **social-native QA: HTML slop + first frame + font regime. Run it on EVERY video you produce.** `--harness` grades against a HARNESS.md too (stackable). Free, instant, feedback-only |
+| `vidfarm qa <dir\|composition.html> [--harness <name\|path>…] [--json] [--strict] [--max-revisions <n>] [--reset-revisions]` | (local static QA — **devcli-only**, no cloud/REST twin) | **social-native QA: HTML slop + first frame + font regime. Run it on EVERY video you produce.** `--harness` grades against a HARNESS.md too (stackable). Free, instant, feedback-only. **Optional** — nothing calls it, skipping it is fine, and watching the render is the review that counts. **Revision governor:** it counts how many times the composition CHANGED between passes (a re-run on an untouched file is free) and after **1 revision** withholds the findings and says stop — the base case that keeps an autonomous agent out of a qa→fix→qa loop. State lives in `.vidfarm-qa-state.json` beside the composition; `--max-revisions <n>` raises it (`0` disables), `--reset-revisions` starts over |
 | `vidfarm harness list\|show <ref> [--dna <strand>]\|init <name> [--out <path>]\|derive <forkId\|dir>\|check <dir>` | (local — **devcli-only**) | **HARNESS.md: the reusable AI harness for one format or template.** `init` copies a bundled base to edit; `derive` turns a decomposed template's DNA into one ("give me the harness for this template_id"); `check` is `vidfarm qa` under the harness noun |
 | `vidfarm doctor` | (local environment triage) | check ffmpeg/node/keys/agent CLI/poisoned env + list local serve/preview processes before debugging anything else; `--kill-orphans` reaps dead servers squatting ports (fixes the "Waiting for preview server…" hang) |
 | `vidfarm skills list\|add <name>\|update` | `GET /skill-pack/index.json` · `/skill-pack/:name/*` | install/refresh skill packs (see "Skill packs — import on demand") |
-| `vidfarm skill ls\|show <path>\|search "<term>"\|path` | (local — **offline, no account**) | **Read this pack straight off disk.** A full copy ships inside the devcli tarball and is pinned to the installed version. `search` greps all 22 files at once — the cheapest way to find one paragraph without loading a whole reference |
+| `vidfarm skill ls\|topics\|show <path\|topic>\|search "<term>"\|path` | (local — **offline, no account**) | **Read this pack straight off disk.** A full copy ships inside the devcli tarball and is pinned to the installed version. `search` greps all 23 files at once — the cheapest way to find one paragraph without loading a whole reference. **`topics` is the spoken-name index** (meme-recaption, product-explainer, captions, first-frame, blurred-plate, density, avatar, dedupe, …) and `show <topic>` prints just that SECTION, not the 650-line file it lives in |
+| `vidfarm ideas [topic] [--topic "<offer>"] [--family <name>] [--families] [--count <n>] [--json]` | (local — **offline, free, no AI call**) | **"What should I post?"** — the 50-frame content-idea angle bank, read out of `references/content-ideas.md` so the CLI and the skill never drift. `--topic` fills every frame with the director's offer as a starter line; `--count` samples across families instead of truncating. It hands over frames, not finished titles — sharpen each one, then write hook/loop/payoff/bait |
 | `vidfarm tts "…" --engine local` / `vidfarm stt <file> --engine whisper` | (keyless LOCAL engines: Kokoro-82M TTS, whisper.cpp STT) | narration + word-timestamp transcripts with zero keys and zero accounts |
 | `vidfarm remove-background <video\|image>` | (local ONNX matting — free) | transparent-subject media for occlusion captions/cutouts (arbitrary/messy background; for a FLAT solid background use `remove-background-greenscreen`) |
 | `vidfarm capture <url>` | (local headless-Chrome capture) | website screenshots/assets for website-to-video flows |
@@ -2356,7 +2417,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 
 **Approving a locally rendered MP4 (the URL-first rule + the durability rule).** The approve route (`POST /api/v1/approved/posts`) and every media-taking route accept a `url`, never raw file bytes — so you never "upload to approve" in one shot. An approved post is a **permanent** share page, so the media must live in **durable My Files**, not the 30-day temp store (a temp-hosted video would 404 the share page after 30 days). The correct sequence for a big local file is: (1) `POST /api/v1/user/me/attachments/presign` with `{ file_name, content_type, size_bytes }` → (2) PUT the raw bytes to the returned presigned S3 URL → (3) `POST /api/v1/user/me/attachments` (finalize) → use the returned durable `viewUrl` as the approve media `url`. `vidfarm approve --video ./final.mp4` does all of this automatically (durable by default; up to **200 MB**). Never POST a large file as multipart to `.../attachments/upload` against the cloud host: that path proxies through Lambda and caps near 6 MB (it exists only as a fallback for local-storage `vidfarm serve` boxes). Only use the temp-store route (`.../temporary-files/*`, or `vidfarm approve --temp`) for a **throwaway** preview you don't mind losing in 30 days.
 
-## `vidfarm qa` — the social-native QA pass (devcli-only, heavily recommended)
+## `vidfarm qa` — the social-native QA pass (devcli-only, OPTIONAL)
 
 ```bash
 vidfarm qa ./work                      # human-readable findings + verdict
@@ -2366,12 +2427,14 @@ vidfarm qa ./work --harness hooks       # + grade against a HARNESS.md (repeatab
                                        #   auto-discovers ./work/HARNESS.md)
 ```
 
-**Run this on every video you produce.** It is free, instant (pure DOM, no ffmpeg/Chrome/network), and it is the only automated check for the thing that most often ruins an agent-made video: **HTML slop**. Compositions are authored in HTML, so an agent's web-page instincts leak straight onto the frame as landing-page furniture that appears on every website and in **zero** real TikToks.
+**It is OPTIONAL.** Nothing requires it, and skipping it is a legitimate choice — **watching the render is the review that actually counts**, and a clean `qa` is not one. When you do run it, it is free and instant (pure DOM, no ffmpeg/Chrome/network), and it is the only automated check for the thing that most often ruins an agent-made video: **HTML slop**. Compositions are authored in HTML, so an agent's web-page instincts leak straight onto the frame as landing-page furniture that appears on every website and in **zero** real TikToks.
 
 It also judges **one frame on its own terms: t=0**, because that frame becomes the thumbnail every feed and share sheet freezes on (see `references/editor-workflows.md`, "The first frame is the thumbnail"). Pair it with `vidfarm stills ./work --at 0` — QA finds the structural cause, the still shows you the actual poster.
 
 **It is feedback, not a gate.** Default exit code is **0** even when it finds slop; nothing in the render or publish path calls it; it never runs automatically. `--strict` exists only if you deliberately want a CI failure. A finding you disagree with is fine to ignore and say so — it is a lint, not a verdict on the work.
 
+**One fix round is the default, not two.** The revision governor stops at **1** revision: the first pass names the slop, one fix clears it, and a second round is nearly always an agent polishing its own taste rather than removing a defect. **The human owns that number** — `--max-revisions <n>` raises it whenever they want another round, `0` disables the governor entirely, and `--reset-revisions` starts the count over. Never raise it on your own initiative to keep a loop alive; ask.
+
 **It is a BLOCKLIST, not an allowlist.** It names specific known-bad web patterns. Everything it doesn't name is legal, so a weird, ugly, hand-made, or wildly stylized composition passes untouched. It will never push your videos toward one house style — if it fires on a genuine creative choice, that's a bug in the rule, not in your video.
 
 What it flags:
@@ -2419,9 +2482,9 @@ The four modes, quoted as **cost per finished video**. The first two are spend p
 
 **All of it bills to the user's own AI provider keys (BYOK)** — the keys saved with `vidfarm add-provider-key <provider> <key>` or at **Settings → Bring your own keys** (<https://vidfarm.cc/settings/developer>). The model providers charge those keys directly; Vidfarm wallet credits only come into play when the user deliberately runs on the platform key instead of their own. So `minimize` isn't "cheap", it's **zero**: nothing reaches a paid key at all.
 
-`vidfarm cost-mode <minimize|hybrid|rich-ai|pure-videogen>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, `cutout --generate` (only the generation step; a bare `cutout` on an existing graphic is free), and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`), `dedupe --cloud`. FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, `dedupe --local`, `cutout` on a file/url, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates.
+`vidfarm cost-mode <minimize|hybrid|rich-ai|pure-videogen>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, `cutout --generate` (only the generation step; a bare `cutout` on an existing graphic is free), and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`), `dedupe --cloud`. FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, `dedupe --local`, `cutout` on a file/url, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates. `vidfarm iconscout` **search** is free and never gates either; only `vidfarm iconscout get` on a PREMIUM asset can spend (a few cents on the wallet), and free assets cost $0.
 
-- **minimize ($0 videos)** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command.
+- **minimize ($0 videos)** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command. **For icons, STICKERS, illustrations, 3D props and Lottie, use `vidfarm iconscout "<meaning>" --style sticker --free` instead** — it needs no key at all, search is free, and free assets download for $0 (a credit line is the only price). Prefer it over a generated graphic in every mode, not just `minimize`.
 - **minimize still gets CUSTOM images — via a free manual generator.** A refused `generate` is not the end of the road. Offer the user the manual loop (ask once, then make it the session default): **you write the prompt → they run it free in <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space (<https://huggingface.co/spaces>) → they hand the PNG back** via `vidfarm put-file ./sheet.png` or web **My Files**. Ask for **one sheet holding every graphic you need**, gridded on a **flat pure-green plate** (`#00FF00`), no text — one round trip instead of N, which saves the user's time and your tokens. Then split it locally for $0: `vidfarm mask ./sheet.png --crop x,y,w,h --flat "#00FF00" --out prop-a.png`, once per element (drop `--flat` and let local ONNX matting handle it if the tool ignored the green background). Full prompt template + loop: recipe `recipes/cutout-graphics-for-explainers.md` (“Free manual image-gen”).
 - **hybrid (~$0.01–$1 per video)** *(default recommendation)* — billed ops run but print a one-line cost notice each, charged to the user's BYOK key.
 - **rich-ai ($1+ per video)** — billed ops run without gating; cost is still printed. AI *video* generation is the line item that pushes a video well past $1 — quote it before running. Spend it on **reusable greenscreen raws**, not on finished shots: `vidfarm avatar "<who>" --say "<line>"` for presenters, `vidfarm create-overlay "<subject>"` / `cutout --generate` for props and illustrations, or `generate video` prompted onto a flat key-color plate. The primitives key the plate in the same job and also hand back `greenscreen_source_url`, so re-keying at a different tolerance is free. Then **animate in hyperframes HTML/CSS over the keyed raws** — generated seconds cost money, motion doesn't — and **persist every asset**: `vidfarm put-file ./keyed.webm --folder greenscreen/<name> --notes "<what it is, when to reuse it>"` (notes are vector-embedded → `vidfarm files --search`), or `vidfarm clipper ./generated.mp4 --folder greenscreen-cast --name "<name>"` for footage-shaped raws in `/raws`. Both stores are **local by default** under `~/.vidfarm`; on a **paid/Pro plan** mirror them with `vidfarm sync push /files` and `vidfarm sync push /raws` (`sync pull` elsewhere, `--dry-run` first). Before generating, always search what already exists — `vidfarm raws search "<meaning>"` then `vidfarm public-raws --category greenscreen --query "<meaning>"`. That is what makes the mode amortize: the next video can reuse the same cast in `hybrid`/`minimize` for ~$0.
@@ -2519,12 +2582,19 @@ Installing `@officexapp/vidfarm-devcli` puts a **complete copy of this pack on d
 
 ```bash
 vidfarm skill ls                        # every file, with sizes
+vidfarm skill topics                    # the craft by SPOKEN name → file § section
 vidfarm skill show primitives           # shorthand resolves to references/primitives.md
+vidfarm skill show meme-recaption       # a TOPIC prints just that section
 vidfarm skill show harnesses/README.md  # or an exact path
 vidfarm skill search "greenscreen"      # grep all of it — find the paragraph, then open that file
 vidfarm skill path                      # where the bundled copy lives
+
+vidfarm ideas --families                # the 50-frame idea bank, by family
+vidfarm ideas --topic "bookkeeping for trades" --count 20
 ```
 
+**Ask by topic before you ask by file.** `vidfarm skill topics` maps what a director actually says ("how do I write a meme recaption?", "product explainer", "captions", "first frame", "density") to the exact section that answers it, and `skill show <topic>` prints that section alone. Opening `editor-workflows.md` to find 25 lines is the expensive way to get the same paragraph.
+
 **Prefer `skill search` over opening a big reference.** `editor-workflows.md` is ~650 lines and `automation-and-local-dev.md` ~520; a grep that returns `references/primitives.md:214` costs almost nothing and tells you exactly which file to load.
 
 Two things this does NOT mean:
@@ -2586,8 +2656,10 @@ The point of onboarding is to build **durable, reusable context** in My Files, n
 2. **Awareness level** (Eugene Schwartz — problem-aware, solution-unaware, …) → `awareness-levels.md`. If it's genuinely unknown after thinking it through, note that ads for **every** level should be made and tested. Use `brainstorm/awareness_stages`.
 3. **Persuasive angles** → `persuasive-angles.md`, via `brainstorm/angles`.
 4. **Hooks** → `ad-hooks.md`, via `brainstorm/hooks`. **Grade what comes back against `references/hooks-and-virality.md`** — the three gates, situation-vs-label, and the unguessable test — instead of shipping the raw list. And never rank a generated batch with the same reasoning that wrote it; the rubric catches defects, it doesn't pick winners.
+4b. **Content ideas** → `content-ideas.md` in their offer folder. Once the offer and awareness stage are known, work the 50-frame angle bank in `references/content-ideas.md` against the topic and save 20+ titled ideas. This is what the director actually posts from between chats, and it is the answer to "what should I post?" for the next month.
 5. **Brand assets & demos** — ask if they have logos/mascots/themes (suggest a `/brand-assets/` folder, e.g. `/brand-assets/logo.png`) or product demos / screen recordings (suggest a `/product-demos/` folder). `browse_files list` / `vidfarm files` first to see what they already uploaded; filenames should be descriptive and every asset worth finding later should get **notes** (`annotate-file` / `browse_files annotate`) so `files --search` works months from now. If they have a recurring character/mascot, set up its `/files/characters/<slug>/` trio now — `<character_id>.json` (e.g. `character_zara.json`) + `character_sprite_card.png` + `character_about.md` (see "Recurring characters are first-class").
 6. **Budget** — ask roughly what they want to spend per video, and map it to the Cost spectrum (free reuse+local render → pennies for cloud render → ~$1 for some AI scenes → $10+ for heavy AI gen). This sets which approach you default to and whether AI **video** generation is on the table (ask permission before using it; image gen is cheap and fine). Budget can also be revisited per editor project.
+   - **While you're on money, set the graphics default: IconScout, not AI image generation.** Any icon, sticker, illustration, 3D prop, or Lottie should come from `vidfarm iconscout "<meaning>" --style sticker` — a designer's finished transparent asset on the first try, for a fraction of one AI attempt. **It needs no key and no setup**: vidfarm's own IconScout account serves it, search is free, and free assets download for $0 (a credit line is the only price). Say this out loud during onboarding — it's the single biggest per-video saving a new director can adopt on day one, and it holds in **every** cost mode, not just `minimize`. A director who already pays IconScout can save their own key once (`vidfarm add-provider-key iconscout "<client_id>:<client_secret>"`, or **Settings → Developer**) and then downloads cost them nothing here.
 7. **Recommend & adapt a template** — pair what you now know about the offer against the decomposed template catalog (`GET /discover/feed?q=<offer>`, read each result's `promotions`/`keywords`/`summary`), recommend the best 3-6, then fork and **modify** the winner to fit their offer. Prefer already-decomposed templates so the director skips the ~$0.10 decompose cost.
 
 **Assume multiple offers.** My Files is multi-offer (see the My Files section) — namescope every onboarding artifact under the right product/offer/region folder (`acme-skincare/OFFER.md`, not a bare `OFFER.md`) so one brand's context never bleeds into another's. When a director keeps several offers in one flat folder, name the files `OFFER_ACME_SKINCARE.md` / `OFFER_ACME_SUPPLEMENTS.md` instead.
@@ -2605,6 +2677,118 @@ When a director asks "make me a video", the default sequence is:
 
 Prefer specific templates over primitives when a template exists that already captures the desired production pattern.
 
+## Content ideas — the angle bank
+
+Read this when a director says **"give me content ideas"**, "what should I post", "I need 30 videos for the month", "I'm out of ideas", or when a batch run needs N *different* videos instead of N variants of one video.
+
+**What this is.** A fixed bank of **50 content frames**. A frame is a reusable shape for a video's subject — not a hook line, not a script. You take the director's topic (their offer, their niche, their product, their audience's world) and pour it into a frame: `the rise of` + `dropshipping supplements` → *"The rise of the supplement dropship store"*. One topic against 50 frames is 50 distinct videos, and they do not read as repeats, because each frame changes what the video is *about*, not just how it opens.
+
+**How to use it (the loop).**
+
+1. **Get the topic.** In priority order: read the director's **`OFFER.md`** if one exists (see `onboarding.md`); **if they named a URL** — "content ideas for my offer example.com" — **fetch the site and read it** (home page, plus the pricing and about pages when they exist) and pull the offer, the audience, the promise, the objections, and the product vocabulary straight off the page; otherwise ask for the offer, the niche, and the audience in one question. Never generate ideas against a topic you guessed. When you work from a URL, **state the offer you read back in one line before the list** ("Reading example.com: a $49/mo bookkeeping tool for solo trades") so the director can correct it before you produce 20 ideas off a wrong premise — and offer to save that line plus the ideas as `OFFER.md` + `content-ideas.md` in their folder.
+2. **Pick frames, don't dump the list.** Choose 10–20 frames that actually fit the topic and the audience's awareness stage — a solution-unaware audience wants `what everyone gets wrong` and `how it works`; a product-aware audience wants `then vs now`, `cheap vs expensive`, `one decision that changed everything`. Say the frame name next to each idea so the director can ask for more of that shape.
+3. **Write each idea as a title, not a frame.** Output `"The one pricing mistake that killed our first 400 orders"`, not `"one mistake that changed everything — about pricing"`. A frame that stays abstract is not an idea yet.
+4. **Then run it through the hook harness.** A content idea is the *subject*; it is not the four charges. Every idea a director picks still needs hook / loop / payoff / bait written before the timeline — `references/hooks-and-virality.md`. The frames on this list are deliberately curiosity-shaped, which makes the loop easy to name, but never skip that pass.
+5. **Batch it properly.** If the director wants the whole set produced, that is scripting mode with a `HARNESS.md` — `recipes/bulk-scripting-with-a-harness.md`. One frame per video, one line in the plan file.
+
+**Give lots when asked.** "Give me content ideas" means volume. Return **20+ titled ideas** by default, grouped by frame family, not three polite suggestions. The director prunes; you supply.
+
+### The 50 frames
+
+**Arc & subject frames — what the video is the story of**
+
+- the history of
+- the rise of
+- the fall of
+- the future of
+- the psychology of
+- the science of
+- the business of
+- the evolution of
+
+**Superlative frames — the extreme case carries the video**
+
+- the biggest mistakes
+- the biggest successes
+- the biggest failures
+
+**Hidden-knowledge frames — the strongest curiosity loops on the list**
+
+- the hidden side
+- the untold story
+- what really happened
+- what everyone gets wrong
+- what nobody noticed
+
+**Mechanism & cause frames — the explainer shapes**
+
+- how it works
+- why it works
+- why it failed
+- why it became popular
+- why it disappeared
+
+**Change-over-time frames**
+
+- how it changed
+- how it started
+- how it ended
+- what happened next
+- before it existed
+- after it disappeared
+
+**Contrast frames — two-column videos, and the easiest to build visually**
+
+- then vs now
+- old vs new
+- best vs worst
+- winner vs loser
+- myth vs reality
+- expectation vs reality
+- beginner vs expert
+- cheap vs expensive
+- simple vs complicated
+- cause vs effect
+- problem vs solution
+- theory vs evidence
+- past vs future
+
+**Pivot frames — one thing turned everything**
+
+- one decision that changed everything
+- one mistake that changed everything
+- one person who changed everything
+- one event that changed everything
+- the chain reaction
+
+**Completionist frames — long-form and carousel shapes**
+
+- the complete timeline
+- the complete story
+- the complete guide
+- the complete breakdown
+- the rabbit hole
+
+### Frame → format notes
+
+The frame also suggests how to build it, which saves a planning round:
+
+| Frame family | Natural format | Build notes |
+|---|---|---|
+| Contrast (`then vs now`, `cheap vs expensive`) | Split screen or A/B beat pairs | Cheapest to produce — two stills or two clips per beat. Great for the cutout/sticker explainer style. |
+| Hidden-knowledge (`what nobody noticed`, `the untold story`) | Talking head, or footage + kinetic captions | The loop writes itself; state the timestamp it closes at anyway. |
+| Mechanism (`how it works`, `why it works`) | Faceless explainer with cutouts | House style applies — white stage, word-pop captions, female TTS. See `recipes/cutout-graphics-for-explainers.md`. |
+| Arc (`the rise of`, `the history of`) | Montage over narration, dated beats | Source footage from the free public raws catalog first (`vidfarm public-raws`). |
+| Pivot (`one decision that changed everything`) | Single-story short, cold open on the aftermath | Open on the consequence, then rewind. |
+| Completionist (`the complete timeline`) | Longer piece, or a numbered series | Usually better as N videos than one long one — one entry per short. |
+
+### Do not
+
+- **Do not hand back the raw 50-item list as the answer.** The list is your instrument; ideas applied to the director's topic are the deliverable.
+- **Do not stack two frames in one title** ("the untold story of why it failed"). One frame per video, or the video has two subjects and lands neither.
+- **Do not use a frame the topic can't honestly fill.** `the untold story of` a two-week-old product is a lie the audience catches. Pick a frame the facts support.
+- **Do not treat the frame as the hook.** "The history of X" spoken flat at `start:0` is a banned opener shape — the hook still has to name a situation. `references/hooks-and-virality.md`.
+
 ## Primitive: image_remove_background
 
 Remove the background from any image URL. Result is a transparent PNG/WebP stored at a durable Vidfarm URL you can reuse in compositions or downstream primitives.
@@ -2986,6 +3170,73 @@ Generate spoken narration audio from text. **`use_wallet_credits` defaults true*
 - Billing: wallet-billed on the platform ElevenLabs key (default); free/BYOK when `use_wallet_credits: false` and the caller's own key serves it.
 - devcli: `vidfarm tts "…" --style "…"` runs LOCAL-FIRST on your own env key (no job); add `--cloud` for the ElevenLabs platform job (`--own-key` = your key). `vidfarm voices` lists voices.
 
+## Primitive: iconscout (designer icons, stickers, illustrations, 3D, Lottie)
+
+**The cheap alternative to AI image generation.** Before you call `images/generate` for an
+icon, sticker, illustration, 3D prop, or Lottie animation — don't. A designer already drew
+it. An AI attempt costs cents, needs a prompt loop, and rarely returns a clean transparent
+vector; IconScout returns a finished SVG or transparent PNG on the first try.
+
+**Needs no key.** Vidfarm's own IconScout account serves the request. A customer only saves
+their own `iconscout` provider key if they already pay IconScout — then their downloads
+cost nothing here.
+
+### Search — free, synchronous, no wallet cost
+
+`GET /api/v1/primitives/iconscout/search`
+
+| Query | Values |
+| --- | --- |
+| `q` | search text (required) |
+| `asset` | `icon` (default), `illustration`, `3d`, `lottie`, `ai_image` |
+| `price` | `free`, `premium`, `all` (default) |
+| `style` | comma list: `sticker`, `flat`, `line`, `glyph`, `gradient`, `isometric`, `rounded`, `doodle`, `dualtone`, `colored-outline`, `tile` — **`style=sticker` is the STICKER path** |
+| `format` | comma list; filters to assets available in those formats |
+| `sort` | `relevant` (default), `popular`, `latest`, `featured` |
+| `page`, `limit` | `limit` default 30, max 100 |
+
+Returns `{ query, asset, page, per_page, total, last_page, count, account, download_usd,
+items: [{ uuid, asset, name, price, is_free, preview_url, source_page, formats }] }`.
+
+`account` is `platform` (vidfarm's subscription — premium downloads bill the wallet) or
+`byok` (the customer's own key — nothing bills). **`preview_url` is a thumbnail, not the
+asset** — download before placing anything.
+
+### Download — durable URL, billed only on premium+platform
+
+`POST /api/v1/primitives/iconscout/download` — body `{ uuid, format?, width?, height? }`
+
+Formats by asset: icon `svg`/`png` · illustration `svg`/`png`/`eps` · 3d
+`png`/`gltf`/`glb`/`obj`/`fbx`/`blend` · lottie `json`/`lottie`/`gif`/`mp4` · ai_image
+`png`/`jpg`. `format` defaults to the first valid one. `width`/`height` apply to raster
+formats only; vector formats force 0.
+
+The bytes are copied into durable vidfarm storage before IconScout's own signed URL
+expires, so the returned `url` is stable and placeable. Returns `{ url, file_name,
+content_type, size_bytes, format, asset, name, uuid, is_free, source_page, account, billed,
+charged_usd, attribution_required, attribution }`.
+
+**Cost.** Free assets: $0, but `attribution_required` is true — honour the returned
+`attribution` credit. Premium assets on the platform account: a few cents on the wallet
+(`ICONSCOUT_DOWNLOAD_USD`). Repeat downloads of the same `uuid` + `format` are idempotent
+and bill once. A premium asset with no active subscription returns **402** with
+`subscription_required: true` — search `price=free` instead.
+
+devcli: `vidfarm iconscout "<query>" --style sticker --free`, then
+`vidfarm iconscout get <uuid> --format svg`.
+
+Example:
+
+```bash
+curl "$VIDFARM_BASE/api/v1/primitives/iconscout/search?q=pineapple&asset=icon&style=sticker&price=free&limit=5" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY"
+
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/iconscout/download" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{ "uuid": "99d2b880-09f7-11eb-992f-0242ac140003", "format": "svg" }'
+```
+
 ## Primitive: audio/voices (list ElevenLabs voices)
 
 `GET /api/v1/primitives/audio/voices` returns the ElevenLabs voice catalog — `{ scope, default_voice_id, voice_library_url, voices: [{ voice_id, name, category, labels, description, preview_url }] }`. Default scope is vidfarm's platform account; add `?use_wallet_credits=false` to list the voices on the customer's OWN saved ElevenLabs key. Pick a `voice_id` and pass it as `voice` to `/audio/speech`. devcli: `vidfarm voices` (`--own-key` for the user's account).
@@ -3163,7 +3414,7 @@ Two ways in, depending on where the format came from:
 
 ```bash
 # (a) From a bundled base — when the format is one you're defining
-vidfarm harness list                                    # short-form | hooks | ugc-testimonial | explainer | product-demo
+vidfarm harness list                                    # short-form | hooks | ugc-testimonial | explainer | product-demo | product-explainer
 vidfarm harness init hooks --out ./work/HARNESS.md
 
 # (b) From the template you're batching — when the format is one you're REPLICATING
@@ -3260,6 +3511,8 @@ The mechanical trio — **generate on a chroma plate → key it out → trim to
 
 **Illustrations default to simplicity — and to SOLID FILLS.** Whatever path you take to a sticker, aim for **flat vector, simple shapes, minimal detail, few colors, solid opaque fills, no background, no text baked in** — a friendly icon-grade illustration, not a rendered 3D scene or a detailed painting. Simple art keys cleanly, trims tight, scales without mush, animates readably at 9:16, and stays on-style across a whole cast. "Solid fills" is the load-bearing word: **outline-only art has its interior keyed away and comes back as a rim around a transparent hole** (see "Then make the ART key-safe too" below). When generating, say so in the prompt: `--generate "a coffee cup, simple flat vector illustration, minimal detail, 2-3 flat colors, solid filled shapes (not outline-only), no shadows"`.
 
+**Before either path: check IconScout.** `vidfarm iconscout "<meaning>" --style sticker --free` searches a designer catalog of icons, stickers, illustrations, 3D props and Lottie for $0 — no key needed, and a free asset downloads as a clean transparent SVG/PNG that needs no keying at all. `vidfarm iconscout get <uuid> --format svg` gives you a durable URL. Only fall through to masking or generation when IconScout genuinely has nothing that fits.
+
 **In cost-saving mode, don't generate illustrations at all — mask them out of images the director already has.** If `vidfarm cost-mode` is `minimize` (or the director says "without burning credits"), the default for adding an illustration is `vidfarm mask <their-image> --crop …` — lifting art out of an infographic, poster, deck slide, brand sheet, or screenshot for **$0 and zero AI calls**. Ask for source art before you ask for a generation budget; the guided loop is **"Mask from an image you already have"** below. **If no source art exists and the graphic must be custom, you still don't have to spend** — hand the director a prompt for a **free** image generator (meta.ai / free ChatGPT / a Hugging Face Space) and cut the returned sheet into stickers locally: **"Free manual image-gen"** below.
 
 ### "A sticker pack" — what it means, and the one command for it
@@ -3540,6 +3793,7 @@ Use this only when the director signals they do not know where to start.
 3. Determine awareness stages, persuasive angles, and hooks with the brainstorm primitives.
 4. Ask about brand assets, demos, and recurring characters; organize them in My Files.
 5. 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.
 6. Search for the best matching templates and fork one strong default.
 7. Teach the house phrasing early: coach the director to ask for **"a vidfarm template that …"** rather than "a video," and explain the payoff — it's forkable forever and a teammate can **`vidfarm serve <template_id>`** to pull it onto their own machine (see SKILL.md, "Say 'create a vidfarm template that…'"). Getting this into their vocabulary on day one is the point.
 8. Transition into the ordinary template-editing workflow.