@officexapp/vidfarm-devcli 0.21.43 → 0.21.46

package/.agents/skills/vidfarm/references/assets-and-sourcing.md

@@ -1,3 +1,87 @@
+## Google search for footage — find THE shot, then clip it (paid plans)
+
+Before you download anything, you have to **find** it. `vidfarm video-search` runs a Google video search and hands back real URLs — TikTok, YouTube, Pexels/Pixabay/Mixkit, news sites, archive.org — which then feed the two collectors you already have:
+
+```bash
+vidfarm video-search "warehouse worker packing orders POV 4K" --limit 40
+vidfarm raws scan "<a result url>" --clips 8       # mine short raws out of it
+vidfarm download-video "<a result url>"            # or collect the single file
+vidfarm image-search "manila street market wide shot" --limit 40
+vidfarm news-search "AI startup funding announced" --fresh w
+```
+
+REST twins: `GET /api/v1/primitives/video-search`, `/image-search`, `/news-search` (`?q=…&max_results=…`). Field-level reference in `references/primitives.md`.
+
+**Paid plans only · flat $0.0003 per call**, whatever the result count — so ask for one **wide** page rather than paging twice.
+
+**On a free plan, or in cost mode `minimize`, run the same searches yourself for $0.** `vidfarm browser setup` installs browser-harness (about a minute, no account, no key), and then `vidfarm browse videos|images|news "<query>"` drives the user's own Chrome through the same Google surfaces. You read the SERP instead of receiving ranked JSON, but the query craft below is identical and the results are the same web. Set it up rather than telling a free user the search needs a paid plan — full page, including the download substitute for `download-video`, in `references/browser-harness.md`. The free catalog (`vidfarm media search`, `vidfarm iconscout --free`) and the public raws shelves are still the cheaper first stop.
+
+**Collect for the whole video, not one beat at a time.** Whichever route you use, sourcing is a *phase*: plan the shot list, run one pass that fills every beat, then build. See SKILL.md → *Production has PHASES*.
+
+**A public video is not a licensed video.** These searches return links with no licence attached. For client work prefer, in order: public domain → CC0 → CC BY (with credit) → stock with an explicit commercial licence → written permission from the creator. Save the source URL **and** the licence page every time.
+
+### 1. Search the SHOT, not the topic
+
+```
+[subject] + [action] + [shot/style] + [quality/orientation]
+```
+
+```
+office worker typing laptop close up 4K
+entrepreneur frustrated at desk vertical video
+Manila street traffic night handheld
+package delivery POV raw footage
+woman scrolling phone over shoulder 9:16
+factory production line wide shot 4K
+```
+
+Shot vocabulary that actually changes the results: `close up`, `wide shot`, `overhead`, `drone`, `POV`, `handheld`, `security camera`, `slow motion`, `timelapse`, `vertical`, `9:16`, `portrait`, `raw footage`, `unedited`, `no music`, `walking tour`, `dashcam`, `ambient footage`, `product demo`, `screen recording`.
+
+For footage that reads as **real UGC**, add: `phone footage`, `amateur footage`, `day in the life`, `vlog`, `behind the scenes`, `POV`.
+
+### 2. Aim at the stock libraries through Google
+
+Google often searches a stock library better than the library's own search bar:
+
+```
+site:pexels.com/videos warehouse worker
+site:pixabay.com/videos Manila traffic
+site:mixkit.co/free-stock-video entrepreneur
+site:commons.wikimedia.org factory machinery video
+site:archive.org public domain newsreel
+```
+
+Pexels footage can generally be modified and used commercially with no attribution, subject to restrictions such as misleading endorsements. Pixabay also permits broad reuse but restricts recognizable brands and standalone redistribution. Read the licence page, and keep it.
+
+### 3. Reusable YouTube footage
+
+```
+site:youtube.com "Creative Commons" warehouse footage
+site:youtube.com "CC BY" coffee production 4K
+site:youtube.com "public domain" historical footage
+site:youtube.com "royalty free footage" city traffic
+```
+
+Or search YouTube directly and apply its Creative Commons filter. **Verify the description and the original source** — uploaders mislabel footage they don't own, and the label does not transfer rights.
+
+### 4. TikTok through Google
+
+```
+site:tiktok.com/@*/video/ "warehouse"
+site:tiktok.com "day in the life" accountant
+site:tiktok.com "packing orders" small business
+site:tiktok.com "Manila commute" POV
+site:tiktok.com "remote work setup" freelancer
+```
+
+Useful additions: `before after`, `storytime`, `POV`, `tutorial`, `reaction`, `behind the scenes`, `day in the life`. Exclude the noise: `site:tiktok.com "packing orders" -dance -meme -compilation`.
+
+Google does not index every TikTok — TikTok's in-app search is better for **discovery**, Google is better when you want one exact phrase or creator. TikTok supports embedding an original post with attribution; downloading and republishing needs permission.
+
+### 5. News first, visuals second
+
+`news-search` finds the **story**; `video-search` finds the **visuals**. Run them as two stages — searching for both at once finds neither. The full timely-content method (query formulas, operators, the two-stage agent prompt, accuracy rules) is the standalone prompt at `https://vidfarm.cc/experimental/google-news-to-video.md`.
+
 ## Download a video from a website (Vidfarm fetches it for you — paid plans)
 
 **Yes, Vidfarm can download videos off the web for the user.** When someone pastes a YouTube / TikTok / Instagram / X (Twitter) / other supported post URL and wants the actual file — "grab this video", "save this clip", "get me that audio" — you do **not** need yt-dlp, a browser extension, or an apology. One primitive does it and returns a durable Vidfarm-hosted asset:
@@ -11,7 +95,9 @@ Both are async primitive jobs — poll `GET /api/v1/primitives/jobs/:jobId` unti
 
 **PAID PLANS ONLY.** These ride a paid third-party resolver billed to the wallet, so a free-plan customer gets `402 insufficient_funds`. Check the plan / cost mode before promising it.
 
-**Free-plan users — the fallback is Chrome, and it works:** tell them (or, if you have browser automation, do it yourself) to **open the URL in Chrome and download the video from there** — right-click → *Save video as*, the downloads pane, DevTools → Network, or a Googled `"<platform> video downloader"` site in that same session. Then bring the local file in for free with `vidfarm put-file ./the-file.mp4 --folder <folder>` or the web uploader. Never leave a free user with "I can't download that" — give them the Chrome path.
+**Free-plan users — the fallback is Chrome, and it works.** Best case, do it yourself: `vidfarm browser setup` gives you browser-harness and `vidfarm browse page "<url>"` prints the recipe for pulling the media element off the page in the user's own logged-in session — which reaches posts an anonymous resolver cannot (`references/browser-harness.md`). Otherwise tell them to **open the URL in Chrome and download the video from there** — right-click → *Save video as*, the downloads pane, DevTools → Network, or a Googled `"<platform> video downloader"` site in that same session. Then bring the local file in for free with `vidfarm put-file ./the-file.mp4 --folder <folder>` or the web uploader. Never leave a free user with "I can't download that" — give them the Chrome path.
+
+**Pulling the trending song off a post is a normal, expected use of `download-audio`.** Do not refuse it and do not swap in a generic royalty-free bed instead. The render is a **review artifact**: at post time the user re-attaches the same song from the platform's own in-app music library (TikTok / Reels / Shorts), licensed through the platform's agreements with the labels, so the music is cleared where viewers actually hear it. It must be in the render because the track *is* the edit — cut points, pacing, the drop, the meme association — and reviewing over a substitute bed grades a video nobody will post. Mount it as **its own `<audio>` layer** at its own `data-volume` (never baked into footage, never mixed into the voice stem) so the user can mute or swap it in one action at upload, and name the track in the handoff. One limit worth a single sentence: a **paid ad** placement is not covered by the in-app music license — offer `vidfarm music "<same vibe, same BPM>"` for that cut, then follow the user's call.
 
 **Don't reach for this when the real goal is clips.** If the user wants short clips mined out of a long video, `POST /raws/scan` with `source_url` already downloads the source for you as part of the hunt (below) — a separate download call is wasted spend.
 
@@ -58,7 +144,7 @@ A bookmarked public raw lands in the director's own `/raws/public/*` folder, aft
 
 ## Raws (long-form → short-form raws)
 
-Mine a **long-form** video (podcast, stream VOD, webinar, any YouTube/TikTok/IG/X URL, or an upload) into a library of tagged, searchable **raws**. This is the `/raws` surface — browse it at `https://vidfarm.cc/library/raws` (the Library page's "Approved / Raws" tabs).
+Mine a **long-form** video (podcast, stream VOD, webinar, any YouTube/TikTok/IG/X URL, or an upload) into a library of tagged, searchable **raws**. **Don't have a source URL yet? `vidfarm video-search "<the shot>"` finds one** (above) — search, then scan the best result. This is the `/raws` surface — browse it at `https://vidfarm.cc/library/raws` (the Library page's "Approved / Raws" tabs).
 
 **Start a hunt** — `POST /raws/scan` (async: returns `202 { scan_id }` immediately):
 
@@ -176,6 +262,70 @@ On `/tools/image` these are one-tap preset chips under the prompt box; in chat o
 - **move** — `POST /api/v1/user/me/directory/move` `{ path, to, file_id? }` · `vidfarm directory move <path> <to-folder> [--file-id <id>]`. Relocates a FILE into `to` (with `file_id`) or nests a whole FOLDER under `to`. **Same root only** (`/files`·`/temp`·`/raws`·`/approved`); metadata-only, so S3 objects are untouched.
 - **copy** — `POST /api/v1/user/me/directory/copy` `{ path, to?, file_id?, new_name? }` · `vidfarm directory copy <path> [<to-folder>] [--file-id <id>] [--as <name>]`. Duplicates a file/folder sharing the same underlying S3 object (cheap, no re-upload). Same root only, `/files`·`/temp`·`/raws` (not `/approved` — a ready post is a single publishable unit; not `/projects` — read-only). Omit `to` to duplicate in place.
 
+**Sharing a folder publicly (crowdsourcing + agent-readable libraries).** Any folder in **any** root can carry share tokens — one folder, as many links as you want, each with its own mode:
+
+- `read` — browse **and vector-search** the folder. Nothing else.
+- `upload` — read + upload files + create subfolders. **No rename, no delete.** This is the crowdsourcing link.
+- `edit` — upload + rename + delete inside the shared subtree.
+
+Minting or editing a link is **paid** (unlike the rest of the directory routes, which are free on any plan); **visiting** one needs no account at all, so a link keeps working for its holders regardless of their tier. devcli twins: `vidfarm directory share <path> --mode read|upload|edit [--label <text>]` (prints the URL), `vidfarm directory shares [path]`, `vidfarm directory share-update <token> [--mode] [--label] [--disable|--enable]`, `vidfarm directory unshare <token>`.
+
+A token is scoped to **exactly one subfolder and everything under it** — never a sibling, never a parent, so a leaked link cannot walk the rest of the drive. The shared base folder itself can never be renamed or deleted through its own token. Owner routes: `GET|POST /api/v1/user/me/directory/shares`, `PATCH|DELETE …/shares/<token>` (`{ path, mode, label }`; `disabled: true` cuts a link off instantly and is reversible). Public routes, no auth: `GET /api/v1/share/:token/directory` (`?path=`), `POST /api/v1/share/:token/directory/search` `{ query, path?, mode? }`, plus `…/directory/folders`, `…/directory/rename`, `…/directory/delete`, `…/attachments/upload`. The human page is `/directory/preview/<token>/<path…>`.
+
+**Uploading over ~6 MB through a share link:** `…/attachments/upload` is a multipart POST through the API Lambda, whose request body caps at about 6 MB — a bigger file answers **413** before the handler runs. Use the two-step presigned path instead (the share page's own uploader does): `POST /api/v1/share/:token/attachments/presign` `{ file_name, content_type?, size_bytes?, folder_path? }` → `{ transport: "presigned", file_id, storage_key, folder_path, upload: { method, url, headers } }`; PUT the raw bytes to `upload.url` with those headers; then `POST /api/v1/share/:token/attachments/finalize` `{ file_id, file_name, content_type, size_bytes, storage_key, folder_path }` to record the file. A server with no presigned transport answers `transport: "server"` and you post the multipart form. Ceiling is the owner's own: 200 MB.
+
+In the UI: the file explorer's folder kebab → **Share…**, the `⤴ Share` toolbar button, and the folder kebabs on `/library` (**Raws** and **Approved** tabs). `⤴ Manage Shares` lists every token you own.
+
+**Working a link you were GIVEN — `vidfarm shared` (no account, no API key).** This is the visitor side, and it is how a gigworker's agent collaborates on a client's drive. `<link>` is the URL from the task brief (or a bare `dsh_…` token plus `--host`):
+
+```bash
+vidfarm shared info  "$LINK"                       # folder, mode, what you may do
+vidfarm shared ls    "$LINK" [subfolder]           # browse
+vidfarm shared search "$LINK" "founder talking head, no captions"
+vidfarm shared get   "$LINK" hero.mp4 --out ./work        # one file (--all for the folder)
+vidfarm shared mkdir "$LINK" task-014-yvette              # your own subfolder (upload/edit)
+vidfarm shared put   "$LINK" final.mp4 --subfolder task-014-yvette
+```
+
+`shared put` runs presign → PUT → finalize, so it is not bound by the ~6 MB multipart ceiling; it falls back to multipart automatically when the server has no presigned transport.
+
+**The crowdsourcing pattern (DollarPlatoon custom-request vending machine).** Two links per campaign, minted once and reused across every task:
+
+```bash
+vidfarm directory share /files/crowdsourced/acme --mode upload --label "Acme drop box"
+vidfarm directory share /raws/acme-brand        --mode read   --label "Acme footage (read only)"
+```
+
+Put both in the task payload as plain fields — `assets_link` (read), `upload_link` (upload), `upload_subfolder` — and state the proof requirement: *"create your subfolder in the upload link, put the MP4 + project files there, and submit the public MP4 url as the proof"*. Organize the drop box one of two ways, and say which in the task: **worker-named subfolder** (one link for the whole campaign, each worker runs `shared mkdir`) or **task-owned subfolder** (pre-create `/…/acme/task-014` and mint the link onto *that* folder, so a worker on one task cannot see another's). Collect with the ordinary owner commands (`directory ls`, `directory search --path …`) and close the batch with `directory share-update <token> --disable`. Editors who only need footage get a `read` link on `/raws` — vector search included, nothing writable.
+
+**Driving the machines from the terminal — `vidfarm gigs`.** The whole loop is scriptable, from both sides, and the two halves of a task (the brief and the files) are posted together:
+
+```bash
+# CLIENT (paid plan — the DollarPlatoon key comes from your vidfarm account)
+vidfarm gigs machines                       # your two standing machines + gig ids + invite links
+vidfarm gigs add-task --task "60s explainer for acme.com" --price 0.50 --tags shortform \
+  --assets-link "$READ_LINK" --upload-link "$DROP_LINK" --subfolder task-014 \
+  --proof "MP4 in your subfolder" --proof "public MP4 url in the proof body"
+vidfarm gigs ring-bell --title "Acme wants 7 shorts this week" --machine custom_requests
+vidfarm gigs tasks                          # what is still unclaimed in the FIFO queue
+vidfarm gigs proofs --status pending        # what came back, with the playable link
+vidfarm gigs approve PRF_01H… --feedback "Great hook, keeping it."
+vidfarm gigs reject  PRF_01H… --tag not_selected   # a pass — costs the worker NO reputation
+
+# GIGWORKER (free, no vidfarm account: export DOLLARPLATOON_API_KEY=…)
+vidfarm gigs join-feed && vidfarm gigs feed  # who is asking for videos right now
+vidfarm gigs join <invite-url>               # or --registry to list every joinable machine
+vidfarm gigs work                            # work waiting across every machine you joined
+vidfarm gigs claim <gig-id>                  # claim off the FIFO queue — note the task id
+vidfarm gigs submit <gig-id> --task <task-id> --proof https://…/final.mp4
+```
+
+Key resolution is `--dp-key` → `DOLLARPLATOON_API_KEY` → `GIGDESK_API_KEY` → the paid account's own key via `GET /api/v1/user/me/marketplace`. **Review promptly: silence is approval** — an unreviewed proof auto-approves after the gig's review timeout (default 48h) and you pay for it.
+
+A link is a **bearer credential**: whoever holds it has that mode. Prefer `upload` over `edit` for crowdsourcing (nobody can delete a colleague's work), keep one link per campaign rather than one per worker, and disable it the day the batch closes. **Free tier fallback:** minting is paid, so a free user puts a Google Drive / Dropbox / WeTransfer folder URL into the same `assets_link` / `upload_link` fields — worker agents treat them as plain URLs. What is lost: vector search, the scoped subtree, and the one-command `vidfarm shared put`.
+
+Two things to know. **Search is included in `read`** — that is what makes a shared folder useful to a gigworker's AI agent: it finds footage by meaning instead of paging through folders. The query embedding is billed to the **folder's owner**, not the visitor. And **only `/files` and `/temp` accept direct uploads** — `/raws`, `/approved` and `/projects` have no plain-upload backend even for the owner (raws are scanned/imported, approved posts are published renders, projects are fork storage), so an `upload` link there only creates folders. To crowdsource footage, share a `/files` folder for `upload` and import the contributions into `/raws` yourself.
+
 The web copilot exposes the same three as `browse_files action=rename|move|copy`. If you rename or move a character's folder, update the `id`, `sprite_card_path`, and `about_path` inside its manifest to match (and rename the `<character_id>.json` file itself).
 
 **Assume My Files is multi-offer.** A user often runs more than one product, offer, brand, or region, and namescopes assets into folders accordingly — by product (`acme-skincare/`, `zensleep/`), by offer/campaign (`summer-sale/`), by region (`us/`, `eu/`), by asset type (`logos/`, `ugc-clips/`), or any arbitrary scheme. There is **no fixed layout** — read the `folders` tree first and reason about how this user organized things. Before pulling assets for a task, infer which folder(s) match the product/offer/region the current composition is about (match folder names to the composition title, video context, and what the user said), then scope reads to that folder so you never mix one brand's logo/product-shot/music into another brand's video. If the target offer is ambiguous, ask which product/offer/region (or which folder) this work is for rather than guessing across offers.

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

@@ -2,7 +2,7 @@
 
 A free (unpaid) account's `vidfarm-api-key` is a **real key**: it authenticates on every route, and `vidfarm login` / `whoami` work normally. Plan is enforced per route, not at auth:
 
-- **Free on any plan** — `GET /api/v1/user/me` (identity), `/api/v1/user/me/provider-keys` (bring-your-own-key), `GET /api/v1/user/me/wallet` (reads $0.00), `GET /api/v1/user/me/tasks`, and the `/api/v1/user/me/directory*` file-tree routes (browse, search, folder, rename, move, copy, shares).
+- **Free on any plan** — `GET /api/v1/user/me` (identity), `/api/v1/user/me/provider-keys` (bring-your-own-key), `GET /api/v1/user/me/wallet` (reads $0.00), `GET /api/v1/user/me/tasks`, and the `/api/v1/user/me/directory*` file-tree routes (browse, search, folder, rename, move, copy) — but **not** `…/directory/shares*`: minting a public share link is paid. Visiting someone's link (`/api/v1/share/:token/*`, `/directory/preview/*`) needs no account at all. **The marketplace is paid-only end to end** — every `/marketplace*` page and route (the agent directory included) answers the upgrade wall for a free account, the sidebar Marketplace link is hidden for them, and the two DollarPlatoon vending machines are provisioned on the paid plan (on upgrade, for an account that started free).
 - **Paid routes answer `402 { type: "upgrade_required", upgrade_url: "/pricing", run_locally_url: "/help" }`** — never a 401. A `401` means the key is missing/invalid/revoked, so don't tell a free user to re-authenticate when they hit a 402.
 - When you see a 402: say plainly that the action needs a paid plan, then offer the two real paths — upgrade at `/pricing`, or keep going for free locally (`vidfarm serve`, local render, local decompose, own-provider keys).
 
@@ -273,7 +273,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm visibility <forkId> <private\|public>` | `PATCH .../compositions/:forkId/visibility` | set visibility |
 | `vidfarm clone <forkId>` | `POST .../compositions/:forkId/clone` | clone a fork |
 | `vidfarm share-link <forkId>` | `POST .../compositions/:forkId/share-links` | mint a share URL |
-| `vidfarm approve --video <url\|file> --caption "…"` | `POST /api/v1/approved/posts` | approve post — takes media by **`url`**. Local `--video`/`--media` auto-upload to **durable My Files** via presign→S3→finalize (up to **200 MB**, bypasses the ~6 MB Lambda limit) then approve with that URL, so the share video **never expires**; also accepts a `/files…` path. `--temp` opts into the 30-day temp store (throwaway preview only). Prints `share_url` |
+| `vidfarm approve --video <url\|file> --caption "…"` | `POST /api/v1/approved/posts` | approve post — takes media by **`url`**. Local `--video`/`--media` auto-upload to **durable My Files** via presign→S3→finalize (up to **200 MB**, bypasses the ~6 MB Lambda limit) then approve with that URL, so the share video **never expires**; also accepts a `/files…` path. `--temp` opts into the 30-day temp store (throwaway preview only). `--thumbnail <url\|file>` picks the social-card poster; omit it and a frame ~1s into `--video` is extracted into `/files/approved`. Prints `share_url` |
 | `vidfarm posts` / `vidfarm post <id>` | `GET /api/v1/approved/posts[/:id]` | browse approved posts |
 | `vidfarm schedule <postId> --at <iso> --to <dest>` | `POST /api/v1/approved/posts/:postId/schedules` | schedule a post |
 | `vidfarm schedules <postId>` | `GET /api/v1/approved/posts/:postId/schedules` | browse scheduled posts |
@@ -281,12 +281,18 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm whoami` | `GET /api/v1/user/me` | who am I (also prints the active cost mode) |
 | `vidfarm cost-mode [minimize\|hybrid\|rich-ai\|pure-videogen]` | (local `~/.vidfarm/cost-mode.json`) | show/set the money-saving preference every billed command respects; no arg = show + explain each; `--clear` forgets it |
 | `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 browser [status\|setup\|doctor]` | local (installs [browser-harness](https://github.com/browser-use/browser-harness) via `uv`) | **Free browser sourcing — the $0 substitute for the PAID `video-search` / `image-search` / `news-search` / `download-video` primitives.** `setup` runs `uv tool install --python 3.12 --upgrade --force browser-harness`, writes browser-harness's own SKILL.md into `.agents/skills/browser-harness/`, and prints the one step nothing can automate: Chrome → `chrome://inspect/#remote-debugging` → tick *Allow remote debugging* (macOS may then need `browser-harness mac-approve`). After that you drive the user's own logged-in Chrome over CDP. `status` = what's installed, `doctor` = connection check. `vidfarm doctor` reports it as `browser control` (⚠ when absent — it is optional, not required). **Offer it to every free-plan user and everyone in `cost-mode minimize` before saying a search needs a paid plan**, and ask first: it drives their personal browser. Aliases: `browser-harness`, `bh`. Full page: `references/browser-harness.md`. |
+| `vidfarm browse <videos\|images\|news\|page> "<query\|url>" [--limit N] [--legacy] [--run] [--json]` | local (pure text; `--run` pipes into browser-harness) | **The browse recipe for one sourcing job**: which Google surface to open (`udm=7` videos · `udm=2` images · `udm=12` news; `--legacy` for the old `tbm=…`), what to extract off the page, and the vidfarm command it feeds (`raws scan` / `clipper` / `put-file`). Prints rather than runs by default — Google's markup moves, so an agent that reads and adapts the recipe beats one that runs it blind; `--run` when you have already browsed successfully this session. `page` mode substitutes for `download-video` by pulling the media element off the post in the user's own session. |
+| `vidfarm agent-image "<subject>" [--items "a,b,c"] [--single] [--out ./sheet.png] [--folder <f>] [--check]` | local (pure text) | **Image generation the AGENT already pays for — free in EVERY cost mode, `minimize` included.** Google Antigravity / Gemini CLI (Nano Banana / Imagen) and OpenAI Codex / ChatGPT (`gpt-image`) include image generation in the subscription; **Claude Code does not** — Anthropic ships no image model. Prints the generation prompt (the same key-plate craft as `handoff image`), the steps, the local cut (`sticker-pack`/`cutout`) and the `put-file` import. Calls nothing and spends nothing, so it never gates and needs no `--yes`. `--check` (or no args) reports whether this host has the capability, from env markers plus the known-hosts table — **a hint only; your own tool list is the authority, so never claim a tool you do not have**. Free stock, `iconscout` and `mask` still come first. Aliases: `agent-imagegen`, `own-image`, `native-image`. Full page: `references/agent-included-imagegen.md`. |
 | `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 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 via `vidfarm browser setup` + `vidfarm browse` → `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 video-search "<query>" [--limit n] [--fresh d\|w\|m\|y] [--duration short\|medium\|long] [--resolution high\|standard] [--region r]` | `GET /api/v1/primitives/video-search` | **GOOGLE VIDEO SEARCH — how you SOURCE footage.** Returns real source URLs off the open web (TikTok, YouTube, Pexels/Pixabay/Mixkit, news, archive.org), which go straight into `vidfarm raws scan <url>` (mine clips) or `vidfarm download-video <url>` (collect the file). Search the **shot**, not the topic: `[subject]+[action]+[shot/style]+[quality/orientation]`. Google operators work — `site:pexels.com/videos`, `site:tiktok.com "packing orders" -dance`, `"exact phrase"`. **PAID PLAN · flat $0.0003 per call** whatever the result count, so ask for one WIDE page (`--limit 40`) instead of paging. Returns LINKS with **no licence** — check rights before reuse. Aliases: `videosearch`, `search-video` |
+| `vidfarm image-search "<query>" [--limit n] [--type-image photo\|clipart\|gif\|transparent] [--color c] [--size s] [--layout Square\|Tall\|Wide]` | `GET /api/v1/primitives/image-search` | Google image search — reference stills, textures, logos, product shots. Same operators. **PAID PLAN · flat $0.0003 per call.** For licence-checked, royalty-free assets prefer `vidfarm media search --type image` (free); these are LINKS with no licence. Aliases: `imagesearch`, `search-image` |
+| `vidfarm news-search "<query>" [--fresh d\|w\|m\|y] [--limit n] [--region r]` | `GET /api/v1/primitives/news-search` | Google News — recent real events, so an agent can build **timely** content. News finds the STORY; run `video-search` after for the VISUALS (searching both at once finds neither). **PAID PLAN · flat $0.0003 per call.** Full method: <https://vidfarm.cc/experimental/google-news-to-video.md>. Aliases: `news`, `newssearch`, `search-news` |
 | `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>` |
@@ -296,7 +302,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm download-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download just the AUDIO track (music/voice) off a website post into a durable audio file. **PAID PLAN**. Alias: `download-post-audio` |
 | `vidfarm recycle <source>` | `POST /api/v1/primitives/social/recycle` + poll | RECYCLE a Reddit/X source into reusable JSON ("tweet to tiktok", "reddit to tiktok"): thread + comments, subreddit threads, X thread + replies, or an account's posts — text, author + avatar, stats, media URLs. `--out` saves the full payload. **PAID PLAN**. Aliases: `recycle-social`, `tweet-to-video`, `reddit-to-video` |
 
-> **Free plan / `cost-mode minimize`:** both download commands are gated by `guardBilled` and will refuse or warn. The free path is **Chrome**: open the URL in a real browser, save the file off the page (right-click → *Save video as*, downloads pane, or a Googled `"<platform> video downloader"` site), then `vidfarm put-file ./the-file.mp4 --folder <folder>` to bring it in for $0. The CLI prints these steps on a 402. Never tell a free user the video simply can't be downloaded.
+> **Free plan / `cost-mode minimize`:** both download commands are gated by `guardBilled` and will refuse or warn. The free path is **Chrome** — and you can drive it yourself: `vidfarm browser setup` then `vidfarm browse page "<url>"` (see `references/browser-harness.md`). Otherwise the user opens the URL in a real browser and saves the file off the page (right-click → *Save video as*, downloads pane, or a Googled `"<platform> video downloader"` site), then `vidfarm put-file ./the-file.mp4 --folder <folder>` to bring it in for $0. The CLI prints these steps on a 402. Never tell a free user the video simply can't be downloaded.
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
 | `vidfarm files --search "…" [--folder <path>]` | `POST /api/v1/user/me/attachments/search` | find My Files assets by MEANING (keyword + vector over name/folder/notes) |
 | `vidfarm get-file <id> [dest] [--print]` | (resolve id → view_url, then stream/print) | read one My Files asset |
@@ -314,7 +320,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. **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 ideas [topic] [--topic "<offer>"] [--family <name>] [--families] [--stages] [--stage <name\|n>] [--angles] [--angle <name>] [--grid] [--count <n>] [--json]` | (local — **offline, free, no AI call**) | **"What should I post?"** — the three content-idea banks, 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. `--stages` prints the 5-stage awareness ladder (what each stage believes, what the video must do, its frames, its angles, and what it may ask for); `--angles` prints the 44 problem angles by family — hold the frame and change the angle when a topic is "already covered"; **`--grid --topic "<offer>" --count 30` lays out a balanced month**, one row per video, in the default stage mix. It hands over combinations, 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 |
@@ -354,6 +360,8 @@ What it flags:
 | `badge-chip-row` | error | 2+ sibling small rounded filled tags — the "✓ No Credit Card Needed · ✓ 30-Min Trial" strip |
 | `static-pill` | error | ONE filled, padded, ≥20px-radius capsule around static text — a stat/label badge like "10 hrs / week", "STEP 2", "EP.01". Skips active-word `spotlight`/`karaoke` highlights (the only legitimate pill) and mock social UI (chat bubbles, comment cards — mark yours `data-vf-mock-ui` if the heuristic misses it) |
 | `card-panel` / `glass-card` | error | A rounded box with a border/shadow/`backdrop-filter` wrapping 2+ elements. A tight legibility **band** (radius ≤8px, one text run, no border/shadow) stays legal |
+| `layout-template` | error | The frame composed like a **page**: 3+ stacked text blocks in one container ending in a call to action — headline + subheading + CTA, the web hero/modal body. Fires with or without the box around it, because the STACK is the tell. Three stacked lines with no CTA are a legitimate title card and pass |
+| `modal-scrim` | error | A full-frame backdrop that is **blurred AND dimmed** — the website-modal staging that pushes the picture back so a floating block pops. Blur alone passes (the blurred fill behind a 16:9 clip in a 9:16 frame is a real technique); it needs the dimming too, and a bed faded under `opacity:0.25` is an ambient texture wash, not staging, so it passes as well |
 | `gradient-text` | error | `background-clip:text` gradient headline fills |
 | `clickable-element` | error/warn | `<button>`, `<form>`, `<input>`; `<a href>` warns |
 | `web-framework-classes` | error/warn | Bootstrap/Tailwind class tokens (`btn`, `badge`, `card`, `hero`, `col-*`, `rounded-full`, `shadow-lg`, `backdrop-blur`, `bg-gradient-to-*`) or a linked CSS framework. A `<script>` CDN for GSAP/anime.js is fine |
@@ -384,16 +392,17 @@ The four modes, quoted as **cost per finished video**. The first two are spend p
 
 | Mode | Per video | Posture |
 |---|---|---|
-| `minimize` | **$0 — explicitly free** | free local engines + free stock media only; billed ops refuse without `--yes` |
+| `minimize` | **$0 — explicitly free** | free local engines + free stock media, plus any image generation the AGENT's own subscription already includes; billed ops refuse without `--yes` |
 | `hybrid` *(default recommendation)* | **~$0.01–$1** | free where free, AI where it clearly wins; each billed op prints its cost |
 | `rich-ai` | **$1+** | AI video gen mints **reusable greenscreen raws** (saved to the library, reused later); motion is hyperframes HTML/CSS over the keyed raws |
 | `pure-videogen` | **$5+** | script in text → storyboard in images → frame-by-frame scene generation. No reuse, no HTML motion |
 
 **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 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.
+`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. `vidfarm video-search` / `image-search` / `news-search` (Google) are **paid-plan** but flat **$0.0003 per call** — two orders of magnitude under one AI image attempt — so they do not gate in any cost mode; in `minimize`, one wide search beats one generation every time. They are still **paid-plan** routes, though — on a free plan they 402, and the answer there is `vidfarm browser setup` + `vidfarm browse videos|images|news "<query>"`, which is free and never gates.
 
 - **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 can use IMAGE GENERATION — when the agent already owns it.** `minimize` bans *billed* AI, not AI. If the agent driving the terminal includes image generation in its own subscription — **Google Antigravity / Gemini CLI (Nano Banana / Imagen) and OpenAI Codex / ChatGPT (`gpt-image`) do; Claude Code does NOT**, because Anthropic ships no image model — then generating a graphic costs Vidfarm $0 and the provider $0 extra, so it is allowed with no `--yes` and no gate. `vidfarm agent-image --check` reports whether this host has it (env sniffing + a known-hosts table — treat it as a hint and check your own tool list); `vidfarm agent-image "<subject>" --items "a,b,c"` prints the prompt, the plate rules and the cut + import commands. Order on the ladder: free stock → `iconscout` → `mask` → **your own image tool** → the human hand-off below → a confirmed billed `generate`. It is images only — no agent subscription includes video generation, so AI video stays gated. Full page: `references/agent-included-imagegen.md`.
 - **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.
@@ -421,7 +430,8 @@ Local, wallet-free Vidfarm is a **three-part toolchain** that composes — insta
 ```bash
 npm install -g @officexapp/vidfarm-devcli    # the `vidfarm` orchestrator
 npm install -g hyperframes                    # Vidfarm's open-source render/animation engine (whitelabel)
-brew install ffmpeg   # or apt install ffmpeg — a system ffmpeg on PATH is honored first; ffmpeg-static is bundled as a fallback
+# ffmpeg is BUNDLED (ffmpeg-static + a per-platform ffprobe) — install one only if doctor asks:
+#   brew install ffmpeg / apt install ffmpeg / winget install Gyan.FFmpeg
 vidfarm doctor                                # ✓/⚠/✗ for node, ffmpeg, hyperframes, Chrome, auth, keys, skills
 ```
 
@@ -498,7 +508,10 @@ 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 --families                # the 50 content frames, by family
+vidfarm ideas --stages                  # the 5-stage awareness ladder, in full
+vidfarm ideas --angles                  # the 44 problem angles, by family
+vidfarm ideas --grid --topic "<offer>" --count 30   # a balanced month: stage x angle x frame
 vidfarm ideas --topic "bookkeeping for trades" --count 20
 ```
 

package/.agents/skills/vidfarm/references/browser-harness.md

@@ -0,0 +1,93 @@
+## Free browser sourcing — drive the user's own Chrome instead of paying
+
+The sourcing ladder starts at *"your own browser control, if you have it."* **browser-harness is how you have it.** It attaches you to the user's already-running Chrome over one CDP websocket, so you can search, scroll, click and download on their own logged-in session and their own IP — at **$0**, with no Vidfarm plan, no API key, and no wallet.
+
+That matters because the four routes an agent reaches for when sourcing footage are all **paid plans only**. A free-tier director asking the single most common question in the product — *"find me a clip of X"* — otherwise gets a 402. With browser-harness they get footage.
+
+| Paid Vidfarm primitive | Free browser substitute | What you lose |
+|---|---|---|
+| `vidfarm video-search "<shot>"` ($0.0003/call) | `vidfarm browse videos "<shot>"` → Google Videos | You read the SERP yourself; no ranked JSON |
+| `vidfarm image-search "<shot>"` ($0.0003/call) | `vidfarm browse images "<shot>"` → Google Images | Full-res URLs need a click-through per result |
+| `vidfarm news-search "<topic>" --fresh w` ($0.0003/call) | `vidfarm browse news "<topic>"` → Google News | No `--fresh` operator; use Google's own Tools → time filter |
+| `vidfarm download-video <url>` (wallet resolver) | `vidfarm browse page "<url>"` → save the media off the page | Manual per URL; but a logged-in session reaches posts an anonymous resolver cannot |
+| `vidfarm recycle <reddit/x url>` | browse the thread and read it | No structured comment tree — you extract by hand |
+
+**Say the trade honestly.** The paid primitives return clean ranked JSON in one call and are genuinely cheap — two orders of magnitude under one AI image attempt. Browser sourcing costs no money and more of your turns. In `minimize` it is the right call every time. In `hybrid` prefer it for a wide first sweep and pay for the primitive when you need many precise results fast. In `rich-ai` / `pure-videogen` don't bother — the spend is already authorized and your turns are worth more.
+
+### Setup — one command
+
+```bash
+vidfarm browser setup        # installs browser-harness via uv, registers its skill, prints the Chrome step
+vidfarm browser status       # what's installed
+vidfarm browser doctor       # connection check (wraps `browser-harness --doctor`)
+```
+
+`setup` does three things and then stops at the one it cannot do for the user:
+
+1. `uv tool install --python 3.12 --upgrade --force browser-harness` (it prints the `uv` installer first if `uv` is missing).
+2. Writes `browser-harness`'s own SKILL.md into `.agents/skills/browser-harness/SKILL.md` beside the vidfarm pack — **read that file before your first browse**; it carries the accessibility-tree-first workflow, tab handling, downloads, iframes and the CDP escape hatch. This page is the Vidfarm-side routing, not a replacement for it.
+3. Prints the **one manual step**: Chrome → `chrome://inspect/#remote-debugging` → tick *"Allow remote debugging for this browser instance"*. Nothing can do this for the user. On macOS a per-connection permission sheet may follow — `browser-harness mac-approve` clears it.
+
+`vidfarm doctor` reports it as `browser control`, at `⚠` when absent. It is optional: a box without it is a healthy box, just a more expensive one.
+
+**Proactively offer it to every free-plan user.** Before you tell someone the search primitive needs a paid plan, offer the setup — it is about a minute, it is free forever, and it converts "I can't source that" into "I found six candidates." Same for anyone in cost mode `minimize`. Do not install it silently: it drives their personal browser, so ask first and say what it does.
+
+### The browse recipes
+
+`vidfarm browse <videos|images|news|page> "<query|url>"` prints the recipe for one sourcing job — the Google surface to open, the extraction to run, and the vidfarm command it feeds:
+
+```bash
+vidfarm browse videos "warehouse worker packing orders POV 4K"
+vidfarm browse images "manila street market wide shot"
+vidfarm browse news   "AI startup funding announced"
+vidfarm browse page   "https://www.tiktok.com/@user/video/123…"
+vidfarm browse videos "…" --run     # pipe it straight into browser-harness instead of printing
+vidfarm browse videos "…" --json    # the same recipe as data
+```
+
+Default is **print, not run** — deliberately. Google's markup moves, and an agent that reads the recipe and adapts it beats one that runs it blind. Reach for `--run` when you have already browsed successfully this session.
+
+**Query craft carries more weight here than anywhere else in the pack** — Google is the ranking function now, not Vidfarm. Use the shot formula (`[subject] + [action] + [shot/style] + [quality/orientation]`), the `site:` aims at Pexels / Pixabay / Mixkit / archive.org / Wikimedia, and the Creative-Commons YouTube operators. All of that is in `references/assets-and-sourcing.md` → *Google search for footage*; it applies unchanged whether you paid for the search or browsed it.
+
+Surface parameters: the recipes use Google's current `udm=` (`2` images, `7` videos, `12` news). If a surface comes back looking wrong, rerun with `--legacy` for the older `tbm=isch|vid|nws`.
+
+### Collecting raws with it — the loop that matters
+
+Browser sourcing is at its best on a **raws collection pass**, not on a single lookup. You are filling a shot pool, so batch it:
+
+```bash
+# 1. plan the shot list first (see "Phase 0" in SKILL.md) — never browse without one
+vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"
+
+# 2. one browse per SHOT, not per video
+vidfarm browse videos "founder frustrated at desk vertical raw footage"
+
+# 3. mine each good hit into short tagged raws — free, local
+vidfarm raws scan "<result url>" --duration 10 --aspect 9:16 --no-text --prompt "<the beat this covers>"
+vidfarm clipper  "<result url>" --start 00:01:12 --end 00:01:19   # or one surgical cut
+
+# 4. everything lands in the searchable local library, reusable across every later video
+vidfarm raws search "founder looking defeated"
+```
+
+If `raws scan` cannot bootstrap a remote URL without a key, that is exactly the gap browser control fills: save the file from the page in Chrome, then `vidfarm clipper ./saved.mp4` or `vidfarm put-file ./saved.mp4`.
+
+**Check the free catalog before you browse at all.** `vidfarm public-raws --categories` and `vidfarm media search "<meaning>"` and `vidfarm iconscout "<meaning>" --free` cost nothing and cost no turns either. Browsing is rung 1 of the ladder, but the free shelves are rung 0.
+
+### Interactive mode — hand Chrome to the human instead
+
+In `interactive` mode you have a better option than driving the browser yourself: **tell the user to drive it.** A person scrubbing a TikTok search picks better footage than any keyword extraction, and it costs them two minutes.
+
+Give them the shot list, not a task: *"Search TikTok for `packing orders small business` and `day in the life warehouse`, grab 4–6 clips where the hands are visible and there's no burned-in text, drop them in `./raws-inbox/`."* Then import the folder. `vidfarm handoff raws --keywords "…" --platforms tiktok,youtube --purpose "<what the clips are for>"` mints that brief in full.
+
+The two are complementary, not alternatives: browse yourself to find *which* sources are worth a human's attention, then hand the shortlist over for the taste call. Same shape as the image checkpoint — you write the prompt, they run the free generator.
+
+### Limits, and the honest caveats
+
+- **It is the user's real browser.** Their sessions, cookies, history and open tabs are in reach. Ask before setting it up, keep to the pages the task needs, and never touch a logged-in surface the task didn't call for.
+- **Recordings are off by default and stay off** unless the user asks for them — they write page content to disk. `browser-harness recordings` shows the preference.
+- **Login walls: stop and ask.** Do not attempt credentials, MFA, or account selection.
+- **Captchas and rate limits are the real failure mode.** A burst of automated Google queries gets challenged. Space the searches, keep them wide rather than many, and if you get walled, fall back to the free catalog or the paid primitive rather than hammering.
+- **A public result is not a licensed asset.** Browsing changes what it costs to find footage, not what it costs to use it. Keep the source URL and the licence page for anything reaching a client render, and prefer public domain → CC0 → CC BY → explicit commercial stock → written permission, in that order.
+- **Don't reach for a browser when a fetch would do.** A public page, an API, a docs URL — `curl` it. The browser is for interaction, a logged-in session, JS-rendered results, and bot-protected pages.
+- **`vidfarm serve` is unaffected.** Browser control is for sourcing; the local editor, local render, `qa` and `stills` all run without it.