@officexapp/vidfarm-devcli 0.21.26 → 0.21.28

package/dist/src/cli.js

@@ -19,6 +19,7 @@ import { formatCompositionLintIssues, lintCompositionHtml } from "./services/com
 import { resolveFfmpeg } from "./services/clip-curation/ffmpeg.js";
 import { parseHyperframesJson, runHyperframesCommand } from "./devcli/hyperframes-cli.js";
 import { renderCompositionStills } from "./devcli/stills.js";
+import { formatQaReport, qaCompositionHtml } from "./devcli/qa-check.js";
 import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders, cropImageRegion } from "./devcli/greenscreen-local.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
@@ -80,9 +81,12 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
   whoami                    Show the logged-in account, host, plan, and cost mode
   cost-mode [mode]          Show or set the money-saving preference all billed
                             commands respect, quoted per finished video:
-                            minimize = $0 · hybrid = ~$0.01-$1 · rich-ai = $1+.
+                            minimize = $0 · hybrid = ~$0.01-$1 · rich-ai = $1+
+                            (AI video gen → REUSABLE greenscreen raws, remixed
+                            with hyperframes) · pure-videogen = $5+ (script →
+                            storyboard → frame-by-frame generated scenes).
                             Spend is billed to YOUR AI provider keys (BYOK).
-                            No arg = show current + explain the three simply.
+                            No arg = show current + explain them simply.
                             --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.
@@ -122,9 +126,17 @@ Discover & inspiration (browse the viral-video catalog, add your own source):
     --limit <n>             Max results
     --cursor <cursor>       Continue from next_cursor
     --sort <mode>           relevance, wow, automation, or recent
-  public-raws [query...]    Browse PUBLIC RAWS (feed / categories)       → GET  /api/v1/public-raws
+  public-raws [query...]    Browse PUBLIC RAWS — free, cleared B-roll you  → GET  /api/v1/public-raws
+                            can drop straight into a composition.
+    --categories            LIST THE SHELVES first (curated categories +   → GET  /api/v1/public-raws/categories
+                            live counts + what each is FOR). The cheapest
+                            way to find footage: pick a shelf, then pull
+                            it with --category. Great for bulk scripting —
+                            one shelf is a ready-made clip pool.
     --query <text>          Keyword/vector query over title + metadata
-    --category <key>        Filter one public-raw category (e.g. emotion:confused)
+    --category <name>       Filter ONE category. Takes a curated shelf
+                            ("scroll-stoppers", "greenscreen", "reaction")
+                            or an exact taxonomy key (emotion:confused).
     --type <raw_type>       Filter one raw family (greenscreen, b_roll, ...)
     --freshness-days <n>    Only raws newer than N days
     --bookmark <raw_id>     Save that public raw into /raws/public/*     → POST /api/v1/public-raws/:rawId/bookmark
@@ -187,6 +199,35 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --no-wait               Return the job id instead of polling to the URL
     --place <dir>           After generating, place it into that composition
     --at <time> | --replace <layer_key>   Placement (fill gap vs replace scene)
+  sequence <step>           STORYBOARD-DRIVEN VIDEO — brief → character card → storyboard
+                            sheet → shot prompt → AI video → final cut. Resumable:
+                            all state lives in sequence.json, rerunning a finished
+                            step is a no-op. (aliases: storyboard, previz)
+    init "<brief>"          Scaffold sequence.json + PLAN_TASK.md from one line
+      --dir <path>          Project folder (default: vidfarm-sequence-<brief>)
+      --parts <n>           Shots to chain; part 2+ extends the one before (default 1)
+      --panels <n>          Panels per storyboard sheet (default 8)
+      --duration <s>        Seconds per part (default 15); --aspect-ratio <r> (16:9)
+      --style "<look>"      Final-film style lock, e.g. "painterly anime, crisp daylight"
+      --board-style <k>     rough = monochrome previz (default) | final = rendered in
+                            the final look, so the board doubles as a style check
+      --character <name> --character-description "<silhouette, wardrobe>"
+      --no-laban            Drop the Laban weight/time/space/flow movement block
+    plan                    Write PLAN_TASK.md for a desktop agent to direct the
+                            sequence properly; --check validates the plan instead
+    characters              One identity sheet per character   [cheap, ~$0.05 each]
+    boards                  One storyboard sheet per part      [cheap, ~$0.05 each]
+    prompts                 Compose the video prompts (free, local, deterministic)
+      --print <kind>:<id>   Preview a prompt without spending: board:part-01,
+                            shot:part-01, card:<slug>
+    animate                 Generate video per part            [EXPENSIVE, ~$1+ each]
+      --resolution <r> --audio --provider <p> --model <m>
+    assemble                ffmpeg-concat the parts into renders/final.mp4  [free]
+      --music <file|url>    Lay a music bed under the cut; --out <path>
+    run                     All of the above in order, with a confirm gate before
+                            each spend. --yes runs it fully autonomously.
+    status                  What's done, what's next (the default step)
+      --force               Redo a completed step; --part <id> / --only <slug> scope it
   inpaint <image|url>       Masked image EDIT — replace ONLY the painted region  → POST /api/v1/primitives/images/inpaint
     --mask <png|@file|url>  Alpha-mask PNG: TRANSPARENT pixels = the editable region (required)
     --prompt <text>         Whole-image edit instruction (what to put in the mask)
@@ -209,6 +250,28 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --out <file>            Download the transparent PNG to this path
     --no-wait               Return the job id instead of polling to the URL
     --place <dir> --at <time>|--replace <layer_key>   Fuse onto a composition
+  avatar "<who they are>"   CREATE AN AVATAR — a TALKING HEAD video with lip-synced
+                            spoken audio, generated on a forced greenscreen plate and
+                            chroma-keyed in the same job → transparent presenter WebM
+                            you composite over any background. (aliases: talking-head,
+                            spokesperson) → POST /api/v1/primitives/videos/create-avatar
+    --say "<line>"          What the avatar SAYS out loud, verbatim (alias --script)
+    --voice <desc>          Delivery note, e.g. "warm, upbeat, mid-tempo"
+    --ref <url|@file|id>    Likeness reference — headshot or character sprite card
+                            (repeatable) → input_references
+    --duration <s>          Clip length in seconds; --resolution 720p|1080p
+    --aspect-ratio <r>      e.g. 9:16 (match where it lands)
+    --preset <name>         Plate color: green (default) | digital-green | blue |
+                            white | black | magenta; --key-color <hex> overrides
+    --tolerance <0..1>      Key radius (default 0.3); --softness <0..1> feather (0.1)
+    --no-despill            Skip edge color-fringe suppression
+    --local                 Generate in the cloud (your keys), key on YOUR machine
+                            with bundled ffmpeg for free
+    --keep-greenscreen      Stop at the raw greenscreen MP4; don't key it at all
+    --provider <p> --model <m>   Video provider/model overrides (omit to auto-pick)
+    --out <file>            Write the finished avatar here
+    --no-wait               Return the job id instead of polling to the URL
+    --place <dir> --at <time>|--replace <layer_key>   Fuse onto a composition
   remove-greenscreen <image|video|url>   Key out a FLAT solid background from an
                             IMAGE (→ transparent PNG/WebP) or VIDEO (→ transparent
                             WebM/VP9 alpha), auto-detecting the media kind.
@@ -533,6 +596,16 @@ 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
+    --json                    Machine-readable findings (rule/severity/fix)
+    --strict                  Also exit 1 when slop is found (for CI)
   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
@@ -689,15 +762,19 @@ Cost spectrum (default to the cheapest approach that works; see SKILL.director.m
   Notes: image gen is cheap (use freely); AI VIDEO gen is expensive (ask the user
   first). Decompose is a one-time ~$0.10 — or skip it by forking a decomposed template.
   Per-video budget by mode: minimize = $0 (explicitly free), hybrid = ~$0.01-$1,
-  rich-ai = $1+. All of it is billed to YOUR OWN AI provider keys (BYOK) — add them
-  with 'vidfarm add-provider-key <provider> <key>' or at vidfarm.cc/settings/developer.
-  Set 'vidfarm cost-mode <minimize|hybrid|rich-ai>' once and every billed command
-  (generate, music, decompose, cloud render/TTS/STT/greenscreen, create, replicate)
+  rich-ai = $1+ (AI video gen buys REUSABLE greenscreen raws — keyed once, then remixed
+  with hyperframes HTML/CSS motion and saved for later hybrid/minimize videos),
+  pure-videogen = $5+ (no reuse at all: text script → image storyboard → frame-by-frame
+  generation of every scene). All of it is billed to YOUR OWN AI provider keys (BYOK) —
+  add them with 'vidfarm add-provider-key <provider> <key>' or vidfarm.cc/settings/developer.
+  Set 'vidfarm cost-mode <minimize|hybrid|rich-ai|pure-videogen>' once and every billed
+  command (generate, music, decompose, cloud render/TTS/STT/greenscreen, create, replicate)
   respects it: minimize refuses billed spend without --yes and points you at the free
-  local path; hybrid/rich-ai run but print each op's cost. FREE local engines never gate
+  local path; the others run but print each op's cost. FREE local engines never gate
   (local render, tts --engine local, stt --engine whisper, remove-greenscreen --local).
   In minimize AND hybrid, 'vidfarm tts' DEFAULTS to the free local Kokoro voice — ask for
-  a premium voice (--style/--voice/--provider/--own-key/--cloud) or rich-ai to opt out.
+  a premium voice (--style/--voice/--provider/--own-key/--cloud), or be in rich-ai /
+  pure-videogen, to opt out.
 
 Escape hatch — call ANY route directly:
   api <METHOD> <path>       Raw REST call with auth + pretty errors
@@ -848,6 +925,11 @@ async function main() {
         case "generate":
             await runGenerateCommand(rest);
             return;
+        case "sequence":
+        case "storyboard":
+        case "previz":
+            await runSequenceCommand(rest);
+            return;
         case "inpaint":
             await runInpaintCommand(rest);
             return;
@@ -855,6 +937,11 @@ async function main() {
         case "overlay":
             await runCreateOverlayCommand(rest);
             return;
+        case "avatar":
+        case "talking-head":
+        case "spokesperson":
+            await runAvatarCommand(rest);
+            return;
         case "remove-greenscreen":
         case "remove-background-greenscreen":
         case "rmbg-green":
@@ -1101,6 +1188,11 @@ async function main() {
         case "lint":
             await runLintCommand(rest);
             return;
+        case "qa":
+        case "qa-check":
+        case "slop-check":
+            await runQaCommand(rest);
+            return;
         case "stills":
             await runStillsCommand(rest);
             return;
@@ -1233,7 +1325,7 @@ function commonOptions() {
         local: { type: "boolean", default: false },
         cloud: { type: "boolean", default: false },
         both: { type: "boolean", default: false },
-        // Money-saving preference: minimize | hybrid | pure-ai. Flag > VIDFARM_COST_MODE
+        // Money-saving preference: minimize | hybrid | rich-ai | pure-videogen. Flag > VIDFARM_COST_MODE
         // 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" },
@@ -2080,6 +2172,8 @@ 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).
+- 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 font regime and 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.
@@ -2633,10 +2727,25 @@ async function runPublicRawsCommand(argv) {
             category: { type: "string" },
             type: { type: "string" },
             "freshness-days": { type: "string" },
-            bookmark: { type: "string" }
+            bookmark: { type: "string" },
+            categories: { type: "boolean", default: false }
         }
     });
     const ctx = commonContext(parsed.values);
+    // `--categories` is the map BEFORE the territory: the curated shelves with
+    // live counts. Start here when you don't know what footage exists — pick a
+    // shelf, then re-run with --category <slug> to pull its clips.
+    if (parsed.values.categories) {
+        const result = await apiRequest({
+            method: "GET",
+            host: ctx.host,
+            path: "/api/v1/public-raws/categories",
+            auth: ctx.auth
+        });
+        assertApiOk(result, "public-raws categories");
+        emitResult(result, ctx.json, [["Browse ", `${ctx.host}/discover/raws/categories`]]);
+        return;
+    }
     const bookmark = parsed.values.bookmark?.trim();
     if (bookmark) {
         const result = await apiRequest({
@@ -3484,6 +3593,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;
     }
@@ -4152,6 +4264,74 @@ async function runGenerateCommand(argv) {
             console.log(`${DIM}Place it with: vidfarm place <dir> --src "${mediaUrl}" --kind ${mediaType} --at <time>|--replace <layer_key>${RESET}`);
     }
 }
+// ── Sequence: storyboard-driven AI video pipeline ────────────────────────────
+// `vidfarm sequence` is a multi-step, resumable director's workflow: brief →
+// character card → storyboard sheet → shot prompt → AI video → final cut. The
+// orchestration + disk state live in devcli/sequence.ts and the prompt grammar
+// in services/sequence-prompts.ts; this wrapper only supplies the cloud seam
+// (auth, primitive jobs, cost gating, downloads) so there is exactly one copy
+// of the REST plumbing.
+/** Submit a primitive generate job and poll it to a finished media URL. */
+async function generatePrimitiveMedia(ctx, kind, payload) {
+    const tracer = `devcli-seq-${Date.now().toString(36)}`;
+    const route = kind === "video" ? "/api/v1/primitives/videos/generate" : "/api/v1/primitives/images/generate";
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: route, auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, `generate ${kind}`);
+    const jobId = submit.json?.job_id;
+    if (!jobId)
+        throw new Error(`generate ${kind} did not return a job id.`);
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const url = resolveJobMediaUrl(job);
+    if (!url) {
+        throw new Error(`generate ${kind} ${String(job?.status ?? "did not finish")} — no media URL (job ${jobId}).`);
+    }
+    return { url, jobId };
+}
+async function runSequenceCommand(argv) {
+    // Parsed loosely: the subcommand flags live in devcli/sequence.ts, and this
+    // pass only needs the shared host/auth/cost-mode options.
+    const parsed = parseArgs({ args: argv, allowPositionals: true, strict: false, options: commonOptions() });
+    const ctx = commonContext(parsed.values);
+    const { runSequenceCommand: run } = await import("./devcli/sequence.js");
+    await run(argv, {
+        json: ctx.json,
+        yes: ctx.yes,
+        guardBilled: (input) => guardBilled(ctx, input),
+        resolveRefs: (values) => resolveReferenceUrls(ctx, values),
+        async generateImage(input) {
+            const payload = { prompt: input.prompt };
+            if (input.aspectRatio)
+                payload.aspect_ratio = input.aspectRatio;
+            if (input.provider)
+                payload.provider = input.provider;
+            if (input.model)
+                payload.model = input.model;
+            if (input.refs.length)
+                payload.prompt_attachments = input.refs.slice(0, 16);
+            return generatePrimitiveMedia(ctx, "image", payload);
+        },
+        async generateVideo(input) {
+            const payload = {
+                prompt: input.prompt,
+                duration: Math.round(input.durationSeconds)
+            };
+            if (input.aspectRatio)
+                payload.aspect_ratio = input.aspectRatio;
+            if (input.resolution)
+                payload.resolution = input.resolution;
+            if (input.audio)
+                payload.generate_audio = true;
+            if (input.provider)
+                payload.provider = input.provider;
+            if (input.model)
+                payload.model = input.model;
+            if (input.refs.length)
+                payload.input_references = input.refs.slice(0, 8);
+            return generatePrimitiveMedia(ctx, "video", payload);
+        },
+        download: (url, dest) => downloadUrlToFile(url, dest, ctx.auth.apiKey ? { "vidfarm-api-key": ctx.auth.apiKey } : undefined)
+    });
+}
 // ── Inpaint: masked image edit ───────────────────────────────────────────────
 // The devcli twin of the web /tools/image page. The browser page rasterizes painted
 // strokes into an alpha mask (transparent = editable), composes one provider
@@ -4473,6 +4653,236 @@ async function runCreateOverlayCommand(argv) {
             console.log(`${DIM}Place it with: vidfarm place <dir> --src "${mediaUrl}" --kind image --at <time>|--replace <layer_key>${RESET}`);
     }
 }
+// ── avatar: talking-head presenter, keyed off its greenscreen ────────────────
+// "Create an avatar" is ALWAYS this: a generated VIDEO of a talking head with
+// lip-synced spoken audio, shot on a flat key-color plate, then chroma-keyed so
+// the presenter composites over whatever is behind them. The devcli twin of the
+// talking_avatar primitive.
+//
+// The generation leg is always the cloud primitive (it rides the caller's own
+// saved video-provider keys — BYOK, same as the web app). The KEYING leg is
+// where local/cloud differ:
+//   default   → the same job keys it in the cloud → browser-ready transparent
+//               WebM (VP9 alpha, audio preserved) you can drop straight in.
+//   --local   → the job returns the raw greenscreen MP4 and bundled ffmpeg keys
+//               it on your machine for free (ProRes .mov fallback if this
+//               ffmpeg build can't write VP9 alpha).
+//   --keep-greenscreen → stop at the plate; don't key at all.
+async function runAvatarCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            prompt: { type: "string" },
+            // What the avatar says out loud. `--script` is the alias.
+            say: { type: "string" },
+            script: { type: "string" },
+            voice: { type: "string" },
+            // Likeness references: headshot, character sprite card, brand photo.
+            ref: { type: "string", multiple: true },
+            duration: { type: "string" },
+            resolution: { type: "string" },
+            "aspect-ratio": { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            // Plate + keying knobs (mirror remove-greenscreen).
+            preset: { type: "string" },
+            "key-color": { type: "string" },
+            tolerance: { type: "string" },
+            softness: { type: "string" },
+            "no-despill": { type: "boolean", default: false },
+            local: { type: "boolean", default: false },
+            "keep-greenscreen": { type: "boolean", default: false },
+            out: { type: "string" },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" },
+            // Fused placement onto a local composition.html (same as `generate`).
+            place: { type: "string" },
+            at: { type: "string" },
+            replace: { type: "string" },
+            track: { type: "string" },
+            transition: { type: "string" },
+            "transition-duration": { type: "string" },
+            "transition-out": { type: "string" },
+            "transition-out-duration": { type: "string" },
+            "layer-key": { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    guardBilled(ctx, {
+        label: "AI talking-avatar video (generation with audio + chroma key)",
+        estimate: "expensive, ~$0.50–$1.50 (AI video)",
+        freeAlternative: 'reuse a free talking-head clip — vidfarm public-raws --category talking-head — or key an existing greenscreen clip with vidfarm remove-greenscreen --local ($0)'
+    });
+    const prompt = (parsed.values.prompt ?? parsed.positionals.join(" ")).trim();
+    if (!prompt) {
+        throw new Error('avatar requires a description of WHO the avatar is: `vidfarm avatar "friendly 30-something founder in a hoodie" --say "Here is why we built this."` — describe the person, not the background (the greenscreen plate is forced for you).');
+    }
+    const script = (parsed.values.say ?? parsed.values.script ?? "").trim();
+    const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
+    const presetRaw = parsed.values.preset?.trim().toLowerCase();
+    if (presetRaw && !GREENSCREEN_PRESETS[presetRaw]) {
+        throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${Object.keys(GREENSCREEN_PRESETS).join(", ")}, or pass --key-color <hex>.`);
+    }
+    // --local keys on this machine, so ask the cloud job for the raw plate.
+    const keyLocally = Boolean(parsed.values.local);
+    const keepPlate = Boolean(parsed.values["keep-greenscreen"]);
+    const payload = { prompt };
+    if (script)
+        payload.script = script;
+    if (parsed.values.voice)
+        payload.voice = parsed.values.voice;
+    if (refs.length)
+        payload.input_references = refs.slice(0, 8);
+    if (parsed.values.duration)
+        payload.duration = Math.round(Number(parsed.values.duration));
+    if (parsed.values.resolution)
+        payload.resolution = parsed.values.resolution;
+    if (parsed.values["aspect-ratio"])
+        payload.aspect_ratio = parsed.values["aspect-ratio"];
+    if (parsed.values.provider)
+        payload.provider = parsed.values.provider;
+    if (parsed.values.model)
+        payload.model = parsed.values.model;
+    if (presetRaw)
+        payload.preset = presetRaw;
+    if (parsed.values["key-color"])
+        payload.key_color = parsed.values["key-color"];
+    if (parsed.values.tolerance)
+        payload.tolerance = Number(parsed.values.tolerance);
+    if (parsed.values.softness)
+        payload.softness = Number(parsed.values.softness);
+    if (parsed.values["no-despill"])
+        payload.despill = false;
+    if (keyLocally || keepPlate)
+        payload.keep_greenscreen = true;
+    const tracer = parsed.values.tracer ?? `devcli-avatar-${Date.now().toString(36)}`;
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/videos/create-avatar", auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "avatar");
+    const jobId = submit.json?.job_id;
+    const wait = !parsed.values["no-wait"];
+    if (!wait || !jobId) {
+        if (!ctx.json && jobId)
+            console.log(`${DIM}Queued ${jobId} (tracer ${tracer}). Poll: vidfarm api GET /api/v1/user/me/jobs/${jobId} — or drop --no-wait to auto-poll.${RESET}`);
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json) {
+        console.log(`${DIM}Generating talking avatar${script ? ` saying "${script.slice(0, 60)}${script.length > 60 ? "…" : ""}"` : ""} on a greenscreen plate (${jobId})… polling every 5s.${RESET}`);
+    }
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const mediaUrl = resolveJobMediaUrl(job);
+    const status = String(job?.status ?? "");
+    if (!mediaUrl) {
+        if (ctx.json) {
+            printJson({ ok: false, job_id: jobId, status, job });
+        }
+        else {
+            console.log(`${RED}Avatar ${status || "did not finish"} — no media URL. Check your video-provider key and wallet.${RESET}`);
+            printJson(job);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // Local keying leg: pull the plate down and run the free ffmpeg keyer on it.
+    let localOut = null;
+    if (keyLocally && !keepPlate) {
+        const downloadDir = mkdtempSync(path.join(tmpdir(), "vidfarm-avatar-"));
+        const platePath = path.join(downloadDir, "avatar-greenscreen.mp4");
+        try {
+            if (!ctx.json)
+                console.log(`${DIM}Downloading the greenscreen plate…${RESET}`);
+            await downloadUrlToFile(mediaUrl, platePath);
+            const preset = presetRaw ? GREENSCREEN_PRESETS[presetRaw] : undefined;
+            const outPath = parsed.values.out
+                ? path.resolve(process.cwd(), String(parsed.values.out))
+                : path.resolve(process.cwd(), "avatar.webm");
+            mkdirSync(path.dirname(outPath), { recursive: true });
+            if (!ctx.json)
+                console.log(`${DIM}Keying the avatar off its greenscreen locally with ffmpeg (free)…${RESET}`);
+            localOut = await removeGreenscreenLocal({
+                sourcePath: platePath,
+                mediaType: "video",
+                outputPath: outPath,
+                keyColor: parsed.values["key-color"] ?? preset?.key_color,
+                tolerance: parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : preset?.tolerance,
+                softness: parsed.values.softness !== undefined ? Number(parsed.values.softness) : preset?.softness,
+                despill: !parsed.values["no-despill"]
+            });
+        }
+        finally {
+            rmSync(downloadDir, { recursive: true, force: true });
+        }
+    }
+    // Whatever the caller ends up placing/saving: the local cut-out if we keyed
+    // here, otherwise the cloud result (transparent WebM, or the plate with
+    // --keep-greenscreen).
+    const finalSrc = localOut?.outputPath ?? mediaUrl;
+    let outPath = localOut?.outputPath ?? null;
+    if (!localOut && parsed.values.out) {
+        outPath = path.resolve(process.cwd(), String(parsed.values.out));
+        await downloadUrlToFile(mediaUrl, outPath);
+    }
+    let placement = null;
+    if (parsed.values.place) {
+        const htmlPath = resolveCompositionHtmlPath(String(parsed.values.place));
+        placement = placeMediaOnDisk({
+            htmlPath,
+            src: finalSrc,
+            kind: "video",
+            at: parsed.values.at ? parseTimeToSeconds(String(parsed.values.at)) : undefined,
+            replace: parsed.values.replace,
+            track: parsed.values.track ? Number(parsed.values.track) : undefined,
+            transition: parsed.values.transition,
+            transitionDuration: parsed.values["transition-duration"] ? Number(parsed.values["transition-duration"]) : undefined,
+            transitionOut: parsed.values["transition-out"],
+            transitionOutDuration: parsed.values["transition-out-duration"] ? Number(parsed.values["transition-out-duration"]) : undefined,
+            layerKey: parsed.values["layer-key"]
+        });
+        if (!ctx.json)
+            console.log(`${GREEN}Placed as ${placement.layerKey} in ${htmlPath}. Run \`vidfarm publish --dir ${path.dirname(htmlPath)}\` (or it live-morphs under \`serve\`).${RESET}`);
+    }
+    const transparent = !keepPlate;
+    if (ctx.json) {
+        printJson({
+            ok: true,
+            job_id: jobId,
+            media_url: mediaUrl,
+            transparent,
+            keyed: keepPlate ? "none" : keyLocally ? "local" : "cloud",
+            format: localOut?.format ?? (keepPlate ? "mp4" : "webm"),
+            out: outPath,
+            placement,
+            script: script || null,
+            greenscreen_source_url: job?.result?.greenscreen_source_url ?? null
+        });
+        return;
+    }
+    if (keepPlate) {
+        console.log(`${GREEN}Avatar greenscreen plate ready:${RESET} ${mediaUrl}`);
+        console.log(`${DIM}Key it whenever you like: vidfarm remove-greenscreen "${mediaUrl}" --local${RESET}`);
+    }
+    else if (localOut) {
+        const label = localOut.format === "webm" ? "Transparent talking avatar (WebM)" : "Transparent talking avatar (ProRes 4444 .mov)";
+        console.log(`${GREEN}${label} ready:${RESET} ${localOut.outputPath}`);
+        if (!localOut.webmAlpha) {
+            console.log(`${YELLOW}Note:${RESET} ${DIM}this ffmpeg build can't write VP9 alpha, so a ProRes .mov alpha master was produced — transparent and free, but not browser/editor-playable. Re-run without ${RESET}--local${DIM} for a browser-ready WebM.${RESET}`);
+        }
+        console.log(`${DIM}Greenscreen plate (re-keyable): ${mediaUrl}${RESET}`);
+    }
+    else {
+        console.log(`${GREEN}Transparent talking avatar ready:${RESET} ${mediaUrl}`);
+        if (outPath)
+            console.log(`${DIM}Saved to ${outPath}${RESET}`);
+        const plate = job?.result?.greenscreen_source_url;
+        if (plate)
+            console.log(`${DIM}Greenscreen plate (re-key at a different tolerance for free): ${plate}${RESET}`);
+    }
+    if (!placement) {
+        console.log(`${DIM}Drop it over a background with: vidfarm place <dir> --src "${finalSrc}" --kind video --at <time> (the alpha survives into the render).${RESET}`);
+    }
+}
 // ── Green-screen (chroma-key) background removal ──────────────────────────────
 // The devcli twin of the remove-greenscreen primitive: key out a flat, solid
 // background from an IMAGE (→ transparent PNG/WebP) OR a VIDEO (→ transparent
@@ -5156,7 +5566,7 @@ async function runTtsCommand(argv) {
     /** 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;
-    if (!engine && !wantCloud && costMode.mode !== "pure-ai" && !premium) {
+    if (!engine && !wantCloud && costMode.mode !== "rich-ai" && costMode.mode !== "pure-videogen" && !premium) {
         try {
             await runLocalKokoroTts({
                 text,
@@ -6838,15 +7248,16 @@ async function runWhoamiCommand(argv) {
         console.log(`${GREEN}${BOLD}${who}${RESET} → ${ctx.host}`);
         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 <minimize|hybrid|rich-ai>)${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}` : ""}`);
         return;
     }
     emitResult(result, ctx.json);
 }
-// `vidfarm cost-mode [minimize|hybrid|rich-ai]` — show or set the money-saving
-// preference every billed command respects. No arg = show current + explain the
-// three simply so an agent can relay them to the user (and be reminded to ask
-// about saving the choice into whatever agent memory it has). `--clear` forgets it.
+// `vidfarm cost-mode [minimize|hybrid|rich-ai|pure-videogen]` — show or set the
+// money-saving preference every billed command respects. No arg = show current +
+// explain the modes simply so an agent can relay them to the user (and be
+// reminded to ask about saving the choice into whatever agent memory it has).
+// `--clear` forgets it.
 async function runCostModeCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -6889,7 +7300,7 @@ async function runCostModeCommand(argv) {
     console.log("");
     console.log(costModeExplainer());
     console.log("");
-    console.log(`${DIM}Set it: ${BOLD}vidfarm cost-mode <minimize|hybrid|rich-ai>${RESET}`);
+    console.log(`${DIM}Set it: ${BOLD}vidfarm cost-mode <${COST_MODE_DISPLAY_LIST.join("|")}>${RESET}`);
     console.log(`${DIM}Forget it: vidfarm cost-mode --clear · override per-run: --cost-mode <m> or VIDFARM_COST_MODE.${RESET}`);
     if (!resolved.isSet) {
         console.log(`${DIM}Nothing saved yet — ask the user which one they want before spending AI credits.${RESET}`);
@@ -8225,6 +8636,54 @@ 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 }
+        }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("qa requires a composition path: `vidfarm qa <dir-or-composition.html> [--json] [--strict]`.");
+    const htmlPath = resolveCompositionHtmlPath(target);
+    const report = qaCompositionHtml(readFileSync(htmlPath, "utf8"));
+    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);
+    const scope = `${report.checked.layers} layer(s), ${report.checked.text_layers} text layer(s)${report.checked.canvas ? `, ${report.checked.canvas}` : ""}`;
+    if (report.verdict === "clean") {
+        console.log(`${GREEN}✓ no HTML slop found${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} 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}`);
+    }
+    if (!report.ok && parsed.values.strict)
+        process.exitCode = 1;
+}
 // `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) {