@officexapp/vidfarm-devcli 0.21.39 → 0.21.43

package/dist/src/cli.js

@@ -19,7 +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 { extractCompositionFacts, formatQaReport, formatWatchTheVideoNotice, qaCompositionHtml, watchTheVideoDirective } from "./devcli/qa-check.js";
+import { extractCompositionFacts, formatQaReport, formatWatchTheVideoNotice, qaCompositionHtml, recordQaPass, 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";
@@ -29,7 +29,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 { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, listPackTopics, loadIdeaBank, readPackDoc, readPackTopic, resolvePackTopic, 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";
@@ -37,6 +37,8 @@ import { readStoredAuth, writeStoredAuth, clearStoredAuth, hostsMatch } from "./
 import { CostModeBlockedError, assertBilledAllowed, clearStoredCostMode, costModeExplainer, costModeSummaryLine, normalizeCostMode, resolveCostMode, writeStoredCostMode, COST_MODE_BLURB, COST_MODE_DISPLAY_LIST, costModeDisplayName } from "./devcli/cost-mode.js";
 import { INTERACTION_MODES, INTERACTION_MODE_BLURB, clearStoredInteractionMode, interactionModeExplainer, interactionModeSummaryLine, interactiveOfferLine, normalizeInteractionMode, resolveInteractionMode, writeStoredInteractionMode } from "./devcli/interaction-mode.js";
 import { buildImageHandoff, buildRawsHandoff, formatHandoff } from "./devcli/handoff.js";
+import { buildConsultBrief, CONSULT_ARTIFACTS, consultContextState, consultCountRange, defaultConsultCount, findOfferFile, formatConsultBrief, looksLikeOfferPath, planConsultation, resolveConsultStep, resolveOfferPath } from "./devcli/consult.js";
+import { resolveRootFileCandidates } from "./lib/package-root.js";
 import { STORYBOARD_FILENAME, readStoryboard, renderStoryboardScaffold, storyboardStage } from "./devcli/storyboard.js";
 import { CORE_METRICS, DEFAULT_FORMAT, DEFAULT_METRIC, EASY_FORMATS, EXPERIMENTS_FILENAME, EXPERIMENT_MODES, analyzeRound, appendResult, appendRound, capacityOf, epochsNeeded, findRoundIndex, lintDiary, markPosted, readDiary, renderDiaryScaffold, writeDiary } from "./devcli/experiments.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
@@ -120,6 +122,31 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
                             download (a downloader SEARCH, not a rotting link), and
                             the vidfarm clipper / raws scan follow-up. Try browser control
                             or "vidfarm raws scan" first.
+  consult [step]            THE CONSULTATION / BRAINSTORM CHAIN, KEYLESS AND LOCAL.
+                            The cloud runs these as brainstorm/* primitives that need
+                            a provider key or wallet credits. This prints the IDENTICAL
+                            prompt for YOU (the agent already in this terminal) to
+                            answer — $0, no key, no network. Bare "consult" = the map
+                            of the four steps + which artifacts already exist.
+                            Every step reads and updates CONTEXT.md in --dir, the
+                            durable answer file, so a later session starts warm.
+                            Run the whole chain from ONE working folder.
+                            (aliases: consultation, brainstorm)
+    coldstart [--short]     The interview → OFFER.md. Ask the human the questions a
+                            few at a time; never invent their answers. --short is a
+                            fixed 6-question form for a director in a hurry, and it
+                            still feeds every later step. (alias: interview)
+    awareness               Which awareness stage to sell to → awareness-levels.md
+    angles                  Persuasive angles → persuasive-angles.md
+                            [--problem-awareness problem_unaware|problem_aware]
+                            [--solution-awareness solution_unaware|solution_aware]
+    hooks                   Openings to test → ad-hooks.md (grade them before showing)
+    placement --video <p>   Native product-placement moments in an existing video
+    --offer <text|path>     The offer. Auto-reads OFFER.md / OFFER_<NAME>.md from --dir.
+    --count <n>             How many questions/angles/hooks (default 12)
+    --refs                  Inline the full SELLING_*.md references, exactly as the
+                            cloud prompt does. Off by default: ~34KB of your context.
+    --json                  The brief as data (prompt, steps, artifact, next)
   storyboard [dir]          The PLAN pass: read the project's STORYBOARD.md (ordered
                             frames + duration/status/src/scene/voiceover, plus SCRIPT.md).
                             The editor renders this file in its Storyboard view — a
@@ -694,6 +721,32 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
     --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
+  media <type> "<query>"    Search the FREE stock catalog — no AI spend, no wallet cost.
+                            type: image|vector|icon|video|bgm|sfx. Openverse (CC images,
+                            music, SFX) and iconify (icons) are KEYLESS; a free Pixabay
+                            key adds photos/vectors/stock video.
+    --provider <p>            Force pixabay|openverse|iconify|iconscout
+    --limit <n> | --json
+  iconscout "<query>"       DESIGNER icons, STICKERS, illustrations, 3D and Lottie —
+                            THE CHEAP ALTERNATIVE TO AI IMAGE GENERATION. Reach for this
+                            BEFORE 'generate' / 'image': an AI sticker costs cents per
+                            attempt, needs a prompt loop, and rarely returns a clean
+                            transparent vector; IconScout returns a finished SVG or
+                            transparent PNG on the first try. Search is FREE.
+                            Works with NO key — vidfarm's own IconScout subscription
+                            serves premium downloads for a tiny wallet charge.
+    --asset <a>               icon (default)|illustration|3d|lottie|ai_image
+    --style <s>               sticker|flat|line|glyph|gradient|isometric|rounded|doodle|
+                              dualtone|colored-outline|tile  (--style sticker = STICKERS)
+    --free                    Free assets only ($0, credit required). --premium for the
+                              paid catalog (no credit line needed)
+    --sort <s>                relevant (default)|popular|latest|featured
+    --limit <n> --page <n> --json
+  iconscout get <uuid>      Download ONE asset to a durable vidfarm URL you can place.
+    --format <f>              icon svg|png · illustration svg|png|eps · 3d png|gltf|glb|
+                              obj|fbx|blend · lottie json|lottie|gif|mp4 (default: first valid)
+    --size <px>               Pixel size for raster formats (default 512; vectors ignore it)
+    --out <file>              Also save the file locally
   stt <file|url>            Video or audio → transcript (alias: transcribe).  LOCAL: local ffmpeg demux +
                             Returns BOTH formats: the simple subtitle    your provider key (gemini labels
                             version (plain text + timed SRT cues) and    speakers; openai/openrouter give
@@ -787,20 +840,30 @@ 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
+  qa <dir|composition.html>   Social-native QA pass — OPTIONAL.           (local, devcli-only)
+                            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. Skip it freely;
+                            watching the render is the review that counts
     --harness <name|path>     Grade against a HARNESS.md too (repeatable —
                               they stack). A built-in name or ANY file path.
                               <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)
+    --max-revisions <n>       REVISION GOVERNOR (default 1, 0 disables). qa counts
+                              how many times the composition CHANGED between passes
+                              — re-running on an untouched file is free — and at the
+                              limit it WITHHOLDS the findings and tells you to ship
+                              or ask the human. That's the base case that stops a
+                              qa -> fix -> qa loop: one pass names the slop, one fix
+                              clears it, and what's left is nearly always taste, not
+                              a defect. Raise it when the human asks for another round
+    --reset-revisions         Start the revision count over
   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.
@@ -809,7 +872,7 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
                             template_id" all land here
     harness list [--json]             Bundled starting points: short-form,
                                       hooks, ugc-testimonial, explainer,
-                                      product-demo
+                                      product-demo, product-explainer
     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
@@ -889,10 +952,31 @@ Account:
   whoami                    Show the authenticated account               → GET  /api/v1/user/me
   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
+                            provider: openai|gemini|openrouter|perplexity|nvidia|elevenlabs|pixabay|iconscout
+                            (iconscout takes BOTH values as one secret: <client_id>:<client_secret>)
 
 Agent skill (the director knowledge — a full copy SHIPS INSIDE this CLI):
+  ideas [topic]             "What should I post?" — the 50-frame ANGLE BANK  (local — offline, free, no AI)
+                            (the rise of · what everyone gets wrong · then vs
+                            now · one decision that changed everything · …).
+                            One offer poured into 50 frames is 50 DIFFERENT
+                            videos, not 50 rewrites of one. It hands over the
+                            frames; you fill them with the director's offer,
+                            then write hook/loop/payoff/bait per pick
+    --topic "<offer>"         Print each frame already filled with your topic
+    --family <name>           One family only (arc, contrast, pivot, …)
+    --families                List the families and their sizes
+    --count <n>               Sample N, spread across families (default 20 with --topic)
+    --json                    Machine-readable frames (+ starter lines)
+  skill topics              The craft this pack knows, by SPOKEN name —       (local — offline, no account)
+                            meme-recaption, product-explainer, captions,
+                            first-frame, blurred-plate, density, avatar, …
+                            each mapped to its file and section
   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
+  skill show <path|topic>   Print one file — or just the SECTION a topic
+                            names: \`skill show meme-recaption\` prints the
+                            recaption method, not the 650-line reference it
+                            lives in. Shorthand works too: \`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
@@ -1239,6 +1323,11 @@ async function main() {
         case "media":
             await runMediaCommand(rest);
             return;
+        case "iconscout":
+        case "icons":
+        case "stickers":
+            await runIconScoutCommand(rest);
+            return;
         case "stt":
         case "transcribe":
             await runSttCommand(rest);
@@ -1334,6 +1423,13 @@ async function main() {
         case "hand-off":
             await runHandoffCommand(rest);
             return;
+        // The brainstorm chain with no AI key: the prompt goes to the agent that is
+        // already here, not to a provider. "consultation" is the director's word.
+        case "consult":
+        case "consultation":
+        case "brainstorm":
+            await runConsultCommand(rest);
+            return;
         case "storyboard":
         case "plan":
             await runStoryboardCommand(rest);
@@ -1342,6 +1438,12 @@ async function main() {
         case "experiments":
             await runExperimentCommand(rest);
             return;
+        // "what should I post?" — the 50-frame angle bank, read off the bundled pack.
+        case "content-ideas":
+        case "idea":
+        case "ideas":
+            await runIdeasCommand(rest);
+            return;
         case "update-skill":
         case "skill":
             await runUpdateSkillCommand(rest);
@@ -2509,15 +2611,17 @@ Rules:
 - 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; a keyword comment ask ("comment CLIPPER and I'll send the breakdown") is standard and allowed, but never "follow for part two", ragebait, or an earnings/health claim traded for the reply. Then build the timeline. Re-theming a decomposed template: viral_dna already names the source's hook/retention/payoff — rebuild each charge for the new subject, never flatten the loop into a product statement. Full craft harness: the vidfarm skill's references/hooks-and-virality.md. Checkable form: \`vidfarm harness show hooks\`.
+- ORIENT THE COLD VIEWER IN THE FIRST 3 SECONDS — THE VIEWER HAS NO CONTEXT AND DID NOT CHOOSE THIS VIDEO. Distinct from the hook: the hook makes them WANT to watch, orientation makes the watching POSSIBLE. A stranger mid-scroll must be able to answer three things by ~3s — what am I looking at (the CATEGORY noun), who is it for, and why is this on my screen (the situation). The failure is not a bad first frame, it is a good video that BEGINS AT BEAT TWO, and the author cannot see it because the author already knows what the thing is. Signatures, each a rebuild not a polish: a pronoun with no referent ("it just works", "this changes everything", "here's how they do it"); starting at step three (the process already running, the dashboard already full); a metaphor whose subject only lands at 6s; insider vocabulary, a product's own feature name, or an ACRONYM in the first line; a detail crop that reads as texture until you know the whole. Instead, the opening beat is BOTH channels at once: an EASY IMAGE (one large subject, already moving, legible at a glance and at thumbnail scale — a relevant die-cut sticker names the category before a word is read) AND an EASY LINE (first spoken sentence one clause, <=12 words, everyday words, concrete noun + verb, no subordinate clause, brand name said once plainly, and the CATEGORY named: "X is a language app that…"). Give the SITUATION, not the label — "the end of the month, and your receipts are in a shoebox" orients, "expense automation" does not. THIS IS NOT AN INTRO AND COSTS NO EXTRA SECONDS: it replaces the wind-up sentence, it never precedes it, and it never licenses a logo, a title card or a fade from black. Test it on the render, not the script: play the first 3 seconds ONLY to somebody with no context and stop — they should say what kind of thing it is and roughly who it is for. "Something about audio" is a fail. Fullest form: \`vidfarm harness show product-explainer\` (Rule 0).
 - THE FIRST FRAME IS THE THUMBNAIL. Frame 0 is one frame of ~30 in the first second, but every feed card, share link, and paused player freezes on it — more people see that frame than watch the video. It must never be black, empty, mid-fade, or mid-animation: a real visual at start:0 (\`vidfarm retime . --layer <key> --start 0\`), the hook words already on screen at t=0, and NO entrance transition on the FIRST clip (\`vidfarm transitions set . --layer <key> --in none\`; junction transitions between later clips are fine). Look at the actual pixels before you render: \`vidfarm stills . --at 0\`.
 - REVIEW THE WHOLE VIDEO AS ONE OBJECT — AND NEVER JUDGE IT BY ONE FRAME. Assume your own finished video has a defect you cannot see: across a 32-video batch, EVERY first-pass video had a real defect its own author had already reported as "verified, looks good". The cause is structural — you build scene by scene, each scene correct while it is the whole world, so every scene passes alone and the video fails as a SEQUENCE: margins shift between beats, headline sizes drift, the accent color wanders, one asset is flat vector and the next is photographic, every beat is the same length, a join lands like a slap. Nobody watches a scene; they watch the sequence. So before you call anything done, tile ~12 stills into ONE contact sheet and READ IT AS AN IMAGE — one command: \`vidfarm stills . --sheet\` (add \`--at 0,2,4,…\` to pick timestamps; writes stills/contact-sheet.png). Check: visual balance (no dead band under top-anchored content), consistent spacing/margins, ONE type scale, ONE accent color, ONE illustration style, deliberate pacing rather than N identical beats, nothing jarring at the joins, no frame where two elements compete for the eye — and the summary question, does it look like one person made it in one sitting? Fix drift by defining the SYSTEM (type scale, margin, palette, default beat) and applying it to every scene, not by patching the one scene that stood out. The defects that actually ship, in observed frequency order: large flat dead regions · a placeholder empty state that reads as a failed render · two contradictory numbers in one frame · a CTA still building at the last frame (settle it >=2s before the end) · two headlines superimposed at a scene handoff (exit at nextIn-0.18, duration 0.24, ease power2.out) · type colliding with a busy background exactly as it is spoken. If a frame looks empty, sample 0.2s apart to see whether it RESTS there — a transient wipe frame is fine, >0.5s is a hole. AND ALWAYS COMPARE TWO FRAMES FROM DIFFERENT SCENES: a frozen render (an overlay/watermark pass missing \`-loop 1\`, or assets outside the composition root so the timeline never runs) makes every frame identical while duration, frame count and audio hash all still pass, and frame 0 looks perfect. Verify audio by MEASUREMENT, never "it sounds fine" (you cannot hear it): ~12-15 dB speech-over-bed separation across the actual word spans, peak <0 dBFS. Never \`adelay\` the VO — whisper word timings and every caption built from them are relative to the raw vo.wav; use apad+atrim. Report what you MEASURED separately from what you JUDGED. Full method: the vidfarm skill's references/reviewing-renders.md.
-- 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.)
+- 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, product-explainer), 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.
 
 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.
 - A background video + a foreground video (greenscreen / picture-in-picture) covers most "video meme" formats with zero generation.
+- IF THE DIRECTOR GAVE YOU A WEBSITE (a product explainer / client brand video), THAT SITE IS THE FIRST ASSET LIBRARY — harvest before you buy or generate, unless they said not to use their site art. Take product screenshots and UI states, brand illustrations, mascots, spot art and icons, the palette and their own words, any animated WebP/GIF (free motion footage — extract frames to a sprite sheet), an SPA's manifest.json screenshots[], and best of all a screen recording in the JS bundle (that is A-roll). \`vidfarm capture <url>\` renders the page and pulls assets; \`vidfarm mask <image> --crop x,y,w,h\` cuts ONE element out of a screenshot into a snug transparent PNG with local matting for $0 (\`--flat <hex>\` on a solid background), repeatable to lift a whole cast out of one image; then place + keyframes it like any sticker. The order is HARVEST -> ICONSCOUT CATALOG -> GENERATE, and it is on-brand by construction, free, and truthful (a screen off their live site cannot claim what they do not claim). Two limits: harvest the ASSETS, never the landing-page furniture (no CTA capsules, feature grids, pricing cards, chip rows — a video is not a web page), and treat obvious stock photography as licensed to THEM, not to you. Say in your report which assets came from the client's own site. Full rule: \`vidfarm harness show product-explainer\` (Rule 5b).
 - Reusable asset library (logos, stickers, reactions, b-roll, a-roll, brand media kit): have an opinion on when/where to reuse — but anchor every asset choice to the viral DNA + harness above. Reskinning past a load-bearing beat kills what made the format work. AI-generate a reusable element ONCE, then reuse it; don't regenerate per-scene.
 
 Two replication harnesses — pick one and name it to the user (default A). When \`replication-harness.json\` is present it holds a CONCRETE, per-beat version of both plans (see "Replication plan" below) — prefer its beat assignments over freestyling; this prose is the fallback when it's absent:
@@ -4525,7 +4629,10 @@ async function runGenerateCommand(argv) {
             estimate: "cheap, ~$0.01–$0.05",
             freeAlternative: 'free stock image/vector — vidfarm media search "<meaning>" --type image|vector ($0). ' +
                 "Openverse (CC images) is keyless and always on — check it first; a free Pixabay key adds " +
-                "photos/vectors and may already be saved (check vidfarm provider-keys)",
+                "photos/vectors and may already be saved (check vidfarm provider-keys). " +
+                "If the image is an ICON, STICKER, illustration, 3D prop or Lottie, do NOT generate it at all — " +
+                'vidfarm iconscout "<meaning>" --style sticker returns a designer\'s finished transparent asset ' +
+                "for $0 (free tier, credit required) or a few cents, with no prompt loop",
             interactiveAlternative: 'hand the user an image brief — vidfarm handoff image --theme "<what>" --items "a,b,c" — they run it ' +
                 "in a free web generator (meta.ai / ChatGPT / Gemini) and drop the PNG back; needing several graphics " +
                 "makes it ONE sticker sheet that vidfarm sticker-pack splits for $0"
@@ -7696,7 +7803,10 @@ async function runMediaCommand(argv) {
     const items = Array.isArray(body.items) ? body.items : [];
     console.log(`${DIM}${items.length} ${type} result(s) for "${query}" via [${(body.providers_used ?? []).join(", ") || "none"}]${RESET}`);
     if (!items.length) {
-        console.log(`${DIM}No results. Try a broader query, another --type, or a specific --provider (pixabay|openverse|iconify).${RESET}`);
+        console.log(`${DIM}No results. Try a broader query, another --type, or a specific --provider (pixabay|openverse|iconify|iconscout).${RESET}`);
+        if (type === "icon" || type === "vector") {
+            console.log(`${DIM}(for icons/STICKERS/illustrations/3D/Lottie try 'vidfarm iconscout "${query}" --style sticker' — a much deeper designer catalog, and far cheaper than generating one with AI.)${RESET}`);
+        }
         if (type === "image" || type === "vector" || type === "video") {
             console.log(`${DIM}(photos/vectors/video need YOUR OWN free Pixabay key — get one at https://pixabay.com/api/docs/ then save it: 'vidfarm add-provider-key pixabay <key>'. openverse covers CC images keyless.)${RESET}`);
         }
@@ -7710,6 +7820,124 @@ async function runMediaCommand(argv) {
     }
     console.log(`${DIM}Attribution shown for CC-BY-style items — include it when you use them. Pixabay/CC0 need none.${RESET}`);
 }
+// IconScout — designer icons / STICKERS / illustrations / 3D / Lottie.
+//
+// This is the CHEAP path, and the CLI says so loudly: an AI image attempt costs
+// cents and a prompt loop for a sticker a designer already drew. Search is free,
+// so there is no cost-mode gate on it; only `iconscout get` can spend, and only
+// on a PREMIUM asset running on the platform subscription.
+async function runIconScoutCommand(argv) {
+    const ASSETS = ["icon", "illustration", "3d", "lottie", "ai_image"];
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            asset: { type: "string", short: "a" },
+            style: { type: "string" },
+            format: { type: "string", short: "f" },
+            sort: { type: "string" },
+            free: { type: "boolean" },
+            premium: { type: "boolean" },
+            limit: { type: "string" },
+            page: { type: "string" },
+            size: { type: "string" },
+            out: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const positionals = parsed.positionals.slice();
+    const sub = (positionals[0] ?? "").toLowerCase();
+    // ── iconscout get <uuid> — download one asset ────────────────────────────
+    if (sub === "get" || sub === "download") {
+        const uuid = positionals[1];
+        if (!uuid)
+            throw new Error('iconscout get requires an asset uuid (from `vidfarm iconscout "<query>"`).');
+        const size = Number(parsed.values.size ?? "512") || 512;
+        const body = { uuid };
+        if (parsed.values.format)
+            body.format = String(parsed.values.format).toLowerCase();
+        if (parsed.values.size) {
+            body.width = size;
+            body.height = size;
+        }
+        const res = await apiRequest({
+            method: "POST", host: ctx.host, path: "/api/v1/primitives/iconscout/download", auth: ctx.auth, body
+        });
+        assertApiOk(res, "iconscout get");
+        const out = (res.json ?? {});
+        if (ctx.json) {
+            printJson(out);
+            return;
+        }
+        console.log(`${GREEN}${out.url}${RESET}`);
+        const cost = out.billed ? `$${out.charged_usd} wallet` : out.is_free ? "$0 (free asset)" : "$0 (your own IconScout key)";
+        console.log(`${DIM}  ${out.name} · ${out.asset}/${out.format} · ${out.size_bytes} bytes · ${cost}${RESET}`);
+        if (out.attribution_required && out.attribution) {
+            console.log(`${RED}  ⚠ credit required: ${out.attribution}${RESET}`);
+        }
+        if (parsed.values.out) {
+            const dest = path.resolve(process.cwd(), String(parsed.values.out));
+            const fileRes = await fetch(out.url, { headers: buildAuthHeaders(ctx.auth) });
+            if (!fileRes.ok || !fileRes.body)
+                throw new Error(`Could not save the asset: ${fileRes.status}.`);
+            await pipeline(Readable.fromWeb(fileRes.body), createWriteStream(dest));
+            console.log(`${DIM}  saved → ${dest}${RESET}`);
+        }
+        console.log(`${DIM}Place it with: vidfarm set-media <dir> --src "${out.url}" --replace <layer_key>${RESET}`);
+        return;
+    }
+    // ── iconscout "<query>" — search ─────────────────────────────────────────
+    const query = (sub === "search" || sub === "find" ? positionals.slice(1) : positionals).join(" ").trim();
+    if (!query) {
+        console.error(`${RED}iconscout: a search query is required${RESET}`);
+        console.error(`${DIM}e.g. vidfarm iconscout "pineapple" --style sticker   |   vidfarm iconscout "rocket" --asset 3d${RESET}`);
+        process.exit(2);
+    }
+    const asset = String(parsed.values.asset ?? "icon").toLowerCase();
+    if (!ASSETS.includes(asset)) {
+        console.error(`${RED}iconscout: --asset must be one of: ${ASSETS.join(", ")}${RESET}`);
+        process.exit(2);
+    }
+    const qs = new URLSearchParams({ q: query, asset });
+    if (parsed.values.free)
+        qs.set("price", "free");
+    else if (parsed.values.premium)
+        qs.set("price", "premium");
+    if (parsed.values.style)
+        qs.set("style", String(parsed.values.style).toLowerCase());
+    if (parsed.values.format)
+        qs.set("format", String(parsed.values.format).toLowerCase());
+    if (parsed.values.sort)
+        qs.set("sort", String(parsed.values.sort).toLowerCase());
+    qs.set("limit", String(Number(parsed.values.limit ?? "20") || 20));
+    qs.set("page", String(Number(parsed.values.page ?? "1") || 1));
+    const res = await apiRequest({
+        method: "GET", host: ctx.host, path: `/api/v1/primitives/iconscout/search?${qs.toString()}`, auth: ctx.auth
+    });
+    assertApiOk(res, "iconscout search");
+    const body = (res.json ?? {});
+    if (ctx.json) {
+        printJson(body);
+        return;
+    }
+    const items = Array.isArray(body.items) ? body.items : [];
+    console.log(`${DIM}${items.length} of ${body.total ?? items.length} ${asset} result(s) for "${query}" (page ${body.page ?? 1}/${body.last_page ?? 1})${RESET}`);
+    if (!items.length) {
+        console.log(`${DIM}No results. Try a broader query, another --asset, or drop --style.${RESET}`);
+        return;
+    }
+    for (const it of items) {
+        const price = it.is_free ? `${GREEN}free${RESET}` : `${DIM}premium${RESET}`;
+        console.log(`${GREEN}${it.uuid}${RESET}  ${it.name}  [${price}${DIM}]${RESET}`);
+        console.log(`${DIM}  ${it.asset} · formats ${(it.formats ?? []).join("/")} · preview ${it.preview_url ?? "—"}${RESET}`);
+    }
+    const perDownload = Number(body.download_usd ?? 0);
+    console.log(`${DIM}Download one: vidfarm iconscout get <uuid> --format svg${RESET}`);
+    if (body.account === "platform" && perDownload > 0) {
+        console.log(`${DIM}Free assets cost $0 (credit required). Premium downloads run on vidfarm's IconScout subscription at ~$${perDownload} wallet each — still far cheaper than generating one with AI.${RESET}`);
+    }
+}
 async function runSttCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -9276,6 +9504,8 @@ async function runExperimentCommand(argv) {
             console.log(`${DIM}Format defaulted to ${BOLD}${DEFAULT_FORMAT}${RESET}${DIM}. Offer the director the menu (--format sets it):${RESET}`);
             for (const f of EASY_FORMATS)
                 console.log(`    ${DIM}·${RESET} ${f.label.padEnd(38)} ${DIM}${f.note}${RESET}`);
+            // The script's grammatical person is the fastest way to pick from that menu.
+            console.log(`${DIM}Rule of thumb: copy that says ${BOLD}"I"${RESET}${DIM} → show the speaker's world (POV b-roll / talking head / process). Copy that says ${BOLD}"you"${RESET}${DIM} → meme recaption (greenscreen raw over a background image). Both finish with TikTok-native type, kinetic captions and free Kokoro VO.${RESET}`);
         }
         console.log(`${DIM}Then plan the first round: ${BOLD}vidfarm experiment round --variable angle --videos 8 --why "awareness level is the largest unknown"${RESET}`);
         return;
@@ -9623,6 +9853,143 @@ async function runHandoffCommand(argv) {
     }
     throw new Error('handoff needs a kind: `vidfarm handoff image --theme "…" --items "a,b,c"` (free web image gen → sticker pack) or `vidfarm handoff raws --keywords "…"` (manual clip sourcing).');
 }
+// `vidfarm consult [step]` — the consultation / brainstorm chain, run KEYLESS
+// and LOCAL. The cloud version of each step is a `brainstorm/*` primitive that
+// needs a provider key or wallet credits; this prints the identical prompt for
+// the agent in this terminal to answer itself, for $0.
+async function runConsultCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            offer: { type: "string" },
+            message: { type: "string" },
+            video: { type: "string" },
+            count: { type: "string" },
+            dir: { type: "string" },
+            "problem-awareness": { type: "string" },
+            "solution-awareness": { type: "string" },
+            refs: { type: "boolean", default: false },
+            short: { type: "boolean", default: false }
+        }
+    });
+    const json = Boolean(parsed.values.json);
+    const dir = parsed.values.dir ?? ".";
+    const rawStep = (parsed.positionals[0] ?? "").trim();
+    // Bare `vidfarm consult` = the map, not a wall of prompt. A director who says
+    // "give me a consultation" needs to see the four steps and where they land.
+    if (!rawStep) {
+        const plan = planConsultation(dir);
+        const context = consultContextState(dir);
+        if (json)
+            return printJson({ ok: true, dir: path.resolve(dir), plan, context });
+        console.log(`${BOLD}Vidfarm consultation${RESET} ${DIM}— keyless and local. No provider key, no wallet, no network.${RESET}`);
+        console.log(`${DIM}Each step prints the same prompt the cloud brainstorm primitive would send. YOU answer it.${RESET}\n`);
+        for (const row of plan) {
+            const mark = row.done ? `${GREEN}✓${RESET}` : `${DIM}·${RESET}`;
+            console.log(`  ${mark} ${row.command.padEnd(28)} ${DIM}→ ${row.artifact}${row.done ? " (exists)" : ""}${RESET}`);
+        }
+        const first = plan.find((row) => !row.done) ?? plan[0];
+        console.log(`\n  ${context.exists ? `${GREEN}✓${RESET}` : `${DIM}·${RESET}`} ${"saved answers".padEnd(28)} ${DIM}→ ${context.file}${context.exists ? " (read it before you ask anything)" : " (written by the first step)"}${RESET}`);
+        console.log(`\nStart here: ${BOLD}${first.command}${RESET}`);
+        console.log(`${DIM}In a hurry: vidfarm consult coldstart --short  (6 fixed questions instead of the full interview)${RESET}`);
+        console.log(`${DIM}Run every step from ONE working folder (--dir), so the artifacts and ${context.file} stay together.${RESET}`);
+        console.log(`${DIM}Also: vidfarm consult placement --video <path|url>  (native product placement inside an existing video)${RESET}`);
+        return;
+    }
+    const step = resolveConsultStep(rawStep);
+    if (!step) {
+        throw new Error(`Unknown consult step "${rawStep}". Use one of: coldstart, awareness, angles, hooks, placement — or bare \`vidfarm consult\` for the map.`);
+    }
+    // coldstart is the step that PRODUCES the offer document, so it is the only
+    // one that runs without one.
+    let offer = "";
+    if (step !== "coldstart") {
+        const inline = parsed.values.offer?.trim();
+        // --offer takes either a path or the offer text itself. A real file wins; a
+        // string that READS like a path but resolves to nothing is an error, never
+        // offer text — otherwise a typo silently consults on the filename.
+        if (inline && !resolveOfferPath(dir, inline) && !looksLikeOfferPath(inline)) {
+            offer = inline;
+        }
+        else {
+            const found = findOfferFile(dir, inline);
+            if ("error" in found) {
+                throw new Error(found.error);
+            }
+            offer = found.text;
+        }
+        if (offer.trim().length < 10) {
+            throw new Error("The offer text is too thin to consult on (under 10 characters). Fill in OFFER.md, or pass --offer \"<a paragraph about the offer>\".");
+        }
+    }
+    const awarenessValue = (raw, allowed, flag) => {
+        if (raw === undefined)
+            return undefined;
+        const value = raw.trim().toLowerCase();
+        if (!allowed.includes(value)) {
+            throw new Error(`${flag} must be one of: ${allowed.join(", ")}.`);
+        }
+        return value;
+    };
+    // --short is a fixed six-question set, so it belongs to the interview only.
+    // On the other steps the equivalent knob is --count, and silently ignoring the
+    // flag would let a director believe they ran a shorter angles pass.
+    const short = Boolean(parsed.values.short);
+    if (short && step !== "coldstart") {
+        throw new Error(`--short is the short-form interview, so it only applies to \`vidfarm consult coldstart\`. For a shorter ${step} run, use --count.`);
+    }
+    const countRaw = parsed.values.count;
+    const range = consultCountRange(step);
+    if (!range && countRaw !== undefined) {
+        throw new Error("consult awareness takes no --count — it returns one markdown recommendation, not a list.");
+    }
+    if (short && countRaw !== undefined) {
+        throw new Error("--short is a fixed six-question set, so it takes no --count. Drop one of the two.");
+    }
+    const count = countRaw === undefined ? defaultConsultCount(step) : Number(countRaw);
+    if (range && (!Number.isInteger(count) || count < range.min || count > range.max)) {
+        throw new Error(`--count for ${step} must be a whole number between ${range.min} and ${range.max} (the cloud primitive enforces the same range).`);
+    }
+    const brief = buildConsultBrief({
+        step,
+        offer,
+        userMessage: parsed.values.message,
+        videoRef: parsed.values.video,
+        count,
+        problemAwareness: awarenessValue(parsed.values["problem-awareness"], ["problem_unaware", "problem_aware"], "--problem-awareness"),
+        solutionAwareness: awarenessValue(parsed.values["solution-awareness"], ["solution_unaware", "solution_aware"], "--solution-awareness"),
+        references: parsed.values.refs ? readSellingReferences() : undefined,
+        dir,
+        short
+    });
+    if (json) {
+        return printJson({ ok: true, keyless: true, cost_usd: 0, artifact_name: CONSULT_ARTIFACTS[step], ...brief });
+    }
+    console.log(formatConsultBrief(brief, { bold: BOLD, dim: DIM, reset: RESET }));
+}
+// The two selling documents the CLOUD prompt inlines. Only read on --refs: they
+// are ~34KB together, which is real context spend for the local agent.
+function readSellingReferences() {
+    const read = (name) => {
+        for (const candidate of resolveRootFileCandidates(path.join("src", "assets", name))) {
+            try {
+                return readFileSync(candidate, "utf8");
+            }
+            catch {
+                continue;
+            }
+        }
+        return undefined;
+    };
+    const hooks = read("SELLING_WITH_HOOKS.md");
+    const awareness = read("SELLING_AWARENESS_STAGES.md");
+    if (!hooks && !awareness) {
+        throw new Error("--refs needs the bundled selling references (src/assets/SELLING_*.md) and neither was found in this install. Drop --refs to use the skill-pack reference instead.");
+    }
+    return { hooks, awareness };
+}
 async function runProviderKeysCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: false, options: commonOptions() });
     const ctx = commonContext(parsed.values);
@@ -9635,7 +10002,7 @@ async function runAddProviderKeyCommand(argv) {
     const provider = parsed.positionals[0];
     const secret = parsed.positionals[1];
     if (!provider || !secret)
-        throw new Error("add-provider-key requires <provider> <secret> (provider: openai|gemini|openrouter|perplexity|nvidia|elevenlabs|pixabay).");
+        throw new Error("add-provider-key requires <provider> <secret> (provider: openai|gemini|openrouter|perplexity|nvidia|elevenlabs|pixabay|iconscout). IconScout packs BOTH values into one secret: <client_id>:<client_secret>.");
     const ctx = commonContext(parsed.values);
     const result = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/user/me/provider-keys", auth: ctx.auth, body: { provider, secret, label: parsed.values.label } });
     assertApiOk(result, "add-provider-key");
@@ -11087,7 +11454,10 @@ async function runQaCommand(argv) {
             "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 }
+            "no-regime": { type: "boolean", default: false },
+            // Revision governor — the base case that stops a qa→fix→qa loop.
+            "max-revisions": { type: "string" },
+            "reset-revisions": { type: "boolean", default: false }
         }
     });
     const target = parsed.positionals[0];
@@ -11095,6 +11465,19 @@ async function runQaCommand(argv) {
         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");
+    // Count this pass BEFORE anything is printed: at the limit qa withholds the
+    // finding list, because handing an agent a fresh list of things to fix is the
+    // fuel the revise-forever loop runs on.
+    const maxRevisionsRaw = parsed.values["max-revisions"];
+    const maxRevisions = maxRevisionsRaw !== undefined ? Number(maxRevisionsRaw) : undefined;
+    if (maxRevisionsRaw !== undefined && !Number.isFinite(maxRevisions)) {
+        throw new Error(`--max-revisions must be a number (0 disables the limit), got "${maxRevisionsRaw}".`);
+    }
+    const governor = recordQaPass(htmlPath, html, {
+        max: maxRevisions,
+        reset: Boolean(parsed.values["reset-revisions"]),
+        now: new Date().toISOString()
+    });
     let report = qaCompositionHtml(html);
     // Harness resolution, in precedence order: explicit --harness flags
     // (stackable) → VIDFARM_HARNESS (a default for a whole scripting run) → the
@@ -11130,11 +11513,31 @@ async function runQaCommand(argv) {
         watch_the_video: watchTheVideoDirective(pastablePath(workDir), render ? pastablePath(render) : null)
     };
     if (parsed.values.json) {
-        printJson(report);
+        printJson({ ...report, revision_governor: governor });
         if (!report.ok && parsed.values.strict)
             process.exitCode = 1;
         return;
     }
+    // ---- the base case ------------------------------------------------------
+    // Findings are withheld, not deleted: --max-revisions raises the ceiling and
+    // --reset-revisions starts the count over, both printed here so nothing is
+    // hidden from a human who genuinely wants another pass.
+    if (governor.limit_reached) {
+        const issues = report.errors.length + report.warnings.length;
+        console.log("");
+        console.log(`${RED}${BOLD}■ REVISION LIMIT REACHED — STOP REVISING THIS VIDEO.${RESET}`);
+        console.log(`  ${DIM}${governor.revisions} revision(s) of ${path.basename(htmlPath)}, limit ${governor.max}.${RESET}`);
+        console.log("");
+        console.log(`  ${issues === 0 ? "No findings this pass." : `${issues} finding(s) withheld.`} ${DIM}Past the limit, what's left is nearly always taste, not a defect — and re-running qa to find more is how an agent loops forever.${RESET}`);
+        console.log("");
+        console.log(`  ${BOLD}Do one of these instead:${RESET}`);
+        console.log(`  ${DIM}1.${RESET} Ship it. ${DIM}Watch the render once, then publish.${RESET}`);
+        console.log(`  ${DIM}2.${RESET} Ask the human. ${DIM}Show them the video and let them call it.${RESET}`);
+        console.log(`  ${DIM}3.${RESET} Genuinely need another pass? ${BOLD}vidfarm qa ${pastablePath(path.dirname(htmlPath))} --max-revisions ${governor.max + 1}${RESET}${DIM} (or --reset-revisions to start over).${RESET}`);
+        console.log("");
+        console.log(formatWatchTheVideoNotice(report.watch_the_video, { yellow: YELLOW, dim: DIM, reset: RESET, bold: BOLD }));
+        return;
+    }
     const body = formatQaReport(report, { red: RED, yellow: YELLOW, green: GREEN, dim: DIM, reset: RESET });
     if (body)
         console.log(body);
@@ -11164,6 +11567,10 @@ async function runQaCommand(argv) {
         console.log(`${DIM}Checked mechanics only — nothing here grades the hook, the loop, the payoff, or the bait.${RESET}`);
         console.log(`${DIM}Structure: vidfarm harness show hooks   ·   grade this video: vidfarm qa <dir> --harness short-form${RESET}`);
     }
+    if (!governor.disabled && governor.revisions > 0) {
+        const left = governor.max - governor.revisions;
+        console.log(`${DIM}Revision ${governor.revisions} of ${governor.max}${left === 1 ? " — one more, then qa stops and you ship or ask the human." : "."}${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)
@@ -11642,6 +12049,131 @@ function devcliVersion() {
  * genuinely offline. Every surface below says so rather than letting an offline
  * read imply an offline entitlement.
  */
+/**
+ * `vidfarm ideas` — the content-ideas angle bank, offline and free.
+ *
+ * WHY A COMMAND AND NOT JUST A DOC: "give me content ideas for <offer>" is one
+ * of the most common asks a director makes, and the honest answer is volume —
+ * 20+ titled ideas, each a DIFFERENT subject rather than 20 rewrites of one.
+ * The bank of 50 reusable frames is what makes that possible without an AI call
+ * and without inventing a list from memory (which drifts, repeats, and forgets
+ * the contrast/pivot shapes entirely). The frames are parsed straight out of
+ * the bundled reference, so the CLI and the skill can never disagree.
+ *
+ * It deliberately does NOT generate the titles: filling a frame needs the
+ * director's offer, audience and vocabulary, which is the agent's job (or the
+ * human's). This hands over the instrument and the loop, for $0.
+ */
+/**
+ * Join a frame to the director's topic with the connector English wants.
+ * "the history of" + X is "the history of X", but "the biggest mistakes" + X is
+ * "the biggest mistakes IN X" and "then vs now" + X is "X: then vs now". Naive
+ * concatenation produces lines an agent then has to un-mangle, which defeats
+ * the point of handing it a starter at all.
+ */
+function joinIdeaFrame(frame, topic) {
+    const lower = frame.toLowerCase();
+    if (/\bof$/.test(lower))
+        return `${frame} ${topic}`;
+    if (lower.includes(" vs "))
+        return `${topic}: ${frame}`;
+    if (/^(the biggest|the chain reaction)/.test(lower) || lower.startsWith("one "))
+        return `${frame} in ${topic}`;
+    if (/^(the hidden side|the untold story|the complete|the rabbit hole)/.test(lower))
+        return `${frame} of ${topic}`;
+    return `${frame} — ${topic}`;
+}
+async function runIdeasCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean", default: false },
+            family: { type: "string" },
+            topic: { type: "string" },
+            count: { type: "string" },
+            families: { type: "boolean", default: false }
+        }
+    });
+    const json = Boolean(parsed.values.json);
+    const topic = String(parsed.values.topic ?? parsed.positionals.join(" ") ?? "").trim();
+    const { frames, families } = loadIdeaBank();
+    if (!frames.length)
+        throw new Error("No bundled content-ideas reference found next to this devcli install. Fetch it with `vidfarm skills add vidfarm`.");
+    if (parsed.values.families) {
+        if (json)
+            return printJson({ ok: true, families, frames: frames.length });
+        console.log(`${DIM}${frames.length} frames in ${families.length} families:${RESET}`);
+        for (const family of families) {
+            console.log(`  ${GREEN}${family.padEnd(22)}${RESET} ${DIM}${frames.filter((entry) => entry.family === family).length} frames${RESET}`);
+        }
+        console.log(`\n${DIM}vidfarm ideas --family contrast   ·   vidfarm ideas --topic "<your offer>"${RESET}`);
+        return;
+    }
+    const familyFilter = String(parsed.values.family ?? "").trim().toLowerCase();
+    let picked = familyFilter ? frames.filter((entry) => entry.family.toLowerCase().includes(familyFilter)) : frames;
+    if (familyFilter && !picked.length) {
+        throw new Error(`No family matches "${familyFilter}". Families: ${families.join(", ")} (see \`vidfarm ideas --families\`).`);
+    }
+    const requested = Number(parsed.values.count ?? (topic ? 20 : picked.length));
+    const limit = Number.isFinite(requested) && requested > 0 ? Math.min(requested, picked.length) : picked.length;
+    if (limit < picked.length) {
+        // Spread the sample across families rather than truncating the list — a
+        // top-N slice would hand back eight arc frames and no contrast frames, and
+        // the variety across shapes is the entire value of the bank.
+        const buckets = families.map((family) => picked.filter((entry) => entry.family === family)).filter((bucket) => bucket.length);
+        const spread = [];
+        for (let round = 0; spread.length < limit; round += 1) {
+            let addedThisRound = false;
+            for (const bucket of buckets) {
+                if (round >= bucket.length)
+                    continue;
+                spread.push(bucket[round]);
+                addedThisRound = true;
+                if (spread.length >= limit)
+                    break;
+            }
+            if (!addedThisRound)
+                break;
+        }
+        picked = spread;
+    }
+    if (json) {
+        return printJson({
+            ok: true,
+            source: "bundled",
+            offline: true,
+            topic: topic || null,
+            total_frames: frames.length,
+            families,
+            frames: picked.map((entry) => ({ frame: entry.frame, family: entry.family, starter: topic ? joinIdeaFrame(entry.frame, topic) : null })),
+            method: "references/content-ideas.md"
+        });
+    }
+    console.log(`${BOLD}Content ideas — the angle bank${RESET} ${DIM}(${picked.length} of ${frames.length} frames · offline, free, no AI call)${RESET}`);
+    if (topic)
+        console.log(`${DIM}Topic: ${RESET}${topic}`);
+    console.log("");
+    let group = "";
+    for (const entry of picked) {
+        if (entry.family !== group) {
+            group = entry.family;
+            console.log(`  ${BOLD}${group}${RESET}`);
+        }
+        console.log(topic ? `    ${GREEN}${joinIdeaFrame(entry.frame, topic)}${RESET}` : `    ${GREEN}${entry.frame}${RESET}`);
+    }
+    console.log("");
+    if (topic) {
+        console.log(`${DIM}Those are FRAMES filled with your topic, not finished ideas. Sharpen each into a real title${RESET}`);
+        console.log(`${DIM}("The one pricing mistake that killed our first 400 orders"), then write hook/loop/payoff/bait.${RESET}`);
+    }
+    else {
+        console.log(`${DIM}Pour ONE topic into a frame to get a video: 'the rise of' + your niche. Add --topic "<offer>" to see it.${RESET}`);
+    }
+    console.log(`${DIM}Method + frame→format notes: vidfarm skill show content-ideas   ·   families: vidfarm ideas --families${RESET}`);
+    console.log(`${DIM}Never ship a frame as a hook — the four charges still apply: vidfarm skill show hooks${RESET}`);
+    console.log(`${DIM}Producing the whole set is a batch: vidfarm skill show bulk (one frame per video).${RESET}`);
+}
 async function runSkillDocsCommand(sub, argv) {
     const parsed = parseArgs({
         args: argv,
@@ -11682,9 +12214,37 @@ async function runSkillDocsCommand(sub, argv) {
         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 === "topics" || sub === "topic" || sub === "craft") {
+        // The spoken-name index. `skill ls` answers "what files exist"; this answers
+        // "what does this thing KNOW", which is the question an agent actually has.
+        const topics = listPackTopics();
+        if (json)
+            return printJson({ ok: true, pack, source: "bundled", offline: true, topics }), true;
+        console.log(`${DIM}Craft topics in the bundled ${pack} pack — say the name, get the section (offline, no account):${RESET}`);
+        for (const entry of topics) {
+            const where = entry.heading ? `${entry.doc} § ${entry.heading}` : entry.doc;
+            console.log(`  ${GREEN}${entry.topic.padEnd(20)}${RESET} ${entry.blurb}`);
+            console.log(`  ${" ".repeat(20)} ${DIM}${where}${RESET}`);
+        }
+        console.log(`\n${DIM}vidfarm skill show <topic>   ·   the 50-frame idea bank has its own command: vidfarm ideas${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).');
+            throw new Error('skill show requires a file or topic: `vidfarm skill show references/primitives.md` (shorthand like "primitives", or a topic like "meme-recaption" — `vidfarm skill topics`).');
+        // A spoken topic wins over fuzzy file matching: "meme-recaption" should print
+        // the 25-line section, not the 650-line reference it lives in.
+        const topic = resolvePackTopic(ref);
+        if (topic) {
+            const read = readPackTopic(topic, pack);
+            if (json) {
+                return printJson({ ok: true, pack, topic: topic.topic, path: read.doc.rel, heading: read.heading ?? null, whole_file: read.whole, source: "bundled", contents: read.contents }), true;
+            }
+            process.stdout.write(read.contents.endsWith("\n") ? read.contents : `${read.contents}\n`);
+            if (!read.whole)
+                console.log(`\n${DIM}— one section of ${read.doc.rel}. Whole file: vidfarm skill show ${read.doc.rel}${RESET}`);
+            return true;
+        }
         let resolved;
         try {
             resolved = readPackDoc(ref, pack);