@officexapp/vidfarm-devcli 0.21.26 → 0.21.28

package/SKILL.md

@@ -18,7 +18,7 @@ Vidfarm is a video composition studio you drive as a **director**. You fork a pu
 
 Every visual on the timeline is painted with one of three brushes. Reach for them in this order — it is combinatorially cheaper and usually better:
 
-1. **Raw clips** — cut/remix existing footage (your library, or hunted from a URL/VOD). Cheapest; the workhorse.
+1. **Raw clips** — cut/remix existing footage. Cheapest; the workhorse. Check the **public raws catalog by category** before you hunt or generate anything: `vidfarm public-raws --categories` lists free, pre-tagged shelves (scroll-stoppers, greenscreen, reaction, b-roll, …) with live counts, and `--category <shelf>` pulls one. A shelf is also a ready-made clip pool for **bulk scripting** — fan one composition into N variants without a single download or generation call. Then your own library, then hunted from a URL/VOD.
 2. **HTML/JS hyperframes** — video-from-HTML: CSS/GSAP/anime.js motion, animated text + image elements, data-viz. Cheap, deterministic, infinitely re-skinnable.
 3. **Pure AI generation** — AI image/video/voice/music. Most expensive (AI *video* especially). Use last, only where the first two genuinely can't cover the beat.
 
@@ -32,7 +32,10 @@ Before spending any AI credits, ask which posture they want and **quote the per-
 |---|---|---|
 | **minimize** | **$0 — explicitly free** | free local compute + free stock media; no AI spend at all |
 | **hybrid** *(recommended)* | **~$0.01–$1** | free where free, pay AI only where it clearly wins |
-| **rich-ai** *(stored as `pure-ai`)* | **$1+** | best quality; AI image/video/voice/music freely |
+| **rich-ai** | **$1+** | AI video gen buys **reusable greenscreen raws** — keyed once, animated/remixed in hyperframes HTML/CSS, then **saved to the library** so later videos reuse them for ~$0 |
+| **pure-videogen** | **$5+** | every shot is generated: text script → image storyboard → frame-by-frame scene generation. No reuse, no HTML motion |
+
+The last two are production *methods*, not just budgets. **rich-ai**: generate the cast and props on greenscreen (`vidfarm avatar "<who>" --say "<line>"`, `vidfarm create-overlay "<subject>"`, or `generate video` on a flat key-color plate), key them, animate in HTML over your other raws, and **persist every asset** (`vidfarm put-file … --folder greenscreen/<name> --notes "…"` or `vidfarm clipper … --folder <name>` for `/raws`) — local under `~/.vidfarm` by default, and mirrored to the cloud with `vidfarm sync push /files` + `sync push /raws` on a paid/Pro plan. Search `vidfarm raws search` and `vidfarm public-raws --category greenscreen` before generating anything. **pure-videogen**: approve the script in text and the look as storyboard stills (cheap `generate image`, `--ref` for character lock) *before* generating any footage, then generate scene by scene off those keyframes (chaining each scene's last frame into the next for continuity) — and quote the number first, since it's ~5× rich-ai.
 
 **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.
 
@@ -69,7 +72,7 @@ This page does not contain the workflows. Pull the full director skill and load
   - `editor-workflows` — timeline editing, decompose, captions, the three paintbrushes & two replication harnesses
   - `assets-and-sourcing` — raws hunts, My Files, recurring characters
   - `automation-and-local-dev` — REST + `vidfarm` devcli + local serve loop
-  - `onboarding` — "help me figure out what to make" interview
+  - `onboarding` — "help me figure out what to make" interview, and the **consultation** flow
   - `primitives` — TTS, STT, music, overlays, background removal, product placement
   - `rest-api` — complete REST map (load only for direct HTTP integration)
 - **Updating Vidfarm:** `https://vidfarm.cc/update.md` — **fetch this file whenever the user asks to update/upgrade Vidfarm**, says their skill or devcli is out of date, or hits a command/route that "used to work". It's the clean uninstall→reinstall runbook for BOTH halves (the `vidfarm` skill pack and `@officexapp/vidfarm-devcli`), and it carries the current breaking-change notes — read it live rather than improvising an `npm i -g`, because the notes are exactly what a blind reinstall misses.
@@ -80,11 +83,12 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 
 ## Router — where to go from the user's ask
 
-1. "Help me figure out what to make" → `references/onboarding.md`
+1. "Help me figure out what to make" **or "give me a consultation"** → `references/onboarding.md`. A consultation *is* the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks. Run the primitives; don't improvise the strategy in chat.
 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`.
+4c. **"Create an avatar"** (spokesperson / presenter / host / UGC creator / talking head) → always a **talking-head VIDEO with spoken audio**, generated on an exact-key-color **greenscreen** plate and keyed off it in the same job → a **transparent presenter** you layer over any background. `vidfarm avatar "<who they are>" --say "<their line>" [--ref headshot.png]` / `POST /api/v1/primitives/videos/create-avatar`. Details: `references/primitives.md` → "Primitive: talking_avatar".
 5. "Script / batch / render loop" → `references/automation-and-local-dev.md`
 6. "I need TTS / music / captions / background removal" → `references/primitives.md`
 7. **"Update / upgrade vidfarm"** (or anything that smells like a stale install — a missing command, a 404 on a documented route, a version mismatch) → fetch <https://vidfarm.cc/update.md> and follow it. Update the skill pack and the devcli **together**; updating one alone is the usual cause of "the skill says to do X but it fails."
@@ -95,6 +99,9 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 - Never build composition HTML by string concatenation — parse, edit, re-serialize the DOM.
 - 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.
+- **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.
 

package/clipper.md

@@ -56,8 +56,9 @@ Ask these, in one message, with the defaults stated:
    gig id or your mailbox id for it." — required, no default. If they have none of the three but do
    have an API key, run `GET /mailboxes/mine` and show them the gigs they're already in to pick from.
 2. **Cost mode — default `minimize`.** Cheapest: free local rendering on their machine, no surprise
-   AI spend. `hybrid` pays for AI only where it clearly wins. `rich-ai` is best quality and most
-   expensive. Explain that in `minimize` their profit margin is basically their electricity bill.
+   AI spend. `hybrid` pays for AI only where it clearly wins. `rich-ai` ($1+/video) spends AI video gen on
+   reusable greenscreen raws and animates them in HTML. `pure-videogen` ($5+/video) generates every
+   frame from a storyboard — most expensive. Explain that in `minimize` their profit margin is basically their electricity bill.
 3. **Free manual image generation — default ON, but ask.** In `minimize` you can still get custom
    artwork for $0: you write the image prompt, *they* paste it into a free generator
    (<https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space) and hand the PNG back.