@officexapp/vidfarm-devcli 0.21.27 → 0.21.29

package/dist/src/cli.js

@@ -19,7 +19,10 @@ 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 { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders, cropImageRegion } from "./devcli/greenscreen-local.js";
+import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor } from "./devcli/sticker-pack.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
@@ -29,6 +32,9 @@ import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError,
 import { startLocalFrontendServer, serveShellsPresent } from "./devcli/local-frontend-server.js";
 import { readStoredAuth, writeStoredAuth, clearStoredAuth, hostsMatch } from "./devcli/auth-store.js";
 import { CostModeBlockedError, assertBilledAllowed, clearStoredCostMode, costModeExplainer, costModeSummaryLine, normalizeCostMode, resolveCostMode, writeStoredCostMode, COST_MODE_BLURB, COST_MODE_DISPLAY_LIST, costModeDisplayName } from "./devcli/cost-mode.js";
+import { INTERACTION_MODES, INTERACTION_MODE_BLURB, clearStoredInteractionMode, interactionModeExplainer, interactionModeSummaryLine, interactiveOfferLine, normalizeInteractionMode, resolveInteractionMode, writeStoredInteractionMode } from "./devcli/interaction-mode.js";
+import { buildImageHandoff, buildRawsHandoff, formatHandoff } from "./devcli/handoff.js";
+import { STORYBOARD_FILENAME, readStoryboard, renderStoryboardScaffold, storyboardStage } from "./devcli/storyboard.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
 // `serve` command boots the FULL editor locally (single origin, disk-backed
 // records + storage) so power users edit compositions on disk while a browser
@@ -89,6 +95,38 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
                             --clear forgets it · --note "<why>" annotates the save.
                             Override per-run with --cost-mode <m> / VIDFARM_COST_MODE;
                             in "minimize" a billed op is refused until you add --yes.
+  mode [interactive|autonomous]  Show or set whether the HUMAN is in the loop —
+                            a SECOND axis, independent of cost mode (every cost
+                            mode runs either way; quality usually goes UP in
+                            interactive, most of all in minimize).
+                            interactive = at checkpoints the user gets a copy-paste
+                            image prompt for a FREE web generator (→ sticker packs)
+                            or a keyword list to hand-source raw clips.
+                            autonomous  = agent finishes solo within the budget.
+                            No arg = show current + explain. --clear forgets it ·
+                            per-run: --interactive / --autonomous / --interaction-mode.
+                            (aliases: interaction-mode, interaction)
+  handoff <image|raws>      Mint the copy-paste brief an INTERACTIVE user works from.
+    image --theme "<what>" --items "a,b,c" [--style …] [--key-color #00FF00]
+                            A free-web-image-gen brief. Defaults to a STICKER PACK:
+                            one prompt → one greenscreen sheet → I split it with
+                            vidfarm sticker-pack for $0. --single for one subject.
+    raws --keywords "a,b" [--platforms tiktok,youtube] [--count N] [--purpose "…"]
+                            A manual clip-sourcing brief: what to search, how to
+                            download (a downloader SEARCH, not a rotting link), and
+                            the vidfarm clipper / raws scan follow-up. Try browser control
+                            or "vidfarm raws scan" first.
+  storyboard [dir]          The PLAN pass: read the project's STORYBOARD.md (ordered
+                            frames + duration/status/src/scene/voiceover, plus SCRIPT.md).
+                            The editor renders this file in its Storyboard view — a
+                            contact sheet with per-frame comments — so it's the cheapest
+                            place to get a director's approval before building.
+                            (alias: plan · not to be confused with "vidfarm sequence",
+                            which GENERATES storyboard images)
+    --init                  Scaffold a STORYBOARD.md (--force overwrites)
+    --frames "Title|scene,…"   Frames to scaffold · --count <n> for N blank frames
+    --title/--format/--message/--arc/--audience   Frontmatter for --init
+    --json                  The parsed manifest (frames, statuses, warnings)
 
 Local editor loop:
   serve [template_id] [opts]  Boot the editor locally. On a full source checkout the
@@ -282,6 +320,10 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --tolerance <0..1>      Key radius (default 0.3); --softness <0..1> edge feather (0.1)
     --no-despill            Skip edge color-fringe suppression
     --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
+    --gif-fps/--gif-width   Animated-GIF frame rate (15) / max width, in px
+    --gif-alpha <0..255>    Where GIF's 1-bit alpha cuts the edge (default 128)
     --local                 Key on your machine with bundled ffmpeg for FREE
                             (no wallet, no account; cloud-parity chroma key) — DEFAULT
     --cloud                 Force the billed cloud primitive
@@ -293,13 +335,48 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             (alias: sticker)
     --generate "<prompt>"   AI-generate the graphic first, on a matching chroma plate
                             (billed image primitive) — then key + trim in one shot
-    --preset/--key-color    Plate color (same knobs as remove-greenscreen)
+    --preset/--key-color    Plate color (same knobs as remove-greenscreen). Auto by
+                            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.
     --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
+                            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. Local, free, ffmpeg-only. Image-only.
+                            (aliases: stickers, sticker-sheet)
+    --generate "<theme>"    AI-generate the sheet first (ONE billed image job for
+                            the WHOLE pack) on a spaced grid over a chroma plate
+    --items "a,b,c"         The exact items to generate — also names the outputs
+                            (sticker-01-a.png, sticker-02-b.png, …)
+    --count <n>             How many items to generate when --items is omitted (6)
+    --preset/--key-color    Plate color. SMART BY DEFAULT: generating picks a plate the
+                            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)
+    --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
+                            split item, lower it to separate two that got merged
+    --min-area <pct>        Drop islands smaller than this % of the sheet (0.15);
+                            there is NO maximum — a landscape can be one sticker
+    --max-items <n>         Cap how many items are cut (default 64)
+    --pad <px>              Keep N px of transparent breathing room per sticker
+    --alpha-threshold <n>   Alpha 0..255 below which edges count as empty (default 8)
+    --output-format <f>     png (default) | webp | gif (1-bit alpha, GIF-only surfaces)
+    --gif-alpha <0..255>    Where GIF's 1-bit alpha cuts the edge (default 128)
+    --out-dir <dir>         Where the pack lands (default ./stickers)
+    --prefix <name>         Filename prefix (default "sticker")
+    --keep-plate <file>     Also save the pre-key generated sheet
+    --keep-sheet <file>     Also save the keyed, uncut transparent sheet
   mask <image|url>          Lift an illustration OUT of an image you already have
                             (an infographic, poster, marketing image, screenshot)
                             → snug transparent PNG you can reuse as a FREE explainer
@@ -595,6 +672,29 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
   lint <dir|composition.html>   Validate a composition on disk (same      (local)
                             checks the /editor chat preflights); prints
                             errors/warnings, exit 1 on errors [--json]
+  qa <dir|composition.html>   Social-native QA pass — HIGHLY RECOMMENDED  (local, devcli-only)
+                            on every video you produce. Blocklists "HTML
+                            slop" (CTA buttons, benefit chip rows, frosted
+                            cards, gradient text, web-page classes/fonts)
+                            and checks the caption font regime + safe zone.
+                            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 —
+                              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
+    --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)
   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
@@ -915,7 +1015,6 @@ async function main() {
             await runGenerateCommand(rest);
             return;
         case "sequence":
-        case "storyboard":
         case "previz":
             await runSequenceCommand(rest);
             return;
@@ -941,6 +1040,12 @@ async function main() {
         case "sticker":
             await runCutoutCommand(rest);
             return;
+        case "sticker-pack":
+        case "stickerpack":
+        case "stickers":
+        case "sticker-sheet":
+            await runStickerPackCommand(rest);
+            return;
         case "mask":
         case "isolate":
         case "extract":
@@ -1035,6 +1140,19 @@ async function main() {
         case "cost":
             await runCostModeCommand(rest);
             return;
+        case "mode":
+        case "interaction-mode":
+        case "interaction":
+            await runInteractionModeCommand(rest);
+            return;
+        case "handoff":
+        case "hand-off":
+            await runHandoffCommand(rest);
+            return;
+        case "storyboard":
+        case "plan":
+            await runStoryboardCommand(rest);
+            return;
         case "update-skill":
         case "skill":
             await runUpdateSkillCommand(rest);
@@ -1177,6 +1295,15 @@ async function main() {
         case "lint":
             await runLintCommand(rest);
             return;
+        case "qa":
+        case "qa-check":
+        case "slop-check":
+            await runQaCommand(rest);
+            return;
+        case "regime":
+        case "regimes":
+            await runRegimeCommand(rest);
+            return;
         case "stills":
             await runStillsCommand(rest);
             return;
@@ -1313,6 +1440,13 @@ function commonOptions() {
         // env > `vidfarm cost-mode` stored value > default (hybrid). Billed commands
         // gate on it; `--yes`/-y confirms a billed spend when the mode is "minimize".
         "cost-mode": { type: "string" },
+        // Is the human in the loop? interactive | autonomous — an axis INDEPENDENT
+        // of cost mode (see interaction-mode.ts). Flag > VIDFARM_INTERACTION_MODE >
+        // `vidfarm mode` stored value > default (autonomous, but flagged unset so
+        // the agent knows to ask — interactive usually produces a better video).
+        "interaction-mode": { type: "string" },
+        interactive: { type: "boolean", default: false },
+        autonomous: { type: "boolean", default: false },
         yes: { type: "boolean", default: false, short: "y" },
         home: { type: "string" }
     };
@@ -1354,12 +1488,22 @@ function commonContext(values) {
         json: Boolean(values.json),
         target: resolveTarget(values),
         costMode: resolveCostMode(values),
+        interaction: resolveInteractionMode(values),
         yes: Boolean(values.yes),
         home: values.home
     };
 }
-/** Gate a billed cloud/AI op against the run's cost mode (see cost-mode.ts). */
+/** Gate a billed cloud/AI op against the run's cost mode (see cost-mode.ts).
+ *  `interactiveAlternative` names the free HUMAN path (a copy-paste prompt the
+ *  user runs in a web tool) — surfaced when the spend is blocked or when no
+ *  interaction preference has been recorded yet, because in `minimize` that
+ *  hand-off is the difference between custom art and none at all. */
 function guardBilled(ctx, input) {
+    const interactiveNote = input.interactiveAlternative
+        ? (ctx.interaction.mode === "interactive"
+            ? `\nYou're in INTERACTIVE mode — prefer the free hand-off: ${input.interactiveAlternative}`
+            : `\nOr offer the user interactive mode (free, usually better): ${input.interactiveAlternative} — \`vidfarm mode interactive\`.`)
+        : "";
     assertBilledAllowed({
         resolved: ctx.costMode,
         yes: ctx.yes,
@@ -1367,7 +1511,14 @@ function guardBilled(ctx, input) {
         label: input.label,
         estimate: input.estimate,
         freeAlternative: input.freeAlternative
+            ? `${input.freeAlternative}${interactiveNote}`
+            : (interactiveNote ? interactiveNote.trimStart() : undefined)
     });
+    if (!ctx.json && input.interactiveAlternative) {
+        const offer = interactiveOfferLine({ interaction: ctx.interaction, about: input.label });
+        if (offer)
+            console.error(offer);
+    }
 }
 /**
  * One dispatch seam for dual local/cloud REST calls. `local` runs the request
@@ -2156,6 +2307,11 @@ Rules:
 - When swapping visuals, match both the literal scene DNA and the narrative purpose of the beat.
 - 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. 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). None of that 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\`.
+- 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\`.
+- 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.
+- 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.
 
 The three paintbrushes (Vidfarm is thrift-first — do NOT spend AI credits on every scene):
 - Paint each REPLACE beat with one of three brushes, cheapest first: (1) RAW CLIPS remixed from existing footage (\`vidfarm raws search\` the local/library first, then \`vidfarm raws scan <url|file>\` to hunt new ones — free local compute); (2) HTML/JS HYPERFRAMES — animate text/images/logos/stickers/charts with CSS or JS adapters (anime.js/GSAP/Lottie/Three) for titles, kinetic captions, data beats, brand cards; (3) PURE AI GENERATION (\`vidfarm generate image|video\`) — most expensive, AI video especially, last resort for beats no clip or hyperframe can cover.
@@ -3575,6 +3731,9 @@ async function runRenderCommand(argv) {
             }
             console.log(`${GREEN}Rendered locally in ${(result.durationMs / 1000).toFixed(1)}s → ${result.outputPath}${RESET}`);
             console.log(`${DIM}$0.00 — local Vidfarm render, no cloud charge.${RESET}`);
+            // Nudge, not a gate: QA never runs automatically, but every production
+            // should get a look before it's published.
+            console.log(`${DIM}Recommended: ${RESET}vidfarm qa ${sourceDir ?? "<dir>"}${DIM} — social-native QA (HTML slop + font regime). Feedback only, free, instant.${RESET}`);
         }
         return;
     }
@@ -4154,14 +4313,20 @@ async function runGenerateCommand(argv) {
             estimate: "expensive, ~$1+",
             freeAlternative: 'free stock video — vidfarm media search "<meaning>" --type video (Pixabay, $0; needs a free ' +
                 "pixabay key — it may already be saved: check vidfarm provider-keys), reuse a raw clip (vidfarm " +
-                "raws), or author the beat as an HTML hyperframe"
+                "raws), or author the beat as an HTML hyperframe",
+            interactiveAlternative: 'hand the user a clip-sourcing brief — vidfarm handoff raws --keywords "<kw>,<kw>" — they search ' +
+                "TikTok/YouTube and download a few clips with a free downloader ($0, and a human eye picks better " +
+                "footage than a keyword scan)"
         }
         : {
             label: "AI image generation",
             estimate: "cheap, ~$0.01–$0.05",
             freeAlternative: 'free stock image/vector — vidfarm media search "<meaning>" --type image|vector ($0). ' +
                 "Openverse (CC images) is keyless and always on — check it first; a free Pixabay key adds " +
-                "photos/vectors and may already be saved (check vidfarm provider-keys)"
+                "photos/vectors and may already be saved (check vidfarm provider-keys)",
+            interactiveAlternative: 'hand the user an image brief — vidfarm handoff image --theme "<what>" --items "a,b,c" — they run it ' +
+                "in a free web generator (meta.ai / ChatGPT / Gemini) and drop the PNG back; needing several graphics " +
+                "makes it ONE sticker sheet that vidfarm sticker-pack splits for $0"
         });
     const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
     const payload = { prompt };
@@ -4903,6 +5068,13 @@ async function runRemoveGreenscreenCommand(argv) {
             softness: { type: "string" },
             "no-despill": { 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
+            // compositing one; --gif-fps/--gif-width/--gif-alpha tune the tradeoff.
+            gif: { type: "boolean", default: false },
+            "gif-fps": { type: "string" },
+            "gif-width": { type: "string" },
+            "gif-alpha": { type: "string" },
             local: { type: "boolean", default: false },
             cloud: { type: "boolean", default: false },
             out: { type: "string" },
@@ -4912,6 +5084,13 @@ async function runRemoveGreenscreenCommand(argv) {
     });
     const ctx = commonContext(parsed.values);
     let target = resolveGreenscreenTarget(parsed.values);
+    // GIF is encoded by the local ffmpeg pass — the cloud primitive only returns
+    // PNG/WebP/WebM — so --gif implies (and requires) the local keyer.
+    if (parsed.values.gif && parsed.values.cloud) {
+        throw new Error("--gif is a local-only output (the cloud primitive returns png/webp/webm). Drop --cloud, or key in the cloud and convert the result afterwards.");
+    }
+    if (parsed.values.gif)
+        target = "local";
     const sourceArg = parsed.values.source ?? parsed.positionals[0];
     if (!sourceArg) {
         throw new Error("remove-greenscreen requires a source image or video: `vidfarm remove-greenscreen <image|video|url> [--preset green|blue|white|black|digital-green|magenta] [--key-color #00FF00] [--cloud] [--out cutout.png|.webm]`.");
@@ -5040,13 +5219,52 @@ async function runLocalGreenscreen(ctx, values, sourceArg, presetRaw) {
         const softness = values.softness !== undefined ? Number(values.softness) : preset?.softness;
         const despill = !values["no-despill"];
         const outputFormat = values["output-format"]?.trim().toLowerCase();
+        const wantGif = Boolean(values.gif);
         const outPath = values.out
             ? path.resolve(process.cwd(), String(values.out))
-            : defaultGreenscreenOutPath(sourcePath, mediaType, outputFormat);
+            : wantGif
+                ? defaultGreenscreenOutPath(sourcePath, mediaType, outputFormat).replace(/\.[^.]+$/, ".gif")
+                : defaultGreenscreenOutPath(sourcePath, mediaType, outputFormat);
         mkdirSync(path.dirname(outPath), { recursive: true });
+        // For GIF we key into a temp alpha master first (PNG for a still, WebM/MOV
+        // for a clip) and quantize afterwards — ffmpeg can't key straight into GIF's
+        // palette without losing the alpha we just cut.
+        const gifWork = wantGif ? mkdtempSync(path.join(tmpdir(), "vidfarm-gif-")) : null;
+        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}`);
-        const result = await removeGreenscreenLocal({ sourcePath, mediaType, outputPath: outPath, keyColor, tolerance, softness, despill });
+        let result = await removeGreenscreenLocal({ sourcePath, mediaType, outputPath: keyTargetPath, keyColor, tolerance, softness, despill });
+        if (gifWork) {
+            try {
+                if (!ctx.json)
+                    console.log(`${DIM}Encoding a transparent ${mediaType === "video" ? "animated " : ""}GIF (1-bit alpha)…${RESET}`);
+                const gifAlpha = values["gif-alpha"] !== undefined ? Number(values["gif-alpha"]) : undefined;
+                if (mediaType === "video") {
+                    await encodeTransparentAnimatedGif(result.outputPath, outPath, {
+                        fps: values["gif-fps"] !== undefined ? Number(values["gif-fps"]) : undefined,
+                        width: values["gif-width"] !== undefined ? Number(values["gif-width"]) : undefined,
+                        alphaThreshold: gifAlpha
+                    });
+                }
+                else {
+                    await encodeTransparentGif(result.outputPath, outPath, { alphaThreshold: gifAlpha });
+                }
+                result = { ...result, outputPath: outPath, format: result.format, webmAlpha: false };
+            }
+            finally {
+                rmSync(gifWork, { recursive: true, force: true });
+            }
+            if (ctx.json) {
+                printJson({ ok: true, target: "local", media_type: mediaType, format: "gif", out: outPath, bytes: safeSize(outPath), webm_alpha: false });
+            }
+            else {
+                console.log(`${GREEN}Transparent ${mediaType === "video" ? "animated " : ""}GIF ready:${RESET} ${outPath} ${DIM}(${formatBytes(safeSize(outPath))})${RESET}`);
+                console.log(`${DIM}GIF alpha is 1-bit, so edges are hard — that's the format, not the key. For compositing on a composition prefer PNG/WebP (still) or transparent WebM (clip); use GIF for surfaces that only take GIF.${RESET}`);
+            }
+            return;
+        }
         if (ctx.json) {
             printJson({ ok: true, target: "local", media_type: mediaType, format: result.format, out: result.outputPath, bytes: safeSize(result.outputPath), webm_alpha: result.webmAlpha });
         }
@@ -5105,6 +5323,7 @@ async function runCutoutCommand(argv) {
             // Keyer knobs (mirror remove-greenscreen).
             preset: { type: "string" },
             "key-color": { type: "string" },
+            "no-auto-key": { type: "boolean", default: false },
             tolerance: { type: "string" },
             softness: { type: "string" },
             "no-despill": { type: "boolean", default: false },
@@ -5128,9 +5347,10 @@ async function runCutoutCommand(argv) {
         throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${Object.keys(GREENSCREEN_PRESETS).join(", ")}, or pass --key-color <hex>.`);
     }
     const preset = presetRaw ? GREENSCREEN_PRESETS[presetRaw] : undefined;
-    const keyColor = parsed.values["key-color"] ?? preset?.key_color ?? "#00FF00";
-    const tolerance = parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : preset?.tolerance;
-    const softness = parsed.values.softness !== undefined ? Number(parsed.values.softness) : preset?.softness;
+    const explicitKeyColor = parsed.values["key-color"] ?? preset?.key_color;
+    let keyColor = explicitKeyColor ?? "#00FF00";
+    let tolerance = parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : preset?.tolerance;
+    let softness = parsed.values.softness !== undefined ? Number(parsed.values.softness) : preset?.softness;
     const despill = !parsed.values["no-despill"];
     const outputFormat = parsed.values["output-format"]?.trim().toLowerCase();
     const outExt = outputFormat === "webp" ? "webp" : "png";
@@ -5139,6 +5359,27 @@ async function runCutoutCommand(argv) {
     if (!generatePrompt && !sourceArg) {
         throw new Error("cutout needs a source: `vidfarm cutout <image|url>` to key+trim an existing graphic, or `vidfarm cutout --generate \"a robot mascot waving\"` to AI-generate one first.");
     }
+    // Plate choice: a chroma key removes ONE color, so a green plate under a green
+    // subject (a frog, a leaf, a dollar bill) keys holes through the art. When
+    // generating without a pinned color, move the plate off any hue the subject
+    // mentions; when keying a file the caller didn't color-pin, read the plate off
+    // the image's own corners.
+    let plateNote = null;
+    if (!explicitKeyColor && !parsed.values["no-auto-key"] && generatePrompt) {
+        const picked = pickPlateColor(generatePrompt);
+        keyColor = picked.keyColor;
+        const p = GREENSCREEN_PRESETS[picked.preset];
+        if (tolerance === undefined)
+            tolerance = p?.tolerance;
+        if (softness === undefined)
+            softness = p?.softness;
+        if (picked.moved)
+            plateNote = `Using a ${picked.preset} (${picked.keyColor}) plate instead of green — ${picked.reason}.`;
+        else if (picked.reason)
+            plateNote = `Sticking with green, but heads up: ${picked.reason}.`;
+        if (!ctx.json && plateNote)
+            console.log(`${YELLOW}Plate:${RESET} ${DIM}${plateNote}${RESET}`);
+    }
     const work = mkdtempSync(path.join(tmpdir(), "vidfarm-cutout-"));
     let sourcePath;
     let stemHint;
@@ -5148,7 +5389,9 @@ async function runCutoutCommand(argv) {
             guardBilled(ctx, {
                 label: "AI image generation (cutout plate)",
                 estimate: "cheap, ~$0.01–$0.05",
-                freeAlternative: "pass an existing graphic instead — `vidfarm cutout <image|url>` keys+trims for $0.00"
+                freeAlternative: "pass an existing graphic instead — `vidfarm cutout <image|url>` keys+trims for $0.00",
+                interactiveAlternative: 'vidfarm handoff image --theme "<subject>" --single — the user generates the plate in a free web tool ' +
+                    "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)}`;
@@ -5206,6 +5449,14 @@ async function runCutoutCommand(argv) {
             }
         }
         // ---- 2. Key out the flat plate → transparent PNG ------------------------
+        if (!explicitKeyColor && !parsed.values["no-auto-key"] && !generatePrompt) {
+            const detected = await detectPlateColor(sourcePath);
+            if (detected && detected.hex.toUpperCase() !== keyColor.toUpperCase()) {
+                keyColor = detected.hex;
+                if (!ctx.json)
+                    console.log(`${YELLOW}Plate:${RESET} ${DIM}Detected the graphic's background as ${detected.hex} from its corners (pass --key-color to override).${RESET}`);
+            }
+        }
         const keyedPath = path.join(work, "keyed.png");
         if (!ctx.json)
             console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} background locally with ffmpeg (free)…${RESET}`);
@@ -5436,6 +5687,326 @@ async function runMaskCommand(argv) {
         rmSync(work, { recursive: true, force: true });
     }
 }
+// ── sticker-pack: ONE plate of MANY items → many individual transparent stickers
+// The bulk sibling of `cutout`. "Make me a sticker pack" is never one graphic —
+// it's a SET (props, icons, reactions, characters, backdrops) that has to share
+// one art style. Generating them one at a time is both expensive (N image jobs)
+// and inconsistent (N independent styles). The standard move is the opposite:
+// generate ONE image holding every item, laid out on a flat chroma plate, then
+// cut each item out locally for $0. This verb is that whole loop:
+//   1. generate (or accept) a single greenscreen SHEET of many items
+//   2. key the flat plate out once → a transparent sheet
+//   3. SEGMENT the sheet's alpha into connected islands — one per item — with no
+//      hand-measured --crop rects (see devcli/sticker-pack.ts)
+//   4. crop + alpha-trim each island → its own snug transparent file, plus a
+//      stickers.json manifest of names/sizes
+// Items are size-agnostic on purpose: a "sticker" here is any transparent
+// element you place and animate — an icon, a mascot, a prop, OR a full-width
+// landscape/backdrop that fills the frame.
+function slugifyStickerName(raw) {
+    return raw.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+}
+/** Prompt scaffolding for a MULTI-item plate. Differs from cutoutPlateInstruction
+ *  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) {
+    const named = /^#?00ff00$/i.test(keyColorHex) ? "pure chroma-key green"
+        : /^#?0047bb$/i.test(keyColorHex) ? "solid chroma-key blue"
+            : /^#?ff00ff$/i.test(keyColorHex) ? "solid magenta"
+                : `a solid flat ${keyColorHex}`;
+    const list = items.length
+        ? `Include exactly these ${items.length} separate items, one of each: ${items.join("; ")}.`
+        : `Include exactly ${count} distinct separate items.`;
+    return (`A sticker sheet: ${count} separate objects arranged in a spaced grid on a completely flat, evenly-lit ` +
+        `${named} (${keyColorHex}) background. ${list} ` +
+        `CRITICAL: every item must be fully separated from the others by a clear margin of plain ${keyColorHex} background — ` +
+        `nothing touching, overlapping, or connected. Keep a wide ${keyColorHex} margin around the edges of the sheet too. ` +
+        `No item may contain that background color anywhere on it. 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.`);
+}
+async function runStickerPackCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            source: { type: "string" },
+            // Optional AI generation of the sheet (ONE billed image job for the set).
+            generate: { type: "string" },
+            items: { type: "string" },
+            count: { type: "string" },
+            ref: { type: "string", multiple: true },
+            "aspect-ratio": { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            // Keyer knobs (mirror cutout / remove-greenscreen).
+            preset: { type: "string" },
+            "key-color": { type: "string" },
+            flat: { type: "string" },
+            "no-auto-key": { type: "boolean", default: false },
+            tolerance: { type: "string" },
+            softness: { type: "string" },
+            "no-despill": { type: "boolean", default: false },
+            // Segmentation knobs.
+            "min-area": { type: "string" },
+            gap: { type: "string" },
+            "max-items": { type: "string" },
+            "dry-run": { type: "boolean", default: false },
+            // Per-sticker output knobs (mirror cutout).
+            pad: { type: "string" },
+            "alpha-threshold": { type: "string" },
+            "output-format": { type: "string" },
+            "gif-alpha": { type: "string" },
+            "out-dir": { type: "string" },
+            prefix: { type: "string" },
+            "keep-plate": { type: "string" },
+            "keep-sheet": { type: "string" },
+            tracer: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    if (!(await localGreenscreenAvailable())) {
+        throw new Error("sticker-pack needs ffmpeg (for the free local keyer, alpha segmentation and trim), which wasn't found. Install ffmpeg (or `npm i -g ffmpeg-static`).");
+    }
+    const presetRaw = parsed.values.preset?.trim().toLowerCase();
+    if (presetRaw && !(presetRaw in GREENSCREEN_PRESETS)) {
+        throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${Object.keys(GREENSCREEN_PRESETS).join(", ")}, or pass --key-color <hex>.`);
+    }
+    const preset = presetRaw ? GREENSCREEN_PRESETS[presetRaw] : undefined;
+    const explicitKeyColor = parsed.values["key-color"] ?? parsed.values.flat ?? preset?.key_color;
+    let keyColor = explicitKeyColor ?? "#00FF00";
+    let tolerance = parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : preset?.tolerance;
+    let softness = parsed.values.softness !== undefined ? Number(parsed.values.softness) : preset?.softness;
+    const despill = !parsed.values["no-despill"];
+    const outputFormat = parsed.values["output-format"]?.trim().toLowerCase();
+    if (outputFormat && !["png", "webp", "gif"].includes(outputFormat)) {
+        throw new Error(`Unknown --output-format "${outputFormat}". Use png (default), webp, or gif (1-bit alpha — for GIF-only surfaces).`);
+    }
+    const wantGif = outputFormat === "gif";
+    const stillExt = outputFormat === "webp" ? "webp" : "png";
+    const itemNames = parsed.values.items
+        ?.split(/\s*[;,]\s*/).map((s) => s.trim()).filter(Boolean) ?? [];
+    const generatePrompt = parsed.values.generate?.trim();
+    const sourceArg = parsed.values.source ?? parsed.positionals[0];
+    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).");
+    }
+    // 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"]) {
+        const picked = pickPlateColor([generatePrompt, itemNames.join(" ")].join(" "));
+        keyColor = picked.keyColor;
+        plateAuto = true;
+        const p = GREENSCREEN_PRESETS[picked.preset];
+        if (tolerance === undefined)
+            tolerance = p?.tolerance;
+        if (softness === undefined)
+            softness = p?.softness;
+        if (picked.moved)
+            plateNote = `Using a ${picked.preset} (${picked.keyColor}) plate instead of green — ${picked.reason}.`;
+        else if (picked.reason)
+            plateNote = `Sticking with green, but heads up: ${picked.reason}.`;
+    }
+    const outDir = path.resolve(process.cwd(), String(parsed.values["out-dir"] ?? "./stickers"));
+    const prefix = parsed.values.prefix?.trim() || "sticker";
+    const work = mkdtempSync(path.join(tmpdir(), "vidfarm-stickerpack-"));
+    try {
+        // ---- 1. Obtain the sheet (generate ONE plate, or use an existing one) -----
+        let sheetPath;
+        if (generatePrompt) {
+            const count = parsed.values.count !== undefined
+                ? Math.max(2, Math.round(Number(parsed.values.count)))
+                : (itemNames.length || 6);
+            if (!Number.isFinite(count))
+                throw new Error(`--count must be a number. Got "${String(parsed.values.count)}".`);
+            guardBilled(ctx, {
+                label: `AI image generation (sticker sheet of ${count} items)`,
+                estimate: "cheap, ~$0.01–$0.05 for the WHOLE pack (one image job, not one per sticker)",
+                freeAlternative: "pass a greenscreen sheet you already have — `vidfarm sticker-pack <sheet.png>` cuts it up for $0.00",
+                interactiveAlternative: `vidfarm handoff image --theme "${generatePrompt.replace(/"/g, "'")}"${itemNames.length ? ` --items "${itemNames.join(",")}"` : ""} — ` +
+                    "the user generates the SAME sheet in a free web tool (often better art than the API tier) and hands it " +
+                    "back; this command then splits it for $0"
+            });
+            const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
+            const fullPrompt = `${generatePrompt}. ${stickerSheetInstruction(keyColor, count, itemNames)}`;
+            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";
+            if (parsed.values.provider)
+                payload.provider = parsed.values.provider;
+            if (parsed.values.model)
+                payload.model = parsed.values.model;
+            if (refs.length)
+                payload.prompt_attachments = refs.slice(0, 16);
+            const tracer = parsed.values.tracer ?? `devcli-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}`);
+            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;
+            if (!jobId)
+                throw new Error("sticker-pack generate: no job id returned.");
+            const job = await pollPrimitiveJob(ctx, jobId);
+            const mediaUrl = resolveJobMediaUrl(job);
+            if (!mediaUrl)
+                throw new Error(`sticker-pack generate: job ${jobId} produced no image (${String(job?.status ?? "unknown")}).`);
+            sheetPath = path.join(work, "sheet.png");
+            await downloadUrlToFile(mediaUrl, sheetPath);
+            if (parsed.values["keep-plate"]) {
+                const keepPath = path.resolve(process.cwd(), String(parsed.values["keep-plate"]));
+                mkdirSync(path.dirname(keepPath), { recursive: true });
+                await downloadUrlToFile(mediaUrl, keepPath);
+                if (!ctx.json)
+                    console.log(`${DIM}Saved the pre-key sheet to ${keepPath}${RESET}`);
+            }
+        }
+        else {
+            const directPath = path.resolve(process.cwd(), sourceArg);
+            const isLocalFile = !/^https?:\/\//i.test(sourceArg) && existsSync(directPath);
+            if (isLocalFile) {
+                if (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(directPath)) {
+                    throw new Error("sticker-pack is image-only (a sheet is one still). For a MOVING sticker, key the clip with `vidfarm remove-greenscreen <video>` → transparent WebM (add --gif for an animated transparent GIF).");
+                }
+                sheetPath = directPath;
+            }
+            else {
+                const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
+                if (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(sourceUrl)) {
+                    throw new Error("sticker-pack is image-only. Key a clip with `vidfarm remove-greenscreen <video>`.");
+                }
+                sheetPath = path.join(work, path.basename(new URL(sourceUrl).pathname) || "sheet.png");
+                if (!ctx.json)
+                    console.log(`${DIM}Downloading sheet…${RESET}`);
+                await downloadUrlToFile(sourceUrl, sheetPath);
+            }
+        }
+        // ---- 2. Key the flat plate 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"]) {
+            const detected = await detectPlateColor(sheetPath);
+            if (detected && detected.hex.toUpperCase() !== keyColor.toUpperCase()) {
+                keyColor = detected.hex;
+                plateAuto = true;
+                plateNote = `Detected the sheet's plate color as ${detected.hex} from its corners (pass --key-color to override).`;
+            }
+            else if (!detected) {
+                plateNote = "Couldn't read a uniform plate color from the sheet's corners — falling back to green. If the background isn't green, pass --preset <name> or --key-color <hex>.";
+            }
+            if (!ctx.json && plateNote)
+                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 });
+        if (parsed.values["keep-sheet"]) {
+            const keepPath = path.resolve(process.cwd(), String(parsed.values["keep-sheet"]));
+            mkdirSync(path.dirname(keepPath), { recursive: true });
+            copyFileSync(keyedSheet, keepPath);
+            if (!ctx.json)
+                console.log(`${DIM}Saved the keyed (uncut) sheet to ${keepPath}${RESET}`);
+        }
+        // ---- 3. Segment the sheet's alpha into one island per item ---------------
+        const alphaThreshold = parsed.values["alpha-threshold"] !== undefined ? Number(parsed.values["alpha-threshold"]) : undefined;
+        if (!ctx.json)
+            console.log(`${DIM}Finding the individual items in the sheet's alpha channel…${RESET}`);
+        const seg = await segmentAlphaComponents({
+            sourcePath: keyedSheet,
+            alphaThreshold,
+            minAreaPct: parsed.values["min-area"] !== undefined ? Number(parsed.values["min-area"]) : undefined,
+            gapPct: parsed.values.gap !== undefined ? Number(parsed.values.gap) : undefined,
+            maxItems: parsed.values["max-items"] !== undefined ? Number(parsed.values["max-items"]) : undefined
+        });
+        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).");
+        }
+        if (parsed.values["dry-run"]) {
+            // 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, items: seg.components });
+            }
+            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) {
+                    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}`);
+                }
+                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}`);
+            }
+            return;
+        }
+        // ---- 4. Crop + alpha-trim each island into its own sticker ---------------
+        mkdirSync(outDir, { recursive: true });
+        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 = [];
+        for (const c of seg.components) {
+            const label = itemNames[c.index - 1] ? slugifyStickerName(itemNames[c.index - 1]) : "";
+            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 });
+            // 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.
+            const stillPath = path.join(wantGif ? work : outDir, `${stem}.${stillExt}`);
+            const trim = await trimTransparentBorders({ sourcePath: regionPath, outputPath: stillPath, padPx, alphaThreshold });
+            let finalPath = trim.outputPath;
+            if (wantGif) {
+                finalPath = path.join(outDir, `${stem}.gif`);
+                await encodeTransparentGif(trim.outputPath, finalPath, { alphaThreshold: gifAlpha });
+            }
+            written.push({
+                index: c.index,
+                name: itemNames[c.index - 1] ?? null,
+                file: finalPath,
+                width: trim.width,
+                height: trim.height,
+                sheet_crop: { x: c.x, y: c.y, width: c.width, height: c.height },
+                area_pct: c.area_pct,
+                bytes: safeSize(finalPath)
+            });
+            if (!ctx.json) {
+                console.log(`  ${GREEN}✓${RESET} ${path.relative(process.cwd(), finalPath)} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(finalPath))})${RESET}`);
+            }
+        }
+        // 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");
+        writeFileSync(manifestPath, `${JSON.stringify({
+            generated_from: generatePrompt ? "generate" : sourceArg,
+            key_color: keyColor,
+            key_color_auto: plateAuto,
+            sheet_width: seg.sourceWidth,
+            sheet_height: seg.sourceHeight,
+            format: wantGif ? "gif" : stillExt,
+            count: written.length,
+            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, 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}`);
+            }
+            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}`);
+        }
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
 // Poll a greenscreen job through the same backend it was submitted to (local
 // in-process app or cloud). Mirrors pollPrimitiveJob's terminal conditions.
 async function pollGreenscreenJob(ctx, target, jobId) {
@@ -7228,6 +7799,7 @@ async function runWhoamiCommand(argv) {
         console.log(`  plan        ${customer.isPaidPlan ? `${GREEN}paid${plan}${RESET}` : `${DIM}free${plan}${RESET}`}`);
         console.log(`  credential  ${DIM}${stored ? "persisted login (vidfarm login)" : "env/flag key — not persisted (run vidfarm login to persist)"}${RESET}`);
         console.log(`  ${costModeSummaryLine(ctx.costMode).replace("cost mode: ", "cost mode   ")}${!ctx.costMode.isSet ? `  ${DIM}(set with: vidfarm cost-mode <${COST_MODE_DISPLAY_LIST.join("|")}>)${RESET}` : ""}`);
+        console.log(`  ${interactionModeSummaryLine(ctx.interaction).replace("interaction mode: ", "interaction ")}${!ctx.interaction.isSet ? `  ${DIM}(set with: vidfarm mode <${INTERACTION_MODES.join("|")}>)${RESET}` : ""}`);
         return;
     }
     emitResult(result, ctx.json);
@@ -7284,6 +7856,267 @@ async function runCostModeCommand(argv) {
     if (!resolved.isSet) {
         console.log(`${DIM}Nothing saved yet — ask the user which one they want before spending AI credits.${RESET}`);
     }
+    // Cost is only half the plan: ask the SECOND axis too. In minimize especially,
+    // interactive mode is what turns "$0 means no custom art" into "$0 with a full
+    // sticker pack and hand-picked footage".
+    const interaction = resolveInteractionMode(parsed.values);
+    console.log("");
+    console.log(`${BOLD}${interactionModeSummaryLine(interaction)}${RESET}`);
+    if (!interaction.isSet) {
+        console.log(`${DIM}Ask this one too — it is INDEPENDENT of cost: is the user willing to do a little manual work (paste an image prompt into a free web tool, hand-source a few clips) for better output? ${BOLD}vidfarm mode <interactive|autonomous>${RESET}`);
+    }
+    if (resolved.mode === "minimize") {
+        console.log(`${DIM}In minimize, ${interaction.mode === "interactive" ? "you're already on" : "offer"} the sweet spot: minimize + interactive = $0 videos that still get custom art (free web image gen → vidfarm sticker-pack) and hand-picked clips (vidfarm handoff raws).${RESET}`);
+    }
+}
+// `vidfarm storyboard [dir]` — the PLAN pass, before any animation work.
+// Storyboarding is a first-class part of the composition format now: a project
+// root carries STORYBOARD.md (ordered frames + per-frame status/duration/
+// narration) and optionally SCRIPT.md (the full voiceover). The Vidfarm editor
+// renders exactly this file in its Storyboard view — a contact sheet with a
+// comment box per frame — which makes it the natural place to get a director's
+// approval before building. This command is the agent-side twin: scaffold a
+// plan, read one back, and see which frames are still outlines.
+async function runStoryboardCommand(argv) {
+    // `storyboard` used to be an alias for the AI shot-sheet pipeline (`vidfarm
+    // sequence`). That name now belongs to the composition format's plan file, so
+    // keep the old muscle memory working: a sequence SUBCOMMAND still routes there.
+    const SEQUENCE_SUBCOMMANDS = new Set(["init", "plan", "characters", "boards", "prompts", "animate", "assemble", "status", "run"]);
+    if (argv[0] && SEQUENCE_SUBCOMMANDS.has(argv[0].trim().toLowerCase()) && argv[0].trim().toLowerCase() !== "plan") {
+        return runSequenceCommand(argv);
+    }
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            init: { type: "boolean", default: false },
+            force: { type: "boolean", default: false },
+            frames: { type: "string" },
+            count: { type: "string" },
+            title: { type: "string" },
+            format: { type: "string" },
+            message: { type: "string" },
+            arc: { type: "string" },
+            audience: { type: "string" }
+        }
+    });
+    const json = Boolean(parsed.values.json);
+    const dir = path.resolve(process.cwd(), parsed.positionals[0] ?? ".");
+    if (!existsSync(dir))
+        throw new Error(`No such project directory: ${dir}`);
+    const target = path.join(dir, STORYBOARD_FILENAME);
+    if (parsed.values.init) {
+        if (existsSync(target) && !parsed.values.force) {
+            throw new Error(`${target} already exists. Edit it, or pass --force to overwrite it.`);
+        }
+        const frames = parsed.values.frames?.split(/\s*[;,]\s*/).map((s) => s.trim()).filter(Boolean);
+        const body = renderStoryboardScaffold({
+            title: parsed.values.title,
+            format: parsed.values.format,
+            message: parsed.values.message,
+            arc: parsed.values.arc,
+            audience: parsed.values.audience,
+            frames,
+            count: parsed.values.count !== undefined ? Number(parsed.values.count) : undefined
+        });
+        writeFileSync(target, body, "utf8");
+        if (json)
+            return printJson({ ok: true, created: target, frames: frames?.length ?? Number(parsed.values.count ?? 5) });
+        console.log(`${GREEN}Storyboard created:${RESET} ${target}`);
+        console.log(`${DIM}Fill in each frame's scene + voiceover, then show the director: the editor's ${BOLD}Storyboard${RESET}${DIM} view renders this file as a contact sheet with a comment box per frame (vidfarm serve → open the composition → Storyboard).${RESET}`);
+        console.log(`${DIM}Advance each frame as you build it: status outline → built (a real sub-composition at src:) → animated.${RESET}`);
+        return;
+    }
+    const read = readStoryboard(dir);
+    const stage = storyboardStage(read.manifest.frames);
+    if (json) {
+        return printJson({
+            ok: true,
+            exists: read.exists,
+            path: read.path,
+            dir,
+            stage,
+            globals: read.manifest.globals,
+            frames: read.manifest.frames,
+            warnings: read.manifest.warnings,
+            script: { exists: read.script.exists, path: read.script.path }
+        });
+    }
+    if (!read.exists) {
+        console.log(`${YELLOW}No ${STORYBOARD_FILENAME} in ${dir}.${RESET}`);
+        console.log(`${DIM}Draft the plan first — it's the cheapest place to get the director's approval: ${BOLD}vidfarm storyboard ${path.relative(process.cwd(), dir) || "."} --init --frames "Hook,Problem,Reveal,Proof,CTA"${RESET}`);
+        return;
+    }
+    const g = read.manifest.globals;
+    console.log(`${BOLD}Storyboard${RESET} ${DIM}${read.absPath}${RESET}`);
+    if (g.message)
+        console.log(`  ${DIM}message${RESET}  ${g.message}`);
+    if (g.arc)
+        console.log(`  ${DIM}arc${RESET}      ${g.arc}`);
+    if (g.audience)
+        console.log(`  ${DIM}audience${RESET} ${g.audience}`);
+    if (g.format)
+        console.log(`  ${DIM}format${RESET}   ${g.format}`);
+    const counts = { outline: 0, built: 0, animated: 0 };
+    for (const f of read.manifest.frames)
+        counts[f.status]++;
+    console.log(`  ${DIM}stage${RESET}    ${stage}  ${DIM}(${counts.outline} outline · ${counts.built} built · ${counts.animated} animated)${RESET}`);
+    console.log("");
+    for (const f of read.manifest.frames) {
+        const mark = f.status === "animated" ? `${GREEN}●${RESET}` : f.status === "built" ? `${YELLOW}◐${RESET}` : `${DIM}○${RESET}`;
+        console.log(`  ${mark} ${String(f.number ?? f.index).padStart(2, "0")}  ${f.title ?? "(untitled)"}${f.duration ? ` ${DIM}${f.duration}${RESET}` : ""}`);
+        if (f.scene)
+            console.log(`       ${DIM}${f.scene}${RESET}`);
+        if (f.voiceover)
+            console.log(`       ${DIM}VO: ${f.voiceover}${RESET}`);
+        if (f.src)
+            console.log(`       ${DIM}src: ${f.src}${RESET}`);
+    }
+    if (read.script.exists)
+        console.log(`\n${DIM}Narration script: ${path.join(dir, read.script.path)}${RESET}`);
+    for (const w of read.manifest.warnings)
+        console.log(`${YELLOW}warn:${RESET} ${DIM}${w.message}${RESET}`);
+    console.log(`\n${DIM}Show it to the director in the editor's ${BOLD}Storyboard${RESET}${DIM} view (per-frame comments come back to you), then build frame by frame.${RESET}`);
+}
+// `vidfarm mode [interactive|autonomous]` — show or set whether the HUMAN is in
+// the loop. Independent of cost mode: any cost mode runs either way, and the
+// pair is what determines the plan. Quality usually goes UP in interactive —
+// most of all in `minimize`, where free frontier web models stand in for the AI
+// budget the user isn't spending.
+async function runInteractionModeCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), note: { type: "string" }, clear: { type: "boolean", default: false } }
+    });
+    const json = Boolean(parsed.values.json);
+    const home = parsed.values.home;
+    if (parsed.values.clear) {
+        const removed = clearStoredInteractionMode(home);
+        if (json)
+            return printJson({ ok: true, cleared: removed });
+        console.log(removed ? `${GREEN}Cleared saved interaction mode.${RESET}` : `${DIM}No saved interaction mode to clear.${RESET}`);
+        return;
+    }
+    const requested = parsed.positionals[0];
+    if (requested) {
+        const mode = normalizeInteractionMode(requested);
+        if (!mode) {
+            throw new Error(`Unknown interaction mode "${requested}". Choose one of: ${INTERACTION_MODES.join(", ")}.`);
+        }
+        const savedAt = new Date().toISOString();
+        const file = writeStoredInteractionMode(mode, savedAt, parsed.values.note ?? null, home);
+        if (json)
+            return printJson({ ok: true, interaction_mode: mode, saved_at: savedAt, file });
+        console.log(`${GREEN}${BOLD}Interaction mode: ${mode}${RESET}`);
+        console.log(`${DIM}${INTERACTION_MODE_BLURB[mode]}${RESET}`);
+        console.log(`${DIM}Saved to ${file}.${RESET}`);
+        if (mode === "interactive") {
+            console.log(`${DIM}Hand-offs: ${BOLD}vidfarm handoff image --theme "<what>" --items "a,b,c"${RESET}${DIM} (sticker pack — the default for manual art)` +
+                ` · ${BOLD}vidfarm handoff raws --keywords "<kw>,<kw>"${RESET}${DIM} (manual clip sourcing).${RESET}`);
+        }
+        const cost = resolveCostMode(parsed.values);
+        if (!cost.isSet) {
+            console.log(`${DIM}Cost preference still unset — ask that too: vidfarm cost-mode <${COST_MODE_DISPLAY_LIST.join("|")}>.${RESET}`);
+        }
+        else if (cost.mode === "minimize" && mode === "interactive") {
+            console.log(`${DIM}minimize + interactive is the sweet spot: $0 videos that still get custom art (free web image gen → vidfarm sticker-pack) and hand-picked footage.${RESET}`);
+        }
+        return;
+    }
+    const resolved = resolveInteractionMode(parsed.values);
+    const cost = resolveCostMode(parsed.values);
+    if (json) {
+        return printJson({
+            ok: true,
+            interaction_mode: resolved.mode,
+            is_set: resolved.isSet,
+            source: resolved.source,
+            cost_mode: cost.mode,
+            cost_mode_is_set: cost.isSet
+        });
+    }
+    console.log(`${BOLD}${interactionModeSummaryLine(resolved)}${RESET}`);
+    console.log(`${DIM}${costModeSummaryLine(cost)}${RESET}`);
+    console.log("");
+    console.log(interactionModeExplainer());
+    console.log("");
+    console.log(`${DIM}Set it: ${BOLD}vidfarm mode <${INTERACTION_MODES.join("|")}>${RESET}${DIM} · forget it: vidfarm mode --clear · per-run: --interactive / --autonomous.${RESET}`);
+    if (!resolved.isSet) {
+        console.log(`${DIM}Nothing saved yet — ask the user before you either spend credits or quietly skip custom art.${RESET}`);
+    }
+}
+// `vidfarm handoff <image|raws>` — mint the copy-paste brief an INTERACTIVE-mode
+// user works from. The agent prints this verbatim, the user does one manual step
+// (paste a prompt into a free image tool / search + download some clips), and
+// the agent picks the files back up with the printed follow-up command.
+async function runHandoffCommand(argv) {
+    const kind = (argv[0] ?? "").trim().toLowerCase();
+    const rest = argv.slice(1);
+    const parsed = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            // image
+            theme: { type: "string" },
+            items: { type: "string" },
+            style: { type: "string" },
+            "key-color": { type: "string" },
+            "out-dir": { type: "string" },
+            grid: { type: "string" },
+            single: { type: "boolean", default: false },
+            // raws
+            keywords: { type: "string" },
+            platforms: { type: "string" },
+            count: { type: "string" },
+            purpose: { type: "string" }
+        }
+    });
+    const json = Boolean(parsed.values.json);
+    const splitList = (raw) => (raw ?? "").split(/\s*[;,]\s*/).map((s) => s.trim()).filter(Boolean);
+    if (kind === "image" || kind === "images" || kind === "sticker-pack" || kind === "stickers") {
+        const theme = parsed.values.theme?.trim() || parsed.positionals.join(" ").trim();
+        const items = splitList(parsed.values.items);
+        if (!theme && !items.length) {
+            throw new Error('handoff image needs a subject: `vidfarm handoff image --theme "cozy farm props" --items "barn,tractor,hay bale"` (or pass the theme as a positional).');
+        }
+        const brief = buildImageHandoff({
+            theme: theme || items.join(", "),
+            items,
+            style: parsed.values.style,
+            keyColor: parsed.values["key-color"],
+            outDir: parsed.values["out-dir"],
+            grid: parsed.values.grid,
+            pack: parsed.values.single ? false : undefined
+        });
+        if (json)
+            return printJson({ ok: true, kind: "image", pack: !parsed.values.single, ...brief });
+        if (brief.keyColorNote)
+            console.log(`${YELLOW}Plate:${RESET} ${DIM}${brief.keyColorNote}${RESET}\n`);
+        console.log(formatHandoff(`${BOLD}Free image hand-off${RESET} ${DIM}— you generate it in a free web tool, I cut it up locally for $0.${RESET}`, brief, { promptLabel: `${DIM}─── copy this prompt into the image tool ───${RESET}` }));
+        return;
+    }
+    if (kind === "raws" || kind === "clips" || kind === "footage") {
+        const keywords = splitList(parsed.values.keywords ?? parsed.positionals.join(","));
+        if (!keywords.length) {
+            throw new Error('handoff raws needs keywords: `vidfarm handoff raws --keywords "villa construction,pouring concrete" --platforms tiktok,youtube`.');
+        }
+        const brief = buildRawsHandoff({
+            keywords,
+            platforms: splitList(parsed.values.platforms),
+            count: parsed.values.count !== undefined ? Number(parsed.values.count) : undefined,
+            purpose: parsed.values.purpose,
+            outDir: parsed.values["out-dir"]
+        });
+        if (json)
+            return printJson({ ok: true, kind: "raws", ...brief });
+        console.log(formatHandoff(`${BOLD}Manual clip-sourcing hand-off${RESET} ${DIM}— your eye picks better clips than a keyword scan.${RESET}`, brief, { promptLabel: `${DIM}─── search + download these ───${RESET}` }));
+        console.log(`${DIM}Note: try browser control or \`vidfarm raws scan <url>\` first — only hand this to the user when neither is available, or when you want a human's taste on the picks.${RESET}`);
+        return;
+    }
+    throw new Error('handoff needs a kind: `vidfarm handoff image --theme "…" --items "a,b,c"` (free web image gen → sticker pack) or `vidfarm handoff raws --keywords "…"` (manual clip sourcing).');
 }
 async function runProviderKeysCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: false, options: commonOptions() });
@@ -8615,6 +9448,149 @@ async function runLintCommand(argv) {
     if (!result.ok)
         process.exitCode = 1;
 }
+// `vidfarm qa <dir|composition.html>` — the social-native QA pass. Compositions
+// are authored in HTML, so an agent's web-page instincts leak in as landing-page
+// furniture (gradient CTA capsules, benefit chip rows, frosted cards) that never
+// appears in a real TikTok. This is a BLOCKLIST of those specific patterns plus
+// the font regime — deliberately NOT an allowlist, so weird/ugly/hand-made
+// compositions pass untouched and nothing pushes every video toward one style.
+//
+// FEEDBACK, NOT A GATE: exit code stays 0 even when slop is found, unless the
+// caller opts into --strict. Nothing in the render path calls this. It is a
+// devcli-only capability (no cloud/REST twin) — heavily recommended after every
+// production, never mandatory and never automatic.
+async function runQaCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean", default: false },
+            strict: { type: "boolean", default: false },
+            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]`.");
+    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)));
+    }
+    if (parsed.values.json) {
+        printJson(report);
+        if (!report.ok && parsed.values.strict)
+            process.exitCode = 1;
+        return;
+    }
+    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 }));
+    }
+    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;
+    if (report.verdict === "clean") {
+        console.log(`${GREEN}✓ no HTML slop found${graded ? ", regime 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}`);
+    }
+    else {
+        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);
+    if (pendingReview) {
+        console.log(`${DIM}${pendingReview} regime 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}`);
+    }
+    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) {
+    const sub = argv[0];
+    const parsed = parseArgs({
+        args: argv.slice(1),
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean", default: false },
+            out: { type: "string" },
+            dir: { type: "string" },
+            force: { type: "boolean", default: false }
+        }
+    });
+    const json = Boolean(parsed.values.json);
+    if (!sub || sub === "list") {
+        const builtins = listBuiltinRegimes();
+        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}`);
+        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}`);
+        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);
+        const raw = readFileSync(file, "utf8");
+        if (json)
+            return printJson(parseRegime(raw, file));
+        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);
+        const outPath = parsed.values.out
+            ? path.resolve(String(parsed.values.out))
+            : path.resolve(String(parsed.values.dir ?? "."), "QA_REGIME.md");
+        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 });
+        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>]`);
+}
 // `vidfarm stills <dir|composition.html>` — render PNG stills of the CURRENT
 // composition in-process (the agent's visual self-verification loop).
 async function runStillsCommand(argv) {