@officexapp/vidfarm-devcli 0.21.18 → 0.21.20

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

@@ -87,6 +87,7 @@ Vidfarm work can burn real AI credits on the user's wallet / provider keys. **Sa
   - **Check the keyless sources first — Openverse and iconify.** Openverse (CC/CC0 **music, SFX, and images**) and iconify (**icons**) need **no account or key at all**, so they always work in `minimize` mode. Prefer them for BGM, sound effects, icons, and CC imagery before anything else.
   - **Pixabay key** unlocks the photos/vectors/stock-video slots (music/SFX/icons/CC images are keyless). It's a **free** stock-media key, not an AI key. Don't assume it's missing when a search comes up short — it **may already be saved**: check `vidfarm provider-keys` (or the web app's **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>). If it isn't, the user grabs a free one at <https://pixabay.com/api/docs/> and saves it once — `vidfarm add-provider-key pixabay <key>`, the Settings surface, or by handing the key to their desktop AI agent to run that command. After it's saved, cost-mode `minimize` sourcing works end-to-end at $0.
 - **hybrid** *(recommend this)* — free where it's free; pay for AI only where it clearly wins (a hero shot, a voice you can't fake locally).
+  - **Free-TTS draft, premium-TTS final (opt-in — offer it, don't assume it).** Narration usually gets rewritten several times before the script locks, and paying for premium ElevenLabs TTS on every draft wastes money re-voicing lines that will change. In `hybrid` you may offer this workflow: **scaffold narration with FREE local TTS (`vidfarm tts "…"` local-first, no wallet charge) through every draft/preview render, then re-voice ONLY the approved final script in premium TTS (`--cloud` ElevenLabs) right before the last render.** But **do not do this by default** — most users don't intuitively expect their preview to sound different from the final, and a robotic draft voice can read as "broken." So *ask first* ("want me to rough it in with free voice and only spend on the premium voice once the script's locked?"), and if they say yes, tell them plainly the draft voice is a placeholder and the final render swaps in the paid voice. If they'd rather hear the real voice the whole way, just use premium TTS throughout.
 - **rich-ai** — best quality; use AI image/video/voice/music freely.
 
 Then **ask whether to remember the choice**, and save it where it will actually be read next time:
@@ -105,6 +106,18 @@ If the user hasn't picked yet and you're about to spend, name the cheaper path a
 - For heavy edits, read the grounding artifacts before acting: `video-context.json`, `editor-harness.json`, and local `.harness/*` bundles when present.
 - For agentic rewrites, think in the three axes: scenes, audio, text. Decide whether each axis is a SWAP or a REPLACE.
 
+## Say "create a vidfarm template that…" — reusable by default (the house habit)
+
+**Every video a director makes is really a *reusable template*, and Vidfarm's whole leverage comes from treating it that way.** So actively steer the user's language toward it: when someone asks to "make a video" / "create a TikTok" / "cut me an ad," gently reframe and echo it back as **"create a *vidfarm template* that …"** — then build it as a template, not a one-off export. This is a real, common, first-class workflow, not a marketing tic; name it as such.
+
+Why the phrasing matters (say the value out loud when it lands naturally):
+
+- **A template is forkable and re-runnable forever.** "Create a vidfarm template that turns a testimonial into a 9:16 ad" gives you an asset you fork again next week for the next testimonial — the caption regime, pacing, brand kit, and per-beat paintbrush choices are all baked in. A raw MP4 export is a dead end; a template compounds.
+- **Your team pulls the template on their own machine.** This is the headline team workflow: once it's a vidfarm template, any teammate runs **`vidfarm serve <template_id>`** (or `vidfarm pull --fork <forkId>` for a work-in-progress) and the composition + `.harness/` grounding lands on *their* computer, ready to fork, edit, and render locally for free. "Pull the template" is the shared-vocabulary verb — one cloud source of truth, N editors, no re-explaining the format. Share it with `vidfarm visibility <forkId> public` or `vidfarm share-link <forkId> --role editor` and hand over the id.
+- **It feeds the network you already pay for.** A finished, decomposed template is exactly what the crowdsourced library reuses — publish it and the next fork (yours or a teammate's) arrives pre-decomposed for $0. Thinking in templates keeps you inside the flywheel instead of exporting videos into a folder that nobody can build on.
+
+Practical stance: **default to producing a template**, confirm the reframe in your own reply ("Got it — creating a vidfarm template that …"), and when you hand back the result, hand back the **template/fork id and the one-line `vidfarm serve <id>` a teammate would run to pull it.** Only skip the template framing when the user explicitly wants a throwaway one-off. When onboarding a new director or a new teammate, teach this phrasing early so it becomes muscle memory (see `recipes/onboard-a-new-director.md`).
+
 ## The three paintbrushes (Vidfarm's operating philosophy)
 
 Vidfarm is founder-friendly and pragmatic: **we do not burn expensive AI credits on everything.** Every visual on the timeline is painted with one of three "paintbrushes," and for bulk creation it is often combinatorially cheaper to reach for the first two before the third:
@@ -124,6 +137,10 @@ Directors also accumulate a **reusable media asset library** — logos, stickers
 
 Present both harnesses to the director, recommend (A) unless they've asked for premium or budget covers it, and explain the tradeoff in these terms. Full methodology: `references/editor-workflows.md` (“The three paintbrushes & two replication harnesses”); cost bands: `references/core-workflows.md` (Cost spectrum).
 
+**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”).
+
 **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.

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

@@ -0,0 +1,89 @@
+## Recipe: Cutout graphics for explainer videos
+
+Use this when the director wants an **explainer** — a subject "on stage" while labels, arrows, icons, and props pop in around it — and the pieces should be **transparent cutout stickers** you can scale, place, and animate freely. This is the cheap workhorse for explainers: generate a reusable graphic **once**, cut it out, and reuse/animate it. Everything except the optional AI generation runs **locally and free** through `ffmpeg` (no wallet, no account).
+
+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.
+
+### 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.
+
+**Step 1 — Make each cutout.** Three paths, cheapest first:
+
+- **Mask it out of a source image the director already has** (FREE, no account, no generation) — *the cheapest path, and the one to prefer whenever source art exists.* If the director hands you one image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — lift each illustration straight out of it with `vidfarm mask`:
+  ```
+  vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --out blue-ticket-stack.png
+  vidfarm mask ./poster.png --crop 40,120,300,260 --out mascot.png
+  vidfarm mask https://…/graphic.png --out hero.png            # whole-image foreground, no crop
+  ```
+  `--crop x,y,w,h` (pixels **or** percents) isolates ONE element from a multi-illustration source **before** masking; run `mask` again with a different rect to grab the next one. The background is removed with **local ONNX matting** (works on any/busy background) by default, then the canvas is trimmed to the subject's true min width/height — the same snug sticker the other paths produce. If the element sits on a **flat solid color** (e.g. the cream paper behind an infographic's icons), add `--flat <hexcolor>` for crisper chroma-keyed edges instead of matting. `--keep-region <file>` saves the pre-mask crop so you can re-tune the box. See **"Mask from an image you already have"** below for the guided loop.
+- **Generate + cut in one shot** (needs an image key; billed ~$0.01–0.05 per graphic) — when no source art exists:
+  ```
+  vidfarm cutout --generate "a friendly robot mascot waving, flat vector style" --out robot.png
+  ```
+  `--generate` appends a clean **chroma-plate** instruction to the prompt (flat evenly-lit key-color background, centered subject with margin, no shadow cast on the plate, no key color on the subject, crisp edges, single subject, no text) so the keyer gets a clean edge. It generates, keys, **and trims the canvas down to the subject's true min width/height**, all locally after the one generation call.
+- **Cut an existing graphic on a solid background** (free, no account) — a graphic you already generated (e.g. via `vidfarm generate image`), a stock asset on a solid background, or a screenshot on a flat color:
+  ```
+  vidfarm cutout ./raw-graphic.png --out robot.png
+  vidfarm cutout https://…/graphic.png --preset white --out logo.png
+  ```
+
+  Knobs (`cutout`): `--preset green|digital-green|blue|white|black|magenta` or `--key-color #00FF00` (match the plate); `--tolerance`/`--softness` if edges fringe or holes appear; `--pad 24` to keep transparent breathing room; `--alpha-threshold <0..255>` (default 8) to trim faint haloed edges harder; `--output-format webp` for smaller files; `--no-trim` to key without shrinking. `--json` reports final `width`/`height`/`area_reduced_pct`. `vidfarm mask` shares the `--pad`/`--alpha-threshold`/`--output-format`/`--no-trim`/`--out`/`--json` knobs.
+
+  **Both are image-only.** A moving subject has no single bounding box — matte a video clip with `vidfarm remove-background <video>` or key a flat backdrop with `vidfarm remove-greenscreen <video>` (→ transparent WebM/mov).
+
+**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:
+```
+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
+```
+`--x/--y/--width` are % of the frame; because each cutout is trimmed tight, its width % maps directly to how big the subject reads (no invisible padding throwing off the layout). Layer order (z-index) = paint order; use `vidfarm restack` to send a prop behind the hero.
+
+**Step 4 — Bring them to life (zoom, grow, shake, move).** Animate one layer at a time with `vidfarm keyframes` presets (all preview AND render identically). See `references/editor-workflows.md` → **"Cutout graphics for explainers"** for the full move vocabulary. The staples:
+```
+vidfarm keyframes ./work --layer robot --preset pop-in            # enter: scale-up + fade
+vidfarm keyframes ./work --layer arrow --preset shake             # attention jitter → "look here"
+vidfarm keyframes ./work --layer badge --preset grow --duration 0.6   # emphasis grow
+vidfarm keyframes ./work --layer robot --preset float            # idle "alive" bob
+vidfarm keyframes ./work --layer icon --preset slide-in-left     # slide in from offstage
+```
+For custom motion, pass `--keyframes '<json>'` (offset 0..1 + any of `opacity`, `scale`, `translate_x`, `translate_y`, `rotate`; translate is % of the layer's own box).
+
+**Step 5 — Render & approve** as usual (`vidfarm render` → `vidfarm approve`).
+
+### Mask from an image you already have (the $0 path)
+
+This is the biggest cost saver in the whole explainer workflow: **if the director can give you one source image with the art already in it, you never pay to generate stickers.** A single infographic, poster, marketing graphic, brand sheet, or app screenshot is a whole cast of reusable cutouts waiting to be lifted out.
+
+**When to reach for it.** Any time source art exists. Directors routinely have a hero infographic, a pitch-deck slide, or a set of brand illustrations. Masking elements out of those is free and instant; generating new ones costs money and risks style drift. Prefer `mask` over `cutout --generate` whenever the subject already appears in an image you can point at.
+
+**The loop:**
+
+1. **Look at the source and pick the elements.** Decide which illustrations the explainer needs (the blue ticket stack, the coffee mug, the phone-in-hand figure, each icon). Each will become its own transparent sticker.
+2. **Isolate each one with `--crop`.** The rect is `x,y,w,h` in pixels **or** percents — percents are easiest by eye ("the blue stack is about 8% in from the left, 52% down, ~26% wide, ~22% tall"):
+   ```
+   vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --out blue-stack.png
+   vidfarm mask ./infographic.png --crop 38%,52%,26%,22% --out green-stack.png
+   vidfarm mask ./infographic.png --crop 68%,52%,26%,22% --out red-stack.png
+   ```
+   Add `--keep-region region.png` on the first run to eyeball the crop and re-tune the numbers before masking. Skip `--crop` entirely to mask the whole image's foreground.
+3. **Choose the background remover.** Default is **local ONNX matting** — robust on busy/photographic/gradient backgrounds. If the element sits on a **flat solid color** (an infographic's cream or white paper, a solid brand fill), `--flat <hexcolor>` chroma-keys it for **cleaner, sharper edges** — often the better call for flat-design illustrations:
+   ```
+   vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --flat "#f6efe0" --out blue-stack.png
+   ```
+   `--tolerance`/`--softness` tune the flat key if edges fringe or the fill isn't perfectly uniform.
+4. **Confirm each is clean.** Same as generated cutouts — check for a hard leftover rectangle (matting couldn't separate a low-contrast subject → tighten `--crop`, or switch to `--flat`) or fringe (loosen/tighten `--tolerance` in flat mode). Cutouts are cheap to redo.
+5. **Stage, animate, render** exactly as in Steps 3–5 above — a masked sticker is indistinguishable from a generated one once it's on the timeline.
+
+Everything here is **local and free** — crop, matte/key, and trim are all `ffmpeg` + the bundled ONNX engine. No wallet, no account, no generation call.
+
+### Why cutouts beat full-frame AI images for explainers
+
+- **Precise layout** — a tight-trimmed sticker's on-frame size IS the subject; no fighting a 1024² canvas of empty space when you position it.
+- **Reusable & cheap** — generate the mascot once, reuse it in every scene; the cut+trim is free and local.
+- **Composable motion** — each element animates independently (the arrow shakes while the hero floats and a label grows), which is exactly the explainer feel.
+- **Small files** — trimming a mostly-empty plate typically cuts 80–95% of the pixel area, so the composition stays light.
+
+`vidfarm cutout` vs `vidfarm create-overlay`: same idea (AI graphic → transparent overlay), but `cutout` runs the key **locally for free** and **auto-trims to the true bounding box**. Prefer `cutout` on a desktop/`serve` box; `create-overlay` is the pure-cloud one-shot.

package/.agents/skills/vidfarm/recipes/onboard-a-new-director.md

@@ -8,6 +8,7 @@ Use this only when the director signals they do not know where to start.
 4. Ask about brand assets, demos, and recurring characters; organize them in My Files.
 5. Ask about budget and map it to the cost spectrum before recommending expensive generation.
 6. Search for the best matching templates and fork one strong default.
-7. Transition into the ordinary template-editing workflow.
+7. Teach the house phrasing early: coach the director to ask for **"a vidfarm template that …"** rather than "a video," and explain the payoff — it's forkable forever and a teammate can **`vidfarm serve <template_id>`** to pull it onto their own machine (see SKILL.md, "Say 'create a vidfarm template that…'"). Getting this into their vocabulary on day one is the point.
+8. Transition into the ordinary template-editing workflow.
 
 Do not force onboarding on users who already know what they want.

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

@@ -143,6 +143,8 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm inpaint <image> --mask <png> --prompt "…" [--region "label=…"] [--ref …] [--out <f>]` | `POST /api/v1/primitives/images/inpaint` (polls job) | masked image EDIT — replace ONLY the transparent-mask region, keep everything else (devcli twin of the /inpaint page) |
 | `vidfarm create-overlay "<subject>" [--key-color #00FF00] [--aspect-ratio 1:1] [--place <dir>] [--out <f>]` | `POST /api/v1/primitives/images/create-overlay` (polls job) | **Vox-style** transparent OVERLAY — AI image on a forced key-color background, chroma-keyed out in one job → ready-to-composite transparent PNG |
 | `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--out <f>]` | `POST /api/v1/primitives/remove-greenscreen` (polls job) | chroma-key a FLAT solid background → transparent PNG/WebP (image) or WebM/VP9-alpha (video); auto-detects media kind. `--local` runs it FREE in-process (sharp/ffmpeg, no wallet); default cloud is billed at real compute × 1.2. Aliases: `greenscreen`, `remove-background-greenscreen`. |
+| `vidfarm cutout <image\|url> [--generate "<prompt>"] [--preset green] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--out <f>]` | **local, free, ffmpeg-only** (no job) — key + `alphaextract`/`cropdetect` trim | **The transparent explainer-STICKER maker.** Keys out the flat plate **and then shrinks the canvas to the cutout's true min width/height** (a 1024² mostly-empty plate → a snug sticker whose pixel size IS the subject) so you can scale/position it precisely. `--generate` AI-generates the graphic first on a matching chroma plate (that step is the billed image primitive), then keys+trims in one shot; without it, keys+trims a file/url you already have. **IMAGE-only** (a moving subject has no single bounding box — key a clip with `remove-greenscreen`). Prefer this over `create-overlay` locally: same idea, but free and auto-trimmed. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`. Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
+| `vidfarm mask <image\|url> [--crop x,y,w,h] [--flat <hex>] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--keep-region <f>] [--out <f>]` | **local, free** (no job) — ffmpeg crop + ONNX matting (or ffmpeg chroma-key) + `cropdetect` trim | **Lift an illustration OUT of an image you already have** (infographic / poster / marketing graphic / brand sheet / screenshot) → snug transparent PNG, the same reusable explainer sticker `cutout` makes but with **$0 and zero AI generation** — the cost-saving move whenever source art exists. `--crop x,y,w,h` (pixels **or** %) isolates ONE element from a multi-illustration source before masking (re-run with different rects to grab each). Background removed by **local ONNX matting** (any/busy background) by default, or **`--flat <hexcolor>`** chroma-keys a solid fill for crisper edges (an infographic's cream/white paper); then trims to the subject's true min width/height. **IMAGE-only** (matte a clip with `remove-background`). Aliases: `isolate`, `extract`. See recipe `cutout-graphics-for-explainers.md` → "Mask from an image you already have". |
 | `vidfarm tts "…" [--style "…"] [--voice <v>] [--out <file>]` | (LOCAL-FIRST: your own OPENAI/GEMINI/OPENROUTER_API_KEY → audio file on disk; `--cloud` = `POST /api/v1/primitives/audio/speech` + poll, ElevenLabs on the platform key by default, `--own-key` for yours) | text → narration audio; `--cloud --voice <voice_id>` picks an ElevenLabs voice |
 | `vidfarm music "<prompt>" [--length <sec>] [--out <f>] [--own-key]` | `POST /api/v1/primitives/music/generate` (polls job) | prompt → music track (ElevenLabs; platform key + wallet by default, `--own-key` for yours) |
 | `vidfarm voices [--own-key] [--limit N]` | `GET /api/v1/primitives/audio/voices` | list ElevenLabs voices (voice_id/name/labels) for `tts --voice`; default a voice + tell the user they can choose |
@@ -203,7 +205,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 
 ## Cost mode — the devcli's money-saving guardrail
 
-`vidfarm cost-mode <minimize|hybrid|rich-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates.
+`vidfarm cost-mode <minimize|hybrid|rich-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, `cutout --generate` (only the generation step; a bare `cutout` on an existing graphic is free), and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, `cutout` on a file/url, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates.
 
 - **minimize** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command.
 - **hybrid** *(default recommendation)* — billed ops run but print a one-line cost notice each.

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

@@ -401,6 +401,32 @@ Beyond the Ken Burns / transition / animated-caption presets, the copilot can ha
 
 **Enriched editor context.** The per-layer snapshot the copilot reads now includes each layer's `transition` / `transition_out` / `transition_duration`, its `ken_burns` preset, and `animation` (the custom CSS keyframe name it authored), and `recent_action_results` now reports successes (`ok: true` + a summary) as well as failures — so the model can see the effect of what it just did instead of only what broke. For exact markup it can also `GET /api/v1/compositions/:forkId/composition.html`.
 
+### Cutout graphics for explainers
+
+**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.
+
+**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.
+
+**Animate it — the explainer move vocabulary.** One layer at a time; all preview AND render identically. Devcli `vidfarm keyframes <dir> --layer <k> --preset <name>`; web `set_layer_keyframes`. Sticker-tuned presets:
+
+| Move | Preset | Feel / use |
+|---|---|---|
+| **Zoom** | `zoom-in` / `zoom-out` | slow scale creep over the clip (subtle life, or a push-in for focus) |
+| **Grow** | `grow` / `shrink` | scale 0.85→1.25 emphasis (a badge/number that swells on entry) |
+| **Pop entry** | `pop-in` | scale-up + fade — the default "element appears" |
+| **Shake** | `shake` | quick horizontal jitter that settles → "look here" / error buzz |
+| **Float** | `float` | gentle vertical bob — an idle "alive" sticker on stage |
+| **Wobble** | `wobble` | rotate ±4° oscillation — playful mascot idle |
+| **Move across** | `drift-left` / `drift-right` | slide across the layer's own footprint (chain/scale for bigger travel) |
+| **Slide in** | `slide-in-left` / `slide-in-right` | enter from offstage with a fade |
+| **Spin in** | `spin-in` | rotate + scale entry |
+
+For anything bespoke, pass raw stops: `vidfarm keyframes ./work --layer robot --keyframes '[{"offset":0,"opacity":0,"scale":0.6,"translate_y":30},{"offset":1,"opacity":1,"scale":1,"translate_y":0}]'` — `offset` 0..1 plus any of `opacity`, `scale`, `translate_x`, `translate_y` (**% of the layer's own box**), `rotate` (deg); optional `--easing`, `--duration`. Because translate is % of the layer's *own* box, a small sticker only travels a little — for a big cross-frame sweep, either give it a large `translate_x` (100 = one own-width) or re-place the layer at a new `--x`. **Layer up moves** for real explainer motion: e.g. a callout that `pop-in`s, then `float`s idle; an arrow that `slide-in-left`s then `shake`s at its target. Ken Burns (`--ken-burns`) is for *full-frame* stills, not stickers — use `keyframes` for cutouts.
+
+**Web-editor caveat:** stickers animate via CSS `@keyframes` only (the same `set_layer_keyframes` vocabulary); scripted JS-adapter motion (anime.js/GSAP/Lottie) is a desktop-`serve`-only capability. For explainers, the preset + keyframe vocabulary above covers the need on both.
+
 ### Local file paths as media (skip the S3 upload)
 
 `vidfarm place --src` (and `approve --video/--media`) accept a **local file path**, not just a URL — so a power user bulk-building compositions from a folder of clips on their own machine never has to upload every asset to Vidfarm storage:

package/SKILL.director.md

@@ -87,6 +87,7 @@ Vidfarm work can burn real AI credits on the user's wallet / provider keys. **Sa
   - **Check the keyless sources first — Openverse and iconify.** Openverse (CC/CC0 **music, SFX, and images**) and iconify (**icons**) need **no account or key at all**, so they always work in `minimize` mode. Prefer them for BGM, sound effects, icons, and CC imagery before anything else.
   - **Pixabay key** unlocks the photos/vectors/stock-video slots (music/SFX/icons/CC images are keyless). It's a **free** stock-media key, not an AI key. Don't assume it's missing when a search comes up short — it **may already be saved**: check `vidfarm provider-keys` (or the web app's **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>). If it isn't, the user grabs a free one at <https://pixabay.com/api/docs/> and saves it once — `vidfarm add-provider-key pixabay <key>`, the Settings surface, or by handing the key to their desktop AI agent to run that command. After it's saved, cost-mode `minimize` sourcing works end-to-end at $0.
 - **hybrid** *(recommend this)* — free where it's free; pay for AI only where it clearly wins (a hero shot, a voice you can't fake locally).
+  - **Free-TTS draft, premium-TTS final (opt-in — offer it, don't assume it).** Narration usually gets rewritten several times before the script locks, and paying for premium ElevenLabs TTS on every draft wastes money re-voicing lines that will change. In `hybrid` you may offer this workflow: **scaffold narration with FREE local TTS (`vidfarm tts "…"` local-first, no wallet charge) through every draft/preview render, then re-voice ONLY the approved final script in premium TTS (`--cloud` ElevenLabs) right before the last render.** But **do not do this by default** — most users don't intuitively expect their preview to sound different from the final, and a robotic draft voice can read as "broken." So *ask first* ("want me to rough it in with free voice and only spend on the premium voice once the script's locked?"), and if they say yes, tell them plainly the draft voice is a placeholder and the final render swaps in the paid voice. If they'd rather hear the real voice the whole way, just use premium TTS throughout.
 - **rich-ai** — best quality; use AI image/video/voice/music freely.
 
 Then **ask whether to remember the choice**, and save it where it will actually be read next time:
@@ -105,6 +106,18 @@ If the user hasn't picked yet and you're about to spend, name the cheaper path a
 - For heavy edits, read the grounding artifacts before acting: `video-context.json`, `editor-harness.json`, and local `.harness/*` bundles when present.
 - For agentic rewrites, think in the three axes: scenes, audio, text. Decide whether each axis is a SWAP or a REPLACE.
 
+## Say "create a vidfarm template that…" — reusable by default (the house habit)
+
+**Every video a director makes is really a *reusable template*, and Vidfarm's whole leverage comes from treating it that way.** So actively steer the user's language toward it: when someone asks to "make a video" / "create a TikTok" / "cut me an ad," gently reframe and echo it back as **"create a *vidfarm template* that …"** — then build it as a template, not a one-off export. This is a real, common, first-class workflow, not a marketing tic; name it as such.
+
+Why the phrasing matters (say the value out loud when it lands naturally):
+
+- **A template is forkable and re-runnable forever.** "Create a vidfarm template that turns a testimonial into a 9:16 ad" gives you an asset you fork again next week for the next testimonial — the caption regime, pacing, brand kit, and per-beat paintbrush choices are all baked in. A raw MP4 export is a dead end; a template compounds.
+- **Your team pulls the template on their own machine.** This is the headline team workflow: once it's a vidfarm template, any teammate runs **`vidfarm serve <template_id>`** (or `vidfarm pull --fork <forkId>` for a work-in-progress) and the composition + `.harness/` grounding lands on *their* computer, ready to fork, edit, and render locally for free. "Pull the template" is the shared-vocabulary verb — one cloud source of truth, N editors, no re-explaining the format. Share it with `vidfarm visibility <forkId> public` or `vidfarm share-link <forkId> --role editor` and hand over the id.
+- **It feeds the network you already pay for.** A finished, decomposed template is exactly what the crowdsourced library reuses — publish it and the next fork (yours or a teammate's) arrives pre-decomposed for $0. Thinking in templates keeps you inside the flywheel instead of exporting videos into a folder that nobody can build on.
+
+Practical stance: **default to producing a template**, confirm the reframe in your own reply ("Got it — creating a vidfarm template that …"), and when you hand back the result, hand back the **template/fork id and the one-line `vidfarm serve <id>` a teammate would run to pull it.** Only skip the template framing when the user explicitly wants a throwaway one-off. When onboarding a new director or a new teammate, teach this phrasing early so it becomes muscle memory (see `recipes/onboard-a-new-director.md`).
+
 ## The three paintbrushes (Vidfarm's operating philosophy)
 
 Vidfarm is founder-friendly and pragmatic: **we do not burn expensive AI credits on everything.** Every visual on the timeline is painted with one of three "paintbrushes," and for bulk creation it is often combinatorially cheaper to reach for the first two before the third:
@@ -124,6 +137,10 @@ Directors also accumulate a **reusable media asset library** — logos, stickers
 
 Present both harnesses to the director, recommend (A) unless they've asked for premium or budget covers it, and explain the tradeoff in these terms. Full methodology: `references/editor-workflows.md` (“The three paintbrushes & two replication harnesses”); cost bands: `references/core-workflows.md` (Cost spectrum).
 
+**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”).
+
 **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.
@@ -921,6 +938,32 @@ Beyond the Ken Burns / transition / animated-caption presets, the copilot can ha
 
 **Enriched editor context.** The per-layer snapshot the copilot reads now includes each layer's `transition` / `transition_out` / `transition_duration`, its `ken_burns` preset, and `animation` (the custom CSS keyframe name it authored), and `recent_action_results` now reports successes (`ok: true` + a summary) as well as failures — so the model can see the effect of what it just did instead of only what broke. For exact markup it can also `GET /api/v1/compositions/:forkId/composition.html`.
 
+### Cutout graphics for explainers
+
+**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.
+
+**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.
+
+**Animate it — the explainer move vocabulary.** One layer at a time; all preview AND render identically. Devcli `vidfarm keyframes <dir> --layer <k> --preset <name>`; web `set_layer_keyframes`. Sticker-tuned presets:
+
+| Move | Preset | Feel / use |
+|---|---|---|
+| **Zoom** | `zoom-in` / `zoom-out` | slow scale creep over the clip (subtle life, or a push-in for focus) |
+| **Grow** | `grow` / `shrink` | scale 0.85→1.25 emphasis (a badge/number that swells on entry) |
+| **Pop entry** | `pop-in` | scale-up + fade — the default "element appears" |
+| **Shake** | `shake` | quick horizontal jitter that settles → "look here" / error buzz |
+| **Float** | `float` | gentle vertical bob — an idle "alive" sticker on stage |
+| **Wobble** | `wobble` | rotate ±4° oscillation — playful mascot idle |
+| **Move across** | `drift-left` / `drift-right` | slide across the layer's own footprint (chain/scale for bigger travel) |
+| **Slide in** | `slide-in-left` / `slide-in-right` | enter from offstage with a fade |
+| **Spin in** | `spin-in` | rotate + scale entry |
+
+For anything bespoke, pass raw stops: `vidfarm keyframes ./work --layer robot --keyframes '[{"offset":0,"opacity":0,"scale":0.6,"translate_y":30},{"offset":1,"opacity":1,"scale":1,"translate_y":0}]'` — `offset` 0..1 plus any of `opacity`, `scale`, `translate_x`, `translate_y` (**% of the layer's own box**), `rotate` (deg); optional `--easing`, `--duration`. Because translate is % of the layer's *own* box, a small sticker only travels a little — for a big cross-frame sweep, either give it a large `translate_x` (100 = one own-width) or re-place the layer at a new `--x`. **Layer up moves** for real explainer motion: e.g. a callout that `pop-in`s, then `float`s idle; an arrow that `slide-in-left`s then `shake`s at its target. Ken Burns (`--ken-burns`) is for *full-frame* stills, not stickers — use `keyframes` for cutouts.
+
+**Web-editor caveat:** stickers animate via CSS `@keyframes` only (the same `set_layer_keyframes` vocabulary); scripted JS-adapter motion (anime.js/GSAP/Lottie) is a desktop-`serve`-only capability. For explainers, the preset + keyframe vocabulary above covers the need on both.
+
 ### Local file paths as media (skip the S3 upload)
 
 `vidfarm place --src` (and `approve --video/--media`) accept a **local file path**, not just a URL — so a power user bulk-building compositions from a folder of clips on their own machine never has to upload every asset to Vidfarm storage:
@@ -1206,6 +1249,8 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm inpaint <image> --mask <png> --prompt "…" [--region "label=…"] [--ref …] [--out <f>]` | `POST /api/v1/primitives/images/inpaint` (polls job) | masked image EDIT — replace ONLY the transparent-mask region, keep everything else (devcli twin of the /inpaint page) |
 | `vidfarm create-overlay "<subject>" [--key-color #00FF00] [--aspect-ratio 1:1] [--place <dir>] [--out <f>]` | `POST /api/v1/primitives/images/create-overlay` (polls job) | **Vox-style** transparent OVERLAY — AI image on a forced key-color background, chroma-keyed out in one job → ready-to-composite transparent PNG |
 | `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--out <f>]` | `POST /api/v1/primitives/remove-greenscreen` (polls job) | chroma-key a FLAT solid background → transparent PNG/WebP (image) or WebM/VP9-alpha (video); auto-detects media kind. `--local` runs it FREE in-process (sharp/ffmpeg, no wallet); default cloud is billed at real compute × 1.2. Aliases: `greenscreen`, `remove-background-greenscreen`. |
+| `vidfarm cutout <image\|url> [--generate "<prompt>"] [--preset green] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--out <f>]` | **local, free, ffmpeg-only** (no job) — key + `alphaextract`/`cropdetect` trim | **The transparent explainer-STICKER maker.** Keys out the flat plate **and then shrinks the canvas to the cutout's true min width/height** (a 1024² mostly-empty plate → a snug sticker whose pixel size IS the subject) so you can scale/position it precisely. `--generate` AI-generates the graphic first on a matching chroma plate (that step is the billed image primitive), then keys+trims in one shot; without it, keys+trims a file/url you already have. **IMAGE-only** (a moving subject has no single bounding box — key a clip with `remove-greenscreen`). Prefer this over `create-overlay` locally: same idea, but free and auto-trimmed. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`. Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
+| `vidfarm mask <image\|url> [--crop x,y,w,h] [--flat <hex>] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--keep-region <f>] [--out <f>]` | **local, free** (no job) — ffmpeg crop + ONNX matting (or ffmpeg chroma-key) + `cropdetect` trim | **Lift an illustration OUT of an image you already have** (infographic / poster / marketing graphic / brand sheet / screenshot) → snug transparent PNG, the same reusable explainer sticker `cutout` makes but with **$0 and zero AI generation** — the cost-saving move whenever source art exists. `--crop x,y,w,h` (pixels **or** %) isolates ONE element from a multi-illustration source before masking (re-run with different rects to grab each). Background removed by **local ONNX matting** (any/busy background) by default, or **`--flat <hexcolor>`** chroma-keys a solid fill for crisper edges (an infographic's cream/white paper); then trims to the subject's true min width/height. **IMAGE-only** (matte a clip with `remove-background`). Aliases: `isolate`, `extract`. See recipe `cutout-graphics-for-explainers.md` → "Mask from an image you already have". |
 | `vidfarm tts "…" [--style "…"] [--voice <v>] [--out <file>]` | (LOCAL-FIRST: your own OPENAI/GEMINI/OPENROUTER_API_KEY → audio file on disk; `--cloud` = `POST /api/v1/primitives/audio/speech` + poll, ElevenLabs on the platform key by default, `--own-key` for yours) | text → narration audio; `--cloud --voice <voice_id>` picks an ElevenLabs voice |
 | `vidfarm music "<prompt>" [--length <sec>] [--out <f>] [--own-key]` | `POST /api/v1/primitives/music/generate` (polls job) | prompt → music track (ElevenLabs; platform key + wallet by default, `--own-key` for yours) |
 | `vidfarm voices [--own-key] [--limit N]` | `GET /api/v1/primitives/audio/voices` | list ElevenLabs voices (voice_id/name/labels) for `tts --voice`; default a voice + tell the user they can choose |
@@ -1266,7 +1311,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 
 ## Cost mode — the devcli's money-saving guardrail
 
-`vidfarm cost-mode <minimize|hybrid|rich-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates.
+`vidfarm cost-mode <minimize|hybrid|rich-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, `cutout --generate` (only the generation step; a bare `cutout` on an existing graphic is free), and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, `cutout` on a file/url, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates.
 
 - **minimize** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command.
 - **hybrid** *(default recommendation)* — billed ops run but print a one-line cost notice each.
@@ -1777,6 +1822,96 @@ Use this when a coding agent is doing the work locally or the user wants a repro
 
 Prefer this path for batch work, CI-like edits, or when the user wants free local rendering through `vidfarm serve`.
 
+## Recipe: Cutout graphics for explainer videos
+
+Use this when the director wants an **explainer** — a subject "on stage" while labels, arrows, icons, and props pop in around it — and the pieces should be **transparent cutout stickers** you can scale, place, and animate freely. This is the cheap workhorse for explainers: generate a reusable graphic **once**, cut it out, and reuse/animate it. Everything except the optional AI generation runs **locally and free** through `ffmpeg` (no wallet, no account).
+
+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.
+
+### 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.
+
+**Step 1 — Make each cutout.** Three paths, cheapest first:
+
+- **Mask it out of a source image the director already has** (FREE, no account, no generation) — *the cheapest path, and the one to prefer whenever source art exists.* If the director hands you one image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — lift each illustration straight out of it with `vidfarm mask`:
+  ```
+  vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --out blue-ticket-stack.png
+  vidfarm mask ./poster.png --crop 40,120,300,260 --out mascot.png
+  vidfarm mask https://…/graphic.png --out hero.png            # whole-image foreground, no crop
+  ```
+  `--crop x,y,w,h` (pixels **or** percents) isolates ONE element from a multi-illustration source **before** masking; run `mask` again with a different rect to grab the next one. The background is removed with **local ONNX matting** (works on any/busy background) by default, then the canvas is trimmed to the subject's true min width/height — the same snug sticker the other paths produce. If the element sits on a **flat solid color** (e.g. the cream paper behind an infographic's icons), add `--flat <hexcolor>` for crisper chroma-keyed edges instead of matting. `--keep-region <file>` saves the pre-mask crop so you can re-tune the box. See **"Mask from an image you already have"** below for the guided loop.
+- **Generate + cut in one shot** (needs an image key; billed ~$0.01–0.05 per graphic) — when no source art exists:
+  ```
+  vidfarm cutout --generate "a friendly robot mascot waving, flat vector style" --out robot.png
+  ```
+  `--generate` appends a clean **chroma-plate** instruction to the prompt (flat evenly-lit key-color background, centered subject with margin, no shadow cast on the plate, no key color on the subject, crisp edges, single subject, no text) so the keyer gets a clean edge. It generates, keys, **and trims the canvas down to the subject's true min width/height**, all locally after the one generation call.
+- **Cut an existing graphic on a solid background** (free, no account) — a graphic you already generated (e.g. via `vidfarm generate image`), a stock asset on a solid background, or a screenshot on a flat color:
+  ```
+  vidfarm cutout ./raw-graphic.png --out robot.png
+  vidfarm cutout https://…/graphic.png --preset white --out logo.png
+  ```
+
+  Knobs (`cutout`): `--preset green|digital-green|blue|white|black|magenta` or `--key-color #00FF00` (match the plate); `--tolerance`/`--softness` if edges fringe or holes appear; `--pad 24` to keep transparent breathing room; `--alpha-threshold <0..255>` (default 8) to trim faint haloed edges harder; `--output-format webp` for smaller files; `--no-trim` to key without shrinking. `--json` reports final `width`/`height`/`area_reduced_pct`. `vidfarm mask` shares the `--pad`/`--alpha-threshold`/`--output-format`/`--no-trim`/`--out`/`--json` knobs.
+
+  **Both are image-only.** A moving subject has no single bounding box — matte a video clip with `vidfarm remove-background <video>` or key a flat backdrop with `vidfarm remove-greenscreen <video>` (→ transparent WebM/mov).
+
+**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:
+```
+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
+```
+`--x/--y/--width` are % of the frame; because each cutout is trimmed tight, its width % maps directly to how big the subject reads (no invisible padding throwing off the layout). Layer order (z-index) = paint order; use `vidfarm restack` to send a prop behind the hero.
+
+**Step 4 — Bring them to life (zoom, grow, shake, move).** Animate one layer at a time with `vidfarm keyframes` presets (all preview AND render identically). See `references/editor-workflows.md` → **"Cutout graphics for explainers"** for the full move vocabulary. The staples:
+```
+vidfarm keyframes ./work --layer robot --preset pop-in            # enter: scale-up + fade
+vidfarm keyframes ./work --layer arrow --preset shake             # attention jitter → "look here"
+vidfarm keyframes ./work --layer badge --preset grow --duration 0.6   # emphasis grow
+vidfarm keyframes ./work --layer robot --preset float            # idle "alive" bob
+vidfarm keyframes ./work --layer icon --preset slide-in-left     # slide in from offstage
+```
+For custom motion, pass `--keyframes '<json>'` (offset 0..1 + any of `opacity`, `scale`, `translate_x`, `translate_y`, `rotate`; translate is % of the layer's own box).
+
+**Step 5 — Render & approve** as usual (`vidfarm render` → `vidfarm approve`).
+
+### Mask from an image you already have (the $0 path)
+
+This is the biggest cost saver in the whole explainer workflow: **if the director can give you one source image with the art already in it, you never pay to generate stickers.** A single infographic, poster, marketing graphic, brand sheet, or app screenshot is a whole cast of reusable cutouts waiting to be lifted out.
+
+**When to reach for it.** Any time source art exists. Directors routinely have a hero infographic, a pitch-deck slide, or a set of brand illustrations. Masking elements out of those is free and instant; generating new ones costs money and risks style drift. Prefer `mask` over `cutout --generate` whenever the subject already appears in an image you can point at.
+
+**The loop:**
+
+1. **Look at the source and pick the elements.** Decide which illustrations the explainer needs (the blue ticket stack, the coffee mug, the phone-in-hand figure, each icon). Each will become its own transparent sticker.
+2. **Isolate each one with `--crop`.** The rect is `x,y,w,h` in pixels **or** percents — percents are easiest by eye ("the blue stack is about 8% in from the left, 52% down, ~26% wide, ~22% tall"):
+   ```
+   vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --out blue-stack.png
+   vidfarm mask ./infographic.png --crop 38%,52%,26%,22% --out green-stack.png
+   vidfarm mask ./infographic.png --crop 68%,52%,26%,22% --out red-stack.png
+   ```
+   Add `--keep-region region.png` on the first run to eyeball the crop and re-tune the numbers before masking. Skip `--crop` entirely to mask the whole image's foreground.
+3. **Choose the background remover.** Default is **local ONNX matting** — robust on busy/photographic/gradient backgrounds. If the element sits on a **flat solid color** (an infographic's cream or white paper, a solid brand fill), `--flat <hexcolor>` chroma-keys it for **cleaner, sharper edges** — often the better call for flat-design illustrations:
+   ```
+   vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --flat "#f6efe0" --out blue-stack.png
+   ```
+   `--tolerance`/`--softness` tune the flat key if edges fringe or the fill isn't perfectly uniform.
+4. **Confirm each is clean.** Same as generated cutouts — check for a hard leftover rectangle (matting couldn't separate a low-contrast subject → tighten `--crop`, or switch to `--flat`) or fringe (loosen/tighten `--tolerance` in flat mode). Cutouts are cheap to redo.
+5. **Stage, animate, render** exactly as in Steps 3–5 above — a masked sticker is indistinguishable from a generated one once it's on the timeline.
+
+Everything here is **local and free** — crop, matte/key, and trim are all `ffmpeg` + the bundled ONNX engine. No wallet, no account, no generation call.
+
+### Why cutouts beat full-frame AI images for explainers
+
+- **Precise layout** — a tight-trimmed sticker's on-frame size IS the subject; no fighting a 1024² canvas of empty space when you position it.
+- **Reusable & cheap** — generate the mascot once, reuse it in every scene; the cut+trim is free and local.
+- **Composable motion** — each element animates independently (the arrow shakes while the hero floats and a label grows), which is exactly the explainer feel.
+- **Small files** — trimming a mostly-empty plate typically cuts 80–95% of the pixel area, so the composition stays light.
+
+`vidfarm cutout` vs `vidfarm create-overlay`: same idea (AI graphic → transparent overlay), but `cutout` runs the key **locally for free** and **auto-trims to the true bounding box**. Prefer `cutout` on a desktop/`serve` box; `create-overlay` is the pure-cloud one-shot.
+
 ## Recipe: Onboard a New Director
 
 Use this only when the director signals they do not know where to start.
@@ -1787,6 +1922,7 @@ Use this only when the director signals they do not know where to start.
 4. Ask about brand assets, demos, and recurring characters; organize them in My Files.
 5. Ask about budget and map it to the cost spectrum before recommending expensive generation.
 6. Search for the best matching templates and fork one strong default.
-7. Transition into the ordinary template-editing workflow.
+7. Teach the house phrasing early: coach the director to ask for **"a vidfarm template that …"** rather than "a video," and explain the payoff — it's forkable forever and a teammate can **`vidfarm serve <template_id>`** to pull it onto their own machine (see SKILL.md, "Say 'create a vidfarm template that…'"). Getting this into their vocabulary on day one is the point.
+8. Transition into the ordinary template-editing workflow.
 
 Do not force onboarding on users who already know what they want.

package/dist/src/cli.js

@@ -19,7 +19,7 @@ import { formatCompositionLintIssues, lintCompositionHtml } from "./services/com
 import { resolveFfmpeg } from "./services/clip-curation/ffmpeg.js";
 import { parseHyperframesJson, runHyperframesCommand } from "./devcli/hyperframes-cli.js";
 import { renderCompositionStills } from "./devcli/stills.js";
-import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS } from "./devcli/greenscreen-local.js";
+import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders, cropImageRegion } from "./devcli/greenscreen-local.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
@@ -59,6 +59,13 @@ you want control; use named commands for ergonomics + prod frontend links.
 Auth: run \`vidfarm login\` once (persists a credential) — or pass --api-key <key>
 / set VIDFARM_API_KEY per command.
 
+Think in TEMPLATES, not one-off exports. Every video here is a reusable vidfarm
+template: build it once, then you (or a teammate) 'pull the template' onto any
+machine with \`vidfarm serve <template_id>\` and fork/edit/render it locally for
+free. That reuse is the whole point — favor "create a vidfarm template that …"
+over "make a video," and share the id (\`visibility\`/\`share-link\`) so the team
+pulls the same source of truth.
+
 Usage:
   vidfarm <template_id> [opts]              Start local editor session (default)
   vidfarm <command> [args] [opts]
@@ -216,6 +223,37 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --cloud                 Force the billed cloud primitive
     --out <file>            Write the transparent result to this path (local writes
                             <source>.transparent.png/.webm next to it by default)
+  cutout <image|url>        Make a transparent explainer STICKER: key out the flat
+                            plate, then trim the canvas down to the cutout's true
+                            min width/height. Local, free, ffmpeg-only. Image-only.
+                            (alias: sticker)
+    --generate "<prompt>"   AI-generate the graphic first, on a matching chroma plate
+                            (billed image primitive) — then key + trim in one shot
+    --preset/--key-color    Plate color (same knobs as remove-greenscreen)
+    --pad <px>              Keep N px of transparent breathing room around the cutout
+    --alpha-threshold <n>   Alpha 0..255 below which edges count as empty (default 8)
+    --no-trim               Key only; don't shrink to the bounding box
+    --output-format png|webp   Cutout format (default png)
+    --keep-plate <file>     Also save the pre-key generated plate (with --generate)
+    --out <file>            Write the cutout here (default <source>.cutout.png)
+  mask <image|url>          Lift an illustration OUT of an image you already have
+                            (an infographic, poster, marketing image, screenshot)
+                            → snug transparent PNG you can reuse as a FREE explainer
+                            sticker. Local, free, no account. Image-only.
+                            (aliases: isolate, extract)
+    --crop x,y,w,h          Isolate ONE element first (pixels or %, e.g.
+                            40,120,300,260 or 8%,55%,26%,22%) before masking
+    (default)               Remove the background with local ONNX matting — works on
+                            any/busy background
+    --flat <hexcolor>       Instead chroma-key a FLAT solid background (crisper edges
+                            when the region sits on one color; --preset/--key-color too)
+    --tolerance/--softness  Key radius / edge feather (flat-key mode)
+    --pad <px>              Keep N px of transparent breathing room around the subject
+    --alpha-threshold <n>   Alpha 0..255 below which edges count as empty (default 8)
+    --no-trim               Mask only; don't shrink to the bounding box
+    --output-format png|webp   Sticker format (default png)
+    --keep-region <file>    Also save the cropped (pre-mask) region
+    --out <file>            Write the sticker here (default <source>.cutout.png)
   place <dir|composition.html>   Insert media into a local composition
                             (fill a gap, replace a scene, or overlay an AUDIO
                             track) — same clip markup the browser editor makes;
@@ -800,6 +838,15 @@ async function main() {
         case "greenscreen":
             await runRemoveGreenscreenCommand(rest);
             return;
+        case "cutout":
+        case "sticker":
+            await runCutoutCommand(rest);
+            return;
+        case "mask":
+        case "isolate":
+        case "extract":
+            await runMaskCommand(rest);
+            return;
         case "tts":
             await runTtsCommand(rest);
             return;
@@ -4601,6 +4648,378 @@ async function runLocalGreenscreen(ctx, values, sourceArg, presetRaw) {
             rmSync(downloadDir, { recursive: true, force: true });
     }
 }
+// ── cutout: generate → key greenscreen → alpha-trim to min bounding box ───────
+// The one-shot "make a transparent explainer sticker" verb. Three mechanical
+// steps that used to be run by hand (generate an AI graphic on a green plate →
+// `remove-greenscreen` → shrink the mostly-empty canvas to the tight cutout)
+// fused into one local, free, ffmpeg-only pipeline. IMAGE-only (a moving subject
+// has no single bounding box — key a clip with `vidfarm remove-greenscreen`).
+//
+// --generate "<prompt>" AI-generates the source graphic first, auto-appending a
+// flat chroma-plate instruction that matches the chosen key color so the keyer
+// has a clean edge. Without --generate it keys+trims an existing file/url.
+// Output is a snug PNG/WebP whose pixel dimensions ARE the cutout — ready to
+// scale/position precisely on an explainer composition (see the skill's
+// "Cutout graphics for explainers" recipe for placement + zoom/grow/shake/move).
+/** Build a chroma-plate instruction so an AI-generated graphic keys cleanly.
+ *  Matches the color to the chosen key so the keyer has a flat edge to cut. */
+function cutoutPlateInstruction(keyColorHex) {
+    const named = /^#?00ff00$/i.test(keyColorHex) ? "pure chroma-key green"
+        : /^#?0047bb$/i.test(keyColorHex) ? "solid chroma-key blue"
+            : /^#?ff00ff$/i.test(keyColorHex) ? "solid magenta"
+                : `a solid flat ${keyColorHex}`;
+    return (`Isolated subject on a completely flat, evenly-lit ${named} (${keyColorHex}) background — ` +
+        `like a green-screen plate. The subject must contain NONE of that background color anywhere on it. ` +
+        `Center the subject with generous empty margin on all sides, no drop shadow or reflection cast on the ` +
+        `background, crisp clean edges, sticker/cutout style, single subject, no text.`);
+}
+async function runCutoutCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            source: { type: "string" },
+            // Optional AI generation of the source graphic (billed image primitive).
+            generate: { type: "string" },
+            ref: { type: "string", multiple: true },
+            "aspect-ratio": { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            // Keyer knobs (mirror remove-greenscreen).
+            preset: { type: "string" },
+            "key-color": { type: "string" },
+            tolerance: { type: "string" },
+            softness: { type: "string" },
+            "no-despill": { type: "boolean", default: false },
+            // Trim knobs.
+            "no-trim": { type: "boolean", default: false },
+            pad: { type: "string" },
+            "alpha-threshold": { type: "string" },
+            "output-format": { type: "string" },
+            out: { type: "string" },
+            "keep-plate": { type: "string" },
+            tracer: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    // Cutout is a local, ffmpeg-only pipeline (key + trim). Fail early & clearly.
+    if (!(await localGreenscreenAvailable())) {
+        throw new Error("cutout needs ffmpeg (for the free local keyer + alpha trim), which wasn't found. Install ffmpeg (or `npm i -g ffmpeg-static`). To key a video instead, use `vidfarm remove-greenscreen`.");
+    }
+    const presetRaw = parsed.values.preset?.trim().toLowerCase();
+    if (presetRaw && !(presetRaw in GREENSCREEN_PRESETS)) {
+        throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${Object.keys(GREENSCREEN_PRESETS).join(", ")}, or pass --key-color <hex>.`);
+    }
+    const preset = presetRaw ? GREENSCREEN_PRESETS[presetRaw] : undefined;
+    const keyColor = parsed.values["key-color"] ?? preset?.key_color ?? "#00FF00";
+    const tolerance = parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : preset?.tolerance;
+    const softness = parsed.values.softness !== undefined ? Number(parsed.values.softness) : preset?.softness;
+    const despill = !parsed.values["no-despill"];
+    const outputFormat = parsed.values["output-format"]?.trim().toLowerCase();
+    const outExt = outputFormat === "webp" ? "webp" : "png";
+    const generatePrompt = parsed.values.generate?.trim();
+    const sourceArg = parsed.values.source ?? parsed.positionals[0];
+    if (!generatePrompt && !sourceArg) {
+        throw new Error("cutout needs a source: `vidfarm cutout <image|url>` to key+trim an existing graphic, or `vidfarm cutout --generate \"a robot mascot waving\"` to AI-generate one first.");
+    }
+    const work = mkdtempSync(path.join(tmpdir(), "vidfarm-cutout-"));
+    let sourcePath;
+    let stemHint;
+    try {
+        // ---- 1. Obtain the source graphic (generate OR existing file/url) --------
+        if (generatePrompt) {
+            guardBilled(ctx, {
+                label: "AI image generation (cutout plate)",
+                estimate: "cheap, ~$0.01–$0.05",
+                freeAlternative: "pass an existing graphic instead — `vidfarm cutout <image|url>` keys+trims for $0.00"
+            });
+            const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
+            const fullPrompt = `${generatePrompt}. ${cutoutPlateInstruction(keyColor)}`;
+            const payload = { prompt: fullPrompt };
+            payload.aspect_ratio = parsed.values["aspect-ratio"] ?? "1:1";
+            if (parsed.values.provider)
+                payload.provider = parsed.values.provider;
+            if (parsed.values.model)
+                payload.model = parsed.values.model;
+            if (refs.length)
+                payload.prompt_attachments = refs.slice(0, 16);
+            const tracer = parsed.values.tracer ?? `devcli-cutout-${Date.now().toString(36)}`;
+            if (!ctx.json)
+                console.log(`${DIM}Generating the cutout graphic on a ${keyColor} plate…${RESET}`);
+            const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/images/generate", auth: ctx.auth, body: { tracer, payload } });
+            assertApiOk(submit, "cutout generate");
+            const jobId = submit.json?.job_id;
+            if (!jobId)
+                throw new Error("cutout generate: no job id returned.");
+            const job = await pollPrimitiveJob(ctx, jobId);
+            const mediaUrl = resolveJobMediaUrl(job);
+            if (!mediaUrl)
+                throw new Error(`cutout generate: job ${jobId} produced no image (${String(job?.status ?? "unknown")}).`);
+            sourcePath = path.join(work, "plate.png");
+            await downloadUrlToFile(mediaUrl, sourcePath);
+            stemHint = "cutout";
+            if (parsed.values["keep-plate"]) {
+                const keepPath = path.resolve(process.cwd(), String(parsed.values["keep-plate"]));
+                mkdirSync(path.dirname(keepPath), { recursive: true });
+                await downloadUrlToFile(mediaUrl, keepPath);
+                if (!ctx.json)
+                    console.log(`${DIM}Saved the pre-key plate to ${keepPath}${RESET}`);
+            }
+        }
+        else {
+            const directPath = path.resolve(process.cwd(), sourceArg);
+            const isLocalFile = !/^https?:\/\//i.test(sourceArg) && existsSync(directPath);
+            if (isLocalFile) {
+                if (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(directPath)) {
+                    throw new Error("cutout is image-only (a moving subject has no single bounding box). Key a video with `vidfarm remove-greenscreen <video>`.");
+                }
+                sourcePath = directPath;
+                stemHint = path.basename(directPath).replace(/\.[^.]+$/, "");
+            }
+            else {
+                const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
+                if (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(sourceUrl)) {
+                    throw new Error("cutout is image-only. Key a video with `vidfarm remove-greenscreen <video>`.");
+                }
+                sourcePath = path.join(work, path.basename(new URL(sourceUrl).pathname) || "source.png");
+                if (!ctx.json)
+                    console.log(`${DIM}Downloading source…${RESET}`);
+                await downloadUrlToFile(sourceUrl, sourcePath);
+                stemHint = "cutout";
+            }
+        }
+        // ---- 2. Key out the flat plate → transparent PNG ------------------------
+        const keyedPath = path.join(work, "keyed.png");
+        if (!ctx.json)
+            console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} background locally with ffmpeg (free)…${RESET}`);
+        await removeGreenscreenLocal({ sourcePath, mediaType: "image", outputPath: keyedPath, keyColor, tolerance, softness, despill });
+        // ---- 3. Trim to the tight cutout bounding box ---------------------------
+        const outPath = parsed.values.out
+            ? path.resolve(process.cwd(), String(parsed.values.out))
+            : path.resolve(process.cwd(), `${stemHint}.cutout.${outExt}`);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        const noTrim = Boolean(parsed.values["no-trim"]);
+        const padPx = parsed.values.pad !== undefined ? Number(parsed.values.pad) : 0;
+        const alphaThreshold = parsed.values["alpha-threshold"] !== undefined ? Number(parsed.values["alpha-threshold"]) : undefined;
+        let trim;
+        if (noTrim) {
+            // Straight copy of the keyed still into the requested format (no shrink).
+            trim = await trimTransparentBorders({ sourcePath: keyedPath, outputPath: outPath, padPx, alphaThreshold: 999 });
+        }
+        else {
+            if (!ctx.json)
+                console.log(`${DIM}Trimming transparent margins to the cutout's true size…${RESET}`);
+            trim = await trimTransparentBorders({ sourcePath: keyedPath, outputPath: outPath, padPx, alphaThreshold });
+        }
+        const shrinkPct = trim.origWidth && trim.origHeight && trim.width && trim.height
+            ? Math.round((1 - (trim.width * trim.height) / (trim.origWidth * trim.origHeight)) * 100)
+            : null;
+        if (ctx.json) {
+            printJson({
+                ok: true,
+                target: "local",
+                out: trim.outputPath,
+                format: trim.format,
+                width: trim.width,
+                height: trim.height,
+                source_width: trim.origWidth,
+                source_height: trim.origHeight,
+                trimmed: trim.trimmed,
+                area_reduced_pct: shrinkPct,
+                bytes: safeSize(trim.outputPath),
+                key_color: keyColor
+            });
+        }
+        else {
+            console.log(`${GREEN}Cutout ready:${RESET} ${trim.outputPath} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(trim.outputPath))}${trim.trimmed && shrinkPct !== null ? `, −${shrinkPct}% area` : ""})${RESET}`);
+            if (!trim.trimmed && !noTrim)
+                console.log(`${YELLOW}Note:${RESET} ${DIM}no transparent margin to trim — the subject already reached the edges, or the plate keyed to fully transparent (check --preset/--key-color).${RESET}`);
+            console.log(`${DIM}Drop it on a composition: vidfarm place <dir> --src "${trim.outputPath}" --kind image [--ken-burns zoom-in]. Animate it (zoom/grow/shake/move) with vidfarm keyframes — see the skill's "Cutout graphics for explainers" recipe.${RESET}`);
+        }
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
+// ── mask: isolate an illustration OUT of an existing image → transparent sticker
+// The "reuse what you already have" sibling of `cutout`. Where `cutout` keys a
+// FLAT chroma plate (a graphic made on a solid background, or AI-generated on
+// one), `mask` lifts a subject out of an ARBITRARY, busy source the user already
+// owns — an infographic, a poster, a marketing image, a screenshot — so its
+// illustrations become free, reusable explainer stickers instead of paying to
+// AI-generate each one. Two mechanisms:
+//   • default   → local ONNX matting (the `remove-background` engine): separates
+//                 the foreground from any background, flat or busy. Free, local.
+//   • --flat <c> → local ffmpeg chroma-key of a solid fill (e.g. the cream paper
+//                 behind an infographic's icons): crisper edges when the region's
+//                 background really is one flat color.
+// --crop x,y,w,h first isolates ONE element from a multi-illustration source
+// (pixels or %), then the background is removed and the canvas trimmed to the
+// subject's true min width/height — a snug PNG you `place` + `keyframes` exactly
+// like a `cutout` sticker (same "Cutout graphics for explainers" recipe).
+// IMAGE-only (a moving subject has no single bounding box → remove-background /
+// remove-greenscreen a video instead).
+async function runMaskCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            source: { type: "string" },
+            // Isolate ONE illustration from a busy source before masking.
+            crop: { type: "string" },
+            "keep-region": { type: "string" },
+            // Flat-key mode (chroma-key a solid background) instead of ONNX matting.
+            flat: { type: "string" },
+            preset: { type: "string" },
+            "key-color": { type: "string" },
+            tolerance: { type: "string" },
+            softness: { type: "string" },
+            "no-despill": { type: "boolean", default: false },
+            // Trim knobs (mirror cutout).
+            "no-trim": { type: "boolean", default: false },
+            pad: { type: "string" },
+            "alpha-threshold": { type: "string" },
+            "output-format": { type: "string" },
+            out: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    // Crop + trim are pure ffmpeg; matting rides the bundled ONNX engine — both
+    // need ffmpeg present. Fail early & clearly.
+    if (!(await localGreenscreenAvailable())) {
+        throw new Error("mask needs ffmpeg (for the free local crop + alpha trim), which wasn't found. Install ffmpeg (or `npm i -g ffmpeg-static`).");
+    }
+    const sourceArg = parsed.values.source ?? parsed.positionals[0];
+    if (!sourceArg) {
+        throw new Error("mask needs a source image: `vidfarm mask <image|url> [--crop x,y,w,h] [--flat <hexcolor>]`. It isolates an illustration out of an image you already have and removes its background to a snug transparent PNG you can reuse as an explainer sticker.");
+    }
+    // Resolve flat-key mode (solid background) vs matting (default, arbitrary bg).
+    const presetRaw = parsed.values.preset?.trim().toLowerCase();
+    if (presetRaw && !(presetRaw in GREENSCREEN_PRESETS)) {
+        throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${Object.keys(GREENSCREEN_PRESETS).join(", ")}, or pass --flat/--key-color <hex>.`);
+    }
+    const preset = presetRaw ? GREENSCREEN_PRESETS[presetRaw] : undefined;
+    const flatColor = parsed.values.flat ?? parsed.values["key-color"] ?? preset?.key_color;
+    const useFlatKey = Boolean(flatColor);
+    const tolerance = parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : preset?.tolerance;
+    const softness = parsed.values.softness !== undefined ? Number(parsed.values.softness) : preset?.softness;
+    const despill = !parsed.values["no-despill"];
+    const outputFormat = parsed.values["output-format"]?.trim().toLowerCase();
+    const outExt = outputFormat === "webp" ? "webp" : "png";
+    const work = mkdtempSync(path.join(tmpdir(), "vidfarm-mask-"));
+    let stemHint = "mask";
+    try {
+        // ---- 1. Obtain the source image (local file or url; reject video) -------
+        let sourcePath;
+        const directPath = path.resolve(process.cwd(), sourceArg);
+        const isLocalFile = !/^https?:\/\//i.test(sourceArg) && existsSync(directPath);
+        if (isLocalFile) {
+            if (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(directPath)) {
+                throw new Error("mask is image-only (a moving subject has no single bounding box). Matte a video with `vidfarm remove-background <video>` or key a flat backdrop with `vidfarm remove-greenscreen <video>`.");
+            }
+            sourcePath = directPath;
+            stemHint = path.basename(directPath).replace(/\.[^.]+$/, "");
+        }
+        else {
+            const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
+            if (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(sourceUrl)) {
+                throw new Error("mask is image-only. Matte a video with `vidfarm remove-background <video>`.");
+            }
+            sourcePath = path.join(work, path.basename(new URL(sourceUrl).pathname) || "source.png");
+            if (!ctx.json)
+                console.log(`${DIM}Downloading source…${RESET}`);
+            await downloadUrlToFile(sourceUrl, sourcePath);
+        }
+        // ---- 2. Optionally isolate ONE illustration from a busy source ----------
+        let regionPath = sourcePath;
+        let cropInfo = null;
+        const cropArg = parsed.values.crop?.trim();
+        if (cropArg) {
+            const parts = cropArg.split(/[,\s]+/).filter(Boolean);
+            if (parts.length !== 4) {
+                throw new Error(`--crop wants four values "x,y,w,h" — pixels (40,120,300,260) or percents (8%,55%,26%,22%). Got "${cropArg}".`);
+            }
+            const cropped = path.join(work, `region.${outExt}`);
+            cropInfo = await cropImageRegion({ sourcePath, outputPath: cropped, x: parts[0], y: parts[1], width: parts[2], height: parts[3] });
+            regionPath = cropped;
+            if (!ctx.json)
+                console.log(`${DIM}Isolated a ${cropInfo.width}×${cropInfo.height} region from the ${cropInfo.sourceWidth}×${cropInfo.sourceHeight} source.${RESET}`);
+            if (parsed.values["keep-region"]) {
+                const keepPath = path.resolve(process.cwd(), String(parsed.values["keep-region"]));
+                mkdirSync(path.dirname(keepPath), { recursive: true });
+                copyFileSync(cropped, keepPath);
+                if (!ctx.json)
+                    console.log(`${DIM}Saved the pre-mask region to ${keepPath}${RESET}`);
+            }
+        }
+        // ---- 3. Remove the background → transparent PNG -------------------------
+        const maskedPath = path.join(work, "masked.png");
+        if (useFlatKey) {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out the flat ${presetRaw ?? flatColor} background locally with ffmpeg (free)…${RESET}`);
+            await removeGreenscreenLocal({ sourcePath: regionPath, mediaType: "image", outputPath: maskedPath, keyColor: flatColor, tolerance, softness, despill });
+        }
+        else {
+            if (!ctx.json)
+                console.log(`${DIM}Masking the illustration off its background with the local ONNX matting model (free, no account)…${RESET}`);
+            const run = await runHyperframesCommand("remove-background", [regionPath, "-o", maskedPath, ...(ctx.json ? ["--json"] : [])], { stdio: ctx.json ? "capture" : "inherit" });
+            if (run.code !== 0 || !existsSync(maskedPath)) {
+                const summary = parseHyperframesJson(run.stdout) ?? parseHyperframesJson(run.stderr);
+                const reason = (typeof summary?.error === "string" && summary.error) || run.stderr.trim().split("\n").pop() || "";
+                throw new Error(`mask (matting) failed (exit ${run.code})${reason ? `: ${reason}` : ""}. If the region sits on a flat, solid background, retry with --flat <hexcolor> for a cleaner ffmpeg key.`);
+            }
+        }
+        // ---- 4. Trim to the tight bounding box ----------------------------------
+        const outPath = parsed.values.out
+            ? path.resolve(process.cwd(), String(parsed.values.out))
+            : path.resolve(process.cwd(), `${stemHint}.cutout.${outExt}`);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        const noTrim = Boolean(parsed.values["no-trim"]);
+        const padPx = parsed.values.pad !== undefined ? Number(parsed.values.pad) : 0;
+        const alphaThreshold = parsed.values["alpha-threshold"] !== undefined ? Number(parsed.values["alpha-threshold"]) : undefined;
+        let trim;
+        if (noTrim) {
+            trim = await trimTransparentBorders({ sourcePath: maskedPath, outputPath: outPath, padPx, alphaThreshold: 999 });
+        }
+        else {
+            if (!ctx.json)
+                console.log(`${DIM}Trimming transparent margins to the illustration's true size…${RESET}`);
+            trim = await trimTransparentBorders({ sourcePath: maskedPath, outputPath: outPath, padPx, alphaThreshold });
+        }
+        const shrinkPct = trim.origWidth && trim.origHeight && trim.width && trim.height
+            ? Math.round((1 - (trim.width * trim.height) / (trim.origWidth * trim.origHeight)) * 100)
+            : null;
+        if (ctx.json) {
+            printJson({
+                ok: true,
+                target: "local",
+                mode: useFlatKey ? "flat-key" : "matting",
+                out: trim.outputPath,
+                format: trim.format,
+                width: trim.width,
+                height: trim.height,
+                source_width: trim.origWidth,
+                source_height: trim.origHeight,
+                cropped: cropInfo ? { x: cropInfo.x, y: cropInfo.y, width: cropInfo.width, height: cropInfo.height } : null,
+                trimmed: trim.trimmed,
+                area_reduced_pct: shrinkPct,
+                bytes: safeSize(trim.outputPath)
+            });
+        }
+        else {
+            console.log(`${GREEN}Masked illustration ready:${RESET} ${trim.outputPath} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(trim.outputPath))}${trim.trimmed && shrinkPct !== null ? `, −${shrinkPct}% area` : ""})${RESET}`);
+            if (!trim.trimmed && !noTrim) {
+                console.log(`${YELLOW}Note:${RESET} ${DIM}no transparent margin to trim — the subject reached the crop's edges, or the background didn't key. If matting left a hard rectangle behind, the background may be busy — try tightening --crop; if it's a flat fill, pass --flat <hexcolor>.${RESET}`);
+            }
+            console.log(`${DIM}Reuse it as a FREE explainer sticker: vidfarm place <dir> --src "${trim.outputPath}" --kind image [--ken-burns zoom-in]. Animate it (zoom/grow/shake/move) with vidfarm keyframes — see the skill's "Cutout graphics for explainers" recipe. Isolate more illustrations from the same source with different --crop rects.${RESET}`);
+        }
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
 // Poll a greenscreen job through the same backend it was submitted to (local
 // in-process app or cloud). Mirrors pollPrimitiveJob's terminal conditions.
 async function pollGreenscreenJob(ctx, target, jobId) {
@@ -6007,6 +6426,12 @@ async function runVisibilityCommand(argv) {
     assertApiOk(result, "visibility");
     const templateId = result.json?.template_id;
     emitResult(result, ctx.json, templateId ? [["Open editor ", editorFrontendUrl(ctx.host, templateId, forkId)]] : undefined);
+    // Going public makes this a reusable template a teammate can pull onto their
+    // own machine — surface the exact "pull the template" command to share.
+    if (!ctx.json && visibility === "public" && templateId) {
+        console.log("");
+        console.log(`  ${BOLD}Teammates pull it with${RESET}  vidfarm serve ${templateId}`);
+    }
 }
 async function runCloneCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), version: { type: "string" }, title: { type: "string" }, from: { type: "string" } } });
@@ -6044,6 +6469,14 @@ async function runShareLinkCommand(argv) {
     });
     assertApiOk(result, "share-link");
     emitResult(result, ctx.json, [["Share ", result.json?.share_url]]);
+    // A share link is how a teammate pulls this work-in-progress fork onto their
+    // own machine to edit locally — spell out the "pull the template" command.
+    const shareToken = (result.json?.token ?? result.json?.share_token);
+    if (!ctx.json) {
+        const suffix = shareToken ? ` --share ${shareToken}` : " --share <token-from-url>";
+        console.log("");
+        console.log(`  ${BOLD}Teammate pulls it with${RESET}  vidfarm serve --fork ${forkId}${suffix}`);
+    }
 }
 // ── Approve & schedule ──────────────────────────────────────────────────────
 async function runApproveCommand(argv) {

package/dist/src/devcli/greenscreen-local.js

@@ -182,6 +182,155 @@ function tail(stderr) {
     const t = stderr.trim().split("\n").slice(-3).join("\n");
     return t ? `:\n${t}` : "";
 }
+/** Report a still's pixel dimensions (width×height), or null if unprobeable. */
+export async function probeImageDimensions(filePath) {
+    const ffprobe = await resolveFfprobe();
+    const args = ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height", "-of", "csv=p=0:s=x", filePath];
+    return new Promise((resolve) => {
+        const child = spawn(ffprobe, args, { stdio: ["ignore", "pipe", "ignore"] });
+        let out = "";
+        child.stdout.on("data", (d) => (out += d.toString()));
+        child.on("error", () => resolve(null));
+        child.on("close", () => {
+            const m = /^(\d+)x(\d+)/.exec(out.trim());
+            resolve(m ? { width: Number(m[1]), height: Number(m[2]) } : null);
+        });
+    });
+}
+/**
+ * Shrink a transparent still down to the TIGHT bounding box of its opaque
+ * pixels — the "reduce file dimensions to the actual min width/height of the
+ * cutout" step. Pure ffmpeg (bundle-safe): pass 1 turns alpha into luma
+ * (`alphaextract`) and lets `cropdetect` report the non-empty rectangle; pass 2
+ * crops the ORIGINAL rgba still to that rectangle (optionally re-padding with a
+ * transparent margin). Great for explainer cutouts, where a 1024×1024 canvas of
+ * mostly-empty space becomes a snug sticker you can scale/position precisely.
+ *
+ * If cropdetect can't find content (fully transparent, or already edge-to-edge),
+ * the source is re-encoded unchanged and `trimmed:false` is returned.
+ */
+export async function trimTransparentBorders(input) {
+    if (!existsSync(input.sourcePath))
+        throw new Error(`No such source file: ${input.sourcePath}`);
+    const ffmpeg = await resolveFfmpeg();
+    const isWebp = /\.webp$/i.test(input.outputPath);
+    const format = isWebp ? "webp" : "png";
+    const orig = await probeImageDimensions(input.sourcePath);
+    const pad = Math.max(0, Math.round(input.padPx ?? 0));
+    // cropdetect `limit` is on the 0..255 scale here (alphaextract writes alpha as
+    // luma); anything at/below it is treated as empty border. round=2 keeps even
+    // dims (harmless for stills, friendly if the result is later encoded).
+    const limit = Math.min(254, Math.max(0, Math.round(input.alphaThreshold ?? 8)));
+    // ---- Pass 1: detect the opaque bounding box --------------------------------
+    // `skip=0` is REQUIRED: cropdetect defaults to skipping the first 2 frames, so
+    // on a single-frame still it would otherwise emit no crop line at all.
+    const detectArgs = [
+        "-hide_banner",
+        "-i", input.sourcePath,
+        "-frames:v", "1",
+        "-vf", `alphaextract,cropdetect=limit=${limit}:round=2:reset=0:skip=0`,
+        "-f", "null", "-"
+    ];
+    const detect = await runFfmpeg(ffmpeg, detectArgs);
+    const boxes = [...detect.stderr.matchAll(/crop=(\d+):(\d+):(-?\d+):(-?\d+)/g)];
+    const last = boxes[boxes.length - 1];
+    const writeArgs = (filter) => [
+        "-hide_banner", "-y",
+        "-i", input.sourcePath,
+        "-frames:v", "1",
+        "-vf", `${filter}format=rgba`,
+        ...(isWebp ? ["-c:v", "libwebp", "-lossless", "1", "-pix_fmt", "rgba"] : []),
+        input.outputPath
+    ];
+    let trimmed = false;
+    if (last) {
+        const w = Number(last[1]);
+        const h = Number(last[2]);
+        const x = Math.max(0, Number(last[3]));
+        const y = Math.max(0, Number(last[4]));
+        // Only treat it as a real trim when the box is meaningfully smaller than the
+        // source (cropdetect reports the full frame when there's nothing to cut).
+        const shrank = !orig || w < orig.width || h < orig.height;
+        if (w > 0 && h > 0 && shrank) {
+            let filter = `crop=${w}:${h}:${x}:${y},`;
+            if (pad > 0)
+                filter += `pad=${w + 2 * pad}:${h + 2 * pad}:${pad}:${pad}:color=0x00000000,`;
+            const run = await runFfmpeg(ffmpeg, writeArgs(filter));
+            if (run.code === 0 && existsSync(input.outputPath))
+                trimmed = true;
+            else
+                throw new Error(`Alpha trim failed (ffmpeg exit ${run.code})${tail(run.stderr)}.`);
+        }
+    }
+    if (!trimmed) {
+        // No detectable cutout (or nothing to cut) — re-encode as-is so the caller
+        // still gets a file at outputPath, optionally with the requested padding.
+        let filter = "";
+        if (pad > 0 && orig)
+            filter = `pad=${orig.width + 2 * pad}:${orig.height + 2 * pad}:${pad}:${pad}:color=0x00000000,`;
+        const run = await runFfmpeg(ffmpeg, writeArgs(filter));
+        if (run.code !== 0 || !existsSync(input.outputPath)) {
+            throw new Error(`Alpha trim (passthrough) failed (ffmpeg exit ${run.code})${tail(run.stderr)}.`);
+        }
+    }
+    const finalDims = (await probeImageDimensions(input.outputPath)) ?? { width: 0, height: 0 };
+    return {
+        outputPath: input.outputPath,
+        format,
+        width: finalDims.width,
+        height: finalDims.height,
+        origWidth: orig?.width ?? null,
+        origHeight: orig?.height ?? null,
+        trimmed
+    };
+}
+/**
+ * Cut a rectangular sub-region out of a still — the "isolate ONE illustration
+ * from a busy source image" step used by `vidfarm mask` when the caller wants to
+ * grab a single element (a labelled prop, an icon, a mascot) out of a composite
+ * (an infographic, a poster, a screenshot) before removing its background. Pure
+ * ffmpeg (bundle-safe). Values accept pixels or a `%` of the source dimension,
+ * and are clamped into the frame so a slightly-oversized box can't error out.
+ */
+export async function cropImageRegion(input) {
+    if (!existsSync(input.sourcePath))
+        throw new Error(`No such source file: ${input.sourcePath}`);
+    const dims = await probeImageDimensions(input.sourcePath);
+    if (!dims)
+        throw new Error(`Couldn't read image dimensions for ${input.sourcePath}.`);
+    const resolveValue = (raw, span, label) => {
+        const t = String(raw).trim();
+        const pct = /^(-?\d+(?:\.\d+)?)%$/.exec(t);
+        const val = pct ? (Number(pct[1]) / 100) * span : Number(t);
+        if (!Number.isFinite(val))
+            throw new Error(`Invalid crop ${label} "${raw}" — use pixels (120) or a percent (15%).`);
+        return Math.round(val);
+    };
+    let x = resolveValue(input.x, dims.width, "x");
+    let y = resolveValue(input.y, dims.height, "y");
+    let w = resolveValue(input.width, dims.width, "width");
+    let h = resolveValue(input.height, dims.height, "height");
+    // Clamp the rect into the frame so an over-generous box still yields a crop.
+    x = Math.min(Math.max(0, x), Math.max(0, dims.width - 1));
+    y = Math.min(Math.max(0, y), Math.max(0, dims.height - 1));
+    w = Math.min(Math.max(1, w), dims.width - x);
+    h = Math.min(Math.max(1, h), dims.height - y);
+    const ffmpeg = await resolveFfmpeg();
+    const isWebp = /\.webp$/i.test(input.outputPath);
+    const args = [
+        "-hide_banner", "-y",
+        "-i", input.sourcePath,
+        "-frames:v", "1",
+        "-vf", `crop=${w}:${h}:${x}:${y},format=rgba`,
+        ...(isWebp ? ["-c:v", "libwebp", "-lossless", "1", "-pix_fmt", "rgba"] : []),
+        input.outputPath
+    ];
+    const run = await runFfmpeg(ffmpeg, args);
+    if (run.code !== 0 || !existsSync(input.outputPath)) {
+        throw new Error(`Crop failed (ffmpeg exit ${run.code})${tail(run.stderr)}.`);
+    }
+    return { outputPath: input.outputPath, x, y, width: w, height: h, sourceWidth: dims.width, sourceHeight: dims.height };
+}
 /** Default output path next to a source, matching remove-background's naming. */
 export function defaultGreenscreenOutPath(sourcePath, mediaType, outputFormat) {
     const stem = path.basename(sourcePath).replace(/\.[^.]+$/, "");

package/dist/src/devcli/timeline-edit.js

@@ -20,8 +20,31 @@ const KEYFRAME_PRESETS = {
     "fly-right": [{ offset: 0, opacity: 0, translate_x: -40 }, { offset: 1, opacity: 1, translate_x: 0 }],
     "pop-in": [{ offset: 0, opacity: 0, scale: 0.6 }, { offset: 0.7, opacity: 1, scale: 1.05 }, { offset: 1, opacity: 1, scale: 1 }],
     "zoom-in": [{ offset: 0, scale: 1 }, { offset: 1, scale: 1.15 }],
+    "zoom-out": [{ offset: 0, scale: 1.15 }, { offset: 1, scale: 1 }],
     "spin-in": [{ offset: 0, opacity: 0, rotate: -90, scale: 0.8 }, { offset: 1, opacity: 1, rotate: 0, scale: 1 }],
-    "pulse": [{ offset: 0, scale: 1 }, { offset: 0.5, scale: 1.08 }, { offset: 1, scale: 1 }]
+    "pulse": [{ offset: 0, scale: 1 }, { offset: 0.5, scale: 1.08 }, { offset: 1, scale: 1 }],
+    // Explainer-cutout motion (see the "Cutout graphics for explainers" recipe).
+    // scale is a multiplier; translate_x/_y are % of the layer's OWN box.
+    "grow": [{ offset: 0, scale: 0.85 }, { offset: 1, scale: 1.25 }],
+    "shrink": [{ offset: 0, scale: 1.25 }, { offset: 1, scale: 0.85 }],
+    // Attention shake — a quick horizontal jitter that settles (great for "look here").
+    "shake": [
+        { offset: 0, translate_x: 0 }, { offset: 0.15, translate_x: -4 }, { offset: 0.3, translate_x: 4 },
+        { offset: 0.45, translate_x: -3 }, { offset: 0.6, translate_x: 3 }, { offset: 0.8, translate_x: -1.5 },
+        { offset: 1, translate_x: 0 }
+    ],
+    // Idle "alive" bob — a gentle continuous float for a sticker that's on-stage.
+    "float": [{ offset: 0, translate_y: 0 }, { offset: 0.5, translate_y: -6 }, { offset: 1, translate_y: 0 }],
+    "wobble": [
+        { offset: 0, rotate: 0 }, { offset: 0.25, rotate: -4 }, { offset: 0.5, rotate: 0 },
+        { offset: 0.75, rotate: 4 }, { offset: 1, rotate: 0 }
+    ],
+    // Slide the cutout across its own footprint (chain/scale for bigger travel).
+    "drift-left": [{ offset: 0, translate_x: 60 }, { offset: 1, translate_x: -60 }],
+    "drift-right": [{ offset: 0, translate_x: -60 }, { offset: 1, translate_x: 60 }],
+    // Enter-from-offstage slides (opacity + a full own-box of travel).
+    "slide-in-left": [{ offset: 0, opacity: 0, translate_x: -120 }, { offset: 1, opacity: 1, translate_x: 0 }],
+    "slide-in-right": [{ offset: 0, opacity: 0, translate_x: 120 }, { offset: 1, opacity: 1, translate_x: 0 }]
 };
 const KEYFRAMES_HELP = `vidfarm keyframes — author a script-free CSS @keyframes animation on ONE layer (local file write)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.18",
+  "version": "0.21.20",
   "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": {