@officexapp/vidfarm-devcli 0.21.15 → 0.21.17

package/dist/src/cli.js

@@ -19,6 +19,7 @@ import { formatCompositionLintIssues, lintCompositionHtml } from "./services/com
 import { resolveFfmpeg } from "./services/clip-curation/ffmpeg.js";
 import { parseHyperframesJson, runHyperframesCommand } from "./devcli/hyperframes-cli.js";
 import { renderCompositionStills } from "./devcli/stills.js";
+import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS } from "./devcli/greenscreen-local.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
@@ -27,7 +28,7 @@ import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError, localApiRequest } from "./devcli/local-backend.js";
 import { startLocalFrontendServer, serveShellsPresent } from "./devcli/local-frontend-server.js";
 import { readStoredAuth, writeStoredAuth, clearStoredAuth, hostsMatch } from "./devcli/auth-store.js";
-import { COST_MODES, CostModeBlockedError, assertBilledAllowed, clearStoredCostMode, costModeExplainer, costModeSummaryLine, normalizeCostMode, resolveCostMode, writeStoredCostMode, COST_MODE_BLURB } from "./devcli/cost-mode.js";
+import { CostModeBlockedError, assertBilledAllowed, clearStoredCostMode, costModeExplainer, costModeSummaryLine, normalizeCostMode, resolveCostMode, writeStoredCostMode, COST_MODE_BLURB, COST_MODE_DISPLAY_LIST, costModeDisplayName } from "./devcli/cost-mode.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
 // `serve` command boots the FULL editor locally (single origin, disk-backed
 // records + storage) so power users edit compositions on disk while a browser
@@ -38,7 +39,7 @@ const DEFAULT_PORT = 4321;
 // Agent skill files the `update-skill` command can install from the live host
 // (`GET /skill/<name>`), falling back to the copy bundled in this npm package.
 const SKILL_TARGETS = {
-    "vidfarm-director": { route: "/skill/vidfarm-director", bundled: "SKILL.director.md" },
+    "vidfarm": { route: "/skill/vidfarm", bundled: "SKILL.director.md" },
     "vidfarm-platform": { route: "/skill/vidfarm-platform", bundled: "SKILL.platform.md" }
 };
 // Most commands below are thin wrappers over ONE Vidfarm REST call (the `→`
@@ -71,7 +72,7 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
   logout                    Clear the persisted credential
   whoami                    Show the logged-in account, host, plan, and cost mode
   cost-mode [mode]          Show or set the money-saving preference all billed
-                            commands respect: minimize | hybrid | pure-ai.
+                            commands respect: minimize | hybrid | rich-ai.
                             No arg = show current + explain the three simply.
                             --clear forgets it · --note "<why>" annotates the save.
                             Override per-run with --cost-mode <m> / VIDFARM_COST_MODE;
@@ -210,9 +211,11 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --tolerance <0..1>      Key radius (default 0.3); --softness <0..1> edge feather (0.1)
     --no-despill            Skip edge color-fringe suppression
     --output-format <f>     Image only: png|webp
-    --local                 Run the keyer in-process for FREE (sharp/ffmpeg, no wallet)
-    --cloud                 Force the billed cloud primitive (default when a key is set)
-    --out <file>            Download the transparent result to this path
+    --local                 Key on your machine with bundled ffmpeg for FREE
+                            (no wallet, no account; cloud-parity chroma key) — DEFAULT
+    --cloud                 Force the billed cloud primitive
+    --out <file>            Write the transparent result to this path (local writes
+                            <source>.transparent.png/.webm next to it by default)
   place <dir|composition.html>   Insert media into a local composition
                             (fill a gap, replace a scene, or overlay an AUDIO
                             track) — same clip markup the browser editor makes;
@@ -539,8 +542,8 @@ Account:
 
 Agent skill (install the latest director skill so your AI agent can act):
   update-skill              DEPRECATED installer alias; installs the canonical
-                            multi-file vidfarm-director pack via \`skills add\`.
-                            Use \`vidfarm skills add vidfarm-director\` directly.
+                            multi-file vidfarm pack via \`skills add\`.
+                            Use \`vidfarm skills add vidfarm\` directly.
     --dir <path>            Project root for the canonical pack install
     --print                 Print the generated single-file director rollup
                             (copy/share artifact; not the canonical install)
@@ -632,10 +635,10 @@ Cost spectrum (default to the cheapest approach that works; see SKILL.director.m
   $10+       Heavy AI generation (many/long AI clips, custom characters).
   Notes: image gen is cheap (use freely); AI VIDEO gen is expensive (ask the user
   first). Decompose is a one-time ~$0.10 — or skip it by forking a decomposed template.
-  Set 'vidfarm cost-mode <minimize|hybrid|pure-ai>' once and every billed command
+  Set 'vidfarm cost-mode <minimize|hybrid|rich-ai>' once and every billed command
   (generate, music, decompose, cloud render/TTS/STT/greenscreen, create, replicate)
   respects it: minimize refuses billed spend without --yes and points you at the free
-  local path; hybrid/pure-ai run but print each op's cost. FREE local engines never gate
+  local path; hybrid/rich-ai run but print each op's cost. FREE local engines never gate
   (local render, tts --engine local, stt --engine whisper, remove-greenscreen --local).
 
 Escape hatch — call ANY route directly:
@@ -673,6 +676,7 @@ const FRONTEND = "\x1b[1m\x1b[36m"; // bold cyan — reserved for openable URLs
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
 const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
 const RED = "\x1b[31m";
 const RESET = "\x1b[0m";
 // Referenced by runMarketplaceCommand's SYNCHRONOUS browse path, so it must be
@@ -2974,11 +2978,218 @@ async function runForkCommand(argv) {
     const tId = result.json?.template_id ?? templateId;
     emitResult(result, ctx.json, [["Open editor ", forkId ? editorFrontendUrl(ctx.host, tId, forkId) : null]]);
 }
+// A weak, UNLICENSED fallback guide for free-tier local decompose. It deliberately
+// omits Vidfarm's proprietary methodology (that lives in the paid HARNESS.md) and
+// tells the agent to produce a best-effort decomposition with open reasoning only.
+const WEAK_FREE_DECOMPOSE_GUIDE = `# Local Decompose — Free Tier (weak, unlicensed)
+
+You are on Vidfarm's FREE tier. This is a stripped-down, best-effort decompose guide.
+It does NOT include Vidfarm's licensed decomposition methodology (viral-DNA extraction,
+editor/replication harnesses, the generative character-card→storyboard→animate
+workflow). Expect noticeably weaker results than Vidfarm cloud decompose, and expect
+to burn more of your own desktop-agent tokens iterating to something usable.
+
+Do your honest best from first principles: watch the source, split it into scenes with
+timestamps, transcribe any on-screen text into captions, and write a short summary.
+Fill \`smart-decompose.template.json\` as far as you can — leave the harness/viral-DNA
+sub-objects mostly empty; you are not licensed to Vidfarm's method for those.
+
+To get the FULL licensed harness (much better results, runs on your own tokens, and
+lets you sync the decomposition back to the shared library so others reuse it free),
+subscribe to Vidfarm and re-run \`vidfarm decompose <forkId> --local\`.
+`;
+// The result skeleton the desktop agent fills in and drops at smart-decompose.json.
+// Kept intentionally sparse — the field docs live in HARNESS.md (paid) or the weak
+// guide (free); this is just the shape the sync endpoint coerces.
+const LOCAL_DECOMPOSE_RESULT_TEMPLATE = JSON.stringify({
+    summary: "",
+    durationSeconds: 0,
+    width: 720,
+    height: 1280,
+    scenes: [{ slug: "scene_1", start: 0, duration: 0, label: "", description: "", viral_note: "" }],
+    captions: [{ slug: "caption_1", text: "", start: 0, duration: 0, x: 8, y: 68, width: 84, height: 12, font_size: 0, color: "#ffffff", background: "#000000", background_style: "highlight-translucent", font_family: "", font_weight: 700, viral_note: "" }],
+    viralDna: {},
+    editorHarness: {},
+    replicationHarness: { generative_workflow: { applies: false, steps: [], character_card: {}, storyboard: {}, animation: { default_motion: "ken_burns_static", scenes: [] } } },
+    transcript: null
+}, null, 2);
+function buildLocalDecomposeTask(input) {
+    const syncLine = input.paid
+        ? `4. Sync it back to cloud (shared library): \`vidfarm decompose ${input.forkId} --local --sync --dir ${input.dir}\``
+        : `4. (Sync to cloud is PAID-only. Your free decomposition stays local. Subscribe to contribute it back.)`;
+    return `# Decompose task — fork ${input.forkId}
+
+You are the desktop AI agent. Run this decompose on your OWN tokens.
+
+Source video: ${input.sourceUrl || "(unknown — pass --source <url> or read it from cloud-video-context.json)"}
+${input.contextNote ? `\n${input.contextNote}\n` : ""}
+Steps:
+1. Read ${input.harnessSaved ? "**HARNESS.md** in this folder — it is Vidfarm's LICENSED decomposition methodology (paid). Follow it exactly, including the character-card → storyboard → (ken-burns vs AI-video) generative workflow detection." : "**HARNESS.md** in this folder (free-tier weak guide) and do your honest best."}
+2. Analyze the source video (sample frames, read on-screen text, transcribe audio if any).
+3. Produce **smart-decompose.json** in this folder, matching the shape in smart-decompose.template.json${input.harnessSaved ? " and every rule in HARNESS.md" : ""}. Fill scenes + captions with real timestamps; ${input.harnessSaved ? "fully populate viralDna, editorHarness, and replicationHarness (including replicationHarness.generative_workflow when the template fits the image→video pipeline)." : "fill what you can."}
+${syncLine}
+
+Do NOT invent footage or audio you cannot see/hear. Ground every scene and caption on a real moment.
+`;
+}
+// Resolve the on-disk staging folder for a local decompose (next to the CWD so the
+// desktop agent sees the harness, the task, and drops its smart-decompose.json here).
+function resolveLocalDecomposeDir(forkId, dirFlag) {
+    const raw = typeof dirFlag === "string" && dirFlag.trim() ? dirFlag.trim() : `vidfarm-decompose-${forkId}`;
+    return path.resolve(process.cwd(), raw);
+}
+// Read the caller's paid/subscription status from the self endpoint. Used to gate
+// the licensed harness fetch and to warn free users before a weak local run.
+async function fetchCustomerPaidStatus(ctx) {
+    try {
+        const res = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me", auth: ctx.auth });
+        if (!res.ok || !res.json || typeof res.json !== "object")
+            return { ok: false, paid: false, email: null, planTier: null };
+        const customer = res.json.customer ?? {};
+        return {
+            ok: true,
+            paid: Boolean(customer.isPaidPlan),
+            email: typeof customer.email === "string" ? customer.email : null,
+            planTier: typeof customer.planTier === "string" ? customer.planTier : null
+        };
+    }
+    catch {
+        return { ok: false, paid: false, email: null, planTier: null };
+    }
+}
+// Local decompose — the paid-vs-free, prepare-vs-sync workflow behind
+// `vidfarm decompose <forkId> --local`. PREPARE stages the harness + task + result
+// skeleton for the desktop agent; SYNC (--sync) posts the agent's produced
+// smart-decompose.json back to cloud (paid-only). Free users get a weak, unlicensed,
+// local-only run with an upgrade nudge — so the ethics/licensing live in the tool,
+// not just the doc, and a customer's agent complies by default.
+async function runLocalDecomposeCommand(forkId, values) {
+    const ctx = commonContext(values);
+    const dir = resolveLocalDecomposeDir(forkId, values.dir);
+    const resultPath = path.join(dir, "smart-decompose.json");
+    // -------- SYNC phase: push the agent's local result back to the shared library.
+    if (values.sync) {
+        if (!existsSync(resultPath)) {
+            throw new Error(`No decomposition to sync at ${resultPath}. Run \`vidfarm decompose ${forkId} --local\` first, have your agent produce smart-decompose.json, then re-run with --sync.`);
+        }
+        let result;
+        try {
+            result = JSON.parse(readFileSync(resultPath, "utf8"));
+        }
+        catch (e) {
+            throw new Error(`smart-decompose.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const res = await apiRequest({
+            method: "POST",
+            host: ctx.host,
+            path: `/api/v1/compositions/${encodeURIComponent(forkId)}/auto-decompose/sync`,
+            auth: ctx.auth,
+            body: {
+                result,
+                source_url: typeof values.source === "string" && values.source.trim() ? values.source.trim() : undefined,
+                provider: "local",
+                model: process.env.VIDFARM_LOCAL_DECOMPOSE_MODEL || "desktop-agent"
+            }
+        });
+        if (res.status === 402) {
+            throw new Error("Syncing a local decompose to cloud requires a PAID Vidfarm subscription — the shared template library is a paid, licensed asset. Subscribe to contribute this back, or keep the decomposition local-only.");
+        }
+        assertApiOk(res, "decompose --local --sync");
+        if (ctx.json) {
+            emitResult(res, true);
+            return;
+        }
+        const j = (res.json ?? {});
+        console.log(`${GREEN}Synced decomposition to cloud.${RESET} fork=${j.fork_id ?? forkId} scenes=${j.scene_count ?? "?"} captions=${j.caption_count ?? "?"}${j.generative_workflow_applies ? `  ${BOLD}generative_workflow: applies${RESET}` : ""}`);
+        console.log(`${DIM}The next creator who forks this template gets your decomposition for free.${RESET}`);
+        return;
+    }
+    // -------- PREPARE phase: stage inputs for the desktop agent.
+    const paid = await fetchCustomerPaidStatus(ctx);
+    mkdirSync(dir, { recursive: true });
+    // Pull any existing cloud grounding for the fork (source URL + prior context).
+    let sourceUrl = typeof values.source === "string" && values.source.trim() ? values.source.trim() : "";
+    let contextNote = "";
+    try {
+        const ctxRes = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/video-context.json`, auth: ctx.auth });
+        if (ctxRes.ok && ctxRes.json && typeof ctxRes.json === "object") {
+            writeFileSync(path.join(dir, "cloud-video-context.json"), JSON.stringify(ctxRes.json, null, 2));
+            const scloud = ctxRes.json.source_url;
+            if (!sourceUrl && typeof scloud === "string" && scloud.trim())
+                sourceUrl = scloud.trim();
+            contextNote = "A prior cloud context was saved to cloud-video-context.json — reuse it where useful.";
+        }
+    }
+    catch {
+        /* fork may not be decomposed yet — fine */
+    }
+    // Fetch the LICENSED harness (paid only). Free users get the weak, unlicensed guide.
+    let harnessSaved = false;
+    if (paid.paid) {
+        try {
+            const hRes = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/decompose/harness.md", auth: ctx.auth });
+            if (hRes.ok && typeof hRes.text === "string" && hRes.text.trim().length > 0) {
+                writeFileSync(path.join(dir, "HARNESS.md"), hRes.text);
+                harnessSaved = true;
+            }
+        }
+        catch {
+            /* fall through to the weak guide */
+        }
+    }
+    if (!harnessSaved) {
+        writeFileSync(path.join(dir, "HARNESS.md"), WEAK_FREE_DECOMPOSE_GUIDE);
+    }
+    writeFileSync(path.join(dir, "smart-decompose.template.json"), LOCAL_DECOMPOSE_RESULT_TEMPLATE);
+    writeFileSync(path.join(dir, "DECOMPOSE_TASK.md"), buildLocalDecomposeTask({ forkId, dir, sourceUrl, paid: paid.paid, harnessSaved, contextNote }));
+    if (ctx.json) {
+        emitResult({
+            status: 200,
+            ok: true,
+            json: {
+                ok: true,
+                prepared: true,
+                dir,
+                paid: paid.paid,
+                harness: harnessSaved ? "licensed" : "weak-free",
+                source_url: sourceUrl || null,
+                task: path.join(dir, "DECOMPOSE_TASK.md"),
+                result_expected: resultPath,
+                sync_cmd: paid.paid ? `vidfarm decompose ${forkId} --local --sync --dir ${dir}` : null
+            },
+            text: ""
+        }, true);
+        return;
+    }
+    if (paid.paid) {
+        console.log(`${GREEN}Local decompose prepared (PAID — latest licensed harness fetched).${RESET}`);
+    }
+    else {
+        console.log(`${RED}Local decompose prepared (FREE tier — WEAK, UNLICENSED).${RESET}`);
+        console.log(`${DIM}Heads up: the free local decompose uses a stripped-down method and your OWN desktop-agent tokens. It typically produces WORSE viral-DNA / harness quality than Vidfarm cloud AND burns more tokens iterating. Cloud decompose (\`vidfarm decompose ${forkId}\`) is ~$0.10 one-time, runs Vidfarm's best models, and its result is shared free with the network. You also CANNOT sync a free local decompose back to cloud.${RESET}`);
+        console.log(`${DIM}Subscribe to run the licensed harness locally on your own tokens AND contribute your decompositions back to the shared library.${RESET}`);
+    }
+    console.log("");
+    console.log(`  1. Open ${BOLD}${path.join(dir, "DECOMPOSE_TASK.md")}${RESET} and follow it (your desktop AI agent does the analysis).`);
+    console.log(`  2. Your agent writes ${BOLD}${resultPath}${RESET} matching smart-decompose.template.json${harnessSaved ? " + HARNESS.md" : ""}.`);
+    if (paid.paid)
+        console.log(`  3. Sync back:  ${BOLD}vidfarm decompose ${forkId} --local --sync --dir ${dir}${RESET}`);
+    else
+        console.log(`  3. ${DIM}(Sync to cloud is paid-only — subscribe to contribute this back.)${RESET}`);
+}
 async function runDecomposeCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), mode: { type: "string", default: "smart" }, prompt: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), mode: { type: "string", default: "smart" }, prompt: { type: "string" }, sync: { type: "boolean", default: false }, dir: { type: "string" }, source: { type: "string" } } });
     const forkId = parsed.positionals[0];
     if (!forkId)
         throw new Error("decompose requires a fork id.");
+    // `--local` runs decompose on the user's OWN desktop AI-agent tokens instead of
+    // billing Vidfarm cloud. Paid users pull the latest licensed harness + can sync
+    // the result back to the shared library; free users get a weaker, unlicensed,
+    // local-only path (with an upgrade nudge). See runLocalDecomposeCommand.
+    if (parsed.values.local) {
+        await runLocalDecomposeCommand(forkId, parsed.values);
+        return;
+    }
     const ctx = commonContext(parsed.values);
     guardBilled(ctx, {
         label: "AI decompose (scene split + annotations)",
@@ -4192,10 +4403,17 @@ async function runCreateOverlayCommand(argv) {
 // The devcli twin of the remove-greenscreen primitive: key out a flat, solid
 // background from an IMAGE (→ transparent PNG/WebP) OR a VIDEO (→ transparent
 // WebM/VP9 alpha), auto-detecting the media kind. LOCAL vs CLOUD: --local runs
-// the keyer in-process for FREE (sharp/ffmpeg, no wallet); --cloud runs the
-// billed primitive. Default = cloud (paid), unless there's no cloud key AND the
-// local backend is present (free / offline), in which case it runs local.
-const GREENSCREEN_PRESET_NAMES = new Set(["green", "digital-green", "blue", "white", "black", "magenta"]);
+// the keyer on your machine with bundled ffmpeg for FREE (no wallet, no
+// backend — same chromakey/despill filter chain as the cloud primitive, so the
+// output matches); --cloud runs the billed primitive. Default = local (free)
+// whenever ffmpeg is available, since keying a flat color is deterministic and
+// cloud-equivalent; the runner falls back to cloud only when ffmpeg is missing.
+//
+// NOTE: preset-name validation reads the IMPORTED `GREENSCREEN_PRESETS` (not a
+// module-local const) on purpose — `void main()` runs near the top of this file
+// and executes synchronously until its first `await`, so a command handler that
+// touches a module-scope const declared further down would TDZ. Imported
+// bindings are initialized before this module's body runs, so they're safe.
 function resolveGreenscreenTarget(values) {
     if (values.local)
         return "local";
@@ -4204,10 +4422,9 @@ function resolveGreenscreenTarget(values) {
     const env = (process.env.VIDFARM_TARGET ?? "").trim().toLowerCase();
     if (env === "local" || env === "cloud")
         return env;
-    const hasCloudKey = Boolean(values["api-key"] ?? process.env.VIDFARM_API_KEY);
-    if (!hasCloudKey && localBackendAvailable())
-        return "local";
-    return "cloud";
+    // Free local ffmpeg keyer is cloud-parity — prefer it by default (the runner
+    // downgrades to cloud if ffmpeg turns out to be unavailable at run time).
+    return "local";
 }
 async function runRemoveGreenscreenCommand(argv) {
     const parsed = parseArgs({
@@ -4231,25 +4448,41 @@ async function runRemoveGreenscreenCommand(argv) {
         }
     });
     const ctx = commonContext(parsed.values);
-    const target = resolveGreenscreenTarget(parsed.values);
-    if (target === "local" && !localBackendAvailable())
-        throw new LocalModeUnavailableError();
-    if (target !== "local") {
-        guardBilled(ctx, {
-            label: "cloud greenscreen removal",
-            estimate: "billed at real compute ×1.2",
-            freeAlternative: "vidfarm remove-greenscreen --local (in-process sharp/ffmpeg, $0.00)"
-        });
-    }
+    let target = resolveGreenscreenTarget(parsed.values);
     const sourceArg = parsed.values.source ?? parsed.positionals[0];
     if (!sourceArg) {
-        throw new Error("remove-greenscreen requires a source image or video: `vidfarm remove-greenscreen <image|video|url> [--preset green|blue|white|black|digital-green|magenta] [--key-color #00FF00] [--local] [--out cutout.png|.webm]`.");
+        throw new Error("remove-greenscreen requires a source image or video: `vidfarm remove-greenscreen <image|video|url> [--preset green|blue|white|black|digital-green|magenta] [--key-color #00FF00] [--cloud] [--out cutout.png|.webm]`.");
     }
-    const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
     const presetRaw = parsed.values.preset?.trim().toLowerCase();
-    if (presetRaw && !GREENSCREEN_PRESET_NAMES.has(presetRaw)) {
-        throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${[...GREENSCREEN_PRESET_NAMES].join(", ")}, or pass --key-color <hex>.`);
+    if (presetRaw && !(presetRaw in GREENSCREEN_PRESETS)) {
+        throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${Object.keys(GREENSCREEN_PRESETS).join(", ")}, or pass --key-color <hex>.`);
+    }
+    // The local keyer is free but needs ffmpeg. If ffmpeg is missing, downgrade to
+    // cloud when possible (or error clearly if the user explicitly demanded local).
+    if (target === "local" && !(await localGreenscreenAvailable())) {
+        const hasCloudKey = Boolean(parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY);
+        if (parsed.values.local) {
+            throw new Error("Local greenscreen needs ffmpeg, which wasn't found. Install ffmpeg (or `npm i -g ffmpeg-static`), or run without --local to use the cloud keyer.");
+        }
+        if (!hasCloudKey) {
+            throw new Error("Greenscreen removal needs either ffmpeg (for the free local keyer) or a cloud API key. Install ffmpeg, or set VIDFARM_API_KEY / pass --cloud --api-key.");
+        }
+        target = "cloud";
+        if (!ctx.json)
+            console.log(`${DIM}ffmpeg not found — using the cloud keyer instead.${RESET}`);
+    }
+    // ---- LOCAL: free, offline, bundled ffmpeg (cloud-parity chroma key) --------
+    if (target === "local") {
+        await runLocalGreenscreen(ctx, parsed.values, sourceArg, presetRaw);
+        return;
     }
+    // ---- CLOUD: billed primitive ----------------------------------------------
+    guardBilled(ctx, {
+        label: "cloud greenscreen removal",
+        estimate: "billed at real compute ×1.2",
+        freeAlternative: "vidfarm remove-greenscreen --local (bundled ffmpeg, $0.00)"
+    });
+    const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
     const mediaTypeArg = parsed.values["media-type"]?.trim().toLowerCase();
     const mediaType = mediaTypeArg === "image" || mediaTypeArg === "video"
         ? mediaTypeArg
@@ -4269,13 +4502,11 @@ async function runRemoveGreenscreenCommand(argv) {
         payload.output_format = parsed.values["output-format"];
     const tracer = parsed.values.tracer ?? `devcli-greenscreen-${Date.now().toString(36)}`;
     const route = "/api/v1/primitives/remove-greenscreen";
-    const submit = target === "local"
-        ? await localApiRequest({ method: "POST", path: route, auth: ctx.auth, body: { tracer, payload }, home: ctx.home })
-        : await apiRequest({ method: "POST", host: ctx.host, path: route, auth: ctx.auth, body: { tracer, payload } });
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: route, auth: ctx.auth, body: { tracer, payload } });
     assertApiOk(submit, "remove-greenscreen");
     const jobId = submit.json?.job_id;
     if (!ctx.json)
-        console.log(`${DIM}${target === "local" ? "Local (free)" : "Cloud"} ${mediaType} greenscreen removal…${RESET}`);
+        console.log(`${DIM}Cloud ${mediaType} greenscreen removal…${RESET}`);
     const wait = !parsed.values["no-wait"];
     if (!wait || !jobId) {
         if (!ctx.json && jobId)
@@ -4314,6 +4545,62 @@ async function runRemoveGreenscreenCommand(argv) {
         console.log(`${DIM}Place it with: vidfarm set-media <dir> --src "${mediaUrl}" --replace <layer_key> (keeps its transparency).${RESET}`);
     }
 }
+// Run the greenscreen key LOCALLY with bundled ffmpeg — free, offline, no
+// wallet, no in-process backend (so it works in the published cloud-only CLI,
+// exactly like `remove-background` rides the bundled ONNX engine). Produces a
+// transparent file on disk and prints its path, mirroring remove-background's
+// UX. Uses the SAME chromakey/despill filter chain as the cloud primitive.
+async function runLocalGreenscreen(ctx, values, sourceArg, presetRaw) {
+    // Resolve the source to a real local file: a path on disk is used in place;
+    // anything else (url / raw id / raws path) resolves to a URL and downloads.
+    const directPath = path.resolve(process.cwd(), sourceArg);
+    const isLocalFile = !/^https?:\/\//i.test(sourceArg) && existsSync(directPath);
+    let sourcePath = directPath;
+    let downloadDir = null;
+    if (!isLocalFile) {
+        const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
+        downloadDir = mkdtempSync(path.join(tmpdir(), "vidfarm-greenscreen-dl-"));
+        sourcePath = path.join(downloadDir, path.basename(new URL(sourceUrl).pathname) || "source.bin");
+        if (!ctx.json)
+            console.log(`${DIM}Downloading source…${RESET}`);
+        await downloadUrlToFile(sourceUrl, sourcePath);
+    }
+    try {
+        const mediaTypeArg = values["media-type"]?.trim().toLowerCase();
+        const mediaType = mediaTypeArg === "image" || mediaTypeArg === "video"
+            ? mediaTypeArg
+            : (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(sourcePath) ? "video" : "image");
+        // Fold preset defaults, letting explicit flags win (mirrors the cloud path).
+        const preset = presetRaw ? GREENSCREEN_PRESETS[presetRaw] : undefined;
+        const keyColor = values["key-color"] ?? preset?.key_color;
+        const tolerance = values.tolerance !== undefined ? Number(values.tolerance) : preset?.tolerance;
+        const softness = values.softness !== undefined ? Number(values.softness) : preset?.softness;
+        const despill = !values["no-despill"];
+        const outputFormat = values["output-format"]?.trim().toLowerCase();
+        const outPath = values.out
+            ? path.resolve(process.cwd(), String(values.out))
+            : defaultGreenscreenOutPath(sourcePath, mediaType, outputFormat);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        if (!ctx.json)
+            console.log(`${DIM}Keying out ${presetRaw ?? keyColor ?? "green"} background locally with ffmpeg (free)…${RESET}`);
+        const result = await removeGreenscreenLocal({ sourcePath, mediaType, outputPath: outPath, keyColor, tolerance, softness, despill });
+        if (ctx.json) {
+            printJson({ ok: true, target: "local", media_type: mediaType, format: result.format, out: result.outputPath, bytes: safeSize(result.outputPath), webm_alpha: result.webmAlpha });
+        }
+        else {
+            const label = result.format === "webm" ? "Transparent WebM" : result.format === "mov" ? "Transparent ProRes 4444 .mov" : "Transparent cut-out";
+            console.log(`${GREEN}${label} ready:${RESET} ${result.outputPath} ${DIM}(${formatBytes(safeSize(result.outputPath))})${RESET}`);
+            if (mediaType === "video" && !result.webmAlpha) {
+                console.log(`${YELLOW}Note:${RESET} ${DIM}your local ffmpeg can't encode transparent WebM (VP9 alpha), so a ProRes .mov alpha master was written instead — genuinely transparent and free, but not directly browser/editor-playable. For a browser-ready transparent WebM, re-run with ${RESET}--cloud${DIM}.${RESET}`);
+            }
+            console.log(`${DIM}Drop it on a composition with: vidfarm set-media <dir> --src "${result.outputPath}" --replace <layer_key> (keeps its transparency).${RESET}`);
+        }
+    }
+    finally {
+        if (downloadDir)
+            rmSync(downloadDir, { recursive: true, force: true });
+    }
+}
 // Poll a greenscreen job through the same backend it was submitted to (local
 // in-process app or cloud). Mirrors pollPrimitiveJob's terminal conditions.
 async function pollGreenscreenJob(ctx, target, jobId) {
@@ -6026,12 +6313,12 @@ async function runWhoamiCommand(argv) {
         console.log(`${GREEN}${BOLD}${who}${RESET} → ${ctx.host}`);
         console.log(`  plan        ${customer.isPaidPlan ? `${GREEN}paid${plan}${RESET}` : `${DIM}free${plan}${RESET}`}`);
         console.log(`  credential  ${DIM}${stored ? "persisted login (vidfarm login)" : "env/flag key — not persisted (run vidfarm login to persist)"}${RESET}`);
-        console.log(`  ${costModeSummaryLine(ctx.costMode).replace("cost mode: ", "cost mode   ")}${!ctx.costMode.isSet ? `  ${DIM}(set with: vidfarm cost-mode <minimize|hybrid|pure-ai>)${RESET}` : ""}`);
+        console.log(`  ${costModeSummaryLine(ctx.costMode).replace("cost mode: ", "cost mode   ")}${!ctx.costMode.isSet ? `  ${DIM}(set with: vidfarm cost-mode <minimize|hybrid|rich-ai>)${RESET}` : ""}`);
         return;
     }
     emitResult(result, ctx.json);
 }
-// `vidfarm cost-mode [minimize|hybrid|pure-ai]` — show or set the money-saving
+// `vidfarm cost-mode [minimize|hybrid|rich-ai]` — show or set the money-saving
 // preference every billed command respects. No arg = show current + explain the
 // three simply so an agent can relay them to the user (and be reminded to ask
 // about saving the choice into whatever agent memory it has). `--clear` forgets it.
@@ -6054,14 +6341,14 @@ async function runCostModeCommand(argv) {
     if (requested) {
         const mode = normalizeCostMode(requested);
         if (!mode) {
-            throw new Error(`Unknown cost mode "${requested}". Choose one of: ${COST_MODES.join(", ")}.`);
+            throw new Error(`Unknown cost mode "${requested}". Choose one of: ${COST_MODE_DISPLAY_LIST.join(", ")}.`);
         }
         // Stamp time on the host so this stays deterministic-friendly for scripts.
         const savedAt = new Date().toISOString();
         const file = writeStoredCostMode(mode, savedAt, parsed.values.note ?? null, home);
         if (json)
             return printJson({ ok: true, cost_mode: mode, saved_at: savedAt, file });
-        console.log(`${GREEN}${BOLD}Cost mode: ${mode}${RESET}`);
+        console.log(`${GREEN}${BOLD}Cost mode: ${costModeDisplayName(mode)}${RESET}`);
         console.log(`${DIM}${COST_MODE_BLURB[mode]}${RESET}`);
         console.log(`${DIM}Saved to ${file} (every billed command now respects it).${RESET}`);
         console.log(`${DIM}Tip: if the user wants this remembered across sessions, offer to also save it to your` +
@@ -6077,7 +6364,7 @@ async function runCostModeCommand(argv) {
     console.log("");
     console.log(costModeExplainer());
     console.log("");
-    console.log(`${DIM}Set it: ${BOLD}vidfarm cost-mode <minimize|hybrid|pure-ai>${RESET}`);
+    console.log(`${DIM}Set it: ${BOLD}vidfarm cost-mode <minimize|hybrid|rich-ai>${RESET}`);
     console.log(`${DIM}Forget it: vidfarm cost-mode --clear · override per-run: --cost-mode <m> or VIDFARM_COST_MODE.${RESET}`);
     if (!resolved.isSet) {
         console.log(`${DIM}Nothing saved yet — ask the user which one they want before spending AI credits.${RESET}`);
@@ -7460,7 +7747,7 @@ async function runUpdateSkillCommand(argv) {
         }
     });
     const ctx = commonContext(parsed.values);
-    const skillNames = ["vidfarm-director", ...(parsed.values.platform ? ["vidfarm-platform"] : [])];
+    const skillNames = ["vidfarm", ...(parsed.values.platform ? ["vidfarm-platform"] : [])];
     if (parsed.values.print) {
         for (const name of skillNames) {
             const { contents } = await fetchSkillContents(ctx.host, SKILL_TARGETS[name]);
@@ -7469,14 +7756,14 @@ async function runUpdateSkillCommand(argv) {
         return;
     }
     if (parsed.values.global || parsed.values.platform) {
-        throw new Error("update-skill --global/--platform are retired. Use `vidfarm skills add vidfarm-director --dir <project>` for the canonical multi-file pack; `update-skill --print` remains available for the generated copy-friendly rollup.");
+        throw new Error("update-skill --global/--platform are retired. Use `vidfarm skills add vidfarm --dir <project>` for the canonical multi-file pack; `update-skill --print` remains available for the generated copy-friendly rollup.");
     }
     if (!ctx.json) {
-        console.warn(`Deprecated: update-skill now delegates to the canonical multi-file skill installer. Use ${BOLD}vidfarm skills add vidfarm-director${RESET}.`);
+        console.warn(`Deprecated: update-skill now delegates to the canonical multi-file skill installer. Use ${BOLD}vidfarm skills add vidfarm${RESET}.`);
     }
     await runSkillsCommand([
         "add",
-        "vidfarm-director",
+        "vidfarm",
         ...(parsed.values.dir ? ["--dir", String(parsed.values.dir)] : []),
         ...(parsed.values.host ? ["--host", String(parsed.values.host)] : []),
         ...(ctx.json ? ["--json"] : [])

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

@@ -10,7 +10,7 @@
 //   - hybrid   : free where it's free, spend on AI only where it clearly wins.
 //                (default recommendation.) Billed ops run but print a cost line.
 //   - pure-ai  : best-quality; AI image/video/voice/music used freely. Billed
-//                ops run; cost is still surfaced.
+//                ops run; cost is still surfaced. Shown to humans as "rich-ai".
 //
 // This module lives in the CLI's static import closure and is BACKEND-FREE (only
 // Node built-ins) so it ships in the public cloud-only package.
@@ -33,10 +33,25 @@ export function normalizeCostMode(raw) {
         return "minimize";
     if (["hybrid", "mixed", "balanced", "smart", "default"].includes(v))
         return "hybrid";
-    if (["pure-ai", "pureai", "ai", "best", "best-quality", "premium", "max"].includes(v))
+    if (["pure-ai", "pureai", "rich-ai", "richai", "rich", "ai", "best", "best-quality", "premium", "max"].includes(v))
         return "pure-ai";
     return null;
 }
+/**
+ * Human-facing NAME for a mode. The canonical stored slug for best-quality stays
+ * `pure-ai` (so saved cost-mode.json, --cost-mode flags, and VIDFARM_COST_MODE
+ * keep resolving), but users see and can type "rich-ai".
+ */
+export const COST_MODE_DISPLAY = {
+    minimize: "minimize",
+    hybrid: "hybrid",
+    "pure-ai": "rich-ai"
+};
+/** The three modes as users see them, e.g. for "<minimize|hybrid|rich-ai>". */
+export const COST_MODE_DISPLAY_LIST = COST_MODES.map((m) => COST_MODE_DISPLAY[m]);
+export function costModeDisplayName(mode) {
+    return COST_MODE_DISPLAY[mode];
+}
 /** Read the persisted cost mode, or null if absent/unparseable. */
 export function readStoredCostMode(home) {
     try {
@@ -96,13 +111,13 @@ export const COST_MODE_BLURB = {
     hybrid: "Hybrid (recommended) — free where it's free, spend AI credits only where they " +
         "clearly win (a hero shot, a voice you can't fake locally). Billed ops run but " +
         "each prints its cost so nothing is a surprise.",
-    "pure-ai": "Pure AI — best quality; AI image/video/voice/music used freely. Billed ops run " +
+    "pure-ai": "Rich AI — best quality; AI image/video/voice/music used freely. Billed ops run " +
         "without gating; cost is still shown."
 };
 /** One short human line summarizing the active mode. */
 export function costModeSummaryLine(resolved) {
     const setNote = resolved.isSet ? `set via ${resolved.source}` : "NOT set — assuming hybrid";
-    return `cost mode: ${resolved.mode} (${setNote})`;
+    return `cost mode: ${costModeDisplayName(resolved.mode)} (${setNote})`;
 }
 /** The 3-line "explain it simply" block an agent should relay to the user. */
 export function costModeExplainer() {
@@ -110,7 +125,7 @@ export function costModeExplainer() {
         "How much do you want Vidfarm to spend on AI credits?",
         "  • minimize — cheapest: free local compute + free stock media, no surprise AI spend.",
         "  • hybrid   — recommended: free where free, pay AI only where it clearly wins.",
-        "  • pure-ai  — best quality: use AI image/video/voice/music freely.",
+        "  • rich-ai  — best quality: use AI image/video/voice/music freely.",
         "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.',
         "  Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons)",
@@ -150,9 +165,9 @@ export function assertBilledAllowed(input) {
         return;
     if (!resolved.isSet) {
         log(`[cost] No spend preference set — ${label}${cost} will bill the account. ` +
-            `Ask the user minimize / hybrid / pure-ai and save it: vidfarm cost-mode <choice>.`);
+            `Ask the user minimize / hybrid / rich-ai and save it: vidfarm cost-mode <choice>.`);
         return;
     }
-    log(`[cost] ${label}${cost} — billed (mode: ${resolved.mode}${yes ? ", confirmed" : ""}).`);
+    log(`[cost] ${label}${cost} — billed (mode: ${costModeDisplayName(resolved.mode)}${yes ? ", confirmed" : ""}).`);
 }
 //# sourceMappingURL=cost-mode.js.map