@officexapp/vidfarm-devcli 0.21.39 → 0.21.43

package/.agents/skills/vidfarm/references/automation-and-local-dev.md

@@ -84,7 +84,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.
 
@@ -283,10 +283,13 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm mode [interactive\|autonomous]` | local (`~/.vidfarm/interaction-mode.json`) | **The SECOND preference axis — ask it alongside cost mode.** Is the human in the loop? `interactive` = at checkpoints you hand them a copy-paste brief (an image prompt for a FREE web generator; a keyword list for sourcing clips) and they hand files back — usually BETTER output, and in `minimize` the only way to get custom art at all. `autonomous` = you finish solo within the budget. Independent of cost mode: every cost mode runs either way. No arg prints the pair + the explainer to relay; `--clear` forgets; per-run `--interactive`/`--autonomous`. Aliases: `interaction-mode`, `interaction`. |
 | `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 consult [coldstart\|awareness\|angles\|hooks\|placement]` | local (pure text) | **The consultation / brainstorm chain, KEYLESS.** Offer `vidfarm ideas` first — the interview is the deeper step a director opts into after they have seen a list of ideas, not the price of entry. The cloud runs these five steps as `brainstorm/*` primitives that need a provider key or wallet credits; this prints the **identical prompt** (same source module, so they cannot drift) for the agent already in the terminal to answer itself — $0, no key, no network. Bare `consult` = the map of the four chain steps and which artifacts already exist. Auto-reads `OFFER.md` / `OFFER_<NAME>.md` from `--dir` (two offer files → it makes you name one rather than guessing the wrong product); `--offer` takes a path **or** the offer text, and a path that resolves to nothing is an error, never silently treated as the offer. `--count` mirrors the cloud bounds. **`coldstart --short` is the short-form interview**: six fixed questions (offer line, price/checkout, best customer, their complaint verbatim, dream outcome, do they know this product category exists) instead of 12-30 generated ones — instant, identical every run, and still enough for every later step. Interview only, and it takes no `--count`. **Every step reads and appends `CONTEXT.md` in `--dir`** — the durable answer file, so a later session in a new terminal starts warm instead of re-interviewing the director. Tell the director the interview is skippable before you ask anything; mark skipped answers `UNKNOWN` and carry on. `--refs` inlines the full `SELLING_*.md` documents for byte parity — off by default because it is ~34KB of your context, and the brief points at `references/hooks-and-virality.md` instead. Each step names the artifact it writes (`OFFER.md` → `awareness-levels.md` → `persuasive-angles.md` → `ad-hooks.md`) and the next command. Aliases: `consultation`, `brainstorm`. Flow: `references/onboarding.md`. |
 | `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` |
@@ -306,11 +309,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. **Run this BEFORE `vidfarm consult` on a new director**: one line of offer buys 20+ ideas with no key and no interview, which is the easiest first win, and their reactions to the list make the later interview better |
 | `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 |
@@ -322,7 +326,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
@@ -332,12 +336,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:
@@ -385,9 +391,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.
@@ -485,12 +491,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:

package/.agents/skills/vidfarm/references/content-ideas.md

@@ -0,0 +1,113 @@
+## 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.
+
+**This also runs FIRST for a brand-new director, before the cold-start interview.** It needs one line of offer, not an interview; it is offline, free, and keyless; and it hands the director 20+ titled videos in about a minute. That is the easiest win available on turn one, and their reactions to the list ("this one, not that one") are better raw material than anything an interview gets cold. Run it, save `content-ideas.md`, then offer the interview as the way to turn ideas into a strategy — `references/onboarding.md` → *Start with content ideas*.
+
+**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`.

package/.agents/skills/vidfarm/references/editor-workflows.md

@@ -52,8 +52,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.
 
@@ -443,6 +448,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.
@@ -518,7 +551,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
 

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

@@ -2,16 +2,79 @@
 
 Run this flow when the director signals they **don't know where to start** ("getting started", "help me set up", "I don't know where to begin") **or asks for a "consultation"** ("give me a consultation", "consult me on my offer", "I want a strategy consultation"). **"Consultation" is a first-class trigger for the brainstorm chain** — treat it as a request for the full run: the cold-start interview → awareness stages → angles → hooks (steps 1-4 below), driven by the `brainstorm/*` primitives rather than brainstormed in chat from memory. If they already know what they want, skip straight to it — never force onboarding. Directors can also jump to any single step (e.g. "just find me a good template for X" → go straight to template discovery, or "consult me on hooks" → run `brainstorm/hooks` alone).
 
+### Start with content ideas, not the interview
+
+**Unless the director explicitly asked for a consultation, run the content-ideas pass first.** Ask for their offer in **one line** — or a URL you can read — then run `vidfarm ideas --topic "<that line>"`, sharpen the frames into **20+ real titles**, and save `content-ideas.md` in their working folder. It is offline, free, needs no key and no `OFFER.md`, and takes about a minute. Method: `references/content-ideas.md`.
+
+Why this order:
+
+- **The director gets something before they give something.** An interview asks them to work first, on a product they already know, for a payoff they cannot see yet. A list of 20 titled videos is the payoff, up front.
+- **Reacting beats recalling.** "This one, not that one — our customers don't care about pricing, they care about the mess we clean up" is a better interview answer than anything they would have typed cold, and they gave it without being interviewed. Read those reactions straight into `CONTEXT.md`.
+- **It makes the interview optional, and therefore wanted.** After the list, say the interview is what turns ideas into a strategy — who to sell to, which angle, which hook — and offer the six-question short form. A director who says yes there is a director who will answer properly.
+- **It fails softer.** If they lose interest after the ideas, they still have a month of content. If they lose interest during an interview, they have nothing.
+
+Skip straight to the interview only when they asked for a consultation by name, when the ideas pass already ran, or when they say they want the strategy first.
+
+**No AI key and no wallet credits? The consultation still runs — locally, for $0.** The `brainstorm/*` primitives broker a provider on the director's saved key or the wallet, so a keyless director would be stopped at step 1. They should not be: **you** are a frontier model already sitting in their terminal, and Vidfarm does not need to hire a second one. `vidfarm consult <step>` (aliases `consultation`, `brainstorm`) prints the **identical prompt** the cloud primitive would have sent — same file, `services/brainstorm-prompts.ts`, so the two paths cannot drift — and you answer it yourself. No network, no key, no charge.
+
+```
+vidfarm consult                 # the map: four steps, which artifacts already exist
+vidfarm consult coldstart       # → the interview questions; you ask the human → OFFER.md
+vidfarm consult coldstart --short   # the SHORT form: 6 fixed questions, ~2 minutes → OFFER.md
+vidfarm consult awareness       # → awareness-levels.md      (reads OFFER.md automatically)
+vidfarm consult angles          # → persuasive-angles.md     [--problem-awareness/--solution-awareness]
+vidfarm consult hooks           # → ad-hooks.md
+vidfarm consult placement --video <path|url>   # native placement moments in an existing video
+```
+
+**Offer the short form first.** The full interview generates 12-30 questions, which is right for a director who came for a strategy session and far too much for one who wants a video today. `vidfarm consult coldstart --short` asks **six fixed questions** — offer line, price and checkout, best customer, their complaint in their own words, their dream outcome, and whether they know this kind of product exists. That is the minimum every later step reads back, so the chain still runs on it. The questions are fixed rather than generated, so the short run is instant and identical every time. Ask them in two batches of three, as written, and keep the pain and desire answers **word for word** — the hooks step quotes them. A director who wants the deeper session runs the bare `coldstart`. `--short` takes no `--count` and applies to the interview only.
+
+**Say up front that the interview is skippable — every time you start one, short or full.** Tell the director in one line that any question can be skipped, and that they can stop the whole interview whenever it gets tedious. Then work with what they gave: mark the gaps `UNKNOWN`, run the rest of the chain on the partial answers, and only come back to a gap when a later step genuinely needs it and you can say why. Never re-ask, never nag, and never make a finished interview a condition of making a video. A director who abandons a form gives you nothing; a director who answers three of six gives you an offer line and a pain quote, which is enough to start.
+
+**Every step reads and writes `CONTEXT.md` in the working folder.** This is the durable answer file: what the director said, which awareness stage was chosen, what they ruled out. Read it **before** you ask anything — never re-ask a question it already answers — and append to it (under a dated heading, never overwriting an earlier session) when the step finishes. `OFFER.md` is the polished product description; `CONTEXT.md` is the raw carry-over that makes the *next* session, in a new terminal weeks later, start warm instead of re-interviewing someone who already answered. Bare `vidfarm consult` shows whether it exists yet.
+
+**Keep one working folder per director, and run every command from it.** Pass it as `--dir ./acme-skincare` (or `cd` into it) so `OFFER.md`, `CONTEXT.md`, `awareness-levels.md`, `persuasive-angles.md`, `ad-hooks.md`, `content-ideas.md`, the storyboards, the raws and the renders all land together. See "The working folder" below.
+
+It auto-reads `OFFER.md` / `OFFER_<NAME>.md` from `--dir` (several offer files → it makes you name one rather than guessing), and `--offer` takes either a path or the offer text. `--count` mirrors the cloud primitive's bounds so nothing that works locally 400s later. The one deliberate difference: the cloud prompt inlines 34KB of `SELLING_*.md`, and the local brief points you at `references/hooks-and-virality.md` instead to protect your context — pass `--refs` for byte parity. Use the cloud primitives when the director HAS a key and wants the run off their own machine, or from the web chat where there is no terminal; use `consult` whenever they are keyless, cost-averse, or already working locally.
+
 The point of onboarding is to build **durable, reusable context** in My Files, namescoped under the director's product/offer folder, so future chats and agents can read it back. Save each artifact as Markdown with `browse_files` write (web copilot) or `vidfarm put-file` (devcli):
 
-1. **Product context** → **`OFFER.md`** (or `OFFER_<NAME>.md` — e.g. `OFFER_ACME_SKINCARE.md` — when the director runs more than one offer). Drive the interview questions with `brainstorm/coldstart` and **recommend the director save their answers into that file**, either locally next to their project or in cloud My Files. This is the durable artifact every later step reads back; `About.md` / `Interview.md` are legacy names — prefer `OFFER*.md` for anything new.
+0. **Content ideas** → **`content-ideas.md`** — **do this one first** (see *Start with content ideas* above). One line of offer in, `vidfarm ideas --topic "<line>"`, 20+ titled ideas out, saved to their folder. No key, no `OFFER.md`, no wallet. It is the fastest visible win in the whole flow, and the director's reactions to the list feed step 1. Deepen it later, once the awareness stage is known.
+1. **Product context** → **`OFFER.md`** (or `OFFER_<NAME>.md` — e.g. `OFFER_ACME_SKINCARE.md` — when the director runs more than one offer). Drive the interview questions with `brainstorm/coldstart` and **recommend the director save their answers into that file**, either locally next to their project or in cloud My Files. This is the durable artifact every later step reads back; `About.md` / `Interview.md` are legacy names — prefer `OFFER*.md` for anything new. Offer the **short form** (`vidfarm consult coldstart --short`, six fixed questions) to anyone who sounds impatient or just wants a video today, and tell them any question is skippable before you ask the first one.
 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, second pass** → update `content-ideas.md`. Step 0 already produced a list from one line of offer; now that the offer document and the awareness stage exist, work the 50-frame angle bank in `references/content-ideas.md` against them again and rewrite the weak picks. A solution-unaware audience wants different frames than a product-aware one, which is exactly what step 0 could not know. 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.
 
+### The working folder — suggest one on the first turn
+
+**Before anything else, ask the director to keep one folder on their machine for all their Vidfarm work, and use it for every command.** Suggest a name after their offer or brand (`./acme-skincare/`), and if they have no preference, propose `~/vidfarm/<brand>/` and create it. Say why in one line: every command that takes `--dir` writes there, so the strategy documents, the storyboards, the footage and the renders stay in one place, and any later session — a new terminal, a different agent, next month — can read the whole history back instead of asking the same questions again.
+
+A typical folder:
+
+```
+acme-skincare/
+  OFFER.md              # the offer, in the director's own words
+  CONTEXT.md            # durable answers, appended every consult step
+  awareness-levels.md   persuasive-angles.md   ad-hooks.md   content-ideas.md
+  brand-assets/         # logo, mascot, fonts, colors
+  product-demos/        # screen recordings, product footage
+  raws/                 # downloaded and mined clips
+  renders/              # exported mp4s
+  STORYBOARD.md         # the current video
+```
+
+Rules that make the folder pay off:
+
+- **Every `vidfarm` command runs from it** — `cd` into it, or pass `--dir`. A command run from the wrong place writes an orphan `OFFER.md` next to the shell, and the next step silently consults on nothing.
+- **One folder per offer.** A director with two products gets two folders, not two `OFFER_*.md` files in one — the artifacts are per-offer, and mixing them bleeds one brand's angles into the other's ads.
+- **Mirror it into cloud My Files** (`vidfarm put-file <file> --folder <brand>`) so the web copilot and any other machine see the same context. Local is the working copy; My Files is the one the web chat can read.
+- **When a director arrives with an existing folder, read `CONTEXT.md` and `OFFER.md` first** and tell them what you already know. Do not re-run the interview on a folder that has answers in it.
+
 **Assume multiple offers.** My Files is multi-offer (see the My Files section) — namescope every onboarding artifact under the right product/offer/region folder (`acme-skincare/OFFER.md`, not a bare `OFFER.md`) so one brand's context never bleeds into another's. When a director keeps several offers in one flat folder, name the files `OFFER_ACME_SKINCARE.md` / `OFFER_ACME_SUPPLEMENTS.md` instead.
 
 ## Default assistance pattern

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

@@ -379,6 +379,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).

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

@@ -140,12 +140,15 @@ Same ownership rule, resolved through the file directory:
 - **Generate on the user's keys** — `vidfarm generate image|video --prompt "…"` (BYOK primitives; `--place <dir>` drops the result straight into a composition).
 - **"Create an avatar" — a talking head, on the user's keys** — `vidfarm avatar "<who they are>" --say "<their line>" [--ref headshot.png] [--aspect-ratio 9:16]` (`POST /api/v1/primitives/videos/create-avatar`). An avatar is always a **video of someone speaking, with lip-synced audio** — never a still portrait, never mute. It's shot on an exact-key-color **greenscreen** plate and keyed off it in the same job, so you get a **transparent presenter** (audio preserved) to composite over any background; `--ref` (headshot or `character_sprite_card.png`) keeps the face on-model across videos, `--local` keys the plate for free with ffmpeg. AI video is the priciest generation here — offer the free `talking-head` raws shelf first when the user is cost-conscious.
 - **Search the free stock catalog** — `vidfarm media search "<meaning>" --type <image|vector|icon|video|bgm|sfx>` (shorthand: `vidfarm media icon "home"`). Returns royalty-free, commercial-safe results, each tagged with its license — honor `attribution` when `attribution_required` is true. Web/API equivalent: `GET /api/v1/primitives/media/search?type=&q=&limit=`.
+- **Buy the graphic instead of generating it — IconScout** — `vidfarm iconscout "<meaning>" --style sticker` (`GET /api/v1/primitives/iconscout/search`), then `vidfarm iconscout get <uuid> --format svg` (`POST /api/v1/primitives/iconscout/download`). Designer-made **icons, STICKERS, illustrations, 3D props and Lottie**. **This is the default path for any of those — reach for it BEFORE `generate image`.** 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. **Search is free.** Free assets download for $0 (a credit line is the only price); premium downloads run on vidfarm's own IconScout subscription for a few cents on the wallet. Works with **no key at all** — see below.
 - Never scrape or hotlink arbitrary third-party pages; the catalog above is the sanctioned licensed source, and a capture workflow's own screenshots + the user's brand assets are always fair game.
 
 ### Free media catalog — sources & keys
 
 In **cost-mode `minimize`**, prefer these keyless sources before spending anything: **Openverse** (CC/CC0 music, SFX, images) and **iconify** (icons) need no account or key, so they always resolve at $0. Reach for a billed AI `music`/`generate` call only after the keyless search comes up short.
 
+In **every** cost mode, an icon / sticker / illustration / 3D prop / Lottie should come from **IconScout**, not from an image model. `vidfarm iconscout "<meaning>" --free` costs $0 and beats a generated sticker on cleanliness (real transparent vectors, consistent style sets). In `minimize`, stay on `--free`; in `hybrid` and above, a premium download at a few cents still undercuts a single AI attempt.
+
 Icons + CC images/audio are **keyless**. Pixabay (stock photos/vectors/video) is
 **BYOK** — each user saves their own free Pixabay key, exactly like their OpenAI /
 Gemini keys, through the same provider-key surface (Settings → Bring your own keys,
@@ -158,6 +161,7 @@ it never counts as a qualified AI provider and never touches editor chat.
 | **iconify** | `icon` (SVG) | keyless — always on |
 | **openverse** | `image` (CC), `bgm`, `sfx` (CC/CC0 audio) | keyless — always on |
 | **pixabay** | `image`, `vector`, `video` (photos/illustrations/stock video) | **BYOK** — the user's own free `pixabay` provider key |
+| **iconscout** | `icon`, sticker, `illustration`, `3d`, `lottie` (designer assets) | **none needed** — runs on vidfarm's account; BYOK optional |
 
 **Check for the key before assuming it's missing.** A short `image`/`vector`/`video`
 result (or `providers_used` omitting `pixabay`) usually means no Pixabay key — but it
@@ -174,3 +178,49 @@ never touches editor chat, so it's exactly what cost-mode `minimize` wants for $
 sourcing. Icons, CC images, and bgm/sfx keep working without any key. (An operator may
 still set a platform `PIXABAY_API_KEY` server-side as a fallback for users who haven't
 saved their own, but the default posture is bring-your-own.)
+
+### IconScout — the cheap alternative to AI graphics
+
+**Rule: never generate an icon, sticker, illustration, 3D prop or Lottie with an image
+model until IconScout has come up empty.** A designer already drew it, it is already a
+clean transparent vector, and it costs a fraction of one AI attempt.
+
+```
+vidfarm iconscout "pineapple" --style sticker --free   # search (FREE, no wallet cost)
+vidfarm iconscout "rocket" --asset 3d                  # 3D props
+vidfarm iconscout "loading" --asset lottie             # Lottie animations
+vidfarm iconscout get <uuid> --format svg              # → durable vidfarm URL
+```
+
+REST equivalents:
+- `GET /api/v1/primitives/iconscout/search?q=&asset=&price=&style=&sort=&page=&limit=`
+- `POST /api/v1/primitives/iconscout/download` — body `{ uuid, format?, width?, height? }`
+
+| | |
+| --- | --- |
+| `asset` | `icon` (default), `illustration`, `3d`, `lottie`, `ai_image` |
+| `style` | `sticker`, `flat`, `line`, `glyph`, `gradient`, `isometric`, `rounded`, `doodle`, `dualtone`, `colored-outline`, `tile` |
+| `price` | `free`, `premium`, `all` (default) |
+| formats | icon `svg`/`png` · illustration `svg`/`png`/`eps` · 3d `png`/`gltf`/`glb`/`obj`/`fbx`/`blend` · lottie `json`/`lottie`/`gif`/`mp4` |
+
+**Cost.** Search is always free. A **free** asset downloads for $0 but requires the
+returned `attribution` credit — honour it. A **premium** asset runs on vidfarm's own
+IconScout subscription and bills a few cents to the wallet (`download_usd` in the search
+response, `charged_usd` on the download). Re-downloading the same asset in the same
+format is idempotent and bills once.
+
+**No key needed.** Unlike Pixabay, IconScout works out of the box — vidfarm's account
+serves the request. A user only saves their own key if they already pay IconScout, in
+which case their downloads cost nothing here. That key is the one provider key that packs
+**two** values into one secret:
+
+```
+vidfarm add-provider-key iconscout "<client_id>:<client_secret>"
+```
+
+Create the pair at <https://iconscout.com/api>, or add it under **Settings → Developer**
+(<https://vidfarm.cc/settings/developer>). Like `pixabay`, it is a catalog key, not an AI
+key — it never counts as a qualified AI provider and never touches editor chat.
+
+**`preview_url` is a thumbnail, not the asset.** Always `iconscout get` before placing
+something in a composition; the search response's preview is too small to render well.