@officexapp/vidfarm-devcli 0.21.34 → 0.21.36

package/dist/src/cli.js

@@ -19,15 +19,17 @@ import { formatCompositionLintIssues, lintCompositionHtml } from "./services/com
 import { resolveFfmpeg } from "./services/clip-curation/ffmpeg.js";
 import { parseHyperframesJson, runHyperframesCommand } from "./devcli/hyperframes-cli.js";
 import { renderCompositionStills } from "./devcli/stills.js";
-import { extractCompositionFacts, formatQaReport, qaCompositionHtml } from "./devcli/qa-check.js";
-import { discoverRegime, formatRegimeReport, listBuiltinRegimes, loadAndEvaluateRegime, mergeRegimeIntoReport, parseRegime, resolveRegimePath } from "./devcli/qa-regime.js";
+import { extractCompositionFacts, formatQaReport, formatWatchTheVideoNotice, qaCompositionHtml, watchTheVideoDirective } from "./devcli/qa-check.js";
+import { HARNESS_FILENAME, discoverHarness, formatHarnessReport, isLegacyHarnessFilename, listBuiltinHarnesses, loadAndEvaluateHarness, mergeHarnessIntoReport, parseHarness, resolveHarnessPath } from "./devcli/harness.js";
 import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders, cropImageRegion } from "./devcli/greenscreen-local.js";
 import { dedupeMediaLocal, localDedupeAvailable, defaultDedupeOutPath, describeLocalDedupe, DEDUPE_PRESETS, DEDUPE_DEFAULT_PRESET, isDedupePresetName } from "./devcli/dedupe-local.js";
-import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor, keySafeArtInstruction, analyzeKeyedArt, HOLE_WARN_PCT } from "./devcli/sticker-pack.js";
+import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor, keySafeArtInstruction, connectivitySafeArtInstruction, analyzeKeyedArt, measureOpaqueShare, HOLE_WARN_PCT } from "./devcli/sticker-pack.js";
+import { smartKeyPlate, planZonedSheet, zonedSheetInstruction } from "./devcli/plate-key.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
 import { runSkillsCommand } from "./devcli/skills.js";
+import { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, readPackDoc, searchPackDocs } from "./devcli/skill-docs.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError, localApiRequest } from "./devcli/local-backend.js";
 import { startLocalFrontendServer, serveShellsPresent } from "./devcli/local-frontend-server.js";
@@ -320,6 +322,10 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --media-type <k>        Force image|video instead of auto-detecting
     --tolerance <0..1>      Key radius (default 0.3); --softness <0..1> edge feather (0.1)
     --no-despill            Skip edge color-fringe suppression
+    --smart                 IMAGE only: key by border-connected fill instead of by
+                            color alone, so plate-colored detail inside the subject
+                            and hollow/outline art survive (what cutout and
+                            sticker-pack do by default). Local only
     --output-format <f>     Image only: png|webp
     --gif                   Write a TRANSPARENT GIF instead (animated for a clip)
                             — local only, 1-bit alpha, for GIF-only sticker surfaces
@@ -372,21 +378,25 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             default: --generate moves the plate off any hue the subject
                             mentions; an existing file's plate is read from its corners.
                             --no-auto-key forces plain green.
+    --key-mode smart|flat   smart (default): flood-fill the plate in from the frame
+                            edge, so plate-colored detail inside the subject and
+                            hollow/outline art survive and the edge is feathered +
+                            de-spilled per pixel. flat: the plain ffmpeg chromakey
     --pad <px>              Keep N px of transparent breathing room around the cutout
     --alpha-threshold <n>   Alpha 0..255 below which edges count as empty (default 8)
     --no-trim               Key only; don't shrink to the bounding box
     --output-format png|webp   Cutout format (default png)
     --keep-plate <file>     Also save the pre-key generated plate (with --generate)
     --out <file>            Write the cutout here (default <source>.cutout.png)
-  sticker-pack [sheet|url]  Make a whole STICKER PACK from ONE greenscreen sheet:
-                            key the flat plate once, auto-find each item in the
-                            alpha channel, and cut every one into its own snug
+  sticker-pack [sheet|url]  Make a whole STICKER PACK from ONE sheet: key the
+                            plate(s) once, auto-find each item in the alpha
+                            channel, and cut every one into its own snug
                             transparent file (+ stickers.json). One image job for
                             the set = one art style, ~1/N the cost of N cutouts.
                             Items may be any size, from an icon to a full-frame
-                            landscape. Prompts for key-safe art (solid fills, no
-                            outline-only/hollow shapes, nothing in a near-plate
-                            shade) and flags any item that came out hollow.
+                            landscape. Keys by CONNECTIVITY, so plate-colored
+                            detail inside an item and hollow/outline shapes
+                            survive, and edges come out feathered + de-spilled.
                             Local, free, ffmpeg-only. Image-only.
                             (aliases: stickers, sticker-sheet)
     --generate "<theme>"    AI-generate the sheet first (ONE billed image job for
@@ -398,6 +408,30 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             art can't collide with (green art → magenta plate, etc.);
                             splitting an existing sheet detects the plate from its
                             corners. --no-auto-key forces plain green. (--flat too)
+    --sheet-mode <m>        auto (default) | zoned | flat. ZONED asks the model for a
+                            grid of color PANELS — one item per panel, each panel's
+                            plate picked against that item — so a green frog and a
+                            pink flower can share a sheet, item art can use ANY
+                            palette, and names are pinned to panels instead of guessed
+                            from reading order. auto = zoned when generating 2+ named
+                            items. FLAT is the classic one-color sheet: use it for a
+                            weaker image model that can't follow a color-block grid
+                            (if a model ignores the grid, keying detects that and
+                            falls back to a flat plate on its own)
+    --zones auto|off|RxC    How to read panels off a sheet at key time (default auto:
+                            recover the grid from the sheet's own edges, else one
+                            plate). Pass RxC for a sheet you know the layout of
+    --zone-cols <n>         Force the panel grid's column count when planning a
+                            zoned generation
+    --key-mode smart|flat   smart (default): flood-fill the plate inward from the
+                            sheet edge, so only background that REACHES the edge is
+                            deleted. flat: the plain ffmpeg chromakey (deletes the key
+                            color wherever it appears) — the simple fallback, and the
+                            way to match a cloud render exactly
+    --refine                Re-cut every item with the local ONNX matting model
+                            (free, ~1-2s each) instead of the chroma cut — the path
+                            for painterly, soft-edged, furry or glassy art. Falls
+                            back to the keyed cut per item when the matte looks wrong
     --dry-run               Just list the detected crop boxes; write nothing
     --gap <pct>             Merge islands closer than this % of the sheet's short
                             side into ONE item (default 1.2) — raise it to rejoin a
@@ -612,7 +646,18 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
     --out <file>              Output mp3 path (default music-<id>.mp3)
     --own-key                 Use your own ElevenLabs key instead of the platform key + wallet
                               (default: platform ElevenLabs, wallet-billed) → POST /api/v1/primitives/music/generate
-  voices                    List ElevenLabs voices for TTS (voice_id + name + labels).
+  voices                    Browse + SAMPLE narration voices (voice_id + name + labels + preview).
+                            Default roster = the premium ElevenLabs catalog reached through
+                            VIDFARM'S OWN ElevenLabs connection: no ElevenLabs account, API key,
+                            or subscription needed — narration on these runs on the platform key
+                            and is billed as vidfarm wallet credits (pennies per narration).
+    --sample                  Write listenable samples to ./voice-samples so a human can CHOOSE by
+                              ear. FREE on both tiers (premium = ElevenLabs' own preview clips,
+                              free = rendered locally) — safe even in cost mode minimize.
+    --sample-count <n>        How many to sample (default 6)
+    --sample-out <dir> | --sample-text "<line>"
+    --search "<text>"         Filter by name/labels/description (e.g. "british narrator")
+    --free                    List the $0 local Kokoro voices instead (--all lists both rosters)
     --own-key                 List voices on your own saved ElevenLabs key (default: platform account)
     --limit <n> | --json      Show more / raw JSON
   stt <file|url>            Video or audio → transcript (alias: transcribe).  LOCAL: local ffmpeg demux +
@@ -716,21 +761,32 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
                             Feedback only: exits 0 even when it finds slop,
                             and it never runs automatically. Blocklist, not
                             allowlist — unusual styles pass untouched
-    --regime <name|path>      Grade against a QA_REGIME.md too (repeatable —
+    --harness <name|path>     Grade against a HARNESS.md too (repeatable —
                               they stack). A built-in name or ANY file path.
-                              <dir>/QA_REGIME.md is picked up automatically
-    --no-regime               Skip QA_REGIME.md auto-discovery
+                              <dir>/HARNESS.md is picked up automatically
+    --no-harness              Skip HARNESS.md auto-discovery
     --json                    Machine-readable findings (rule/severity/fix)
     --strict                  Also exit 1 when slop is found (for CI)
-  regime list|show|init       QA_REGIME.md — the per-style quality contract   (local, devcli-only)
-                            you own, for bulk/scripting mode. Built-ins:
-                            short-form, hooks, ugc-testimonial, explainer,
-                            product-demo
-    regime list [--json]              What ships with the CLI
-    regime show <name|path>           Print one
-    regime init <name> [--out <path>] Copy it next to your work, then EDIT it
-                                      (default ./QA_REGIME.md; --dir <d> to
-                                      write <d>/QA_REGIME.md)
+  harness <sub>               HARNESS.md — the reusable AI harness for ONE     (local, devcli-only)
+                            format or template: what makes it special,
+                            written down so an agent can reproduce it.
+                            "create me a harness" / "update the harness for
+                            this format" / "give me the harness for this
+                            template_id" all land here
+    harness list [--json]             Bundled starting points: short-form,
+                                      hooks, ugc-testimonial, explainer,
+                                      product-demo
+    harness show <name|path>          Print one [--dna <strand>] to print just
+                                      one strand (viral_dna, visual_dna, …)
+    harness init <name> [--out <p>]   Copy one next to your work, then EDIT it
+                                      (default ./HARNESS.md; --dir <d> to
+                                      write <d>/HARNESS.md)
+    harness derive <forkId|dir>       DECOMPOSITION → HARNESS.md. Distils a
+                                      decomposed template's viral/visual/
+                                      structural/audio/build DNA into an
+                                      editable harness [--out <p>] [--force]
+    harness check <dir>               Grade a composition against its harness
+                                      (same engine as vidfarm qa)
   stills <dir|composition.html>   Render PNG stills of the CURRENT        (local in-process render)
                             composition — the visual self-check loop
                             ("did my edit look right") without a full render
@@ -800,13 +856,27 @@ Account:
   provider-keys             List saved AI provider keys                  → GET  /api/v1/user/me/provider-keys
   add-provider-key <provider> <secret>   Save an AI provider key         → POST /api/v1/user/me/provider-keys
 
-Agent skill (install the latest director skill so your AI agent can act):
+Agent skill (the director knowledge — a full copy SHIPS INSIDE this CLI):
+  skill ls                  List every file in the bundled pack, with sizes  (local — offline, no account)
+  skill show <path>         Print one file. Shorthand works: \`skill show
+                            primitives\`, \`skill show harnesses/README.md\`
+  skill search "<term>"     Grep all of it — the fastest way to find the one
+                            paragraph you need without loading a whole file
+    --limit <n>               Max matches (default 40)
+  skill path                Where the bundled pack lives on disk
+  skill --print             Print the single-file director rollup (bundled
+                            copy; --remote for the host's latest)
+                            NOTE: the bundled pack is pinned to THIS CLI
+                            version — the pairing that actually works. It is
+                            documentation, not entitlement: the free-local
+                            half (clips, hyperframes, serve render, qa,
+                            harnesses, dedupe, local TTS) runs offline, while
+                            AI generation, hosted render, recycle, download
+                            and marketplace still need login + network.
   update-skill              DEPRECATED installer alias; installs the canonical
                             multi-file vidfarm pack via \`skills add\`.
                             Use \`vidfarm skills add vidfarm\` directly.
     --dir <path>            Project root for the canonical pack install
-    --print                 Print the generated single-file director rollup
-                            (copy/share artifact; not the canonical install)
 
 Files (multi-step flows the devcli handles for you):
   upload <file>             Upload to the EPHEMERAL temp store, print URL → presign + S3 PUT + finalize
@@ -1388,9 +1458,13 @@ async function main() {
         case "slop-check":
             await runQaCommand(rest);
             return;
+        case "harness":
+        case "harnesses":
+        // `regime` is the pre-rename name. Kept as a silent alias so old scripts
+        // and old skill copies keep working; every surface says "harness" now.
         case "regime":
         case "regimes":
-            await runRegimeCommand(rest);
+            await runHarnessCommand(rest);
             return;
         case "stills":
             await runStillsCommand(rest);
@@ -2396,10 +2470,10 @@ Rules:
 - For replacement graphics, screenshots, or still-like scenes, prefer AI image generation plus Ken Burns before paying for AI video unless static_vs_pivot says motion footage is load-bearing.
 - If narration must be customized, default to premium ElevenLabs first, then the user's own ElevenLabs path, then BYOK OpenAI/Gemini/OpenRouter. If captions or scenes were timed to the old VO, retime them to the new narration.
 - NO HTML SLOP. You are editing HTML, but the output is a social video, not a web page. THE TEST IS THE NATIVE-EDITOR TEST: could you have made this element with the tools inside TikTok's own editor? That toolset is a font, a color, a stroke/outline, a soft shadow, a tight text box, alignment, opacity, rotation, animation presets — plus stickers, emoji, drawn marks and clips. It has NO padded capsule, NO border, NO gradient fill, NO blur panel, NO card. If you reached past it, cut it. Never author landing-page furniture: CTA "buttons" (a filled/gradient rounded capsule with action copy like "Sign Up for a Free Trial →"), benefit chip/badge rows ("✓ No Credit Card Needed"), bordered/shadowed/frosted cards holding a headline + URL, gradient text fills, feature grids, bulleted lists, or web-default fonts (Inter/Roboto/Arial/system-ui). AND NOT A SINGLE PILL EITHER: one lonely rounded, padded, filled capsule around a static stat or label — "10 hrs / week", "STEP 2", "EP.01", "+40%" — is a web badge, and being the only one on screen does not make it native. The ONLY legitimate capsule in a video is the active-word spotlight/karaoke caption highlight, because it moves with the spoken word. Emphasize a stat the way the editor would: bigger, heavier, ALL-CAPS, an accent color, a hand-drawn circle or underline, or its own beat on screen. Rule of thumb on anything holding words: border-radius over ~8px PLUS a background fill PLUS padding = a badge; drop the fill or drop the radius until the band hugs the glyphs. None of this appears in a real TikTok, and nothing in a video is clickable — say it as timed text on the footage instead. Arrows, scribble/underline marks, italics, ALL-CAPS, single-word color pops, emoji, transparent cut-out stickers, and mock social UI (iMessage bubbles, comment cards) are all fine. Captions use an imported family (Montserrat default / TikTok Sans / Abel / Source Code Pro / Yesteryear) at weight 700-900, ~36-64px on a 1080-wide frame, inside the 8%-85% safe zone, with exactly one of four backgrounds: outline, plain, an active-word spotlight/karaoke pill, or a tight-hugging solid band (radius <=8px, no border/shadow/gradient/blur).
-- STRUCTURE BEFORE POLISH — THE FOUR CHARGES, WRITTEN BEFORE YOU TOUCH THE TIMELINE. Most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) HOOK — write the opening line as text first: a complete clause (subject + verb), no jargon, naming a SITUATION ("I've quit six businesses") not a label ("anonymity"); it goes on screen at start:0, because caption chunk 1 is read before any audio and muted autoplay is the default. Banned openings: throat-clearing ("so I was thinking", "here's the thing"), a logo, a title card, a fade from black, context before the claim. (2) LOOP — one open question by 0:10, said ON SCREEN, closing INSIDE this video (state the timestamp it closes at; if you can't, there is no loop), and the withheld answer must be one the viewer CANNOT supply themselves — a formally-correct loop with a guessable answer passes every mechanical check and dies in the field. (3) PAYOFF — shown, not summarized, ≥5 uninterrupted seconds, landing BEFORE the final beat; the payoff is not the CTA. (4) BAIT — one ask in the final beat and in the post caption; never a DM funnel, "follow for part two", or ragebait. Then build the timeline. Re-theming a decomposed template: viral_dna already names the source's hook/retention/payoff — rebuild each charge for the new subject, never flatten the loop into a product statement. Full craft harness: the vidfarm skill's references/hooks-and-virality.md. Checkable form: \`vidfarm regime show hooks\`.
+- STRUCTURE BEFORE POLISH — THE FOUR CHARGES, WRITTEN BEFORE YOU TOUCH THE TIMELINE. Most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) HOOK — write the opening line as text first: a complete clause (subject + verb), no jargon, naming a SITUATION ("I've quit six businesses") not a label ("anonymity"); it goes on screen at start:0, because caption chunk 1 is read before any audio and muted autoplay is the default. Banned openings: throat-clearing ("so I was thinking", "here's the thing"), a logo, a title card, a fade from black, context before the claim. (2) LOOP — one open question by 0:10, said ON SCREEN, closing INSIDE this video (state the timestamp it closes at; if you can't, there is no loop), and the withheld answer must be one the viewer CANNOT supply themselves — a formally-correct loop with a guessable answer passes every mechanical check and dies in the field. (3) PAYOFF — shown, not summarized, ≥5 uninterrupted seconds, landing BEFORE the final beat; the payoff is not the CTA. (4) BAIT — one ask in the final beat and in the post caption; a keyword comment ask ("comment CLIPPER and I'll send the breakdown") is standard and allowed, but never "follow for part two", ragebait, or an earnings/health claim traded for the reply. Then build the timeline. Re-theming a decomposed template: viral_dna already names the source's hook/retention/payoff — rebuild each charge for the new subject, never flatten the loop into a product statement. Full craft harness: the vidfarm skill's references/hooks-and-virality.md. Checkable form: \`vidfarm harness show hooks\`.
 - THE FIRST FRAME IS THE THUMBNAIL. Frame 0 is one frame of ~30 in the first second, but every feed card, share link, and paused player freezes on it — more people see that frame than watch the video. It must never be black, empty, mid-fade, or mid-animation: a real visual at start:0 (\`vidfarm retime . --layer <key> --start 0\`), the hook words already on screen at t=0, and NO entrance transition on the FIRST clip (\`vidfarm transitions set . --layer <key> --in none\`; junction transitions between later clips are fine). Look at the actual pixels before you render: \`vidfarm stills . --at 0\`.
 - REVIEW THE WHOLE VIDEO AS ONE OBJECT — AND NEVER JUDGE IT BY ONE FRAME. Assume your own finished video has a defect you cannot see: across a 32-video batch, EVERY first-pass video had a real defect its own author had already reported as "verified, looks good". The cause is structural — you build scene by scene, each scene correct while it is the whole world, so every scene passes alone and the video fails as a SEQUENCE: margins shift between beats, headline sizes drift, the accent color wanders, one asset is flat vector and the next is photographic, every beat is the same length, a join lands like a slap. Nobody watches a scene; they watch the sequence. So before you call anything done, tile ~12 stills into ONE contact sheet and READ IT AS AN IMAGE — one command: \`vidfarm stills . --sheet\` (add \`--at 0,2,4,…\` to pick timestamps; writes stills/contact-sheet.png). Check: visual balance (no dead band under top-anchored content), consistent spacing/margins, ONE type scale, ONE accent color, ONE illustration style, deliberate pacing rather than N identical beats, nothing jarring at the joins, no frame where two elements compete for the eye — and the summary question, does it look like one person made it in one sitting? Fix drift by defining the SYSTEM (type scale, margin, palette, default beat) and applying it to every scene, not by patching the one scene that stood out. The defects that actually ship, in observed frequency order: large flat dead regions · a placeholder empty state that reads as a failed render · two contradictory numbers in one frame · a CTA still building at the last frame (settle it >=2s before the end) · two headlines superimposed at a scene handoff (exit at nextIn-0.18, duration 0.24, ease power2.out) · type colliding with a busy background exactly as it is spoken. If a frame looks empty, sample 0.2s apart to see whether it RESTS there — a transient wipe frame is fine, >0.5s is a hole. AND ALWAYS COMPARE TWO FRAMES FROM DIFFERENT SCENES: a frozen render (an overlay/watermark pass missing \`-loop 1\`, or assets outside the composition root so the timeline never runs) makes every frame identical while duration, frame count and audio hash all still pass, and frame 0 looks perfect. Verify audio by MEASUREMENT, never "it sounds fine" (you cannot hear it): ~12-15 dB speech-over-bed separation across the actual word spans, peak <0 dBFS. Never \`adelay\` the VO — whisper word timings and every caption built from them are relative to the raw vo.wav; use apad+atrim. Report what you MEASURED separately from what you JUDGED. Full method: the vidfarm skill's references/reviewing-renders.md.
-- ONE-TIME OR BULK? Ask before you build. If the director wants volume (daily posting, N variants, hook tests), that's SCRIPTING MODE: pin this fork as the base, vary exactly ONE thing per variant, and install a QA_REGIME.md — \`vidfarm regime init short-form --out ./QA_REGIME.md\` (bases: short-form, hooks, ugc-testimonial, explainer, product-demo), then EDIT it with them. It is their own written quality standard, and it exists because nobody watches variant #37 as carefully as #1. \`vidfarm qa .\` picks up ./QA_REGIME.md automatically; \`--regime <name|path>\` adds more (they stack, and any file of theirs anywhere is valid). Its \`checks:\` are machine-settled; its \`- [ ]\` items come back for YOU to answer honestly in your report — never claim a pass on the half the CLI can't judge. When a batch teaches you something, write it back into the regime.
+- THE HARNESS IS A FIRST-CLASS ARTIFACT — KNOW THE THREE PHRASINGS. A HARNESS.md is the reusable AI harness for ONE format or template: what makes it special, written down so an agent reproduces it without the director in the room. "Create me a harness" → \`vidfarm harness init short-form --out ./HARNESS.md\` (bases: short-form, hooks, ugc-testimonial, explainer, product-demo), then EDIT it with them. "Update the harness for this format" → open the file and write the new rule in WITH ITS REASON on the same line. "Give me the harness for this template_id" → they mean the DECOMPOSITION: \`vidfarm harness derive <forkId>\` distils this fork's viral/visual/structural/audio/build DNA into an editable HARNESS.md, keyed the same way the decompose JSON is (\`## Viral DNA\` → \`viral_dna\`, …); \`vidfarm harness show <ref> --dna visual\` prints one strand. \`vidfarm qa .\` picks up ./HARNESS.md automatically; \`--harness <name|path>\` adds more (they stack, and any file of theirs anywhere is valid). Its \`checks:\` are machine-settled; its \`- [ ]\` items come back for YOU to answer honestly in your report — never claim a pass on the half the CLI can't judge. ONE-TIME OR BULK? Ask before you build: if the director wants volume (daily posting, N variants, hook tests), that's SCRIPTING MODE — pin this fork as the base, vary exactly ONE thing per variant, and install a harness, because nobody watches variant #37 as carefully as #1. When a batch teaches you something, write it back into the harness — the compositions are disposable, the harness compounds. (Formerly QA_REGIME.md; \`vidfarm regime …\` still works as an alias. NOTE: the \`.harness/\` directory beside this file is machine-generated context regenerated on every pull — never hand-edit it. HARNESS.md is the one you own.)
 - DEDUPLICATE BEFORE YOU PUBLISH — AND ASK FIRST. Social platforms fingerprint every upload, so the same render posted twice (a second account, another platform, a re-post next month) gets the later copy suppressed as duplicate/reused content. BEFORE you render for publication, and before any bulk run, ASK the director: "do you want deduplicated copies for posting, and how many?" Ask THEN, not after — dedupe is a post-render ffmpeg pass, so the correct order is RENDER ONCE → DEDUPE N, and deciding late means paying for a second render. Run it on the EXPORTED file: \`vidfarm dedupe ./final.mp4\` (one copy) or \`vidfarm dedupe ./final.mp4 --variants N --seed <slug> --out-dir ./posts\` (N copies, one per account/slot). Free, offline, no wallet — it never re-renders the composition. The default \`standard\` preset is 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; invisible to a viewer, and each variant differs from the original AND from its siblings. Post each variant to a DIFFERENT account — two accounts posting the same variant defeats the point. A rotate forces a bigger centre-crop to hide the black corners (~6.7% on a tall frame at 2°) and the CLI says so; pass \`--rotate 0\` when framing matters more. Cloud twin: \`POST /api/v1/primitives/media/dedupe\`.
 - QA EVERY VIDEO BEFORE YOU RENDER: run \`vidfarm qa .\` in this directory. It's free, instant, and local — a blocklist for the slop above plus the first frame, the font regime, and the safe zone, with a concrete fix per finding. It's feedback, not a gate (exits 0 even on findings, never runs automatically) and a blocklist, not an allowlist, so stylized or hand-made work passes untouched. Fix what's real, ignore what's a deliberate style call. \`--json\` for scripted batches.
 
@@ -5157,6 +5231,12 @@ async function runRemoveGreenscreenCommand(argv) {
             tolerance: { type: "string" },
             softness: { type: "string" },
             "no-despill": { type: "boolean", default: false },
+            // IMAGE-only upgrade: key by border-connected fill instead of by color
+            // alone, so plate-colored detail inside the subject and hollow/outline art
+            // survive (`vidfarm cutout` / `sticker-pack` use this by default). Video
+            // stays on the ffmpeg filter chain — per-frame fills in JS would be slow
+            // and would break cloud parity.
+            smart: { type: "boolean", default: false },
             "output-format": { type: "string" },
             // Animated transparent GIF (local only) — the "sticker for GIF-only
             // surfaces" output. GIF alpha is 1-bit, so it's a hand-off format, not a
@@ -5323,9 +5403,38 @@ async function runLocalGreenscreen(ctx, values, sourceArg, presetRaw) {
         const keyTargetPath = gifWork
             ? path.join(gifWork, mediaType === "video" ? "keyed.webm" : "keyed.png")
             : outPath;
-        if (!ctx.json)
-            console.log(`${DIM}Keying out ${presetRaw ?? keyColor ?? "green"} background locally with ffmpeg (free)…${RESET}`);
-        let result = await removeGreenscreenLocal({ sourcePath, mediaType, outputPath: keyTargetPath, keyColor, tolerance, softness, despill });
+        const wantSmart = Boolean(values.smart);
+        if (wantSmart && mediaType === "video") {
+            throw new Error("--smart is image-only (it flood-fills the plate per frame). For a clip, key it without --smart, or cut the subject out with `vidfarm remove-background <video>` (ONNX matting, color-blind).");
+        }
+        let result;
+        if (wantSmart) {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out ${presetRaw ?? keyColor ?? "green"} background locally with the smart keyer (border-connected fill, free)…${RESET}`);
+            const smart = await smartKeyPlate({
+                sourcePath,
+                outputPath: /\.(png|webp)$/i.test(keyTargetPath) ? keyTargetPath : `${keyTargetPath.replace(/\.[^.]+$/, "")}.png`,
+                keyColor: keyColor ?? "#00FF00",
+                singlePlate: true,
+                tolerance: values.tolerance !== undefined ? Number(values.tolerance) : undefined,
+                softness: values.softness !== undefined ? Number(values.softness) : undefined,
+                despill
+            });
+            result = {
+                outputPath: smart.outputPath,
+                format: (/\.webp$/i.test(smart.outputPath) ? "webp" : "png"),
+                alpha: true,
+                webmAlpha: false
+            };
+            if (!ctx.json && smart.stats.protected_px) {
+                console.log(`${DIM}Kept ${smart.stats.protected_px.toLocaleString()} plate-colored pixel(s) INSIDE the subject that a flat key would have deleted.${RESET}`);
+            }
+        }
+        else {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out ${presetRaw ?? keyColor ?? "green"} background locally with ffmpeg (free)…${RESET}`);
+            result = await removeGreenscreenLocal({ sourcePath, mediaType, outputPath: keyTargetPath, keyColor, tolerance, softness, despill });
+        }
         if (gifWork) {
             try {
                 if (!ctx.json)
@@ -5735,7 +5844,7 @@ async function runLocalDedupe(ctx, input) {
 // "Cutout graphics for explainers" recipe for placement + zoom/grow/shake/move).
 /** Build a chroma-plate instruction so an AI-generated graphic keys cleanly.
  *  Matches the color to the chosen key so the keyer has a flat edge to cut. */
-function cutoutPlateInstruction(keyColorHex) {
+function cutoutPlateInstruction(keyColorHex, keyMode = "smart") {
     const named = /^#?00ff00$/i.test(keyColorHex) ? "pure chroma-key green"
         : /^#?0047bb$/i.test(keyColorHex) ? "solid chroma-key blue"
             : /^#?ff00ff$/i.test(keyColorHex) ? "solid magenta"
@@ -5744,9 +5853,10 @@ function cutoutPlateInstruction(keyColorHex) {
         `like a green-screen plate. ` +
         `Center the subject with generous empty margin on all sides, no drop shadow or reflection cast on the ` +
         `background, crisp clean edges, sticker/cutout style, single subject, no text. ` +
-        // The plate color is only half the battle — art drawn as a hollow outline
-        // (or in a near-plate shade) gets its middle keyed away too.
-        keySafeArtInstruction(keyColorHex));
+        // Which art rules apply depends on the keyer: a flat chromakey deletes the
+        // key color wherever it appears (so hollow art loses its middle), while the
+        // smart keyer only deletes background that reaches the frame edge.
+        (keyMode === "smart" ? connectivitySafeArtInstruction(keyColorHex) : keySafeArtInstruction(keyColorHex)));
 }
 async function runCutoutCommand(argv) {
     const parsed = parseArgs({
@@ -5768,6 +5878,7 @@ async function runCutoutCommand(argv) {
             tolerance: { type: "string" },
             softness: { type: "string" },
             "no-despill": { type: "boolean", default: false },
+            "key-mode": { type: "string" }, // smart (default) | flat
             // Trim knobs.
             "no-trim": { type: "boolean", default: false },
             pad: { type: "string" },
@@ -5795,6 +5906,15 @@ async function runCutoutCommand(argv) {
     const despill = !parsed.values["no-despill"];
     const outputFormat = parsed.values["output-format"]?.trim().toLowerCase();
     const outExt = outputFormat === "webp" ? "webp" : "png";
+    // `smart` keys by border-connected fill, so plate-colored details inside the
+    // subject and hollow/outline art survive, and the edge is feathered + de-spilled
+    // per pixel. `flat` is the plain ffmpeg chromakey, kept as the simple fallback
+    // (and the way to match a cloud render exactly).
+    const keyModeRaw = (parsed.values["key-mode"] ?? "smart").trim().toLowerCase();
+    if (!["smart", "flat"].includes(keyModeRaw)) {
+        throw new Error(`Unknown --key-mode "${keyModeRaw}". Use smart (default) or flat (the plain ffmpeg chromakey).`);
+    }
+    const keyMode = keyModeRaw;
     const generatePrompt = parsed.values.generate?.trim();
     const sourceArg = parsed.values.source ?? parsed.positionals[0];
     if (!generatePrompt && !sourceArg) {
@@ -5835,7 +5955,7 @@ async function runCutoutCommand(argv) {
                     "and hands the PNG back; `vidfarm cutout <file>` then keys + trims it for $0"
             });
             const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
-            const fullPrompt = `${generatePrompt}. ${cutoutPlateInstruction(keyColor)}`;
+            const fullPrompt = `${generatePrompt}. ${cutoutPlateInstruction(keyColor, keyMode)}`;
             const payload = { prompt: fullPrompt };
             payload.aspect_ratio = parsed.values["aspect-ratio"] ?? "1:1";
             if (parsed.values.provider)
@@ -5899,9 +6019,28 @@ async function runCutoutCommand(argv) {
             }
         }
         const keyedPath = path.join(work, "keyed.png");
-        if (!ctx.json)
-            console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} background locally with ffmpeg (free)…${RESET}`);
-        await removeGreenscreenLocal({ sourcePath, mediaType: "image", outputPath: keyedPath, keyColor, tolerance, softness, despill });
+        let cutoutKey = null;
+        if (keyMode === "flat") {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} background locally with ffmpeg chromakey (--key-mode flat, free)…${RESET}`);
+            await removeGreenscreenLocal({ sourcePath, mediaType: "image", outputPath: keyedPath, keyColor, tolerance, softness, despill });
+        }
+        else {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} background locally with the smart keyer (border-connected fill, free)…${RESET}`);
+            cutoutKey = await smartKeyPlate({
+                sourcePath,
+                outputPath: keyedPath,
+                keyColor,
+                singlePlate: true,
+                tolerance: parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : undefined,
+                softness: parsed.values.softness !== undefined ? Number(parsed.values.softness) : undefined,
+                despill
+            });
+            if (!ctx.json && cutoutKey.stats.protected_px) {
+                console.log(`${DIM}Kept ${cutoutKey.stats.protected_px.toLocaleString()} ${keyColor}-colored pixel(s) INSIDE the subject that a flat key would have deleted.${RESET}`);
+            }
+        }
         // ---- 3. Trim to the tight cutout bounding box ---------------------------
         const outPath = parsed.values.out
             ? path.resolve(process.cwd(), String(parsed.values.out))
@@ -5927,12 +6066,18 @@ async function runCutoutCommand(argv) {
         // left as bare plate) or a near-plate fill comes back as a rim around a
         // see-through hole — invisible until it composites over a real background.
         const art = await analyzeKeyedArt(trim.outputPath);
-        const hollowNote = art?.hollow
-            ? `${art.hole_pct}% of this cutout is transparent HOLES inside the art. If it's meant to be a ring/frame/donut, ignore this. ` +
-                `Otherwise the key ate the fill: the art was drawn as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. ` +
-                `Fix it in the PROMPT — ask for "a closed, solidly filled shape, no outline-only or hollow art, nothing in ${keyColor} or any near-shade of it, ` +
-                `fully opaque, no translucency or glow" — and re-generate. (--tolerance lower can rescue a near-shade fill; nothing rescues an empty one.)`
-            : null;
+        const hollowNote = !art?.hollow
+            ? null
+            : keyMode === "smart"
+                // The smart keyer can't reach an enclosed interior, so a hole is almost
+                // always drawn that way — or the fill is OPEN to the background.
+                ? `${art.hole_pct}% of this cutout is transparent HOLES inside the art. The smart keyer can't delete an enclosed interior, so this is ` +
+                    `most likely real (a ring, frame, donut, or separate pieces with background between them). If it looks wrong, the shape's fill is open ` +
+                    `to the background through a gap in its outline — ask the prompt for a closed, solidly filled shape.`
+                : `${art.hole_pct}% of this cutout is transparent HOLES inside the art. If it's meant to be a ring/frame/donut, ignore this. ` +
+                    `Otherwise the flat key ate the fill: the art was drawn as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. ` +
+                    `Re-run without --key-mode flat (the smart keyer keeps enclosed interiors), or fix it in the PROMPT — "a closed, solidly filled shape, ` +
+                    `nothing in ${keyColor} or any near-shade of it, fully opaque".`;
         if (ctx.json) {
             printJson({
                 ok: true,
@@ -5947,6 +6092,9 @@ async function runCutoutCommand(argv) {
                 area_reduced_pct: shrinkPct,
                 bytes: safeSize(trim.outputPath),
                 key_color: keyColor,
+                key_mode: keyMode,
+                keyed_pct: cutoutKey?.stats.keyed_pct ?? null,
+                protected_px: cutoutKey?.stats.protected_px ?? null,
                 hole_pct: art?.hole_pct ?? null,
                 hollow: art?.hollow ?? false,
                 hollow_note: hollowNote
@@ -6166,7 +6314,7 @@ function slugifyStickerName(raw) {
  *  in the parts that make segmentation work: a spread-out grid and, above all,
  *  visible plate-colored GAPS between items (touching items merge into one
  *  island and come out as a single sticker). */
-function stickerSheetInstruction(keyColorHex, count, items) {
+function stickerSheetInstruction(keyColorHex, count, items, keyMode = "smart") {
     const named = /^#?00ff00$/i.test(keyColorHex) ? "pure chroma-key green"
         : /^#?0047bb$/i.test(keyColorHex) ? "solid chroma-key blue"
             : /^#?ff00ff$/i.test(keyColorHex) ? "solid magenta"
@@ -6180,7 +6328,10 @@ function stickerSheetInstruction(keyColorHex, count, items) {
         `nothing touching, overlapping, or connected. Keep a wide ${keyColorHex} margin around the edges of the sheet too. ` +
         `No drop shadows, no reflections, no text, no labels, ` +
         `no frames or dividing lines between items. One consistent art style across all items, crisp clean edges, sticker/cutout style. ` +
-        keySafeArtInstruction(keyColorHex));
+        // The art rules depend on which keyer will cut this sheet: the smart keyer
+        // only deletes background that reaches the sheet's edge, so it can allow
+        // hollow shapes and plate-colored detail that a flat chromakey cannot.
+        (keyMode === "smart" ? connectivitySafeArtInstruction(keyColorHex) : keySafeArtInstruction(keyColorHex)));
 }
 async function runStickerPackCommand(argv) {
     const parsed = parseArgs({
@@ -6205,6 +6356,12 @@ async function runStickerPackCommand(argv) {
             tolerance: { type: "string" },
             softness: { type: "string" },
             "no-despill": { type: "boolean", default: false },
+            // How the plate is removed, and how the sheet is laid out.
+            "key-mode": { type: "string" }, // smart (default) | flat
+            "sheet-mode": { type: "string" }, // auto (default) | zoned | flat
+            zones: { type: "string" }, // auto (default) | off | RxC
+            "zone-cols": { type: "string" },
+            refine: { type: "boolean", default: false },
             // Segmentation knobs.
             "min-area": { type: "string" },
             gap: { type: "string" },
@@ -6249,13 +6406,71 @@ async function runStickerPackCommand(argv) {
     if (!generatePrompt && !sourceArg) {
         throw new Error("sticker-pack needs a sheet: `vidfarm sticker-pack <sheet.png|url>` to cut up a greenscreen sheet you already have, or `vidfarm sticker-pack --generate \"cozy farm props\" --items \"barn,tractor,hay bale,sun\"` to AI-generate one first (ONE image job for the whole set).");
     }
+    // ---- How to key, and how to lay the sheet out -----------------------------
+    // KEY MODE. `smart` (default) keys by CONNECTIVITY: it flood-fills the plate
+    // inward from the sheet's edge, so only background that reaches the edge is
+    // deleted. Plate-colored art interiors and hollow/outline shapes survive, and
+    // edges come out feathered and de-spilled per pixel. `flat` is the original
+    // ffmpeg chromakey — every pixel that looks like the key color goes, wherever
+    // it is. Kept as a first-class fallback: it is the cloud path's exact filter
+    // chain, so it's the way to reproduce a cloud render bit-for-bit.
+    const keyModeRaw = (parsed.values["key-mode"] ?? "smart").trim().toLowerCase();
+    if (!["smart", "flat"].includes(keyModeRaw)) {
+        throw new Error(`Unknown --key-mode "${keyModeRaw}". Use smart (default — connectivity fill, keeps plate-colored art) or flat (the plain ffmpeg chromakey).`);
+    }
+    const keyMode = keyModeRaw;
+    // SHEET MODE. `zoned` puts every item on its OWN colored panel, so each item's
+    // plate is chosen against that item — a green frog on magenta beside a pink
+    // flower on green. `flat` is the classic ONE-color sheet. `auto` (default)
+    // zones a named multi-item generation and stays flat otherwise, because a
+    // weaker image model may not honor a color-block grid; if the model ignores it
+    // anyway, keying falls back to a flat plate automatically (see below).
+    const sheetModeRaw = (parsed.values["sheet-mode"] ?? "auto").trim().toLowerCase();
+    if (!["auto", "zoned", "flat"].includes(sheetModeRaw)) {
+        throw new Error(`Unknown --sheet-mode "${sheetModeRaw}". Use auto (default), zoned (one plate color per item — needs a model that follows a color-block grid), or flat (one plate color for the whole sheet).`);
+    }
+    if (sheetModeRaw === "zoned" && keyMode === "flat") {
+        throw new Error("--sheet-mode zoned needs the smart keyer (a flat chromakey can only remove one color per sheet). Drop --key-mode flat, or use --sheet-mode flat.");
+    }
+    if (sheetModeRaw === "zoned" && !generatePrompt) {
+        throw new Error("--sheet-mode zoned only applies when GENERATING a sheet (it plans the panel colors). For a zoned sheet you already have, pass --zones auto (the default) or --zones RxC.");
+    }
+    const wantZonedSheet = generatePrompt
+        ? sheetModeRaw === "zoned" || (sheetModeRaw === "auto" && keyMode === "smart" && itemNames.length >= 2 && !explicitKeyColor)
+        : false;
+    // ZONES: how to READ panels back off a sheet at key time. Independent of
+    // sheet-mode, because a zoned sheet can also arrive from a web generator.
+    const zonesRaw = (parsed.values.zones ?? "auto").trim().toLowerCase();
+    let declaredGrid = null;
+    if (!["auto", "off", "none"].includes(zonesRaw)) {
+        const m = /^(\d+)\s*[x×]\s*(\d+)$/.exec(zonesRaw);
+        if (!m)
+            throw new Error(`Unknown --zones "${zonesRaw}". Use auto (default — read the panels off the sheet), off (one plate for the whole sheet), or a grid like 3x2 (rows x columns).`);
+        declaredGrid = { rows: Number(m[1]), cols: Number(m[2]) };
+    }
+    const zonesOff = ["off", "none"].includes(zonesRaw);
+    const refine = Boolean(parsed.values.refine);
     // PLATE CHOICE. A chroma key removes exactly one color, so a plate the art
     // also uses keys holes through the art — a pack of leaves/frogs/money on GREEN
     // is the classic own-goal. When generating and the caller didn't pin a color,
     // read the subject and move the plate off any hue it mentions.
     let plateNote = null;
     let plateAuto = false;
-    if (generatePrompt && !explicitKeyColor && !parsed.values["no-auto-key"]) {
+    let zonePlan = null;
+    if (wantZonedSheet) {
+        // ZONED: no single plate to pick — every panel gets its own, chosen against
+        // the item that sits on it.
+        zonePlan = planZonedSheet(itemNames, itemNames.length, pickPlateColor, {
+            theme: generatePrompt,
+            cols: parsed.values["zone-cols"] !== undefined ? Math.max(1, Math.round(Number(parsed.values["zone-cols"]))) : undefined
+        });
+        plateAuto = true;
+        plateNote =
+            `Zoned sheet: ${zonePlan.rows}×${zonePlan.cols} panels, one plate color per item ` +
+                `(${zonePlan.cells.map((c) => `${c.name ?? `item ${c.index}`} on ${c.keyColor}`).join(", ")}). ` +
+                `Each item's art can use ANY color — including the colors of the other panels.`;
+    }
+    else if (generatePrompt && !explicitKeyColor && !parsed.values["no-auto-key"]) {
         const picked = pickPlateColor([generatePrompt, itemNames.join(" ")].join(" "));
         keyColor = picked.keyColor;
         plateAuto = true;
@@ -6290,7 +6505,9 @@ async function runStickerPackCommand(argv) {
                     "back; this command then splits it for $0"
             });
             const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
-            const fullPrompt = `${generatePrompt}. ${stickerSheetInstruction(keyColor, count, itemNames)}`;
+            const fullPrompt = zonePlan
+                ? `${generatePrompt}. ${zonedSheetInstruction(zonePlan, { theme: generatePrompt })}`
+                : `${generatePrompt}. ${stickerSheetInstruction(keyColor, count, itemNames, keyMode)}`;
             const payload = { prompt: fullPrompt };
             // A sheet wants room to spread items out — square by default, not portrait.
             payload.aspect_ratio = parsed.values["aspect-ratio"] ?? "1:1";
@@ -6303,8 +6520,11 @@ async function runStickerPackCommand(argv) {
             const tracer = parsed.values.tracer ?? `devcli-stickerpack-${Date.now().toString(36)}`;
             if (!ctx.json && plateNote)
                 console.log(`${YELLOW}Plate:${RESET} ${DIM}${plateNote}${RESET}`);
-            if (!ctx.json)
-                console.log(`${DIM}Generating ONE ${keyColor} plate holding ${count} items…${RESET}`);
+            if (!ctx.json) {
+                console.log(zonePlan
+                    ? `${DIM}Generating ONE color-block sheet — ${zonePlan.rows}×${zonePlan.cols} panels, ${count} items, a different plate under each…${RESET}`
+                    : `${DIM}Generating ONE ${keyColor} plate holding ${count} items…${RESET}`);
+            }
             const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/images/generate", auth: ctx.auth, body: { tracer, payload } });
             assertApiOk(submit, "sticker-pack generate");
             const jobId = submit.json?.job_id;
@@ -6344,12 +6564,12 @@ async function runStickerPackCommand(argv) {
                 await downloadUrlToFile(sourceUrl, sheetPath);
             }
         }
-        // ---- 2. Key the flat plate ONCE → a transparent sheet ---------------------
+        // ---- 2. Key the plate(s) ONCE → a transparent sheet ------------------------
         // For a sheet we did NOT generate, read the plate off the image instead of
         // assuming green: the four corners of a sticker sheet are always plate, so
         // a user can hand back a red/purple/blue sheet from a web generator and the
         // cut still works without them knowing what a chroma key is.
-        if (!explicitKeyColor && !generatePrompt && !parsed.values["no-auto-key"]) {
+        if (!explicitKeyColor && !generatePrompt && !parsed.values["no-auto-key"] && (keyMode === "flat" || zonesOff)) {
             const detected = await detectPlateColor(sheetPath);
             if (detected && detected.hex.toUpperCase() !== keyColor.toUpperCase()) {
                 keyColor = detected.hex;
@@ -6363,9 +6583,83 @@ async function runStickerPackCommand(argv) {
                 console.log(`${YELLOW}Plate:${RESET} ${DIM}${plateNote}${RESET}`);
         }
         const keyedSheet = path.join(work, "keyed-sheet.png");
-        if (!ctx.json)
-            console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} plate locally with ffmpeg (free)…${RESET}`);
-        await removeGreenscreenLocal({ sourcePath: sheetPath, mediaType: "image", outputPath: keyedSheet, keyColor, tolerance, softness, despill });
+        let smart = null;
+        let zonesUsed = [];
+        let keyNote = null;
+        if (keyMode === "flat") {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} plate locally with ffmpeg chromakey (--key-mode flat, free)…${RESET}`);
+            await removeGreenscreenLocal({ sourcePath: sheetPath, mediaType: "image", outputPath: keyedSheet, keyColor, tolerance, softness, despill });
+        }
+        else {
+            // SMART. Zones come from (a) the grid we asked the model for, (b) a grid the
+            // caller declared, (c) the sheet's own edges, or (d) one plate for the whole
+            // sheet. Panels are keyed independently, each with its own color read back
+            // off that panel's corners.
+            const grid = declaredGrid ?? (zonePlan && !zonesOff ? { rows: zonePlan.rows, cols: zonePlan.cols } : null);
+            if (!ctx.json) {
+                console.log(grid || !zonesOff
+                    ? `${DIM}Keying locally with the smart keyer (border-connected fill${grid ? `, ${grid.rows}×${grid.cols} panels` : ", auto zones"}, free)…${RESET}`
+                    : `${DIM}Keying the ${keyColor} plate locally with the smart keyer (border-connected fill, free)…${RESET}`);
+            }
+            smart = await smartKeyPlate({
+                sourcePath: sheetPath,
+                outputPath: keyedSheet,
+                keyColor: zonesOff || explicitKeyColor ? keyColor : undefined,
+                singlePlate: zonesOff,
+                grid: grid ?? undefined,
+                tolerance: parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : undefined,
+                softness: parsed.values.softness !== undefined ? Number(parsed.values.softness) : undefined,
+                despill
+            });
+            // AUTOMATIC FALLBACK TO A FLAT PLATE. A weaker image model may ignore the
+            // color-block grid and paint one background anyway (or paint a busy one).
+            // Then some "panel" has almost nothing to key, and its item would come out
+            // welded to a colored rectangle. Detect that and re-key the sheet as a
+            // single plate, read off its corners — the simple method, still free.
+            // Two ways a panel says "this sheet isn't the grid I asked for":
+            //   • it keyed almost NOTHING (25%) — the color read at its corners isn't a
+            //     plate, so the panel is really part of one big background or of the art;
+            //   • it keyed EVERYTHING — the item filled the panel corner to corner, so
+            //     the item's own color was read as the plate and the item was deleted.
+            // The second only counts for a panel we expected to hold an item: a trailing
+            // panel of a grid wider than the item list is legitimately all plate.
+            const expectedItems = zonePlan ? zonePlan.cells.length : itemNames.length;
+            const weakZone = smart.stats.perZone.find((z) => z.keyed_pct < 25 || (z.keyed_pct > 99.5 && expectedItems > 0 && z.zone <= expectedItems));
+            if (smart.stats.zones.length > 1 && weakZone) {
+                const detected = await detectPlateColor(sheetPath);
+                keyColor = detected?.hex ?? keyColor;
+                plateAuto = Boolean(detected);
+                keyNote =
+                    `Panel ${weakZone.zone} (${weakZone.hex}) keyed ${weakZone.keyed_pct}% of itself — ` +
+                        `${weakZone.keyed_pct < 25 ? "there's no plate there" : "its item filled the panel corner to corner, so the item's own color read as the plate"}, ` +
+                        `i.e. the sheet isn't really a color-block grid, ` +
+                        `so it was re-keyed as ONE ${keyColor} plate${detected ? " (read off the sheet's corners)" : ""}. ` +
+                        `That's the simple path and it works; for zoned sheets the image model has to follow a color-block grid ` +
+                        `(try a stronger model, or pass --sheet-mode flat to skip zoning entirely).`;
+                smart = await smartKeyPlate({
+                    sourcePath: sheetPath,
+                    outputPath: keyedSheet,
+                    keyColor,
+                    singlePlate: true,
+                    tolerance: parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : undefined,
+                    softness: parsed.values.softness !== undefined ? Number(parsed.values.softness) : undefined,
+                    despill
+                });
+                zonePlan = null; // panel→name mapping is meaningless once we fall back
+                if (!ctx.json)
+                    console.log(`${YELLOW}Zones:${RESET} ${DIM}${keyNote}${RESET}`);
+            }
+            zonesUsed = smart.stats.zones;
+            if (zonesUsed.length === 1)
+                keyColor = zonesUsed[0].hex;
+            if (!ctx.json) {
+                const zoneWord = zonesUsed.length > 1 ? `${zonesUsed.length} panels (${zonesUsed.map((z) => z.hex).join(", ")})` : `one ${keyColor} plate`;
+                console.log(`${DIM}Keyed ${smart.stats.keyed_pct}% of the sheet — ${zoneWord}` +
+                    (smart.stats.protected_px ? `, kept ${smart.stats.protected_px.toLocaleString()} plate-colored pixel(s) INSIDE the art that a flat key would have punched out` : "") +
+                    `.${RESET}`);
+            }
+        }
         if (parsed.values["keep-sheet"]) {
             const keepPath = path.resolve(process.cwd(), String(parsed.values["keep-sheet"]));
             mkdirSync(path.dirname(keepPath), { recursive: true });
@@ -6387,6 +6681,43 @@ async function runStickerPackCommand(argv) {
         if (!seg.components.length) {
             throw new Error("No items found in the sheet. Either the plate didn't key (check --preset/--key-color, raise --tolerance) or every item was filtered as speckle (lower --min-area).");
         }
+        // ---- 3a. Names, by PANEL when the sheet is zoned -------------------------
+        // On a flat sheet, names can only be matched to items in reading order, which
+        // goes off-by-one the moment two items merge or one splits. A zoned sheet
+        // makes it exact: panel N holds the item we asked for in panel N, so an item's
+        // name comes from whichever panel its box sits in.
+        const zoneIndexOf = (c) => {
+            if (zonesUsed.length < 2)
+                return -1;
+            const cx = c.x + c.width / 2;
+            const cy = c.y + c.height / 2;
+            return zonesUsed.findIndex((z) => cx >= z.x && cx < z.x + z.width && cy >= z.y && cy < z.y + z.height);
+        };
+        const nameOf = (c) => {
+            if (zonePlan) {
+                const zi = zoneIndexOf(c);
+                if (zi >= 0)
+                    return zonePlan.cells.find((cell) => cell.index === zi + 1)?.name ?? null;
+            }
+            return itemNames[c.index - 1] ?? null;
+        };
+        // A panel that yielded NO sticker is worth saying out loud: either it was
+        // empty (a grid wider than the item list — fine) or its item was keyed away
+        // with the panel. The pack is still usable, so this warns rather than fails.
+        let emptyPanelNote = null;
+        if (zonesUsed.length > 1) {
+            const empty = zonesUsed
+                .map((_, i) => i + 1)
+                .filter((panel) => !seg.components.some((c) => zoneIndexOf(c) === panel - 1));
+            if (empty.length) {
+                emptyPanelNote =
+                    `Panel(s) ${empty.join(", ")} produced no sticker. If those panels were meant to be empty, ignore this — otherwise the item ` +
+                        `there touched its panel's edges (so its own color read as the plate and it keyed away). Re-run with --zones off, or ` +
+                        `--key-color <hex> to pin the plate.`;
+                if (!ctx.json)
+                    console.log(`${YELLOW}Panels:${RESET} ${DIM}${emptyPanelNote}${RESET}`);
+            }
+        }
         // ---- 3b. Hollow-sticker check -------------------------------------------
         // The other half of "did the key work": items that came back as a rim around
         // a transparent hole, because the art was drawn as an outline (interior left
@@ -6396,14 +6727,24 @@ async function runStickerPackCommand(argv) {
         // which is why this warns and never blocks.
         let hollowNote = null;
         if (seg.hollow.length) {
-            const named = seg.hollow.map((i) => `${String(i).padStart(2, "0")}${itemNames[i - 1] ? ` (${itemNames[i - 1]})` : ""} — ${seg.components.find((c) => c.index === i)?.hole_pct}% see-through`);
-            hollowNote =
-                `${seg.hollow.length} of ${seg.components.length} sticker(s) came out mostly hollow: ${named.join(", ")}. ` +
-                    `If those are meant to be rings/frames/donuts, ignore this. Otherwise the key ate their FILL: the art was drawn ` +
-                    `as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. Fix it in the PROMPT, not the keyer — ` +
-                    `ask for "closed, solidly filled shapes, no outline-only or hollow objects, nothing on the art in ${keyColor} or any ` +
-                    `near-shade of it, fully opaque, no translucency or glow" — then re-generate the sheet. ` +
-                    `(Lowering --tolerance can rescue a near-shade fill from an existing sheet, but not a genuinely empty one.)`;
+            const named = seg.hollow.map((i) => {
+                const c = seg.components.find((comp) => comp.index === i);
+                const label = c ? nameOf(c) : null;
+                return `${String(i).padStart(2, "0")}${label ? ` (${label})` : ""} — ${c?.hole_pct}% see-through`;
+            });
+            hollowNote = keyMode === "smart"
+                // Under the smart keyer an ENCLOSED interior can't be keyed away, so a
+                // hole here is either genuinely drawn art (a ring, a frame) or a gap that
+                // the plate really did reach through — not the old "the key ate the fill".
+                ? `${seg.hollow.length} of ${seg.components.length} sticker(s) have large transparent areas inside them: ${named.join(", ")}. ` +
+                    `With the smart keyer a shape's ENCLOSED interior can't be keyed away, so this is most likely real: a ring, frame, donut, ` +
+                    `or an item drawn as separate pieces with plate showing between them. If it looks wrong, the art's fill is probably OPEN ` +
+                    `to the background (a gap in the outline lets the fill reach the sheet edge) — ask the prompt for closed, solidly filled shapes.`
+                : `${seg.hollow.length} of ${seg.components.length} sticker(s) came out mostly hollow: ${named.join(", ")}. ` +
+                    `If those are meant to be rings/frames/donuts, ignore this. Otherwise the flat key ate their FILL: the art was drawn ` +
+                    `as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. Either re-run without ` +
+                    `--key-mode flat (the smart keyer keeps enclosed interiors), or fix it in the PROMPT — ` +
+                    `"closed, solidly filled shapes, nothing on the art in ${keyColor} or any near-shade of it, fully opaque".`;
             if (!ctx.json)
                 console.log(`${YELLOW}Hollow:${RESET} ${DIM}${hollowNote}${RESET}`);
         }
@@ -6411,13 +6752,24 @@ async function runStickerPackCommand(argv) {
             // Report the boxes without writing stickers — for eyeballing segmentation
             // before spending disk, and for hand-fixing a merged item with `mask --crop`.
             if (ctx.json) {
-                printJson({ ok: true, target: "local", dry_run: true, sheet: `${seg.sourceWidth}x${seg.sourceHeight}`, found: seg.components.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, hollow: seg.hollow, hollow_note: hollowNote, items: seg.components });
+                printJson({
+                    ok: true, target: "local", dry_run: true, sheet: `${seg.sourceWidth}x${seg.sourceHeight}`,
+                    found: seg.components.length, skipped_specks: seg.rejected, key_mode: keyMode,
+                    key_color: keyColor, key_color_auto: plateAuto,
+                    zones: zonesUsed.map((z, i) => ({ panel: i + 1, x: z.x, y: z.y, width: z.width, height: z.height, plate: z.hex, keyed_pct: smart?.stats.perZone[i]?.keyed_pct ?? null })),
+                    protected_px: smart?.stats.protected_px ?? null,
+                    hollow: seg.hollow, hollow_note: hollowNote,
+                    items: seg.components.map((c) => ({ ...c, name: nameOf(c), panel: zoneIndexOf(c) >= 0 ? zoneIndexOf(c) + 1 : null }))
+                });
             }
             else {
                 console.log(`${GREEN}Found ${seg.components.length} item${seg.components.length === 1 ? "" : "s"}${RESET} ${DIM}on the ${seg.sourceWidth}×${seg.sourceHeight} sheet${seg.rejected ? `, ${seg.rejected} speck(s) skipped` : ""} (dry run — nothing written):${RESET}`);
                 for (const c of seg.components) {
                     const hollowFlag = c.hole_pct >= HOLE_WARN_PCT ? `  ${YELLOW}⚠ ${c.hole_pct}% hollow${RESET}` : "";
-                    console.log(`  ${DIM}${String(c.index).padStart(2, "0")}  crop ${c.x},${c.y},${c.width},${c.height}  (${c.width}×${c.height}, ${c.area_pct}% of sheet)${RESET}${hollowFlag}`);
+                    const zi = zoneIndexOf(c);
+                    const where = zi >= 0 ? `  panel ${zi + 1} (${zonesUsed[zi].hex})` : "";
+                    const label = nameOf(c);
+                    console.log(`  ${DIM}${String(c.index).padStart(2, "0")}  crop ${c.x},${c.y},${c.width},${c.height}  (${c.width}×${c.height}, ${c.area_pct}% of sheet)${where}${label ? `  ${label}` : ""}${RESET}${hollowFlag}`);
                 }
                 console.log(`${DIM}Merged two items into one box? Raise the gap between them in the prompt, lower --gap, or grab that one by hand: vidfarm mask <sheet> --crop x,y,w,h --flat "${keyColor}".${RESET}`);
             }
@@ -6428,11 +6780,56 @@ async function runStickerPackCommand(argv) {
         const padPx = parsed.values.pad !== undefined ? Number(parsed.values.pad) : 0;
         const gifAlpha = parsed.values["gif-alpha"] !== undefined ? Number(parsed.values["gif-alpha"]) : undefined;
         const written = [];
+        if (refine && !ctx.json) {
+            console.log(`${DIM}Refining each item with the local ONNX matting model (free, a second or two each) — this is the path for painterly/soft-edged art…${RESET}`);
+        }
         for (const c of seg.components) {
-            const label = itemNames[c.index - 1] ? slugifyStickerName(itemNames[c.index - 1]) : "";
+            const itemName = nameOf(c);
+            const label = itemName ? slugifyStickerName(itemName) : "";
             const stem = `${prefix}-${String(c.index).padStart(2, "0")}${label ? `-${label}` : ""}`;
             const regionPath = path.join(work, `${stem}.region.png`);
-            await cropImageRegion({ sourcePath: keyedSheet, outputPath: regionPath, x: c.x, y: c.y, width: c.width, height: c.height });
+            let refined = false;
+            if (refine) {
+                // REFINE. The keyer decides WHERE each item is; matting decides what its
+                // alpha should be. Cropping the item out of the ORIGINAL (un-keyed) sheet
+                // and running the ONNX matte on it is color-blind, so it handles the art a
+                // chroma key can't: soft/painterly edges, fur, glows, glass, drop shadows,
+                // and an item whose own silhouette is the plate color. A little margin
+                // gives the model context to separate against.
+                const margin = Math.round(Math.max(c.width, c.height) * 0.08);
+                const rawRegion = path.join(work, `${stem}.raw.png`);
+                await cropImageRegion({
+                    sourcePath: sheetPath,
+                    outputPath: rawRegion,
+                    x: Math.max(0, c.x - margin),
+                    y: Math.max(0, c.y - margin),
+                    width: c.width + margin * 2,
+                    height: c.height + margin * 2
+                });
+                const matted = path.join(work, `${stem}.matte.png`);
+                const run = await runHyperframesCommand("remove-background", [rawRegion, "-o", matted], { stdio: "capture" });
+                // Trust the matte only if it looks like a cut-out. The model is trained on
+                // photographic subjects, so on flat vector art it can return an EMPTY
+                // matte (blank sticker) or an untouched one (plate still attached) — both
+                // of which write a file and exit 0. The keyed cut is the safer answer then.
+                const opaqueShare = run.code === 0 && existsSync(matted) ? await measureOpaqueShare(matted) : null;
+                const usable = opaqueShare !== null && opaqueShare >= 5 && opaqueShare <= 95;
+                if (usable) {
+                    copyFileSync(matted, regionPath);
+                    refined = true;
+                }
+                else if (!ctx.json) {
+                    const why = run.code !== 0
+                        ? (run.stderr.trim().split("\n").pop() ?? "the matting engine failed")
+                        : opaqueShare === null
+                            ? "the matte had no alpha"
+                            : `the matte came back ${opaqueShare < 5 ? "empty" : "fully opaque"} (${opaqueShare}% opaque) — the model didn't see a subject in this art`;
+                    console.log(`  ${YELLOW}↳${RESET} ${DIM}item ${c.index}: kept the keyed cut instead of the matte — ${why}.${RESET}`);
+                }
+            }
+            if (!refined) {
+                await cropImageRegion({ sourcePath: keyedSheet, outputPath: regionPath, x: c.x, y: c.y, width: c.width, height: c.height });
+            }
             // Trim to the item's TRUE box: segmentation works on a downscaled alpha, so
             // the crop carries a pixel or two of slack — this is what makes the sticker's
             // pixel size equal the subject, the property placement/scaling relies on.
@@ -6443,13 +6840,17 @@ async function runStickerPackCommand(argv) {
                 finalPath = path.join(outDir, `${stem}.gif`);
                 await encodeTransparentGif(trim.outputPath, finalPath, { alphaThreshold: gifAlpha });
             }
+            const zi = zoneIndexOf(c);
             written.push({
                 index: c.index,
-                name: itemNames[c.index - 1] ?? null,
+                name: itemName,
                 file: finalPath,
                 width: trim.width,
                 height: trim.height,
                 sheet_crop: { x: c.x, y: c.y, width: c.width, height: c.height },
+                panel: zi >= 0 ? zi + 1 : null,
+                plate: zi >= 0 ? zonesUsed[zi].hex : keyColor,
+                refined,
                 area_pct: c.area_pct,
                 holes: c.holes,
                 hole_pct: c.hole_pct,
@@ -6464,10 +6865,22 @@ async function runStickerPackCommand(argv) {
         // A manifest so the next step (place/keyframes, or an agent picking props by
         // name) doesn't have to re-derive what's in the pack.
         const manifestPath = path.join(outDir, "stickers.json");
+        const keyReport = {
+            key_mode: keyMode,
+            sheet_mode: zonesUsed.length > 1 ? "zoned" : "flat",
+            zones: zonesUsed.map((z, i) => ({ panel: i + 1, x: z.x, y: z.y, width: z.width, height: z.height, plate: z.hex, keyed_pct: smart?.stats.perZone[i]?.keyed_pct ?? null })),
+            keyed_pct: smart?.stats.keyed_pct ?? null,
+            protected_px: smart?.stats.protected_px ?? null,
+            protected_pct: smart?.stats.protected_pct ?? null,
+            key_note: keyNote,
+            empty_panel_note: emptyPanelNote,
+            refined: refine
+        };
         writeFileSync(manifestPath, `${JSON.stringify({
             generated_from: generatePrompt ? "generate" : sourceArg,
             key_color: keyColor,
             key_color_auto: plateAuto,
+            ...keyReport,
             hollow: seg.hollow,
             hollow_note: hollowNote,
             sheet_width: seg.sourceWidth,
@@ -6477,12 +6890,14 @@ async function runStickerPackCommand(argv) {
             stickers: written
         }, null, 2)}\n`);
         if (ctx.json) {
-            printJson({ ok: true, target: "local", out_dir: outDir, manifest: manifestPath, count: written.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, key_color_note: plateNote, hollow: seg.hollow, hollow_note: hollowNote, stickers: written });
+            printJson({ ok: true, target: "local", out_dir: outDir, manifest: manifestPath, count: written.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, key_color_note: plateNote, ...keyReport, hollow: seg.hollow, hollow_note: hollowNote, stickers: written });
         }
         else {
             console.log(`${GREEN}Sticker pack ready:${RESET} ${written.length} transparent sticker${written.length === 1 ? "" : "s"} in ${outDir} ${DIM}(manifest: stickers.json${seg.rejected ? `, ${seg.rejected} speck(s) skipped` : ""})${RESET}`);
-            if (itemNames.length && itemNames.length !== written.length) {
-                console.log(`${YELLOW}Note:${RESET} ${DIM}you named ${itemNames.length} item(s) but ${written.length} were cut, so names may be off-by-one. Re-run with --dry-run to inspect the boxes; two touching items segment as ONE (lower --gap or ask the generator for wider spacing), and one item split in two segments as TWO (raise --gap).${RESET}`);
+            // Names are only guessed by reading order on a FLAT sheet; a zoned sheet
+            // pins each name to its panel, so the off-by-one caveat doesn't apply.
+            if (itemNames.length && itemNames.length !== written.length && !zonePlan) {
+                console.log(`${YELLOW}Note:${RESET} ${DIM}you named ${itemNames.length} item(s) but ${written.length} were cut, so names may be off-by-one. Re-run with --dry-run to inspect the boxes; two touching items segment as ONE (lower --gap or ask the generator for wider spacing), and one item split in two segments as TWO (raise --gap). A zoned sheet (--sheet-mode zoned) names items by PANEL instead of by order, which can't drift.${RESET}`);
             }
             console.log(`${DIM}Place one: vidfarm place <dir> --src "${written[0]?.file}" --kind image. Animate it (pop-in/float/shake/drift) with vidfarm keyframes — see the skill's "Cutout graphics for explainers" recipe.${RESET}`);
         }
@@ -6586,10 +7001,6 @@ async function runTtsCommand(argv) {
         throw new Error("tts --engine must be local (keyless Kokoro), byok (your provider key — default), or cloud.");
     }
     const wantCloud = Boolean(parsed.values.cloud) || engine === "cloud";
-    if (engine === "local") {
-        await runLocalKokoroTts({ text, voice, style, out: parsed.values.out, format: explicitFormat, json });
-        return;
-    }
     // COST-MODE DEFAULT: in minimize/hybrid, narration starts on the FREE local
     // Kokoro engine unless the run asked for a premium/cloud voice (see
     // wantsPremiumVoice). The BYOK key path is a real fallback, not a downgrade —
@@ -6597,6 +7008,18 @@ async function runTtsCommand(argv) {
     // below rather than failing the run.
     const costMode = resolveCostMode(parsed.values);
     const premium = wantsPremiumVoice(parsed.values, voice, style);
+    // Offer the human the choice of voice BEFORE any engine runs — the notice is
+    // identical whichever tier this run lands on, so it sits above the dispatch.
+    printVoiceCheckpoint({
+        interaction: resolveInteractionMode(parsed.values),
+        costMode: costMode.mode,
+        voiceChosen: Boolean(voice?.trim()),
+        tier: engine === "local" || (!engine && !wantCloud && costMode.mode !== "rich-ai" && costMode.mode !== "pure-videogen" && !premium) ? "free" : "premium"
+    });
+    if (engine === "local") {
+        await runLocalKokoroTts({ text, voice, style, out: parsed.values.out, format: explicitFormat, json });
+        return;
+    }
     /** Set when the cost-mode default ran Kokoro and it failed — so the keyless
      *  path below doesn't pointlessly retry the same engine. */
     let kokoroError = null;
@@ -6694,7 +7117,7 @@ async function runTtsCommand(argv) {
     if (parsed.values["own-key"])
         payload.use_wallet_credits = false;
     if (!ctx.json && !parsed.values["own-key"]) {
-        console.log(`${DIM}Using ElevenLabs on the platform key (wallet-billed). Browse voices: vidfarm voices — then pass --voice <voice_id>. Add --own-key to use your own key.${RESET}`);
+        console.log(`${DIM}Premium ElevenLabs narration through VIDFARM'S OWN ElevenLabs connection — no ElevenLabs account or API key needed on your side; it's billed as vidfarm wallet credits. Hear the catalog first: vidfarm voices --sample, then pass --voice <voice_id>. Already have an ElevenLabs key? add --own-key.${RESET}`);
     }
     const tracer = parsed.values.tracer ?? `devcli-tts-${Date.now().toString(36)}`;
     const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/audio/speech", auth: ctx.auth, body: { tracer, payload } });
@@ -6731,6 +7154,38 @@ async function runTtsCommand(argv) {
         console.log(`${GREEN}Wrote ${outPath}${RESET} ${DIM}(${mediaUrl})${RESET}`);
     }
 }
+/**
+ * The VOICE CHECKPOINT. Who a video sounds like is a taste decision, and the
+ * default voice is the one choice an agent makes silently that a human would
+ * almost always want a say in. So when narration is about to run with NO voice
+ * named, say so — loudly enough that the agent stops and offers samples.
+ *
+ * Interactive mode → always offer (sampling is FREE on both rosters, so this
+ * holds in `minimize` exactly as much as in `hybrid`; only the roster the offer
+ * leads with changes). Autonomous with a mode actually set → stay silent and
+ * let the pipeline run. Mode never set → offer, because "nobody asked" is not
+ * the same as "the user opted out of choosing".
+ *
+ * stderr, never stdout, so `--json` output stays parseable.
+ */
+function printVoiceCheckpoint(input) {
+    if (input.voiceChosen)
+        return;
+    if (input.interaction.mode !== "interactive" && input.interaction.isSet)
+        return;
+    const lead = input.interaction.mode === "interactive"
+        ? "[voice] Interactive mode and no voice picked yet"
+        : "[voice] No interaction preference set and no voice picked yet";
+    const free = "vidfarm voices --free --sample (renders $0 local Kokoro samples)";
+    const premium = "vidfarm voices --sample (premium ElevenLabs voices through VIDFARM'S OWN ElevenLabs connection — " +
+        "no ElevenLabs account or API key needed, narration billed as wallet credits, pennies each)";
+    const order = input.tier === "free"
+        ? `Sample the free voices first: ${free}. Same command reaches the premium tier: ${premium}.`
+        : `Sample them: ${premium}. Or stay at $0: ${free}.`;
+    console.error(`${lead} — ASK THE USER whether they want to hear a few samples and choose. ${order} ` +
+        "Sampling costs nothing on either tier (preview clips + local renders), so it's safe even in cost mode minimize. " +
+        "Then narrate with --voice <id>.");
+}
 /** Kokoro voice ids look like af_heart / am_adam / bf_emma. Anything else is a
  *  cloud provider preset (openai "alloy", gemini "Kore", an ElevenLabs id).
  *  Declared as a hoisted function, not a const: `wantsPremiumVoice` runs during
@@ -6779,7 +7234,7 @@ async function runLocalKokoroTts(input) {
     if (!input.json) {
         console.log(`${DIM}Generating speech with the local Kokoro-82M engine (free, no account)…${RESET}`);
         if (input.costModeDefault) {
-            console.log(`${DIM}(cost mode ${costModeDisplayName(input.costModeDefault)} → free local voice by default. Want a premium voice? add --style/--voice/--provider, or --cloud.)${RESET}`);
+            console.log(`${DIM}(cost mode ${costModeDisplayName(input.costModeDefault)} → free local voice by default. Pick a different free voice: vidfarm voices --free --sample. Want a PREMIUM voice? vidfarm carries the ElevenLabs catalog on its own connection — no ElevenLabs account needed, just wallet credits: vidfarm voices --sample, then --cloud --voice <voice_id>.)${RESET}`);
         }
     }
     const run = await runHyperframesCommand("tts", [input.text, "-o", wavPath, ...(voice ? ["-v", voice] : [])], { stdio: input.json ? "capture" : "inherit" });
@@ -6965,8 +7420,53 @@ async function runMusicCommand(argv) {
         console.log(`${DIM}Place it as its own <audio> layer under narration (~0.1–0.2 volume).${RESET}`);
     }
 }
-// List ElevenLabs voices for TTS. --own-key lists the voices on your own saved
-// ElevenLabs key; default lists the platform account's voices.
+/** The sentence spoken when sampling FREE voices (premium samples reuse
+ *  ElevenLabs' own preview clips, so they need no text). A hoisted function,
+ *  not a const: cli.ts runs `await main()` at top level ABOVE this point, so a
+ *  const declared here hits the TDZ when a command reads it. */
+function voiceSampleText() {
+    return "Here's how I sound. Pick the voice that fits your video.";
+}
+/** Pull the human-meaningful line out of a hyperframes engine failure. Its CLI
+ *  paints spinners and cursor codes, so the LAST line is usually an escape
+ *  sequence — prefer a line that actually reads like an error. */
+function engineFailureLine(output, fallback) {
+    const clean = output
+        // ESC-anchored so it strips real ANSI, never a literal "[mode]" in a message.
+        .replace(/\u001b\[[0-9;?]*[a-zA-Z]/g, "")
+        .split("\n")
+        .map((line) => line.replace(/^[\s│◇◆○●✖✗ו]+/, "").trim())
+        .filter((line) => line.length > 2);
+    return (clean.find((line) => /fail|error|not installed|cannot|unable|missing/i.test(line)) ?? clean.pop() ?? fallback).slice(0, 240);
+}
+/** The free local Kokoro roster, straight from the bundled engine (never a
+ *  hardcoded list — the engine owns which ids actually load). */
+async function listFreeVoices() {
+    const run = await runHyperframesCommand("tts", ["--list", "--json"], { stdio: "capture" });
+    if (run.code !== 0)
+        return [];
+    try {
+        const parsed = JSON.parse(run.stdout.slice(run.stdout.indexOf("[")));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+// Browse the voices available for narration, and SAMPLE them so a human can
+// actually choose one by ear. Two rosters, because they cost different money:
+//
+//   premium (default) — the ElevenLabs catalog reached through VIDFARM'S OWN
+//     ElevenLabs connection. No ElevenLabs account, no API key, no separate
+//     subscription: narration runs on the platform key and is billed as
+//     Vidfarm wallet credits. `--own-key` swaps in the customer's own saved
+//     ElevenLabs key instead (their account, their voices, no wallet spend).
+//   free (--free) — the keyless local Kokoro-82M presets, $0 forever, the
+//     default engine in cost mode minimize/hybrid.
+//
+// SAMPLING IS ALWAYS FREE on both rosters: premium samples are ElevenLabs'
+// static preview clips (a CDN download, not a synthesis call) and free samples
+// are generated on the local engine. So `--sample` is safe in `minimize`.
 async function runVoicesCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -6974,28 +7474,135 @@ async function runVoicesCommand(argv) {
         options: {
             ...commonOptions(),
             "own-key": { type: "boolean", default: false },
+            free: { type: "boolean", default: false },
+            all: { type: "boolean", default: false },
+            search: { type: "string" },
+            sample: { type: "boolean", default: false },
+            "sample-count": { type: "string" },
+            "sample-out": { type: "string" },
+            "sample-text": { type: "string" },
             limit: { type: "string" }
         }
     });
     const ctx = commonContext(parsed.values);
-    const query = parsed.values["own-key"] ? "?use_wallet_credits=false" : "";
-    const res = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/primitives/audio/voices${query}`, auth: ctx.auth });
-    assertApiOk(res, "voices");
-    const body = (res.json ?? {});
-    const voices = Array.isArray(body.voices) ? body.voices : [];
+    const wantFree = Boolean(parsed.values.free) || Boolean(parsed.values.all);
+    const wantPremium = !parsed.values.free || Boolean(parsed.values.all);
+    const search = parsed.values.search?.trim().toLowerCase() || null;
+    const sample = Boolean(parsed.values.sample);
+    const sampleCount = Math.max(1, Number(parsed.values["sample-count"] ?? "6") || 6);
+    const sampleText = parsed.values["sample-text"]?.trim() || voiceSampleText();
+    const sampleDir = path.resolve(process.cwd(), parsed.values["sample-out"] ?? "voice-samples");
+    const limit = Number(parsed.values.limit ?? "40") || 40;
+    const matches = (haystack) => !search || haystack.toLowerCase().includes(search);
+    const premium = [];
+    let scope = "platform";
+    let libraryUrl = "https://elevenlabs.io/app/voice-library";
+    if (wantPremium) {
+        const query = parsed.values["own-key"] ? "?use_wallet_credits=false" : "";
+        const res = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/primitives/audio/voices${query}`, auth: ctx.auth });
+        assertApiOk(res, "voices");
+        const body = (res.json ?? {});
+        scope = String(body.scope ?? "platform");
+        libraryUrl = String(body.voice_library_url ?? libraryUrl);
+        for (const voice of Array.isArray(body.voices) ? body.voices : []) {
+            const labels = voice.labels && typeof voice.labels === "object" ? Object.values(voice.labels).join(", ") : "";
+            if (matches(`${voice.name ?? ""} ${labels} ${voice.description ?? ""} ${voice.category ?? ""}`)) {
+                premium.push({ ...voice, label_text: labels });
+            }
+        }
+    }
+    const free = wantFree ? (await listFreeVoices()).filter((v) => matches(`${v.id} ${v.label} ${v.language} ${v.gender}`)) : [];
+    // Sampling: write listenable audio to disk so the human can play it and pick.
+    const samples = [];
+    /** Why a sample didn't land. Never swallowed: a browse that quietly produced
+     *  no audio reads as "there was nothing to hear". */
+    const sampleErrors = [];
+    if (sample) {
+        mkdirSync(sampleDir, { recursive: true });
+        for (const voice of premium.filter((v) => v.preview_url).slice(0, sampleCount)) {
+            const out = path.join(sampleDir, `premium-${String(voice.name ?? voice.voice_id).replace(/[^a-z0-9]+/gi, "-").toLowerCase()}-${voice.voice_id}.mp3`);
+            try {
+                await downloadUrlToFile(String(voice.preview_url), out);
+                samples.push({ voice_id: String(voice.voice_id), name: String(voice.name ?? ""), tier: "premium", out });
+            }
+            catch (error) {
+                // A dead preview URL must not sink the whole browse.
+                sampleErrors.push({ voice_id: String(voice.voice_id), tier: "premium", error: String(error?.message ?? error).slice(0, 200) });
+            }
+        }
+        for (const voice of free.slice(0, sampleCount)) {
+            const out = path.join(sampleDir, `free-${voice.id}.wav`);
+            const run = await runHyperframesCommand("tts", [sampleText, "-o", out, "-v", voice.id], { stdio: "capture" });
+            if (run.code === 0 && existsSync(out)) {
+                samples.push({ voice_id: voice.id, name: voice.label, tier: "free", out });
+            }
+            else {
+                sampleErrors.push({ voice_id: voice.id, tier: "free", error: engineFailureLine(`${run.stderr}\n${run.stdout}`, `exit ${run.code}`) });
+            }
+        }
+    }
     if (ctx.json) {
-        printJson(body);
+        printJson({
+            ok: true,
+            scope,
+            billing: parsed.values["own-key"] ? "your own ElevenLabs key" : "vidfarm platform ElevenLabs connection (wallet credits)",
+            voice_library_url: libraryUrl,
+            premium_voices: premium,
+            free_voices: free,
+            samples,
+            sample_errors: sampleErrors,
+            sample_dir: sample ? sampleDir : null
+        });
         return;
     }
-    console.log(`${DIM}${voices.length} ElevenLabs voices (${body.scope ?? "platform"} account). Browse more: ${body.voice_library_url ?? "https://elevenlabs.io/app/voice-library"}${RESET}`);
-    const limit = Number(parsed.values.limit ?? "40") || 40;
-    for (const voice of voices.slice(0, limit)) {
-        const labels = voice.labels && typeof voice.labels === "object" ? Object.values(voice.labels).join(", ") : "";
-        console.log(`${GREEN}${voice.voice_id}${RESET}  ${voice.name}${labels ? ` ${DIM}(${labels})${RESET}` : ""}`);
+    if (wantPremium) {
+        console.log(scope === "user"
+            ? `${GREEN}${premium.length} premium ElevenLabs voices${RESET} ${DIM}(YOUR OWN ElevenLabs key — billed to your ElevenLabs account, no wallet spend).${RESET}`
+            : `${GREEN}${premium.length} premium ElevenLabs voices${RESET} ${DIM}— available right here through VIDFARM'S OWN ElevenLabs connection. You do NOT need an ElevenLabs account, API key, or subscription: narration on these voices runs on the platform key and is billed as vidfarm wallet credits (pennies per narration). Already have an ElevenLabs key? add --own-key.${RESET}`);
+        for (const voice of premium.slice(0, limit)) {
+            console.log(`${GREEN}${voice.voice_id}${RESET}  ${voice.name}${voice.label_text ? ` ${DIM}(${voice.label_text})${RESET}` : ""}`);
+            if (voice.preview_url)
+                console.log(`   ${DIM}preview: ${voice.preview_url}${RESET}`);
+        }
+        if (premium.length > limit)
+            console.log(`${DIM}… ${premium.length - limit} more (raise with --limit, narrow with --search "british narrator", or use --json).${RESET}`);
+        console.log(`${DIM}Browse thousands more at ${libraryUrl}.${RESET}`);
+    }
+    if (wantFree) {
+        console.log(`\n${GREEN}${free.length} free local voices${RESET} ${DIM}(Kokoro-82M, keyless, $0 forever — the default engine in cost mode minimize/hybrid).${RESET}`);
+        for (const voice of free.slice(0, limit)) {
+            console.log(`${GREEN}${voice.id}${RESET}  ${voice.label} ${DIM}(${voice.language}, ${voice.gender})${RESET}`);
+        }
+    }
+    if (!wantFree && wantPremium) {
+        console.log(`${DIM}Prefer to spend nothing? vidfarm voices --free lists the $0 local voices (--all lists both).${RESET}`);
+    }
+    if (samples.length) {
+        console.log(`\n${GREEN}Wrote ${samples.length} samples to ${sampleDir}${RESET} ${DIM}(free — premium samples are ElevenLabs' own preview clips, free samples are rendered locally; no credits spent).${RESET}`);
+        for (const s of samples)
+            console.log(`   ${DIM}${s.tier === "free" ? "free " : "prem "}${s.voice_id} — ${s.name} → ${s.out}${RESET}`);
+        console.log(`${DIM}PLAY THESE FOR THE USER and let them pick, then narrate with the id they choose.${RESET}`);
+    }
+    if (sampleErrors.length) {
+        const freeFailed = sampleErrors.filter((e) => e.tier === "free");
+        console.log(`${RED}${sampleErrors.length} sample(s) could not be produced.${RESET} ${DIM}${sampleErrors[0].error}${RESET}`);
+        if (freeFailed.length) {
+            console.log(`${DIM}Free samples render on the local Kokoro engine — install it once (\`pip install kokoro-onnx soundfile\`, or point HYPERFRAMES_PYTHON at a venv that has them). The PREMIUM voices need nothing installed: vidfarm voices --sample streams ElevenLabs' own preview clips over vidfarm's connection.${RESET}`);
+        }
+    }
+    if (!sample) {
+        console.log(`${DIM}Hear them before choosing: vidfarm voices --sample${parsed.values.free ? " --free" : ""} — downloads/renders ${sampleCount} samples to ./voice-samples (free, no credits).${RESET}`);
     }
-    if (voices.length > limit)
-        console.log(`${DIM}… ${voices.length - limit} more (raise with --limit or use --json).${RESET}`);
-    console.log(`${DIM}Use one: vidfarm tts "Hello" --cloud --voice <voice_id>${RESET}`);
+    // Interaction mode decides whose ear picks the voice. In interactive mode the
+    // human should hear samples and choose; when the mode was never set, say so
+    // rather than silently picking a default voice on their behalf.
+    if (ctx.interaction.mode === "interactive") {
+        console.log(`${DIM}[mode] Interactive — don't pick for them: sample a few, share the files, and let the user choose the voice.${RESET}`);
+    }
+    else if (!ctx.interaction.isSet) {
+        console.log(`${DIM}[mode] No interaction preference set — ask whether the user wants to hear samples and pick the voice themselves (\`vidfarm mode interactive\`), or wants you to choose one.${RESET}`);
+    }
+    console.log(`${DIM}Use one: vidfarm tts "Hello" --cloud --voice <voice_id>   (free voice: vidfarm tts "Hello" --engine local --voice <kokoro_id>)${RESET}`);
 }
 async function runMediaCommand(argv) {
     const MEDIA_TYPES = ["image", "vector", "icon", "video", "bgm", "sfx"];
@@ -8628,6 +9235,7 @@ async function runHandoffCommand(argv) {
             "out-dir": { type: "string" },
             grid: { type: "string" },
             single: { type: "boolean", default: false },
+            zoned: { type: "boolean", default: false },
             // raws
             keywords: { type: "string" },
             platforms: { type: "string" },
@@ -8650,7 +9258,8 @@ async function runHandoffCommand(argv) {
             keyColor: parsed.values["key-color"],
             outDir: parsed.values["out-dir"],
             grid: parsed.values.grid,
-            pack: parsed.values.single ? false : undefined
+            pack: parsed.values.single ? false : undefined,
+            zoned: Boolean(parsed.values.zoned)
         });
         if (json)
             return printJson({ ok: true, kind: "image", pack: !parsed.values.single, ...brief });
@@ -10139,31 +10748,52 @@ async function runQaCommand(argv) {
         options: {
             json: { type: "boolean", default: false },
             strict: { type: "boolean", default: false },
+            harness: { type: "string", multiple: true },
+            "no-harness": { type: "boolean", default: false },
+            // Pre-rename aliases; `harness` is the name everywhere else now.
             regime: { type: "string", multiple: true },
             "no-regime": { type: "boolean", default: false }
         }
     });
     const target = parsed.positionals[0];
     if (!target)
-        throw new Error("qa requires a composition path: `vidfarm qa <dir-or-composition.html> [--regime <name|path>] [--json] [--strict]`.");
+        throw new Error("qa requires a composition path: `vidfarm qa <dir-or-composition.html> [--harness <name|path>] [--json] [--strict]`.");
     const htmlPath = resolveCompositionHtmlPath(target);
     const html = readFileSync(htmlPath, "utf8");
     let report = qaCompositionHtml(html);
-    // Regime resolution, in precedence order: explicit --regime flags (stackable)
-    // → VIDFARM_QA_REGIME (a default for a whole scripting run) → the working
-    // directory's own QA_REGIME.md. --no-regime opts out of the implicit paths.
-    const explicit = parsed.values.regime ?? [];
-    const fromEnv = (process.env.VIDFARM_QA_REGIME ?? "").split(",").map((entry) => entry.trim()).filter(Boolean);
-    let regimeRefs = explicit.length ? explicit : fromEnv;
-    if (!regimeRefs.length && !parsed.values["no-regime"]) {
-        const discovered = discoverRegime(path.dirname(htmlPath));
-        if (discovered)
-            regimeRefs = [discovered];
-    }
-    if (regimeRefs.length) {
-        const facts = extractCompositionFacts(html);
-        report = mergeRegimeIntoReport(report, regimeRefs.map((ref) => loadAndEvaluateRegime(ref, facts)));
+    // Harness resolution, in precedence order: explicit --harness flags
+    // (stackable) → VIDFARM_HARNESS (a default for a whole scripting run) → the
+    // working directory's own HARNESS.md. --no-harness opts out of the implicit
+    // paths. The `regime`-spelled forms are the pre-rename aliases.
+    const explicit = [
+        ...(parsed.values.harness ?? []),
+        ...(parsed.values.regime ?? [])
+    ];
+    const envValue = process.env.VIDFARM_HARNESS ?? process.env.VIDFARM_QA_REGIME ?? "";
+    const fromEnv = envValue.split(",").map((entry) => entry.trim()).filter(Boolean);
+    let harnessRefs = explicit.length ? explicit : fromEnv;
+    const optedOut = Boolean(parsed.values["no-harness"]) || Boolean(parsed.values["no-regime"]);
+    if (!harnessRefs.length && !optedOut) {
+        const discovered = discoverHarness(path.dirname(htmlPath));
+        if (discovered) {
+            harnessRefs = [discovered];
+            if (isLegacyHarnessFilename(discovered)) {
+                console.log(`${DIM}Using ${path.basename(discovered)} — the file is now called ${HARNESS_FILENAME}. Rename it when convenient; both are read.${RESET}`);
+            }
+        }
     }
+    if (harnessRefs.length) {
+        const facts = extractCompositionFacts(html);
+        report = mergeHarnessIntoReport(report, harnessRefs.map((ref) => loadAndEvaluateHarness(ref, facts)));
+    }
+    // The directive is on the report already; re-issue it with THIS work dir (and
+    // an existing render, if there is one) substituted into the commands.
+    const workDir = path.dirname(htmlPath);
+    const render = newestRenderIn(workDir);
+    report = {
+        ...report,
+        watch_the_video: watchTheVideoDirective(pastablePath(workDir), render ? pastablePath(render) : null)
+    };
     if (parsed.values.json) {
         printJson(report);
         if (!report.ok && parsed.values.strict)
@@ -10173,13 +10803,13 @@ async function runQaCommand(argv) {
     const body = formatQaReport(report, { red: RED, yellow: YELLOW, green: GREEN, dim: DIM, reset: RESET });
     if (body)
         console.log(body);
-    for (const evaluation of report.regimes ?? []) {
-        console.log(formatRegimeReport(evaluation, { green: GREEN, red: RED, yellow: YELLOW, dim: DIM, reset: RESET }));
+    for (const evaluation of report.harnesses ?? []) {
+        console.log(formatHarnessReport(evaluation, { green: GREEN, red: RED, yellow: YELLOW, dim: DIM, reset: RESET }));
     }
     const scope = `${report.checked.layers} layer(s), ${report.checked.text_layers} text layer(s)${report.checked.canvas ? `, ${report.checked.canvas}` : ""}`;
-    const graded = (report.regimes ?? []).length > 0;
+    const graded = (report.harnesses ?? []).length > 0;
     if (report.verdict === "clean") {
-        console.log(`${GREEN}✓ no HTML slop found${graded ? ", regime checks passed" : ""}${RESET} ${DIM}— ${scope} — ${htmlPath}${RESET}`);
+        console.log(`${GREEN}✓ no HTML slop found${graded ? ", harness checks passed" : ""}${RESET} ${DIM}— ${scope} — ${htmlPath}${RESET}`);
     }
     else if (report.verdict === "warnings") {
         console.log(`${YELLOW}! ${report.warnings.length} warning(s), no slop${RESET} ${DIM}— ${scope} — ${htmlPath}${RESET}`);
@@ -10188,81 +10818,376 @@ async function runQaCommand(argv) {
         console.log(`${RED}✗ ${report.errors.length} ${graded ? "issue(s)" : "slop issue(s)"}${RESET}, ${report.warnings.length} warning(s) ${DIM}— ${scope} — ${htmlPath}${RESET}`);
         console.log(`${DIM}This is feedback, not a gate — fix what's real and re-run. A deliberate stylistic choice that trips a rule is fine to ignore.${RESET}`);
     }
-    const pendingReview = (report.regimes ?? []).reduce((total, evaluation) => total + evaluation.review_items.length, 0);
+    const pendingReview = (report.harnesses ?? []).reduce((total, evaluation) => total + evaluation.review_items.length, 0);
     if (pendingReview) {
-        console.log(`${DIM}${pendingReview} regime item(s) above are NOT machine-checkable — answer them yourself before you call this video done.${RESET}`);
+        console.log(`${DIM}${pendingReview} harness item(s) above are NOT machine-checkable — answer them yourself before you call this video done.${RESET}`);
     }
     else if (!graded) {
         // Everything above is mechanical. Structure — hook, loop, payoff, bait — is
         // what actually decides whether the video travels, and nothing here checks
         // it. Say so rather than letting a green tick imply the video is good.
         console.log(`${DIM}Checked mechanics only — nothing here grades the hook, the loop, the payoff, or the bait.${RESET}`);
-        console.log(`${DIM}Structure: vidfarm regime show hooks   ·   grade this video: vidfarm qa <dir> --regime short-form${RESET}`);
+        console.log(`${DIM}Structure: vidfarm harness show hooks   ·   grade this video: vidfarm qa <dir> --harness short-form${RESET}`);
     }
+    // Last word on every run, clean ones included: this tool never saw the video.
+    console.log(formatWatchTheVideoNotice(report.watch_the_video, { yellow: YELLOW, dim: DIM, reset: RESET, bold: BOLD }));
     if (!report.ok && parsed.values.strict)
         process.exitCode = 1;
 }
-// `vidfarm regime <list|show|init>` — the QA_REGIME.md surface. A regime is the
-// director's OWN quality contract for one template style; the built-ins are
-// starting points to copy and edit, never a house style to conform to.
-async function runRegimeCommand(argv) {
+/** Shortest form of a path the caller can paste back: relative when it's under cwd. */
+function pastablePath(target) {
+    const rel = path.relative(process.cwd(), target);
+    if (!rel)
+        return ".";
+    return rel.startsWith("..") ? target : `./${rel}`;
+}
+/** Newest rendered MP4 in `<dir>/renders`, if the director has rendered yet. */
+function newestRenderIn(dir) {
+    const rendersDir = path.join(dir, "renders");
+    try {
+        const candidates = readdirSync(rendersDir)
+            .filter((entry) => entry.toLowerCase().endsWith(".mp4"))
+            .map((entry) => {
+            const full = path.join(rendersDir, entry);
+            return { full, mtime: statSync(full).mtimeMs };
+        })
+            .sort((a, b) => b.mtime - a.mtime);
+        return candidates.length ? candidates[0].full : null;
+    }
+    catch {
+        return null;
+    }
+}
+// `vidfarm harness <list|show|init|derive|check>` — the HARNESS.md surface.
+//
+// A harness is the reusable apparatus for ONE format or template: what makes it
+// special, written down so an agent can reproduce it without the director in
+// the room. Three director phrasings all land here:
+//
+//   "create me a harness"                        → init  (copy a base, then EDIT)
+//   "update the harness for this format"         → edit the file in place; the
+//                                                  CLI just reads and grades it
+//   "give me the harness for this template_id"   → derive (the DECOMPOSITION,
+//                                                  distilled into a harness)
+//
+// The built-ins are starting points to copy and edit, never a house style to
+// conform to.
+async function runHarnessCommand(argv) {
     const sub = argv[0];
     const parsed = parseArgs({
         args: argv.slice(1),
         allowPositionals: true,
         options: {
-            json: { type: "boolean", default: false },
+            // `derive` talks to the API to fetch a fork's decompose output, so this
+            // command carries the standard auth/host flags alongside its own.
+            ...commonOptions(),
             out: { type: "string" },
             dir: { type: "string" },
+            dna: { type: "string" },
+            refetch: { type: "boolean", default: false },
             force: { type: "boolean", default: false }
         }
     });
     const json = Boolean(parsed.values.json);
     if (!sub || sub === "list") {
-        const builtins = listBuiltinRegimes();
+        const builtins = listBuiltinHarnesses();
         if (json)
-            return printJson({ regimes: builtins.map(({ name, path: file, video_type }) => ({ name, path: file, video_type })) });
-        console.log(`${DIM}Built-in QA regimes — copy one next to your work, then edit it:${RESET}`);
+            return printJson({ harnesses: builtins.map(({ name, path: file, video_type }) => ({ name, path: file, video_type })) });
+        console.log(`${DIM}Built-in harnesses — copy one next to your work, then edit it:${RESET}`);
         for (const entry of builtins) {
             console.log(`  ${GREEN}${entry.name}${RESET} ${DIM}${entry.video_type ?? ""}${RESET}`);
         }
-        console.log(`\n${DIM}vidfarm regime init <name> --out ./work/QA_REGIME.md${RESET}`);
-        console.log(`${DIM}vidfarm qa ./work --regime <name|path>   (repeatable — regimes stack)${RESET}`);
-        console.log(`${DIM}A regime is YOURS: any QA_REGIME.md anywhere on disk can be passed in. Format: .agents/skills/vidfarm/regimes/README.md${RESET}`);
+        console.log(`\n${DIM}vidfarm harness init <name> --out ./work/${HARNESS_FILENAME}${RESET}`);
+        console.log(`${DIM}vidfarm harness derive <forkId>          (a decomposed template → a harness)${RESET}`);
+        console.log(`${DIM}vidfarm qa ./work --harness <name|path>  (repeatable — harnesses stack)${RESET}`);
+        console.log(`${DIM}A harness is YOURS: any ${HARNESS_FILENAME} anywhere on disk can be passed in. Format: .agents/skills/vidfarm/harnesses/README.md${RESET}`);
         return;
     }
     if (sub === "show") {
         const ref = parsed.positionals[0];
         if (!ref)
-            throw new Error("regime show requires a name or path: `vidfarm regime show <name|path>`.");
-        const file = resolveRegimePath(ref);
+            throw new Error("harness show requires a name or path: `vidfarm harness show <name|path>`.");
+        const file = resolveHarnessPath(ref);
         const raw = readFileSync(file, "utf8");
+        const doc = parseHarness(raw, file);
+        // `--dna visual` prints ONE strand. A harness that documents five kinds of
+        // DNA is long; an agent re-theming the look only needs the visual strand.
+        const wanted = parsed.values.dna ? String(parsed.values.dna).toLowerCase().replace(/[^a-z0-9]+/g, "_") : null;
+        if (wanted) {
+            const strand = doc.dna.find((entry) => entry.key === wanted || entry.key === `${wanted}_dna` || entry.key.startsWith(wanted));
+            if (!strand) {
+                throw new Error(`"${doc.name}" documents no ${wanted} strand. It has: ${doc.dna.map((entry) => entry.key).join(", ") || "(no DNA sections)"}.`);
+            }
+            if (json)
+                return printJson(strand);
+            console.log(`## ${strand.heading}\n\n${strand.body}`);
+            return;
+        }
         if (json)
-            return printJson(parseRegime(raw, file));
+            return printJson(doc);
         console.log(raw);
         return;
     }
-    if (sub === "init") {
-        const ref = parsed.positionals[0];
-        if (!ref)
-            throw new Error("regime init requires a built-in name or source path: `vidfarm regime init short-form --out ./work/QA_REGIME.md`.");
-        const source = resolveRegimePath(ref);
+    if (sub === "init" || sub === "new" || sub === "create") {
+        const ref = parsed.positionals[0] ?? "short-form";
+        const source = resolveHarnessPath(ref);
         const outPath = parsed.values.out
             ? path.resolve(String(parsed.values.out))
-            : path.resolve(String(parsed.values.dir ?? "."), "QA_REGIME.md");
+            : path.resolve(String(parsed.values.dir ?? "."), HARNESS_FILENAME);
         if (existsSync(outPath) && !parsed.values.force) {
             throw new Error(`${outPath} already exists. Pass --force to overwrite (you will lose your edits).`);
         }
         mkdirSync(path.dirname(outPath), { recursive: true });
         writeFileSync(outPath, readFileSync(source, "utf8"), "utf8");
         if (json)
-            return printJson({ ok: true, regime: ref, source, path: outPath });
+            return printJson({ ok: true, harness: ref, source, path: outPath });
         console.log(`${GREEN}${outPath}${RESET} ${DIM}← ${path.basename(source)}${RESET}`);
         console.log(`${DIM}Now EDIT it — delete what doesn't apply, add what makes your format yours (start with the audience line).${RESET}`);
         console.log(`${DIM}Then: vidfarm qa ${path.dirname(outPath)}${RESET}`);
         return;
     }
-    throw new Error(`Unknown regime subcommand "${sub}". Use: list | show <name|path> | init <name> [--out <path>]`);
+    if (sub === "derive" || sub === "from" || sub === "decompose") {
+        const ref = parsed.positionals[0];
+        if (!ref) {
+            throw new Error("harness derive requires a fork/template id or a pulled work dir: `vidfarm harness derive <forkId|dir> [--out ./work/HARNESS.md]`.");
+        }
+        await runHarnessDerive(ref, {
+            outPath: parsed.values.out ? path.resolve(String(parsed.values.out)) : null,
+            dirOverride: parsed.values.dir ? path.resolve(String(parsed.values.dir)) : null,
+            refetch: Boolean(parsed.values.refetch),
+            force: Boolean(parsed.values.force),
+            values: parsed.values,
+            json
+        });
+        return;
+    }
+    if (sub === "check" || sub === "qa" || sub === "grade") {
+        // The same engine as `vidfarm qa`, reachable under the noun the director
+        // used. One implementation, two doors.
+        const rest = argv.slice(1);
+        await runQaCommand(rest.length ? rest : ["."]);
+        return;
+    }
+    throw new Error(`Unknown harness subcommand "${sub}". Use: list | show <name|path> [--dna <strand>] | init <name> [--out <path>] | derive <forkId|dir> | check <dir>`);
+}
+/**
+ * `vidfarm harness derive <forkId|dir>` — THE DECOMPOSITION, as a harness.
+ *
+ * When a director says "give me the harness for this template_id", this is what
+ * they mean: the decompose pass already extracted the template's DNA into JSON
+ * (video-context viral_dna, editor-harness, replication-harness,
+ * scene-annotations), and this folds those strands into ONE editable Markdown
+ * doc laid out the way every other harness is — so a derived harness and a
+ * hand-written one are the same artifact, gradeable by the same `vidfarm qa`.
+ *
+ * It writes the DNA it FOUND and says "unknown" where the decompose pass has
+ * nothing, rather than inventing a plausible strand. A harness that quietly
+ * fabricates the thing the director asked for is worse than a short one.
+ */
+async function runHarnessDerive(ref, opts) {
+    const asDir = path.resolve(ref);
+    const isLocalDir = existsSync(asDir) && statSync(asDir).isDirectory();
+    let dir = opts.dirOverride ?? (isLocalDir ? asDir : null);
+    let forkId = isLocalDir ? null : ref;
+    if (!dir) {
+        // A bare id: pull the decompose artifacts down the same way `vidfarm pull`
+        // does, into the same cache dir, so a later `pull` is a no-op.
+        const ctx = commonContext(opts.values);
+        dir = path.resolve(process.cwd(), path.join(".vidfarm", ref));
+        mkdirSync(dir, { recursive: true });
+        await fetchCompositionFiles({ host: ctx.host, forkId: ref, dir, apiKey: ctx.auth.apiKey, shareToken: ctx.auth.shareToken, refetch: opts.refetch });
+    }
+    const videoContext = readJsonFile(path.join(dir, "video-context.json"));
+    const editorHarness = readJsonFile(path.join(dir, "editor-harness.json"));
+    const replicationHarness = readJsonFile(path.join(dir, "replication-harness.json"));
+    if (!videoContext && !editorHarness && !replicationHarness) {
+        throw new Error(`No decompose output in ${dir} — nothing to derive a harness from. Run \`vidfarm decompose ${forkId ?? "<forkId>"}\` first, ` +
+            `then re-run. (A harness can also be written from scratch: \`vidfarm harness init short-form\`.)`);
+    }
+    const markdown = buildDerivedHarnessMarkdown({
+        ref,
+        forkId,
+        dir,
+        videoContext,
+        editorHarness,
+        replicationHarness,
+        sceneAnnotations: readJsonFile(path.join(dir, "scene-annotations.json")),
+        compositionHtml: existsSync(path.join(dir, "composition.html")) ? readFileSync(path.join(dir, "composition.html"), "utf8") : null
+    });
+    const outPath = opts.outPath ?? path.join(dir, HARNESS_FILENAME);
+    if (existsSync(outPath) && !opts.force) {
+        throw new Error(`${outPath} already exists. Pass --force to overwrite (you will lose your edits), or --out <path> to write elsewhere.`);
+    }
+    mkdirSync(path.dirname(outPath), { recursive: true });
+    writeFileSync(outPath, markdown, "utf8");
+    const parsedOut = parseHarness(markdown, outPath);
+    if (opts.json) {
+        return printJson({
+            ok: true,
+            source: forkId ?? dir,
+            dir,
+            path: outPath,
+            dna: parsedOut.dna.map((strand) => strand.key),
+            checks: Object.keys(parsedOut.checks),
+            review_items: parsedOut.review_items.length
+        });
+    }
+    console.log(`${GREEN}${outPath}${RESET} ${DIM}← decomposition of ${forkId ?? path.basename(dir)}${RESET}`);
+    console.log(`${DIM}DNA written: ${parsedOut.dna.map((strand) => strand.key).join(", ") || "none"}${RESET}`);
+    console.log(`${DIM}${Object.keys(parsedOut.checks).length} machine check(s), ${parsedOut.review_items.length} review item(s).${RESET}`);
+    console.log(`${DIM}This is a STARTING POINT, not a verdict — read it, delete what the decompose pass guessed wrong, and add what only you know.${RESET}`);
+    console.log(`${DIM}Then: vidfarm qa ${pastablePath(dir)}${RESET}`);
+}
+/** Fold the decompose JSON strands into the standard harness layout. */
+function buildDerivedHarnessMarkdown(input) {
+    const viralDna = (input.videoContext?.viral_dna && typeof input.videoContext.viral_dna === "object"
+        ? input.videoContext.viral_dna : null);
+    const harness = (input.editorHarness?.harness && typeof input.editorHarness.harness === "object"
+        ? input.editorHarness.harness : null);
+    const replication = (input.replicationHarness?.harness && typeof input.replicationHarness.harness === "object"
+        ? input.replicationHarness.harness : null);
+    const sub = (parent, key) => parent && parent[key] && typeof parent[key] === "object" && !Array.isArray(parent[key])
+        ? parent[key]
+        : null;
+    const emotional = sub(viralDna, "emotional_punch") ?? sub(harness, "emotional");
+    const pacing = sub(harness, "pacing");
+    const typography = sub(harness, "typography");
+    const broll = sub(harness, "broll");
+    const transitions = sub(harness, "transitions");
+    const audio = sub(harness, "audio");
+    const staticVsPivot = sub(viralDna, "static_vs_pivot");
+    const annotations = Array.isArray(input.sceneAnnotations?.annotations)
+        ? input.sceneAnnotations.annotations
+        : [];
+    const scenes = Array.isArray(harness?.scenes) ? harness.scenes : [];
+    const value = (raw) => readJsonString(raw) || "_unknown — the decompose pass didn't record this; fill it in._";
+    const bullets = (items, empty) => items.length ? items.map((item) => `- ${item}`).join("\n") : `- ${empty}`;
+    // The composition itself settles the two checks nobody should have to type.
+    const info = input.compositionHtml ? inspectComposition(input.compositionHtml) : null;
+    const durationCheck = info?.duration_seconds ? `${Math.max(1, Math.floor(info.duration_seconds * 0.7))}-${Math.ceil(info.duration_seconds * 1.3)}` : null;
+    const beatRows = scenes.slice(0, 12).map((scene) => {
+        const role = readJsonString(scene.role) || "beat";
+        const importance = readJsonString(scene.importance);
+        const bias = readJsonString(scene.edit_bias);
+        const keep = scene.must_keep === true ? " **must-keep**" : "";
+        return `**${role}**${importance ? ` (${importance})` : ""}${keep}${bias ? ` — ${bias}` : ""}`;
+    });
+    const mustPreserve = annotations
+        .flatMap((entry) => readJsonStringList(entry.must_preserve, 3).map((item) => {
+        const slug = readJsonString(entry.scene_slug);
+        return slug ? `${slug}: ${item}` : item;
+    }))
+        .slice(0, 8);
+    const recommendedStrategy = readJsonString(replication?.recommended_strategy) || "cheap_efficient";
+    const cheapPlan = sub(replication, "cheap");
+    const qualityPlan = sub(replication, "quality");
+    const motionStyle = sub(replication, "motion_style");
+    const frontMatter = [
+        "---",
+        `name: ${(input.forkId ?? path.basename(input.dir)).replace(/[^A-Za-z0-9_-]/g, "-")}`,
+        `video_type: ${readJsonString(viralDna?.trend_tagline) || readJsonString(harness?.one_liner) || "derived from a decomposed template"}`,
+        `derived_from: decompose`,
+        input.forkId ? `source_template_id: ${input.forkId}` : null,
+        "checks:",
+        durationCheck ? `  duration_sec: ${durationCheck}` : null,
+        info?.aspect_ratio ? `  aspect: ${info.aspect_ratio}` : null,
+        "  first_frame_visual: required",
+        "  font_regime: required",
+        "  safe_zone: required",
+        "---"
+    ].filter(Boolean).join("\n");
+    return `${frontMatter}
+
+# Harness: ${readJsonString(viralDna?.trend_tagline) || readJsonString(harness?.one_liner) || input.forkId || path.basename(input.dir)}
+
+Derived from the decomposition of ${input.forkId ? `\`${input.forkId}\`` : path.basename(input.dir)}. **This is a first draft written by a model that watched the source, not a verdict.** Read every strand, delete what it got wrong, and add what only you know — the audience, the offer, the banned vocabulary. A harness nobody edited is about the source video, not about your videos.
+
+## Viral DNA — why the source travelled
+
+- **Trend/format:** ${value(viralDna?.trend_tagline)}
+- **Hook:** ${value(viralDna?.hook)}
+- **Retention mechanic:** ${value(viralDna?.retention ?? viralDna?.retention_mechanic)}
+- **Payoff:** ${value(viralDna?.payoff)}
+- **Core emotion:** ${value(emotional?.core_emotion ?? emotional?.target_feeling)}
+- **Mechanism:** ${value(emotional?.mechanism)}
+- **Contrast:** ${value(emotional?.contrast)}
+
+**Rebuild each charge for the new subject — never flatten the loop into a product statement.** The four charges (hook / loop / payoff / bait) are the craft behind this section: \`vidfarm harness show hooks\`.
+
+- [ ] Does my version have its OWN hook, or did I keep the source's sentence with the nouns swapped?
+- [ ] Does the curiosity loop close inside this video, at a timestamp I can name?
+- [ ] Is the withheld answer one the viewer genuinely can't supply themselves?
+
+## Visual DNA — how it looks and cuts
+
+- **Cut rhythm:** ${value(pacing?.cut_rhythm)}${readJsonString(pacing?.avg_scene_seconds) ? ` (~${readJsonString(pacing?.avg_scene_seconds)}s per scene)` : ""}
+- **Energy curve:** ${value(pacing?.energy_curve)}
+- **Caption style:** ${value(typography?.caption_style)} — placement ${readJsonString(typography?.placement) || "unrecorded"}, ${readJsonString(typography?.text_density) || "density unrecorded"}
+- **Font character:** ${value(typography?.font_character)}
+- **B-roll:** ${value(broll?.reliance)}${readJsonString(broll?.sourcing) ? ` — sourced ${readJsonString(broll?.sourcing)}` : ""}${readJsonString(broll?.cadence) ? `, cadence ${readJsonString(broll?.cadence)}` : ""}
+- **Transitions:** default ${readJsonString(transitions?.default) || "unrecorded"}, in ${readJsonString(transitions?.intro) || "unrecorded"}, out ${readJsonString(transitions?.outro) || "unrecorded"}
+- **Motion feel:** ${value(motionStyle?.animation_feel)}
+
+- [ ] One type scale, one accent colour, one illustration style across every beat — checked on a contact sheet, not scene by scene (\`vidfarm stills . --sheet\`).
+- [ ] Caption colour and plate chosen by MEASURING the composited background, not by habit — one treatment for the whole video.
+
+## Structural DNA — the beats
+
+${bullets(beatRows, "_no scene roles recorded — run `vidfarm decompose` with the harness pass._")}
+
+**Load-bearing beats (do not reskin past these):**
+${bullets(mustPreserve.length ? mustPreserve : readJsonStringList(harness?.important_scenes, 6), "_none recorded._")}
+
+- [ ] Every must-keep beat kept its timing, role, and caption cadence — I swapped the subject, not the structure.
+
+## Audio DNA — voice, bed, timing
+
+- **Voiceover:** ${value(audio?.voiceover)}
+- **Music:** ${value(audio?.music)}
+- **SFX:** ${value(audio?.sfx)}
+- **Captions from:** ${value(audio?.captions_from)}
+- **Comedic timing:** ${value(emotional?.comedic_timing)}
+- **Intonation / delivery:** ${value(emotional?.intonation ?? emotional?.delivery)}
+
+- [ ] The held beat / pause / hard cut that sells the joke survived the re-cut.
+- [ ] Speech sits ~12–15 dB over the bed across the actual word spans — MEASURED, not "sounds fine".
+
+## Build DNA — which paintbrush per beat
+
+Recommended strategy: **${recommendedStrategy}**${readJsonString(replication?.recommendation_reason) ? ` — ${readJsonString(replication?.recommendation_reason)}` : ""}
+
+- **Cheap mix:** ${value(cheapPlan?.method_mix ?? cheapPlan?.one_liner)}
+- **Best-quality mix:** ${value(qualityPlan?.method_mix ?? qualityPlan?.one_liner)}
+- **Free-tier path:** ${value(replication?.free_tier_note)}
+
+**Do these in hyperframes (HTML/CSS/JS), never AI video:**
+${bullets(readJsonStringList(motionStyle?.hyperframes_candidates, 6), "all on-screen text and graphic overlays")}
+
+**Guardrails the replication pass flagged:**
+${bullets(readJsonStringList(replication?.viral_dna_guardrails, 6), "_none recorded._")}
+
+## Re-theming — what's static, what pivots
+
+- **Summary:** ${value(staticVsPivot?.summary)}
+- **Scenes:** ${value(sub(staticVsPivot, "scene_replacement")?.overall)}
+- **Narration:** ${value(sub(staticVsPivot, "narration")?.overall)}
+- **Music:** ${value(sub(staticVsPivot, "music")?.overall)}
+- **Captions:** ${value(sub(staticVsPivot, "captions")?.overall)}
+
+## Rules for this format
+
+${bullets(readJsonStringList(harness?.do, 6).map((item) => `DO: ${item}`).concat(readJsonStringList(harness?.dont, 6).map((item) => `DON'T: ${item}`)), "_none recorded — write yours here, each with the reason attached._")}
+
+> Every rule you add needs its **why** on the same line. A rule whose reason is missing gets argued away by the next agent that reads it.
+
+## Whole-video review — do this last
+
+Nothing above can see the finished video. Tile ~12 stills into one contact sheet and read it as a single image (\`vidfarm stills . --sheet\`): margins that shift between beats, three type sizes, an accent colour that wanders, N identically-long beats, a jarring join, a dead band under top-anchored content. Those are sequence-level defects, invisible to every per-scene check and to the agent that built it. Compare two frames from DIFFERENT scenes — a frozen render passes duration, frame count and every one-frame check. Method: \`references/reviewing-renders.md\`.
+
+- [ ] I read a contact sheet of the finished render, not just stills of the scenes I was working on.
+- [ ] I compared two frames from different scenes and they differ.
+- [ ] I reported what I MEASURED separately from what I JUDGED.
+`;
 }
 // `vidfarm stills <dir|composition.html>` — render PNG stills of the CURRENT
 // composition in-process (the agent's visual self-verification loop).
@@ -10351,7 +11276,134 @@ async function fetchSkillContents(host, target) {
     }
     throw new Error(`Could not fetch ${target.bundled} from ${host} and no bundled copy was found.`);
 }
+/** The installed devcli's own version — the thing the bundled pack is pinned to. */
+function devcliVersion() {
+    const pkgPath = locateBundledSkill("package.json");
+    if (!pkgPath)
+        return null;
+    try {
+        const version = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `vidfarm skill <ls|show|search|print|path>` — READ the skill pack that ships
+ * inside this devcli, with no network and no account.
+ *
+ * The pack is already in the npm tarball (`.agents/skills/**` is in
+ * package.json `files`), so every install has the full director knowledge on
+ * disk. Before this, nothing could read it without `vidfarm skills add`
+ * (installs into a project) or a fetch — which meant going online to learn how
+ * to use a local-first CLI.
+ *
+ * The bundled copy is version-pinned to this CLI, which is the correct pairing.
+ * It is documentation, NOT entitlement: the paid primitives it documents (AI
+ * generation, hosted render, social recycle, media download, marketplace) still
+ * require `vidfarm login` and a cloud call. The free-local half (clipping,
+ * hyperframes, `vidfarm serve` render, qa, harnesses, dedupe, Kokoro TTS) is
+ * genuinely offline. Every surface below says so rather than letting an offline
+ * read imply an offline entitlement.
+ */
+async function runSkillDocsCommand(sub, argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { json: { type: "boolean", default: false }, pack: { type: "string" }, limit: { type: "string" } }
+    });
+    const json = Boolean(parsed.values.json);
+    const pack = String(parsed.values.pack ?? DEFAULT_PACK);
+    const ref = parsed.positionals[0];
+    if (sub === "path" || sub === "where") {
+        const dir = bundledPackDir(pack);
+        if (!dir)
+            throw new Error(`No bundled "${pack}" pack found next to this devcli install.`);
+        if (json)
+            return printJson({ ok: true, pack, path: dir, offline: true }), true;
+        console.log(dir);
+        return true;
+    }
+    if (sub === "ls" || sub === "list" || sub === "files" || sub === "index") {
+        const docs = listPackDocs(pack);
+        if (!docs.length)
+            throw new Error(`No bundled "${pack}" pack found next to this devcli install. Fetch it with \`vidfarm skills add ${pack}\`.`);
+        if (json)
+            return printJson({ ok: true, pack, source: "bundled", offline: true, files: docs.map(({ rel, lines, bytes }) => ({ path: rel, lines, bytes })) }), true;
+        console.log(`${DIM}Bundled ${pack} skill pack — pinned to devcli ${devcliVersion() ?? "(this install)"}, read offline, no account:${RESET}`);
+        let group = "";
+        for (const doc of docs) {
+            const dir = doc.rel.includes("/") ? doc.rel.slice(0, doc.rel.indexOf("/")) : "";
+            if (dir !== group) {
+                group = dir;
+                if (dir)
+                    console.log(`  ${BOLD}${dir}/${RESET}`);
+            }
+            console.log(`    ${GREEN}${doc.rel.padEnd(46)}${RESET} ${DIM}${String(doc.lines).padStart(4)} ln${RESET}`);
+        }
+        console.log(`\n${DIM}vidfarm skill show <path|shorthand>   ·   vidfarm skill search "<term>"${RESET}`);
+        console.log(`${DIM}Start with SKILL.md — its File Index says which file answers what.${RESET}`);
+        console.log(`${DIM}This is documentation, not entitlement: the free-local half (clips, hyperframes, \`vidfarm serve\` render, qa, harnesses, dedupe, local TTS) runs offline; AI generation, hosted render, recycle, download and marketplace still need \`vidfarm login\` and a network call.${RESET}`);
+        return true;
+    }
+    if (sub === "show" || sub === "read" || sub === "cat") {
+        if (!ref)
+            throw new Error('skill show requires a file: `vidfarm skill show references/primitives.md` (shorthand like "primitives" works too).');
+        let resolved;
+        try {
+            resolved = readPackDoc(ref, pack);
+        }
+        catch (error) {
+            // An ambiguous shorthand is a normal outcome, not a crash — "hooks"
+            // legitimately names both the craft reference and the harness. Print the
+            // choice instead of a stack trace, and don't guess on the caller's behalf.
+            if (!(error instanceof AmbiguousDocRef))
+                throw error;
+            if (json)
+                return printJson({ ok: false, pack, ref, ambiguous: error.candidates }), true;
+            console.log(`${YELLOW}"${ref}" matches ${error.candidates.length} files${RESET} ${DIM}— name one:${RESET}`);
+            for (const candidate of error.candidates)
+                console.log(`  vidfarm skill show ${GREEN}${candidate}${RESET}`);
+            process.exitCode = 1;
+            return true;
+        }
+        const { doc, contents } = resolved;
+        if (json)
+            return printJson({ ok: true, pack, path: doc.rel, lines: doc.lines, source: "bundled", contents }), true;
+        process.stdout.write(contents.endsWith("\n") ? contents : `${contents}\n`);
+        return true;
+    }
+    if (sub === "search" || sub === "grep" || sub === "find") {
+        if (!ref)
+            throw new Error('skill search requires a term: `vidfarm skill search greenscreen`.');
+        const limit = Number(parsed.values.limit ?? 40);
+        const matches = searchPackDocs(ref, { name: pack, limit: Number.isFinite(limit) ? limit : 40 });
+        if (json)
+            return printJson({ ok: true, pack, term: ref, matches }), true;
+        if (!matches.length) {
+            console.log(`${DIM}No match for "${ref}" in the bundled ${pack} pack. \`vidfarm skill ls\` lists every file.${RESET}`);
+            return true;
+        }
+        let current = "";
+        for (const match of matches) {
+            if (match.rel !== current) {
+                current = match.rel;
+                console.log(`${BOLD}${match.rel}${RESET}`);
+            }
+            console.log(`  ${DIM}${String(match.line).padStart(4)}${RESET}  ${match.text}`);
+        }
+        console.log(`\n${DIM}${matches.length} match(es). Open one: vidfarm skill show <path>${RESET}`);
+        return true;
+    }
+    return false;
+}
 async function runUpdateSkillCommand(argv) {
+    // Read-only subcommands come first and never touch the network or auth, so
+    // `vidfarm skill ls` works on a plane with no credential configured.
+    const sub = argv[0] ?? "";
+    if (sub && !sub.startsWith("-") && await runSkillDocsCommand(sub, argv.slice(1)))
+        return;
     const parsed = parseArgs({
         args: argv,
         allowPositionals: false,
@@ -10360,14 +11412,21 @@ async function runUpdateSkillCommand(argv) {
             global: { type: "boolean", default: false },
             dir: { type: "string" },
             platform: { type: "boolean", default: false },
-            print: { type: "boolean", default: false }
+            print: { type: "boolean", default: false },
+            remote: { type: "boolean", default: false }
         }
     });
     const ctx = commonContext(parsed.values);
     const skillNames = ["vidfarm", ...(parsed.values.platform ? ["vidfarm-platform"] : [])];
     if (parsed.values.print) {
+        // BUNDLED FIRST. The tarball's copy is pinned to this CLI version, which is
+        // the pairing that actually works — a newer skill against an older binary
+        // is the usual cause of "the skill says to do X but the command 404s".
+        // `--remote` opts into the host's latest when that's what you want.
         for (const name of skillNames) {
-            const { contents } = await fetchSkillContents(ctx.host, SKILL_TARGETS[name]);
+            const target = SKILL_TARGETS[name];
+            const bundled = parsed.values.remote ? null : locateBundledSkill(target.bundled);
+            const contents = bundled ? readFileSync(bundled, "utf8") : (await fetchSkillContents(ctx.host, target)).contents;
             process.stdout.write(contents.endsWith("\n") ? contents : `${contents}\n`);
         }
         return;