@officexapp/vidfarm-devcli 0.21.34 → 0.21.36

package/.agents/skills/vidfarm/{regimes/short-form.QA_REGIME.md → harnesses/short-form.HARNESS.md}

@@ -1,6 +1,6 @@
 ---
 name: short-form
-video_type: general short-form social video (TikTok / Reels / Shorts) — the default base regime
+video_type: general short-form social video (TikTok / Reels / Shorts) — the default base harness
 checks:
   duration_sec: 8-90
   aspect: 9:16
@@ -11,16 +11,19 @@ checks:
   font_regime: required
   max_text_cards: 3
   max_simultaneous_text: 2
+  max_words_per_cue: 12
+  max_dead_air_sec: 2.5
+  max_tail_sec: 1.5
   max_scene_sec: 8
 ---
 
-# Short-Form QA Regime
+# Short-Form Harness
 
-The default base. Start here, copy it next to your work, then **delete what doesn't apply and add what makes your format yours** — a regime you didn't edit is a regime that isn't about your videos.
+The default base. Start here, copy it next to your work, then **delete what doesn't apply and add what makes your format yours** — a harness you didn't edit is a harness that isn't about your videos.
 
 > **Part I** is the anatomy: the four charges that decide whether a video travels.
 > **Part II** is the rules that keep it credible.
-> Run the pre-flight checklist before you build, and `vidfarm qa <dir> --regime ./QA_REGIME.md` before you publish. An unchecked box is a rewrite, not a fix in the edit.
+> Run the pre-flight checklist before you build, and `vidfarm qa <dir> --harness ./HARNESS.md` before you publish. An unchecked box is a rewrite, not a fix in the edit.
 
 ## Part 0 — who this is for (fill this in yourself)
 
@@ -57,7 +60,7 @@ Three seconds, not five. The decision is made before you finish the first senten
 
 **Banned openings:** throat-clearing ("Hey guys", "So I wanted to talk about…") · a logo, title card, fade from black, or a beat of silence · any sentence whose subject arrives in the second half · context before the claim (context is beat 2).
 
-⚠️ **Frame 0 is the hook AND the thumbnail.** No black open, no fade, subject in frame, caption already legible. See the `hooks` regime for the full chunk-1 craft.
+⚠️ **Frame 0 is the hook AND the thumbnail.** No black open, no fade, subject in frame, caption already legible. See the `hooks` harness for the full chunk-1 craft.
 
 ### 🔄 Curiosity loop — retention
 
@@ -84,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
 
@@ -94,10 +97,20 @@ Not an accessibility afterthought: captions are how the hook, the loop, and the
 
 - **Verbatim, every word.** Paraphrased captions desync from the voice and read as fake.
 - **Weight 700–900, inside the 8–85% safe zone.** Below 700 disappears against footage.
-- **One to three words per line, one line at a time.** A block of full sentences doesn't get read.
+- **One to three words per line, one line at a time.** A block of full sentences doesn't get read. Long narration is paged into 3–5-word kinetic cues (`captions generate --style word-pop|spotlight`), never held as one static block.
+- **Placed in the quietest region of the frame**, measured off a still — not dropped on the default lower third.
 - **Cards are timed text over footage** — never a card UI, table, chip row, or frosted panel (`vidfarm qa` flags those as slop).
 - **Max ~3 standalone cards per video:** one for the loop, one for the payoff, one for the bait.
 
+#### Caption PLACEMENT is measured off the frame, before styling is decided
+
+The safe zone (8–85%) says where text is *allowed*; it does not say where text *belongs*. Inside that band, the caption goes in the region of the frame with the least competing for attention — and that region is found by looking at a frame, not by defaulting to `y:70`.
+
+- **Grab the frame and read it.** `vidfarm stills <dir> --at <t>` is free. Split the safe band into thirds and ask which one is quietest: open sky, a blank wall, a defocused background, an empty tabletop, dead space above or below the subject. That third gets the words.
+- **A caption over the busy third is a self-inflicted wound.** It collides with the subject, so it needs a plate to survive, so the plate becomes a bright slab, so the frame now has two things fighting instead of one. Moving the text 40% up the frame solves all three at once. Nothing else on screen competing → the placement is purely a legibility choice, so make it the *readable* one.
+- **Placement decides the plate, not the other way round.** Choose the position first, then measure the band you actually chose (below). Empty sky measures calm → no plate. Reaching for treatment 4 before you've tried moving the text is the mistake.
+- **Size is part of placement.** A line that runs frame-edge to frame-edge has no placement left to choose. If the words don't fit in the quiet region at ~36–64px, cut words or shrink the type — don't widen the box.
+
 #### Caption styling is MEASURED off the background, never hardcoded
 
 A white rounded caption plate copied from another video onto a near-black stage is a bright slab the design never asked for — it dominates the frame and reads as a UI element pasted over the video. So measure what is actually behind the caption band, then pick one of three treatments:
@@ -121,6 +134,18 @@ The mechanical fix: compare each caption phrase against the words on screen in t
 
 ## Part II — the rules
 
+### Rule 0 — every second earns its place, or it gets cut
+
+The thumb re-decides continuously; a second carrying nothing is a free exit. Assume the first assembly is **30–50% too long** and go find the seconds — agents write videos like prose (wind-up, restatement, tidy conclusion) and every one of those habits is a hole in the retention curve.
+
+- **The deletion test, on every beat:** delete it — does the video still make sense and does the payoff still land? Then it stays deleted. Anything that survives must serve one of the four charges; "it gives context" is not a charge.
+- **Cut on sight:** intros/logo stings, the wind-up sentence before the claim, restatement, inter-sentence silence over ~0.35s, real-time process, establishing shots, reading what's already on screen, the outro tail, and filler pans that exist because a clip was short.
+- **Always ripple the hole closed** (`vidfarm ripple <dir> --at <sec> --delta -<sec>`) — a cut that leaves a gap converts fluff into dead air, which is worse.
+- **Density is not speed.** The held comedic beat, the payoff playing out, and a cue's readability keep their seconds. Cut *words*, never the time text needs to be read.
+- **Length is an output.** Build the charges, cut, and ship whatever's left. A brief that dictates a duration ordered fluff.
+
+Machine half: `max_dead_air_sec` / `max_tail_sec` / `max_scene_sec` above, plus `vidfarm qa`'s `dead-air`, `dead-tail`, `slow-scene`. Craft: `references/hooks-and-virality.md` → "Density".
+
 ### Rule 1 — every video is standalone. There is no part two.
 
 A viewer arriving mid-scroll with zero context must get a complete, useful video. **You do not control the order** — your video 12 is most people's video 1, and if one breaks out it breaks out *alone*. A cross-video cliffhanger converts your one winner into a dead end. Sharing an angle, a look, or a set of beliefs across the catalog is the strategy; *dependency* is what's banned. Test: hand it to someone who knows nothing — "wait, what is this?" and "where's the rest?" are both failures.
@@ -155,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
@@ -168,9 +193,13 @@ Verbatim captions in the font regime and the safe zone · frame 0 works as hook
 
 **Production**
 - [ ] Verbatim captions, weight 700–900, safe zone, one line at a time
+- [ ] Caption position was chosen off an actual still — it sits in the quietest region of the frame, not on top of the subject, and no line runs edge-to-edge
+- [ ] Anything longer than a phrase is paged into kinetic cues rather than held as a static block
 - [ ] Caption colour / active colour / plate were chosen by measuring the composited background behind the band, not copied from another video
 - [ ] One caption treatment for the whole video, and the active-word colour is readable on it
 - [ ] No caption repeats the words already on screen in that scene (≥60% overlap → drop the caption)
+- [ ] The deletion test was actually run: name the beat you cut, or why nothing could go
+- [ ] No stretch of the video is there to fill time — no intro, no wind-up, no restatement, no tail after the last word
 - [ ] ≤3 standalone cards, no slop furniture, `vidfarm qa` otherwise clean
 - [ ] In a batch: this variant differs from its siblings by more than one noun
 
@@ -191,4 +220,4 @@ Verbatim captions in the font regime and the safe zone · frame 0 works as hook
 | Good retention, no comments | 🎣 Bait | No ask, or the ask was "thoughts?" |
 | Comments, but hostile | 🎣 Bait | Ragebait or an over-claim |
 
-**Vary one charge at a time.** A batch where everything changed at once teaches you nothing — which is the entire point of running scripting mode against a regime instead of just generating volume.
+**Vary one charge at a time.** A batch where everything changed at once teaches you nothing — which is the entire point of running scripting mode against a harness instead of just generating volume.

package/.agents/skills/vidfarm/{regimes/ugc-testimonial.QA_REGIME.md → harnesses/ugc-testimonial.HARNESS.md}

@@ -13,9 +13,9 @@ checks:
   max_simultaneous_text: 1
 ---
 
-# UGC / Testimonial QA Regime
+# UGC / Testimonial Harness
 
-For the format where a person talks to camera about a product they use. The entire value of the format is that it **doesn't look produced** — so most of this regime is about what NOT to add.
+For the format where a person talks to camera about a product they use. The entire value of the format is that it **doesn't look produced** — so most of this harness is about what NOT to add.
 
 ## The one test
 
@@ -33,7 +33,7 @@ If the answer needs the brand's permission, budget, or logo, it isn't UGC — it
 | **Honest limit** | before the close | What it doesn't do / who it isn't for. **The credibility beat** |
 | **Close** | final beat | What they'd tell a friend. Not a CTA read |
 
-**The product enters second, never first.** A testimonial that opens on the product is a commercial. It opens on the *situation* — and situations are also what survives a cold algorithm (see the `hooks` regime).
+**The product enters second, never first.** A testimonial that opens on the product is a commercial. It opens on the *situation* — and situations are also what survives a cold algorithm (see the `hooks` harness).
 
 ## Rules
 

package/.agents/skills/vidfarm/recipes/{bulk-scripting-with-a-regime.md → bulk-scripting-with-a-harness.md}

@@ -1,12 +1,12 @@
-## Recipe: Bulk Video Generation (Scripting Mode) with a QA_REGIME.md
+## Recipe: Bulk Video Generation (Scripting Mode) with a HARNESS.md
 
 Use this when the director wants **volume** — daily posting, hook tests, one video per clip in a pool, N variants of a template. Ask first if you're not sure: *"One video, or should we set this up as a repeatable batch?"* If they want volume, this is the shape.
 
-The thing that makes bulk work is not the loop — loops are easy. It's that **nobody is going to watch variant #37 as carefully as variant #1**, so the standard has to be written down before the loop runs. That's the `QA_REGIME.md`.
+The thing that makes bulk work is not the loop — loops are easy. It's that **nobody is going to watch variant #37 as carefully as variant #1**, so the standard has to be written down before the loop runs. That's the `HARNESS.md`.
 
 ### 0. Read the craft harness first
 
-`references/hooks-and-virality.md` — the four charges (hook / loop / payoff / bait), the three gates, and the anti-patterns that only bite at volume. Two of them decide whether this batch is worth running at all: **a different noun is not a different hook** (twenty variants of one sentence with the nouns swapped is one video), and **never point a generator at your grader** (a model writing hooks scored by the same model converges on the rubric, not on what works — scores climb, nothing improves). The regime catches defects; it does not rank winners.
+`references/hooks-and-virality.md` — the four charges (hook / loop / payoff / bait), the three gates, and the anti-patterns that only bite at volume. Two of them decide whether this batch is worth running at all: **a different noun is not a different hook** (twenty variants of one sentence with the nouns swapped is one video), and **never point a generator at your grader** (a model writing hooks scored by the same model converges on the rubric, not on what works — scores climb, nothing improves). The harness catches defects; it does not rank winners.
 
 ### 1. Agree the variant axis — before any code
 
@@ -20,14 +20,22 @@ vidfarm pull <forkId> --dir ./work        # one canonical base fork per batch
 
 Read `./work/.harness/agent-guide.md` first, as always.
 
-### 3. Install and EDIT the regime
+### 3. Install and EDIT the harness
+
+Two ways in, depending on where the format came from:
 
 ```bash
-vidfarm regime list                                        # short-form | hooks | ugc-testimonial | explainer | product-demo
-vidfarm regime init hooks --out ./work/QA_REGIME.md
+# (a) From a bundled base — when the format is one you're defining
+vidfarm harness list                                    # short-form | hooks | ugc-testimonial | explainer | product-demo
+vidfarm harness init hooks --out ./work/HARNESS.md
+
+# (b) From the template you're batching — when the format is one you're REPLICATING
+vidfarm harness derive <forkId> --out ./work/HARNESS.md # the decomposition, as a harness
 ```
 
-Then **edit it with the director**. The bundled file is a starting point; the parts that matter are the ones they add — who the viewer is, their banned vocabulary, the compliance line, the pacing this account actually uses. A regime nobody edited isn't about their videos. Existing regime somewhere else on disk? Just point at it: `--regime ./brand/HOUSE_RULES.md`. They stack.
+(b) is what a director means by *"give me the harness for this template_id"*: the decompose pass already extracted the template's viral / visual / structural / audio / build DNA, and `derive` folds those strands into the same editable Markdown a bundled base produces. If the fork was never decomposed, run `vidfarm decompose` first.
+
+Either way, **edit it with the director**. The generated file is a starting point; the parts that matter are the ones they add — who the viewer is, their banned vocabulary, the compliance line, the pacing this account actually uses. A harness nobody edited isn't about their videos. A *derived* harness has the extra failure mode of sounding authoritative: it was written by a model that watched one video, so its "unknown" lines and its confident-but-wrong lines both need a human pass. Existing harness somewhere else on disk? Just point at it: `--harness ./brand/HOUSE_RULES.md`. They stack.
 
 ### 4. Source the N cheaply
 
@@ -38,13 +46,13 @@ vidfarm public-raws --category scroll-stoppers --limit 20 --json > pool.json
 
 A curated shelf is a pre-tagged, free, already-hosted clip pool — the cheapest way to get N distinct variants without N downloads or N generation calls.
 
-### 5. Loop: edit → QA against the regime → render
+### 5. Loop: edit → QA against the harness → render
 
 ```bash
 for VARIANT in "${VARIANTS[@]}"; do
   SLUG="$(echo "$VARIANT" | tr ' ' '-' | cut -c1-40)"
   vidfarm set-text ./work --layer hook --text "$VARIANT"
-  vidfarm qa ./work --json > "qa/$SLUG.json"               # ./work/QA_REGIME.md auto-discovered
+  vidfarm qa ./work --json > "qa/$SLUG.json"               # ./work/HARNESS.md auto-discovered
   jq -e '.ok' "qa/$SLUG.json" >/dev/null || { echo "skipped $SLUG"; continue; }
   vidfarm render "$FORK_ID" --dir ./work --out "renders/$SLUG.mp4" --tracer "batch-$SLUG"
 done
@@ -81,11 +89,11 @@ Read the sheets. In a batch you're looking for two different things: **per-video
 
 ### 6. Answer the review items — don't skip this
 
-The regime's `- [ ]` checklist comes back on every run because the CLI *can't* settle it. Machine checks catch a 13-word hook or a black first frame; only you can answer "is this variant genuinely different from its siblings?" or "can the viewer guess the withheld answer?" **Report both halves honestly**: what the machine checked, and what you judged. A batch report claiming a clean pass on the judgment half is worse than no report.
+The harness's `- [ ]` checklist comes back on every run because the CLI *can't* settle it. Machine checks catch a 13-word hook or a black first frame; only you can answer "is this variant genuinely different from its siblings?" or "can the viewer guess the withheld answer?" **Report both halves honestly**: what the machine checked, and what you judged. A batch report claiming a clean pass on the judgment half is worse than no report.
 
-### 7. Feed what you learn back into the regime
+### 7. Feed what you learn back into the harness
 
-When the director says "the label-framed hooks all died" or "anything over 30s tanked", write it into `QA_REGIME.md` as a rule or a checklist line — with the reason attached, so the next agent doesn't argue it away. The compositions are disposable; **the regime is the artifact that compounds across batches.**
+When the director says "the label-framed hooks all died" or "anything over 30s tanked", write it into `HARNESS.md` as a rule or a checklist line — with the reason attached, so the next agent doesn't argue it away. The compositions are disposable; **the harness is the artifact that compounds across batches.**
 
 ### Cost note
 

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

@@ -16,7 +16,7 @@ The mechanical trio — **generate on a chroma plate → key it out → trim to
   ```
   One accent color for the active word, everything else near-black. No outline/stroke, no drop shadow, no pill — those exist to survive busy footage and just add noise on white.
 
-  **Those hexes are the answer for a white stage, not the answer.** They are one instance of a general rule: **caption color, active-word color and plate are chosen by MEASURING the background behind the caption band, never by taste or habit.** On a near-black stage the same flags ship a bright plate the design never asked for and an active word nobody can read. The measurement procedure and the three treatments live in `regimes/short-form.QA_REGIME.md` → "Caption styling is measured off the background" — read it before you copy the line above onto anything that isn't white.
+  **Those hexes are the answer for a white stage, not the answer.** They are one instance of a general rule: **caption color, active-word color and plate are chosen by MEASURING the background behind the caption band, never by taste or habit.** On a near-black stage the same flags ship a bright plate the design never asked for and an active word nobody can read. The measurement procedure and the three treatments live in `harnesses/short-form.HARNESS.md` → "Caption styling is measured off the background" — read it before you copy the line above onto anything that isn't white.
 - **Female TTS narration.** Default to a warm, friendly **female** voice and say which one you picked: local-first `vidfarm tts "<script>" --voice coral` (OpenAI — `nova` if the script wants more energy, `sage` for calmer), `--voice Kore` or `Leda` on Gemini, or `vidfarm voices` → `vidfarm tts --cloud --voice <voice_id>` on ElevenLabs. Tell the director they can swap it in one flag.
 - **Clean and simple wins.** One idea on screen at a time. Two or three cutouts per beat, not eight. Generous white space, one accent color, one font. When in doubt, remove an element rather than add one.
 
@@ -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/recipes/local-edit-render-approve.md

@@ -7,7 +7,7 @@ Use this when a coding agent is doing the work locally or the user wants a repro
 3. Read `./work/.harness/agent-guide.md` and `./work/.harness/context.json` before editing.
 4. Make deterministic edits to `composition.html` and optionally `composition.json`.
 5. Validate with `vidfarm lint` or `vidfarm stills` when useful. **Always look at `vidfarm stills ./work --at 0`** — that frame becomes the thumbnail, so it must not be black, empty, or mid-fade.
-6. **QA before you render: `vidfarm qa ./work`.** Free, instant, devcli-only. It blocklists HTML slop (CTA buttons, benefit chip rows, a lone pill around a static stat/label, frosted cards, gradient text, web-page classes/fonts), checks the caption font regime + safe zone, and flags a blank/fading first frame (the thumbnail). Feedback only — exit 0 even on findings, never automatic — but it catches the #1 tell of an agent-made video, so run it on every production. Fix what's real, ignore what's a deliberate style call, then render.
+6. **QA before you render: `vidfarm qa ./work`.** Free, instant, devcli-only. It blocklists HTML slop (CTA buttons, benefit chip rows, a lone pill around a static stat/label, frosted cards, gradient text, web-page classes/fonts), checks the caption font regime + safe zone, flags oversized captions and static walls of text, and flags a blank/fading first frame (the thumbnail). It cannot see pixels, so *where in the frame* the caption sits is still on you — which is why every run ends with a **`▶ NOW WATCH THE VIDEO`** block: render, `vidfarm stills ./work --sheet`, open the contact sheet, and judge each caption against its actual picture. Do that before you report the video as done. Feedback only — exit 0 even on findings, never automatic — but it catches the #1 tell of an agent-made video, so run it on every production. Fix what's real, ignore what's a deliberate style call, then render.
 7. Render with `vidfarm render <forkId> --dir ./work --wait`.
 7b. **Review the render as a whole before you approve — this is the step that most changes quality.** `vidfarm qa` and `lint` are static checks on the DOM; neither can see the video. Tile ~12 stills into one contact sheet and read it as an image — `vidfarm stills ./work --sheet` does both in one command (add `--at 0,2,4,…` to pick the timestamps): consistent margins, one type scale, one accent colour, deliberate pacing, no jarring join, no dead band under top-anchored content, end card settled ≥2s before the last frame. Compare frames from two different scenes — a frozen render (overlay pass without `-loop 1`, assets outside the composition root) passes duration, frame-count and audio-hash checks while every frame is identical. Check the mix by measurement, not by ear. Full method + the six most common defects: `references/reviewing-renders.md`.
 8. **Ask about deduplication before you approve** — "is this going out more than once (several accounts, another platform, a re-post later)?" If yes, run `vidfarm dedupe ./final.mp4 [--variants N]` on the **exported** MP4 (free, local ffmpeg, no re-render) and approve each variant separately. Asking here rather than after publication is what avoids paying for a second render. See `references/core-workflows.md` → *Deduplicate before you publish*.