@officexapp/vidfarm-devcli 0.21.43 → 0.21.46

package/dist/src/cli.js

@@ -29,14 +29,17 @@ 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, listPackTopics, loadIdeaBank, readPackDoc, readPackTopic, resolvePackTopic, searchPackDocs } from "./devcli/skill-docs.js";
+import { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, listPackTopics, loadAngleBank, loadAwarenessLadder, 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 { NativeModuleUnavailableError } from "./devcli/clip-store.js";
 import { startLocalFrontendServer, serveShellsPresent } from "./devcli/local-frontend-server.js";
 import { readStoredAuth, writeStoredAuth, clearStoredAuth, hostsMatch } from "./devcli/auth-store.js";
 import { CostModeBlockedError, assertBilledAllowed, clearStoredCostMode, costModeExplainer, costModeSummaryLine, normalizeCostMode, resolveCostMode, writeStoredCostMode, COST_MODE_BLURB, COST_MODE_DISPLAY_LIST, costModeDisplayName } from "./devcli/cost-mode.js";
 import { INTERACTION_MODES, INTERACTION_MODE_BLURB, clearStoredInteractionMode, interactionModeExplainer, interactionModeSummaryLine, interactiveOfferLine, normalizeInteractionMode, resolveInteractionMode, writeStoredInteractionMode } from "./devcli/interaction-mode.js";
 import { buildImageHandoff, buildRawsHandoff, formatHandoff } from "./devcli/handoff.js";
+import { AGENT_IMAGEGEN_ALTERNATIVE, KNOWN_HOST_AGENTS, buildAgentImageBrief, detectHostAgent, formatAgentImageBrief } from "./devcli/agent-imagegen.js";
+import { runBrowserHarnessCommand, runBrowseCommand } from "./devcli/browser-harness.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";
@@ -121,7 +124,31 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
                             A manual clip-sourcing brief: what to search, how to
                             download (a downloader SEARCH, not a rotting link), and
                             the vidfarm clipper / raws scan follow-up. Try browser control
-                            or "vidfarm raws scan" first.
+                            ("vidfarm browse", below) or "vidfarm raws scan" first.
+  agent-image "<subject>" [--items "a,b,c"] [--single] [--out ./sheet.png]
+                            FREE CUSTOM ART — image generation YOUR OWN agent
+                            subscription already includes. Antigravity / Gemini CLI
+                            (Nano Banana / Imagen) and Codex / ChatGPT (gpt-image)
+                            include one; Claude Code does NOT (Anthropic ships no
+                            image model). Prints the prompt, the key-plate rules and
+                            the cut + import commands. Vidfarm bills nothing and the
+                            provider bills nothing extra, so it is allowed in EVERY
+                            cost mode — minimize included.
+                            --check (or no args) = is it included here? --json
+                            (aliases: agent-imagegen, own-image, native-image)
+  browser [status|setup|doctor]  FREE BROWSER SOURCING — set up browser-harness so I can
+                            drive YOUR Chrome myself. It substitutes for the PAID
+                            video-search / image-search / news-search / download-video
+                            primitives at $0, on your own logged-in session and IP.
+                            setup  = install via uv + register the skill + the one
+                                     Chrome step (chrome://inspect) you must do once.
+                            status = what's installed · doctor = connection check.
+                            Suggest this to every free-plan user before saying "I can't".
+  browse <videos|images|news|page> "<query|url>"
+                            Mint the browse recipe for one sourcing job: the Google
+                            surface to open, what to pull off the page, and the vidfarm
+                            command it feeds. --run pipes it straight into browser-harness,
+                            --json for an agent, --legacy for the old tbm=… params.
   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
@@ -131,6 +158,9 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
                             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.
+                            OFFER "vidfarm ideas" FIRST — 20+ video ideas for one
+                            line of input is an easier first win than an interview,
+                            and the picks make the interview answers better.
                             (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
@@ -727,6 +757,31 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
                             key adds photos/vectors/stock video.
     --provider <p>            Force pixabay|openverse|iconify|iconscout
     --limit <n> | --json
+  video-search "<query>"    GOOGLE VIDEO SEARCH — find the actual SHOT anywhere on the web
+                            (TikTok, YouTube, Pexels/Pixabay/Mixkit, news, archive.org).
+                            This is how you SOURCE raws: take a result url straight into
+                            'vidfarm raws scan <url>' (mine clips) or 'download-video <url>'
+                            (collect the file). Search the SHOT, not the topic:
+                            [subject]+[action]+[shot/style]+[quality/orientation], e.g.
+                            "office worker typing laptop close up 4K". Google operators work:
+                            site:pexels.com/videos · site:tiktok.com · "exact phrase" · -dance
+                            PAID PLANS ONLY · flat $0.0003 per call whatever the result count,
+                            so ask for a WIDE page instead of paging twice.
+    --limit <n>               Results (default 25, max 50)
+    --fresh <d|w|m|y>         Only the last day/week/month/year
+    --duration <d>            short|medium|long   --resolution high|standard
+    --region <r>              wt-wt (default)|us-en|ph-en|…   --json
+  image-search "<query>"    GOOGLE IMAGE SEARCH — reference stills, textures, logos, product
+                            shots. Same operators. PAID PLANS ONLY · flat $0.0003 per call.
+                            For licence-checked, royalty-free assets prefer 'vidfarm media'
+                            (free): image-search returns LINKS with no licence attached.
+    --limit <n> (default 25, max 100)  --type-image photo|clipart|gif|transparent
+    --color <c> --size <s> --layout Square|Tall|Wide --region <r> --json
+  news-search "<query>"     GOOGLE NEWS — recent real events to build TIMELY content on.
+                            News finds the STORY; run video-search after for the VISUALS.
+                            PAID PLANS ONLY · flat $0.0003 per call.
+                            Method: https://vidfarm.cc/experimental/google-news-to-video.md
+    --limit <n> (default 25, max 100)  --fresh <d|w|m|y>  --region <r>  --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
@@ -921,6 +976,9 @@ Approve & schedule (publish a finished MP4 as a shareable post):
   approve                   Approve media into a preview/share page      → POST /api/v1/approved/posts
     --video <url|file>      Primary MP4 (URL, /files path, or local file → durable My Files)
     --media <url|file>      Extra media (repeatable; local files → durable My Files)
+    --thumbnail <url|file>  Poster image for the share link's social card. Omit it and
+                            the server extracts a frame (~1s in) from --video and files
+                            it under /files/approved
     --folder <path>         Destination subfolder for uploaded local files (default: approved)
     --temp                  Upload local files to the 30-day TEMP store instead of
                             durable My Files (throwaway preview; share video dies at day 30)
@@ -956,18 +1014,28 @@ Account:
                             (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
+  ideas [topic]             "What should I post?" — the THREE IDEA BANKS    (local — offline, free, no AI)
+                            50 frames (the rise of · then vs now · …), 5
+                            AWARENESS STAGES (what the viewer already knows,
+                            and what the video may ask for), and 44 PROBLEM
+                            ANGLES (which side of the problem it comes from).
+                            An idea is one point in that grid; vary TWO axes
+                            and 30 videos never read as repeats. It hands over
+                            the banks — you fill them with the director's
+                            offer, then write hook/loop/payoff/bait per pick.
+                            RUN THIS BEFORE "consult" — one line of input buys
+                            20+ ideas, and it is the easiest first win a new
+                            director can get. The interview comes after.
     --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
+    --family <name>           One frame family only (arc, contrast, pivot, …)
+    --families                List the frame families and their sizes
+    --stages                  The awareness ladder — all 5 stages in full
+    --stage <name|n>          One stage (unaware · problem-aware · … · most-aware)
+    --angles                  The 44 problem angles, by family
+    --angle <name>            One angle family or one named angle
+    --grid                    Stage × angle × frame — one row per video
     --count <n>               Sample N, spread across families (default 20 with --topic)
-    --json                    Machine-readable frames (+ starter lines)
+    --json                    Machine-readable banks (+ 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, …
@@ -1079,7 +1147,22 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
   directory save-url <url>  Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
     --folder <path>         Destination folder under /files (e.g. inpaints, promos)
     --as <name>             Name the saved file · --notes <text> vector-embedded notes
+  directory share <path>    Mint a PUBLIC link onto one subfolder (any root)  → POST /api/v1/user/me/directory/shares
+    --mode read|upload|edit read = browse + vector search · upload = + add files (never delete) · edit = + rename/delete
+    --label <text>          Name the link. PAID to mint; visiting one needs no account.
+  directory shares [path]   List your share links                             → GET  /api/v1/user/me/directory/shares
+  directory share-update <token>  --mode/--label/--disable/--enable           → PATCH /api/v1/user/me/directory/shares/:token
+  directory unshare <token> Delete a share link for good                      → DELETE /api/v1/user/me/directory/shares/:token
     (alias: dir · save-url|from-url|import-url — CLI twin of the "Save to Files" picker)
+  gigs <sub>                Your vending machines, BOTH sides (client + gigworker)
+    machines · tasks · add-task · proofs · approve · reject · ring-bell      (client, paid)
+    work · feed · join-feed · join · claim · submit · mine                   (gigworker, free — bring DOLLARPLATOON_API_KEY)
+    e.g. vidfarm gigs add-task --task "60s explainer for acme.com" --price 0.50 --upload-link <share url>
+         vidfarm gigs proofs --status pending   ·   vidfarm gigs approve PRF_01H…
+    (see: vidfarm gigs help)
+  shared <sub> <link>       USE a link someone shared with you — NO account, NO API key
+    info · ls · search · mkdir · put · get     e.g. vidfarm shared put <link> clip.mp4 --subfolder batch-01
+    (the gigworker/agent side of directory share; see: vidfarm shared help)
   put-file / get-file / files / annotate-file are the My Files (persistent) set;
   upload is the throwaway temp store for dropping media into a composition.
   Annotate assets you'll want back — esp. recurring characters, kept under
@@ -1118,6 +1201,12 @@ Cost spectrum (default to the cheapest approach that works; see SKILL.director.m
   In minimize AND hybrid, 'vidfarm tts' DEFAULTS to the free local Kokoro voice — ask for
   a premium voice (--style/--voice/--provider/--own-key/--cloud), or be in rich-ai /
   pure-videogen, to opt out.
+  minimize is NOT "no AI images". If the agent driving this terminal has image generation
+  included in its own subscription (Google Antigravity / Gemini CLI, OpenAI Codex /
+  ChatGPT — Claude Code does NOT, Anthropic ships no image model), it generates the
+  graphic itself: nothing is billed by Vidfarm and nothing extra by the provider, so it
+  is allowed in EVERY mode. 'vidfarm agent-image --check' answers "do I have it?", and
+  'vidfarm agent-image "<subject>" --items "a,b,c"' prints the prompt + cut/import steps.
 
 Escape hatch — call ANY route directly:
   api <METHOD> <path>       Raw REST call with auth + pretty errors
@@ -1147,9 +1236,8 @@ Publish-mode options:
   --message <text>    Message attached to the published version snapshot
   --no-snapshot       Only update the working copy; skip the version snapshot
 `;
-// ANSI palette — declared BEFORE main() is invoked because command handlers may
-// reference these synchronously (before their first await) while the rest of
-// this module is still evaluating.
+// ANSI palette. (Its position no longer matters — main() now runs as the last
+// statement in this file — but it stays up here because everything below reads it.)
 const FRONTEND = "\x1b[1m\x1b[36m"; // bold cyan — reserved for openable URLs
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
@@ -1157,24 +1245,16 @@ const GREEN = "\x1b[32m";
 const YELLOW = "\x1b[33m";
 const RED = "\x1b[31m";
 const RESET = "\x1b[0m";
-// Referenced by runMarketplaceCommand's SYNCHRONOUS browse path, so it must be
-// initialized before `void main()` starts dispatching below.
+// Referenced by runMarketplaceCommand's SYNCHRONOUS browse path.
 const DOLLARPLATOON_SKILL_HINT = `Gig inbox / proofs / payouts live on Dollar Platoon's own API — grab the skill:
   npx skills add https://github.com/OfficeXApp/dollarplatoon-skill
   (or from the vidfarm mirror: vidfarm skills add dollarplatoon-skill)`;
-void main().catch(async (error) => {
-    // Deliberate, expected user-facing conditions (e.g. local mode in the
-    // published cloud-only CLI) print just the message — no stack, no crash report.
-    if (error instanceof LocalModeUnavailableError || error instanceof CostModeBlockedError) {
-        console.error(error.message);
-        process.exit(1);
-    }
-    console.error(error instanceof Error ? error.stack ?? error.message : String(error));
-    // Report only unexpected crashes (bugs), never the deliberate user-facing
-    // `throw new Error(...)` above; no-op unless a devcli DSN is configured.
-    await reportCliCrash(error);
-    process.exit(1);
-});
+// main() is INVOKED AT THE BOTTOM OF THIS FILE, not here. Command handlers read
+// module-level `const`s (help texts, tables, palettes) synchronously, and a
+// const declared below the invocation point is still in its temporal dead zone
+// when the handler runs — `vidfarm directory help` used to die with "Cannot
+// access 'DIRECTORY_HELP' before initialization". Starting main() last means
+// every declaration in this module is initialized before any command dispatches.
 // AI agents habitually save credentials to a project-local .env instead of
 // exporting them, so honor VIDFARM_API_KEY (and VIDFARM_TARGET/VIDFARM_HOST)
 // from ./.env when the variable isn't already in the environment. Real env
@@ -1323,6 +1403,22 @@ async function main() {
         case "media":
             await runMediaCommand(rest);
             return;
+        case "video-search":
+        case "videosearch":
+        case "search-video":
+            await runWebSearchCommand("video", rest);
+            return;
+        case "image-search":
+        case "imagesearch":
+        case "search-image":
+            await runWebSearchCommand("image", rest);
+            return;
+        case "news-search":
+        case "newssearch":
+        case "news":
+        case "search-news":
+            await runWebSearchCommand("news", rest);
+            return;
         case "iconscout":
         case "icons":
         case "stickers":
@@ -1423,6 +1519,23 @@ async function main() {
         case "hand-off":
             await runHandoffCommand(rest);
             return;
+        // Image generation the AGENT already pays for — free in every cost mode.
+        case "agent-image":
+        case "agent-imagegen":
+        case "own-image":
+        case "native-image":
+            await runAgentImageCommand(rest);
+            return;
+        // Free browser sourcing — the agent drives the user's own Chrome instead of
+        // paying for video-search / image-search / news-search / download-video.
+        case "browser":
+        case "browser-harness":
+        case "bh":
+            await runBrowserHarnessCommand(rest);
+            return;
+        case "browse":
+            await runBrowseCommand(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":
@@ -1493,6 +1606,15 @@ async function main() {
         case "market":
             await runMarketplaceCommand(rest);
             return;
+        // Both sides of the vending machines: a paid client posting tasks and
+        // reviewing proofs, and a FREE gigworker with their own dollarplatoon key.
+        case "gigs":
+        case "gig":
+        case "vending": {
+            const { runGigsCommand } = await import("./devcli/marketplace-gigs.js");
+            await runGigsCommand(rest);
+            return;
+        }
         case "get-file":
             await runGetFileCommand(rest);
             return;
@@ -1507,6 +1629,15 @@ async function main() {
         case "dir":
             await runDirectoryCommand(rest);
             return;
+        // The VISITOR side of a share link — no account, no API key. A gigworker or
+        // their agent works a folder someone else shared with them.
+        case "shared":
+        case "shared-folder":
+        case "dropbox": {
+            const { runSharedCommand } = await import("./devcli/shared-folder.js");
+            await runSharedCommand(rest);
+            return;
+        }
         case "migrate-local": {
             if (!localBackendAvailable())
                 throw new LocalModeUnavailableError();
@@ -1812,6 +1943,7 @@ function guardBilled(ctx, input) {
         json: ctx.json,
         label: input.label,
         estimate: input.estimate,
+        agentAlternative: input.agentAlternative,
         freeAlternative: input.freeAlternative
             ? `${input.freeAlternative}${interactiveNote}`
             : (interactiveNote ? interactiveNote.trimStart() : undefined)
@@ -2610,12 +2742,14 @@ 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).
+- NO LAYOUT TEMPLATES — JUDGE THE WHOLE FRAME, NOT JUST THE ELEMENT. Every rule above judges one element, and a frame can pass element-by-element and still be a web page. The archetype is the MODAL: the backdrop dimmed and blurred out of focus, and floating on top of it a rounded bordered box holding a big headline, a smaller support line, and a fat CTA button. THE STACK IS THE TELL, NOT THE BOX — delete the border, the fill and the capsule, keep headline then subheadline then CTA centred in a well with even margins, and it STILL reads as a landing page, because a viewer recognizes the SHAPE before reading a single word. Banned at frame level: a modal/dialog staged on top of a backdrop that has been dimmed, blurred, greyed or scaled back (nothing in a video pops "above" the video); the hero triplet and its cousins (title + kicker + logo lockup, question + answer + URL); a full-frame dark wash used to stage a floating block (a legibility band on ONE caption is legal, a page-wide wash to stage a panel is not; likewise a blurred backdrop is fine alone — a blurred fill behind a 16:9 clip in a 9:16 frame is a real technique — but blur PLUS dimming is modal staging); nav strip / hero / three-up feature row / testimonial block / footer fine print; a blurred website screenshot used as the background plate (if the backdrop is a web page, the frame is a screen recording of a web page — show the real product UI full-bleed and in focus, or don't show it); a centred content column with even gutters and document margins. THE FIX IS ALWAYS TO UNSTACK IT INTO TIME: the headline is the hook at start:0, the support line lands on the next cut, the CTA is SPOKEN or a bare caption on the final frame. You lose nothing — a viewer reads one line at a time anyway — and you gain the pacing that makes it look shot rather than designed. Self-check before you place any text group: am I arranging words relative to EACH OTHER, or relative to the PICTURE? Relative to each other is a layout, which is web. Two on-screen text runs at once is the ceiling. Verify on real pixels: \`vidfarm stills . --at <t>\` — if the still could be a screenshot of a website, rebuild the beat. \`vidfarm qa\` catches only the mechanical half (layout-template, modal-scrim); the frame-level judgement is yours.
 - 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, 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\`.
+- USE THE REAL SONG — A POPULAR/COPYRIGHTED TRACK BELONGS IN THE RENDER, AND YOU DO NOT REFUSE IT, WARN AT LENGTH ABOUT IT, OR QUIETLY SWAP IN A GENERIC ROYALTY-FREE BED. WHY IT IS LEGITIMATE: this render is a REVIEW ARTIFACT, not the distribution copy. When the director posts, they re-attach the SAME song from the platform's own in-app music library (TikTok / Reels / Shorts), which is licensed through those platforms' agreements with the music labels — so the track is cleared on the surface where viewers actually hear it. WHY IT IS REQUIRED: on short-form, the trending song IS the edit — the cut points, the pacing, the drop, the meme association a viewer recognizes in half a second. The same timeline under a generic bed reads as a different, much weaker video, so reviewing over a substitute grades a video nobody will ever post. Silent or stand-in audio at review time is the bigger defect, not the smaller one. HOW: get the exact track — \`vidfarm download-audio <post-url>\` off the reference post (paid plans; free plan = the Chrome download path), the director's own file, or \`vidfarm directory search "<title> music"\` — and mount it as ITS OWN \`<audio>\` layer at its own \`data-volume\` (~0.1-0.2 under narration, or full level when the song carries the piece). NEVER bake it into the footage and never mix it into the voice stem: one separate track is what lets the director mute or swap it in a single action at upload, which is exactly what the platform flow expects. Name the track you used in your report. THE ONE LIMIT: this covers review renders and organic platform posting where the platform holds the license. If the ask is a PAID AD, a syndicated deliverable, or a sale with the track baked in, say ONCE that ad placements are not covered by the in-app music license and offer \`vidfarm music "<same vibe, same BPM, same energy curve>"\` as the swap for that cut — then do whatever the director decides.
 - 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):
@@ -4627,6 +4761,7 @@ async function runGenerateCommand(argv) {
         : {
             label: "AI image generation",
             estimate: "cheap, ~$0.01–$0.05",
+            agentAlternative: AGENT_IMAGEGEN_ALTERNATIVE,
             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). " +
@@ -4878,7 +5013,11 @@ async function runInpaintCommand(argv) {
         }
     });
     const ctx = commonContext(parsed.values);
-    guardBilled(ctx, { label: "AI image inpaint", estimate: "cheap, ~$0.01–$0.05" });
+    guardBilled(ctx, {
+        label: "AI image inpaint",
+        estimate: "cheap, ~$0.01–$0.05",
+        agentAlternative: AGENT_IMAGEGEN_ALTERNATIVE
+    });
     const sourceArg = parsed.values.source ?? parsed.positionals[0];
     if (!sourceArg)
         throw new Error("inpaint requires a source image: `vidfarm inpaint <image|url> --mask <mask.png> --prompt \"...\"`.");
@@ -5014,7 +5153,11 @@ async function runCreateOverlayCommand(argv) {
         }
     });
     const ctx = commonContext(parsed.values);
-    guardBilled(ctx, { label: "AI transparent overlay generation", estimate: "cheap, ~$0.01–$0.05" });
+    guardBilled(ctx, {
+        label: "AI transparent overlay generation",
+        estimate: "cheap, ~$0.01–$0.05",
+        agentAlternative: AGENT_IMAGEGEN_ALTERNATIVE
+    });
     const prompt = (parsed.values.prompt ?? parsed.positionals.join(" ")).trim();
     if (!prompt) {
         throw new Error("create-overlay requires a subject prompt: `vidfarm create-overlay \"a cartoon rocket ship\" [--key-color #00FF00] [--out overlay.png]`. Describe ONLY the subject — the flat key-color background is added for you.");
@@ -6095,6 +6238,7 @@ async function runCutoutCommand(argv) {
             guardBilled(ctx, {
                 label: "AI image generation (cutout plate)",
                 estimate: "cheap, ~$0.01–$0.05",
+                agentAlternative: AGENT_IMAGEGEN_ALTERNATIVE,
                 freeAlternative: "pass an existing graphic instead — `vidfarm cutout <image|url>` keys+trims for $0.00",
                 interactiveAlternative: 'vidfarm handoff image --theme "<subject>" --single — the user generates the plate in a free web tool ' +
                     "and hands the PNG back; `vidfarm cutout <file>` then keys + trims it for $0"
@@ -6644,6 +6788,7 @@ async function runStickerPackCommand(argv) {
             guardBilled(ctx, {
                 label: `AI image generation (sticker sheet of ${count} items)`,
                 estimate: "cheap, ~$0.01–$0.05 for the WHOLE pack (one image job, not one per sticker)",
+                agentAlternative: AGENT_IMAGEGEN_ALTERNATIVE,
                 freeAlternative: "pass a greenscreen sheet you already have — `vidfarm sticker-pack <sheet.png>` cuts it up for $0.00",
                 interactiveAlternative: `vidfarm handoff image --theme "${generatePrompt.replace(/"/g, "'")}"${itemNames.length ? ` --items "${itemNames.join(",")}"` : ""} — ` +
                     "the user generates the SAME sheet in a free web tool (often better art than the API tier) and hands it " +
@@ -7820,6 +7965,121 @@ 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}`);
 }
+// Google search — video / image / news.
+//
+// The catalog (`vidfarm media`) answers "give me A clip of X". Google answers
+// "give me THE shot": it indexes TikTok, YouTube, every stock library, and the
+// news at once, so one query returns candidate SOURCE URLs that feed straight
+// into `raws scan` (mine clips out of them) or `download-video` (collect one).
+//
+// Flat $0.0003 per CALL — the same price for 1 or 100 links — so the CLI nudges
+// toward one wide page rather than repeated narrow ones. No cost-mode gate: at
+// this price a search is cheaper than the agent turn that decides to skip it.
+async function runWebSearchCommand(kind, argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            limit: { type: "string" },
+            fresh: { type: "string" },
+            region: { type: "string" },
+            duration: { type: "string" },
+            resolution: { type: "string" },
+            color: { type: "string" },
+            size: { type: "string" },
+            "type-image": { type: "string" },
+            layout: { type: "string" },
+            safesearch: { type: "string" }
+        }
+    });
+    const positionals = parsed.positionals.slice();
+    if (positionals[0] && ["search", "find"].includes(positionals[0].toLowerCase()))
+        positionals.shift();
+    const query = positionals.join(" ").trim();
+    if (!query) {
+        console.error(`${RED}${kind}-search: a search query is required${RESET}`);
+        if (kind === "video") {
+            console.error(`${DIM}Search the SHOT, not the topic: vidfarm video-search "office worker typing laptop close up 4K"${RESET}`);
+            console.error(`${DIM}Operators work: site:pexels.com/videos · site:tiktok.com "packing orders" -dance${RESET}`);
+        }
+        else if (kind === "news") {
+            console.error(`${DIM}e.g. vidfarm news-search "AI startup funding announced" --fresh w${RESET}`);
+        }
+        else {
+            console.error(`${DIM}e.g. vidfarm image-search "warehouse interior wide shot" --limit 40${RESET}`);
+        }
+        process.exit(2);
+    }
+    const ctx = commonContext(parsed.values);
+    const maxCap = kind === "video" ? 50 : 100;
+    const limit = Math.min(Math.max(Number(parsed.values.limit ?? "25") || 25, 1), maxCap);
+    const qs = new URLSearchParams({ q: query, max_results: String(limit) });
+    if (parsed.values.region)
+        qs.set("region", String(parsed.values.region));
+    if (parsed.values.fresh)
+        qs.set("timelimit", String(parsed.values.fresh));
+    if (parsed.values.safesearch)
+        qs.set("safesearch", String(parsed.values.safesearch));
+    if (kind === "video") {
+        if (parsed.values.duration)
+            qs.set("duration", String(parsed.values.duration));
+        if (parsed.values.resolution)
+            qs.set("resolution", String(parsed.values.resolution));
+    }
+    if (kind === "image") {
+        if (parsed.values.color)
+            qs.set("color", String(parsed.values.color));
+        if (parsed.values.size)
+            qs.set("size", String(parsed.values.size));
+        if (parsed.values["type-image"])
+            qs.set("type_image", String(parsed.values["type-image"]));
+        if (parsed.values.layout)
+            qs.set("layout", String(parsed.values.layout));
+    }
+    const res = await apiRequest({
+        method: "GET", host: ctx.host, path: `/api/v1/primitives/${kind}-search?${qs.toString()}`, auth: ctx.auth
+    });
+    assertApiOk(res, `${kind} search`);
+    const body = (res.json ?? {});
+    if (ctx.json) {
+        printJson(body);
+        return;
+    }
+    const results = Array.isArray(body.results) ? body.results : [];
+    console.log(`${DIM}${results.length} ${kind} result(s) for "${query}" · $${body.charged_usd ?? 0} this call${RESET}`);
+    if (!results.length) {
+        console.log(`${DIM}No results. Loosen the query — a site: filter plus a long phrase often returns nothing. Try fewer operators, or drop --fresh.${RESET}`);
+        return;
+    }
+    for (const item of results) {
+        if (kind === "image") {
+            console.log(`${GREEN}${item.image_url}${RESET}`);
+            const dims = item.width && item.height ? ` · ${item.width}x${item.height}` : "";
+            console.log(`${DIM}  ${item.title}${dims}${item.source_page ? ` · ${item.source_page}` : ""}${RESET}`);
+            continue;
+        }
+        if (kind === "news") {
+            console.log(`${GREEN}${item.url}${RESET}`);
+            console.log(`${DIM}  ${item.title}${item.source ? ` · ${item.source}` : ""}${item.date ? ` · ${item.date}` : ""}${RESET}`);
+            continue;
+        }
+        console.log(`${GREEN}${item.url}${RESET}`);
+        const meta = [item.duration, item.publisher, item.uploader].filter(Boolean).join(" · ");
+        console.log(`${DIM}  ${item.title}${meta ? ` · ${meta}` : ""}${RESET}`);
+    }
+    if (kind === "video") {
+        console.log(`${DIM}Next: 'vidfarm raws scan <url>' mines clips out of a source · 'vidfarm download-video <url>' collects the file.${RESET}`);
+        console.log(`${RED}A public video is NOT a licensed video — check rights before you reuse anything. Licence-checked free footage: 'vidfarm media search "<meaning>" --type video'.${RESET}`);
+    }
+    else if (kind === "news") {
+        console.log(`${DIM}News finds the STORY. Run 'vidfarm video-search "<event> footage"' for the VISUALS — searching both at once finds neither.${RESET}`);
+        console.log(`${DIM}Method: https://vidfarm.cc/experimental/google-news-to-video.md${RESET}`);
+    }
+    else {
+        console.log(`${RED}These are LINKS with no licence attached. For royalty-free assets use 'vidfarm media search "<meaning>" --type image' instead.${RESET}`);
+    }
+}
 // IconScout — designer icons / STICKERS / illustrations / 3D / Lottie.
 //
 // This is the CHEAP path, and the CLI says so loudly: an AI image attempt costs
@@ -8896,6 +9156,7 @@ async function runApproveCommand(argv) {
             ...commonOptions(),
             video: { type: "string" },
             media: { type: "string", multiple: true },
+            thumbnail: { type: "string" },
             caption: { type: "string" },
             title: { type: "string" },
             pinned: { type: "string" },
@@ -8937,6 +9198,11 @@ async function runApproveCommand(argv) {
         media.push({ url: await resolveApproveMedia(String(parsed.values.video)), kind: "video", role: "primary" });
     for (const url of parsed.values.media ?? [])
         media.push({ url: await resolveApproveMedia(String(url)) });
+    // The social-card poster of the share page. Omit it and the server extracts a
+    // frame (~1s in) from --video and files it under /files/approved.
+    if (parsed.values.thumbnail) {
+        media.push({ url: await resolveApproveMedia(String(parsed.values.thumbnail)), kind: "image", role: "thumbnail" });
+    }
     if (media.length === 0) {
         console.warn(`${DIM}[vidfarm] no --video / --media given; approving a text-only post.${RESET}`);
     }
@@ -9302,6 +9568,15 @@ async function runCostModeCommand(argv) {
     if (resolved.mode === "minimize") {
         console.log(`${DIM}In minimize, ${interaction.mode === "interactive" ? "you're already on" : "offer"} the sweet spot: minimize + interactive = $0 videos that still get custom art (free web image gen → vidfarm sticker-pack) and hand-picked clips (vidfarm handoff raws).${RESET}`);
     }
+    // The one exception worth naming out loud: image generation the AGENT already
+    // owns is free custom art with NO manual step, so minimize keeps it.
+    if (resolved.mode === "minimize" || resolved.mode === "hybrid") {
+        const detection = detectHostAgent();
+        const verdict = detection.host
+            ? `${detection.host.name} — image generation ${detection.availability}`
+            : "host agent not detected";
+        console.log(`${DIM}Image generation included in YOUR agent's own subscription is free in every mode, minimize included (${verdict}). Check: ${BOLD}vidfarm agent-image --check${RESET}${DIM} · brief: vidfarm agent-image "<subject>".${RESET}`);
+    }
 }
 // `vidfarm storyboard [dir]` — the PLAN pass, before any animation work.
 // Storyboarding is a first-class part of the composition format now: a project
@@ -9853,6 +10128,106 @@ 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 agent-image "<subject>"` — the brief for image generation the AGENT
+// runs on its OWN subscription. Vidfarm charges nothing and the provider charges
+// nothing extra, so this rung is allowed in EVERY cost mode, `minimize`
+// included. Antigravity / Gemini CLI and Codex / ChatGPT include an image tool;
+// Claude Code does not (Anthropic ships no image model) — those runs fall back
+// to stock, IconScout, a human hand-off, or a confirmed billed generation.
+async function runAgentImageCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            theme: { type: "string" },
+            items: { type: "string" },
+            style: { type: "string" },
+            "key-color": { type: "string" },
+            "out-dir": { type: "string" },
+            out: { type: "string" },
+            folder: { type: "string" },
+            grid: { type: "string" },
+            single: { type: "boolean", default: false },
+            zoned: { type: "boolean", default: false },
+            check: { type: "boolean", default: false }
+        }
+    });
+    const json = Boolean(parsed.values.json);
+    const detection = detectHostAgent();
+    // `--check` (and a bare invocation) answers only "do I have this at all?".
+    if (parsed.values.check || (!parsed.values.theme && !parsed.values.items && !parsed.positionals.length)) {
+        if (json) {
+            return printJson({
+                ok: true,
+                host: detection.host?.id ?? null,
+                host_name: detection.host?.name ?? null,
+                availability: detection.availability,
+                matched_env: detection.matched,
+                known_hosts: KNOWN_HOST_AGENTS.map((h) => ({ id: h.id, name: h.name, availability: h.availability, note: h.note }))
+            });
+        }
+        console.log(`${BOLD}Agent-included image generation${RESET}`);
+        console.log(`${DIM}Vidfarm does not need to sell you an image model if the agent driving this terminal already has one.${RESET}\n`);
+        if (detection.host) {
+            const flag = detection.availability === "included" ? GREEN : detection.availability === "none" ? YELLOW : DIM;
+            console.log(`Detected: ${flag}${detection.host.name}${RESET} — image generation ${BOLD}${detection.availability}${RESET}`);
+            console.log(`${DIM}${detection.host.note}${RESET}`);
+            console.log(`${DIM}Matched env: ${detection.matched.join(", ")}${RESET}\n`);
+        }
+        else {
+            console.log(`${DIM}Host agent not detected from the environment.${RESET}\n`);
+        }
+        for (const h of KNOWN_HOST_AGENTS) {
+            console.log(`  ${h.availability === "included" ? GREEN + "✓" : h.availability === "none" ? YELLOW + "✗" : DIM + "?"}${RESET} ${h.name} ${DIM}— ${h.availability}${RESET}`);
+        }
+        console.log(`\n${DIM}The env check is a hint only. The authority is your own tool list — if you have an image tool, you have this.${RESET}`);
+        console.log(`${DIM}Brief: ${BOLD}vidfarm agent-image "<subject>" --items "a,b,c"${RESET}${DIM} · free in EVERY cost mode, minimize included.${RESET}`);
+        return;
+    }
+    const splitList = (raw) => (raw ?? "").split(/\s*[;,]\s*/).map((s) => s.trim()).filter(Boolean);
+    const theme = parsed.values.theme?.trim() || parsed.positionals.join(" ").trim();
+    const items = splitList(parsed.values.items);
+    if (!theme && !items.length) {
+        throw new Error('agent-image needs a subject: `vidfarm agent-image "cozy farm props" --items "barn,tractor,hay bale"`.');
+    }
+    const brief = buildAgentImageBrief({
+        theme: theme || items.join(", "),
+        items,
+        style: parsed.values.style,
+        keyColor: parsed.values["key-color"],
+        outDir: parsed.values["out-dir"],
+        outFile: parsed.values.out,
+        folder: parsed.values.folder,
+        grid: parsed.values.grid,
+        pack: parsed.values.single ? false : undefined,
+        zoned: Boolean(parsed.values.zoned),
+        detection
+    });
+    if (json) {
+        return printJson({
+            ok: true,
+            host: detection.host?.id ?? null,
+            availability: brief.availability,
+            out_file: brief.outFile,
+            prompt: brief.prompt,
+            steps: brief.steps,
+            follow_up: brief.followUp,
+            fallbacks: brief.fallbacks,
+            key_color: brief.keyColor,
+            key_color_note: brief.keyColorNote
+        });
+    }
+    if (detection.availability === "none") {
+        console.log(`${YELLOW}${BOLD}This host has no image tool of its own — read the fallbacks at the bottom first.${RESET}`);
+        console.log(`${DIM}The prompt is still below: it is the same prompt for a human hand-off or a billed generation.${RESET}\n`);
+    }
+    else {
+        console.log(`${BOLD}Generate this yourself — it is already in your subscription.${RESET}`);
+        console.log(`${DIM}Costs $0 on Vidfarm and $0 extra on the provider, so it is allowed in cost mode minimize.${RESET}\n`);
+    }
+    console.log(formatAgentImageBrief(brief, detection));
+}
 // `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
@@ -9892,7 +10267,11 @@ async function runConsultCommand(argv) {
         }
         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}`);
+        // The easier win comes first. A director who has seen 20 titled ideas
+        // answers the interview better than one asked to think cold.
+        console.log(`\nBefore the interview: ${BOLD}vidfarm ideas --topic "<your offer in one line>"${RESET}`);
+        console.log(`${DIM}20+ video ideas, offline and free, for one sentence of input → content-ideas.md. Do that first.${RESET}`);
+        console.log(`\nThen 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}`);
@@ -10733,6 +11112,30 @@ const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/fil
     e.g. vidfarm directory save-url "https://…/inpaint-out.png" --folder inpaints --as hero.png
     (server fetches the URL — handles cross-origin S3; the CLI twin of the pop-panel "Save to Files")
 
+  directory share <path>           Mint a PUBLIC link onto one subfolder          → POST /api/v1/user/me/directory/shares
+    --mode read|upload|edit        read = browse + vector search (default) · upload = + add files/folders,
+                                   never delete · edit = + rename & delete. Scoped to <path> and everything
+                                   under it — never a sibling or a parent.
+    --label <text>                 Name the link so you can tell your links apart
+    --json                         Raw JSON response
+    Works on ANY root (/files·/temp·/raws·/approved; /projects is read-only so it takes --mode read).
+    Only /files and /temp accept uploads — the other roots have no plain-upload backend, so an upload
+    link there only creates folders. PAID: minting a link needs a paid plan; VISITING one needs no account.
+    e.g. vidfarm directory share /files/crowdsourced --mode upload --label "Contributor drop box"
+         vidfarm directory share /raws/b-roll --mode read --label "Editor library"
+
+  directory shares [path]          List your share links (optionally for one folder) → GET /api/v1/user/me/directory/shares
+    --path <path> --json
+
+  directory share-update <token>   Change or switch off a link                    → PATCH /api/v1/user/me/directory/shares/:token
+    --mode read|upload|edit        Re-scope what holders can do
+    --label <text>                 Rename the link
+    --disable | --enable           Cut off access instantly (reversible — the token survives)
+    --json
+
+  directory unshare <token>        Delete a link for good                         → DELETE /api/v1/user/me/directory/shares/:token
+    --json                         (to keep the record, prefer share-update --disable)
+
   Aliases: directory | dir  (move|mv · copy|cp)   ·   Auth: --api-key <key> or VIDFARM_API_KEY, --host <url>`;
 async function runDirectoryCommand(argv) {
     const sub = argv[0];
@@ -10756,6 +11159,14 @@ async function runDirectoryCommand(argv) {
         case "from-url":
         case "import-url":
             return runDirectorySaveUrl(rest);
+        case "shares":
+            return runDirectorySharesList(rest);
+        case "share":
+            return runDirectoryShareCreate(rest);
+        case "share-update":
+            return runDirectoryShareUpdate(rest);
+        case "unshare":
+            return runDirectoryShareDelete(rest);
         case undefined:
         case "help":
         case "--help":
@@ -10929,6 +11340,140 @@ async function runDirectoryCopy(argv) {
     const suffix = typeof copied === "number" ? ` ${DIM}(${copied} file${copied === 1 ? "" : "s"})${RESET}` : "";
     console.log(`${GREEN}✓${RESET} Copied to ${BOLD}${newPath}${RESET}${suffix} ${DIM}[${space}]${RESET}`);
 }
+// ── directory share tokens ───────────────────────────────────────────────────
+// Public links onto ONE subfolder of any root. Three modes: read (browse +
+// vector search), upload (+ add files/folders, never delete), edit (+ rename &
+// delete). Minting a link is a PAID action; visiting one needs no account at
+// all. Shares live in the cloud directory, so these never fan out to --both.
+// A hoisted function, not a const: main() runs at module top-level ABOVE this
+// point, so a `const` declared down here is still in its temporal dead zone
+// when a command handler reads it.
+function shareModes() {
+    return ["read", "upload", "edit"];
+}
+function shareLine(share) {
+    const mode = String(share?.mode ?? "read");
+    const state = share?.disabled ? `${DIM}(disabled)${RESET}` : "";
+    const label = share?.label ? `${BOLD}${share.label}${RESET}  ` : "";
+    return [
+        `${label}${DIM}${share?.path ?? ""}${RESET}  [${mode}] ${state}`,
+        `  ${share?.url ?? ""}`,
+        `  ${DIM}${share?.token ?? ""}${RESET}`
+    ].join("\n");
+}
+async function runDirectorySharesList(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), path: { type: "string" } } });
+    const ctx = commonContext(parsed.values);
+    const pathFilter = parsed.values.path ?? parsed.positionals[0];
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, { method: "GET", path: "/api/v1/user/me/directory/shares", query: pathFilter ? { path: pathFilter } : {} }, space);
+    assertApiOk(result, "directory shares");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const shares = (result.json?.shares ?? []);
+    if (!shares.length) {
+        console.log(`${DIM}No share links${pathFilter ? ` for ${pathFilter}` : ""}. Create one: vidfarm directory share <path> --mode read${RESET}`);
+        return;
+    }
+    console.log(shares.map(shareLine).join("\n\n"));
+    console.log(`\n${DIM}${shares.length} link${shares.length === 1 ? "" : "s"}${RESET}`);
+}
+async function runDirectoryShareCreate(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), mode: { type: "string" }, label: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const targetPath = parsed.positionals[0];
+    if (!targetPath) {
+        throw new Error('directory share requires a folder path: vidfarm directory share <path> [--mode read|upload|edit] [--label <text>]\n  e.g. vidfarm directory share /files/crowdsourced --mode upload --label "Contributor drop box"\n       vidfarm directory share /raws/b-roll --mode read --label "Editor library"');
+    }
+    const mode = parsed.values.mode ?? "read";
+    if (!shareModes().includes(mode)) {
+        throw new Error(`--mode must be ${shareModes().join(" | ")} (got "${mode}")`);
+    }
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, {
+        method: "POST",
+        path: "/api/v1/user/me/directory/shares",
+        body: { path: targetPath, mode, ...(parsed.values.label ? { label: String(parsed.values.label) } : {}) }
+    }, space);
+    assertApiOk(result, "directory share");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const share = result.json?.share ?? {};
+    console.log(`${GREEN}✓${RESET} Shared ${BOLD}${share.path ?? targetPath}${RESET} as ${BOLD}${mode}${RESET} ${DIM}[${space}]${RESET}`);
+    console.log(`  ${share.url ?? ""}`);
+    console.log(`  ${DIM}${share.token ?? ""}  ·  disable it with: vidfarm directory share-update ${share.token ?? "<token>"} --disable${RESET}`);
+}
+async function runDirectoryShareUpdate(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            mode: { type: "string" },
+            label: { type: "string" },
+            disable: { type: "boolean" },
+            enable: { type: "boolean" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const token = parsed.positionals[0];
+    if (!token) {
+        throw new Error('directory share-update requires a token: vidfarm directory share-update <token> [--mode read|upload|edit] [--label <text>] [--disable|--enable]');
+    }
+    const mode = parsed.values.mode;
+    if (mode && !shareModes().includes(mode)) {
+        throw new Error(`--mode must be ${shareModes().join(" | ")} (got "${mode}")`);
+    }
+    if (parsed.values.disable && parsed.values.enable) {
+        throw new Error("Pass --disable or --enable, not both.");
+    }
+    const body = {};
+    if (mode)
+        body.mode = mode;
+    if (parsed.values.label !== undefined)
+        body.label = String(parsed.values.label);
+    if (parsed.values.disable)
+        body.disabled = true;
+    if (parsed.values.enable)
+        body.disabled = false;
+    if (!Object.keys(body).length) {
+        throw new Error("Nothing to change — pass --mode, --label, --disable or --enable.");
+    }
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, { method: "PATCH", path: `/api/v1/user/me/directory/shares/${encodeURIComponent(token)}`, body }, space);
+    assertApiOk(result, "directory share-update");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const share = result.json?.share ?? {};
+    const state = share.disabled ? `${BOLD}disabled${RESET}` : `${BOLD}live${RESET}`;
+    console.log(`${GREEN}✓${RESET} Share ${DIM}${token}${RESET} is ${state} as ${BOLD}${share.mode ?? "read"}${RESET} ${DIM}[${space}]${RESET}`);
+}
+async function runDirectoryShareDelete(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions() } });
+    const ctx = commonContext(parsed.values);
+    const token = parsed.positionals[0];
+    if (!token) {
+        throw new Error('directory unshare requires a token: vidfarm directory unshare <token>\n  (to keep the record but cut off access, use: vidfarm directory share-update <token> --disable)');
+    }
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, { method: "DELETE", path: `/api/v1/user/me/directory/shares/${encodeURIComponent(token)}` }, space);
+    assertApiOk(result, "directory unshare");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    console.log(`${GREEN}✓${RESET} Deleted share ${DIM}${token}${RESET} ${DIM}[${space}]${RESET}`);
+}
 // Save a durable media URL (e.g. a finished job's output) INTO My Files at a
 // folder — the CLI twin of the pop-panel "Save to Files" picker. Server fetches
 // the URL (handles cross-origin S3), so no local download round-trip needed.
@@ -12092,7 +12637,12 @@ async function runIdeasCommand(argv) {
             family: { type: "string" },
             topic: { type: "string" },
             count: { type: "string" },
-            families: { type: "boolean", default: false }
+            families: { type: "boolean", default: false },
+            angles: { type: "boolean", default: false },
+            angle: { type: "string" },
+            stages: { type: "boolean", default: false },
+            stage: { type: "string" },
+            grid: { type: "boolean", default: false }
         }
     });
     const json = Boolean(parsed.values.json);
@@ -12100,6 +12650,139 @@ async function runIdeasCommand(argv) {
     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`.");
+    // The three axes of an idea live in one reference, so they live behind one
+    // command. A director who only ever sees the frames posts 30 videos at one
+    // awareness stage from one angle, which is the exact failure this expansion
+    // exists to prevent — so the stage and angle banks are flags here, not a
+    // separate command nobody discovers.
+    const ladder = loadAwarenessLadder();
+    const angleBank = loadAngleBank();
+    if (parsed.values.stages || parsed.values.stage) {
+        const wanted = String(parsed.values.stage ?? "").trim().toLowerCase();
+        const picked = wanted
+            ? ladder.filter((entry) => entry.stage.toLowerCase().includes(wanted) || String(entry.index) === wanted)
+            : ladder;
+        if (wanted && !picked.length) {
+            throw new Error(`No awareness stage matches "${wanted}". Stages: ${ladder.map((entry) => `${entry.index} ${entry.stage}`).join(", ")}.`);
+        }
+        if (json)
+            return printJson({ ok: true, offline: true, topic: topic || null, stages: picked });
+        console.log(`${BOLD}The awareness ladder${RESET} ${DIM}(${picked.length} of ${ladder.length} stages · what the viewer already knows)${RESET}\n`);
+        for (const entry of picked) {
+            console.log(`  ${GREEN}${entry.index} · ${entry.stage}${RESET} ${DIM}— ${entry.summary}${RESET}`);
+            for (const field of entry.fields)
+                console.log(`      ${BOLD}${field.label}:${RESET} ${field.value}`);
+            console.log("");
+        }
+        console.log(`${DIM}The stage decides the first ten seconds AND the ask. Do not sell at stage 1 or 2.${RESET}`);
+        console.log(`${DIM}A month of posts should cover the ladder — default mix + the grid: vidfarm skill show content-ideas${RESET}`);
+        console.log(`${DIM}Angles for a stage: vidfarm ideas --angles   ·   pair them up: vidfarm ideas --grid --topic "<offer>"${RESET}`);
+        return;
+    }
+    if (parsed.values.angles || parsed.values.angle) {
+        const wanted = String(parsed.values.angle ?? "").trim().toLowerCase();
+        const picked = wanted
+            ? angleBank.angles.filter((entry) => entry.family.toLowerCase().includes(wanted) || entry.frame.toLowerCase().includes(wanted))
+            : angleBank.angles;
+        if (wanted && !picked.length) {
+            throw new Error(`No angle matches "${wanted}". Angle families: ${angleBank.families.join(", ")} (see \`vidfarm ideas --angles\`).`);
+        }
+        if (json) {
+            return printJson({
+                ok: true,
+                offline: true,
+                topic: topic || null,
+                total_angles: angleBank.angles.length,
+                families: angleBank.families,
+                angles: picked,
+                method: "references/content-ideas.md"
+            });
+        }
+        console.log(`${BOLD}Problem angles${RESET} ${DIM}(${picked.length} of ${angleBank.angles.length} · which side of the problem the video comes from)${RESET}`);
+        if (topic)
+            console.log(`${DIM}Topic: ${RESET}${topic}`);
+        console.log("");
+        let angleGroup = "";
+        for (const entry of picked) {
+            if (entry.family !== angleGroup) {
+                angleGroup = entry.family;
+                console.log(`  ${BOLD}${angleGroup}${RESET}`);
+            }
+            console.log(`    ${GREEN}${entry.frame}${RESET}${entry.note ? ` ${DIM}— ${entry.note}${RESET}` : ""}`);
+        }
+        console.log("");
+        console.log(`${DIM}"I already covered that topic" → hold the frame, change the angle. Same research, new video.${RESET}`);
+        console.log(`${DIM}Pair angles with frames and stages: vidfarm ideas --grid --topic "<offer>"${RESET}`);
+        return;
+    }
+    if (parsed.values.grid) {
+        // The grid is the honest answer to "give me 30 videos": vary TWO axes.
+        // Walking frames, angles and stages at different strides keeps every row a
+        // different combination instead of 30 rows of one frame family.
+        const rows = Number(parsed.values.count ?? 20);
+        const total = Number.isFinite(rows) && rows > 0 ? Math.min(rows, 200) : 20;
+        if (!angleBank.angles.length || !ladder.length) {
+            throw new Error("The bundled content-ideas reference has no angle or awareness bank. Update it with `vidfarm skills add vidfarm`.");
+        }
+        // Stage order is not round-robin: this ten-row cycle reproduces the default
+        // monthly mix from the reference (3 unaware, 3 problem-aware, 2 solution-
+        // aware, 1 product-aware, 1 most-aware), so a 30-row grid is already a
+        // balanced month instead of six videos of each.
+        const mixCycle = [1, 2, 1, 3, 2, 4, 1, 2, 3, 5];
+        // Each stage names the frames and angles it can actually carry. Pairing
+        // "the price objection" with a stage-1 video would hand the director a row
+        // the reference itself calls wrong, so draw from the stage's own lists and
+        // fall back to the full banks only if a list is missing.
+        const listed = (stage, label) => (stage.fields.find((field) => field.label.toLowerCase().startsWith(label))?.value ?? "")
+            .split(" · ").map((item) => item.trim().toLowerCase()).filter(Boolean);
+        const gridSeen = new Set();
+        const grid = Array.from({ length: total }, (_, i) => {
+            const stage = ladder.find((entry) => entry.index === mixCycle[i % mixCycle.length]) ?? ladder[i % ladder.length];
+            const round = Math.floor(i / mixCycle.length);
+            const fitFrames = listed(stage, "frames");
+            const fitAngles = listed(stage, "angles");
+            const framePool = frames.filter((entry) => fitFrames.includes(entry.frame.toLowerCase()));
+            const anglePool = angleBank.angles.filter((entry) => fitAngles.includes(entry.frame.toLowerCase()));
+            const usableFrames = framePool.length ? framePool : frames;
+            const usableAngles = anglePool.length ? anglePool : angleBank.angles;
+            // Strides alone collide once a pool size divides one of them, and a grid
+            // that prints the same row twice is exactly the repetition this command
+            // sells against — so walk forward until the triple is new.
+            let frame = usableFrames[(i + round) % usableFrames.length];
+            let angle = usableAngles[(i * 3 + round) % usableAngles.length];
+            for (let bump = 0; bump < usableFrames.length * usableAngles.length; bump += 1) {
+                if (!gridSeen.has(`${stage.index}|${frame.frame}|${angle.frame}`))
+                    break;
+                angle = usableAngles[(i * 3 + round + bump + 1) % usableAngles.length];
+                if ((bump + 1) % usableAngles.length === 0)
+                    frame = usableFrames[(i + round + bump + 1) % usableFrames.length];
+            }
+            gridSeen.add(`${stage.index}|${frame.frame}|${angle.frame}`);
+            return {
+                stage: `${stage.index} · ${stage.stage}`,
+                angle: angle.frame,
+                angle_family: angle.family,
+                frame: frame.frame,
+                frame_family: frame.family,
+                starter: topic ? joinIdeaFrame(frame.frame, topic) : null
+            };
+        });
+        if (json)
+            return printJson({ ok: true, offline: true, topic: topic || null, rows: grid, method: "references/content-ideas.md" });
+        console.log(`${BOLD}Idea grid${RESET} ${DIM}(${total} combinations · stage × angle × frame · offline, free, no AI call)${RESET}`);
+        if (topic)
+            console.log(`${DIM}Topic: ${RESET}${topic}`);
+        console.log("");
+        for (const row of grid) {
+            console.log(`  ${DIM}${row.stage.padEnd(18)}${RESET}${GREEN}${row.angle}${RESET}`);
+            console.log(`    ${row.starter ?? row.frame}`);
+        }
+        console.log("");
+        console.log(`${DIM}Each row is a DIFFERENT video, not a rewrite — the stage and the angle both moved.${RESET}`);
+        console.log(`${DIM}Sharpen each into a real title, keep the stage label on it, then write hook/loop/payoff/bait.${RESET}`);
+        console.log(`${DIM}Method, the monthly stage mix, and a worked example: vidfarm skill show content-ideas${RESET}`);
+        return;
+    }
     if (parsed.values.families) {
         if (json)
             return printJson({ ok: true, families, frames: frames.length });
@@ -12147,6 +12830,9 @@ async function runIdeasCommand(argv) {
             total_frames: frames.length,
             families,
             frames: picked.map((entry) => ({ frame: entry.frame, family: entry.family, starter: topic ? joinIdeaFrame(entry.frame, topic) : null })),
+            total_angles: angleBank.angles.length,
+            angle_families: angleBank.families,
+            awareness_stages: ladder.map((entry) => ({ index: entry.index, stage: entry.stage, summary: entry.summary })),
             method: "references/content-ideas.md"
         });
     }
@@ -12170,9 +12856,18 @@ async function runIdeasCommand(argv) {
     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}A frame is only ONE axis. The other two are here too, and a set that freezes them repeats:${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --stages    ${RESET}${ladder.length} awareness stages ${DIM}— what the viewer knows, and what you may ask for${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --angles    ${RESET}${angleBank.angles.length} problem angles ${DIM}— which side of the problem the video comes from${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --grid --topic "<offer>"${RESET} ${DIM}— stage × angle × frame, one row per video${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}`);
+    // The natural upsell, in the right order: ideas are the easy win, and the
+    // interview is what a director opts into once they want the strategy behind
+    // the list. Offering it here means it never has to be asked for cold.
+    console.log(`${DIM}Save the picks as content-ideas.md in your working folder. Want the strategy behind them${RESET}`);
+    console.log(`${DIM}(who to sell to, which angle, which hook)? That is the interview: vidfarm consult coldstart --short${RESET}`);
 }
 async function runSkillDocsCommand(sub, argv) {
     const parsed = parseArgs({
@@ -12340,4 +13035,25 @@ async function runUpdateSkillCommand(argv) {
         ...(ctx.json ? ["--json"] : [])
     ]);
 }
+// ── entry point ──────────────────────────────────────────────────────────────
+// Last statement in the file ON PURPOSE: see the note where this used to live.
+// Every module-level declaration above is initialized by the time a command
+// handler reads it, so late-declared help texts and tables are safe.
+void main().catch(async (error) => {
+    // Deliberate, expected user-facing conditions (e.g. local mode in the
+    // published cloud-only CLI) print just the message — no stack, no crash report.
+    if (error instanceof LocalModeUnavailableError
+        || error instanceof CostModeBlockedError
+        // A missing OPTIONAL native module (better-sqlite3 with no C++ toolchain,
+        // the common Windows case) is an environment fact, not a vidfarm bug.
+        || error instanceof NativeModuleUnavailableError) {
+        console.error(error.message);
+        process.exit(1);
+    }
+    console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+    // Report only unexpected crashes (bugs), never the deliberate user-facing
+    // `throw new Error(...)` above; no-op unless a devcli DSN is configured.
+    await reportCliCrash(error);
+    process.exit(1);
+});
 //# sourceMappingURL=cli.js.map