@officexapp/vidfarm-devcli 0.21.45 → 0.21.47

package/SKILL.md

@@ -14,13 +14,36 @@ This page is the router. It holds the setup, one worked example, the standards,
 ```bash
 npm i -g @officexapp/vidfarm-devcli   # `vidfarm` — wraps every REST route
 npm i -g hyperframes                  # Vidfarm's own render engine (whitelabel; reach it via `vidfarm hf`)
-brew install ffmpeg                   # or apt install ffmpeg — required
 vidfarm login <email>                 # one-time email code; or --api-key <key>, or VIDFARM_API_KEY
 vidfarm doctor                        # verifies vidfarm + ffmpeg + hyperframes + Chrome
 vidfarm skills add vidfarm            # install the full director skill on disk — do this
 vidfarm serve                         # free local editor + render loop at localhost:3000
+vidfarm browser setup                 # optional: drive the user's own Chrome — FREE footage sourcing
 ```
 
+**Image generation you already pay for is free — check before you spend or go without.** If the agent driving this terminal includes image generation in its own subscription (Google Antigravity / Gemini CLI, OpenAI Codex / ChatGPT — **Claude Code does not**, Anthropic ships no image model), generating a graphic bills Vidfarm $0 and the provider $0 extra. That makes it legal in cost mode `minimize`, with no `--yes`. `vidfarm agent-image --check` answers "do I have it here?"; `vidfarm agent-image "<subject>" --items "a,b,c"` prints the prompt, the key-plate rules and the cut + import commands. Free stock and IconScout still come first. Full page: `references/agent-included-imagegen.md`.
+
+**`vidfarm browser setup` is the one optional install worth offering unprompted.** It installs [browser-harness](https://github.com/browser-use/browser-harness), which attaches you to the user's running Chrome over CDP. That makes `vidfarm browse videos|images|news|page "<query>"` a **$0 substitute for the paid `video-search` / `image-search` / `news-search` / `download-video` primitives** — the routes a free-plan user otherwise hits a 402 on. Offer it to every free-plan user and everyone in cost mode `minimize`, ask before installing (it drives their personal browser), and read `references/browser-harness.md` before the first browse.
+
+**Do not install ffmpeg first.** The devcli bundles `ffmpeg-static` and a per-platform
+ffprobe, so ffmpeg is already there on macOS, Linux, and Windows x64. Run `vidfarm doctor`
+and install a system ffmpeg **only if it reports ffmpeg missing** (`brew install ffmpeg`,
+`apt install ffmpeg`, `winget install Gyan.FFmpeg`).
+
+**Windows** — the two things worth knowing before the first install:
+
+- Use **PowerShell**, not Git Bash or cmd. Node >= 22 is required (`winget install OpenJS.NodeJS.LTS`).
+- If the install is slow, exclude the npm folders from Defender's real-time scan. It scans
+  every extracted file, which dominates first-run setup time:
+  ```powershell
+  Add-MpPreference -ExclusionPath "$env:APPDATA\npm", "$env:APPDATA\npm-cache", "$env:LOCALAPPDATA\npm-cache"
+  ```
+- `better-sqlite3` is an **optional** native module. If it fails to build, that is not a broken
+  install — only `vidfarm clips` (the local clip library) is unavailable. Everything else,
+  including local render, works. To enable it, install "Desktop development with C++" from
+  the Visual Studio Installer and reinstall.
+- Windows on ARM has no prebuilt ffmpeg/ffprobe. Install a system ffmpeg and put it on PATH.
+
 Work in **one folder per brand or offer** (`~/vidfarm/<brand>/`). Run every command from it, or pass `--dir`. Strategy documents, `STORYBOARD.md`, `brand-assets/`, `raws/` and `renders/` all land there, so a session weeks later reads the history back instead of re-interviewing the user.
 
 **If that folder already exists, read `CONTEXT.md` and `OFFER.md` before you ask the user anything.**
@@ -66,9 +89,11 @@ vidfarm publish <forkId>                                 # push edits back to th
 | "Give me a consultation" | the `brainstorm/*` chain: cold-start → awareness stages → angles → hooks. No AI key: `vidfarm consult` prints the prompt for **you** to answer, $0 | `references/onboarding.md` |
 | "Find a template and start" | `vidfarm templates search` → `fork` → `pull` | `references/core-workflows.md`, `recipes/find-and-fork-template.md` |
 | "Change / re-theme this video" | timeline edits, decompose, captions | `references/editor-workflows.md`, `recipes/retheme-template.md` |
-| "Find footage / a clip of X" | public raws → own library → `vidfarm video-search "<the shot>"` (paid, $0.0003/call) → generate last | `references/assets-and-sourcing.md` |
+| "Find footage / a clip of X" | public raws → own library → `vidfarm browse videos "<the shot>"` (free, your Chrome) or `vidfarm video-search` (paid, $0.0003/call) → generate last | `references/assets-and-sourcing.md` |
+| "Make a graphic / sticker / illustration" in cost mode `minimize` | free stock → IconScout → `vidfarm mask` → **generate it with YOUR OWN image tool if this subscription includes one** (Antigravity / Gemini CLI, Codex / ChatGPT — Claude Code has none): `vidfarm agent-image "<subject>"`. $0, and no `--yes` needed | `references/agent-included-imagegen.md` |
+| A free plan / a 402 / cost mode `minimize` on any search or download | `vidfarm browser setup`, then `vidfarm browse videos\|images\|news\|page "<q>"`. Never answer a sourcing ask with "that needs a paid plan." | `references/browser-harness.md` |
 | "Make a video about what just happened" | two stages: `vidfarm news-search "<topic>" --fresh w` for the STORY, then `video-search` for the VISUALS | `vidfarm.cc/experimental/google-news-to-video.md` |
-| "Download this video from `<url>`" | `vidfarm download-video <url>` (paid). Free plan gets a 402 — have the user download it in Chrome, then `vidfarm put-file`. Never answer "I can't." | `references/assets-and-sourcing.md` |
+| "Download this video from `<url>`" | `vidfarm download-video <url>` (paid). Free plan gets a 402 — `vidfarm browse page "<url>"` and save it from their Chrome yourself, else have them download it, then `vidfarm put-file`. Never answer "I can't." | `references/browser-harness.md` |
 | "Turn this thread / subreddit / profile into a video" | `vidfarm recycle <source>` — returns the raw decomposition, unranked; you pick the hook (paid) | `references/assets-and-sourcing.md` |
 | "Create an avatar / spokesperson / talking head" | `vidfarm avatar "<who>" --say "<line>"` — a greenscreen talking-head video, keyed in the same job | `references/primitives.md` |
 | "TTS / music / captions / background removal" | the primitive catalog | `references/primitives.md` |
@@ -101,12 +126,26 @@ AI charges go to the user's own provider keys (`vidfarm add-provider-key`), not
 
 Two consequences worth stating out loud: `minimize + interactive` still gets custom art, for $0. `minimize + autonomous` gets none. Voice samples (`vidfarm voices --sample`, `--free --sample`) are free on both tiers — offer them either way.
 
+## 5b. Production has phases — plan, collect, build
+
+**Do not open the timeline before you know what footage you have.** Building to a shot you assumed existed is the most expensive mistake available: you either pay to generate it or rewrite a beat you already built. Four phases, in order — plan the shot list (`vidfarm storyboard --init`), collect assets for **every** beat in one pass, build, then review and cut.
+
+The collection phase is where the cost mode actually bites:
+
+- **`minimize`** — collection *is* the job, and being cheap is not being worse. Work the ladder: `public-raws --categories` → `media search` / `iconscout --free` → `raws search` (what they already own) → **browser control** (`vidfarm browse videos "<the shot>"`, $0) → mine it with `raws scan` / `clipper`. One long source cut eight ways beats one generated clip.
+- **`minimize` + `interactive`** — buy quality with the user's hands, not their wallet. Direct them like an editor: hand over the shot list and let them pick clips themselves (`vidfarm handoff raws`), and hand over ONE prompt for a free web image generator to get a whole sticker sheet back (`vidfarm handoff image` → `vidfarm sticker-pack`). Both beat anything autonomous, at $0.
+- **`hybrid`** — collect free first, then spend on the gaps only. AI image generation for the hero graphic, `vidfarm avatar` for a presenter; keep AI *video* for beats nothing static can carry.
+- **`rich-ai` / `pure-videogen`** — collection becomes generation, and moves earlier. `rich-ai` mints reusable greenscreen raws that get keyed once and saved to the library; `pure-videogen` runs script → storyboard stills → scene-by-scene (`vidfarm sequence`). Even here, search what already exists before generating it.
+
+Say the phase out loud when you switch. Deciding to source mid-build is how a $0 video turns into a $3 one.
+
 ## 6. Standards — these override your defaults
 
 The standards themselves are not optional. `vidfarm qa <dir>` is — it is a free local checker for most of them, feedback rather than a gate. Nothing calls it, skipping it is fine, and it allows one fix round by default. **Watching the render is the review that counts.** Full reasoning: `references/hooks-and-virality.md` and `references/reviewing-renders.md`.
 
 - **Write the four charges before the timeline.** Hook: first line is a complete clause naming a situation, on screen at `start:0`. Loop: one open question by 0:10, closing inside this video. Payoff: shown, not summarized. Bait: one ask, final beat. Banned openers — throat-clearing, a logo, a title card, a fade from black.
 - **No HTML slop.** Test: could you have made this element inside TikTok's own editor? If you reached past that — a padded capsule, border, gradient fill, blur panel, card, CTA "button", benefit chips, feature grid — cut it. Nothing in a video is clickable. Emphasize with size, weight, caps, an accent colour, or a drawn mark.
+- **No layout templates — judge the whole frame.** The stack is the tell, not the box: headline + subheadline + CTA centred in a well is a landing page even with every border, fill and capsule stripped off. Banned at frame level — a modal/dialog floating over a dimmed or blurred backdrop, a full-frame wash used to stage a floating block, nav/hero/feature-row sections, a blurred website screenshot as the background plate, document margins. Unstack it into time: hook at t=0, support line on the next cut, CTA spoken or a bare caption. Are you arranging words relative to each other, or relative to the picture? Two text runs at once is the ceiling.
 - **Captions**: imported display font (Montserrat 700–900 default), ~36–64px on a 1080 frame, inside the 8%–85% safe zone, and within that band placed in the **emptiest part of the frame**. Long narration pages into 3–5-word cues. Exactly one of four backgrounds: `outline`, `plain`, active-word `spotlight`/`karaoke`, or a tight `highlight-solid` band.
 - **The first frame is the thumbnail.** A real visual and the hook words at `start:0`. No fade-up, no entrance transition on the first clip. Check with `vidfarm stills <dir> --at 0`.
 - **Cut ruthlessly.** First assembly is 30–50% too long. Delete every beat that the video survives without, then ripple the hole closed. Length is an output, not a target.
@@ -140,6 +179,8 @@ Otherwise fetch `https://vidfarm.cc/skill-pack/vidfarm/files/<path>`. Load one f
 | `references/core-workflows.md` | discovery, auth, fork/publish/share, cost spectrum, dedupe |
 | `references/editor-workflows.md` | timeline editing, decompose, captions, the replication harnesses *(largest file)* |
 | `references/assets-and-sourcing.md` | Google search for footage, raws hunts, My Files, recurring characters, downloads |
+| `references/agent-included-imagegen.md` | free custom art — image generation the AGENT's own subscription already includes, and why cost mode `minimize` allows it |
+| `references/browser-harness.md` | free-plan sourcing and cost mode `minimize` — driving the user's Chrome as the $0 substitute for the paid search/download primitives |
 | `references/automation-and-local-dev.md` | REST + devcli command table, scripting mode, the local serve loop |
 | `references/hooks-and-virality.md` | before writing any hook, caption script, or re-theme |
 | `references/reviewing-renders.md` | before reporting a video as done |
@@ -150,4 +191,4 @@ Otherwise fetch `https://vidfarm.cc/skill-pack/vidfarm/files/<path>`. Load one f
 | `recipes/*.md` | `find-and-fork-template` · `retheme-template` · `local-edit-render-approve` · `onboard-a-new-director` · `bulk-scripting-with-a-harness` · `cutout-graphics-for-explainers` |
 | `harnesses/README.md` | anything harness-shaped — start here. Bases: `short-form` · `hooks` · `ugc-testimonial` · `explainer` · `product-demo` · `product-explainer` |
 
-Also served at `vidfarm.cc`: `/experiments.md` (ad testing), `/crowdsourcing.md` (producing a batch with gigworkers), `/update.md` (upgrade runbook), `/experimental` (methods under live testing), `/skill/vidfarm-platform` (architecture), `/skill/hyperframes` (composition-authoring craft — route broad "make me a video" asks here first).
+Also served at `vidfarm.cc`: `/experiments.md` (ad testing), `/marketplace.md` (producing a batch with gigworkers), `/update.md` (upgrade runbook), `/experimental` (methods under live testing), `/skill/vidfarm-platform` (architecture), `/skill/hyperframes` (composition-authoring craft — route broad "make me a video" asks here first).

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,14 @@ 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
+        // marketplace-gigs is imported lazily, so match its "no key yet" error by
+        // name rather than pulling the module into the startup path just for this.
+        || (error instanceof Error && error.name === "GigsAuthMissingError")) {
         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