@officexapp/vidfarm-devcli 0.21.28 → 0.21.29

package/SKILL.md

@@ -39,7 +39,20 @@ The last two are production *methods*, not just budgets. **rich-ai**: generate t
 
 **Those charges go to the user's own AI provider keys (BYOK)** — saved via `vidfarm add-provider-key <provider> <key>` or **Settings → Bring your own keys** (<https://vidfarm.cc/settings/developer>). The providers bill those keys directly; Vidfarm wallet credits only apply when the user deliberately runs on the platform key. That's why `minimize` is genuinely $0, not just cheap. With the devcli, persist it via `vidfarm cost-mode <choice>` (billed commands then respect it; `minimize` refuses billed ops without `--yes`). **Narration follows the mode automatically**: in `minimize` and `hybrid`, plain `vidfarm tts "…"` uses the free local Kokoro voice — ask for a premium voice explicitly (`--style`/`--voice`/`--provider`/`--cloud`) when the piece needs one, and tell the user which tier they're hearing. Then ask if they want it remembered across sessions — save to the agent's own memory (Claude Code → `CLAUDE.md`; Codex/OpenCode/others → `AGENTS.md`; or a note they name), asking first. In the **web app UI** there's no memory file to write, so just ask each time unless they state a standing preference. Full guidance is in the director skill.
 
-**Even in `minimize`, you can still get custom images — for free, manually.** When stock and masking existing art won't cover a bespoke graphic, don't say "not possible" and don't quietly spend: ask the user once whether to **default to free manual image generation**, then write the prompt and have them run it in <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space, and hand the PNG back (`vidfarm put-file`, or drag into My Files). Ask for **one image containing every graphic you need**, gridded on a **flat pure-green background** (`#00FF00`) with no text — one round trip instead of many, which is the token-efficient move. Then split it locally at $0: `vidfarm mask ./sheet.png --crop x,y,w,h --flat "#00FF00"` once per element gives you snug transparent stickers. Prompt template + full loop in the director skill.
+**Even in `minimize`, you can still get custom images — for free, manually.** When stock and masking existing art won't cover a bespoke graphic, don't say "not possible" and don't quietly spend: ask the user once whether to **default to free manual image generation**, then write the prompt and have them run it in <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space, and hand the PNG back (`vidfarm put-file`, or drag into My Files). Ask for **one image containing every graphic you need**, gridded on a **flat chroma plate** with no text (`#00FF00` green by default — but pick a different plate when the art itself is green, or the key will punch holes through it) — one round trip instead of many, which is the token-efficient move. Then split it locally at $0 in one command: `vidfarm sticker-pack ./sheet.png --items "a,b,c" --out-dir ./stickers` keys the green out, finds each item in the sheet automatically, and writes a snug transparent sticker per item. Prompt template + full loop in the director skill.
+
+**"Make me a sticker pack" = one greenscreen sheet, then masked apart.** A pack is a *set* that has to share one art style, so never generate the items one by one — generate a single image holding all of them on a flat `#00FF00` plate, then split it: `vidfarm sticker-pack --generate "<theme>" --items "a,b,c,d"` (one billed image job for the whole set, then free local keying + automatic alpha segmentation + per-item trim + a `stickers.json` manifest). **The plate must be a color the art doesn't use** — a green pack (leaves, frogs, plants, money) on a green plate keys holes through the art. The commands pick the plate off the subject when generating (green → magenta → blue → black → white, and they tell you when they move) and **detect the plate from an existing sheet's corners**, so a red or purple sheet from a web tool just works; pin it with `--key-color`/`--preset`, or `--no-auto-key` for plain green. Stickers are **not necessarily small** — a full-frame landscape or backdrop is as valid an item as an icon — and they're normally **animated on the canvas** (`vidfarm place` + `vidfarm keyframes` presets: pop-in, float, shake, grow, slide-in, drift). A sticker whose own art moves is a **transparent WebM** (`vidfarm remove-greenscreen <video>`), and for GIF-only surfaces both paths can emit **transparent GIFs** (`sticker-pack --output-format gif`, `remove-greenscreen --gif`, 1-bit alpha). Full recipe in the director skill.
+
+## Ask the second question too — interactive or autonomous?
+
+Cost mode says how much MONEY to spend. It doesn't say how much of the user's own HANDS you may use — and that moves quality more. **Ask both, up front**, and persist the answer with `vidfarm mode interactive|autonomous` (the twin of `vidfarm cost-mode`). The axes are independent: every cost mode runs either way.
+
+- **interactive** — at checkpoints you hand the user a copy-paste brief and they hand files back: an **image prompt** they run in a *free* frontier web generator (meta.ai / ChatGPT / Gemini / a HF Space), or a **keyword list** they use to search TikTok/YouTube and download clips with a free downloader. Costs them a few minutes; the free web models usually beat what an API budget buys, and a human eye picks better footage than a keyword scan.
+- **autonomous** — you finish end-to-end with zero steps from them: source clips yourself (browser control → `vidfarm clipper`/`raws scan` → public raws), generate within budget, or do without.
+
+`minimize + interactive` is the sweet spot: **$0 videos that still get custom art.** `minimize + autonomous` means no custom art at all — say so before defaulting to it. Mint the briefs with `vidfarm handoff image --theme "<what>" --items "a,b,c"` (defaults to a sticker pack) and `vidfarm handoff raws --keywords "<kw>,<kw>"` (only after browser control and cloud scan are ruled out).
+
+**Storyboard before you build.** The plan lives with the project as `STORYBOARD.md` (ordered frames: `duration`, `status`, `src`, `scene`, `voiceover`) plus an optional `SCRIPT.md`, and the Vidfarm editor renders it — a Storyboard view with a contact sheet, per-frame comments, and `outline → built → animated` progress. Draft it with `vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"`, read it with `vidfarm storyboard ./work`, and get approval there: a plan is free to redo, a rendered scene is not.
 
 ## Get hands-on now — pick your surface
 
@@ -100,7 +113,10 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 - Render only through `POST /api/v1/compositions/:forkId/render`; never call the renderer directly.
 - Submissions are **not idempotent** — every render/primitive POST charges again. Check status before retrying.
 - **No HTML slop.** Compositions are HTML, but a video is not a web page: never author CTA "buttons", benefit chip/badge rows, frosted or bordered cards holding a headline + URL, gradient text, feature grids, or bullet lists — none of that exists in a real TikTok, and nothing in a video is clickable. Say it as timed text on the footage. Arrows, scribble/underline marks, italics, ALL-CAPS, color pops, emoji, cut-out stickers, and mock social UI are fine.
-- **On devcli, `vidfarm qa <dir>` before every render.** Free, instant, local-only blocklist for the slop above + the font regime. Feedback, not a gate (exits 0, never automatic). No REST/web equivalent.
+- **Structure before polish — the four charges, written before the timeline.** 🪝 **Hook**: the first line is a complete clause naming a *situation*, not a label; on screen at `start:0` (chunk 1 is read before any audio). 🔄 **Loop**: one open question by 0:10, stated on screen, **closing inside this video**, with an answer the viewer can't guess. 😍 **Payoff**: shown, not summarized, before the final beat. 🎣 **Bait**: one ask, final beat + post caption. Banned openers: throat-clearing, a logo, a title card, a fade from black. Full harness: `references/hooks-and-virality.md`; checkable form: `vidfarm regime show hooks`.
+- **The first frame is the thumbnail.** Frame 0 is one frame of ~30 in the first second, but it's the poster every feed and share link freezes on — so it's seen by more people than the video is. Never open on black, an empty frame, or a fade-up: a real visual at `start:0`, the hook words already up, and no *entrance* transition on the first clip (junction transitions between later clips are fine). Check it with `vidfarm stills <dir> --at 0`.
+- **On devcli, `vidfarm qa <dir>` before every render.** Free, instant, local-only blocklist for the slop above + the first frame + the font regime. Feedback, not a gate (exits 0, never automatic). No REST/web equivalent.
+- **Ask one-time vs bulk before you build.** Volume = **scripting mode**: a pinned base fork, a loop varying ONE thing, and a **`QA_REGIME.md`** — the director's own written standard, because a fifty-video loop has no human watching every frame. `vidfarm regime init short-form --out ./work/QA_REGIME.md` (bases: `short-form`, `hooks`, `ugc-testimonial`, `explainer`, `product-demo`), then `vidfarm qa ./work --regime <name|path>` — stackable, any user file valid, auto-discovered from the work dir. Its `checks:` are machine-settled; its `- [ ]` items come back for **you** to answer honestly.
 - **Caption regime is mandatory**: an imported display font (Montserrat default / TikTok Sans), weight 700–900, ~36–64px on a 1080-wide frame, inside the 8%–85% safe zone, and exactly one of four backgrounds — `outline`, `plain`, an active-word `spotlight`/`karaoke` pill, or a tight-hugging `highlight-solid` band (radius ≤8px, no border/shadow/gradient/blur).
 - In the web editor, CSS/declarative motion only (JS animation adapters are stripped on save); locally via `vidfarm serve` the full JS adapters work.
 - Treat `forkId` as an unguessable bearer token. Never put provider secrets in composition HTML/JSON.