@officexapp/vidfarm-devcli 0.21.42 → 0.21.43

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

@@ -32,6 +32,7 @@ vidfarm login --api-key vf_key_...          # validates + persists the key durab
 vidfarm serve template_<32hex>              # local server + browser, opens that template
 ```
 
+- **Suggest a working folder on the first turn, and run every command from it.** Ask the director to keep one folder per offer for all their Vidfarm work — `./acme-skincare/`, or propose `~/vidfarm/<brand>/` and create it if they have no preference. Everything lands there: `OFFER.md`, `CONTEXT.md` (the durable consultation answers), `awareness-levels.md`, `persuasive-angles.md`, `ad-hooks.md`, `content-ideas.md`, `STORYBOARD.md`, `brand-assets/`, `raws/`, `renders/`. `cd` into it or pass `--dir`; a command run from the wrong place writes an orphan file the next step cannot find. Mirror the strategy documents into cloud My Files (`vidfarm put-file <file> --folder <brand>`) so the web copilot sees them too. When a director already has a folder, **read `CONTEXT.md` and `OFFER.md` first** and tell them what you already know instead of re-asking. Layout and rules: `references/onboarding.md` → *The working folder*.
 - The API key comes from https://vidfarm.cc/settings and starts with `vf_key_`. Instead of `login`, setting the `VIDFARM_API_KEY` environment variable also works for every command — the CLI reads it from the environment or from a `.env` file in the current directory.
 - No account or key? `vidfarm serve --no-cloud` still gives a fully local editor with free local renders.
 - "Open/run template X locally" is exactly one command: `vidfarm serve <template_id>` (alias: `vidfarm <template_id>`). Do not hand-roll REST or hunt for local `.harness/` files first — `serve` and `pull` create those.
@@ -344,7 +345,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 | `references/primitives.md` | ~475 ln | **Big.** One-shot primitive routes: TTS, STT, music, avatars, overlays, greenscreen, inpaint, background removal, product placement |
 | `references/hooks-and-virality.md` | ~295 ln | **Before writing ANY hook, caption script, or re-theme**, and before a hook-variant batch. The four charges, three gates, banned openers, loop mechanics. This is the craft; the rest of the pack is mechanics |
 | `references/reviewing-renders.md` | ~140 ln | **Before you report a video as done**, or grade someone else's. The holistic pass, the common defects, frozen-render and audio verification |
-| `references/onboarding.md` | ~30 ln | Cold-start interviews, **consultations** (the `brainstorm/*` chain), strategy docs, durable director context |
+| `references/onboarding.md` | ~80 ln | Cold-start interviews, **consultations** (the `brainstorm/*` chain), strategy docs, durable director context |
 | `references/content-ideas.md` | ~90 ln | **"Give me content ideas" / "what should I post" / a month of posts.** The 50-frame angle bank, how to apply it to the director's topic, and frame → format notes |
 | `references/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 |
 
@@ -389,7 +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.
+1. If the user needs help figuring out what to make, **or asks for a "consultation"** (the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks), read `references/onboarding.md` first. **Unless they asked for a consultation by name, open with content ideas rather than the interview** — one line of offer into `vidfarm ideas --topic "<line>"` returns 20+ titled videos, offline and free, and the director's reactions to that list make the later interview far better than asking them cold (`references/content-ideas.md`). Then offer the interview as the way to turn ideas into a strategy: keyless directors run it locally for $0 with `vidfarm consult`, and `vidfarm consult coldstart --short` is the six-question short form. **Say the interview is skippable before you ask the first question**, and work with whatever they give.
 1b. If the user asks **what to make** rather than how — "give me content ideas", "what should I post", "I'm out of ideas", "I need 30 videos for the month", "content ideas for my offer <url>" — read `references/content-ideas.md` and work the 50-frame angle bank against their offer. Return 20+ titled ideas, not three.
 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`.

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

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

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

@@ -283,6 +283,7 @@ 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` |
@@ -313,7 +314,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `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\|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 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 |

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

@@ -2,6 +2,8 @@
 
 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).**

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

@@ -2,18 +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** → `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.
+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/SKILL.director.md

@@ -32,6 +32,7 @@ vidfarm login --api-key vf_key_...          # validates + persists the key durab
 vidfarm serve template_<32hex>              # local server + browser, opens that template
 ```
 
+- **Suggest a working folder on the first turn, and run every command from it.** Ask the director to keep one folder per offer for all their Vidfarm work — `./acme-skincare/`, or propose `~/vidfarm/<brand>/` and create it if they have no preference. Everything lands there: `OFFER.md`, `CONTEXT.md` (the durable consultation answers), `awareness-levels.md`, `persuasive-angles.md`, `ad-hooks.md`, `content-ideas.md`, `STORYBOARD.md`, `brand-assets/`, `raws/`, `renders/`. `cd` into it or pass `--dir`; a command run from the wrong place writes an orphan file the next step cannot find. Mirror the strategy documents into cloud My Files (`vidfarm put-file <file> --folder <brand>`) so the web copilot sees them too. When a director already has a folder, **read `CONTEXT.md` and `OFFER.md` first** and tell them what you already know instead of re-asking. Layout and rules: `references/onboarding.md` → *The working folder*.
 - The API key comes from https://vidfarm.cc/settings and starts with `vf_key_`. Instead of `login`, setting the `VIDFARM_API_KEY` environment variable also works for every command — the CLI reads it from the environment or from a `.env` file in the current directory.
 - No account or key? `vidfarm serve --no-cloud` still gives a fully local editor with free local renders.
 - "Open/run template X locally" is exactly one command: `vidfarm serve <template_id>` (alias: `vidfarm <template_id>`). Do not hand-roll REST or hunt for local `.harness/` files first — `serve` and `pull` create those.
@@ -344,7 +345,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 | `references/primitives.md` | ~475 ln | **Big.** One-shot primitive routes: TTS, STT, music, avatars, overlays, greenscreen, inpaint, background removal, product placement |
 | `references/hooks-and-virality.md` | ~295 ln | **Before writing ANY hook, caption script, or re-theme**, and before a hook-variant batch. The four charges, three gates, banned openers, loop mechanics. This is the craft; the rest of the pack is mechanics |
 | `references/reviewing-renders.md` | ~140 ln | **Before you report a video as done**, or grade someone else's. The holistic pass, the common defects, frozen-render and audio verification |
-| `references/onboarding.md` | ~30 ln | Cold-start interviews, **consultations** (the `brainstorm/*` chain), strategy docs, durable director context |
+| `references/onboarding.md` | ~80 ln | Cold-start interviews, **consultations** (the `brainstorm/*` chain), strategy docs, durable director context |
 | `references/content-ideas.md` | ~90 ln | **"Give me content ideas" / "what should I post" / a month of posts.** The 50-frame angle bank, how to apply it to the director's topic, and frame → format notes |
 | `references/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 |
 
@@ -389,7 +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.
+1. If the user needs help figuring out what to make, **or asks for a "consultation"** (the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks), read `references/onboarding.md` first. **Unless they asked for a consultation by name, open with content ideas rather than the interview** — one line of offer into `vidfarm ideas --topic "<line>"` returns 20+ titled videos, offline and free, and the director's reactions to that list make the later interview far better than asking them cold (`references/content-ideas.md`). Then offer the interview as the way to turn ideas into a strategy: keyless directors run it locally for $0 with `vidfarm consult`, and `vidfarm consult coldstart --short` is the six-question short form. **Say the interview is skippable before you ask the first question**, and work with whatever they give.
 1b. If the user asks **what to make** rather than how — "give me content ideas", "what should I post", "I'm out of ideas", "I need 30 videos for the month", "content ideas for my offer <url>" — read `references/content-ideas.md` and work the 50-frame angle bank against their offer. Return 20+ titled ideas, not three.
 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`.
@@ -2375,6 +2376,7 @@ 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` |
@@ -2405,7 +2407,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `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\|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 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 |
@@ -2650,18 +2652,79 @@ Vidfarm is in active development. Endpoints, response shapes, and the editor UI
 
 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** → `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.
+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
@@ -2681,6 +2744,8 @@ Prefer specific templates over primitives when a template exists that already ca
 
 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).**
@@ -3788,14 +3853,15 @@ Everything here is **local and free** — crop, matte/key, and trim are all `ffm
 
 Use this only when the director signals they do not know where to start.
 
-1. Read `references/onboarding.md`.
-2. Capture product context and save durable notes into the correct My Files folder.
-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.
+1. Read `references/onboarding.md`. Agree on one **working folder** for all of this director's Vidfarm work, and run every command from it.
+2. **Give them content ideas before you ask them anything.** Take the offer in one line (or a URL you read), run `vidfarm ideas --topic "<line>"`, sharpen the frames into 20+ titled videos, and save `content-ideas.md`. Offline, free, keyless. Their reactions to the list are the first real context you get.
+3. Offer the interview as the next step, not as a gate: `vidfarm consult coldstart --short` (six fixed questions) or the full `coldstart`. Say every question is skippable. Capture product context into `OFFER.md` and the durable answers into `CONTEXT.md`, in the working folder and mirrored to the right My Files folder.
+4. Determine awareness stages, persuasive angles, and hooks with the brainstorm primitives, then revisit `content-ideas.md` now that the awareness stage is known.
+5. Ask about brand assets, demos, and recurring characters; organize them in My Files.
+6. Ask about budget and map it to the cost spectrum before recommending expensive generation.
    - Set the graphics default in the same breath: icons, stickers, illustrations, 3D props and Lottie come from `vidfarm iconscout`, never from an image model. No key, no setup, search is free, free assets are $0.
-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.
+7. Search for the best matching templates and fork one strong default.
+8. 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.
+9. Transition into the ordinary template-editing workflow.
 
 Do not force onboarding on users who already know what they want.

package/SKILL.md

@@ -7,8 +7,9 @@ description: Thin entry point for agentic video editing with Vidfarm. An AI agen
 
 **You are an AI agent that was pointed at `https://vidfarm.cc/SKILL.md` to get your human started with agentic video editing.** This page is deliberately thin. It tells you what Vidfarm is, how to get hands-on in the next two minutes, and exactly which deeper files to fetch. Read this, then pull the full director skill — don't improvise Vidfarm's workflows from this page alone.
 
-**Do these two things first, before anything else:**
+**Do these three things first, before anything else:**
 
+0. **Agree on a working folder.** Ask the user to keep **one folder for all their Vidfarm work**, named after their offer or brand (`./acme-skincare/`; if they have no preference, propose `~/vidfarm/<brand>/` and create it). Run every `vidfarm` command from it, or pass `--dir`. Everything lands there — the strategy documents (`OFFER.md`, `CONTEXT.md`, `ad-hooks.md`, `content-ideas.md`), `STORYBOARD.md`, `brand-assets/`, `raws/`, `renders/` — so a later session, in a new terminal weeks from now, reads the whole history back instead of asking the same questions again. If the folder already exists, **read `CONTEXT.md` and `OFFER.md` before you ask anything.**
 1. **Install the `vidfarm` devcli** — `npm i -g @officexapp/vidfarm-devcli`. It wraps every REST route, runs a free local editor + render loop, and is by far the smoothest way to drive Vidfarm.
 2. **Log in** — `vidfarm login <email>` (one-time email code), or if you already hold a key: `vidfarm login --api-key <key>` / set `VIDFARM_API_KEY` and run `vidfarm login`. This persists the credential so every later command and `vidfarm serve` just work.
 
@@ -106,6 +107,8 @@ Otherwise, pull it over the network and load only the reference you need:
 - **Running ad experiments (finding the winning ad):** `https://vidfarm.cc/experiments.md` — **fetch this whenever the ask is about performance rather than one video**: "which ad should I run", "test these angles", "what's working", "we post daily on N channels", or any campaign that runs for weeks. It primes you as a short-form ad scientist: the KPI interview (default north star = **comments**), channel count → testing capacity, **epochs** and **rounds**, **Creative Mode** (N free-form videos, the default, ideal for gigworkers) vs **Structured Mode** (one variable, everything else pinned by a harness, your own agents only), the composition params, and the standalone `EXPERIMENTS_DIARY.md` ledger. Plan → user approval → one static handoff document per video.
 - **Crowdsourcing the editing:** `https://vidfarm.cc/crowdsourcing.md` — the client-vs-gigworker router for agentic clipper loops (a Dollar Platoon vending machine, recruiting editors, claiming tasks, proofs and payouts). This is how a Creative Mode batch gets produced in bulk.
 - **Updating Vidfarm:** `https://vidfarm.cc/update.md` — **fetch this file whenever the user asks to update/upgrade Vidfarm**, says their skill or devcli is out of date, or hits a command/route that "used to work". It's the clean uninstall→reinstall runbook for BOTH halves (the `vidfarm` skill pack and `@officexapp/vidfarm-devcli`), and it carries the current breaking-change notes — read it live rather than improvising an `npm i -g`, because the notes are exactly what a blind reinstall misses.
+- **Experimental prompts (index):** `https://vidfarm.cc/experimental` — methods under live testing. They are **not** part of the router and nothing above depends on them: read one only when the user asks for experimental prompts, or names one. Current list:
+  - **Unique Product Explainer Videos** — `https://vidfarm.cc/experimental/unique-product-explainers.md` — N customer URLs → N product-introduction videos that do not look like each other. Differentiation as an input, frame-level review, measured verification.
 - **Skill pack index (what else is installable):** `https://vidfarm.cc/skill-pack/index.json`
 - **Platform architecture (how it all fits together):** `https://vidfarm.cc/skill/vidfarm-platform`
 
@@ -113,7 +116,7 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 
 ## Router — where to go from the user's ask
 
-1. "Help me figure out what to make" **or "give me a consultation"** → `references/onboarding.md`. A consultation *is* the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks. Run the primitives; don't improvise the strategy in chat.
+1. "Help me figure out what to make" **or "give me a consultation"** → `references/onboarding.md`. **Lead with content ideas, not the interview**, unless they said "consultation": ask for their offer in one line, run `vidfarm ideas --topic "<line>"`, and hand back 20+ titled videos saved as `content-ideas.md` — offline, free, keyless, about a minute. It is the easiest first win, and what they say about the list is better interview material than an interview. A consultation *is* the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks. Run the primitives; don't improvise the strategy in chat. **On devcli with no AI key or no credits, run it keyless: `vidfarm consult` prints the same prompt for YOU to answer, for $0** — never tell a keyless director the consultation is unavailable. Offer `vidfarm consult coldstart --short` (six fixed questions) to anyone who just wants a video today, tell them any question is skippable before you ask the first one, and keep every answer in `CONTEXT.md` in their working folder so the next session starts warm.
 2. "Find a template and start" → `references/core-workflows.md`
 3. "Change / re-theme this video" → `references/editor-workflows.md`
 4. "Find footage / use our assets" → `references/assets-and-sourcing.md`