@officexapp/vidfarm-devcli 0.21.34 → 0.21.36

package/SKILL.md

@@ -41,15 +41,17 @@ The last two are production *methods*, not just budgets. **rich-ai**: generate t
 
 **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. **And the art itself must be closed and solidly filled** — outline-only/hollow art (or a near-plate fill, or anything translucent/glowing) has its interior keyed away and composites as a rim around a see-through hole. The generation prompts say so for you; write it in by hand when you prompt a generator directly, and check the `⚠ N% hollow` / `hole_pct` flag each command reports after keying. 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.
+**"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 key is connectivity-based, so the art is far freer than a chroma key implies:** the plate is flood-filled inward from the sheet's edge and only background that *reaches* the edge is removed, so plate-colored detail inside an item and hollow/outline shapes survive, and the plate is un-mixed out of each edge pixel individually (no green fringe). What still matters is the **silhouette** — an item's outer edge must differ from its plate and must be crisp (nothing glowing/blurring/shadowing into the background) — plus clear gaps between items. **And you can give every sticker its OWN plate color:** `--sheet-mode zoned` asks for a grid of solid color *panels*, one item per panel, each panel's plate picked against that item (a green frog on magenta beside a pink flower on green), keyed panel-by-panel, with names pinned to panels instead of guessed from reading order. It's the default for 2+ named items; `--sheet-mode flat` (or a model that just ignores the grid — detected automatically, re-keyed as one plate) falls back to the classic single-color sheet. `--key-mode flat` restores the plain chromakey, and `--refine` re-cuts each item with local ONNX matting for painterly/soft/furry art. 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.
+- **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. The third checkpoint is the cheapest: **let them pick the voice** — `vidfarm voices --sample` (premium) or `vidfarm voices --free --sample` ($0 local) writes listenable clips to `./voice-samples`, **free on both tiers**, so offer it in `minimize` exactly as readily as in `hybrid`.
 - **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.
 
+**Premium voices don't need an ElevenLabs account.** Vidfarm carries its own ElevenLabs connection, so the full premium catalog is available to any user for **vidfarm wallet credits** (pennies per narration) — no signup, no API key, no subscription. Put that on the table when you offer voices instead of letting the user assume premium narration is a door they have to unlock elsewhere; `--own-key` is only for people who already have a key and want to bill their own account.
+
 `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.
@@ -76,18 +78,31 @@ vidfarm skills add vidfarm  # install the full director skill locally
 
 ## Fetch the real knowledge (do this next)
 
-This page does not contain the workflows. Pull the full director skill and load only the reference you need:
+This page does not contain the workflows. **If the devcli is installed, you already have all of it on disk** — a full copy of the pack ships in the npm tarball, pinned to that CLI version:
+
+```bash
+vidfarm skill ls                   # every file, with sizes
+vidfarm skill search "greenscreen" # grep all of it — find the paragraph, then open that file
+vidfarm skill show primitives      # shorthand or an exact path
+```
+
+No account, no network. It is documentation, not entitlement — the free-local half (clips, hyperframes, `serve` render, `qa`, harnesses, `dedupe`, local TTS/STT) runs offline; AI generation, hosted render, `recycle`, `download-video` and marketplace still need `vidfarm login` and a cloud call.
+
+Otherwise, pull it over the network and load only the reference you need:
 
 - **Full director skill (rollup):** `https://vidfarm.cc/skill/vidfarm`
-- **Individual reference files** (load on demand, not all at once):
-  `https://vidfarm.cc/skill-pack/vidfarm/files/references/<name>.md` where `<name>` is one of:
-  - `core-workflows` — discovery, auth, fork/publish/share, cost spectrum
-  - `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, and the **consultation** flow
-  - `primitives` — TTS, STT, music, overlays, background removal, product placement
-  - `rest-api` — complete REST map (load only for direct HTTP integration)
+- **Individual files** (load on demand, not all at once) — `https://vidfarm.cc/skill-pack/vidfarm/files/<path>`. **Any path in the pack works**, not just `references/`; the full index with sizes and "read it when" lives in the rollup's *File Index* section. The whole inventory:
+  - `references/core-workflows.md` — discovery, auth, fork/publish/share, cost spectrum, dedupe-before-publish
+  - `references/editor-workflows.md` — timeline editing, decompose, captions, the three paintbrushes & two replication harnesses *(the biggest read)*
+  - `references/assets-and-sourcing.md` — raws hunts, My Files, recurring characters, downloading media off a URL
+  - `references/automation-and-local-dev.md` — REST + `vidfarm` devcli command table + scripting mode + local serve loop
+  - `references/hooks-and-virality.md` — **the four charges. Read before writing any hook, caption script, or re-theme**
+  - `references/reviewing-renders.md` — **the holistic pass. Read before reporting a video as done**
+  - `references/onboarding.md` — "help me figure out what to make" interview, and the **consultation** flow
+  - `references/primitives.md` — TTS, STT, music, avatars, overlays, background removal, product placement
+  - `references/rest-api.md` — complete REST map (load only for direct HTTP integration)
+  - `recipes/` — `find-and-fork-template.md` · `retheme-template.md` · `local-edit-render-approve.md` · `onboard-a-new-director.md` · `bulk-scripting-with-a-harness.md` (volume/N-variant work) · `cutout-graphics-for-explainers.md` (sticker-art explainers)
+  - `harnesses/` — `README.md` (**start here for anything harness-shaped**: the three director phrasings, the format, the DNA strands) plus the bundled bases `short-form` · `hooks` · `ugc-testimonial` · `explainer` · `product-demo`, each as `<name>.HARNESS.md`
 - **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.
 - **Skill pack index (what else is installable):** `https://vidfarm.cc/skill-pack/index.json`
 - **Platform architecture (how it all fits together):** `https://vidfarm.cc/skill/vidfarm-platform`
@@ -104,7 +119,9 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 4b-ii. **"Tweet to TikTok" / "Reddit to TikTok" / "make a video out of this thread / subreddit / account"** → `vidfarm recycle <source>` (devcli), or `POST /api/v1/primitives/social/recycle` with `{ tracer, payload: { source_url, max_records } }`. It **decomposes** a Reddit thread (post + comments), a subreddit (its threads), an X thread (tweet + replies), or an X profile (their posts) into raw JSON — text, comment tree, media URLs, author avatar, engagement stats — and hands it back **unranked and unsummarized** so you pick the hook, the punchline comment, the stat. Auto-paginates via `nextCursor`; `max_records` is the spend ceiling. Brokers the reddit-lead-gen / x-lead-gen OfficeX apps and waits out their async job for you. **Paid plan.** 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".
 4d. **"Post this again / to several accounts / on another platform"** → **deduplication**. Platforms fingerprint uploads; the second copy of the same render gets suppressed as duplicate/reused content. `vidfarm dedupe <mp4> [--variants N]` runs on the **exported file** — free, local ffmpeg, **no re-render** — nudging skew/zoom/rotate/speed/saturation/grain a couple of percent and stripping container metadata, invisibly to a viewer. `--variants N` mints N copies distinct from the original *and from each other*, one per account/slot. Cloud twin: `POST /api/v1/primitives/media/dedupe`. Details: `references/core-workflows.md` → *Deduplicate before you publish*.
+4e. **Anything with the word "harness"** — "create me a harness", "update the harness for this format", "give me the harness for this template_id" → a known, named process. `harnesses/README.md` for the three phrasings and the format; `recipes/bulk-scripting-with-a-harness.md` if it's a batch. The third phrasing means the **decomposition**: `vidfarm harness derive <forkId>`.
 5. "Script / batch / render loop" → `references/automation-and-local-dev.md`
+5b. **"Explainer with cutout/sticker art"** (flat illustrations on a stage, sticker sheets, "like those animated explainer videos") → `recipes/cutout-graphics-for-explainers.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."
 
@@ -115,13 +132,14 @@ 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. The test: *could you have made this element with the tools inside TikTok's own editor* (font, color, stroke, shadow, tight text box, rotation, animation presets, stickers, emoji, drawn marks)? If you reached past that — a padded capsule, a border, a gradient fill, a blur panel, a card — cut it. So: no CTA "buttons", no benefit chip/badge rows, **no single pill around a static stat or label** (`( 10 hrs / week )`, `( STEP 2 )` — the only legitimate capsule is the active-word `spotlight`/`karaoke` highlight), no frosted/bordered cards holding a headline + URL, no gradient text, feature grids, or bullet lists. Nothing in a video is clickable. Say it as timed text on the footage; emphasize with size, weight, ALL-CAPS, an accent color, or a drawn circle. Arrows, scribble/underline marks, italics, color pops, emoji, cut-out stickers, and mock social UI are fine.
-- **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`.
+- **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 harness show hooks`.
+- **Then cut ruthlessly — every second is precious.** First assembly is ~30–50% too long. **Deletion test** on every beat (delete it; if the video survives, it stays deleted); what's left must serve a charge. Cut intros, the wind-up before the claim, restatement, >0.35s silences, real-time process, establishing shots, and any tail after the last word — then **ripple the hole closed** or fluff becomes dead air. Not speed: keep the comedic beat, the payoff, and readable cue time. Length is an output. `vidfarm qa` flags `dead-air` / `dead-tail` / `slow-scene`.
 - **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.
 - **Review the finished video as a WHOLE, and never by one frame.** Agents build scene by scene, so every scene passes alone while the video drifts as a sequence — shifting margins, three type sizes, a wandering accent colour, N identically-long beats, a jarring join, a dead band under top-anchored content. Tile ~12 stills into one contact sheet — one command, `vidfarm stills <dir> --sheet` — and **read it as an image**: balance, spacing, one type scale, one palette, deliberate pacing, clean joins — then fix the *system*, not the one odd scene. Compare frames from two different scenes (a frozen render passes duration, frame-count and audio-hash checks), verify audio by measurement (~12–15 dB speech-over-bed, peak <0 dBFS) rather than "sounds fine", and report what you measured separately from what you judged. Your own "verified, looks good" is the least reliable signal here — it was wrong on every video of a 32-video batch. Method: `references/reviewing-renders.md`.
 - **Ask about deduplication before you publish or bulk-produce.** "Is this going out more than once — several accounts, another platform, a re-post later? How many copies?" Ask *before* the render or the batch, not after: dedupe is a post-render ffmpeg pass, so answering early keeps it at **render once → dedupe N** instead of paying for a second render per slot. Then post each variant to a **different** account — two accounts posting the same variant defeats the point.
-- **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).
+- **Ask one-time vs bulk before you build.** Volume = **scripting mode**: a pinned base fork, a loop varying ONE thing, and a **`HARNESS.md`** — the director's own written standard, because a fifty-video loop has no human watching every frame. `vidfarm harness init short-form --out ./work/HARNESS.md` (bases: `short-form`, `hooks`, `ugc-testimonial`, `explainer`, `product-demo`), then `vidfarm qa ./work --harness <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 **inside that band, placed in the emptiest part of the frame** (look at a still; text over open sky beats a lower third over the subject, and usually needs no plate at all). Long narration is paged into 3–5-word kinetic cues, never one static wall of text. 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.