@officexapp/vidfarm-devcli 0.21.45 → 0.21.46

package/dist/src/devcli/browser-harness.js

@@ -0,0 +1,384 @@
+// `vidfarm browser` — wire the agent's OWN Chrome up as a FREE substitute for
+// the paid cloud search/download primitives.
+//
+// WHY THIS EXISTS. The sourcing ladder in SKILL.md already starts at "your own
+// browser control, if you have it" — but nothing in the devcli ever made that
+// rung real, so every agent fell straight through to `video-search` /
+// `image-search` / `news-search` / `download-video`, all of which are paid
+// plans only. A free-tier director therefore got a 402 for the single most
+// common ask in the product ("find me a clip of X").
+//
+// browser-harness (https://github.com/browser-use/browser-harness) closes that
+// gap: it attaches an LLM to the user's already-running Chrome over one CDP
+// websocket, so the agent can drive Google Images / Google Videos / Google News
+// itself. The session is the user's own logged-in browser, on the user's own
+// IP, at $0. That is a genuine substitute for the paid primitives when the mode
+// is `minimize`, and a cost saver in `hybrid`.
+//
+// This module does NOT reimplement browser-harness. It does three things:
+//   1. detect / install it (`setup`), so "can easily set it up" is one command;
+//   2. report it in `vidfarm doctor` as an optional free capability;
+//   3. mint the exact browse RECIPE for a given sourcing job (`browse`), in the
+//      same house pattern as `vidfarm consult` and `vidfarm handoff` — the
+//      devcli writes the brief, the agent already in this terminal executes it.
+//
+// Nothing here is billed and nothing here needs a Vidfarm account.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { resolveSkillsRoot } from "./skills.js";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+export const BROWSER_HARNESS_REPO = "https://github.com/browser-use/browser-harness";
+/** Where `uv tool install` drops console scripts, per platform. browser-harness
+ *  lands on PATH for most users, but a fresh `uv` install in the same shell has
+ *  not re-hashed PATH yet — so check the well-known bin dirs too rather than
+ *  telling a user who just installed it that it isn't there. */
+function candidateBins() {
+    const home = homedir();
+    const exe = process.platform === "win32" ? "browser-harness.exe" : "browser-harness";
+    const dirs = process.platform === "win32"
+        ? [path.join(home, ".local", "bin"), path.join(home, "AppData", "Roaming", "uv", "tools", "browser-harness", "Scripts")]
+        : [path.join(home, ".local", "bin"), "/usr/local/bin", "/opt/homebrew/bin"];
+    return dirs.map((dir) => path.join(dir, exe));
+}
+function which(command) {
+    const probe = process.platform === "win32" ? "where" : "which";
+    const res = spawnSync(probe, [command], { encoding: "utf8" });
+    if (res.status !== 0)
+        return null;
+    const first = String(res.stdout ?? "").split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+    return first || null;
+}
+export function detectBrowserHarness() {
+    const uv = which("uv");
+    let bin = which("browser-harness");
+    if (!bin)
+        bin = candidateBins().find((candidate) => existsSync(candidate)) ?? null;
+    let version = null;
+    if (bin) {
+        const res = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 20_000 });
+        const out = `${res.stdout ?? ""}${res.stderr ?? ""}`.trim();
+        version = out ? out.split(/\r?\n/)[0].trim() : null;
+    }
+    return { bin, version, uv };
+}
+/** One line for `vidfarm doctor`. Never a failure — this is an OPTIONAL free
+ *  capability, and a box without it is a perfectly healthy box. */
+export function browserHarnessDoctorCheck() {
+    const found = detectBrowserHarness();
+    if (found.bin) {
+        return {
+            level: "ok",
+            detail: `${found.bin}${found.version ? ` (${found.version})` : ""} — free browser sourcing available; \`vidfarm browse videos "<shot>"\` for the recipe`
+        };
+    }
+    return {
+        level: "warn",
+        detail: found.uv
+            ? "not installed — the FREE substitute for the paid video-search/image-search/news-search/download-video primitives. Install: `vidfarm browser setup`"
+            : "not installed, and `uv` is missing too — run `vidfarm browser setup` (it prints the one-line uv install first)"
+    };
+}
+const RECIPES = {
+    videos: {
+        replaces: "vidfarm video-search (paid, $0.0003/call)",
+        udm: "7",
+        tbm: "vid",
+        extract: "every off-Google result link with its title and host — YouTube, TikTok, Pexels, Pixabay, Mixkit, archive.org, news sites",
+        next: [
+            "vidfarm raws scan \"<result url>\" --clips 8      # mine short raws out of the best hit",
+            "vidfarm clipper \"<result url>\" --start <t> --end <t>   # one surgical cut instead"
+        ]
+    },
+    images: {
+        replaces: "vidfarm image-search (paid, $0.0003/call)",
+        udm: "2",
+        tbm: "isch",
+        extract: "the SOURCE PAGE url behind each thumbnail (Google lazy-loads full-res, so the thumbnail src is a data: URI and not what you want) — click a result, then read the full-size image url off the detail panel",
+        next: [
+            "vidfarm put-file ./downloaded.png --folder brand-assets --notes \"<what it is, so files --search finds it later>\""
+        ]
+    },
+    news: {
+        replaces: "vidfarm news-search (paid, $0.0003/call)",
+        udm: "12",
+        tbm: "nws",
+        extract: "headline, publisher, timestamp and article url for each story — this is the STORY stage, not the visuals stage",
+        next: [
+            "# then a SECOND pass for the visuals — never one query for both:",
+            "vidfarm browse videos \"<the thing the story is about>\""
+        ]
+    },
+    page: {
+        replaces: "vidfarm download-video / download-audio (paid, wallet-billed resolver)",
+        udm: null,
+        tbm: null,
+        extract: "the media element itself — `document.querySelectorAll('video source, video')` for the src, or CDP `Network.getResponseBody` on the media request; a logged-in session sees what an anonymous resolver cannot",
+        next: [
+            "vidfarm put-file ./saved.mp4 --folder raws-inbox      # bring the local file in for $0",
+            "vidfarm clipper ./saved.mp4 --start <t> --end <t>     # or clip it straight away"
+        ]
+    }
+};
+function googleUrl(mode, query, legacy) {
+    const recipe = RECIPES[mode];
+    const q = encodeURIComponent(query);
+    if (!recipe.udm && !recipe.tbm)
+        return query.startsWith("http") ? query : `https://www.google.com/search?q=${q}`;
+    const surface = legacy ? `tbm=${recipe.tbm}` : `udm=${recipe.udm}`;
+    return `https://www.google.com/search?q=${q}&${surface}`;
+}
+/** The heredoc an agent runs. Deliberately short: browser-harness's own SKILL.md
+ *  teaches the AX-tree-first workflow, and we do not want to fight it with a
+ *  brittle selector script that Google will break next month. */
+function browseScript(mode, query, legacy, limit) {
+    const url = googleUrl(mode, query, legacy);
+    if (mode === "page") {
+        return [
+            "browser-harness <<'PY'",
+            `new_tab(${JSON.stringify(query)})`,
+            "wait_for_load()",
+            "print(page_info())",
+            "print(js(\"JSON.stringify([...document.querySelectorAll('video, video source')].map(n => n.currentSrc || n.src).filter(Boolean))\"))",
+            "PY"
+        ].join("\n");
+    }
+    return [
+        "browser-harness <<'PY'",
+        `new_tab(${JSON.stringify(url)})`,
+        "wait_for_load()",
+        "# Result links, deduped, Google's own chrome stripped out.",
+        "print(js(\"\"\"JSON.stringify(",
+        "  [...document.querySelectorAll('a[href^=\\\"http\\\"]')]",
+        "    .map(a => ({ url: a.href, title: (a.innerText || '').trim().split('\\\\n')[0] }))",
+        "    .filter(r => !/(^|\\\\.)google\\\\.com$/.test(new URL(r.url).hostname) && r.title)",
+        "    .filter((r, i, all) => all.findIndex(o => o.url === r.url) === i)",
+        `    .slice(0, ${limit})`,
+        ")\"\"\"))",
+        "PY"
+    ].join("\n");
+}
+function renderBrowseRecipe(mode, query, legacy, limit, installed) {
+    const recipe = RECIPES[mode];
+    const lines = [];
+    lines.push(`${BOLD}Free browser sourcing — ${mode}${RESET}  ${DIM}(replaces ${recipe.replaces})${RESET}`);
+    lines.push("");
+    if (!installed) {
+        lines.push(`${YELLOW}browser-harness is not installed yet.${RESET} Run ${BOLD}vidfarm browser setup${RESET} first — one command, no account, no key.`);
+        lines.push("");
+    }
+    lines.push(`${BOLD}1. Open it${RESET}`);
+    lines.push("");
+    lines.push(browseScript(mode, query, legacy, limit));
+    lines.push("");
+    lines.push(`${BOLD}2. Pull off the page${RESET}`);
+    lines.push(`   ${recipe.extract}`);
+    lines.push("");
+    lines.push(`${BOLD}3. Feed it forward${RESET}`);
+    for (const step of recipe.next)
+        lines.push(`   ${step}`);
+    lines.push("");
+    lines.push(`${DIM}Prefer the accessibility tree over screenshots — cdp("Accessibility.getFullAXTree"). If a`);
+    lines.push(`selector above comes back empty, Google changed its markup: read the AX tree and adapt,`);
+    lines.push(`don't retry the same query. Legacy surface param: rerun with --legacy (tbm=… instead of udm=…).${RESET}`);
+    lines.push("");
+    lines.push(`${DIM}A public result is not a licensed asset. Keep the source URL and the licence page for`);
+    lines.push(`anything that reaches a client render.${RESET}`);
+    return lines.join("\n");
+}
+// ── setup ───────────────────────────────────────────────────────────────────
+function runSetup(opts) {
+    const before = detectBrowserHarness();
+    console.log(`${BOLD}vidfarm browser setup${RESET} — free browser sourcing via browser-harness`);
+    console.log(`${DIM}${BROWSER_HARNESS_REPO}${RESET}`);
+    console.log("");
+    if (!before.uv) {
+        console.log(`${YELLOW}Step 0 — install uv (the Python tool installer browser-harness ships through):${RESET}`);
+        console.log(process.platform === "win32"
+            ? '  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"'
+            : "  curl -LsSf https://astral.sh/uv/install.sh | sh");
+        console.log("");
+        console.log("Then re-run `vidfarm browser setup`.");
+        return 1;
+    }
+    const install = ["tool", "install", "--python", "3.12", "--upgrade", "--force", "browser-harness"];
+    console.log(`${BOLD}Step 1 — install/upgrade browser-harness${RESET}`);
+    console.log(`  uv ${install.join(" ")}`);
+    if (opts.dryRun) {
+        console.log(`${DIM}  (--dry-run: not executed)${RESET}`);
+    }
+    else {
+        const res = spawnSync(before.uv, install, { stdio: "inherit" });
+        if (res.status !== 0) {
+            console.error(`${YELLOW}uv tool install failed (exit ${res.status}). Run the command above by hand to see why.${RESET}`);
+            return 1;
+        }
+    }
+    console.log("");
+    const found = opts.dryRun ? before : detectBrowserHarness();
+    const bin = found.bin ?? "browser-harness";
+    // Step 2 — register browser-harness's OWN skill next to the vidfarm pack, so
+    // the agent reading .agents/skills finds the browser workflow without a
+    // network fetch. `browser-harness skill` prints the canonical body; we never
+    // author or paraphrase it here.
+    const skillRoot = opts.skillDir ? path.resolve(process.cwd(), opts.skillDir) : resolveSkillsRoot();
+    const skillDir = path.join(skillRoot, ".agents", "skills", "browser-harness");
+    const skillFile = path.join(skillDir, "SKILL.md");
+    console.log(`${BOLD}Step 2 — register the browser-harness skill${RESET}`);
+    console.log(`  ${skillFile}`);
+    if (opts.dryRun) {
+        console.log(`${DIM}  (--dry-run: not written)${RESET}`);
+    }
+    else {
+        const res = spawnSync(bin, ["skill"], { encoding: "utf8", timeout: 60_000 });
+        const body = String(res.stdout ?? "").trim();
+        if (res.status === 0 && body) {
+            mkdirSync(skillDir, { recursive: true });
+            writeFileSync(skillFile, `${body}\n`, "utf8");
+            console.log(`  ${GREEN}written${RESET}`);
+        }
+        else {
+            console.log(`  ${YELLOW}\`${bin} skill\` produced nothing — register it by hand: \`${bin} skill > ${skillFile}\`${RESET}`);
+        }
+    }
+    console.log("");
+    // Step 3 — the one manual step. Chrome will not expose CDP until the user
+    // ticks the box, and no amount of tooling can do it for them.
+    console.log(`${BOLD}Step 3 — let Chrome be driven (one-time, the user must do this)${RESET}`);
+    console.log("  1. Open Chrome → chrome://inspect/#remote-debugging");
+    console.log('  2. Tick "Allow remote debugging for this browser instance"');
+    console.log(`  3. macOS only, if a permission sheet appears: ${bin} mac-approve`);
+    console.log("");
+    console.log(`${BOLD}Step 4 — verify${RESET}`);
+    console.log(`  ${bin} <<'PY'`);
+    console.log("  print(page_info())");
+    console.log("  PY");
+    console.log(`  ${DIM}(if it fails: ${bin} --doctor)${RESET}`);
+    console.log("");
+    console.log(`${GREEN}Then this is free:${RESET}`);
+    console.log('  vidfarm browse videos "warehouse worker packing orders POV 4K"   # was: video-search, paid');
+    console.log('  vidfarm browse images "manila street market wide shot"           # was: image-search, paid');
+    console.log('  vidfarm browse news   "AI startup funding announced"             # was: news-search, paid');
+    console.log('  vidfarm browse page   "https://…"                                # was: download-video, paid');
+    console.log("");
+    console.log(`${DIM}Recordings are OFF by default and stay off unless the user asks — they capture page`);
+    console.log(`content to disk. \`${bin} recordings\` shows the current preference.${RESET}`);
+    return 0;
+}
+function printStatus() {
+    const found = detectBrowserHarness();
+    console.log(`${BOLD}browser-harness${RESET}  ${DIM}— free substitute for the paid search/download primitives${RESET}`);
+    console.log("");
+    console.log(`  uv               ${found.uv ? `${GREEN}${found.uv}${RESET}` : `${YELLOW}not found${RESET}`}`);
+    console.log(`  browser-harness  ${found.bin ? `${GREEN}${found.bin}${RESET}${found.version ? ` ${DIM}(${found.version})${RESET}` : ""}` : `${YELLOW}not installed${RESET}`}`);
+    console.log("");
+    if (!found.bin) {
+        console.log(`Install it with ${BOLD}vidfarm browser setup${RESET} — no account, no API key, ~1 minute.`);
+        console.log(`${DIM}It replaces video-search / image-search / news-search / download-video, all of which are`);
+        console.log(`paid plans only. In cost mode \`minimize\` this is the difference between sourcing footage`);
+        console.log(`and telling the user you can't.${RESET}`);
+        return 0;
+    }
+    console.log(`Connection check: ${BOLD}${found.bin} --doctor${RESET}`);
+    console.log(`Browse recipes:  ${BOLD}vidfarm browse <videos|images|news|page> "<query>"${RESET}`);
+    return 0;
+}
+export async function runBrowserHarnessCommand(argv) {
+    const sub = (argv[0] ?? "status").toLowerCase();
+    const rest = argv.slice(1);
+    if (sub === "setup" || sub === "install") {
+        const parsed = parseArgs({
+            args: rest,
+            allowPositionals: false,
+            options: { "dry-run": { type: "boolean", default: false }, dir: { type: "string" } }
+        });
+        const code = runSetup({ dryRun: Boolean(parsed.values["dry-run"]), skillDir: parsed.values.dir });
+        if (code !== 0)
+            process.exitCode = code;
+        return;
+    }
+    if (sub === "doctor") {
+        const found = detectBrowserHarness();
+        if (!found.bin) {
+            printStatus();
+            return;
+        }
+        const res = spawnSync(found.bin, ["--doctor"], { stdio: "inherit" });
+        if (res.status !== 0)
+            process.exitCode = res.status ?? 1;
+        return;
+    }
+    if (sub === "status" || sub === "" || sub === "--help" || sub === "-h") {
+        printStatus();
+        return;
+    }
+    // `vidfarm browser videos "…"` is the same thing as `vidfarm browse videos "…"`.
+    if (sub === "videos" || sub === "images" || sub === "news" || sub === "page") {
+        await runBrowseCommand(argv);
+        return;
+    }
+    throw new Error(`Unknown browser subcommand "${sub}". Use: status | setup | doctor, or \`vidfarm browse <videos|images|news|page> "<query>"\`.`);
+}
+export async function runBrowseCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            limit: { type: "string", default: "40" },
+            legacy: { type: "boolean", default: false },
+            // Pipe the script straight into browser-harness instead of printing it.
+            // Off by default: the recipe is meant to be ADAPTED (Google's markup
+            // moves), and an agent that reads it first gets better results than one
+            // that runs it blind.
+            run: { type: "boolean", default: false },
+            json: { type: "boolean", default: false }
+        }
+    });
+    const positionals = parsed.positionals ?? [];
+    const mode = String(positionals[0] ?? "").toLowerCase();
+    const query = positionals.slice(1).join(" ").trim();
+    if (!["videos", "images", "news", "page"].includes(mode) || !query) {
+        throw new Error('Usage: vidfarm browse <videos|images|news|page> "<query or url>" [--limit 40] [--legacy] [--run]\n' +
+            '  videos → replaces the paid video-search · images → image-search · news → news-search · page → download-video');
+    }
+    const limit = Math.max(1, Math.min(200, Number(parsed.values.limit) || 40));
+    const legacy = Boolean(parsed.values.legacy);
+    const found = detectBrowserHarness();
+    if (parsed.values.json) {
+        console.log(JSON.stringify({
+            mode,
+            query,
+            installed: Boolean(found.bin),
+            bin: found.bin,
+            replaces: RECIPES[mode].replaces,
+            url: googleUrl(mode, query, legacy),
+            script: browseScript(mode, query, legacy, limit),
+            extract: RECIPES[mode].extract,
+            next: RECIPES[mode].next
+        }, null, 2));
+        return;
+    }
+    if (parsed.values.run) {
+        if (!found.bin) {
+            throw new Error("--run needs browser-harness. Install it with `vidfarm browser setup`, or drop --run to print the recipe.");
+        }
+        // Feed the PY body (not the wrapper) to the binary on stdin, exactly as the
+        // heredoc would.
+        const script = browseScript(mode, query, legacy, limit)
+            .split("\n")
+            .slice(1, -1)
+            .join("\n");
+        const res = spawnSync(found.bin, [], { input: `${script}\n`, stdio: ["pipe", "inherit", "inherit"] });
+        if (res.status !== 0)
+            process.exitCode = res.status ?? 1;
+        return;
+    }
+    console.log(renderBrowseRecipe(mode, query, legacy, limit, Boolean(found.bin)));
+}
+//# sourceMappingURL=browser-harness.js.map

package/dist/src/devcli/clip-store.js

@@ -6,8 +6,7 @@
 //   ~/.vidfarm/clips/<id>.mp4    clip files
 //   ~/.vidfarm/thumbs/<id>.jpg   thumbnails
 // Override the base dir with VIDFARM_HOME.
-import Database from "better-sqlite3";
-import * as sqliteVec from "sqlite-vec";
+import { createRequire } from "node:module";
 import { existsSync, mkdirSync, rmSync } from "node:fs";
 import path from "node:path";
 import { homedir } from "node:os";
@@ -27,6 +26,44 @@ export function resolveClipStorePaths(baseOverride) {
         workDir: path.join(base, "scan-tmp")
     };
 }
+const requireFrom = createRequire(import.meta.url);
+let cachedSqlite;
+/**
+ * A missing OPTIONAL native module is an expected environment condition, not a
+ * bug — cli.ts prints the message without a stack and skips the crash report,
+ * the same treatment LocalModeUnavailableError gets.
+ */
+export class NativeModuleUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NativeModuleUnavailableError";
+    }
+}
+/**
+ * Load the optional native SQLite stack, or throw a message that names the
+ * actual fix. Called from the ClipStore constructor, never at import time.
+ */
+function loadSqlite() {
+    if (cachedSqlite)
+        return cachedSqlite;
+    try {
+        const mod = requireFrom("better-sqlite3");
+        const ctor = (typeof mod === "function" ? mod : mod.default);
+        const sqliteVec = requireFrom("sqlite-vec");
+        return (cachedSqlite = { Database: ctor, sqliteVec });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.split("\n")[0] : String(error);
+        throw new NativeModuleUnavailableError("The local clip library needs the optional native module `better-sqlite3`, which is not built on this machine.\n" +
+            "  Everything else in vidfarm works without it — only `vidfarm clips` does not.\n" +
+            "  To enable it, install a C++ toolchain and reinstall:\n" +
+            "    Windows : npm i -g windows-build-tools   (or install \"Desktop development with C++\" from the Visual Studio Installer)\n" +
+            "    macOS   : xcode-select --install\n" +
+            "    Linux   : apt install build-essential python3\n" +
+            "  Then: npm i -g @officexapp/vidfarm-devcli\n" +
+            `  Underlying load error: ${detail}`);
+    }
+}
 export class ClipStore {
     paths;
     db;
@@ -36,7 +73,8 @@ export class ClipStore {
         mkdirSync(this.paths.base, { recursive: true });
         mkdirSync(this.paths.clipsDir, { recursive: true });
         mkdirSync(this.paths.thumbsDir, { recursive: true });
-        this.db = new Database(this.paths.db);
+        const { Database: DatabaseCtor, sqliteVec } = loadSqlite();
+        this.db = new DatabaseCtor(this.paths.db);
         this.db.pragma("journal_mode = WAL");
         sqliteVec.load(this.db);
         this.dim = this.initSchema();

package/dist/src/devcli/cost-mode.js

@@ -7,7 +7,11 @@
 // their AI agent up front), then every billed command respects it:
 //   - minimize : ~$0 per video. Never burn AI credits by surprise. Prefer free
 //                local engines; refuse billed cloud/AI ops unless the user
-//                re-confirms (--yes).
+//                re-confirms (--yes). NOTE this does not mean "no AI at all":
+//                if the AGENT driving the terminal has image generation included
+//                in its own subscription (Antigravity / Gemini CLI, Codex /
+//                ChatGPT — Claude Code does not), it should generate the graphic
+//                itself for $0 rather than go without. See agent-imagegen.ts.
 //   - hybrid   : roughly $0.01–$1 per video. Free where it's free, spend on AI
 //                only where it clearly wins. (default recommendation.) Billed
 //                ops run but print a cost line.
@@ -134,9 +138,15 @@ export const COST_MODE_BLURB = {
         'For any ICON, STICKER, illustration, 3D prop or Lottie, use vidfarm iconscout "<meaning>" ' +
         "--free before even considering AI image generation: free IconScout assets cost $0 (a credit " +
         "line is the only price) and arrive as clean transparent vectors. " +
+        "$0 does NOT mean no AI: if YOUR OWN agent subscription already includes image generation " +
+        "(Google Antigravity / Gemini CLI, OpenAI Codex / ChatGPT — Claude Code does not, Anthropic " +
+        'ships no image model), generate the graphic yourself — `vidfarm agent-image "<subject>"` ' +
+        "prints the prompt, the plate rules and the import command. It is free in minimize. " +
         "Billed cloud/AI generation is refused unless you re-confirm it (--yes).",
     hybrid: "Hybrid (recommended) — roughly $0.01–$1 per video. Free where it's free, spend AI " +
         "credits only where they clearly win (a hero shot, a voice you can't fake locally). " +
+        'If your own agent subscription includes image generation, use it first (`vidfarm agent-image "<subject>"`) — ' +
+        "it costs nothing extra and leaves the budget for the shots only Vidfarm can make. " +
         'Never GENERATE an icon, sticker, illustration or 3D prop — vidfarm iconscout "<meaning>" ' +
         "buys a designer's finished asset for a fraction of one AI attempt, with no prompt loop. " +
         "Billed ops run but each prints its cost so nothing is a surprise. Charges land on " +
@@ -171,6 +181,10 @@ export function costModeExplainer() {
         "                    frame-by-frame scene generation. Most cinematic, most expensive.",
         "Any spend is billed to YOUR own AI provider keys (BYOK) — add them with",
         "  `vidfarm add-provider-key <provider> <key>` or at vidfarm.cc/settings/developer.",
+        "Even minimize can make custom art: if the AI agent you are talking to has image generation",
+        "  included in its own subscription (Google Antigravity / Gemini CLI, OpenAI Codex / ChatGPT —",
+        "  Claude Code does not), it generates the graphic itself for $0 extra. Ask it to run",
+        '  `vidfarm agent-image "<subject>" --items "a,b,c"`.',
         "Tip: before paying to generate music/SFX/images/video, try the free stock catalog —",
         '  vidfarm media search "<meaning>" --type bgm|sfx|image|vector|icon|video.',
         "  For icons, STICKERS, illustrations, 3D props and Lottie, IconScout beats AI generation on price",
@@ -200,14 +214,20 @@ export class CostModeBlockedError extends Error {
  *   nudge once so the default posture really is "ask before spending."
  */
 export function assertBilledAllowed(input) {
-    const { resolved, yes, json, label, estimate, freeAlternative } = input;
+    const { resolved, yes, json, label, estimate, freeAlternative, agentAlternative } = input;
     const log = input.log ?? ((line) => console.error(line));
     const cost = estimate ? ` (${estimate})` : "";
     if (resolved.mode === "minimize" && !yes) {
+        const agentAlt = agentAlternative ? `\nDo it yourself for $0: ${agentAlternative}` : "";
         const alt = freeAlternative ? `\nFree alternative: ${freeAlternative}` : "";
         throw new CostModeBlockedError(`Blocked by cost mode "minimize": ${label}${cost} spends billed AI credits.\n` +
             `Confirm the spend with the user, then re-run with --yes (or switch modes: ` +
-            `vidfarm cost-mode hybrid).${alt}`);
+            `vidfarm cost-mode hybrid).${agentAlt}${alt}`);
+    }
+    // Not blocked, but still worth saying: a capability the agent already pays for
+    // beats one Vidfarm bills for, in every mode below rich-ai.
+    if (!json && agentAlternative && (resolved.mode === "hybrid" || !resolved.isSet)) {
+        log(`[cost] Cheaper first: ${agentAlternative}`);
     }
     if (json)
         return;

package/dist/src/devcli/doctor.js

@@ -8,6 +8,7 @@
 // unconditionally at session start.
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
 import net from "node:net";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -17,6 +18,7 @@ import { hasFfmpeg, resolveFfmpeg, resolveFfprobe } from "../services/clip-curat
 import { resolveHyperframesCli } from "./hyperframes-cli.js";
 import { applyVidfarmStudioBrand } from "./studio-brand.js";
 import { resolveSkillsRoot } from "./skills.js";
+import { browserHarnessDoctorCheck } from "./browser-harness.js";
 import { readStoredAuth } from "./auth-store.js";
 import { scanLocalServers, reapProcesses } from "./process-scan.js";
 const GREEN = "\x1b[32m";
@@ -47,6 +49,24 @@ function isPortInUse(port) {
         server.listen(port, "127.0.0.1");
     });
 }
+// Windows installs Chrome/Edge under one of three roots depending on whether it
+// was a per-machine or per-user install. Without these the check ALWAYS reported
+// "no Chrome" on Windows, and agents went off installing a browser the user
+// already had. Edge is included because it is Chromium and always present.
+function windowsChromeCandidates() {
+    const roots = [
+        process.env["PROGRAMFILES"],
+        process.env["PROGRAMFILES(X86)"],
+        process.env.LOCALAPPDATA
+    ].filter((value) => Boolean(value?.trim()));
+    const relative = [
+        ["Google", "Chrome", "Application", "chrome.exe"],
+        ["Google", "Chrome Beta", "Application", "chrome.exe"],
+        ["Chromium", "Application", "chrome.exe"],
+        ["Microsoft", "Edge", "Application", "msedge.exe"]
+    ];
+    return roots.flatMap((root) => relative.map((parts) => path.join(root, ...parts)));
+}
 // Best-effort Chrome availability for the in-process HyperFrames render:
 // explicit env overrides, the puppeteer download cache, or a system Chrome.
 function detectChromeForRender() {
@@ -66,7 +86,9 @@ function detectChromeForRender() {
     }
     const systemCandidates = process.platform === "darwin"
         ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium"]
-        : ["/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"];
+        : process.platform === "win32"
+            ? windowsChromeCandidates()
+            : ["/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"];
     for (const candidate of systemCandidates) {
         if (existsSync(candidate))
             return { found: true, detail: candidate };
@@ -154,6 +176,11 @@ export async function runDoctorCommand(argv) {
     // 4. Chrome for the in-process render (stills / serve local render).
     const chrome = detectChromeForRender();
     add("chrome", chrome.found ? "ok" : "warn", chrome.found ? chrome.detail : `${chrome.detail} — local render/stills will try to download one on first run`);
+    // 4b. browser-harness — OPTIONAL, and the only free substitute for the paid
+    // search/download primitives. Reported even when absent because a free-plan
+    // user who doesn't know it exists gets a 402 instead of footage.
+    const browserHarness = browserHarnessDoctorCheck();
+    add("browser control", browserHarness.level, browserHarness.detail);
     // 5. Vidfarm cloud auth — --api-key / env, else the persisted `vidfarm login`
     // (auth-store), which is how most users authenticate. Without the store
     // lookup a logged-in user got a false "VIDFARM_API_KEY not set" warning.
@@ -175,9 +202,31 @@ export async function runDoctorCommand(argv) {
     add("provider keys", presentKeys.length > 0 ? "ok" : "warn", presentKeys.length > 0
         ? presentKeys.join(", ")
         : "none of OPENAI/GEMINI/OPENROUTER/ELEVENLABS_API_KEY set — BYOK speech/clip tagging unavailable (keyless local engines still work)");
-    // 7. Local agent CLI (claude / codex) for clips scan etc.
+    // 7. Local agent CLI (claude / codex) for clips scan etc. On Windows the CLI
+    // is a .cmd shim and the scan passes a multi-line prompt as an argv, which a
+    // cmd.exe command line cannot carry — so report the limit rather than
+    // claiming a path that fails at use time.
     const agent = detectLocalAgent();
-    add("agent CLI", agent ? "ok" : "warn", agent ? `${agent.kind} (${agent.bin})` : "no claude/codex CLI on PATH — `clips scan` falls back to provider keys");
+    if (agent && process.platform === "win32") {
+        add("agent CLI", "warn", `${agent.kind} found (${agent.bin}) but agent-driven \`clips scan\` is not supported on Windows yet — use provider keys (OPENAI/GEMINI_API_KEY)`);
+    }
+    else {
+        add("agent CLI", agent ? "ok" : "warn", agent ? `${agent.kind} (${agent.bin})` : "no claude/codex CLI on PATH — `clips scan` falls back to provider keys");
+    }
+    // 7b. The local clip library rides on the OPTIONAL native module
+    // better-sqlite3. It is optional precisely because a Windows box with no C++
+    // toolchain cannot build it — report that here instead of letting
+    // `vidfarm clips` be the thing that discovers it.
+    try {
+        createRequire(import.meta.url)("better-sqlite3");
+        add("clip library", "ok", "better-sqlite3 native module loaded (`vidfarm clips` available)");
+    }
+    catch {
+        add("clip library", "warn", "optional native module better-sqlite3 is not built — only `vidfarm clips` is affected; everything else works. " +
+            (process.platform === "win32"
+                ? "To enable it, install \"Desktop development with C++\" from the Visual Studio Installer, then reinstall the devcli."
+                : "To enable it, install a C++ toolchain (macOS: xcode-select --install; Linux: apt install build-essential python3), then reinstall the devcli."));
+    }
     // 8. Poisoned-env traps.
     if (process.env.AWS_PROFILE?.trim()) {
         add("env AWS_PROFILE", "warn", `AWS_PROFILE=${process.env.AWS_PROFILE} is set — it can hijack AWS SDK auth; run \`env -u AWS_PROFILE\` or unset it`);

package/dist/src/devcli/hyperframes-cli.js

@@ -74,11 +74,21 @@ export async function runHyperframesCommand(subcommand, args, opts = {}) {
     const [bin, baseArgs] = cli
         ? [process.execPath, [cli]]
         : ["npx", ["-y", "hyperframes"]];
+    // On Windows `npx` is `npx.cmd`, and Node >= 20.12 refuses to spawn a
+    // .cmd/.bat without a shell (it throws EINVAL, which surfaced here as the
+    // misleading "npx unavailable" error below). Route the FALLBACK through a
+    // shell there. The primary path spawns process.execPath directly and needs
+    // no shell on any platform, so this never touches the normal case.
+    const useShell = !cli && process.platform === "win32";
+    // A shell re-parses the command line, so quote anything with whitespace
+    // (project paths under "C:\Users\Some Name\..." are the common case).
+    const quote = (value) => (useShell && /[\s"&|<>^]/.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value);
     const capture = opts.stdio === "capture";
     return new Promise((resolvePromise, rejectPromise) => {
-        const child = spawn(bin, [...baseArgs, subcommand, ...args], {
+        const child = spawn(bin, [...baseArgs, subcommand, ...args].map(quote), {
             cwd: opts.cwd,
             env,
+            shell: useShell,
             stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit"
         });
         let stdout = "";

package/dist/src/devcli/local-render.js

@@ -19,6 +19,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { prepareProjectMediaForRender } from "../lib/render-media-prep.js";
+import { resolveBundledFfprobe } from "../lib/ffprobe-path.js";
 import { runHyperframesCommand } from "./hyperframes-cli.js";
 import { normalizeTikTokCaptionLayout } from "./composition-edit.js";
 // Same invariant as the backend's forceEvenCompositionDimensions: libx264
@@ -53,13 +54,9 @@ async function producerFfmpegEnv() {
         catch { /* PATH fallback */ }
     }
     if (!process.env.HYPERFRAMES_FFPROBE_PATH?.trim()) {
-        try {
-            const mod = (await import("ffprobe-static"));
-            const resolved = (mod.path ?? mod.default?.path);
-            if (typeof resolved === "string" && resolved && existsSync(resolved))
-                env.HYPERFRAMES_FFPROBE_PATH = resolved;
-        }
-        catch { /* PATH fallback */ }
+        const resolved = resolveBundledFfprobe();
+        if (resolved)
+            env.HYPERFRAMES_FFPROBE_PATH = resolved;
     }
     return env;
 }