@officexapp/vidfarm-devcli 0.21.35 → 0.21.36

package/.agents/skills/editor-capabilities/SKILL.md

@@ -84,7 +84,7 @@ Every video you touch has four charges in series, and **you write them before yo
 1. 🪝 **Hook** — the opening line, as text, on screen at `start:0`. A **complete clause** (subject + verb), no jargon, naming a **situation** ("I've quit six businesses") not a label ("anonymity"). Caption chunk 1 is read before any audio — muted autoplay is the default viewing condition, so the text hook outworks the spoken one. Banned openings: throat-clearing, a logo, a title card, a fade from black, context before the claim.
 2. 🔄 **Loop** — one open question by 0:10, stated **on screen**, closing **inside this video** (name the timestamp; if you can't, there's no loop). The withheld answer must be one the viewer **can't supply themselves** — a loop whose answer they can guess passes every mechanical check and dies in the field.
 3. 😍 **Payoff** — shown, not summarized, landing before the final beat. The payoff is not the CTA.
-4. 🎣 **Bait** — one ask, final beat, and tell the user to put it in the post caption too. Never a DM funnel, "follow for part two", or ragebait.
+4. 🎣 **Bait** — one ask, final beat, and tell the user to put it in the post caption too. A keyword comment ask ("comment CLIPPER and I'll send the breakdown") is standard and allowed. Never "follow for part two", ragebait, or an earnings/health claim traded for the reply.
 
 **On a re-theme this is the thing you protect.** `editor_context` → `viral_dna.hook` / `retention` / `payoff` / `emotional_punch` tells you what the source's charges were — that structure is *why the template worked*. Rebuild each charge for the new subject; flattening the loop into a product statement is the most common way a re-theme kills a format.
 

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

@@ -209,13 +209,17 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 **Explainer/cutout videos — the transparent-sticker workflow.** For explainers (a subject "on stage" while labels, arrows, and props pop in around it), the cheap workhorse is a **transparent cutout sticker**: `vidfarm cutout --generate "<subject>"` AI-generates the graphic on a chroma plate, keys it out, **and trims the canvas down to the subject's true min width/height** — one free local ffmpeg step, no mostly-empty PNG to fight with — then `vidfarm place` + `vidfarm keyframes` scale/position and animate it (zoom, grow, shake, drift). It's the same "generate a reusable element once, then reuse it" thrift as the cheap harness, tuned for stickers. Full guided harness: recipe `recipes/cutout-graphics-for-explainers.md`; placement + zoom/grow/shake/move motion recipes: `references/editor-workflows.md` (“Cutout graphics for explainers”).
 
-**"Make me a sticker pack" = ONE greenscreen sheet of many items, then masked apart — and `vidfarm sticker-pack` is that whole loop.** A sticker pack is never one graphic; it's a *set* (props, icons, reactions, characters, backdrops) that must share one art style. Generating them one at a time is both expensive (N image jobs) and inconsistent (N independent styles), so the move is the opposite: **generate a single image holding every item, laid out on a flat greenscreen plate, then cut each item out locally for $0.** `vidfarm sticker-pack --generate "<theme>" --items "a,b,c"` does all of it — one billed image job for the whole set, then a free local key, an **automatic** alpha-segmentation that finds each item (no hand-measured `--crop` rects), a per-item trim to its true bounding box, and a `stickers.json` manifest. Already have a greenscreen sheet? `vidfarm sticker-pack ./sheet.png` cuts it up for **$0**. Use `--dry-run` to eyeball the detected boxes first; `--gap` merges/splits items that came out joined or broken; `vidfarm mask <sheet> --crop …` is the manual fallback for one stubborn item.
+**"Make me a sticker pack" = ONE greenscreen sheet of many items, then masked apart — and `vidfarm sticker-pack` is that whole loop.** A sticker pack is never one graphic; it's a *set* (props, icons, reactions, characters, backdrops) that must share one art style. Generating them one at a time is both expensive (N image jobs) and inconsistent (N independent styles), so the move is the opposite: **generate a single image holding every item, laid out on a flat greenscreen plate, then cut each item out locally for $0.** `vidfarm sticker-pack --generate "<theme>" --items "a,b,c"` does all of it — one billed image job for the whole set, then a free local key, an **automatic** alpha-segmentation that finds each item (no hand-measured `--crop` rects), a per-item trim to its true bounding box, and a `stickers.json` manifest. The sheet comes in two shapes: **zoned** (a grid of color panels, one plate color per item — the default for 2+ named items, and what frees the art from a single banned hue) and **flat** (the classic one-color plate, for a model that can't follow a color-block grid). Already have a greenscreen sheet? `vidfarm sticker-pack ./sheet.png` cuts it up for **$0**. Use `--dry-run` to eyeball the detected boxes first; `--gap` merges/splits items that came out joined or broken; `vidfarm mask <sheet> --crop …` is the manual fallback for one stubborn item.
 
 - **Stickers are not necessarily small.** A sticker is *any* transparent element you place and animate — an icon, a mascot, a prop, a character, and equally **a full-width landscape, skyline, or backdrop** that fills the frame. `sticker-pack` filters speckle only; it has no maximum item size. Ask for the big pieces in the same sheet as the small ones.
 - **Stickers are usually animated, not pasted.** Once placed, animate each one with `vidfarm keyframes` presets (`pop-in`, `float`, `shake`, `grow`, `slide-in-left`, `drift`) — that's HTML/CSS canvas motion, deterministic, free, and identical in preview and render. Layer moves up (pop-in, then idle float) for real life. See `references/editor-workflows.md` → "Cutout graphics for explainers".
 - **A sticker can carry its OWN motion too.** A *moving* subject has no single bounding box, so it isn't a PNG: key the clip with `vidfarm remove-greenscreen <video>` → transparent WebM (browser/editor-playable, the right choice on a composition).
-- **The plate must be a color the ART DOESN'T USE — green is a default, not a law.** A chroma key removes exactly ONE color, so a green plate under green artwork (leaves, frogs, plants, money, an "eco" icon set) keys holes straight through the stickers. `sticker-pack`/`cutout` handle this for you in two ways, and you should still say it out loud when it matters: **(a)** when generating, they read the subject and move the plate off any hue it mentions — green → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — and print which plate they picked and why; **(b)** when splitting a sheet you already have, they **detect the plate from the sheet's four corners**, so a red/purple/blue sheet handed back from a web generator just works. Pin it yourself with `--key-color "#FF00FF"` / `--preset magenta` (that disables the auto-pick), or `--no-auto-key` to force plain green. If a pack's palette collides with *every* standard plate, split it into two sheets on two different plates rather than fighting the key.
-- **The ART must be CLOSED and SOLIDLY FILLED — this is the other half of surviving the key, and the #1 way stickers come back broken.** Ask an image model for "icons on a green plate" and it will happily draw **outline art**: a colored stroke with the shape's interior left as bare plate. It looks perfect on the sheet, and after the key each sticker is a **rim floating around a see-through hole** (an apple-shaped outline with nothing inside it). Same outcome from a *near-plate* fill (the keyer works on tolerance, not exact match), a translucent/glassy/glowing material, or a soft glow fading into the plate. **You cannot key those pixels back — it has to be in the prompt:** *"every object is a closed, solidly filled shape; outlines must enclose an opaque fill of a different color; no outline-only or hollow art; nothing on the art in the plate color or any near-shade of it; fully opaque, no translucency, glow or drop shadow."* `cutout --generate`, `sticker-pack --generate`, `handoff image` and the `create-overlay` primitive **append that clause for you** with the chosen plate hex — write it yourself only when you prompt a generator directly. After the key, both commands report per-item `hole_pct`/`hollow` (console `⚠ N% hollow`, `--json`, `stickers.json`) — a ring or picture frame reads the same way, so it **warns, never blocks**. Flagged and it shouldn't be? Re-generate with the fill clause; a *near*-plate fill can sometimes be rescued with a lower `--tolerance`; one stubborn item can be lifted with `vidfarm mask --crop …` (ONNX matting ignores fill color).
+- **The key is CONNECTIVITY-based, so "the art can't use the plate color" is no longer true — only its OUTER EDGE can't.** `sticker-pack`/`cutout` (and `remove-greenscreen <image> --smart`) don't delete every pixel that looks like the plate. They flood-fill the plate **inward from the edge of the sheet** and delete only background that **reaches** that edge. A green leaf inside a mascot, a plate-colored eye, an outline shape whose interior was left as bare plate — none of it is reachable, so none of it is deleted. Edges are feathered and the plate is **un-mixed out of each edge pixel individually** (real alpha math, not a global `despill`), which is what kills the green fringe a flat key leaves. What still matters: the item's **silhouette** must be a different color from its own plate, and nothing may **fade** into the plate (no soft glow, blur or drop shadow on the background). Say the win out loud when it matters — the console prints *"kept N plate-colored pixels INSIDE the art that a flat key would have punched out."* `--key-mode flat` restores the old plain-chromakey behaviour (the cloud path's exact filter chain — use it to reproduce a cloud render, or as a simple fallback).
+- **Plate color is still chosen for you, and it still matters for the silhouette.** When generating, `sticker-pack`/`cutout` read the subject and move the plate off any hue it mentions — green → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — printing which plate they picked and why. When splitting a sheet you already have, they **read the plate off the sheet itself**, so a red/purple/blue sheet from a web generator just works. Pin it with `--key-color "#FF00FF"` / `--preset magenta`, or `--no-auto-key` for plain green.
+- **ONE PLATE COLOR PER STICKER — `--sheet-mode zoned`.** The real fix for "our art has to be simple because of the greenscreen" is to stop giving a whole sheet one background. A **zoned** sheet is a grid of solid color **panels**, one item per panel, each panel's plate chosen against **that item**: a green frog on magenta beside a pink flower on green, in one image job. Each panel is keyed independently with its own color (read back off that panel's own corners, because models drift the hue they were asked for), and item art may then use **any palette at all — including the color of a different panel**. Bonus: names stop being guessed from reading order — panel N holds the item you asked for in panel N, so `--items` maps exactly, and `stickers.json` records each sticker's `panel` and `plate`. `--sheet-mode auto` (the default) zones a generation of 2+ named items and stays flat otherwise. Reading a zoned sheet you already have: `--zones auto` (default — recovers the grid from the sheet's own edges) or `--zones 3x2`.
+- **The FLAT single-color sheet is still first-class — use it for a weaker image model.** Not every model can hold a color-block grid; a cheap or small one will paint one background regardless of the prompt. That path is fully supported: `--sheet-mode flat` asks for the classic one-plate sheet, and even if you asked for zones, keying **detects a model that ignored the grid** (a panel with no plate to remove, or one whose item filled it corner to corner) and **automatically re-keys the sheet as one plate**, telling you it did. So zoning can't strand you — worst case you're back on the simple method, still for $0.
+- **Painterly, soft, furry or glassy art → `--refine`.** Chroma keying of any kind needs a crisp silhouette. When the art has genuinely soft edges (watercolor, fur, glow, glass, a cast shadow), add `--refine`: after the keyer locates each item, that item is re-cut from the **un-keyed** sheet with the local ONNX matting model (free, ~1–2s each), which is color-blind and handles soft mattes. It sanity-checks each matte and falls back to the keyed cut per item if the model didn't find a subject — flat vector art is exactly the case where matting fails and the chroma cut is better, so don't reach for `--refine` by default.
+- **What the ART still has to honor: a crisp silhouette, sealed shapes, and gaps between items.** The connectivity key removes the old bans on hollow art and plate-colored fills, but three prompt rules are still load-bearing: **(1)** every object's **outer edge** is a clearly different color from its own plate and is **crisp** — no glow, blur, mist or drop shadow fading into the background; **(2)** enclosed areas are **sealed by the artwork**, because a gap in an outline lets the background flow in and the fill really does get keyed; **(3)** items are separated by a clear margin of plate — two touching items segment as ONE sticker. `cutout --generate`, `sticker-pack --generate`, `handoff image` and the `create-overlay` primitive **append the right clause for you** (a relaxed one for the smart keyer, the strict "closed, solidly filled, nothing in a near-plate shade" one when `--key-mode flat` is in play) — write it yourself only when prompting a generator directly. Both commands still report per-item `hole_pct`/`hollow` (console `⚠ N% hollow`, `--json`, `stickers.json`); under the smart keyer a flagged item is *usually real* (a ring, frame, donut, or pieces with background between them), so it **warns, never blocks**. One stubborn item can always be lifted with `vidfarm mask --crop …` (ONNX matting ignores color entirely).
 - **Transparent GIF is supported, for GIF-only surfaces.** `vidfarm sticker-pack … --output-format gif` (stills) and `vidfarm remove-greenscreen <video> --gif` (animated) emit transparent GIFs. GIF alpha is **1-bit**, so edges go hard — fine for chat/forum/Notion sticker surfaces, worse than PNG/WebP/WebM for compositing on a timeline. Prefer PNG/WebP/WebM unless the destination only eats GIF.
 
 **Explainer house style — the defaults to build with unless told otherwise.** **White background / light mode** (plain white stage, no gradients, no dark mode, no photo backdrop), **kinetic word-by-word captions** in dark ink on the light stage (`vidfarm captions generate --style word-pop --color "#111111" --active-color "#7C3AED" --background-style plain` — skip outlines/shadows, they're only needed over busy footage), and **female TTS narration** (`vidfarm tts --voice coral` on OpenAI — `nova` for energy, `sage` for calm; `Kore`/`Leda` on Gemini; any ElevenLabs voice via `vidfarm voices`). **Keep it clean and simple** — one idea on screen at a time, two or three cutouts per beat, one accent color, one font, lots of white space; remove before you add. **Illustrations default to simplicity**: flat vector, simple shapes, minimal detail, 2–3 flat colors, no baked-in text — simple art keys cleanly, trims tight, and stays on-style across the whole cast. State the defaults once so the director can override any of them. Full detail: recipe `recipes/cutout-graphics-for-explainers.md` (“House style — the explainer defaults”). **If the director takes the stage off white**, two things stop being optional: every sticker's **white die-cut rim** has to be stripped (on a dark stage it's a glaring halo and the most obvious bot-made artefact in the frame — recipe → “Stickers on a DARK or photographic stage”), and the caption hexes above stop applying — **caption colour, active-word colour and plate are chosen by measuring the composited background behind the caption band**, one treatment per video (`harnesses/short-form.HARNESS.md` → “Caption styling is MEASURED off the background”). Related: **on-screen text and captions must not say the same thing at once** — display text carries the argument, captions carry only what the screen doesn't show.

package/.agents/skills/vidfarm/harnesses/short-form.HARNESS.md

@@ -87,9 +87,9 @@ The moment the video pays what the hook promised, landing on **what they actuall
 
 A video with replies gets shown again; a video with none dies at its first audience regardless of watch time. **Bait is a deliberate beat, not something you hope for.** One ask, in the final beat, **and in the post caption** (many people reply from the caption without finishing).
 
-Works: the confession invite ("tell me which one you already quit") · the guess ("guess how long it took, I say it at the end" — pairs perfectly with a withheld-number loop) · the named omission ("I left one thing out on purpose, ask me") · the soft disagree (a true concession people want to argue with) · a specific question, never "thoughts?".
+Works: the confession invite ("tell me which one you already quit") · the guess ("guess how long it took, I say it at the end" — pairs perfectly with a withheld-number loop) · the named omission ("I left one thing out on purpose, ask me") · the soft disagree (a true concession people want to argue with) · a specific question, never "thoughts?" · the keyword comment ("comment CLIPPER and I'll send the breakdown") — standard and allowed; keep the keyword topical and actually hand over what you promised.
 
-Doesn't: ragebait or a deliberate error to farm corrections (works once, costs the positioning permanently) · "follow for part two" (breaks Rule 1) · DM funnels · anything that makes bait the price of the payoff. **Pay off first, then ask.**
+Doesn't: ragebait or a deliberate error to farm corrections (works once, costs the positioning permanently) · "follow for part two" (breaks Rule 1) · an earnings/health claim attached to the ask ("comment MONEY and I'll show you how to make $10k/mo" — the keyword is fine, the claim isn't) · anything that makes bait the price of the payoff. **Pay off first, then ask.**
 
 ### 📝 Captions — the delivery system for three of the four charges
 
@@ -180,7 +180,7 @@ Verbatim captions in the font regime and the safe zone · frame 0 works as hook
 - [ ] 🔄 The loop closes in this video, and the payoff is the thing that was promised
 - [ ] 😍 The payoff is shown, not summarized, and lands before the final beat
 - [ ] 🎣 One bait ask, in the final beat and in the post caption
-- [ ] 🎣 The bait is not ragebait, a DM funnel, or a follow-for-part-two
+- [ ] 🎣 The bait is not ragebait, a follow-for-part-two, or an earnings/health claim traded for the reply (a keyword comment ask is fine)
 
 **Standalone**
 - [ ] A stranger seeing only this video understands what it's about

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

@@ -56,28 +56,58 @@ Out comes `./stickers/sticker-01-red-barn.png`, `sticker-02-tractor.png`, … ea
 - `--gap <pct>` (default 1.2) — how far apart two islands must be to count as separate items. **Two items came out as one sticker → lower it** (or ask for wider spacing on the sheet). **One item came out split in two → raise it** (its parts, e.g. a floating antenna or a dotted arrow, weren't bridged).
 - `--min-area <pct>` (default 0.15) — drops key speckle. There is **no maximum** — see the size note below.
 - `--preset`/`--key-color` — match the plate (default `#00FF00`). `--pad`, `--alpha-threshold`, `--output-format png|webp|gif`, `--prefix`, `--max-items`, `--keep-plate`/`--keep-sheet` behave like `cutout`'s.
+- `--sheet-mode auto|zoned|flat`, `--zones auto|off|RxC`, `--zone-cols <n>`, `--key-mode smart|flat`, `--refine` — how the plate(s) are laid out and removed. All four are explained below ("How the key actually works now").
 - Stubborn item? Fall back to one hand-measured `vidfarm mask ./sheet.png --crop x,y,w,h --flat "#00FF00"` for that one; the rest of the pack still comes from `sticker-pack`.
 
-**Pick a plate the ART doesn't use — this is the #1 way a pack comes out broken.** A chroma key removes exactly ONE color. A sticker pack of leaves, frogs, plants, money, or "eco" iconography on a GREEN plate keys holes straight through the artwork, and it looks like the cut failed when really the plate was wrong. The commands handle it two ways:
+**How the key actually works now — CONNECTIVITY, not color matching.** This is the thing to internalize, because it removes the constraint that used to force sticker art to stay flat and simple. `sticker-pack` and `cutout` do **not** delete every pixel that looks like the plate. They score each pixel's distance to its plate color, then **flood-fill inward from the edge of the sheet** through plate-ish pixels, and delete only what the fill **reaches**. Consequences, all of them useful:
 
-- **Generating?** `sticker-pack --generate` / `cutout --generate` read the subject text and move the plate off any hue it mentions — green (`#00FF00`) → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — then print which plate they chose and why. Say it back to the director when it moves: *"Your items are mostly green, so I generated them on a magenta plate."*
-- **Splitting a sheet you already have?** The plate is **detected from the sheet's four corners** (a sticker sheet always has plate in the corners), so a red/purple/blue sheet handed back from a free web generator just works with no flags.
+- **Plate-colored art survives if it's inside the item.** A green leaf on a green sheet, a `#00FF00` eye, a highlight in the plate hue — unreachable from the sheet edge, therefore not background, therefore kept. The console tells you when it mattered: *"kept 10,000 plate-colored pixels INSIDE the art that a flat key would have punched out."*
+- **Outline / line-art shapes keep their middles.** The old "rim around a see-through hole" failure is a property of the flat chromakey, not of keying. An enclosed interior can't be reached by the fill.
+- **Edges come out clean.** Boundary pixels get a real coverage estimate and the plate is **un-mixed out of each one individually** (`art = (C − (1−α)·plate)/α`, stored as straight alpha), so there's no green fringe. That's strictly better than ffmpeg's global `despill`, which rebalances every pixel and discolors plate-hued art in the interior.
+- **`--key-mode flat` brings the old behaviour back.** It's the cloud primitive's exact filter chain — use it to reproduce a cloud render bit-for-bit, or as a simple fallback.
 
-Override whenever you know better: `--key-color "#FF00FF"` or `--preset magenta` pins the plate (and turns the auto-pick off); `--no-auto-key` forces plain green. If a pack's palette collides with *every* standard plate — a rainbow icon set — split it across two sheets on two different plates rather than fighting `--tolerance`. And when a sticker is a *green* subject, never let the user generate it on green: the hand-off brief (`vidfarm handoff image`) already picks the plate for them and carries the matching `--key-color` into the follow-up command.
+What the key still can't do for you: an item whose **outer edge** is the plate color dissolves into it, and anything that **fades** into the plate (soft glow, blur, drop shadow) has no crisp silhouette to find.
 
-**Then make the ART key-safe too — CLOSED, SOLIDLY FILLED shapes.** Picking the right plate is only half of surviving the key. The other half is the failure you actually see in the wild: you ask for "sticker icons on a green plate" and the model draws **outline art** — a colored stroke with the shape's *interior left as bare plate*. On the sheet it looks perfect. After the key, the interior is gone with the background, and every sticker composites as a **rim floating around a see-through hole** (an apple that's just an apple-shaped outline, a clock with no face). Same result from three cousins: a fill that's a *near-shade* of the plate (the keyer works on tolerance, not exact match), a **translucent/glassy/glowing** material that lets the plate through, and a **soft glow or drop shadow** that fades into the plate at the edges.
+**ONE PLATE COLOR PER STICKER — `--sheet-mode zoned`.** The silhouette constraint is what "one plate per sheet" makes painful: the more items on the sheet, the more of the palette is off-limits to all of them. So stop giving the sheet one background. A **zoned** sheet is a grid of solid color **panels**, one item per panel, each panel's plate chosen against **that item**:
 
-None of that is fixable after generation — you cannot key back pixels that were never drawn. So it belongs in the **prompt**, every time:
+```
+# 6 items → a 3×2 grid of color panels, each item's plate picked against its own art
+vidfarm sticker-pack --generate "pond life, flat vector" \
+  --items "green frog,pink lotus,blue heron,white pebble,yellow reed,orange koi" \
+  --sheet-mode zoned --out-dir ./stickers
+
+# A zoned sheet from a web tool: recover the panels from the sheet's own edges
+vidfarm sticker-pack ./sheet.png --zones auto      # (this is the default)
+vidfarm sticker-pack ./sheet.png --zones 3x2       # or declare the grid you asked for
+```
+
+- The green frog sits on magenta while the pink lotus sits on green — **in the same image job**. Item art may use **any** palette, including the colors of the *other* panels.
+- Each panel is keyed independently, with its color read back off **that panel's own corners** (image models drift the exact hue they were told, so the sheet is the source of truth, not the prompt).
+- **Names stop being guessed.** On a flat sheet, `--items` is matched to items in reading order, which goes off-by-one the moment two items merge. On a zoned sheet, panel *N* holds the item you asked for in panel *N* — so the mapping is exact, and `stickers.json` records each sticker's `panel` and `plate`.
+- `--sheet-mode auto` (the default) zones a generation of 2+ named items and stays flat otherwise. `--zone-cols <n>` forces the grid width.
+
+**The FLAT one-color sheet is still first-class — reach for it with a weaker image model.** A cheap or small model will paint one background no matter how the grid is described. That's fine and fully supported:
+
+- `--sheet-mode flat` asks for the classic single-plate sheet (and `--key-mode smart` still applies, so hollow art and plate-colored interiors are still safe).
+- If you asked for zones and the model ignored them, **keying detects it and re-keys the sheet as one plate automatically** — either because a "panel" had no plate to remove, or because its item filled the panel corner to corner (so the item's own color read as the plate). It says so on the console and in `stickers.json` (`key_note`). Zoning can't strand you.
+
+**Plate color is still chosen for you on a flat sheet.** `--generate` reads the subject and moves the plate off any hue it mentions — green (`#00FF00`) → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — and prints which it chose and why; say it back to the director when it moves (*"your items are mostly green, so I generated them on a magenta plate"*). Splitting a sheet you already have, the plate is read off the sheet itself, so a red/purple/blue sheet from a free web generator just works. Pin it with `--key-color "#FF00FF"` / `--preset magenta`, or `--no-auto-key` for plain green.
+
+**Soft, painterly, furry or glassy art → `--refine`.** Every chroma key needs a crisp silhouette, so watercolor edges, fur, glow, glass and cast shadows are out of scope for the keyer no matter how clever the fill is. `--refine` handles them: the keyer's job shrinks to *locating* each item, and the item is then re-cut from the **un-keyed** sheet with the local ONNX matting model (free, ~1–2s each), which ignores color entirely and produces a genuine soft matte.
+
+```
+vidfarm sticker-pack ./painterly-sheet.png --refine --out-dir ./stickers
+```
+
+It's checked, not trusted: the matte is measured, and if it came back **empty** or **fully opaque** (the model didn't see a subject) that item keeps its keyed cut and the console says so. Flat vector art is exactly where matting fails and the chroma cut is better — so **don't use `--refine` by default**, only when the art is genuinely soft.
 
-> Every object must be a CLOSED, SOLIDLY FILLED shape — outlines and strokes must enclose an opaque fill of a different color. No outline-only, hollow, or line-art objects; never leave a shape's interior as bare background. No part of any object — fill, outline, highlight, gradient, shading or detail — may be `<PLATE HEX>` or any near-shade, tint or tone of it. No transparent, translucent, glassy, glowing or ghosted materials; every pixel of every object is fully opaque. No soft glows, blurs or drop shadows fading into the background. Keep the whole palette in strong contrast to `<PLATE HEX>`. The background must be visible ONLY around the outside of the objects, never showing through inside them.
+**What the prompt still has to ask for.** Three rules survive, and they're all about geometry rather than color:
 
-`cutout --generate`, `sticker-pack --generate`, `vidfarm handoff image`, and the `create-overlay` REST primitive all append that clause automatically with the chosen plate hex substituted in — **you only have to write it yourself when you're prompting a generator directly** (a free web tool by hand, or your own `POST /api/v1/primitives/images/generate` call). Do write it. It costs one paragraph and it is the difference between a usable pack and a re-generation.
+> Every object's OUTER EDGE must be a clearly different color from its own panel's background, and crisp — no glow, blur, mist, drop shadow or reflection fading from the object into the background. Every enclosed area must be sealed by the artwork itself, not open to the background. Keep a clear margin of plain background between objects and around the sheet edge; nothing touching, overlapping or connected.
 
-**And it's checked after the key.** `sticker-pack` and `cutout` measure, per item, the transparent area **fully enclosed by that item's own art** and report it as `hole_pct` (plus `holes`, and `hollow: true` at ≥20%) in `--json`, in `stickers.json`, and as a `⚠ N% hollow` flag on the console line. A ring, donut, picture frame or letter "O" reads the same way, so it **warns, never blocks** — the judgement is yours. When items you expected to be solid come back flagged:
+`cutout --generate`, `sticker-pack --generate`, `vidfarm handoff image` and the `create-overlay` REST primitive append the right clause for you — the relaxed one above for the smart keyer, and the strict "closed, solidly filled shapes, nothing in a near-plate shade, fully opaque" clause when `--key-mode flat` is in play. **Write it yourself only when you prompt a generator directly** (a free web tool by hand, or your own `POST /api/v1/primitives/images/generate` call).
 
-- **Re-generate the sheet** with the fill clause above spelled out. This is the fix ~90% of the time.
-- If the fill was merely *close* to the plate rather than absent, a lower `--tolerance` can rescue the sheet you already have. Nothing rescues a genuinely empty interior.
-- Last resort for one stubborn item: `vidfarm mask ./sheet.png --crop x,y,w,h` — ONNX matting doesn't care what color the fill is, so it lifts art the chroma key can't.
+**The hollow check still runs, and it means something different now.** `sticker-pack` and `cutout` measure the transparent area **fully enclosed by an item's own art** and report `hole_pct` (plus `holes`, `hollow: true` at ≥20%) in `--json`, in `stickers.json`, and as a `⚠ N% hollow` console flag. Under the smart keyer an enclosed hole **can't** have been keyed away, so a flag is usually *real* art — a ring, donut, picture frame, letter "O", or an item drawn as separate pieces with background showing between them. It warns, never blocks. If a flagged item genuinely looks wrong, the shape's fill is **open** to the background through a gap in its outline; ask the prompt for sealed shapes. Last resort for one stubborn item: `vidfarm mask ./sheet.png --crop x,y,w,h` — ONNX matting doesn't care what color anything is.
 
 **Generation is the failure point, not the cutting.** The sheet prompt is auto-appended with the important instruction — *every item fully separated by clear plate-colored background, nothing touching or overlapping, wide margins, no text, no shadows, one consistent style* — because **touching items segment as one sticker**. If a pack comes back merged, re-run the generation asking for more spacing before you fight the `--gap` knob.
 

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

@@ -248,11 +248,11 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm generate <image\|video> --prompt "…"` | `POST /api/v1/primitives/{images,videos}/generate` (polls job) | generate AI media → finished URL |
 | `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] [--gif] [--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. **`--gif` writes a transparent GIF instead** (ANIMATED for a clip; `--gif-fps`/`--gif-width`/`--gif-alpha`) — local-only, 1-bit alpha, for GIF-only sticker surfaces; prefer PNG/WebP/WebM for compositing. Aliases: `greenscreen`, `remove-background-greenscreen`. |
+| `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--gif] [--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. **`--gif` writes a transparent GIF instead** (ANIMATED for a clip; `--gif-fps`/`--gif-width`/`--gif-alpha`) — local-only, 1-bit alpha, for GIF-only sticker surfaces; prefer PNG/WebP/WebM for compositing. **`--smart`** (IMAGE + local only) swaps the flat chromakey for the connectivity keyer `cutout`/`sticker-pack` use, so plate-colored detail inside the subject and hollow/outline art survive. Aliases: `greenscreen`, `remove-background-greenscreen`. |
 | `vidfarm dedupe <video\|image\|url> [--preset light\|standard\|strong] [--variants N] [--seed <s>] [--zoom/--rotate/--skew/--speed/--saturation/--hue/--noise/--flip] [--local\|--cloud] [--out <f>\|--out-dir <d>]` | **local, free, ffmpeg-only** by default (no job); `--cloud` = `POST /api/v1/primitives/media/dedupe` (polls job) | **DEDUPLICATION — the publish-safety pass.** Makes a finished render read as a NEW upload to a platform's duplicate-content detector, invisibly to a viewer. Default preset `standard` = skew 2%, zoom 3%, rotate 2°, speed +2%, saturation +4%, plus contrast/brightness/hue/grain, a container-metadata strip and a per-variant CRF walk. **Runs on the EXPORTED file — never re-render for this.** `--variants N` mints N copies that differ from the original AND from each other (jittered magnitudes, alternating signs), one per account/posting slot; `--seed` makes a batch reproducible. A rotate forces a bigger centre-crop to hide the black corners (~6.7% on a tall frame at 2°) and says so — pass `--rotate 0` when framing matters more. `--flip` is the strongest single knob but visibly reverses on-screen text. **Ask the operator whether they want this BEFORE publishing or bulk-producing.** Aliases: `dedup`, `deduplicate`, `uniquify`. |
-| `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`, plus `hole_pct`/`hollow` — the "the key ate the fill" check (outline-only art keys into a rim around a transparent hole; `--generate` prompts against it automatically, and the console prints a `Hollow:` warning with the fix). Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
+| `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. Keys by CONNECTIVITY by default (`--key-mode smart`): the plate is flood-filled in from the frame edge, so plate-colored detail inside the subject and hollow/outline art survive, and the plate is un-mixed out of each edge pixel individually instead of by a global `despill`. `--key-mode flat` is the old plain chromakey. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`, `key_mode`, `protected_px` (plate-colored pixels kept inside the art), plus `hole_pct`/`hollow` (under the smart keyer an enclosed hole is usually real art, so it warns only). 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 sticker-pack [sheet\|url] [--generate "<theme>"] [--items "a,b,c"] [--count <n>] [--dry-run] [--gap <pct>] [--min-area <pct>] [--output-format png\|webp\|gif] [--out-dir <d>]` | **local, free, ffmpeg-only** (no job; only `--generate` bills, ONCE for the whole set) — key + alpha-channel segmentation + per-item trim | **The STICKER-PACK maker — the answer whenever a director asks for "a sticker pack" / prop set / icon set.** A pack is ONE greenscreen sheet holding every item, keyed once and then masked apart: 1/N the cost of N `cutout` calls, and the only way a cast stays on-style. Finds each item **automatically** by segmenting the keyed sheet's alpha into connected islands — no hand-measured `--crop` rects — and writes one snug transparent file per item (named from `--items`, reading order) plus a `stickers.json` manifest. `--dry-run` prints the detected boxes first; `--gap` merges (lower) or splits (raise) items that came out joined/broken; items have **no maximum size** — a full-frame landscape/backdrop is as valid a sticker as a 3% icon. **Plate color is chosen for you:** when generating it reads the subject and moves the plate off any hue the art uses (green → magenta → blue → black → white — a pack of leaves/frogs/money on GREEN would key holes through the art), and when splitting an existing sheet it DETECTS the plate from the sheet's four corners, so a red/purple sheet handed back from a web tool just works. Pin it with `--key-color`/`--preset`, or `--no-auto-key` for plain green. **The ART is made key-safe too:** the generation prompt is auto-appended with "closed, solidly filled shapes, no outline-only/hollow art, nothing in the plate hue or a near-shade, fully opaque, no glow/translucency" — the fix for stickers that come back as a rim around a transparent hole — and after keying each item reports `holes`/`hole_pct`/`hollow` (console `⚠ N% hollow` at ≥20%, plus `--json` and `stickers.json`). It **warns, never blocks** (a ring/frame/donut reads identically); re-generate with the fill clause, or lift that one item with `vidfarm mask --crop …`. `--output-format gif` emits 1-bit-alpha GIFs for GIF-only surfaces. IMAGE-only. Aliases: `stickers`, `sticker-sheet`. See recipe `cutout-graphics-for-explainers.md` → "A sticker pack". |
+| `vidfarm sticker-pack [sheet\|url] [--generate "<theme>"] [--items "a,b,c"] [--count <n>] [--dry-run] [--gap <pct>] [--min-area <pct>] [--output-format png\|webp\|gif] [--out-dir <d>]` | **local, free, ffmpeg-only** (no job; only `--generate` bills, ONCE for the whole set) — key + alpha-channel segmentation + per-item trim | **The STICKER-PACK maker — the answer whenever a director asks for "a sticker pack" / prop set / icon set.** A pack is ONE greenscreen sheet holding every item, keyed once and then masked apart: 1/N the cost of N `cutout` calls, and the only way a cast stays on-style. Finds each item **automatically** by segmenting the keyed sheet's alpha into connected islands — no hand-measured `--crop` rects — and writes one snug transparent file per item (named from `--items`, reading order) plus a `stickers.json` manifest. `--dry-run` prints the detected boxes first; `--gap` merges (lower) or splits (raise) items that came out joined/broken; items have **no maximum size** — a full-frame landscape/backdrop is as valid a sticker as a 3% icon. **The key is CONNECTIVITY-based (`--key-mode smart`, the default):** the plate is flood-filled inward from the sheet's edge and only background that REACHES the edge is deleted, so plate-colored detail inside an item, and an outline shape whose interior is bare plate, both survive; edge pixels get the plate un-mixed out of them individually (real alpha math, better than a global `despill`). `--key-mode flat` is the old plain chromakey — the simple fallback and the way to match a cloud render exactly. **ONE PLATE PER STICKER (`--sheet-mode zoned`):** generates a grid of solid color PANELS, one item per panel, each panel's plate picked against that item (green frog on magenta beside a pink flower on green), keyed panel-by-panel with the color read back off that panel's own corners — item art may then use any palette including other panels' colors, and names map to PANELS instead of reading order (`panel`/`plate` land in `stickers.json`). `--sheet-mode auto` (default) zones a generation of 2+ named items; `--sheet-mode flat` forces the classic one-color sheet for a weaker model, and if a model ignores the grid anyway the keyer detects it (a panel with no plate, or one whose item filled it corner to corner) and **re-keys the sheet as one plate automatically**. Read a zoned sheet you already have with `--zones auto` (default) or `--zones 3x2`. **`--refine`** re-cuts each located item from the UN-keyed sheet with the local ONNX matting model (free, ~1–2s each) for painterly/soft/furry/glassy art, falling back per item to the keyed cut when the matte comes back empty or fully opaque. **Plate color is still chosen for you** when generating flat (green → magenta → blue → black → white) and detected off an existing sheet. Per-item `holes`/`hole_pct`/`hollow` are still reported (console `⚠ N% hollow` at ≥20%, `--json`, `stickers.json`) — under the smart keyer a flag usually means real art (ring/frame/donut), so it **warns, never blocks**; lift a stubborn item with `vidfarm mask --crop …`. `--output-format gif` emits 1-bit-alpha GIFs for GIF-only surfaces. IMAGE-only. Aliases: `stickers`, `sticker-sheet`. See recipe `cutout-graphics-for-explainers.md` → "A sticker pack". |
 | `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 [--sample] [--search "…"] [--free\|--all] [--own-key] [--limit N]` | `GET /api/v1/primitives/audio/voices` | **Browse AND sample narration voices.** Default roster = the premium ElevenLabs catalog reached through **vidfarm's own ElevenLabs connection** — the user needs no ElevenLabs account, API key, or subscription; narration is billed as vidfarm wallet credits (pennies each). `--free` = the $0 local Kokoro roster (`--all` = both). `--sample` writes listenable clips to `./voice-samples` (`--sample-count`, `--sample-out`, `--sample-text`) and is **free on both tiers** — premium samples are ElevenLabs' own preview clips, free samples render locally — so it's safe in `minimize`. `--search` filters by name/labels/description. **In interactive mode play the samples and let the USER pick**; autonomous = default a voice and still say they can choose. `--own-key` lists the customer's own ElevenLabs account instead. |
@@ -281,7 +281,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm whoami` | `GET /api/v1/user/me` | who am I (also prints the active cost mode) |
 | `vidfarm cost-mode [minimize\|hybrid\|rich-ai\|pure-videogen]` | (local `~/.vidfarm/cost-mode.json`) | show/set the money-saving preference every billed command respects; no arg = show + explain each; `--clear` forgets it |
 | `vidfarm mode [interactive\|autonomous]` | local (`~/.vidfarm/interaction-mode.json`) | **The SECOND preference axis — ask it alongside cost mode.** Is the human in the loop? `interactive` = at checkpoints you hand them a copy-paste brief (an image prompt for a FREE web generator; a keyword list for sourcing clips) and they hand files back — usually BETTER output, and in `minimize` the only way to get custom art at all. `autonomous` = you finish solo within the budget. Independent of cost mode: every cost mode runs either way. No arg prints the pair + the explainer to relay; `--clear` forgets; per-run `--interactive`/`--autonomous`. Aliases: `interaction-mode`, `interaction`. |
-| `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate), spells out the **key-safe fill rules** (closed solidly-filled shapes, no outline-only/hollow art, nothing in a near-plate shade, fully opaque) so the sheet doesn't come back as rims around holes, and carries that `--key-color` into the follow-up. `--single` for one subject. |
+| `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate), spells out what the local keyer actually needs (a crisp silhouette in a different color from the plate, sealed shapes, clear gaps between items — hollow art and plate-colored detail INSIDE a shape are fine now), and carries that `--key-color` into the follow-up. `--single` for one subject. `--zoned` asks instead for a color-block sheet (one panel colour per item) and hands back a `--zones RxC` follow-up — worth it when the pack's own colors fight one plate, but leave it off for a free consumer tool that may not follow a grid. |
 | `vidfarm handoff raws --keywords "a,b" [--platforms tiktok,youtube] [--count N] [--purpose "…"]` | local (pure text) | **The interactive-mode CLIP-SOURCING brief** — the bottom rung of the sourcing ladder (browser control → `clipper`/`raws scan --cloud` → public raws → the human). Prints what to search, how to download (a Google *search* for a downloader, never a link that rots), and the import command for when the folder is ready. |
 | `vidfarm storyboard [dir] [--init] [--frames "Title\|scene,…"] [--json]` | local (`STORYBOARD.md` / `SCRIPT.md`) | **The plan pass, and a core part of the composition format.** Scaffolds/reads the project's `STORYBOARD.md`: ordered frames with `duration`/`status`/`src`/`scene`/`voiceover`. The Vidfarm editor renders this file in its **Storyboard** view (contact sheet + per-frame comments + `outline → built → animated` progress), so it's the cheapest place to get a director's approval before building. Not to be confused with `vidfarm sequence` (which GENERATES storyboard images for the pure-videogen pipeline). Alias: `plan`. |
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only; readable on the free plan too (shows $0.00). Aliases: `spend`, `costs` |

package/.agents/skills/vidfarm/references/hooks-and-virality.md

@@ -228,10 +228,11 @@ A video with replies gets shown again; a video with none dies at its first audie
 - **The named omission** — *"I left one thing out on purpose. Ask me."* Converts what you couldn't fit into the reason to reply.
 - **The soft disagree** — a true concession people want to argue with. Not ragebait if you actually believe it.
 - **The specific question** — concrete always beats "thoughts?".
+- **The keyword comment** — *"Comment CLIPPER and I'll send you the breakdown."* Standard, allowed, and it works: the keyword is the reply the algorithm counts, and the word itself doubles as a filter. Keep the keyword topical (name the thing, not the money), promise something you actually hand over, and say what they get. What makes this beat go wrong is the *promise*, not the mechanic.
 
-**⚠️ Bait is the highest-compliance-risk beat in the video.** For money/health/appearance topics the obvious bait is the illegal one:
+**⚠️ Bait is the highest-compliance-risk beat in the video.** For money/health/appearance topics the risk is what you promise in exchange for the reply:
 
-- ❌ *"Comment MONEY and I'll send you the link"* — the most scam-coded line available, and a DM funnel.
+- ❌ *"Comment MONEY and I'll show you how to make $10k/mo"* — the keyword is fine; the earnings claim attached to it is what's scam-coded and enforceable. Same line with a topical keyword and a deliverable ("Comment CLIPPER for the template") is fine.
 - ❌ *"How much do you want to make a month?"* — invites an earnings-claim thread you now own.
 - ❌ *"Follow for part two"* — breaks the standalone rule.
 - ❌ Fake controversy, ragebait, or a deliberate error to farm corrections. Works once, costs the positioning permanently.

package/SKILL.director.md

@@ -209,13 +209,17 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 **Explainer/cutout videos — the transparent-sticker workflow.** For explainers (a subject "on stage" while labels, arrows, and props pop in around it), the cheap workhorse is a **transparent cutout sticker**: `vidfarm cutout --generate "<subject>"` AI-generates the graphic on a chroma plate, keys it out, **and trims the canvas down to the subject's true min width/height** — one free local ffmpeg step, no mostly-empty PNG to fight with — then `vidfarm place` + `vidfarm keyframes` scale/position and animate it (zoom, grow, shake, drift). It's the same "generate a reusable element once, then reuse it" thrift as the cheap harness, tuned for stickers. Full guided harness: recipe `recipes/cutout-graphics-for-explainers.md`; placement + zoom/grow/shake/move motion recipes: `references/editor-workflows.md` (“Cutout graphics for explainers”).
 
-**"Make me a sticker pack" = ONE greenscreen sheet of many items, then masked apart — and `vidfarm sticker-pack` is that whole loop.** A sticker pack is never one graphic; it's a *set* (props, icons, reactions, characters, backdrops) that must share one art style. Generating them one at a time is both expensive (N image jobs) and inconsistent (N independent styles), so the move is the opposite: **generate a single image holding every item, laid out on a flat greenscreen plate, then cut each item out locally for $0.** `vidfarm sticker-pack --generate "<theme>" --items "a,b,c"` does all of it — one billed image job for the whole set, then a free local key, an **automatic** alpha-segmentation that finds each item (no hand-measured `--crop` rects), a per-item trim to its true bounding box, and a `stickers.json` manifest. Already have a greenscreen sheet? `vidfarm sticker-pack ./sheet.png` cuts it up for **$0**. Use `--dry-run` to eyeball the detected boxes first; `--gap` merges/splits items that came out joined or broken; `vidfarm mask <sheet> --crop …` is the manual fallback for one stubborn item.
+**"Make me a sticker pack" = ONE greenscreen sheet of many items, then masked apart — and `vidfarm sticker-pack` is that whole loop.** A sticker pack is never one graphic; it's a *set* (props, icons, reactions, characters, backdrops) that must share one art style. Generating them one at a time is both expensive (N image jobs) and inconsistent (N independent styles), so the move is the opposite: **generate a single image holding every item, laid out on a flat greenscreen plate, then cut each item out locally for $0.** `vidfarm sticker-pack --generate "<theme>" --items "a,b,c"` does all of it — one billed image job for the whole set, then a free local key, an **automatic** alpha-segmentation that finds each item (no hand-measured `--crop` rects), a per-item trim to its true bounding box, and a `stickers.json` manifest. The sheet comes in two shapes: **zoned** (a grid of color panels, one plate color per item — the default for 2+ named items, and what frees the art from a single banned hue) and **flat** (the classic one-color plate, for a model that can't follow a color-block grid). Already have a greenscreen sheet? `vidfarm sticker-pack ./sheet.png` cuts it up for **$0**. Use `--dry-run` to eyeball the detected boxes first; `--gap` merges/splits items that came out joined or broken; `vidfarm mask <sheet> --crop …` is the manual fallback for one stubborn item.
 
 - **Stickers are not necessarily small.** A sticker is *any* transparent element you place and animate — an icon, a mascot, a prop, a character, and equally **a full-width landscape, skyline, or backdrop** that fills the frame. `sticker-pack` filters speckle only; it has no maximum item size. Ask for the big pieces in the same sheet as the small ones.
 - **Stickers are usually animated, not pasted.** Once placed, animate each one with `vidfarm keyframes` presets (`pop-in`, `float`, `shake`, `grow`, `slide-in-left`, `drift`) — that's HTML/CSS canvas motion, deterministic, free, and identical in preview and render. Layer moves up (pop-in, then idle float) for real life. See `references/editor-workflows.md` → "Cutout graphics for explainers".
 - **A sticker can carry its OWN motion too.** A *moving* subject has no single bounding box, so it isn't a PNG: key the clip with `vidfarm remove-greenscreen <video>` → transparent WebM (browser/editor-playable, the right choice on a composition).
-- **The plate must be a color the ART DOESN'T USE — green is a default, not a law.** A chroma key removes exactly ONE color, so a green plate under green artwork (leaves, frogs, plants, money, an "eco" icon set) keys holes straight through the stickers. `sticker-pack`/`cutout` handle this for you in two ways, and you should still say it out loud when it matters: **(a)** when generating, they read the subject and move the plate off any hue it mentions — green → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — and print which plate they picked and why; **(b)** when splitting a sheet you already have, they **detect the plate from the sheet's four corners**, so a red/purple/blue sheet handed back from a web generator just works. Pin it yourself with `--key-color "#FF00FF"` / `--preset magenta` (that disables the auto-pick), or `--no-auto-key` to force plain green. If a pack's palette collides with *every* standard plate, split it into two sheets on two different plates rather than fighting the key.
-- **The ART must be CLOSED and SOLIDLY FILLED — this is the other half of surviving the key, and the #1 way stickers come back broken.** Ask an image model for "icons on a green plate" and it will happily draw **outline art**: a colored stroke with the shape's interior left as bare plate. It looks perfect on the sheet, and after the key each sticker is a **rim floating around a see-through hole** (an apple-shaped outline with nothing inside it). Same outcome from a *near-plate* fill (the keyer works on tolerance, not exact match), a translucent/glassy/glowing material, or a soft glow fading into the plate. **You cannot key those pixels back — it has to be in the prompt:** *"every object is a closed, solidly filled shape; outlines must enclose an opaque fill of a different color; no outline-only or hollow art; nothing on the art in the plate color or any near-shade of it; fully opaque, no translucency, glow or drop shadow."* `cutout --generate`, `sticker-pack --generate`, `handoff image` and the `create-overlay` primitive **append that clause for you** with the chosen plate hex — write it yourself only when you prompt a generator directly. After the key, both commands report per-item `hole_pct`/`hollow` (console `⚠ N% hollow`, `--json`, `stickers.json`) — a ring or picture frame reads the same way, so it **warns, never blocks**. Flagged and it shouldn't be? Re-generate with the fill clause; a *near*-plate fill can sometimes be rescued with a lower `--tolerance`; one stubborn item can be lifted with `vidfarm mask --crop …` (ONNX matting ignores fill color).
+- **The key is CONNECTIVITY-based, so "the art can't use the plate color" is no longer true — only its OUTER EDGE can't.** `sticker-pack`/`cutout` (and `remove-greenscreen <image> --smart`) don't delete every pixel that looks like the plate. They flood-fill the plate **inward from the edge of the sheet** and delete only background that **reaches** that edge. A green leaf inside a mascot, a plate-colored eye, an outline shape whose interior was left as bare plate — none of it is reachable, so none of it is deleted. Edges are feathered and the plate is **un-mixed out of each edge pixel individually** (real alpha math, not a global `despill`), which is what kills the green fringe a flat key leaves. What still matters: the item's **silhouette** must be a different color from its own plate, and nothing may **fade** into the plate (no soft glow, blur or drop shadow on the background). Say the win out loud when it matters — the console prints *"kept N plate-colored pixels INSIDE the art that a flat key would have punched out."* `--key-mode flat` restores the old plain-chromakey behaviour (the cloud path's exact filter chain — use it to reproduce a cloud render, or as a simple fallback).
+- **Plate color is still chosen for you, and it still matters for the silhouette.** When generating, `sticker-pack`/`cutout` read the subject and move the plate off any hue it mentions — green → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — printing which plate they picked and why. When splitting a sheet you already have, they **read the plate off the sheet itself**, so a red/purple/blue sheet from a web generator just works. Pin it with `--key-color "#FF00FF"` / `--preset magenta`, or `--no-auto-key` for plain green.
+- **ONE PLATE COLOR PER STICKER — `--sheet-mode zoned`.** The real fix for "our art has to be simple because of the greenscreen" is to stop giving a whole sheet one background. A **zoned** sheet is a grid of solid color **panels**, one item per panel, each panel's plate chosen against **that item**: a green frog on magenta beside a pink flower on green, in one image job. Each panel is keyed independently with its own color (read back off that panel's own corners, because models drift the hue they were asked for), and item art may then use **any palette at all — including the color of a different panel**. Bonus: names stop being guessed from reading order — panel N holds the item you asked for in panel N, so `--items` maps exactly, and `stickers.json` records each sticker's `panel` and `plate`. `--sheet-mode auto` (the default) zones a generation of 2+ named items and stays flat otherwise. Reading a zoned sheet you already have: `--zones auto` (default — recovers the grid from the sheet's own edges) or `--zones 3x2`.
+- **The FLAT single-color sheet is still first-class — use it for a weaker image model.** Not every model can hold a color-block grid; a cheap or small one will paint one background regardless of the prompt. That path is fully supported: `--sheet-mode flat` asks for the classic one-plate sheet, and even if you asked for zones, keying **detects a model that ignored the grid** (a panel with no plate to remove, or one whose item filled it corner to corner) and **automatically re-keys the sheet as one plate**, telling you it did. So zoning can't strand you — worst case you're back on the simple method, still for $0.
+- **Painterly, soft, furry or glassy art → `--refine`.** Chroma keying of any kind needs a crisp silhouette. When the art has genuinely soft edges (watercolor, fur, glow, glass, a cast shadow), add `--refine`: after the keyer locates each item, that item is re-cut from the **un-keyed** sheet with the local ONNX matting model (free, ~1–2s each), which is color-blind and handles soft mattes. It sanity-checks each matte and falls back to the keyed cut per item if the model didn't find a subject — flat vector art is exactly the case where matting fails and the chroma cut is better, so don't reach for `--refine` by default.
+- **What the ART still has to honor: a crisp silhouette, sealed shapes, and gaps between items.** The connectivity key removes the old bans on hollow art and plate-colored fills, but three prompt rules are still load-bearing: **(1)** every object's **outer edge** is a clearly different color from its own plate and is **crisp** — no glow, blur, mist or drop shadow fading into the background; **(2)** enclosed areas are **sealed by the artwork**, because a gap in an outline lets the background flow in and the fill really does get keyed; **(3)** items are separated by a clear margin of plate — two touching items segment as ONE sticker. `cutout --generate`, `sticker-pack --generate`, `handoff image` and the `create-overlay` primitive **append the right clause for you** (a relaxed one for the smart keyer, the strict "closed, solidly filled, nothing in a near-plate shade" one when `--key-mode flat` is in play) — write it yourself only when prompting a generator directly. Both commands still report per-item `hole_pct`/`hollow` (console `⚠ N% hollow`, `--json`, `stickers.json`); under the smart keyer a flagged item is *usually real* (a ring, frame, donut, or pieces with background between them), so it **warns, never blocks**. One stubborn item can always be lifted with `vidfarm mask --crop …` (ONNX matting ignores color entirely).
 - **Transparent GIF is supported, for GIF-only surfaces.** `vidfarm sticker-pack … --output-format gif` (stills) and `vidfarm remove-greenscreen <video> --gif` (animated) emit transparent GIFs. GIF alpha is **1-bit**, so edges go hard — fine for chat/forum/Notion sticker surfaces, worse than PNG/WebP/WebM for compositing on a timeline. Prefer PNG/WebP/WebM unless the destination only eats GIF.
 
 **Explainer house style — the defaults to build with unless told otherwise.** **White background / light mode** (plain white stage, no gradients, no dark mode, no photo backdrop), **kinetic word-by-word captions** in dark ink on the light stage (`vidfarm captions generate --style word-pop --color "#111111" --active-color "#7C3AED" --background-style plain` — skip outlines/shadows, they're only needed over busy footage), and **female TTS narration** (`vidfarm tts --voice coral` on OpenAI — `nova` for energy, `sage` for calm; `Kore`/`Leda` on Gemini; any ElevenLabs voice via `vidfarm voices`). **Keep it clean and simple** — one idea on screen at a time, two or three cutouts per beat, one accent color, one font, lots of white space; remove before you add. **Illustrations default to simplicity**: flat vector, simple shapes, minimal detail, 2–3 flat colors, no baked-in text — simple art keys cleanly, trims tight, and stays on-style across the whole cast. State the defaults once so the director can override any of them. Full detail: recipe `recipes/cutout-graphics-for-explainers.md` (“House style — the explainer defaults”). **If the director takes the stage off white**, two things stop being optional: every sticker's **white die-cut rim** has to be stripped (on a dark stage it's a glaring halo and the most obvious bot-made artefact in the frame — recipe → “Stickers on a DARK or photographic stage”), and the caption hexes above stop applying — **caption colour, active-word colour and plate are chosen by measuring the composited background behind the caption band**, one treatment per video (`harnesses/short-form.HARNESS.md` → “Caption styling is MEASURED off the background”). Related: **on-screen text and captions must not say the same thing at once** — display text carries the argument, captions carry only what the screen doesn't show.
@@ -1638,10 +1642,11 @@ A video with replies gets shown again; a video with none dies at its first audie
 - **The named omission** — *"I left one thing out on purpose. Ask me."* Converts what you couldn't fit into the reason to reply.
 - **The soft disagree** — a true concession people want to argue with. Not ragebait if you actually believe it.
 - **The specific question** — concrete always beats "thoughts?".
+- **The keyword comment** — *"Comment CLIPPER and I'll send you the breakdown."* Standard, allowed, and it works: the keyword is the reply the algorithm counts, and the word itself doubles as a filter. Keep the keyword topical (name the thing, not the money), promise something you actually hand over, and say what they get. What makes this beat go wrong is the *promise*, not the mechanic.
 
-**⚠️ Bait is the highest-compliance-risk beat in the video.** For money/health/appearance topics the obvious bait is the illegal one:
+**⚠️ Bait is the highest-compliance-risk beat in the video.** For money/health/appearance topics the risk is what you promise in exchange for the reply:
 
-- ❌ *"Comment MONEY and I'll send you the link"* — the most scam-coded line available, and a DM funnel.
+- ❌ *"Comment MONEY and I'll show you how to make $10k/mo"* — the keyword is fine; the earnings claim attached to it is what's scam-coded and enforceable. Same line with a topical keyword and a deliverable ("Comment CLIPPER for the template") is fine.
 - ❌ *"How much do you want to make a month?"* — invites an earnings-claim thread you now own.
 - ❌ *"Follow for part two"* — breaks the standalone rule.
 - ❌ Fake controversy, ragebait, or a deliberate error to farm corrections. Works once, costs the positioning permanently.
@@ -2278,11 +2283,11 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm generate <image\|video> --prompt "…"` | `POST /api/v1/primitives/{images,videos}/generate` (polls job) | generate AI media → finished URL |
 | `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] [--gif] [--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. **`--gif` writes a transparent GIF instead** (ANIMATED for a clip; `--gif-fps`/`--gif-width`/`--gif-alpha`) — local-only, 1-bit alpha, for GIF-only sticker surfaces; prefer PNG/WebP/WebM for compositing. Aliases: `greenscreen`, `remove-background-greenscreen`. |
+| `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--gif] [--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. **`--gif` writes a transparent GIF instead** (ANIMATED for a clip; `--gif-fps`/`--gif-width`/`--gif-alpha`) — local-only, 1-bit alpha, for GIF-only sticker surfaces; prefer PNG/WebP/WebM for compositing. **`--smart`** (IMAGE + local only) swaps the flat chromakey for the connectivity keyer `cutout`/`sticker-pack` use, so plate-colored detail inside the subject and hollow/outline art survive. Aliases: `greenscreen`, `remove-background-greenscreen`. |
 | `vidfarm dedupe <video\|image\|url> [--preset light\|standard\|strong] [--variants N] [--seed <s>] [--zoom/--rotate/--skew/--speed/--saturation/--hue/--noise/--flip] [--local\|--cloud] [--out <f>\|--out-dir <d>]` | **local, free, ffmpeg-only** by default (no job); `--cloud` = `POST /api/v1/primitives/media/dedupe` (polls job) | **DEDUPLICATION — the publish-safety pass.** Makes a finished render read as a NEW upload to a platform's duplicate-content detector, invisibly to a viewer. Default preset `standard` = skew 2%, zoom 3%, rotate 2°, speed +2%, saturation +4%, plus contrast/brightness/hue/grain, a container-metadata strip and a per-variant CRF walk. **Runs on the EXPORTED file — never re-render for this.** `--variants N` mints N copies that differ from the original AND from each other (jittered magnitudes, alternating signs), one per account/posting slot; `--seed` makes a batch reproducible. A rotate forces a bigger centre-crop to hide the black corners (~6.7% on a tall frame at 2°) and says so — pass `--rotate 0` when framing matters more. `--flip` is the strongest single knob but visibly reverses on-screen text. **Ask the operator whether they want this BEFORE publishing or bulk-producing.** Aliases: `dedup`, `deduplicate`, `uniquify`. |
-| `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`, plus `hole_pct`/`hollow` — the "the key ate the fill" check (outline-only art keys into a rim around a transparent hole; `--generate` prompts against it automatically, and the console prints a `Hollow:` warning with the fix). Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
+| `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. Keys by CONNECTIVITY by default (`--key-mode smart`): the plate is flood-filled in from the frame edge, so plate-colored detail inside the subject and hollow/outline art survive, and the plate is un-mixed out of each edge pixel individually instead of by a global `despill`. `--key-mode flat` is the old plain chromakey. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`, `key_mode`, `protected_px` (plate-colored pixels kept inside the art), plus `hole_pct`/`hollow` (under the smart keyer an enclosed hole is usually real art, so it warns only). 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 sticker-pack [sheet\|url] [--generate "<theme>"] [--items "a,b,c"] [--count <n>] [--dry-run] [--gap <pct>] [--min-area <pct>] [--output-format png\|webp\|gif] [--out-dir <d>]` | **local, free, ffmpeg-only** (no job; only `--generate` bills, ONCE for the whole set) — key + alpha-channel segmentation + per-item trim | **The STICKER-PACK maker — the answer whenever a director asks for "a sticker pack" / prop set / icon set.** A pack is ONE greenscreen sheet holding every item, keyed once and then masked apart: 1/N the cost of N `cutout` calls, and the only way a cast stays on-style. Finds each item **automatically** by segmenting the keyed sheet's alpha into connected islands — no hand-measured `--crop` rects — and writes one snug transparent file per item (named from `--items`, reading order) plus a `stickers.json` manifest. `--dry-run` prints the detected boxes first; `--gap` merges (lower) or splits (raise) items that came out joined/broken; items have **no maximum size** — a full-frame landscape/backdrop is as valid a sticker as a 3% icon. **Plate color is chosen for you:** when generating it reads the subject and moves the plate off any hue the art uses (green → magenta → blue → black → white — a pack of leaves/frogs/money on GREEN would key holes through the art), and when splitting an existing sheet it DETECTS the plate from the sheet's four corners, so a red/purple sheet handed back from a web tool just works. Pin it with `--key-color`/`--preset`, or `--no-auto-key` for plain green. **The ART is made key-safe too:** the generation prompt is auto-appended with "closed, solidly filled shapes, no outline-only/hollow art, nothing in the plate hue or a near-shade, fully opaque, no glow/translucency" — the fix for stickers that come back as a rim around a transparent hole — and after keying each item reports `holes`/`hole_pct`/`hollow` (console `⚠ N% hollow` at ≥20%, plus `--json` and `stickers.json`). It **warns, never blocks** (a ring/frame/donut reads identically); re-generate with the fill clause, or lift that one item with `vidfarm mask --crop …`. `--output-format gif` emits 1-bit-alpha GIFs for GIF-only surfaces. IMAGE-only. Aliases: `stickers`, `sticker-sheet`. See recipe `cutout-graphics-for-explainers.md` → "A sticker pack". |
+| `vidfarm sticker-pack [sheet\|url] [--generate "<theme>"] [--items "a,b,c"] [--count <n>] [--dry-run] [--gap <pct>] [--min-area <pct>] [--output-format png\|webp\|gif] [--out-dir <d>]` | **local, free, ffmpeg-only** (no job; only `--generate` bills, ONCE for the whole set) — key + alpha-channel segmentation + per-item trim | **The STICKER-PACK maker — the answer whenever a director asks for "a sticker pack" / prop set / icon set.** A pack is ONE greenscreen sheet holding every item, keyed once and then masked apart: 1/N the cost of N `cutout` calls, and the only way a cast stays on-style. Finds each item **automatically** by segmenting the keyed sheet's alpha into connected islands — no hand-measured `--crop` rects — and writes one snug transparent file per item (named from `--items`, reading order) plus a `stickers.json` manifest. `--dry-run` prints the detected boxes first; `--gap` merges (lower) or splits (raise) items that came out joined/broken; items have **no maximum size** — a full-frame landscape/backdrop is as valid a sticker as a 3% icon. **The key is CONNECTIVITY-based (`--key-mode smart`, the default):** the plate is flood-filled inward from the sheet's edge and only background that REACHES the edge is deleted, so plate-colored detail inside an item, and an outline shape whose interior is bare plate, both survive; edge pixels get the plate un-mixed out of them individually (real alpha math, better than a global `despill`). `--key-mode flat` is the old plain chromakey — the simple fallback and the way to match a cloud render exactly. **ONE PLATE PER STICKER (`--sheet-mode zoned`):** generates a grid of solid color PANELS, one item per panel, each panel's plate picked against that item (green frog on magenta beside a pink flower on green), keyed panel-by-panel with the color read back off that panel's own corners — item art may then use any palette including other panels' colors, and names map to PANELS instead of reading order (`panel`/`plate` land in `stickers.json`). `--sheet-mode auto` (default) zones a generation of 2+ named items; `--sheet-mode flat` forces the classic one-color sheet for a weaker model, and if a model ignores the grid anyway the keyer detects it (a panel with no plate, or one whose item filled it corner to corner) and **re-keys the sheet as one plate automatically**. Read a zoned sheet you already have with `--zones auto` (default) or `--zones 3x2`. **`--refine`** re-cuts each located item from the UN-keyed sheet with the local ONNX matting model (free, ~1–2s each) for painterly/soft/furry/glassy art, falling back per item to the keyed cut when the matte comes back empty or fully opaque. **Plate color is still chosen for you** when generating flat (green → magenta → blue → black → white) and detected off an existing sheet. Per-item `holes`/`hole_pct`/`hollow` are still reported (console `⚠ N% hollow` at ≥20%, `--json`, `stickers.json`) — under the smart keyer a flag usually means real art (ring/frame/donut), so it **warns, never blocks**; lift a stubborn item with `vidfarm mask --crop …`. `--output-format gif` emits 1-bit-alpha GIFs for GIF-only surfaces. IMAGE-only. Aliases: `stickers`, `sticker-sheet`. See recipe `cutout-graphics-for-explainers.md` → "A sticker pack". |
 | `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 [--sample] [--search "…"] [--free\|--all] [--own-key] [--limit N]` | `GET /api/v1/primitives/audio/voices` | **Browse AND sample narration voices.** Default roster = the premium ElevenLabs catalog reached through **vidfarm's own ElevenLabs connection** — the user needs no ElevenLabs account, API key, or subscription; narration is billed as vidfarm wallet credits (pennies each). `--free` = the $0 local Kokoro roster (`--all` = both). `--sample` writes listenable clips to `./voice-samples` (`--sample-count`, `--sample-out`, `--sample-text`) and is **free on both tiers** — premium samples are ElevenLabs' own preview clips, free samples render locally — so it's safe in `minimize`. `--search` filters by name/labels/description. **In interactive mode play the samples and let the USER pick**; autonomous = default a voice and still say they can choose. `--own-key` lists the customer's own ElevenLabs account instead. |
@@ -2311,7 +2316,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm whoami` | `GET /api/v1/user/me` | who am I (also prints the active cost mode) |
 | `vidfarm cost-mode [minimize\|hybrid\|rich-ai\|pure-videogen]` | (local `~/.vidfarm/cost-mode.json`) | show/set the money-saving preference every billed command respects; no arg = show + explain each; `--clear` forgets it |
 | `vidfarm mode [interactive\|autonomous]` | local (`~/.vidfarm/interaction-mode.json`) | **The SECOND preference axis — ask it alongside cost mode.** Is the human in the loop? `interactive` = at checkpoints you hand them a copy-paste brief (an image prompt for a FREE web generator; a keyword list for sourcing clips) and they hand files back — usually BETTER output, and in `minimize` the only way to get custom art at all. `autonomous` = you finish solo within the budget. Independent of cost mode: every cost mode runs either way. No arg prints the pair + the explainer to relay; `--clear` forgets; per-run `--interactive`/`--autonomous`. Aliases: `interaction-mode`, `interaction`. |
-| `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate), spells out the **key-safe fill rules** (closed solidly-filled shapes, no outline-only/hollow art, nothing in a near-plate shade, fully opaque) so the sheet doesn't come back as rims around holes, and carries that `--key-color` into the follow-up. `--single` for one subject. |
+| `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate), spells out what the local keyer actually needs (a crisp silhouette in a different color from the plate, sealed shapes, clear gaps between items — hollow art and plate-colored detail INSIDE a shape are fine now), and carries that `--key-color` into the follow-up. `--single` for one subject. `--zoned` asks instead for a color-block sheet (one panel colour per item) and hands back a `--zones RxC` follow-up — worth it when the pack's own colors fight one plate, but leave it off for a free consumer tool that may not follow a grid. |
 | `vidfarm handoff raws --keywords "a,b" [--platforms tiktok,youtube] [--count N] [--purpose "…"]` | local (pure text) | **The interactive-mode CLIP-SOURCING brief** — the bottom rung of the sourcing ladder (browser control → `clipper`/`raws scan --cloud` → public raws → the human). Prints what to search, how to download (a Google *search* for a downloader, never a link that rots), and the import command for when the folder is ready. |
 | `vidfarm storyboard [dir] [--init] [--frames "Title\|scene,…"] [--json]` | local (`STORYBOARD.md` / `SCRIPT.md`) | **The plan pass, and a core part of the composition format.** Scaffolds/reads the project's `STORYBOARD.md`: ordered frames with `duration`/`status`/`src`/`scene`/`voiceover`. The Vidfarm editor renders this file in its **Storyboard** view (contact sheet + per-frame comments + `outline → built → animated` progress), so it's the cheapest place to get a director's approval before building. Not to be confused with `vidfarm sequence` (which GENERATES storyboard images for the pure-videogen pipeline). Alias: `plan`. |
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only; readable on the free plan too (shows $0.00). Aliases: `spend`, `costs` |
@@ -3289,28 +3294,58 @@ Out comes `./stickers/sticker-01-red-barn.png`, `sticker-02-tractor.png`, … ea
 - `--gap <pct>` (default 1.2) — how far apart two islands must be to count as separate items. **Two items came out as one sticker → lower it** (or ask for wider spacing on the sheet). **One item came out split in two → raise it** (its parts, e.g. a floating antenna or a dotted arrow, weren't bridged).
 - `--min-area <pct>` (default 0.15) — drops key speckle. There is **no maximum** — see the size note below.
 - `--preset`/`--key-color` — match the plate (default `#00FF00`). `--pad`, `--alpha-threshold`, `--output-format png|webp|gif`, `--prefix`, `--max-items`, `--keep-plate`/`--keep-sheet` behave like `cutout`'s.
+- `--sheet-mode auto|zoned|flat`, `--zones auto|off|RxC`, `--zone-cols <n>`, `--key-mode smart|flat`, `--refine` — how the plate(s) are laid out and removed. All four are explained below ("How the key actually works now").
 - Stubborn item? Fall back to one hand-measured `vidfarm mask ./sheet.png --crop x,y,w,h --flat "#00FF00"` for that one; the rest of the pack still comes from `sticker-pack`.
 
-**Pick a plate the ART doesn't use — this is the #1 way a pack comes out broken.** A chroma key removes exactly ONE color. A sticker pack of leaves, frogs, plants, money, or "eco" iconography on a GREEN plate keys holes straight through the artwork, and it looks like the cut failed when really the plate was wrong. The commands handle it two ways:
+**How the key actually works now — CONNECTIVITY, not color matching.** This is the thing to internalize, because it removes the constraint that used to force sticker art to stay flat and simple. `sticker-pack` and `cutout` do **not** delete every pixel that looks like the plate. They score each pixel's distance to its plate color, then **flood-fill inward from the edge of the sheet** through plate-ish pixels, and delete only what the fill **reaches**. Consequences, all of them useful:
 
-- **Generating?** `sticker-pack --generate` / `cutout --generate` read the subject text and move the plate off any hue it mentions — green (`#00FF00`) → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — then print which plate they chose and why. Say it back to the director when it moves: *"Your items are mostly green, so I generated them on a magenta plate."*
-- **Splitting a sheet you already have?** The plate is **detected from the sheet's four corners** (a sticker sheet always has plate in the corners), so a red/purple/blue sheet handed back from a free web generator just works with no flags.
+- **Plate-colored art survives if it's inside the item.** A green leaf on a green sheet, a `#00FF00` eye, a highlight in the plate hue — unreachable from the sheet edge, therefore not background, therefore kept. The console tells you when it mattered: *"kept 10,000 plate-colored pixels INSIDE the art that a flat key would have punched out."*
+- **Outline / line-art shapes keep their middles.** The old "rim around a see-through hole" failure is a property of the flat chromakey, not of keying. An enclosed interior can't be reached by the fill.
+- **Edges come out clean.** Boundary pixels get a real coverage estimate and the plate is **un-mixed out of each one individually** (`art = (C − (1−α)·plate)/α`, stored as straight alpha), so there's no green fringe. That's strictly better than ffmpeg's global `despill`, which rebalances every pixel and discolors plate-hued art in the interior.
+- **`--key-mode flat` brings the old behaviour back.** It's the cloud primitive's exact filter chain — use it to reproduce a cloud render bit-for-bit, or as a simple fallback.
 
-Override whenever you know better: `--key-color "#FF00FF"` or `--preset magenta` pins the plate (and turns the auto-pick off); `--no-auto-key` forces plain green. If a pack's palette collides with *every* standard plate — a rainbow icon set — split it across two sheets on two different plates rather than fighting `--tolerance`. And when a sticker is a *green* subject, never let the user generate it on green: the hand-off brief (`vidfarm handoff image`) already picks the plate for them and carries the matching `--key-color` into the follow-up command.
+What the key still can't do for you: an item whose **outer edge** is the plate color dissolves into it, and anything that **fades** into the plate (soft glow, blur, drop shadow) has no crisp silhouette to find.
 
-**Then make the ART key-safe too — CLOSED, SOLIDLY FILLED shapes.** Picking the right plate is only half of surviving the key. The other half is the failure you actually see in the wild: you ask for "sticker icons on a green plate" and the model draws **outline art** — a colored stroke with the shape's *interior left as bare plate*. On the sheet it looks perfect. After the key, the interior is gone with the background, and every sticker composites as a **rim floating around a see-through hole** (an apple that's just an apple-shaped outline, a clock with no face). Same result from three cousins: a fill that's a *near-shade* of the plate (the keyer works on tolerance, not exact match), a **translucent/glassy/glowing** material that lets the plate through, and a **soft glow or drop shadow** that fades into the plate at the edges.
+**ONE PLATE COLOR PER STICKER — `--sheet-mode zoned`.** The silhouette constraint is what "one plate per sheet" makes painful: the more items on the sheet, the more of the palette is off-limits to all of them. So stop giving the sheet one background. A **zoned** sheet is a grid of solid color **panels**, one item per panel, each panel's plate chosen against **that item**:
 
-None of that is fixable after generation — you cannot key back pixels that were never drawn. So it belongs in the **prompt**, every time:
+```
+# 6 items → a 3×2 grid of color panels, each item's plate picked against its own art
+vidfarm sticker-pack --generate "pond life, flat vector" \
+  --items "green frog,pink lotus,blue heron,white pebble,yellow reed,orange koi" \
+  --sheet-mode zoned --out-dir ./stickers
+
+# A zoned sheet from a web tool: recover the panels from the sheet's own edges
+vidfarm sticker-pack ./sheet.png --zones auto      # (this is the default)
+vidfarm sticker-pack ./sheet.png --zones 3x2       # or declare the grid you asked for
+```
+
+- The green frog sits on magenta while the pink lotus sits on green — **in the same image job**. Item art may use **any** palette, including the colors of the *other* panels.
+- Each panel is keyed independently, with its color read back off **that panel's own corners** (image models drift the exact hue they were told, so the sheet is the source of truth, not the prompt).
+- **Names stop being guessed.** On a flat sheet, `--items` is matched to items in reading order, which goes off-by-one the moment two items merge. On a zoned sheet, panel *N* holds the item you asked for in panel *N* — so the mapping is exact, and `stickers.json` records each sticker's `panel` and `plate`.
+- `--sheet-mode auto` (the default) zones a generation of 2+ named items and stays flat otherwise. `--zone-cols <n>` forces the grid width.
+
+**The FLAT one-color sheet is still first-class — reach for it with a weaker image model.** A cheap or small model will paint one background no matter how the grid is described. That's fine and fully supported:
+
+- `--sheet-mode flat` asks for the classic single-plate sheet (and `--key-mode smart` still applies, so hollow art and plate-colored interiors are still safe).
+- If you asked for zones and the model ignored them, **keying detects it and re-keys the sheet as one plate automatically** — either because a "panel" had no plate to remove, or because its item filled the panel corner to corner (so the item's own color read as the plate). It says so on the console and in `stickers.json` (`key_note`). Zoning can't strand you.
+
+**Plate color is still chosen for you on a flat sheet.** `--generate` reads the subject and moves the plate off any hue it mentions — green (`#00FF00`) → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — and prints which it chose and why; say it back to the director when it moves (*"your items are mostly green, so I generated them on a magenta plate"*). Splitting a sheet you already have, the plate is read off the sheet itself, so a red/purple/blue sheet from a free web generator just works. Pin it with `--key-color "#FF00FF"` / `--preset magenta`, or `--no-auto-key` for plain green.
+
+**Soft, painterly, furry or glassy art → `--refine`.** Every chroma key needs a crisp silhouette, so watercolor edges, fur, glow, glass and cast shadows are out of scope for the keyer no matter how clever the fill is. `--refine` handles them: the keyer's job shrinks to *locating* each item, and the item is then re-cut from the **un-keyed** sheet with the local ONNX matting model (free, ~1–2s each), which ignores color entirely and produces a genuine soft matte.
+
+```
+vidfarm sticker-pack ./painterly-sheet.png --refine --out-dir ./stickers
+```
+
+It's checked, not trusted: the matte is measured, and if it came back **empty** or **fully opaque** (the model didn't see a subject) that item keeps its keyed cut and the console says so. Flat vector art is exactly where matting fails and the chroma cut is better — so **don't use `--refine` by default**, only when the art is genuinely soft.
 
-> Every object must be a CLOSED, SOLIDLY FILLED shape — outlines and strokes must enclose an opaque fill of a different color. No outline-only, hollow, or line-art objects; never leave a shape's interior as bare background. No part of any object — fill, outline, highlight, gradient, shading or detail — may be `<PLATE HEX>` or any near-shade, tint or tone of it. No transparent, translucent, glassy, glowing or ghosted materials; every pixel of every object is fully opaque. No soft glows, blurs or drop shadows fading into the background. Keep the whole palette in strong contrast to `<PLATE HEX>`. The background must be visible ONLY around the outside of the objects, never showing through inside them.
+**What the prompt still has to ask for.** Three rules survive, and they're all about geometry rather than color:
 
-`cutout --generate`, `sticker-pack --generate`, `vidfarm handoff image`, and the `create-overlay` REST primitive all append that clause automatically with the chosen plate hex substituted in — **you only have to write it yourself when you're prompting a generator directly** (a free web tool by hand, or your own `POST /api/v1/primitives/images/generate` call). Do write it. It costs one paragraph and it is the difference between a usable pack and a re-generation.
+> Every object's OUTER EDGE must be a clearly different color from its own panel's background, and crisp — no glow, blur, mist, drop shadow or reflection fading from the object into the background. Every enclosed area must be sealed by the artwork itself, not open to the background. Keep a clear margin of plain background between objects and around the sheet edge; nothing touching, overlapping or connected.
 
-**And it's checked after the key.** `sticker-pack` and `cutout` measure, per item, the transparent area **fully enclosed by that item's own art** and report it as `hole_pct` (plus `holes`, and `hollow: true` at ≥20%) in `--json`, in `stickers.json`, and as a `⚠ N% hollow` flag on the console line. A ring, donut, picture frame or letter "O" reads the same way, so it **warns, never blocks** — the judgement is yours. When items you expected to be solid come back flagged:
+`cutout --generate`, `sticker-pack --generate`, `vidfarm handoff image` and the `create-overlay` REST primitive append the right clause for you — the relaxed one above for the smart keyer, and the strict "closed, solidly filled shapes, nothing in a near-plate shade, fully opaque" clause when `--key-mode flat` is in play. **Write it yourself only when you prompt a generator directly** (a free web tool by hand, or your own `POST /api/v1/primitives/images/generate` call).
 
-- **Re-generate the sheet** with the fill clause above spelled out. This is the fix ~90% of the time.
-- If the fill was merely *close* to the plate rather than absent, a lower `--tolerance` can rescue the sheet you already have. Nothing rescues a genuinely empty interior.
-- Last resort for one stubborn item: `vidfarm mask ./sheet.png --crop x,y,w,h` — ONNX matting doesn't care what color the fill is, so it lifts art the chroma key can't.
+**The hollow check still runs, and it means something different now.** `sticker-pack` and `cutout` measure the transparent area **fully enclosed by an item's own art** and report `hole_pct` (plus `holes`, `hollow: true` at ≥20%) in `--json`, in `stickers.json`, and as a `⚠ N% hollow` console flag. Under the smart keyer an enclosed hole **can't** have been keyed away, so a flag is usually *real* art — a ring, donut, picture frame, letter "O", or an item drawn as separate pieces with background showing between them. It warns, never blocks. If a flagged item genuinely looks wrong, the shape's fill is **open** to the background through a gap in its outline; ask the prompt for sealed shapes. Last resort for one stubborn item: `vidfarm mask ./sheet.png --crop x,y,w,h` — ONNX matting doesn't care what color anything is.
 
 **Generation is the failure point, not the cutting.** The sheet prompt is auto-appended with the important instruction — *every item fully separated by clear plate-colored background, nothing touching or overlapping, wide margins, no text, no shadows, one consistent style* — because **touching items segment as one sticker**. If a pack comes back merged, re-run the generation asking for more spacing before you fight the `--gap` knob.