@officexapp/vidfarm-devcli 0.21.33 → 0.21.35

package/dist/src/cli.js

@@ -19,8 +19,8 @@ import { formatCompositionLintIssues, lintCompositionHtml } from "./services/com
 import { resolveFfmpeg } from "./services/clip-curation/ffmpeg.js";
 import { parseHyperframesJson, runHyperframesCommand } from "./devcli/hyperframes-cli.js";
 import { renderCompositionStills } from "./devcli/stills.js";
-import { extractCompositionFacts, formatQaReport, qaCompositionHtml } from "./devcli/qa-check.js";
-import { discoverRegime, formatRegimeReport, listBuiltinRegimes, loadAndEvaluateRegime, mergeRegimeIntoReport, parseRegime, resolveRegimePath } from "./devcli/qa-regime.js";
+import { extractCompositionFacts, formatQaReport, formatWatchTheVideoNotice, qaCompositionHtml, watchTheVideoDirective } from "./devcli/qa-check.js";
+import { HARNESS_FILENAME, discoverHarness, formatHarnessReport, isLegacyHarnessFilename, listBuiltinHarnesses, loadAndEvaluateHarness, mergeHarnessIntoReport, parseHarness, resolveHarnessPath } from "./devcli/harness.js";
 import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders, cropImageRegion } from "./devcli/greenscreen-local.js";
 import { dedupeMediaLocal, localDedupeAvailable, defaultDedupeOutPath, describeLocalDedupe, DEDUPE_PRESETS, DEDUPE_DEFAULT_PRESET, isDedupePresetName } from "./devcli/dedupe-local.js";
 import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor, keySafeArtInstruction, analyzeKeyedArt, HOLE_WARN_PCT } from "./devcli/sticker-pack.js";
@@ -28,6 +28,7 @@ import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
 import { runSkillsCommand } from "./devcli/skills.js";
+import { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, readPackDoc, searchPackDocs } from "./devcli/skill-docs.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError, localApiRequest } from "./devcli/local-backend.js";
 import { startLocalFrontendServer, serveShellsPresent } from "./devcli/local-frontend-server.js";
@@ -612,7 +613,18 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
     --out <file>              Output mp3 path (default music-<id>.mp3)
     --own-key                 Use your own ElevenLabs key instead of the platform key + wallet
                               (default: platform ElevenLabs, wallet-billed) → POST /api/v1/primitives/music/generate
-  voices                    List ElevenLabs voices for TTS (voice_id + name + labels).
+  voices                    Browse + SAMPLE narration voices (voice_id + name + labels + preview).
+                            Default roster = the premium ElevenLabs catalog reached through
+                            VIDFARM'S OWN ElevenLabs connection: no ElevenLabs account, API key,
+                            or subscription needed — narration on these runs on the platform key
+                            and is billed as vidfarm wallet credits (pennies per narration).
+    --sample                  Write listenable samples to ./voice-samples so a human can CHOOSE by
+                              ear. FREE on both tiers (premium = ElevenLabs' own preview clips,
+                              free = rendered locally) — safe even in cost mode minimize.
+    --sample-count <n>        How many to sample (default 6)
+    --sample-out <dir> | --sample-text "<line>"
+    --search "<text>"         Filter by name/labels/description (e.g. "british narrator")
+    --free                    List the $0 local Kokoro voices instead (--all lists both rosters)
     --own-key                 List voices on your own saved ElevenLabs key (default: platform account)
     --limit <n> | --json      Show more / raw JSON
   stt <file|url>            Video or audio → transcript (alias: transcribe).  LOCAL: local ffmpeg demux +
@@ -716,26 +728,45 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
                             Feedback only: exits 0 even when it finds slop,
                             and it never runs automatically. Blocklist, not
                             allowlist — unusual styles pass untouched
-    --regime <name|path>      Grade against a QA_REGIME.md too (repeatable —
+    --harness <name|path>     Grade against a HARNESS.md too (repeatable —
                               they stack). A built-in name or ANY file path.
-                              <dir>/QA_REGIME.md is picked up automatically
-    --no-regime               Skip QA_REGIME.md auto-discovery
+                              <dir>/HARNESS.md is picked up automatically
+    --no-harness              Skip HARNESS.md auto-discovery
     --json                    Machine-readable findings (rule/severity/fix)
     --strict                  Also exit 1 when slop is found (for CI)
-  regime list|show|init       QA_REGIME.md — the per-style quality contract   (local, devcli-only)
-                            you own, for bulk/scripting mode. Built-ins:
-                            short-form, hooks, ugc-testimonial, explainer,
-                            product-demo
-    regime list [--json]              What ships with the CLI
-    regime show <name|path>           Print one
-    regime init <name> [--out <path>] Copy it next to your work, then EDIT it
-                                      (default ./QA_REGIME.md; --dir <d> to
-                                      write <d>/QA_REGIME.md)
+  harness <sub>               HARNESS.md — the reusable AI harness for ONE     (local, devcli-only)
+                            format or template: what makes it special,
+                            written down so an agent can reproduce it.
+                            "create me a harness" / "update the harness for
+                            this format" / "give me the harness for this
+                            template_id" all land here
+    harness list [--json]             Bundled starting points: short-form,
+                                      hooks, ugc-testimonial, explainer,
+                                      product-demo
+    harness show <name|path>          Print one [--dna <strand>] to print just
+                                      one strand (viral_dna, visual_dna, …)
+    harness init <name> [--out <p>]   Copy one next to your work, then EDIT it
+                                      (default ./HARNESS.md; --dir <d> to
+                                      write <d>/HARNESS.md)
+    harness derive <forkId|dir>       DECOMPOSITION → HARNESS.md. Distils a
+                                      decomposed template's viral/visual/
+                                      structural/audio/build DNA into an
+                                      editable harness [--out <p>] [--force]
+    harness check <dir>               Grade a composition against its harness
+                                      (same engine as vidfarm qa)
   stills <dir|composition.html>   Render PNG stills of the CURRENT        (local in-process render)
                             composition — the visual self-check loop
                             ("did my edit look right") without a full render
     --at 0,2.5,7              Timestamps (default: midpoint of each scene clip, cap 8)
     --out <dir>               Output dir (default <dir>/stills)
+    --sheet                   ALSO tile them into one contact sheet PNG — the
+                              whole-video review pass. Read it as ONE image:
+                              scene-by-scene building drifts (uneven margins,
+                              3 type sizes, a wandering accent colour, N equal
+                              beats, a jarring join) and only a side-by-side
+                              sheet shows it
+    --sheet-out <file>        Sheet path (default <out>/contact-sheet.png)
+    --sheet-width <px>        Per-tile width in the sheet (default 320)
   doctor                    Health-check the local toolchain: node,       (local)
                             ffmpeg, hyperframes engines, Chrome, API key
                             (whoami), provider keys, agent CLI, poisoned
@@ -792,13 +823,27 @@ Account:
   provider-keys             List saved AI provider keys                  → GET  /api/v1/user/me/provider-keys
   add-provider-key <provider> <secret>   Save an AI provider key         → POST /api/v1/user/me/provider-keys
 
-Agent skill (install the latest director skill so your AI agent can act):
+Agent skill (the director knowledge — a full copy SHIPS INSIDE this CLI):
+  skill ls                  List every file in the bundled pack, with sizes  (local — offline, no account)
+  skill show <path>         Print one file. Shorthand works: \`skill show
+                            primitives\`, \`skill show harnesses/README.md\`
+  skill search "<term>"     Grep all of it — the fastest way to find the one
+                            paragraph you need without loading a whole file
+    --limit <n>               Max matches (default 40)
+  skill path                Where the bundled pack lives on disk
+  skill --print             Print the single-file director rollup (bundled
+                            copy; --remote for the host's latest)
+                            NOTE: the bundled pack is pinned to THIS CLI
+                            version — the pairing that actually works. It is
+                            documentation, not entitlement: the free-local
+                            half (clips, hyperframes, serve render, qa,
+                            harnesses, dedupe, local TTS) runs offline, while
+                            AI generation, hosted render, recycle, download
+                            and marketplace still need login + network.
   update-skill              DEPRECATED installer alias; installs the canonical
                             multi-file vidfarm pack via \`skills add\`.
                             Use \`vidfarm skills add vidfarm\` directly.
     --dir <path>            Project root for the canonical pack install
-    --print                 Print the generated single-file director rollup
-                            (copy/share artifact; not the canonical install)
 
 Files (multi-step flows the devcli handles for you):
   upload <file>             Upload to the EPHEMERAL temp store, print URL → presign + S3 PUT + finalize
@@ -1380,9 +1425,13 @@ async function main() {
         case "slop-check":
             await runQaCommand(rest);
             return;
+        case "harness":
+        case "harnesses":
+        // `regime` is the pre-rename name. Kept as a silent alias so old scripts
+        // and old skill copies keep working; every surface says "harness" now.
         case "regime":
         case "regimes":
-            await runRegimeCommand(rest);
+            await runHarnessCommand(rest);
             return;
         case "stills":
             await runStillsCommand(rest);
@@ -2388,9 +2437,10 @@ Rules:
 - For replacement graphics, screenshots, or still-like scenes, prefer AI image generation plus Ken Burns before paying for AI video unless static_vs_pivot says motion footage is load-bearing.
 - If narration must be customized, default to premium ElevenLabs first, then the user's own ElevenLabs path, then BYOK OpenAI/Gemini/OpenRouter. If captions or scenes were timed to the old VO, retime them to the new narration.
 - NO HTML SLOP. You are editing HTML, but the output is a social video, not a web page. THE TEST IS THE NATIVE-EDITOR TEST: could you have made this element with the tools inside TikTok's own editor? That toolset is a font, a color, a stroke/outline, a soft shadow, a tight text box, alignment, opacity, rotation, animation presets — plus stickers, emoji, drawn marks and clips. It has NO padded capsule, NO border, NO gradient fill, NO blur panel, NO card. If you reached past it, cut it. Never author landing-page furniture: CTA "buttons" (a filled/gradient rounded capsule with action copy like "Sign Up for a Free Trial →"), benefit chip/badge rows ("✓ No Credit Card Needed"), bordered/shadowed/frosted cards holding a headline + URL, gradient text fills, feature grids, bulleted lists, or web-default fonts (Inter/Roboto/Arial/system-ui). AND NOT A SINGLE PILL EITHER: one lonely rounded, padded, filled capsule around a static stat or label — "10 hrs / week", "STEP 2", "EP.01", "+40%" — is a web badge, and being the only one on screen does not make it native. The ONLY legitimate capsule in a video is the active-word spotlight/karaoke caption highlight, because it moves with the spoken word. Emphasize a stat the way the editor would: bigger, heavier, ALL-CAPS, an accent color, a hand-drawn circle or underline, or its own beat on screen. Rule of thumb on anything holding words: border-radius over ~8px PLUS a background fill PLUS padding = a badge; drop the fill or drop the radius until the band hugs the glyphs. None of this appears in a real TikTok, and nothing in a video is clickable — say it as timed text on the footage instead. Arrows, scribble/underline marks, italics, ALL-CAPS, single-word color pops, emoji, transparent cut-out stickers, and mock social UI (iMessage bubbles, comment cards) are all fine. Captions use an imported family (Montserrat default / TikTok Sans / Abel / Source Code Pro / Yesteryear) at weight 700-900, ~36-64px on a 1080-wide frame, inside the 8%-85% safe zone, with exactly one of four backgrounds: outline, plain, an active-word spotlight/karaoke pill, or a tight-hugging solid band (radius <=8px, no border/shadow/gradient/blur).
-- STRUCTURE BEFORE POLISH — THE FOUR CHARGES, WRITTEN BEFORE YOU TOUCH THE TIMELINE. Most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) HOOK — write the opening line as text first: a complete clause (subject + verb), no jargon, naming a SITUATION ("I've quit six businesses") not a label ("anonymity"); it goes on screen at start:0, because caption chunk 1 is read before any audio and muted autoplay is the default. Banned openings: throat-clearing ("so I was thinking", "here's the thing"), a logo, a title card, a fade from black, context before the claim. (2) LOOP — one open question by 0:10, said ON SCREEN, closing INSIDE this video (state the timestamp it closes at; if you can't, there is no loop), and the withheld answer must be one the viewer CANNOT supply themselves — a formally-correct loop with a guessable answer passes every mechanical check and dies in the field. (3) PAYOFF — shown, not summarized, ≥5 uninterrupted seconds, landing BEFORE the final beat; the payoff is not the CTA. (4) BAIT — one ask in the final beat and in the post caption; never a DM funnel, "follow for part two", or ragebait. Then build the timeline. Re-theming a decomposed template: viral_dna already names the source's hook/retention/payoff — rebuild each charge for the new subject, never flatten the loop into a product statement. Full craft harness: the vidfarm skill's references/hooks-and-virality.md. Checkable form: \`vidfarm regime show hooks\`.
+- STRUCTURE BEFORE POLISH — THE FOUR CHARGES, WRITTEN BEFORE YOU TOUCH THE TIMELINE. Most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) HOOK — write the opening line as text first: a complete clause (subject + verb), no jargon, naming a SITUATION ("I've quit six businesses") not a label ("anonymity"); it goes on screen at start:0, because caption chunk 1 is read before any audio and muted autoplay is the default. Banned openings: throat-clearing ("so I was thinking", "here's the thing"), a logo, a title card, a fade from black, context before the claim. (2) LOOP — one open question by 0:10, said ON SCREEN, closing INSIDE this video (state the timestamp it closes at; if you can't, there is no loop), and the withheld answer must be one the viewer CANNOT supply themselves — a formally-correct loop with a guessable answer passes every mechanical check and dies in the field. (3) PAYOFF — shown, not summarized, ≥5 uninterrupted seconds, landing BEFORE the final beat; the payoff is not the CTA. (4) BAIT — one ask in the final beat and in the post caption; 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 harness show hooks\`.
 - THE FIRST FRAME IS THE THUMBNAIL. Frame 0 is one frame of ~30 in the first second, but every feed card, share link, and paused player freezes on it — more people see that frame than watch the video. It must never be black, empty, mid-fade, or mid-animation: a real visual at start:0 (\`vidfarm retime . --layer <key> --start 0\`), the hook words already on screen at t=0, and NO entrance transition on the FIRST clip (\`vidfarm transitions set . --layer <key> --in none\`; junction transitions between later clips are fine). Look at the actual pixels before you render: \`vidfarm stills . --at 0\`.
-- 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.
+- REVIEW THE WHOLE VIDEO AS ONE OBJECT — AND NEVER JUDGE IT BY ONE FRAME. Assume your own finished video has a defect you cannot see: across a 32-video batch, EVERY first-pass video had a real defect its own author had already reported as "verified, looks good". The cause is structural — you build scene by scene, each scene correct while it is the whole world, so every scene passes alone and the video fails as a SEQUENCE: margins shift between beats, headline sizes drift, the accent color wanders, one asset is flat vector and the next is photographic, every beat is the same length, a join lands like a slap. Nobody watches a scene; they watch the sequence. So before you call anything done, tile ~12 stills into ONE contact sheet and READ IT AS AN IMAGE — one command: \`vidfarm stills . --sheet\` (add \`--at 0,2,4,…\` to pick timestamps; writes stills/contact-sheet.png). Check: visual balance (no dead band under top-anchored content), consistent spacing/margins, ONE type scale, ONE accent color, ONE illustration style, deliberate pacing rather than N identical beats, nothing jarring at the joins, no frame where two elements compete for the eye — and the summary question, does it look like one person made it in one sitting? Fix drift by defining the SYSTEM (type scale, margin, palette, default beat) and applying it to every scene, not by patching the one scene that stood out. The defects that actually ship, in observed frequency order: large flat dead regions · a placeholder empty state that reads as a failed render · two contradictory numbers in one frame · a CTA still building at the last frame (settle it >=2s before the end) · two headlines superimposed at a scene handoff (exit at nextIn-0.18, duration 0.24, ease power2.out) · type colliding with a busy background exactly as it is spoken. If a frame looks empty, sample 0.2s apart to see whether it RESTS there — a transient wipe frame is fine, >0.5s is a hole. AND ALWAYS COMPARE TWO FRAMES FROM DIFFERENT SCENES: a frozen render (an overlay/watermark pass missing \`-loop 1\`, or assets outside the composition root so the timeline never runs) makes every frame identical while duration, frame count and audio hash all still pass, and frame 0 looks perfect. Verify audio by MEASUREMENT, never "it sounds fine" (you cannot hear it): ~12-15 dB speech-over-bed separation across the actual word spans, peak <0 dBFS. Never \`adelay\` the VO — whisper word timings and every caption built from them are relative to the raw vo.wav; use apad+atrim. Report what you MEASURED separately from what you JUDGED. Full method: the vidfarm skill's references/reviewing-renders.md.
+- THE HARNESS IS A FIRST-CLASS ARTIFACT — KNOW THE THREE PHRASINGS. A HARNESS.md is the reusable AI harness for ONE format or template: what makes it special, written down so an agent reproduces it without the director in the room. "Create me a harness" → \`vidfarm harness init short-form --out ./HARNESS.md\` (bases: short-form, hooks, ugc-testimonial, explainer, product-demo), then EDIT it with them. "Update the harness for this format" → open the file and write the new rule in WITH ITS REASON on the same line. "Give me the harness for this template_id" → they mean the DECOMPOSITION: \`vidfarm harness derive <forkId>\` distils this fork's viral/visual/structural/audio/build DNA into an editable HARNESS.md, keyed the same way the decompose JSON is (\`## Viral DNA\` → \`viral_dna\`, …); \`vidfarm harness show <ref> --dna visual\` prints one strand. \`vidfarm qa .\` picks up ./HARNESS.md automatically; \`--harness <name|path>\` adds more (they stack, and any file of theirs anywhere is valid). Its \`checks:\` are machine-settled; its \`- [ ]\` items come back for YOU to answer honestly in your report — never claim a pass on the half the CLI can't judge. ONE-TIME OR BULK? Ask before you build: if the director wants volume (daily posting, N variants, hook tests), that's SCRIPTING MODE — pin this fork as the base, vary exactly ONE thing per variant, and install a harness, because nobody watches variant #37 as carefully as #1. When a batch teaches you something, write it back into the harness — the compositions are disposable, the harness compounds. (Formerly QA_REGIME.md; \`vidfarm regime …\` still works as an alias. NOTE: the \`.harness/\` directory beside this file is machine-generated context regenerated on every pull — never hand-edit it. HARNESS.md is the one you own.)
 - DEDUPLICATE BEFORE YOU PUBLISH — AND ASK FIRST. Social platforms fingerprint every upload, so the same render posted twice (a second account, another platform, a re-post next month) gets the later copy suppressed as duplicate/reused content. BEFORE you render for publication, and before any bulk run, ASK the director: "do you want deduplicated copies for posting, and how many?" Ask THEN, not after — dedupe is a post-render ffmpeg pass, so the correct order is RENDER ONCE → DEDUPE N, and deciding late means paying for a second render. Run it on the EXPORTED file: \`vidfarm dedupe ./final.mp4\` (one copy) or \`vidfarm dedupe ./final.mp4 --variants N --seed <slug> --out-dir ./posts\` (N copies, one per account/slot). Free, offline, no wallet — it never re-renders the composition. The default \`standard\` preset is skew 2%, zoom 3%, rotate 2°, speed +2%, saturation +4%, plus contrast/brightness/hue/grain, a container-metadata strip and a per-variant CRF walk; invisible to a viewer, and each variant differs from the original AND from its siblings. Post each variant to a DIFFERENT account — two accounts posting the same variant defeats the point. A rotate forces a bigger centre-crop to hide the black corners (~6.7% on a tall frame at 2°) and the CLI says so; pass \`--rotate 0\` when framing matters more. Cloud twin: \`POST /api/v1/primitives/media/dedupe\`.
 - QA EVERY VIDEO BEFORE YOU RENDER: run \`vidfarm qa .\` in this directory. It's free, instant, and local — a blocklist for the slop above plus the first frame, the font regime, and the safe zone, with a concrete fix per finding. It's feedback, not a gate (exits 0 even on findings, never runs automatically) and a blocklist, not an allowlist, so stylized or hand-made work passes untouched. Fix what's real, ignore what's a deliberate style call. \`--json\` for scripted batches.
 
@@ -6577,10 +6627,6 @@ async function runTtsCommand(argv) {
         throw new Error("tts --engine must be local (keyless Kokoro), byok (your provider key — default), or cloud.");
     }
     const wantCloud = Boolean(parsed.values.cloud) || engine === "cloud";
-    if (engine === "local") {
-        await runLocalKokoroTts({ text, voice, style, out: parsed.values.out, format: explicitFormat, json });
-        return;
-    }
     // COST-MODE DEFAULT: in minimize/hybrid, narration starts on the FREE local
     // Kokoro engine unless the run asked for a premium/cloud voice (see
     // wantsPremiumVoice). The BYOK key path is a real fallback, not a downgrade —
@@ -6588,6 +6634,18 @@ async function runTtsCommand(argv) {
     // below rather than failing the run.
     const costMode = resolveCostMode(parsed.values);
     const premium = wantsPremiumVoice(parsed.values, voice, style);
+    // Offer the human the choice of voice BEFORE any engine runs — the notice is
+    // identical whichever tier this run lands on, so it sits above the dispatch.
+    printVoiceCheckpoint({
+        interaction: resolveInteractionMode(parsed.values),
+        costMode: costMode.mode,
+        voiceChosen: Boolean(voice?.trim()),
+        tier: engine === "local" || (!engine && !wantCloud && costMode.mode !== "rich-ai" && costMode.mode !== "pure-videogen" && !premium) ? "free" : "premium"
+    });
+    if (engine === "local") {
+        await runLocalKokoroTts({ text, voice, style, out: parsed.values.out, format: explicitFormat, json });
+        return;
+    }
     /** Set when the cost-mode default ran Kokoro and it failed — so the keyless
      *  path below doesn't pointlessly retry the same engine. */
     let kokoroError = null;
@@ -6685,7 +6743,7 @@ async function runTtsCommand(argv) {
     if (parsed.values["own-key"])
         payload.use_wallet_credits = false;
     if (!ctx.json && !parsed.values["own-key"]) {
-        console.log(`${DIM}Using ElevenLabs on the platform key (wallet-billed). Browse voices: vidfarm voices — then pass --voice <voice_id>. Add --own-key to use your own key.${RESET}`);
+        console.log(`${DIM}Premium ElevenLabs narration through VIDFARM'S OWN ElevenLabs connection — no ElevenLabs account or API key needed on your side; it's billed as vidfarm wallet credits. Hear the catalog first: vidfarm voices --sample, then pass --voice <voice_id>. Already have an ElevenLabs key? add --own-key.${RESET}`);
     }
     const tracer = parsed.values.tracer ?? `devcli-tts-${Date.now().toString(36)}`;
     const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/audio/speech", auth: ctx.auth, body: { tracer, payload } });
@@ -6722,6 +6780,38 @@ async function runTtsCommand(argv) {
         console.log(`${GREEN}Wrote ${outPath}${RESET} ${DIM}(${mediaUrl})${RESET}`);
     }
 }
+/**
+ * The VOICE CHECKPOINT. Who a video sounds like is a taste decision, and the
+ * default voice is the one choice an agent makes silently that a human would
+ * almost always want a say in. So when narration is about to run with NO voice
+ * named, say so — loudly enough that the agent stops and offers samples.
+ *
+ * Interactive mode → always offer (sampling is FREE on both rosters, so this
+ * holds in `minimize` exactly as much as in `hybrid`; only the roster the offer
+ * leads with changes). Autonomous with a mode actually set → stay silent and
+ * let the pipeline run. Mode never set → offer, because "nobody asked" is not
+ * the same as "the user opted out of choosing".
+ *
+ * stderr, never stdout, so `--json` output stays parseable.
+ */
+function printVoiceCheckpoint(input) {
+    if (input.voiceChosen)
+        return;
+    if (input.interaction.mode !== "interactive" && input.interaction.isSet)
+        return;
+    const lead = input.interaction.mode === "interactive"
+        ? "[voice] Interactive mode and no voice picked yet"
+        : "[voice] No interaction preference set and no voice picked yet";
+    const free = "vidfarm voices --free --sample (renders $0 local Kokoro samples)";
+    const premium = "vidfarm voices --sample (premium ElevenLabs voices through VIDFARM'S OWN ElevenLabs connection — " +
+        "no ElevenLabs account or API key needed, narration billed as wallet credits, pennies each)";
+    const order = input.tier === "free"
+        ? `Sample the free voices first: ${free}. Same command reaches the premium tier: ${premium}.`
+        : `Sample them: ${premium}. Or stay at $0: ${free}.`;
+    console.error(`${lead} — ASK THE USER whether they want to hear a few samples and choose. ${order} ` +
+        "Sampling costs nothing on either tier (preview clips + local renders), so it's safe even in cost mode minimize. " +
+        "Then narrate with --voice <id>.");
+}
 /** Kokoro voice ids look like af_heart / am_adam / bf_emma. Anything else is a
  *  cloud provider preset (openai "alloy", gemini "Kore", an ElevenLabs id).
  *  Declared as a hoisted function, not a const: `wantsPremiumVoice` runs during
@@ -6770,7 +6860,7 @@ async function runLocalKokoroTts(input) {
     if (!input.json) {
         console.log(`${DIM}Generating speech with the local Kokoro-82M engine (free, no account)…${RESET}`);
         if (input.costModeDefault) {
-            console.log(`${DIM}(cost mode ${costModeDisplayName(input.costModeDefault)} → free local voice by default. Want a premium voice? add --style/--voice/--provider, or --cloud.)${RESET}`);
+            console.log(`${DIM}(cost mode ${costModeDisplayName(input.costModeDefault)} → free local voice by default. Pick a different free voice: vidfarm voices --free --sample. Want a PREMIUM voice? vidfarm carries the ElevenLabs catalog on its own connection — no ElevenLabs account needed, just wallet credits: vidfarm voices --sample, then --cloud --voice <voice_id>.)${RESET}`);
         }
     }
     const run = await runHyperframesCommand("tts", [input.text, "-o", wavPath, ...(voice ? ["-v", voice] : [])], { stdio: input.json ? "capture" : "inherit" });
@@ -6956,8 +7046,53 @@ async function runMusicCommand(argv) {
         console.log(`${DIM}Place it as its own <audio> layer under narration (~0.1–0.2 volume).${RESET}`);
     }
 }
-// List ElevenLabs voices for TTS. --own-key lists the voices on your own saved
-// ElevenLabs key; default lists the platform account's voices.
+/** The sentence spoken when sampling FREE voices (premium samples reuse
+ *  ElevenLabs' own preview clips, so they need no text). A hoisted function,
+ *  not a const: cli.ts runs `await main()` at top level ABOVE this point, so a
+ *  const declared here hits the TDZ when a command reads it. */
+function voiceSampleText() {
+    return "Here's how I sound. Pick the voice that fits your video.";
+}
+/** Pull the human-meaningful line out of a hyperframes engine failure. Its CLI
+ *  paints spinners and cursor codes, so the LAST line is usually an escape
+ *  sequence — prefer a line that actually reads like an error. */
+function engineFailureLine(output, fallback) {
+    const clean = output
+        // ESC-anchored so it strips real ANSI, never a literal "[mode]" in a message.
+        .replace(/\u001b\[[0-9;?]*[a-zA-Z]/g, "")
+        .split("\n")
+        .map((line) => line.replace(/^[\s│◇◆○●✖✗ו]+/, "").trim())
+        .filter((line) => line.length > 2);
+    return (clean.find((line) => /fail|error|not installed|cannot|unable|missing/i.test(line)) ?? clean.pop() ?? fallback).slice(0, 240);
+}
+/** The free local Kokoro roster, straight from the bundled engine (never a
+ *  hardcoded list — the engine owns which ids actually load). */
+async function listFreeVoices() {
+    const run = await runHyperframesCommand("tts", ["--list", "--json"], { stdio: "capture" });
+    if (run.code !== 0)
+        return [];
+    try {
+        const parsed = JSON.parse(run.stdout.slice(run.stdout.indexOf("[")));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+// Browse the voices available for narration, and SAMPLE them so a human can
+// actually choose one by ear. Two rosters, because they cost different money:
+//
+//   premium (default) — the ElevenLabs catalog reached through VIDFARM'S OWN
+//     ElevenLabs connection. No ElevenLabs account, no API key, no separate
+//     subscription: narration runs on the platform key and is billed as
+//     Vidfarm wallet credits. `--own-key` swaps in the customer's own saved
+//     ElevenLabs key instead (their account, their voices, no wallet spend).
+//   free (--free) — the keyless local Kokoro-82M presets, $0 forever, the
+//     default engine in cost mode minimize/hybrid.
+//
+// SAMPLING IS ALWAYS FREE on both rosters: premium samples are ElevenLabs'
+// static preview clips (a CDN download, not a synthesis call) and free samples
+// are generated on the local engine. So `--sample` is safe in `minimize`.
 async function runVoicesCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -6965,28 +7100,135 @@ async function runVoicesCommand(argv) {
         options: {
             ...commonOptions(),
             "own-key": { type: "boolean", default: false },
+            free: { type: "boolean", default: false },
+            all: { type: "boolean", default: false },
+            search: { type: "string" },
+            sample: { type: "boolean", default: false },
+            "sample-count": { type: "string" },
+            "sample-out": { type: "string" },
+            "sample-text": { type: "string" },
             limit: { type: "string" }
         }
     });
     const ctx = commonContext(parsed.values);
-    const query = parsed.values["own-key"] ? "?use_wallet_credits=false" : "";
-    const res = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/primitives/audio/voices${query}`, auth: ctx.auth });
-    assertApiOk(res, "voices");
-    const body = (res.json ?? {});
-    const voices = Array.isArray(body.voices) ? body.voices : [];
+    const wantFree = Boolean(parsed.values.free) || Boolean(parsed.values.all);
+    const wantPremium = !parsed.values.free || Boolean(parsed.values.all);
+    const search = parsed.values.search?.trim().toLowerCase() || null;
+    const sample = Boolean(parsed.values.sample);
+    const sampleCount = Math.max(1, Number(parsed.values["sample-count"] ?? "6") || 6);
+    const sampleText = parsed.values["sample-text"]?.trim() || voiceSampleText();
+    const sampleDir = path.resolve(process.cwd(), parsed.values["sample-out"] ?? "voice-samples");
+    const limit = Number(parsed.values.limit ?? "40") || 40;
+    const matches = (haystack) => !search || haystack.toLowerCase().includes(search);
+    const premium = [];
+    let scope = "platform";
+    let libraryUrl = "https://elevenlabs.io/app/voice-library";
+    if (wantPremium) {
+        const query = parsed.values["own-key"] ? "?use_wallet_credits=false" : "";
+        const res = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/primitives/audio/voices${query}`, auth: ctx.auth });
+        assertApiOk(res, "voices");
+        const body = (res.json ?? {});
+        scope = String(body.scope ?? "platform");
+        libraryUrl = String(body.voice_library_url ?? libraryUrl);
+        for (const voice of Array.isArray(body.voices) ? body.voices : []) {
+            const labels = voice.labels && typeof voice.labels === "object" ? Object.values(voice.labels).join(", ") : "";
+            if (matches(`${voice.name ?? ""} ${labels} ${voice.description ?? ""} ${voice.category ?? ""}`)) {
+                premium.push({ ...voice, label_text: labels });
+            }
+        }
+    }
+    const free = wantFree ? (await listFreeVoices()).filter((v) => matches(`${v.id} ${v.label} ${v.language} ${v.gender}`)) : [];
+    // Sampling: write listenable audio to disk so the human can play it and pick.
+    const samples = [];
+    /** Why a sample didn't land. Never swallowed: a browse that quietly produced
+     *  no audio reads as "there was nothing to hear". */
+    const sampleErrors = [];
+    if (sample) {
+        mkdirSync(sampleDir, { recursive: true });
+        for (const voice of premium.filter((v) => v.preview_url).slice(0, sampleCount)) {
+            const out = path.join(sampleDir, `premium-${String(voice.name ?? voice.voice_id).replace(/[^a-z0-9]+/gi, "-").toLowerCase()}-${voice.voice_id}.mp3`);
+            try {
+                await downloadUrlToFile(String(voice.preview_url), out);
+                samples.push({ voice_id: String(voice.voice_id), name: String(voice.name ?? ""), tier: "premium", out });
+            }
+            catch (error) {
+                // A dead preview URL must not sink the whole browse.
+                sampleErrors.push({ voice_id: String(voice.voice_id), tier: "premium", error: String(error?.message ?? error).slice(0, 200) });
+            }
+        }
+        for (const voice of free.slice(0, sampleCount)) {
+            const out = path.join(sampleDir, `free-${voice.id}.wav`);
+            const run = await runHyperframesCommand("tts", [sampleText, "-o", out, "-v", voice.id], { stdio: "capture" });
+            if (run.code === 0 && existsSync(out)) {
+                samples.push({ voice_id: voice.id, name: voice.label, tier: "free", out });
+            }
+            else {
+                sampleErrors.push({ voice_id: voice.id, tier: "free", error: engineFailureLine(`${run.stderr}\n${run.stdout}`, `exit ${run.code}`) });
+            }
+        }
+    }
     if (ctx.json) {
-        printJson(body);
+        printJson({
+            ok: true,
+            scope,
+            billing: parsed.values["own-key"] ? "your own ElevenLabs key" : "vidfarm platform ElevenLabs connection (wallet credits)",
+            voice_library_url: libraryUrl,
+            premium_voices: premium,
+            free_voices: free,
+            samples,
+            sample_errors: sampleErrors,
+            sample_dir: sample ? sampleDir : null
+        });
         return;
     }
-    console.log(`${DIM}${voices.length} ElevenLabs voices (${body.scope ?? "platform"} account). Browse more: ${body.voice_library_url ?? "https://elevenlabs.io/app/voice-library"}${RESET}`);
-    const limit = Number(parsed.values.limit ?? "40") || 40;
-    for (const voice of voices.slice(0, limit)) {
-        const labels = voice.labels && typeof voice.labels === "object" ? Object.values(voice.labels).join(", ") : "";
-        console.log(`${GREEN}${voice.voice_id}${RESET}  ${voice.name}${labels ? ` ${DIM}(${labels})${RESET}` : ""}`);
+    if (wantPremium) {
+        console.log(scope === "user"
+            ? `${GREEN}${premium.length} premium ElevenLabs voices${RESET} ${DIM}(YOUR OWN ElevenLabs key — billed to your ElevenLabs account, no wallet spend).${RESET}`
+            : `${GREEN}${premium.length} premium ElevenLabs voices${RESET} ${DIM}— available right here through VIDFARM'S OWN ElevenLabs connection. You do NOT need an ElevenLabs account, API key, or subscription: narration on these voices runs on the platform key and is billed as vidfarm wallet credits (pennies per narration). Already have an ElevenLabs key? add --own-key.${RESET}`);
+        for (const voice of premium.slice(0, limit)) {
+            console.log(`${GREEN}${voice.voice_id}${RESET}  ${voice.name}${voice.label_text ? ` ${DIM}(${voice.label_text})${RESET}` : ""}`);
+            if (voice.preview_url)
+                console.log(`   ${DIM}preview: ${voice.preview_url}${RESET}`);
+        }
+        if (premium.length > limit)
+            console.log(`${DIM}… ${premium.length - limit} more (raise with --limit, narrow with --search "british narrator", or use --json).${RESET}`);
+        console.log(`${DIM}Browse thousands more at ${libraryUrl}.${RESET}`);
+    }
+    if (wantFree) {
+        console.log(`\n${GREEN}${free.length} free local voices${RESET} ${DIM}(Kokoro-82M, keyless, $0 forever — the default engine in cost mode minimize/hybrid).${RESET}`);
+        for (const voice of free.slice(0, limit)) {
+            console.log(`${GREEN}${voice.id}${RESET}  ${voice.label} ${DIM}(${voice.language}, ${voice.gender})${RESET}`);
+        }
+    }
+    if (!wantFree && wantPremium) {
+        console.log(`${DIM}Prefer to spend nothing? vidfarm voices --free lists the $0 local voices (--all lists both).${RESET}`);
     }
-    if (voices.length > limit)
-        console.log(`${DIM}… ${voices.length - limit} more (raise with --limit or use --json).${RESET}`);
-    console.log(`${DIM}Use one: vidfarm tts "Hello" --cloud --voice <voice_id>${RESET}`);
+    if (samples.length) {
+        console.log(`\n${GREEN}Wrote ${samples.length} samples to ${sampleDir}${RESET} ${DIM}(free — premium samples are ElevenLabs' own preview clips, free samples are rendered locally; no credits spent).${RESET}`);
+        for (const s of samples)
+            console.log(`   ${DIM}${s.tier === "free" ? "free " : "prem "}${s.voice_id} — ${s.name} → ${s.out}${RESET}`);
+        console.log(`${DIM}PLAY THESE FOR THE USER and let them pick, then narrate with the id they choose.${RESET}`);
+    }
+    if (sampleErrors.length) {
+        const freeFailed = sampleErrors.filter((e) => e.tier === "free");
+        console.log(`${RED}${sampleErrors.length} sample(s) could not be produced.${RESET} ${DIM}${sampleErrors[0].error}${RESET}`);
+        if (freeFailed.length) {
+            console.log(`${DIM}Free samples render on the local Kokoro engine — install it once (\`pip install kokoro-onnx soundfile\`, or point HYPERFRAMES_PYTHON at a venv that has them). The PREMIUM voices need nothing installed: vidfarm voices --sample streams ElevenLabs' own preview clips over vidfarm's connection.${RESET}`);
+        }
+    }
+    if (!sample) {
+        console.log(`${DIM}Hear them before choosing: vidfarm voices --sample${parsed.values.free ? " --free" : ""} — downloads/renders ${sampleCount} samples to ./voice-samples (free, no credits).${RESET}`);
+    }
+    // Interaction mode decides whose ear picks the voice. In interactive mode the
+    // human should hear samples and choose; when the mode was never set, say so
+    // rather than silently picking a default voice on their behalf.
+    if (ctx.interaction.mode === "interactive") {
+        console.log(`${DIM}[mode] Interactive — don't pick for them: sample a few, share the files, and let the user choose the voice.${RESET}`);
+    }
+    else if (!ctx.interaction.isSet) {
+        console.log(`${DIM}[mode] No interaction preference set — ask whether the user wants to hear samples and pick the voice themselves (\`vidfarm mode interactive\`), or wants you to choose one.${RESET}`);
+    }
+    console.log(`${DIM}Use one: vidfarm tts "Hello" --cloud --voice <voice_id>   (free voice: vidfarm tts "Hello" --engine local --voice <kokoro_id>)${RESET}`);
 }
 async function runMediaCommand(argv) {
     const MEDIA_TYPES = ["image", "vector", "icon", "video", "bgm", "sfx"];
@@ -10130,31 +10372,52 @@ async function runQaCommand(argv) {
         options: {
             json: { type: "boolean", default: false },
             strict: { type: "boolean", default: false },
+            harness: { type: "string", multiple: true },
+            "no-harness": { type: "boolean", default: false },
+            // Pre-rename aliases; `harness` is the name everywhere else now.
             regime: { type: "string", multiple: true },
             "no-regime": { type: "boolean", default: false }
         }
     });
     const target = parsed.positionals[0];
     if (!target)
-        throw new Error("qa requires a composition path: `vidfarm qa <dir-or-composition.html> [--regime <name|path>] [--json] [--strict]`.");
+        throw new Error("qa requires a composition path: `vidfarm qa <dir-or-composition.html> [--harness <name|path>] [--json] [--strict]`.");
     const htmlPath = resolveCompositionHtmlPath(target);
     const html = readFileSync(htmlPath, "utf8");
     let report = qaCompositionHtml(html);
-    // Regime resolution, in precedence order: explicit --regime flags (stackable)
-    // → VIDFARM_QA_REGIME (a default for a whole scripting run) → the working
-    // directory's own QA_REGIME.md. --no-regime opts out of the implicit paths.
-    const explicit = parsed.values.regime ?? [];
-    const fromEnv = (process.env.VIDFARM_QA_REGIME ?? "").split(",").map((entry) => entry.trim()).filter(Boolean);
-    let regimeRefs = explicit.length ? explicit : fromEnv;
-    if (!regimeRefs.length && !parsed.values["no-regime"]) {
-        const discovered = discoverRegime(path.dirname(htmlPath));
-        if (discovered)
-            regimeRefs = [discovered];
-    }
-    if (regimeRefs.length) {
-        const facts = extractCompositionFacts(html);
-        report = mergeRegimeIntoReport(report, regimeRefs.map((ref) => loadAndEvaluateRegime(ref, facts)));
+    // Harness resolution, in precedence order: explicit --harness flags
+    // (stackable) → VIDFARM_HARNESS (a default for a whole scripting run) → the
+    // working directory's own HARNESS.md. --no-harness opts out of the implicit
+    // paths. The `regime`-spelled forms are the pre-rename aliases.
+    const explicit = [
+        ...(parsed.values.harness ?? []),
+        ...(parsed.values.regime ?? [])
+    ];
+    const envValue = process.env.VIDFARM_HARNESS ?? process.env.VIDFARM_QA_REGIME ?? "";
+    const fromEnv = envValue.split(",").map((entry) => entry.trim()).filter(Boolean);
+    let harnessRefs = explicit.length ? explicit : fromEnv;
+    const optedOut = Boolean(parsed.values["no-harness"]) || Boolean(parsed.values["no-regime"]);
+    if (!harnessRefs.length && !optedOut) {
+        const discovered = discoverHarness(path.dirname(htmlPath));
+        if (discovered) {
+            harnessRefs = [discovered];
+            if (isLegacyHarnessFilename(discovered)) {
+                console.log(`${DIM}Using ${path.basename(discovered)} — the file is now called ${HARNESS_FILENAME}. Rename it when convenient; both are read.${RESET}`);
+            }
+        }
     }
+    if (harnessRefs.length) {
+        const facts = extractCompositionFacts(html);
+        report = mergeHarnessIntoReport(report, harnessRefs.map((ref) => loadAndEvaluateHarness(ref, facts)));
+    }
+    // The directive is on the report already; re-issue it with THIS work dir (and
+    // an existing render, if there is one) substituted into the commands.
+    const workDir = path.dirname(htmlPath);
+    const render = newestRenderIn(workDir);
+    report = {
+        ...report,
+        watch_the_video: watchTheVideoDirective(pastablePath(workDir), render ? pastablePath(render) : null)
+    };
     if (parsed.values.json) {
         printJson(report);
         if (!report.ok && parsed.values.strict)
@@ -10164,13 +10427,13 @@ async function runQaCommand(argv) {
     const body = formatQaReport(report, { red: RED, yellow: YELLOW, green: GREEN, dim: DIM, reset: RESET });
     if (body)
         console.log(body);
-    for (const evaluation of report.regimes ?? []) {
-        console.log(formatRegimeReport(evaluation, { green: GREEN, red: RED, yellow: YELLOW, dim: DIM, reset: RESET }));
+    for (const evaluation of report.harnesses ?? []) {
+        console.log(formatHarnessReport(evaluation, { green: GREEN, red: RED, yellow: YELLOW, dim: DIM, reset: RESET }));
     }
     const scope = `${report.checked.layers} layer(s), ${report.checked.text_layers} text layer(s)${report.checked.canvas ? `, ${report.checked.canvas}` : ""}`;
-    const graded = (report.regimes ?? []).length > 0;
+    const graded = (report.harnesses ?? []).length > 0;
     if (report.verdict === "clean") {
-        console.log(`${GREEN}✓ no HTML slop found${graded ? ", regime checks passed" : ""}${RESET} ${DIM}— ${scope} — ${htmlPath}${RESET}`);
+        console.log(`${GREEN}✓ no HTML slop found${graded ? ", harness checks passed" : ""}${RESET} ${DIM}— ${scope} — ${htmlPath}${RESET}`);
     }
     else if (report.verdict === "warnings") {
         console.log(`${YELLOW}! ${report.warnings.length} warning(s), no slop${RESET} ${DIM}— ${scope} — ${htmlPath}${RESET}`);
@@ -10179,81 +10442,376 @@ async function runQaCommand(argv) {
         console.log(`${RED}✗ ${report.errors.length} ${graded ? "issue(s)" : "slop issue(s)"}${RESET}, ${report.warnings.length} warning(s) ${DIM}— ${scope} — ${htmlPath}${RESET}`);
         console.log(`${DIM}This is feedback, not a gate — fix what's real and re-run. A deliberate stylistic choice that trips a rule is fine to ignore.${RESET}`);
     }
-    const pendingReview = (report.regimes ?? []).reduce((total, evaluation) => total + evaluation.review_items.length, 0);
+    const pendingReview = (report.harnesses ?? []).reduce((total, evaluation) => total + evaluation.review_items.length, 0);
     if (pendingReview) {
-        console.log(`${DIM}${pendingReview} regime item(s) above are NOT machine-checkable — answer them yourself before you call this video done.${RESET}`);
+        console.log(`${DIM}${pendingReview} harness item(s) above are NOT machine-checkable — answer them yourself before you call this video done.${RESET}`);
     }
     else if (!graded) {
         // Everything above is mechanical. Structure — hook, loop, payoff, bait — is
         // what actually decides whether the video travels, and nothing here checks
         // it. Say so rather than letting a green tick imply the video is good.
         console.log(`${DIM}Checked mechanics only — nothing here grades the hook, the loop, the payoff, or the bait.${RESET}`);
-        console.log(`${DIM}Structure: vidfarm regime show hooks   ·   grade this video: vidfarm qa <dir> --regime short-form${RESET}`);
+        console.log(`${DIM}Structure: vidfarm harness show hooks   ·   grade this video: vidfarm qa <dir> --harness short-form${RESET}`);
     }
+    // Last word on every run, clean ones included: this tool never saw the video.
+    console.log(formatWatchTheVideoNotice(report.watch_the_video, { yellow: YELLOW, dim: DIM, reset: RESET, bold: BOLD }));
     if (!report.ok && parsed.values.strict)
         process.exitCode = 1;
 }
-// `vidfarm regime <list|show|init>` — the QA_REGIME.md surface. A regime is the
-// director's OWN quality contract for one template style; the built-ins are
-// starting points to copy and edit, never a house style to conform to.
-async function runRegimeCommand(argv) {
+/** Shortest form of a path the caller can paste back: relative when it's under cwd. */
+function pastablePath(target) {
+    const rel = path.relative(process.cwd(), target);
+    if (!rel)
+        return ".";
+    return rel.startsWith("..") ? target : `./${rel}`;
+}
+/** Newest rendered MP4 in `<dir>/renders`, if the director has rendered yet. */
+function newestRenderIn(dir) {
+    const rendersDir = path.join(dir, "renders");
+    try {
+        const candidates = readdirSync(rendersDir)
+            .filter((entry) => entry.toLowerCase().endsWith(".mp4"))
+            .map((entry) => {
+            const full = path.join(rendersDir, entry);
+            return { full, mtime: statSync(full).mtimeMs };
+        })
+            .sort((a, b) => b.mtime - a.mtime);
+        return candidates.length ? candidates[0].full : null;
+    }
+    catch {
+        return null;
+    }
+}
+// `vidfarm harness <list|show|init|derive|check>` — the HARNESS.md surface.
+//
+// A harness is the reusable apparatus for ONE format or template: what makes it
+// special, written down so an agent can reproduce it without the director in
+// the room. Three director phrasings all land here:
+//
+//   "create me a harness"                        → init  (copy a base, then EDIT)
+//   "update the harness for this format"         → edit the file in place; the
+//                                                  CLI just reads and grades it
+//   "give me the harness for this template_id"   → derive (the DECOMPOSITION,
+//                                                  distilled into a harness)
+//
+// The built-ins are starting points to copy and edit, never a house style to
+// conform to.
+async function runHarnessCommand(argv) {
     const sub = argv[0];
     const parsed = parseArgs({
         args: argv.slice(1),
         allowPositionals: true,
         options: {
-            json: { type: "boolean", default: false },
+            // `derive` talks to the API to fetch a fork's decompose output, so this
+            // command carries the standard auth/host flags alongside its own.
+            ...commonOptions(),
             out: { type: "string" },
             dir: { type: "string" },
+            dna: { type: "string" },
+            refetch: { type: "boolean", default: false },
             force: { type: "boolean", default: false }
         }
     });
     const json = Boolean(parsed.values.json);
     if (!sub || sub === "list") {
-        const builtins = listBuiltinRegimes();
+        const builtins = listBuiltinHarnesses();
         if (json)
-            return printJson({ regimes: builtins.map(({ name, path: file, video_type }) => ({ name, path: file, video_type })) });
-        console.log(`${DIM}Built-in QA regimes — copy one next to your work, then edit it:${RESET}`);
+            return printJson({ harnesses: builtins.map(({ name, path: file, video_type }) => ({ name, path: file, video_type })) });
+        console.log(`${DIM}Built-in harnesses — copy one next to your work, then edit it:${RESET}`);
         for (const entry of builtins) {
             console.log(`  ${GREEN}${entry.name}${RESET} ${DIM}${entry.video_type ?? ""}${RESET}`);
         }
-        console.log(`\n${DIM}vidfarm regime init <name> --out ./work/QA_REGIME.md${RESET}`);
-        console.log(`${DIM}vidfarm qa ./work --regime <name|path>   (repeatable — regimes stack)${RESET}`);
-        console.log(`${DIM}A regime is YOURS: any QA_REGIME.md anywhere on disk can be passed in. Format: .agents/skills/vidfarm/regimes/README.md${RESET}`);
+        console.log(`\n${DIM}vidfarm harness init <name> --out ./work/${HARNESS_FILENAME}${RESET}`);
+        console.log(`${DIM}vidfarm harness derive <forkId>          (a decomposed template → a harness)${RESET}`);
+        console.log(`${DIM}vidfarm qa ./work --harness <name|path>  (repeatable — harnesses stack)${RESET}`);
+        console.log(`${DIM}A harness is YOURS: any ${HARNESS_FILENAME} anywhere on disk can be passed in. Format: .agents/skills/vidfarm/harnesses/README.md${RESET}`);
         return;
     }
     if (sub === "show") {
         const ref = parsed.positionals[0];
         if (!ref)
-            throw new Error("regime show requires a name or path: `vidfarm regime show <name|path>`.");
-        const file = resolveRegimePath(ref);
+            throw new Error("harness show requires a name or path: `vidfarm harness show <name|path>`.");
+        const file = resolveHarnessPath(ref);
         const raw = readFileSync(file, "utf8");
+        const doc = parseHarness(raw, file);
+        // `--dna visual` prints ONE strand. A harness that documents five kinds of
+        // DNA is long; an agent re-theming the look only needs the visual strand.
+        const wanted = parsed.values.dna ? String(parsed.values.dna).toLowerCase().replace(/[^a-z0-9]+/g, "_") : null;
+        if (wanted) {
+            const strand = doc.dna.find((entry) => entry.key === wanted || entry.key === `${wanted}_dna` || entry.key.startsWith(wanted));
+            if (!strand) {
+                throw new Error(`"${doc.name}" documents no ${wanted} strand. It has: ${doc.dna.map((entry) => entry.key).join(", ") || "(no DNA sections)"}.`);
+            }
+            if (json)
+                return printJson(strand);
+            console.log(`## ${strand.heading}\n\n${strand.body}`);
+            return;
+        }
         if (json)
-            return printJson(parseRegime(raw, file));
+            return printJson(doc);
         console.log(raw);
         return;
     }
-    if (sub === "init") {
-        const ref = parsed.positionals[0];
-        if (!ref)
-            throw new Error("regime init requires a built-in name or source path: `vidfarm regime init short-form --out ./work/QA_REGIME.md`.");
-        const source = resolveRegimePath(ref);
+    if (sub === "init" || sub === "new" || sub === "create") {
+        const ref = parsed.positionals[0] ?? "short-form";
+        const source = resolveHarnessPath(ref);
         const outPath = parsed.values.out
             ? path.resolve(String(parsed.values.out))
-            : path.resolve(String(parsed.values.dir ?? "."), "QA_REGIME.md");
+            : path.resolve(String(parsed.values.dir ?? "."), HARNESS_FILENAME);
         if (existsSync(outPath) && !parsed.values.force) {
             throw new Error(`${outPath} already exists. Pass --force to overwrite (you will lose your edits).`);
         }
         mkdirSync(path.dirname(outPath), { recursive: true });
         writeFileSync(outPath, readFileSync(source, "utf8"), "utf8");
         if (json)
-            return printJson({ ok: true, regime: ref, source, path: outPath });
+            return printJson({ ok: true, harness: ref, source, path: outPath });
         console.log(`${GREEN}${outPath}${RESET} ${DIM}← ${path.basename(source)}${RESET}`);
         console.log(`${DIM}Now EDIT it — delete what doesn't apply, add what makes your format yours (start with the audience line).${RESET}`);
         console.log(`${DIM}Then: vidfarm qa ${path.dirname(outPath)}${RESET}`);
         return;
     }
-    throw new Error(`Unknown regime subcommand "${sub}". Use: list | show <name|path> | init <name> [--out <path>]`);
+    if (sub === "derive" || sub === "from" || sub === "decompose") {
+        const ref = parsed.positionals[0];
+        if (!ref) {
+            throw new Error("harness derive requires a fork/template id or a pulled work dir: `vidfarm harness derive <forkId|dir> [--out ./work/HARNESS.md]`.");
+        }
+        await runHarnessDerive(ref, {
+            outPath: parsed.values.out ? path.resolve(String(parsed.values.out)) : null,
+            dirOverride: parsed.values.dir ? path.resolve(String(parsed.values.dir)) : null,
+            refetch: Boolean(parsed.values.refetch),
+            force: Boolean(parsed.values.force),
+            values: parsed.values,
+            json
+        });
+        return;
+    }
+    if (sub === "check" || sub === "qa" || sub === "grade") {
+        // The same engine as `vidfarm qa`, reachable under the noun the director
+        // used. One implementation, two doors.
+        const rest = argv.slice(1);
+        await runQaCommand(rest.length ? rest : ["."]);
+        return;
+    }
+    throw new Error(`Unknown harness subcommand "${sub}". Use: list | show <name|path> [--dna <strand>] | init <name> [--out <path>] | derive <forkId|dir> | check <dir>`);
+}
+/**
+ * `vidfarm harness derive <forkId|dir>` — THE DECOMPOSITION, as a harness.
+ *
+ * When a director says "give me the harness for this template_id", this is what
+ * they mean: the decompose pass already extracted the template's DNA into JSON
+ * (video-context viral_dna, editor-harness, replication-harness,
+ * scene-annotations), and this folds those strands into ONE editable Markdown
+ * doc laid out the way every other harness is — so a derived harness and a
+ * hand-written one are the same artifact, gradeable by the same `vidfarm qa`.
+ *
+ * It writes the DNA it FOUND and says "unknown" where the decompose pass has
+ * nothing, rather than inventing a plausible strand. A harness that quietly
+ * fabricates the thing the director asked for is worse than a short one.
+ */
+async function runHarnessDerive(ref, opts) {
+    const asDir = path.resolve(ref);
+    const isLocalDir = existsSync(asDir) && statSync(asDir).isDirectory();
+    let dir = opts.dirOverride ?? (isLocalDir ? asDir : null);
+    let forkId = isLocalDir ? null : ref;
+    if (!dir) {
+        // A bare id: pull the decompose artifacts down the same way `vidfarm pull`
+        // does, into the same cache dir, so a later `pull` is a no-op.
+        const ctx = commonContext(opts.values);
+        dir = path.resolve(process.cwd(), path.join(".vidfarm", ref));
+        mkdirSync(dir, { recursive: true });
+        await fetchCompositionFiles({ host: ctx.host, forkId: ref, dir, apiKey: ctx.auth.apiKey, shareToken: ctx.auth.shareToken, refetch: opts.refetch });
+    }
+    const videoContext = readJsonFile(path.join(dir, "video-context.json"));
+    const editorHarness = readJsonFile(path.join(dir, "editor-harness.json"));
+    const replicationHarness = readJsonFile(path.join(dir, "replication-harness.json"));
+    if (!videoContext && !editorHarness && !replicationHarness) {
+        throw new Error(`No decompose output in ${dir} — nothing to derive a harness from. Run \`vidfarm decompose ${forkId ?? "<forkId>"}\` first, ` +
+            `then re-run. (A harness can also be written from scratch: \`vidfarm harness init short-form\`.)`);
+    }
+    const markdown = buildDerivedHarnessMarkdown({
+        ref,
+        forkId,
+        dir,
+        videoContext,
+        editorHarness,
+        replicationHarness,
+        sceneAnnotations: readJsonFile(path.join(dir, "scene-annotations.json")),
+        compositionHtml: existsSync(path.join(dir, "composition.html")) ? readFileSync(path.join(dir, "composition.html"), "utf8") : null
+    });
+    const outPath = opts.outPath ?? path.join(dir, HARNESS_FILENAME);
+    if (existsSync(outPath) && !opts.force) {
+        throw new Error(`${outPath} already exists. Pass --force to overwrite (you will lose your edits), or --out <path> to write elsewhere.`);
+    }
+    mkdirSync(path.dirname(outPath), { recursive: true });
+    writeFileSync(outPath, markdown, "utf8");
+    const parsedOut = parseHarness(markdown, outPath);
+    if (opts.json) {
+        return printJson({
+            ok: true,
+            source: forkId ?? dir,
+            dir,
+            path: outPath,
+            dna: parsedOut.dna.map((strand) => strand.key),
+            checks: Object.keys(parsedOut.checks),
+            review_items: parsedOut.review_items.length
+        });
+    }
+    console.log(`${GREEN}${outPath}${RESET} ${DIM}← decomposition of ${forkId ?? path.basename(dir)}${RESET}`);
+    console.log(`${DIM}DNA written: ${parsedOut.dna.map((strand) => strand.key).join(", ") || "none"}${RESET}`);
+    console.log(`${DIM}${Object.keys(parsedOut.checks).length} machine check(s), ${parsedOut.review_items.length} review item(s).${RESET}`);
+    console.log(`${DIM}This is a STARTING POINT, not a verdict — read it, delete what the decompose pass guessed wrong, and add what only you know.${RESET}`);
+    console.log(`${DIM}Then: vidfarm qa ${pastablePath(dir)}${RESET}`);
+}
+/** Fold the decompose JSON strands into the standard harness layout. */
+function buildDerivedHarnessMarkdown(input) {
+    const viralDna = (input.videoContext?.viral_dna && typeof input.videoContext.viral_dna === "object"
+        ? input.videoContext.viral_dna : null);
+    const harness = (input.editorHarness?.harness && typeof input.editorHarness.harness === "object"
+        ? input.editorHarness.harness : null);
+    const replication = (input.replicationHarness?.harness && typeof input.replicationHarness.harness === "object"
+        ? input.replicationHarness.harness : null);
+    const sub = (parent, key) => parent && parent[key] && typeof parent[key] === "object" && !Array.isArray(parent[key])
+        ? parent[key]
+        : null;
+    const emotional = sub(viralDna, "emotional_punch") ?? sub(harness, "emotional");
+    const pacing = sub(harness, "pacing");
+    const typography = sub(harness, "typography");
+    const broll = sub(harness, "broll");
+    const transitions = sub(harness, "transitions");
+    const audio = sub(harness, "audio");
+    const staticVsPivot = sub(viralDna, "static_vs_pivot");
+    const annotations = Array.isArray(input.sceneAnnotations?.annotations)
+        ? input.sceneAnnotations.annotations
+        : [];
+    const scenes = Array.isArray(harness?.scenes) ? harness.scenes : [];
+    const value = (raw) => readJsonString(raw) || "_unknown — the decompose pass didn't record this; fill it in._";
+    const bullets = (items, empty) => items.length ? items.map((item) => `- ${item}`).join("\n") : `- ${empty}`;
+    // The composition itself settles the two checks nobody should have to type.
+    const info = input.compositionHtml ? inspectComposition(input.compositionHtml) : null;
+    const durationCheck = info?.duration_seconds ? `${Math.max(1, Math.floor(info.duration_seconds * 0.7))}-${Math.ceil(info.duration_seconds * 1.3)}` : null;
+    const beatRows = scenes.slice(0, 12).map((scene) => {
+        const role = readJsonString(scene.role) || "beat";
+        const importance = readJsonString(scene.importance);
+        const bias = readJsonString(scene.edit_bias);
+        const keep = scene.must_keep === true ? " **must-keep**" : "";
+        return `**${role}**${importance ? ` (${importance})` : ""}${keep}${bias ? ` — ${bias}` : ""}`;
+    });
+    const mustPreserve = annotations
+        .flatMap((entry) => readJsonStringList(entry.must_preserve, 3).map((item) => {
+        const slug = readJsonString(entry.scene_slug);
+        return slug ? `${slug}: ${item}` : item;
+    }))
+        .slice(0, 8);
+    const recommendedStrategy = readJsonString(replication?.recommended_strategy) || "cheap_efficient";
+    const cheapPlan = sub(replication, "cheap");
+    const qualityPlan = sub(replication, "quality");
+    const motionStyle = sub(replication, "motion_style");
+    const frontMatter = [
+        "---",
+        `name: ${(input.forkId ?? path.basename(input.dir)).replace(/[^A-Za-z0-9_-]/g, "-")}`,
+        `video_type: ${readJsonString(viralDna?.trend_tagline) || readJsonString(harness?.one_liner) || "derived from a decomposed template"}`,
+        `derived_from: decompose`,
+        input.forkId ? `source_template_id: ${input.forkId}` : null,
+        "checks:",
+        durationCheck ? `  duration_sec: ${durationCheck}` : null,
+        info?.aspect_ratio ? `  aspect: ${info.aspect_ratio}` : null,
+        "  first_frame_visual: required",
+        "  font_regime: required",
+        "  safe_zone: required",
+        "---"
+    ].filter(Boolean).join("\n");
+    return `${frontMatter}
+
+# Harness: ${readJsonString(viralDna?.trend_tagline) || readJsonString(harness?.one_liner) || input.forkId || path.basename(input.dir)}
+
+Derived from the decomposition of ${input.forkId ? `\`${input.forkId}\`` : path.basename(input.dir)}. **This is a first draft written by a model that watched the source, not a verdict.** Read every strand, delete what it got wrong, and add what only you know — the audience, the offer, the banned vocabulary. A harness nobody edited is about the source video, not about your videos.
+
+## Viral DNA — why the source travelled
+
+- **Trend/format:** ${value(viralDna?.trend_tagline)}
+- **Hook:** ${value(viralDna?.hook)}
+- **Retention mechanic:** ${value(viralDna?.retention ?? viralDna?.retention_mechanic)}
+- **Payoff:** ${value(viralDna?.payoff)}
+- **Core emotion:** ${value(emotional?.core_emotion ?? emotional?.target_feeling)}
+- **Mechanism:** ${value(emotional?.mechanism)}
+- **Contrast:** ${value(emotional?.contrast)}
+
+**Rebuild each charge for the new subject — never flatten the loop into a product statement.** The four charges (hook / loop / payoff / bait) are the craft behind this section: \`vidfarm harness show hooks\`.
+
+- [ ] Does my version have its OWN hook, or did I keep the source's sentence with the nouns swapped?
+- [ ] Does the curiosity loop close inside this video, at a timestamp I can name?
+- [ ] Is the withheld answer one the viewer genuinely can't supply themselves?
+
+## Visual DNA — how it looks and cuts
+
+- **Cut rhythm:** ${value(pacing?.cut_rhythm)}${readJsonString(pacing?.avg_scene_seconds) ? ` (~${readJsonString(pacing?.avg_scene_seconds)}s per scene)` : ""}
+- **Energy curve:** ${value(pacing?.energy_curve)}
+- **Caption style:** ${value(typography?.caption_style)} — placement ${readJsonString(typography?.placement) || "unrecorded"}, ${readJsonString(typography?.text_density) || "density unrecorded"}
+- **Font character:** ${value(typography?.font_character)}
+- **B-roll:** ${value(broll?.reliance)}${readJsonString(broll?.sourcing) ? ` — sourced ${readJsonString(broll?.sourcing)}` : ""}${readJsonString(broll?.cadence) ? `, cadence ${readJsonString(broll?.cadence)}` : ""}
+- **Transitions:** default ${readJsonString(transitions?.default) || "unrecorded"}, in ${readJsonString(transitions?.intro) || "unrecorded"}, out ${readJsonString(transitions?.outro) || "unrecorded"}
+- **Motion feel:** ${value(motionStyle?.animation_feel)}
+
+- [ ] One type scale, one accent colour, one illustration style across every beat — checked on a contact sheet, not scene by scene (\`vidfarm stills . --sheet\`).
+- [ ] Caption colour and plate chosen by MEASURING the composited background, not by habit — one treatment for the whole video.
+
+## Structural DNA — the beats
+
+${bullets(beatRows, "_no scene roles recorded — run `vidfarm decompose` with the harness pass._")}
+
+**Load-bearing beats (do not reskin past these):**
+${bullets(mustPreserve.length ? mustPreserve : readJsonStringList(harness?.important_scenes, 6), "_none recorded._")}
+
+- [ ] Every must-keep beat kept its timing, role, and caption cadence — I swapped the subject, not the structure.
+
+## Audio DNA — voice, bed, timing
+
+- **Voiceover:** ${value(audio?.voiceover)}
+- **Music:** ${value(audio?.music)}
+- **SFX:** ${value(audio?.sfx)}
+- **Captions from:** ${value(audio?.captions_from)}
+- **Comedic timing:** ${value(emotional?.comedic_timing)}
+- **Intonation / delivery:** ${value(emotional?.intonation ?? emotional?.delivery)}
+
+- [ ] The held beat / pause / hard cut that sells the joke survived the re-cut.
+- [ ] Speech sits ~12–15 dB over the bed across the actual word spans — MEASURED, not "sounds fine".
+
+## Build DNA — which paintbrush per beat
+
+Recommended strategy: **${recommendedStrategy}**${readJsonString(replication?.recommendation_reason) ? ` — ${readJsonString(replication?.recommendation_reason)}` : ""}
+
+- **Cheap mix:** ${value(cheapPlan?.method_mix ?? cheapPlan?.one_liner)}
+- **Best-quality mix:** ${value(qualityPlan?.method_mix ?? qualityPlan?.one_liner)}
+- **Free-tier path:** ${value(replication?.free_tier_note)}
+
+**Do these in hyperframes (HTML/CSS/JS), never AI video:**
+${bullets(readJsonStringList(motionStyle?.hyperframes_candidates, 6), "all on-screen text and graphic overlays")}
+
+**Guardrails the replication pass flagged:**
+${bullets(readJsonStringList(replication?.viral_dna_guardrails, 6), "_none recorded._")}
+
+## Re-theming — what's static, what pivots
+
+- **Summary:** ${value(staticVsPivot?.summary)}
+- **Scenes:** ${value(sub(staticVsPivot, "scene_replacement")?.overall)}
+- **Narration:** ${value(sub(staticVsPivot, "narration")?.overall)}
+- **Music:** ${value(sub(staticVsPivot, "music")?.overall)}
+- **Captions:** ${value(sub(staticVsPivot, "captions")?.overall)}
+
+## Rules for this format
+
+${bullets(readJsonStringList(harness?.do, 6).map((item) => `DO: ${item}`).concat(readJsonStringList(harness?.dont, 6).map((item) => `DON'T: ${item}`)), "_none recorded — write yours here, each with the reason attached._")}
+
+> Every rule you add needs its **why** on the same line. A rule whose reason is missing gets argued away by the next agent that reads it.
+
+## Whole-video review — do this last
+
+Nothing above can see the finished video. Tile ~12 stills into one contact sheet and read it as a single image (\`vidfarm stills . --sheet\`): margins that shift between beats, three type sizes, an accent colour that wanders, N identically-long beats, a jarring join, a dead band under top-anchored content. Those are sequence-level defects, invisible to every per-scene check and to the agent that built it. Compare two frames from DIFFERENT scenes — a frozen render passes duration, frame count and every one-frame check. Method: \`references/reviewing-renders.md\`.
+
+- [ ] I read a contact sheet of the finished render, not just stills of the scenes I was working on.
+- [ ] I compared two frames from different scenes and they differ.
+- [ ] I reported what I MEASURED separately from what I JUDGED.
+`;
 }
 // `vidfarm stills <dir|composition.html>` — render PNG stills of the CURRENT
 // composition in-process (the agent's visual self-verification loop).
@@ -10264,20 +10822,32 @@ async function runStillsCommand(argv) {
         options: {
             at: { type: "string" },
             out: { type: "string" },
+            sheet: { type: "boolean", default: false },
+            "sheet-out": { type: "string" },
+            "sheet-width": { type: "string" },
             json: { type: "boolean", default: false }
         }
     });
     const target = parsed.positionals[0];
     if (!target)
-        throw new Error("stills requires a composition path: `vidfarm stills <dir-or-composition.html> [--at 0,2.5,7] [--out <dir>]`.");
+        throw new Error("stills requires a composition path: `vidfarm stills <dir-or-composition.html> [--at 0,2.5,7] [--sheet] [--out <dir>]`.");
     const htmlPath = resolveCompositionHtmlPath(target);
     const json = Boolean(parsed.values.json);
     const at = parsed.values.at
         ? String(parsed.values.at).split(",").map((value) => parseTimeToSeconds(value.trim())).filter((value) => Number.isFinite(value))
         : undefined;
+    const sheetWidthRaw = parsed.values["sheet-width"] ? Number.parseInt(String(parsed.values["sheet-width"]), 10) : undefined;
     if (!json)
         console.log(`${DIM}Rendering stills in-process (free, local Chrome capture)…${RESET}`);
-    const result = await renderCompositionStills({ htmlPath, at, outDir: parsed.values.out, quiet: json });
+    const result = await renderCompositionStills({
+        htmlPath,
+        at,
+        outDir: parsed.values.out,
+        quiet: json,
+        sheet: Boolean(parsed.values.sheet),
+        sheetPath: parsed.values["sheet-out"],
+        ...(Number.isFinite(sheetWidthRaw) ? { sheetTileWidth: sheetWidthRaw } : {})
+    });
     if (json) {
         printJson(result);
         return;
@@ -10286,6 +10856,10 @@ async function runStillsCommand(argv) {
         console.log(`  ${GREEN}${still.path}${RESET} ${DIM}(requested ${still.requested_sec}s → captured ${still.captured_sec}s)${RESET}`);
     }
     console.log(`${DIM}${result.stills.length} still(s) at ${result.grid_fps}fps grid accuracy — open them to verify the edit before rendering.${RESET}`);
+    if (result.sheet) {
+        console.log(`  ${GREEN}${result.sheet}${RESET} ${DIM}(contact sheet)${RESET}`);
+        console.log(`${DIM}READ the contact sheet as ONE image — that is how you catch what per-scene checks miss: uneven margins, a wandering type scale or accent colour, N identically-long beats, a jarring join, dead space under top-anchored content. Fix drift by defining the system, not by patching the one odd scene.${RESET}`);
+    }
 }
 // ── Agent skill ───────────────────────────────────────────────────────────────
 // Install the latest director skill onto disk as a Claude Code / agent skill so
@@ -10326,7 +10900,134 @@ async function fetchSkillContents(host, target) {
     }
     throw new Error(`Could not fetch ${target.bundled} from ${host} and no bundled copy was found.`);
 }
+/** The installed devcli's own version — the thing the bundled pack is pinned to. */
+function devcliVersion() {
+    const pkgPath = locateBundledSkill("package.json");
+    if (!pkgPath)
+        return null;
+    try {
+        const version = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `vidfarm skill <ls|show|search|print|path>` — READ the skill pack that ships
+ * inside this devcli, with no network and no account.
+ *
+ * The pack is already in the npm tarball (`.agents/skills/**` is in
+ * package.json `files`), so every install has the full director knowledge on
+ * disk. Before this, nothing could read it without `vidfarm skills add`
+ * (installs into a project) or a fetch — which meant going online to learn how
+ * to use a local-first CLI.
+ *
+ * The bundled copy is version-pinned to this CLI, which is the correct pairing.
+ * It is documentation, NOT entitlement: the paid primitives it documents (AI
+ * generation, hosted render, social recycle, media download, marketplace) still
+ * require `vidfarm login` and a cloud call. The free-local half (clipping,
+ * hyperframes, `vidfarm serve` render, qa, harnesses, dedupe, Kokoro TTS) is
+ * genuinely offline. Every surface below says so rather than letting an offline
+ * read imply an offline entitlement.
+ */
+async function runSkillDocsCommand(sub, argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { json: { type: "boolean", default: false }, pack: { type: "string" }, limit: { type: "string" } }
+    });
+    const json = Boolean(parsed.values.json);
+    const pack = String(parsed.values.pack ?? DEFAULT_PACK);
+    const ref = parsed.positionals[0];
+    if (sub === "path" || sub === "where") {
+        const dir = bundledPackDir(pack);
+        if (!dir)
+            throw new Error(`No bundled "${pack}" pack found next to this devcli install.`);
+        if (json)
+            return printJson({ ok: true, pack, path: dir, offline: true }), true;
+        console.log(dir);
+        return true;
+    }
+    if (sub === "ls" || sub === "list" || sub === "files" || sub === "index") {
+        const docs = listPackDocs(pack);
+        if (!docs.length)
+            throw new Error(`No bundled "${pack}" pack found next to this devcli install. Fetch it with \`vidfarm skills add ${pack}\`.`);
+        if (json)
+            return printJson({ ok: true, pack, source: "bundled", offline: true, files: docs.map(({ rel, lines, bytes }) => ({ path: rel, lines, bytes })) }), true;
+        console.log(`${DIM}Bundled ${pack} skill pack — pinned to devcli ${devcliVersion() ?? "(this install)"}, read offline, no account:${RESET}`);
+        let group = "";
+        for (const doc of docs) {
+            const dir = doc.rel.includes("/") ? doc.rel.slice(0, doc.rel.indexOf("/")) : "";
+            if (dir !== group) {
+                group = dir;
+                if (dir)
+                    console.log(`  ${BOLD}${dir}/${RESET}`);
+            }
+            console.log(`    ${GREEN}${doc.rel.padEnd(46)}${RESET} ${DIM}${String(doc.lines).padStart(4)} ln${RESET}`);
+        }
+        console.log(`\n${DIM}vidfarm skill show <path|shorthand>   ·   vidfarm skill search "<term>"${RESET}`);
+        console.log(`${DIM}Start with SKILL.md — its File Index says which file answers what.${RESET}`);
+        console.log(`${DIM}This is documentation, not entitlement: the free-local half (clips, hyperframes, \`vidfarm serve\` render, qa, harnesses, dedupe, local TTS) runs offline; AI generation, hosted render, recycle, download and marketplace still need \`vidfarm login\` and a network call.${RESET}`);
+        return true;
+    }
+    if (sub === "show" || sub === "read" || sub === "cat") {
+        if (!ref)
+            throw new Error('skill show requires a file: `vidfarm skill show references/primitives.md` (shorthand like "primitives" works too).');
+        let resolved;
+        try {
+            resolved = readPackDoc(ref, pack);
+        }
+        catch (error) {
+            // An ambiguous shorthand is a normal outcome, not a crash — "hooks"
+            // legitimately names both the craft reference and the harness. Print the
+            // choice instead of a stack trace, and don't guess on the caller's behalf.
+            if (!(error instanceof AmbiguousDocRef))
+                throw error;
+            if (json)
+                return printJson({ ok: false, pack, ref, ambiguous: error.candidates }), true;
+            console.log(`${YELLOW}"${ref}" matches ${error.candidates.length} files${RESET} ${DIM}— name one:${RESET}`);
+            for (const candidate of error.candidates)
+                console.log(`  vidfarm skill show ${GREEN}${candidate}${RESET}`);
+            process.exitCode = 1;
+            return true;
+        }
+        const { doc, contents } = resolved;
+        if (json)
+            return printJson({ ok: true, pack, path: doc.rel, lines: doc.lines, source: "bundled", contents }), true;
+        process.stdout.write(contents.endsWith("\n") ? contents : `${contents}\n`);
+        return true;
+    }
+    if (sub === "search" || sub === "grep" || sub === "find") {
+        if (!ref)
+            throw new Error('skill search requires a term: `vidfarm skill search greenscreen`.');
+        const limit = Number(parsed.values.limit ?? 40);
+        const matches = searchPackDocs(ref, { name: pack, limit: Number.isFinite(limit) ? limit : 40 });
+        if (json)
+            return printJson({ ok: true, pack, term: ref, matches }), true;
+        if (!matches.length) {
+            console.log(`${DIM}No match for "${ref}" in the bundled ${pack} pack. \`vidfarm skill ls\` lists every file.${RESET}`);
+            return true;
+        }
+        let current = "";
+        for (const match of matches) {
+            if (match.rel !== current) {
+                current = match.rel;
+                console.log(`${BOLD}${match.rel}${RESET}`);
+            }
+            console.log(`  ${DIM}${String(match.line).padStart(4)}${RESET}  ${match.text}`);
+        }
+        console.log(`\n${DIM}${matches.length} match(es). Open one: vidfarm skill show <path>${RESET}`);
+        return true;
+    }
+    return false;
+}
 async function runUpdateSkillCommand(argv) {
+    // Read-only subcommands come first and never touch the network or auth, so
+    // `vidfarm skill ls` works on a plane with no credential configured.
+    const sub = argv[0] ?? "";
+    if (sub && !sub.startsWith("-") && await runSkillDocsCommand(sub, argv.slice(1)))
+        return;
     const parsed = parseArgs({
         args: argv,
         allowPositionals: false,
@@ -10335,14 +11036,21 @@ async function runUpdateSkillCommand(argv) {
             global: { type: "boolean", default: false },
             dir: { type: "string" },
             platform: { type: "boolean", default: false },
-            print: { type: "boolean", default: false }
+            print: { type: "boolean", default: false },
+            remote: { type: "boolean", default: false }
         }
     });
     const ctx = commonContext(parsed.values);
     const skillNames = ["vidfarm", ...(parsed.values.platform ? ["vidfarm-platform"] : [])];
     if (parsed.values.print) {
+        // BUNDLED FIRST. The tarball's copy is pinned to this CLI version, which is
+        // the pairing that actually works — a newer skill against an older binary
+        // is the usual cause of "the skill says to do X but the command 404s".
+        // `--remote` opts into the host's latest when that's what you want.
         for (const name of skillNames) {
-            const { contents } = await fetchSkillContents(ctx.host, SKILL_TARGETS[name]);
+            const target = SKILL_TARGETS[name];
+            const bundled = parsed.values.remote ? null : locateBundledSkill(target.bundled);
+            const contents = bundled ? readFileSync(bundled, "utf8") : (await fetchSkillContents(ctx.host, target)).contents;
             process.stdout.write(contents.endsWith("\n") ? contents : `${contents}\n`);
         }
         return;