@officexapp/vidfarm-devcli 0.21.45 → 0.21.46

package/dist/src/cli.js

@@ -32,11 +32,14 @@ import { runSkillsCommand } from "./devcli/skills.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
@@ -1127,6 +1154,15 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
   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
@@ -1165,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
@@ -1477,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":
@@ -1547,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;
@@ -1561,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();
@@ -1866,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)
@@ -2664,6 +2742,7 @@ 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\`.
@@ -4682,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). " +
@@ -4933,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 \"...\"`.");
@@ -5069,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.");
@@ -6150,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"
@@ -6699,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 " +
@@ -9478,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
@@ -10029,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
@@ -12843,7 +13042,11 @@ async function runUpdateSkillCommand(argv) {
 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) {
+    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);
     }

package/dist/src/devcli/agent-imagegen.js

@@ -0,0 +1,181 @@
+// Agent-included image generation — the $0 rung between "free stock" and "pay
+// Vidfarm to generate it".
+//
+// The premise: Vidfarm does not need to broker an image model when the agent
+// driving the terminal ALREADY has one included in its own subscription. Google
+// Antigravity / Gemini CLI ship image generation (Nano Banana / Imagen) at no
+// extra charge. OpenAI Codex / ChatGPT ship gpt-image. Claude does not — there
+// is no Anthropic image model, so Claude Code has nothing to fall back on here.
+//
+// That distinction is the whole feature. In cost mode `minimize` the old answer
+// to "I need a graphic" was: free stock, IconScout, or hand the human a prompt.
+// If the agent's own runtime includes image generation, there is a better answer
+// that is still $0 — the agent generates the file itself and imports it. Same
+// house pattern as `vidfarm consult`: the devcli writes the brief, the agent in
+// the terminal executes it. See references/agent-included-imagegen.md.
+//
+// Availability is asserted by the AGENT, not sniffed by us. Env detection here
+// is a hint for the opening line only; the authoritative check is the agent
+// looking at its own tool list. Never claim a capability the agent has to prove.
+//
+// Backend-free (Node built-ins + pure sibling modules) so it ships in the public
+// cloud-only package.
+import { buildImageHandoff } from "./handoff.js";
+/**
+ * Hosts we can say something concrete about. Kept deliberately short: a wrong
+ * "yes" costs the user a wasted turn, a wrong "no" costs them money, so anything
+ * we are not sure of stays `unknown` and the agent checks its own tools.
+ */
+export const KNOWN_HOST_AGENTS = [
+    {
+        id: "claude-code",
+        name: "Claude Code",
+        availability: "none",
+        envMarkers: ["CLAUDECODE", "CLAUDE_CODE", "CLAUDE_CODE_ENTRYPOINT"],
+        note: "Anthropic ships no image model, so there is nothing included here. Use free stock / IconScout, hand the user a prompt (`vidfarm handoff image`), or spend on `vidfarm generate image`."
+    },
+    {
+        id: "antigravity",
+        name: "Google Antigravity",
+        availability: "included",
+        tool: "the built-in Gemini image generation (Nano Banana / Imagen)",
+        envMarkers: ["ANTIGRAVITY", "ANTIGRAVITY_SESSION", "ANTIGRAVITY_WORKSPACE"],
+        note: "Image generation is part of the Gemini subscription — generating a graphic costs $0 extra."
+    },
+    {
+        id: "gemini-cli",
+        name: "Gemini CLI",
+        availability: "included",
+        tool: "the built-in Gemini image generation (Nano Banana / Imagen)",
+        envMarkers: ["GEMINI_CLI", "GEMINI_CLI_SESSION", "GEMINI_SANDBOX"],
+        note: "Image generation is part of the Gemini subscription — generating a graphic costs $0 extra."
+    },
+    {
+        id: "codex",
+        name: "OpenAI Codex",
+        availability: "included",
+        tool: "the built-in OpenAI image generation (gpt-image)",
+        envMarkers: ["CODEX_SANDBOX", "CODEX_HOME", "CODEX_CLI"],
+        note: "Image generation is part of the ChatGPT/Codex subscription — generating a graphic costs $0 extra."
+    },
+    {
+        id: "opencode",
+        name: "OpenCode",
+        availability: "unknown",
+        envMarkers: ["OPENCODE", "OPENCODE_SESSION"],
+        note: "Depends entirely on which model is configured — check your own tool list."
+    },
+    {
+        id: "cursor",
+        name: "Cursor",
+        availability: "unknown",
+        envMarkers: ["CURSOR_TRACE_ID", "CURSOR_SESSION_ID"],
+        note: "Depends on the selected model — check your own tool list."
+    }
+];
+/**
+ * Guess which agent runtime is driving this terminal from its env markers.
+ * A miss is normal and harmless — `availability: "unknown"` just means the brief
+ * asks the agent to check its own tools instead of asserting anything.
+ */
+export function detectHostAgent(env = process.env) {
+    for (const host of KNOWN_HOST_AGENTS) {
+        const matched = host.envMarkers.filter((k) => {
+            const v = env[k];
+            return typeof v === "string" && v.trim() !== "" && v.trim() !== "0" && v.trim().toLowerCase() !== "false";
+        });
+        if (matched.length)
+            return { host, matched, availability: host.availability };
+    }
+    return { host: null, matched: [], availability: "unknown" };
+}
+/** One line naming this rung, for cost-mode block messages and help text. */
+export const AGENT_IMAGEGEN_ALTERNATIVE = "generate it YOURSELF for $0 if your own agent subscription includes image generation " +
+    "(Google Antigravity / Gemini CLI and OpenAI Codex / ChatGPT do; Claude Code does NOT — " +
+    'Anthropic ships no image model) — run `vidfarm agent-image "<subject>" --items "a,b,c"` for ' +
+    "the prompt, the plate rules and the import command, then `vidfarm put-file` the result";
+/** The shorter form used inside prose blurbs. */
+export const AGENT_IMAGEGEN_SHORT = 'if YOUR agent subscription includes image generation (Gemini/Antigravity, Codex/ChatGPT — not Claude), generate it yourself: `vidfarm agent-image "<subject>"`';
+/**
+ * Build the brief the AGENT executes itself. The prompt body is shared verbatim
+ * with `vidfarm handoff image` (`buildImageHandoff`) — a plate that keys cleanly
+ * and art that survives the cut are the same craft whoever runs the generator —
+ * only the STEPS change, because here the runner is the agent, not the human.
+ */
+export function buildAgentImageBrief(input) {
+    const base = buildImageHandoff(input);
+    const detection = input.detection ?? detectHostAgent();
+    const items = input.items.map((s) => s.trim()).filter(Boolean);
+    const pack = input.pack ?? items.length > 1;
+    const outDir = input.outDir ?? "./stickers";
+    const outFile = input.outFile ?? (pack ? "./sheet.png" : "./art.png");
+    const folderFlag = input.folder ? ` --folder ${input.folder}` : "";
+    const cutCmd = pack
+        ? `vidfarm sticker-pack ${outFile}${items.length ? ` --items "${items.join(",")}"` : ""} --out-dir ${outDir}`
+        : `vidfarm cutout ${outFile}`;
+    const steps = [
+        "Check YOUR OWN tool list for an image-generation tool included in this subscription — " +
+            "Antigravity / Gemini CLI have one (Nano Banana / Imagen), Codex / ChatGPT have one (gpt-image), " +
+            "Claude Code has none. If you have none, use the fallbacks below instead; do not pretend.",
+        `Generate the image with that tool using the prompt below, and save it to ${outFile}. ` +
+            "This spends nothing on Vidfarm and nothing extra on the provider — it is already in the subscription.",
+        "Look at the result before you use it: a flat even plate, crisp edges, nothing touching or " +
+            "cropped at the frame edge. Re-generate rather than shipping a sheet that will cut badly.",
+        `Cut it locally for $0: \`${cutCmd}\`.`,
+        `Bring the asset into the library so later videos reuse it: \`vidfarm put-file ${outDir}/<file>.png${folderFlag}\`.`
+    ];
+    const fallbacks = [
+        'Free stock first, always — `vidfarm media search "<meaning>" --type image|vector` (Openverse is keyless).',
+        'Any icon, sticker, illustration, 3D prop or Lottie — `vidfarm iconscout "<meaning>" --free` beats generation on price AND quality.',
+        'Hand the human the prompt — `vidfarm handoff image --theme "<what>" --items "a,b,c"`; they run it in a free web generator.',
+        "Only then spend: `vidfarm generate image --prompt \"…\"` (~$0.01–$0.05, billed to the user's own provider key)."
+    ];
+    return {
+        ...base,
+        outFile,
+        availability: detection.availability,
+        hostName: detection.host?.name ?? null,
+        steps,
+        followUp: cutCmd,
+        fallbacks,
+        tools: detection.host?.tool
+            ? [detection.host.tool]
+            : ["your own runtime's image-generation tool, if this subscription includes one"]
+    };
+}
+/** Render the brief as the block an agent reads (and may show the user). */
+export function formatAgentImageBrief(brief, detection) {
+    const lines = [];
+    const host = detection.host;
+    if (host && host.availability === "included") {
+        lines.push(`Detected host: ${host.name} — image generation IS included in this subscription.`);
+        lines.push(host.note);
+    }
+    else if (host && host.availability === "none") {
+        lines.push(`Detected host: ${host.name} — image generation is NOT included.`);
+        lines.push(host.note);
+    }
+    else if (host) {
+        lines.push(`Detected host: ${host.name} — unclear whether image generation is included.`);
+        lines.push(host.note);
+    }
+    else {
+        lines.push("Host agent not detected from the environment.");
+    }
+    lines.push("The env check is only a hint. YOU are the authority: look at your own tool list.");
+    lines.push("");
+    brief.steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+    lines.push("");
+    lines.push("─── the generation prompt ───");
+    lines.push(brief.prompt);
+    lines.push("─────────────────────────────");
+    if (brief.keyColorNote) {
+        lines.push("");
+        lines.push(`Plate: ${brief.keyColorNote}`);
+    }
+    lines.push("");
+    lines.push("If you have NO image tool of your own, in this order:");
+    brief.fallbacks.forEach((f) => lines.push(`  • ${f}`));
+    return lines.join("\n");
+}
+//# sourceMappingURL=agent-imagegen.js.map