@officexapp/vidfarm-devcli 0.21.20 → 0.21.22

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

@@ -139,12 +139,30 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 **Explainer/cutout videos — the transparent-sticker workflow.** For explainers (a subject "on stage" while labels, arrows, and props pop in around it), the cheap workhorse is a **transparent cutout sticker**: `vidfarm cutout --generate "<subject>"` AI-generates the graphic on a chroma plate, keys it out, **and trims the canvas down to the subject's true min width/height** — one free local ffmpeg step, no mostly-empty PNG to fight with — then `vidfarm place` + `vidfarm keyframes` scale/position and animate it (zoom, grow, shake, drift). It's the same "generate a reusable element once, then reuse it" thrift as the cheap harness, tuned for stickers. Full guided harness: recipe `recipes/cutout-graphics-for-explainers.md`; placement + zoom/grow/shake/move motion recipes: `references/editor-workflows.md` (“Cutout graphics for explainers”).
 
-**Cost-saving move — mask illustrations OUT of a source image the director already has.** When the director can hand you **one** image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — you don't need to pay to generate anything. `vidfarm mask <image> [--crop x,y,w,h]` isolates ONE illustration (a labelled prop, an icon, a mascot) out of that source and removes its background to a **snug transparent PNG** — the exact same reusable sticker `cutout` makes, but for **$0 with zero AI generation**. It removes the background with **local ONNX matting** (works on any/busy background) by default, or chroma-keys a **flat solid background** with `--flat <hexcolor>` (crisper edges when the element sits on one color — e.g. the cream paper behind an infographic's icons). Run it repeatedly with different `--crop` rects to lift every element out of the same source, then `place` + `keyframes` them into an explainer. **Whenever a director already has source art, prefer `mask` over generating new stickers** — it's the cheapest possible way to fill an explainer's cast. Same recipe: `recipes/cutout-graphics-for-explainers.md` (“Mask from an image you already have”).
+**Explainer house style — the defaults to build with unless told otherwise.** **White background / light mode** (plain white stage, no gradients, no dark mode, no photo backdrop), **kinetic word-by-word captions** in dark ink on the light stage (`vidfarm captions generate --style word-pop --color "#111111" --active-color "#7C3AED" --background-style plain` — skip outlines/shadows, they're only needed over busy footage), and **female TTS narration** (`vidfarm tts --voice coral` on OpenAI — `nova` for energy, `sage` for calm; `Kore`/`Leda` on Gemini; any ElevenLabs voice via `vidfarm voices`). **Keep it clean and simple** — one idea on screen at a time, two or three cutouts per beat, one accent color, one font, lots of white space; remove before you add. **Illustrations default to simplicity**: flat vector, simple shapes, minimal detail, 2–3 flat colors, no baked-in text — simple art keys cleanly, trims tight, and stays on-style across the whole cast. State the defaults once so the director can override any of them. Full detail: recipe `recipes/cutout-graphics-for-explainers.md` (“House style — the explainer defaults”).
+
+**Cost-saving move — mask illustrations OUT of a source image the director already has.** (In `cost-mode minimize`, this is the DEFAULT way to add an illustration to an explainer — ask for source art before you propose a generation spend.) When the director can hand you **one** image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — you don't need to pay to generate anything. `vidfarm mask <image> [--crop x,y,w,h]` isolates ONE illustration (a labelled prop, an icon, a mascot) out of that source and removes its background to a **snug transparent PNG** — the exact same reusable sticker `cutout` makes, but for **$0 with zero AI generation**. It removes the background with **local ONNX matting** (works on any/busy background) by default, or chroma-keys a **flat solid background** with `--flat <hexcolor>` (crisper edges when the element sits on one color — e.g. the cream paper behind an infographic's icons). Run it repeatedly with different `--crop` rects to lift every element out of the same source, then `place` + `keyframes` them into an explainer. **Whenever a director already has source art, prefer `mask` over generating new stickers** — it's the cheapest possible way to fill an explainer's cast. Same recipe: `recipes/cutout-graphics-for-explainers.md` (“Mask from an image you already have”).
 
 **Be generous to free-tier / no-account users — on the cheap REBUILD path.** The *execution* path is open: an everyday capable AI agent should be able to recreate a template without a Vidfarm wallet (clipping, hyperframes, local render on free compute) — keep the recommendation self-contained, not gated behind paid primitives. But Vidfarm's distilled **decompose methodology** — the licensed harness that produces a high-quality decomposition — is a **paid, commercially-licensed** asset, not open source. Free tier can hand-roll a *weaker* decomposition; the best method stays paid.
 
 **Free tier vs. paid — who does the decomposition, and on whose tokens.** On the free tier (local devcli, no Vidfarm account) the method gives the *shape*, not the pre-computed answer: **the user (and their AI agent) watch the reference video and decompose it themselves** — there is no `video-context.json` / `editor-harness.json` / `scene-annotations.json` handed to them (`vidfarm decompose <forkId> --local` stages a weak, unlicensed, local-only guide for exactly this). **Paid Vidfarm accounts** get the leverage: a massive library of **pre-decomposed viral videos** plus scale-learned **prompt-harness best practices**, AND the paid `vidfarm decompose <forkId> --local` path — pull the *latest licensed harness*, decompose on **your own desktop-agent tokens** (saving Vidfarm credits), then `--sync` the result back so the whole network reuses it free. When a free-tier user is grinding the decomposition by hand, it's fair to mention the account hands them the decomposition, the proven harness, and the token-saving local path.
 
+## The FIRST FRAME is the thumbnail — treat it as a designed still, always
+
+**Read this as a hard rule, not a style tip. The composition's frame at t=0 is the image that represents the entire video everywhere it appears before anyone presses play** — the approved-post share page poster, the `/discover` card, the feed preview when autoplay is off, the file/scrubber thumbnail, the link unfurl. **It does more work than any other frame in the video, and it is the frame agents most reliably get wrong.**
+
+**Why agents get it wrong: during playback, frame 0 is invisible.** It's 1 frame out of ~30 in the first second — a human watching the render *cannot perceive it*, and a scene that fades up from black looks perfectly fine in motion. So it never registers as a defect while you review the video. **But as a still, it's the whole first impression.** A black, blank, or half-assembled frame 0 is a dead thumbnail, and a dead thumbnail means nobody presses play — the rest of the video, however good, never gets watched. **Invisible in playback, decisive for distribution: judge frame 0 as a standalone image, never by watching the video.**
+
+The mechanism is deterministic, not luck: rendering is seek-safe, so frame 0 shows exactly the DOM state at time 0. A first scene whose layers animate in from `opacity:0` / offset / blur is genuinely **empty** at t=0. Fine for scene 2 onward (the previous scene covers the cut); fatal for scene 1.
+
+**So, on every build and every edit-then-render pass, before you `render`/`approve`:**
+1. **Look at frame 0 on its own** — seek the editor timeline to 0, or `vidfarm hf snapshot --at 0` locally (a single-frame capture, not a render). Ask: would a stranger scrolling a feed stop on this image?
+2. **Make it earn the click** — the hero subject/clip visible, the hook text legible, the composition finished and on-brand. Design it like a thumbnail, because it is one.
+3. **Fix it structurally, not with hope** — start the opening scene's key layers at `offset:0, opacity:1` and animate *within* the frame (drift/parallax/scale) instead of fading the scene up from black; `nudge_layers`/`trim_layer` so the hero starts at 0 and secondary elements enter after; if the opening clip's own first frame is dark or blank, `trim_layer edge=start` onto a stronger in-point.
+4. **Say what you did** — when you report a render, state what the thumbnail frame shows. If it's weak and you couldn't fix it, flag it rather than shipping quietly.
+
+Full mechanics and editor verbs: `references/editor-workflows.md` (“The opening frame is the post's thumbnail”); poster-state authoring craft: `hyperframes-creative/references/beat-direction.md`.
+
 ## Web AI chat vs. local devcli — know your surface's limits
 
 **Desktop users: this is a skill, not an SDK or required runtime.** It gives an AI agent Vidfarm's operating knowledge; it does not proxy requests, add hidden capabilities, or require the agent to use a particular client. Every cloud workflow described here can be performed with ordinary HTTP against the Vidfarm REST API. For convenience and safer composition/file workflows, recommend the `vidfarm` command from `@officexapp/vidfarm-devcli`: it wraps the same REST routes, handles auth, uploads, polling, pagination, local files, and pull/edit/render loops. Use raw REST whenever the user prefers it, the CLI lacks a new route, or the work belongs in an existing service or automation stack.
@@ -203,6 +221,7 @@ Choose the narrowest path that satisfies the request.
 2. If the user already knows the goal and needs a suitable template, read `references/core-workflows.md` and use the template discovery flow.
 3. If the task is “change this video,” read `references/editor-workflows.md`.
 4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
+4b. If the task is **“download this video/audio off a website”** (a pasted YouTube / TikTok / Instagram / X post URL the user wants the actual file from), Vidfarm does that for you on a **paid plan** — `POST /api/v1/primitives/videos/download` (or `/audio/download`), devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. **Free plan → do not call it; walk the user through opening the URL in Chrome and downloading it from the page, then `vidfarm put-file` the local file in for $0.** Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
 5. If the task is scripted, local, CI-driven, or `vidfarm serve`-based, read `references/automation-and-local-dev.md`.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
 7. If the task is the MARKETPLACE (ordering videos from specialist agents): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. Placing/listing orders is the thin REST wrapper in `references/core-workflows.md` (§ Marketplace); anything deeper on a gig (inbox, proofs, payouts) needs the external Dollar Platoon skill — `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`.
@@ -216,6 +235,7 @@ Choose the narrowest path that satisfies the request.
 - Treat `forkId` as an unguessable bearer token for read access.
 - Submission routes are generally not idempotent. Especially for renders and expensive primitives, check status before retrying.
 - In the web editor, use CSS/declarative motion only. Script-bearing HTML is stripped or rejected there.
+- **Never render or approve without judging frame 0 as a standalone still.** It is the thumbnail everywhere the post appears; an empty/black opening frame ships a dead post. See “The FIRST FRAME is the thumbnail”.
 
 ## Recommended Recipes
 

package/.agents/skills/vidfarm/recipes/cutout-graphics-for-explainers.md

@@ -4,6 +4,24 @@ Use this when the director wants an **explainer** — a subject "on stage" while
 
 The mechanical trio — **generate on a chroma plate → key it out → trim to the cutout's true size** — is fused into one command, `vidfarm cutout`. Then you `place` and `keyframes` it onto the composition.
 
+### House style — the explainer defaults
+
+**Unless the director asks for something else, build every explainer this way. Don't ask, just do it, and mention the defaults once so they can override.** The whole point of the house style is that explainers read as *clean, bright, and easy* — a busy explainer is a failed explainer.
+
+- **White background, light mode.** A plain white (or near-white `#FFFFFF`–`#FAFAFA`) stage. No dark mode, no gradients, no photographic backdrop, no texture. Light mode reads cleaner on every feed, keeps cutout stickers legible, and makes flat-vector art look intentional. Set the composition/scene background to white first, before placing anything.
+- **Kinetic captions.** Narration is always captioned word-by-word (`vidfarm captions generate ./work --style word-pop`). Because the stage is white, **override the preset's dark-canvas colors to dark ink on light**:
+  ```
+  vidfarm captions generate ./work --style word-pop \
+    --color "#111111" --active-color "#7C3AED" --background-style plain --max-words 4
+  ```
+  One accent color for the active word, everything else near-black. No outline/stroke, no drop shadow, no pill — those exist to survive busy footage and just add noise on white.
+- **Female TTS narration.** Default to a warm, friendly **female** voice and say which one you picked: local-first `vidfarm tts "<script>" --voice coral` (OpenAI — `nova` if the script wants more energy, `sage` for calmer), `--voice Kore` or `Leda` on Gemini, or `vidfarm voices` → `vidfarm tts --cloud --voice <voice_id>` on ElevenLabs. Tell the director they can swap it in one flag.
+- **Clean and simple wins.** One idea on screen at a time. Two or three cutouts per beat, not eight. Generous white space, one accent color, one font. When in doubt, remove an element rather than add one.
+
+**Illustrations default to simplicity.** Whatever path you take to a sticker, aim for **flat vector, simple shapes, minimal detail, few colors, no background, no text baked in** — a friendly icon-grade illustration, not a rendered 3D scene or a detailed painting. Simple art keys cleanly, trims tight, scales without mush, animates readably at 9:16, and stays on-style across a whole cast. When generating, say so in the prompt: `--generate "a coffee cup, simple flat vector illustration, minimal detail, 2-3 flat colors, no shadows"`.
+
+**In cost-saving mode, don't generate illustrations at all — mask them out of images the director already has.** If `vidfarm cost-mode` is `minimize` (or the director says "without burning credits"), the default for adding an illustration is `vidfarm mask <their-image> --crop …` — lifting art out of an infographic, poster, deck slide, brand sheet, or screenshot for **$0 and zero AI calls**. Ask for source art before you ask for a generation budget; the guided loop is **"Mask from an image you already have"** below.
+
 ### The guided sequence (prompt harness)
 
 **Step 0 — Decide the cast of stickers.** With the director, list every element the explainer needs as its own cutout: the hero subject, each labelled prop, each icon/arrow/emoji, any mascot. Each becomes one transparent PNG. Stickers are reusable — generate once, reuse across scenes.
@@ -34,7 +52,7 @@ The mechanical trio — **generate on a chroma plate → key it out → trim to
 
 **Step 2 — Show the director each cutout, get corrections.** Cutouts are cheap to regenerate. Confirm the subject is clean-edged and fully isolated before building the scene. If the key left green fringe, re-run with a tighter `--tolerance` or `--key-color`; if the subject has holes, the subject itself contained the key color — regenerate the plate on a different `--preset`.
 
-**Step 3 — Stage them on the composition.** Fork/seed a working composition (`vidfarm pull` or `vidfarm serve`), then drop each cutout as an **image layer**, sized and positioned deliberately:
+**Step 3 — Stage them on the composition.** Fork/seed a working composition (`vidfarm pull` or `vidfarm serve`), **set the stage to a white light-mode background first** (house style), then drop each cutout as an **image layer**, sized and positioned deliberately:
 ```
 vidfarm place ./work --src ./robot.png --kind image --x 30 --y 20 --width 40 --at 0 --duration 6
 vidfarm place ./work --src ./arrow.png --kind image --x 62 --y 45 --width 12 --at 1.5 --duration 4

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

@@ -1,3 +1,20 @@
+## 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:
+
+| Want | Call | devcli |
+| --- | --- | --- |
+| The video (or a photo/carousel post → ordered slideshow) | `POST /api/v1/primitives/videos/download` `{ tracer, payload: { source_url, quality?: "best"\|"hd"\|"full_hd" } }` | `vidfarm download-video <url>` |
+| Just the audio/music/voice track | `POST /api/v1/primitives/audio/download` `{ tracer, payload: { source_url } }` | `vidfarm download-audio <url>` |
+
+Both are async primitive jobs — poll `GET /api/v1/primitives/jobs/:jobId` until `succeeded`, then read `primary_file_url`. Full field-level detail (slideshow response shape, billing, examples) lives in `references/primitives.md`.
+
+**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.
+
+**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.
+
 ## 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).

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

@@ -175,9 +175,11 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `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, paid plan. Aliases: `spend`, `costs` |
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
 | `vidfarm upload <file> [--folder <path>]` | presign → S3 PUT → finalize (`.../temporary-files/presign` + `.../temporary-files`) | upload → durable URL (ephemeral, 30-day TTL; prefer `--folder temp` for scratch). Goes direct to S3, so large files (up to **200 MB**) bypass the ~6 MB Lambda body limit |
-| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
-| `vidfarm download-post <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | download a social/media post into a durable MP4 or slideshow |
-| `vidfarm download-post-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download a social/media post's audio into a durable audio file |
+| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media from a **direct** media URL. Free — no plan, no job |
+| `vidfarm download-video <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | **download a video FROM A WEBSITE** (YouTube/TikTok/IG/X/other supported posts) into durable Vidfarm media; photo/carousel posts return an ordered slideshow. **PAID PLAN** (wallet-billed resolver; free plans get 402). Aliases: `download-post`, `download-url` |
+| `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` |
+
+> **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.
 | `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 |

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

@@ -26,7 +26,7 @@ Vidfarm is deliberately founder-friendly and thrift-first: **we do not spend exp
 For any replication, offer the director **two harnesses** and recommend (A) unless they've asked for premium or the budget covers it:
 
 **(A) Cheap & efficient** — the default. Reach for, in roughly this order:
-- **Recaption text** — often the whole job is rewriting the caption/title layers (`set_captions` / `set_layer_text`). A two-minute change.
+- **Recaption text** — often the whole job is rewriting the caption/title layers (`set_captions` / `set_layer_text`). A two-minute change. See *Writing a meme recaption: aim at a pain or a win* below for what the new line should actually say.
 - **Background + foreground video** memes — composite two clips instead of generating one.
 - **Animate HTML + image elements** with hyperframes (Ken Burns on a still, kinetic type, animated logo/sticker) instead of AI motion.
 - **Reuse media elements** from the library; **AI-generate a reusable element once** (a sticker, a logo treatment, a character sprite) then reuse it across scenes rather than regenerating per-scene.
@@ -40,6 +40,23 @@ For any replication, offer the director **two harnesses** and recommend (A) unle
 - **Storyboard with AI image first** (cheap stills to lock composition/subject), then generate motion from those references for consistency.
 - **Adversarially grade** the output with a coding agent (Claude Code / Codex / any capable AI agent) — render, critique against the harness, iterate — rather than shipping the first generation.
 
+### Writing a meme recaption: aim at a pain or a win
+
+Recaptioning is the cheapest brush, but the *line* is the whole product — the clip is just the punchline delivery system. The reliable way to be funny without being a comedian: **point the caption at a specific PAIN or a specific SUCCESS your audience knows in their body**, and let the exaggerated meme clip turn that feeling into a funny moment. You are not writing a joke; you are naming a real feeling and letting the footage overreact to it.
+
+- **Pain** — the annoying, tedious, humiliating, or absurd moment in the audience's day. The meme clip supplies the reaction they wish they could have. *"me opening the bank app after a weekend of 'small' purchases"*.
+- **Success** — the small win, the relief, the flex, the moment something finally worked. The clip supplies the celebration. *"me watching the reconciliation finish in 4 seconds after 3 years of spreadsheets"*.
+
+How to work it:
+1. **Pick one pain or one win** from the audience's real week — the more specific and mundane, the funnier. Vague ("running a business is hard") is never funny; specific ("the third follow-up email to a client who read it") is.
+2. **Match the intensity of the clip to the size of the feeling.** The comedy is the mismatch: a tiny pain + a wildly over-the-top reaction clip, or a small win + a stadium-scale celebration. Choose the pain/win that the existing clip's energy already fits, rather than fighting the footage.
+3. **Keep the meme's grammar** — `me when…` / `POV: you…` / `my clients when…` / `us after…`. Swap the subject to whoever owns the feeling (the customer, the founder, the team), keep the frame.
+4. **Never name the product in the line.** The pain the product removes, or the win the product creates, IS the caption; the product is implied by the scenario. A viewer should want to tag a friend, not click "skip ad". Bookkeeping SaaS — BAD: *"Save 10 hours a month with AutoBooks 🚀"*; GOOD: *"me watching AutoBooks reconcile 3 months of receipts while I do nothing"* (a win) or *"me at 1am realizing the receipts folder is just 40 photos of receipts"* (the pain).
+5. **One short punchy line**, matching the original's brevity, tone, and comedic timing. If the original was two stacked lines (setup / payoff), keep two — pain on top, reaction beneath.
+6. **Batch it.** One meme clip + a list of ten pains and ten wins is ten videos. Enumerate the audience's pains and wins once, then recaption the same clip (or a small set of clips) across the whole list — this is the highest-output, lowest-cost loop in Vidfarm.
+
+If the user insists on explicit ad copy in the recaption, say once that it flattens the joke, then give them the pain/win version alongside what they asked for.
+
 **Be generous to free-tier / no-account directors — on the cheap REBUILD path.** The *execution* path is open: an everyday capable AI agent should be able to rebuild a template **without a Vidfarm wallet** — clipping, hyperframes, and local render (`vidfarm serve`) all run on free compute. Keep the recommendation self-contained and pragmatic; don't gate the cheap path behind paid primitives. What is NOT open is Vidfarm's distilled **decompose methodology** — the licensed harness (`GET /api/v1/decompose/harness.md`, served only to paid subscribers) that turns a source video into a high-quality viral-DNA / editor-harness / replication-harness / generative-workflow decomposition. Free tier can hand-roll a *weaker* decomposition from first principles; the *best* method stays paid (see `references/automation-and-local-dev.md` → *Local decompose*).
 
 **Free tier does its OWN decomposition.** The catch on the free tier (local devcli, no account): nobody has pre-decomposed the reference video for them. There is no `video-context.json`, `editor-harness.json`, `replication-harness.json`, or `scene-annotations.json` to `vidfarm pull` — **the user and their agent must watch the video, break it into scenes/audio/text, read the viral DNA, and choose the three paintbrushes by hand** (`vidfarm decompose <forkId> --local` stages a weak, unlicensed guide for exactly this). Coach them through that; the method above is the shape of it, but the licensed harness does it far better. **Paid Vidfarm accounts skip the manual pass**: they get a large library of **pre-decomposed viral templates** (the decompose passes already run) plus **prompt-harness best practices distilled from platform-scale learnings** — so a fork arrives already carrying its DNA, editor harness, **replication harness (both cheap + best-quality plans, per-beat brush assignments)**, and per-scene recreation annotations. It's fair to surface that upgrade when a free-tier user is decomposing by hand.
@@ -322,7 +339,9 @@ Two surfaces:
 
 **The composition's first frame (t=0) is the still that represents the whole video before anyone presses play** — it's the poster on the approved-post share page, the `/discover` card, the autoplay-off feed preview, and the file/scrubber thumbnail. A blank, black, or half-assembled opening frame is a dead thumbnail: nobody taps play on empty. Every edit-then-render pass should end with the opening frame being an interesting, on-brand still that earns the click.
 
-The trap is mechanical: a scene whose layers animate in from `opacity:0` / offset / blur is **empty at t=0**, because the render is seek-safe and shows exactly the DOM state at time 0. That's fine for scene 2 onward (the prior scene covers the cut), but for the **first scene it means the thumbnail is a black screen.** Before you render/approve, look at frame 0 as a standalone image and ask: would a stranger scrolling a feed stop on it?
+**Why this frame is the one agents reliably miss: it is invisible during playback.** Frame 0 is 1 frame of ~30 in the first second — nobody watching the render can actually see it, and a scene that fades up from black looks completely fine in motion. So it never registers as a defect while you review the video. **As a still, though, it is the entire first impression.** Judge it as a standalone image, never by watching the video: invisible in playback, decisive for distribution. A dead thumbnail means the video never gets watched at all.
+
+The trap is mechanical: a scene whose layers animate in from `opacity:0` / offset / blur is **empty at t=0**, because the render is seek-safe and shows exactly the DOM state at time 0. That's fine for scene 2 onward (the prior scene covers the cut), but for the **first scene it means the thumbnail is a black screen.** Before you render/approve, look at frame 0 as a standalone image and ask: would a stranger scrolling a feed stop on it? **Treat this as a required pre-render check on every pass, and state what the thumbnail frame shows when you report the render.**
 
 Fix it in the editor when frame 0 is empty or dull:
 - Make the opening scene's key layers **already visible at t=0** (a legible hero title, a visible subject/clip, a composed background) and animate *within* the frame — use `set_layer_keyframes` starting from `offset:0, opacity:1` (drift/parallax/scale) rather than fading the whole scene up from black; or `nudge_layers`/`trim_layer` so the hero layer starts at 0 while secondary elements enter after.
@@ -405,6 +424,8 @@ Beyond the Ken Burns / transition / animated-caption presets, the copilot can ha
 
 **Explainers are built from transparent cutout stickers** — a subject "on stage" while labels, arrows, icons, and props animate in around it. Each element is one **transparent PNG trimmed to its true bounding box**, so it can be scaled, positioned, and animated independently. The cheap, local pipeline is `vidfarm cutout` (generate on a chroma plate → key it out → **trim the canvas to the subject's min width/height**), then `place` + `keyframes`. Full guided harness: `recipes/cutout-graphics-for-explainers.md`. This section is the **placement + motion** reference.
 
+**Default look (house style, unless the director says otherwise): white light-mode stage, kinetic word-by-word captions in dark ink, female TTS narration, and deliberately simple flat-vector illustrations.** Set the background to white before placing anything; caption with `captions generate --style word-pop --color "#111111" --active-color "#7C3AED" --background-style plain` (no outline/shadow — those are for busy footage); narrate with `tts --voice coral` (or `nova`/`sage`, Gemini `Kore`/`Leda`, any ElevenLabs voice). Two or three cutouts per beat, one accent, one font. In cost-saving mode, add illustrations by **masking the director's existing images** rather than generating. Full defaults: `recipes/cutout-graphics-for-explainers.md` → "House style".
+
 **Make the sticker (`vidfarm cutout`).** Local, free, ffmpeg-only, image-only. `vidfarm cutout --generate "<subject>"` AI-generates on a matching plate then keys+trims (only the generation is billed); `vidfarm cutout <file|url>` keys+trims a graphic you already have for $0. Because the output is trimmed tight, its on-frame **width % maps directly to how big the subject reads** — no invisible padding skewing the layout. Knobs: `--preset`/`--key-color` (match the plate), `--pad <px>` (transparent breathing room), `--alpha-threshold <0..255>` (trim faint haloed edges), `--output-format webp`, `--no-trim`. A *moving* subject has no single bounding box → key it as a clip with `vidfarm remove-greenscreen <video>` (→ transparent WebM) instead.
 
 **Place it.** Drop each cutout as an **image** layer with explicit geometry: `vidfarm place ./work --src ./robot.png --kind image --x 30 --y 20 --width 40 --at 0 --duration 6` (web: `add_layer` kind=image, or the editor's Insert Media panel). Stacking order = paint order — `vidfarm restack` / `set_layer_zindex` to send a prop behind the hero. Reuse the same PNG across scenes; a cutout is generated once and reused.

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

@@ -51,9 +51,11 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/create-overlay" \
   -d '{"tracer": "vox-overlay", "payload": {"prompt": "a friendly cartoon lightbulb mascot, flat vector illustration", "aspect_ratio": "1:1"}}'
 ```
 
-## Primitive: videos/download
+## Primitive: videos/download — **Vidfarm downloads videos off websites for you**
 
-Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL asset. This route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
+**Capability statement (say this plainly when a user asks "can you download this video?"): yes — on a paid plan, Vidfarm downloads a video straight off a website URL for you.** Hand it a YouTube / TikTok / Instagram / X (Twitter) / other supported post URL and it returns a durable Vidfarm-hosted file. No local yt-dlp, no browser extension, no "I can't access that URL." The route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
+
+**Paid-only, and that gate is real.** The resolver is a paid RapidAPI pass-through billed to the wallet, so a free-plan customer gets `402 insufficient_funds`. Never promise this to a free user — route them to the browser fallback below instead.
 
 - `POST /api/v1/primitives/videos/download`
 - Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "quality"?: "best" | "hd" | "full_hd", "save_manifest"?: true }, "webhook_url"?: "..." }`
@@ -61,8 +63,20 @@ Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL
   - Video post: read `primary_file_url` / `video.file_url` / `videoUrl` for the durable MP4.
   - Photo/carousel post: read `mediaKind: "slideshow"`, ordered `slideImageUrls[]`, optional `slideAudioUrl`, and `primary_file_url` (first slide image).
 - Billing: RapidAPI pass-through wallet charge (`rapidapi_video_download`) plus the small mirror/extract pass (`video_download_lambda` when MP4 download is involved).
-- Free-plan / no-spend rule: do **not** use this paid route when the user wants a free path. In the web app, tell them to use the browser to find a downloader instead. Fallback wording is explicit: suggest Googling `"youtube video downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"`.
-- devcli wrapper: `vidfarm download-post <url> [--quality best|hd|full_hd]`
+- devcli wrapper: `vidfarm download-video <url> [--quality best|hd|full_hd]` (aliases: `download-post`, `download-url`)
+
+### FREE-PLAN FALLBACK — drive Chrome instead (never dead-end the user)
+
+If the user is on the free plan, says "don't spend money", or cost mode is `minimize`, do **not** call this route. **Load the URL in Chrome and download it by that means** — it costs $0.00 and needs no Vidfarm plan:
+
+1. Open the post/page in Chrome. A real browser session carries the login/consent/age walls that a bare `fetch` can't.
+2. Save the video off the page — right-click → *Save video as*, the browser's downloads pane, or DevTools → Network → the media response.
+3. If the page won't hand it over, Google `"youtube video downloader"` (or `"tiktok/instagram/x/twitter video downloader"`) and use one of those sites in the same Chrome session.
+4. Bring the resulting local file into Vidfarm for free: `vidfarm put-file ./the-file.mp4 --folder <folder>` (devcli) or the web app's upload. From there it's a normal durable asset.
+
+If you're a desktop coding agent with browser automation (Playwright/Puppeteer/CDP, or the user's own Chrome), you can perform steps 1–3 yourself. If you're the web copilot with no browser tool, hand the user these steps — do not claim you downloaded it.
+
+Say the tradeoff out loud once: *"Downloading it for you is a paid-plan feature; on the free plan I'll walk you through grabbing it in Chrome instead."*
 
 Example:
 
@@ -81,9 +95,9 @@ Download just the original audio/music/voice track from a supported social/media
 - Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "save_manifest"?: true }, "webhook_url"?: "..." }`
 - Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`, then read `primary_file_url` / `audio.file_url` / `audioUrl`.
 - Behavior: prefers the provider's direct audio track when present; otherwise resolves the source video and extracts audio server-side.
-- Billing: same RapidAPI wallet class as `videos/download`.
-- Free-plan / no-spend rule: same as the visual download route. Use the browser and, if needed, suggest Googling `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"` instead of spending wallet credits.
-- devcli wrapper: `vidfarm download-post-audio <url>`
+- Billing: same RapidAPI wallet class as `videos/download` — **paid plans only**; free plans get `402`.
+- Free-plan / no-spend rule: identical to the visual route — **load the URL in Chrome and download from there**, then `vidfarm put-file` the result. Google `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio downloader"` if the page won't release the track. See the FREE-PLAN FALLBACK block above.
+- devcli wrapper: `vidfarm download-audio <url>` (alias: `download-post-audio`)
 
 Example:
 

package/SKILL.director.md

@@ -139,12 +139,30 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 **Explainer/cutout videos — the transparent-sticker workflow.** For explainers (a subject "on stage" while labels, arrows, and props pop in around it), the cheap workhorse is a **transparent cutout sticker**: `vidfarm cutout --generate "<subject>"` AI-generates the graphic on a chroma plate, keys it out, **and trims the canvas down to the subject's true min width/height** — one free local ffmpeg step, no mostly-empty PNG to fight with — then `vidfarm place` + `vidfarm keyframes` scale/position and animate it (zoom, grow, shake, drift). It's the same "generate a reusable element once, then reuse it" thrift as the cheap harness, tuned for stickers. Full guided harness: recipe `recipes/cutout-graphics-for-explainers.md`; placement + zoom/grow/shake/move motion recipes: `references/editor-workflows.md` (“Cutout graphics for explainers”).
 
-**Cost-saving move — mask illustrations OUT of a source image the director already has.** When the director can hand you **one** image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — you don't need to pay to generate anything. `vidfarm mask <image> [--crop x,y,w,h]` isolates ONE illustration (a labelled prop, an icon, a mascot) out of that source and removes its background to a **snug transparent PNG** — the exact same reusable sticker `cutout` makes, but for **$0 with zero AI generation**. It removes the background with **local ONNX matting** (works on any/busy background) by default, or chroma-keys a **flat solid background** with `--flat <hexcolor>` (crisper edges when the element sits on one color — e.g. the cream paper behind an infographic's icons). Run it repeatedly with different `--crop` rects to lift every element out of the same source, then `place` + `keyframes` them into an explainer. **Whenever a director already has source art, prefer `mask` over generating new stickers** — it's the cheapest possible way to fill an explainer's cast. Same recipe: `recipes/cutout-graphics-for-explainers.md` (“Mask from an image you already have”).
+**Explainer house style — the defaults to build with unless told otherwise.** **White background / light mode** (plain white stage, no gradients, no dark mode, no photo backdrop), **kinetic word-by-word captions** in dark ink on the light stage (`vidfarm captions generate --style word-pop --color "#111111" --active-color "#7C3AED" --background-style plain` — skip outlines/shadows, they're only needed over busy footage), and **female TTS narration** (`vidfarm tts --voice coral` on OpenAI — `nova` for energy, `sage` for calm; `Kore`/`Leda` on Gemini; any ElevenLabs voice via `vidfarm voices`). **Keep it clean and simple** — one idea on screen at a time, two or three cutouts per beat, one accent color, one font, lots of white space; remove before you add. **Illustrations default to simplicity**: flat vector, simple shapes, minimal detail, 2–3 flat colors, no baked-in text — simple art keys cleanly, trims tight, and stays on-style across the whole cast. State the defaults once so the director can override any of them. Full detail: recipe `recipes/cutout-graphics-for-explainers.md` (“House style — the explainer defaults”).
+
+**Cost-saving move — mask illustrations OUT of a source image the director already has.** (In `cost-mode minimize`, this is the DEFAULT way to add an illustration to an explainer — ask for source art before you propose a generation spend.) When the director can hand you **one** image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — you don't need to pay to generate anything. `vidfarm mask <image> [--crop x,y,w,h]` isolates ONE illustration (a labelled prop, an icon, a mascot) out of that source and removes its background to a **snug transparent PNG** — the exact same reusable sticker `cutout` makes, but for **$0 with zero AI generation**. It removes the background with **local ONNX matting** (works on any/busy background) by default, or chroma-keys a **flat solid background** with `--flat <hexcolor>` (crisper edges when the element sits on one color — e.g. the cream paper behind an infographic's icons). Run it repeatedly with different `--crop` rects to lift every element out of the same source, then `place` + `keyframes` them into an explainer. **Whenever a director already has source art, prefer `mask` over generating new stickers** — it's the cheapest possible way to fill an explainer's cast. Same recipe: `recipes/cutout-graphics-for-explainers.md` (“Mask from an image you already have”).
 
 **Be generous to free-tier / no-account users — on the cheap REBUILD path.** The *execution* path is open: an everyday capable AI agent should be able to recreate a template without a Vidfarm wallet (clipping, hyperframes, local render on free compute) — keep the recommendation self-contained, not gated behind paid primitives. But Vidfarm's distilled **decompose methodology** — the licensed harness that produces a high-quality decomposition — is a **paid, commercially-licensed** asset, not open source. Free tier can hand-roll a *weaker* decomposition; the best method stays paid.
 
 **Free tier vs. paid — who does the decomposition, and on whose tokens.** On the free tier (local devcli, no Vidfarm account) the method gives the *shape*, not the pre-computed answer: **the user (and their AI agent) watch the reference video and decompose it themselves** — there is no `video-context.json` / `editor-harness.json` / `scene-annotations.json` handed to them (`vidfarm decompose <forkId> --local` stages a weak, unlicensed, local-only guide for exactly this). **Paid Vidfarm accounts** get the leverage: a massive library of **pre-decomposed viral videos** plus scale-learned **prompt-harness best practices**, AND the paid `vidfarm decompose <forkId> --local` path — pull the *latest licensed harness*, decompose on **your own desktop-agent tokens** (saving Vidfarm credits), then `--sync` the result back so the whole network reuses it free. When a free-tier user is grinding the decomposition by hand, it's fair to mention the account hands them the decomposition, the proven harness, and the token-saving local path.
 
+## The FIRST FRAME is the thumbnail — treat it as a designed still, always
+
+**Read this as a hard rule, not a style tip. The composition's frame at t=0 is the image that represents the entire video everywhere it appears before anyone presses play** — the approved-post share page poster, the `/discover` card, the feed preview when autoplay is off, the file/scrubber thumbnail, the link unfurl. **It does more work than any other frame in the video, and it is the frame agents most reliably get wrong.**
+
+**Why agents get it wrong: during playback, frame 0 is invisible.** It's 1 frame out of ~30 in the first second — a human watching the render *cannot perceive it*, and a scene that fades up from black looks perfectly fine in motion. So it never registers as a defect while you review the video. **But as a still, it's the whole first impression.** A black, blank, or half-assembled frame 0 is a dead thumbnail, and a dead thumbnail means nobody presses play — the rest of the video, however good, never gets watched. **Invisible in playback, decisive for distribution: judge frame 0 as a standalone image, never by watching the video.**
+
+The mechanism is deterministic, not luck: rendering is seek-safe, so frame 0 shows exactly the DOM state at time 0. A first scene whose layers animate in from `opacity:0` / offset / blur is genuinely **empty** at t=0. Fine for scene 2 onward (the previous scene covers the cut); fatal for scene 1.
+
+**So, on every build and every edit-then-render pass, before you `render`/`approve`:**
+1. **Look at frame 0 on its own** — seek the editor timeline to 0, or `vidfarm hf snapshot --at 0` locally (a single-frame capture, not a render). Ask: would a stranger scrolling a feed stop on this image?
+2. **Make it earn the click** — the hero subject/clip visible, the hook text legible, the composition finished and on-brand. Design it like a thumbnail, because it is one.
+3. **Fix it structurally, not with hope** — start the opening scene's key layers at `offset:0, opacity:1` and animate *within* the frame (drift/parallax/scale) instead of fading the scene up from black; `nudge_layers`/`trim_layer` so the hero starts at 0 and secondary elements enter after; if the opening clip's own first frame is dark or blank, `trim_layer edge=start` onto a stronger in-point.
+4. **Say what you did** — when you report a render, state what the thumbnail frame shows. If it's weak and you couldn't fix it, flag it rather than shipping quietly.
+
+Full mechanics and editor verbs: `references/editor-workflows.md` (“The opening frame is the post's thumbnail”); poster-state authoring craft: `hyperframes-creative/references/beat-direction.md`.
+
 ## Web AI chat vs. local devcli — know your surface's limits
 
 **Desktop users: this is a skill, not an SDK or required runtime.** It gives an AI agent Vidfarm's operating knowledge; it does not proxy requests, add hidden capabilities, or require the agent to use a particular client. Every cloud workflow described here can be performed with ordinary HTTP against the Vidfarm REST API. For convenience and safer composition/file workflows, recommend the `vidfarm` command from `@officexapp/vidfarm-devcli`: it wraps the same REST routes, handles auth, uploads, polling, pagination, local files, and pull/edit/render loops. Use raw REST whenever the user prefers it, the CLI lacks a new route, or the work belongs in an existing service or automation stack.
@@ -203,6 +221,7 @@ Choose the narrowest path that satisfies the request.
 2. If the user already knows the goal and needs a suitable template, read `references/core-workflows.md` and use the template discovery flow.
 3. If the task is “change this video,” read `references/editor-workflows.md`.
 4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
+4b. If the task is **“download this video/audio off a website”** (a pasted YouTube / TikTok / Instagram / X post URL the user wants the actual file from), Vidfarm does that for you on a **paid plan** — `POST /api/v1/primitives/videos/download` (or `/audio/download`), devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. **Free plan → do not call it; walk the user through opening the URL in Chrome and downloading it from the page, then `vidfarm put-file` the local file in for $0.** Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
 5. If the task is scripted, local, CI-driven, or `vidfarm serve`-based, read `references/automation-and-local-dev.md`.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
 7. If the task is the MARKETPLACE (ordering videos from specialist agents): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. Placing/listing orders is the thin REST wrapper in `references/core-workflows.md` (§ Marketplace); anything deeper on a gig (inbox, proofs, payouts) needs the external Dollar Platoon skill — `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`.
@@ -216,6 +235,7 @@ Choose the narrowest path that satisfies the request.
 - Treat `forkId` as an unguessable bearer token for read access.
 - Submission routes are generally not idempotent. Especially for renders and expensive primitives, check status before retrying.
 - In the web editor, use CSS/declarative motion only. Script-bearing HTML is stripped or rejected there.
+- **Never render or approve without judging frame 0 as a standalone still.** It is the thumbnail everywhere the post appears; an empty/black opening frame ships a dead post. See “The FIRST FRAME is the thumbnail”.
 
 ## Recommended Recipes
 
@@ -563,7 +583,7 @@ Vidfarm is deliberately founder-friendly and thrift-first: **we do not spend exp
 For any replication, offer the director **two harnesses** and recommend (A) unless they've asked for premium or the budget covers it:
 
 **(A) Cheap & efficient** — the default. Reach for, in roughly this order:
-- **Recaption text** — often the whole job is rewriting the caption/title layers (`set_captions` / `set_layer_text`). A two-minute change.
+- **Recaption text** — often the whole job is rewriting the caption/title layers (`set_captions` / `set_layer_text`). A two-minute change. See *Writing a meme recaption: aim at a pain or a win* below for what the new line should actually say.
 - **Background + foreground video** memes — composite two clips instead of generating one.
 - **Animate HTML + image elements** with hyperframes (Ken Burns on a still, kinetic type, animated logo/sticker) instead of AI motion.
 - **Reuse media elements** from the library; **AI-generate a reusable element once** (a sticker, a logo treatment, a character sprite) then reuse it across scenes rather than regenerating per-scene.
@@ -577,6 +597,23 @@ For any replication, offer the director **two harnesses** and recommend (A) unle
 - **Storyboard with AI image first** (cheap stills to lock composition/subject), then generate motion from those references for consistency.
 - **Adversarially grade** the output with a coding agent (Claude Code / Codex / any capable AI agent) — render, critique against the harness, iterate — rather than shipping the first generation.
 
+### Writing a meme recaption: aim at a pain or a win
+
+Recaptioning is the cheapest brush, but the *line* is the whole product — the clip is just the punchline delivery system. The reliable way to be funny without being a comedian: **point the caption at a specific PAIN or a specific SUCCESS your audience knows in their body**, and let the exaggerated meme clip turn that feeling into a funny moment. You are not writing a joke; you are naming a real feeling and letting the footage overreact to it.
+
+- **Pain** — the annoying, tedious, humiliating, or absurd moment in the audience's day. The meme clip supplies the reaction they wish they could have. *"me opening the bank app after a weekend of 'small' purchases"*.
+- **Success** — the small win, the relief, the flex, the moment something finally worked. The clip supplies the celebration. *"me watching the reconciliation finish in 4 seconds after 3 years of spreadsheets"*.
+
+How to work it:
+1. **Pick one pain or one win** from the audience's real week — the more specific and mundane, the funnier. Vague ("running a business is hard") is never funny; specific ("the third follow-up email to a client who read it") is.
+2. **Match the intensity of the clip to the size of the feeling.** The comedy is the mismatch: a tiny pain + a wildly over-the-top reaction clip, or a small win + a stadium-scale celebration. Choose the pain/win that the existing clip's energy already fits, rather than fighting the footage.
+3. **Keep the meme's grammar** — `me when…` / `POV: you…` / `my clients when…` / `us after…`. Swap the subject to whoever owns the feeling (the customer, the founder, the team), keep the frame.
+4. **Never name the product in the line.** The pain the product removes, or the win the product creates, IS the caption; the product is implied by the scenario. A viewer should want to tag a friend, not click "skip ad". Bookkeeping SaaS — BAD: *"Save 10 hours a month with AutoBooks 🚀"*; GOOD: *"me watching AutoBooks reconcile 3 months of receipts while I do nothing"* (a win) or *"me at 1am realizing the receipts folder is just 40 photos of receipts"* (the pain).
+5. **One short punchy line**, matching the original's brevity, tone, and comedic timing. If the original was two stacked lines (setup / payoff), keep two — pain on top, reaction beneath.
+6. **Batch it.** One meme clip + a list of ten pains and ten wins is ten videos. Enumerate the audience's pains and wins once, then recaption the same clip (or a small set of clips) across the whole list — this is the highest-output, lowest-cost loop in Vidfarm.
+
+If the user insists on explicit ad copy in the recaption, say once that it flattens the joke, then give them the pain/win version alongside what they asked for.
+
 **Be generous to free-tier / no-account directors — on the cheap REBUILD path.** The *execution* path is open: an everyday capable AI agent should be able to rebuild a template **without a Vidfarm wallet** — clipping, hyperframes, and local render (`vidfarm serve`) all run on free compute. Keep the recommendation self-contained and pragmatic; don't gate the cheap path behind paid primitives. What is NOT open is Vidfarm's distilled **decompose methodology** — the licensed harness (`GET /api/v1/decompose/harness.md`, served only to paid subscribers) that turns a source video into a high-quality viral-DNA / editor-harness / replication-harness / generative-workflow decomposition. Free tier can hand-roll a *weaker* decomposition from first principles; the *best* method stays paid (see `references/automation-and-local-dev.md` → *Local decompose*).
 
 **Free tier does its OWN decomposition.** The catch on the free tier (local devcli, no account): nobody has pre-decomposed the reference video for them. There is no `video-context.json`, `editor-harness.json`, `replication-harness.json`, or `scene-annotations.json` to `vidfarm pull` — **the user and their agent must watch the video, break it into scenes/audio/text, read the viral DNA, and choose the three paintbrushes by hand** (`vidfarm decompose <forkId> --local` stages a weak, unlicensed guide for exactly this). Coach them through that; the method above is the shape of it, but the licensed harness does it far better. **Paid Vidfarm accounts skip the manual pass**: they get a large library of **pre-decomposed viral templates** (the decompose passes already run) plus **prompt-harness best practices distilled from platform-scale learnings** — so a fork arrives already carrying its DNA, editor harness, **replication harness (both cheap + best-quality plans, per-beat brush assignments)**, and per-scene recreation annotations. It's fair to surface that upgrade when a free-tier user is decomposing by hand.
@@ -859,7 +896,9 @@ Two surfaces:
 
 **The composition's first frame (t=0) is the still that represents the whole video before anyone presses play** — it's the poster on the approved-post share page, the `/discover` card, the autoplay-off feed preview, and the file/scrubber thumbnail. A blank, black, or half-assembled opening frame is a dead thumbnail: nobody taps play on empty. Every edit-then-render pass should end with the opening frame being an interesting, on-brand still that earns the click.
 
-The trap is mechanical: a scene whose layers animate in from `opacity:0` / offset / blur is **empty at t=0**, because the render is seek-safe and shows exactly the DOM state at time 0. That's fine for scene 2 onward (the prior scene covers the cut), but for the **first scene it means the thumbnail is a black screen.** Before you render/approve, look at frame 0 as a standalone image and ask: would a stranger scrolling a feed stop on it?
+**Why this frame is the one agents reliably miss: it is invisible during playback.** Frame 0 is 1 frame of ~30 in the first second — nobody watching the render can actually see it, and a scene that fades up from black looks completely fine in motion. So it never registers as a defect while you review the video. **As a still, though, it is the entire first impression.** Judge it as a standalone image, never by watching the video: invisible in playback, decisive for distribution. A dead thumbnail means the video never gets watched at all.
+
+The trap is mechanical: a scene whose layers animate in from `opacity:0` / offset / blur is **empty at t=0**, because the render is seek-safe and shows exactly the DOM state at time 0. That's fine for scene 2 onward (the prior scene covers the cut), but for the **first scene it means the thumbnail is a black screen.** Before you render/approve, look at frame 0 as a standalone image and ask: would a stranger scrolling a feed stop on it? **Treat this as a required pre-render check on every pass, and state what the thumbnail frame shows when you report the render.**
 
 Fix it in the editor when frame 0 is empty or dull:
 - Make the opening scene's key layers **already visible at t=0** (a legible hero title, a visible subject/clip, a composed background) and animate *within* the frame — use `set_layer_keyframes` starting from `offset:0, opacity:1` (drift/parallax/scale) rather than fading the whole scene up from black; or `nudge_layers`/`trim_layer` so the hero layer starts at 0 while secondary elements enter after.
@@ -942,6 +981,8 @@ Beyond the Ken Burns / transition / animated-caption presets, the copilot can ha
 
 **Explainers are built from transparent cutout stickers** — a subject "on stage" while labels, arrows, icons, and props animate in around it. Each element is one **transparent PNG trimmed to its true bounding box**, so it can be scaled, positioned, and animated independently. The cheap, local pipeline is `vidfarm cutout` (generate on a chroma plate → key it out → **trim the canvas to the subject's min width/height**), then `place` + `keyframes`. Full guided harness: `recipes/cutout-graphics-for-explainers.md`. This section is the **placement + motion** reference.
 
+**Default look (house style, unless the director says otherwise): white light-mode stage, kinetic word-by-word captions in dark ink, female TTS narration, and deliberately simple flat-vector illustrations.** Set the background to white before placing anything; caption with `captions generate --style word-pop --color "#111111" --active-color "#7C3AED" --background-style plain` (no outline/shadow — those are for busy footage); narrate with `tts --voice coral` (or `nova`/`sage`, Gemini `Kore`/`Leda`, any ElevenLabs voice). Two or three cutouts per beat, one accent, one font. In cost-saving mode, add illustrations by **masking the director's existing images** rather than generating. Full defaults: `recipes/cutout-graphics-for-explainers.md` → "House style".
+
 **Make the sticker (`vidfarm cutout`).** Local, free, ffmpeg-only, image-only. `vidfarm cutout --generate "<subject>"` AI-generates on a matching plate then keys+trims (only the generation is billed); `vidfarm cutout <file|url>` keys+trims a graphic you already have for $0. Because the output is trimmed tight, its on-frame **width % maps directly to how big the subject reads** — no invisible padding skewing the layout. Knobs: `--preset`/`--key-color` (match the plate), `--pad <px>` (transparent breathing room), `--alpha-threshold <0..255>` (trim faint haloed edges), `--output-format webp`, `--no-trim`. A *moving* subject has no single bounding box → key it as a clip with `vidfarm remove-greenscreen <video>` (→ transparent WebM) instead.
 
 **Place it.** Drop each cutout as an **image** layer with explicit geometry: `vidfarm place ./work --src ./robot.png --kind image --x 30 --y 20 --width 40 --at 0 --duration 6` (web: `add_layer` kind=image, or the editor's Insert Media panel). Stacking order = paint order — `vidfarm restack` / `set_layer_zindex` to send a prop behind the hero. Reuse the same PNG across scenes; a cutout is generated once and reused.
@@ -980,6 +1021,23 @@ For anything bespoke, pass raw stops: `vidfarm keyframes ./work --layer robot --
 
 **Pick the store by lifetime.** A throwaway intermediate (cloud render source, a `place` scratch asset) belongs in the 30-day `temp/` store: `vidfarm upload clip.mp4 --folder temp`, `vidfarm place … --folder temp` — quarantined in one place you can periodically purge. Anything you **approve/share is permanent**, so `vidfarm approve --video ./final.mp4` uploads to **durable My Files** by default (the share video would otherwise 404 after the temp store's 30-day deletion). Only add `vidfarm approve --temp` when you deliberately want a disposable 30-day preview.
 
+## 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:
+
+| Want | Call | devcli |
+| --- | --- | --- |
+| The video (or a photo/carousel post → ordered slideshow) | `POST /api/v1/primitives/videos/download` `{ tracer, payload: { source_url, quality?: "best"\|"hd"\|"full_hd" } }` | `vidfarm download-video <url>` |
+| Just the audio/music/voice track | `POST /api/v1/primitives/audio/download` `{ tracer, payload: { source_url } }` | `vidfarm download-audio <url>` |
+
+Both are async primitive jobs — poll `GET /api/v1/primitives/jobs/:jobId` until `succeeded`, then read `primary_file_url`. Full field-level detail (slideshow response shape, billing, examples) lives in `references/primitives.md`.
+
+**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.
+
+**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.
+
 ## 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).
@@ -1281,9 +1339,11 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `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, paid plan. Aliases: `spend`, `costs` |
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
 | `vidfarm upload <file> [--folder <path>]` | presign → S3 PUT → finalize (`.../temporary-files/presign` + `.../temporary-files`) | upload → durable URL (ephemeral, 30-day TTL; prefer `--folder temp` for scratch). Goes direct to S3, so large files (up to **200 MB**) bypass the ~6 MB Lambda body limit |
-| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
-| `vidfarm download-post <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | download a social/media post into a durable MP4 or slideshow |
-| `vidfarm download-post-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download a social/media post's audio into a durable audio file |
+| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media from a **direct** media URL. Free — no plan, no job |
+| `vidfarm download-video <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | **download a video FROM A WEBSITE** (YouTube/TikTok/IG/X/other supported posts) into durable Vidfarm media; photo/carousel posts return an ordered slideshow. **PAID PLAN** (wallet-billed resolver; free plans get 402). Aliases: `download-post`, `download-url` |
+| `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` |
+
+> **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.
 | `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 |
@@ -1516,9 +1576,11 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/create-overlay" \
   -d '{"tracer": "vox-overlay", "payload": {"prompt": "a friendly cartoon lightbulb mascot, flat vector illustration", "aspect_ratio": "1:1"}}'
 ```
 
-## Primitive: videos/download
+## Primitive: videos/download — **Vidfarm downloads videos off websites for you**
+
+**Capability statement (say this plainly when a user asks "can you download this video?"): yes — on a paid plan, Vidfarm downloads a video straight off a website URL for you.** Hand it a YouTube / TikTok / Instagram / X (Twitter) / other supported post URL and it returns a durable Vidfarm-hosted file. No local yt-dlp, no browser extension, no "I can't access that URL." The route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
 
-Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL asset. This route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
+**Paid-only, and that gate is real.** The resolver is a paid RapidAPI pass-through billed to the wallet, so a free-plan customer gets `402 insufficient_funds`. Never promise this to a free user — route them to the browser fallback below instead.
 
 - `POST /api/v1/primitives/videos/download`
 - Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "quality"?: "best" | "hd" | "full_hd", "save_manifest"?: true }, "webhook_url"?: "..." }`
@@ -1526,8 +1588,20 @@ Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL
   - Video post: read `primary_file_url` / `video.file_url` / `videoUrl` for the durable MP4.
   - Photo/carousel post: read `mediaKind: "slideshow"`, ordered `slideImageUrls[]`, optional `slideAudioUrl`, and `primary_file_url` (first slide image).
 - Billing: RapidAPI pass-through wallet charge (`rapidapi_video_download`) plus the small mirror/extract pass (`video_download_lambda` when MP4 download is involved).
-- Free-plan / no-spend rule: do **not** use this paid route when the user wants a free path. In the web app, tell them to use the browser to find a downloader instead. Fallback wording is explicit: suggest Googling `"youtube video downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"`.
-- devcli wrapper: `vidfarm download-post <url> [--quality best|hd|full_hd]`
+- devcli wrapper: `vidfarm download-video <url> [--quality best|hd|full_hd]` (aliases: `download-post`, `download-url`)
+
+### FREE-PLAN FALLBACK — drive Chrome instead (never dead-end the user)
+
+If the user is on the free plan, says "don't spend money", or cost mode is `minimize`, do **not** call this route. **Load the URL in Chrome and download it by that means** — it costs $0.00 and needs no Vidfarm plan:
+
+1. Open the post/page in Chrome. A real browser session carries the login/consent/age walls that a bare `fetch` can't.
+2. Save the video off the page — right-click → *Save video as*, the browser's downloads pane, or DevTools → Network → the media response.
+3. If the page won't hand it over, Google `"youtube video downloader"` (or `"tiktok/instagram/x/twitter video downloader"`) and use one of those sites in the same Chrome session.
+4. Bring the resulting local file into Vidfarm for free: `vidfarm put-file ./the-file.mp4 --folder <folder>` (devcli) or the web app's upload. From there it's a normal durable asset.
+
+If you're a desktop coding agent with browser automation (Playwright/Puppeteer/CDP, or the user's own Chrome), you can perform steps 1–3 yourself. If you're the web copilot with no browser tool, hand the user these steps — do not claim you downloaded it.
+
+Say the tradeoff out loud once: *"Downloading it for you is a paid-plan feature; on the free plan I'll walk you through grabbing it in Chrome instead."*
 
 Example:
 
@@ -1546,9 +1620,9 @@ Download just the original audio/music/voice track from a supported social/media
 - Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "save_manifest"?: true }, "webhook_url"?: "..." }`
 - Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`, then read `primary_file_url` / `audio.file_url` / `audioUrl`.
 - Behavior: prefers the provider's direct audio track when present; otherwise resolves the source video and extracts audio server-side.
-- Billing: same RapidAPI wallet class as `videos/download`.
-- Free-plan / no-spend rule: same as the visual download route. Use the browser and, if needed, suggest Googling `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"` instead of spending wallet credits.
-- devcli wrapper: `vidfarm download-post-audio <url>`
+- Billing: same RapidAPI wallet class as `videos/download` — **paid plans only**; free plans get `402`.
+- Free-plan / no-spend rule: identical to the visual route — **load the URL in Chrome and download from there**, then `vidfarm put-file` the result. Google `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio downloader"` if the page won't release the track. See the FREE-PLAN FALLBACK block above.
+- devcli wrapper: `vidfarm download-audio <url>` (alias: `download-post-audio`)
 
 Example:
 
@@ -1828,6 +1902,24 @@ Use this when the director wants an **explainer** — a subject "on stage" while
 
 The mechanical trio — **generate on a chroma plate → key it out → trim to the cutout's true size** — is fused into one command, `vidfarm cutout`. Then you `place` and `keyframes` it onto the composition.
 
+### House style — the explainer defaults
+
+**Unless the director asks for something else, build every explainer this way. Don't ask, just do it, and mention the defaults once so they can override.** The whole point of the house style is that explainers read as *clean, bright, and easy* — a busy explainer is a failed explainer.
+
+- **White background, light mode.** A plain white (or near-white `#FFFFFF`–`#FAFAFA`) stage. No dark mode, no gradients, no photographic backdrop, no texture. Light mode reads cleaner on every feed, keeps cutout stickers legible, and makes flat-vector art look intentional. Set the composition/scene background to white first, before placing anything.
+- **Kinetic captions.** Narration is always captioned word-by-word (`vidfarm captions generate ./work --style word-pop`). Because the stage is white, **override the preset's dark-canvas colors to dark ink on light**:
+  ```
+  vidfarm captions generate ./work --style word-pop \
+    --color "#111111" --active-color "#7C3AED" --background-style plain --max-words 4
+  ```
+  One accent color for the active word, everything else near-black. No outline/stroke, no drop shadow, no pill — those exist to survive busy footage and just add noise on white.
+- **Female TTS narration.** Default to a warm, friendly **female** voice and say which one you picked: local-first `vidfarm tts "<script>" --voice coral` (OpenAI — `nova` if the script wants more energy, `sage` for calmer), `--voice Kore` or `Leda` on Gemini, or `vidfarm voices` → `vidfarm tts --cloud --voice <voice_id>` on ElevenLabs. Tell the director they can swap it in one flag.
+- **Clean and simple wins.** One idea on screen at a time. Two or three cutouts per beat, not eight. Generous white space, one accent color, one font. When in doubt, remove an element rather than add one.
+
+**Illustrations default to simplicity.** Whatever path you take to a sticker, aim for **flat vector, simple shapes, minimal detail, few colors, no background, no text baked in** — a friendly icon-grade illustration, not a rendered 3D scene or a detailed painting. Simple art keys cleanly, trims tight, scales without mush, animates readably at 9:16, and stays on-style across a whole cast. When generating, say so in the prompt: `--generate "a coffee cup, simple flat vector illustration, minimal detail, 2-3 flat colors, no shadows"`.
+
+**In cost-saving mode, don't generate illustrations at all — mask them out of images the director already has.** If `vidfarm cost-mode` is `minimize` (or the director says "without burning credits"), the default for adding an illustration is `vidfarm mask <their-image> --crop …` — lifting art out of an infographic, poster, deck slide, brand sheet, or screenshot for **$0 and zero AI calls**. Ask for source art before you ask for a generation budget; the guided loop is **"Mask from an image you already have"** below.
+
 ### The guided sequence (prompt harness)
 
 **Step 0 — Decide the cast of stickers.** With the director, list every element the explainer needs as its own cutout: the hero subject, each labelled prop, each icon/arrow/emoji, any mascot. Each becomes one transparent PNG. Stickers are reusable — generate once, reuse across scenes.
@@ -1858,7 +1950,7 @@ The mechanical trio — **generate on a chroma plate → key it out → trim to
 
 **Step 2 — Show the director each cutout, get corrections.** Cutouts are cheap to regenerate. Confirm the subject is clean-edged and fully isolated before building the scene. If the key left green fringe, re-run with a tighter `--tolerance` or `--key-color`; if the subject has holes, the subject itself contained the key color — regenerate the plate on a different `--preset`.
 
-**Step 3 — Stage them on the composition.** Fork/seed a working composition (`vidfarm pull` or `vidfarm serve`), then drop each cutout as an **image layer**, sized and positioned deliberately:
+**Step 3 — Stage them on the composition.** Fork/seed a working composition (`vidfarm pull` or `vidfarm serve`), **set the stage to a white light-mode background first** (house style), then drop each cutout as an **image layer**, sized and positioned deliberately:
 ```
 vidfarm place ./work --src ./robot.png --kind image --x 30 --y 20 --width 40 --at 0 --duration 6
 vidfarm place ./work --src ./arrow.png --kind image --x 62 --y 45 --width 12 --at 1.5 --duration 4

package/SKILL.md

@@ -73,6 +73,7 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 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`
+4b. **"Download this video/audio from <a website URL>"** → Vidfarm fetches it for you on a **paid plan**: `POST /api/v1/primitives/videos/download` (or `/audio/download`); devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. Works on YouTube, TikTok, Instagram, X, and other supported posts; returns a durable Vidfarm file (photo/carousel posts → an ordered slideshow). **Free plan gets a 402 — don't call it. Tell the user (or, with browser automation, do it yourself) to open the URL in Chrome and download it from the page, then `vidfarm put-file ./the-file.mp4` to bring it in for $0.** Never answer "I can't download that." Details: `references/assets-and-sourcing.md`.
 5. "Script / batch / render loop" → `references/automation-and-local-dev.md`
 6. "I need TTS / music / captions / background removal" → `references/primitives.md`
 

package/dist/src/cli.js

@@ -600,12 +600,19 @@ Files (multi-step flows the devcli handles for you):
     --notes <text>          Metadata notes (what it is / when to use it) — vector-embedded for search
                             e.g. vidfarm put-file About.md --folder acme-skincare
                                  echo "..." | vidfarm put-file --stdin --as About.md --folder acme
-  download <url> [dest]     Stream any Vidfarm/media URL to disk
-  download-post <url>       Download a social/media post into Vidfarm media → POST /api/v1/primitives/videos/download
+  download <url> [dest]     Stream any Vidfarm/media URL to disk (free — direct media URLs only)
+  download-video <url>      PAID. Download a video FROM A WEBSITE (YouTube, TikTok, Instagram,
+    (aka download-post)     X/Twitter, and other supported posts) into durable Vidfarm media.
+                            Photo/carousel posts come back as an ordered slideshow.
+                            → POST /api/v1/primitives/videos/download
     --quality <q>           best | hd | full_hd (default: best)
     --no-wait               Return the queued job immediately instead of polling
-  download-post-audio <url> Download a social/media post's audio into Vidfarm → POST /api/v1/primitives/audio/download
+  download-audio <url>      PAID. Download just the AUDIO track (music/voice) from a website post
+    (aka download-post-audio)  → POST /api/v1/primitives/audio/download
     --no-wait               Return the queued job immediately instead of polling
+                            FREE PLAN: both bill the wallet via a paid resolver. If the user is
+                            free/no-spend, don't call them — open the URL in Chrome and download
+                            it from the page, then 'vidfarm put-file ./the-file' to bring it in.
   tasks                     Cloud Status: imports · forks · renders · jobs → GET /api/v1/user/me/tasks
     --running|--done|--error  Filter (or --status <all|running|done|error>); --limit <n>
   wallet                    Wallet cost log: balance + what each video cost → GET /api/v1/user/me/wallet
@@ -769,7 +776,10 @@ function loadDotEnvCredentials(cwd = process.cwd()) {
 async function main() {
     const argv = process.argv.slice(2);
     loadDotEnvCredentials();
-    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    // `help` must be caught here too: without it the bare word falls through the
+    // dispatch switch and is treated as a TEMPLATE ID by the default `serve` case,
+    // which boots a local server on :3000 instead of printing help.
+    if (argv.length === 0 || argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
         process.stdout.write(HELP);
         return;
     }
@@ -952,10 +962,14 @@ async function main() {
         case "download":
             await runDownloadCommand(rest);
             return;
+        // Aliases: agents look for "download a video from a website", not "post".
         case "download-post":
+        case "download-video":
+        case "download-url":
             await runDownloadPostCommand(rest);
             return;
         case "download-post-audio":
+        case "download-audio":
             await runDownloadPostAudioCommand(rest);
             return;
         case "files":
@@ -6877,6 +6891,27 @@ async function runDownloadCommand(argv) {
         console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
     }
 }
+// The FREE fallback for the paid download primitives. Both routes ride a paid
+// RapidAPI resolver billed to the wallet, so a free-plan customer gets a 402.
+// Rather than dead-ending them, tell the agent to drive the user's own browser:
+// open the URL in Chrome and download it from there (no Vidfarm spend).
+// NOTE: a hoisted function, NOT a module const — `void main()` runs synchronously
+// until its first await, so a const declared this far down the file is still in
+// its TDZ when a command handler reads it (same gotcha as the *_HELP consts).
+function downloadFreeAlternative() {
+    return "open the URL in Chrome and download it from the page yourself ($0.00 — no wallet spend)";
+}
+function printDownloadFreePathHint(ctx, kind) {
+    if (ctx.json)
+        return;
+    const noun = kind === "video" ? "video" : "audio";
+    console.log("");
+    console.log(`${YELLOW}Free path (no Vidfarm spend):${RESET} load the URL in Chrome and grab the ${noun} from there.`);
+    console.log(`${DIM}  1. Open the post/page in Chrome (a real browser session handles the login/consent walls).${RESET}`);
+    console.log(`${DIM}  2. Save the ${noun} from the page — right-click → Save, the browser's downloads, or a downloader site.${RESET}`);
+    console.log(`${DIM}  3. Google "youtube ${noun} downloader" or "tiktok/instagram/x ${noun} downloader" if the page won't give it up.${RESET}`);
+    console.log(`${DIM}  4. Then bring the local file into Vidfarm for free: vidfarm put-file ./the-file --folder <folder>${RESET}`);
+}
 async function runDownloadPostCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -6891,6 +6926,11 @@ async function runDownloadPostCommand(argv) {
         throw new Error("download-post --quality must be one of: best, hd, full_hd.");
     }
     const ctx = commonContext(parsed.values);
+    guardBilled(ctx, {
+        label: "download a video from a website (paid plan — RapidAPI resolver)",
+        estimate: "small per-download wallet charge",
+        freeAlternative: downloadFreeAlternative()
+    });
     const tracer = String(parsed.values.tracer ?? `devcli-download-post-${Date.now().toString(36)}`);
     const submit = await apiRequest({
         method: "POST",
@@ -6899,6 +6939,9 @@ async function runDownloadPostCommand(argv) {
         auth: ctx.auth,
         body: { tracer, payload: { source_url: url, quality } }
     });
+    if (!submit.ok && (submit.status === 402 || submit.status === 401 || submit.status === 403)) {
+        printDownloadFreePathHint(ctx, "video");
+    }
     assertApiOk(submit, "download-post");
     const jobId = submit.json?.job_id;
     if (!jobId || parsed.values["no-wait"]) {
@@ -6920,6 +6963,11 @@ async function runDownloadPostAudioCommand(argv) {
     if (!url)
         throw new Error("download-post-audio requires a source URL.");
     const ctx = commonContext(parsed.values);
+    guardBilled(ctx, {
+        label: "download audio from a website (paid plan — RapidAPI resolver)",
+        estimate: "small per-download wallet charge",
+        freeAlternative: downloadFreeAlternative()
+    });
     const tracer = String(parsed.values.tracer ?? `devcli-download-post-audio-${Date.now().toString(36)}`);
     const submit = await apiRequest({
         method: "POST",
@@ -6928,6 +6976,9 @@ async function runDownloadPostAudioCommand(argv) {
         auth: ctx.auth,
         body: { tracer, payload: { source_url: url } }
     });
+    if (!submit.ok && (submit.status === 402 || submit.status === 401 || submit.status === 403)) {
+        printDownloadFreePathHint(ctx, "audio");
+    }
     assertApiOk(submit, "download-post-audio");
     const jobId = submit.json?.job_id;
     if (!jobId || parsed.values["no-wait"]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.20",
+  "version": "0.21.22",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {