@mevdragon/vidfarm-devcli 0.20.6 → 0.20.8

package/dist/src/cli.js

@@ -22,6 +22,7 @@ import { renderCompositionStills } from "./devcli/stills.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { runSkillsCommand } from "./devcli/skills.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
+import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError } from "./devcli/local-backend.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
@@ -60,16 +61,16 @@ Local editor loop:
   serve [template_id] [opts]  Boot the FULL editor locally (single origin, disk-backed).
                               Records + storage run on disk; render runs in-process on
                               this box for FREE (no cloud, no wallet charge).
-                              /discover and /library still list the CLOUD catalog —
-                              opening a cloud template seeds it onto local disk, and
-                              the editor's Render button can hand off to the cloud
-                              renderer (needs the cloud --api-key). Only the editor
-                              and its data are local.
+                              With a VALID cloud API key, /discover and /library can
+                              mirror the CLOUD catalog, opening a cloud template seeds
+                              it onto local disk, and the editor can hand a render off
+                              to the cloud renderer. Without a valid key, serve falls
+                              back to local browse mode and opens /tools/clipper.
                               With a template_id or --fork, pulls that composition
                               (or the template's default/shared decomposition) from
                               the cloud host onto local disk to edit offline.
     --port <n>                Server port (default: 3000)
-    --dir <path>              Local data dir (default: ./.vidfarm-local)
+    --dir <path>              Local data dir (default: ~/.vidfarm/data or VIDFARM_HOME/data)
     --key <api-key>           Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
     --fork <id>               Pull + open a specific cloud fork
     --host <url>              Cloud host to pull from (default: ${DEFAULT_HOST})
@@ -84,17 +85,27 @@ Discover & inspiration (browse the viral-video catalog, add your own source):
   discover [query...]       List/search TEMPLATES (best for an offer)    → GET  /discover/feed
     --query <text>          Keyword search (e.g. "weight loss app")
     --limit <n>             Max results
+  public-raws [query...]    Browse PUBLIC RAWS (feed / categories)       → GET  /api/v1/public-raws
+    --query <text>          Keyword/vector query over title + metadata
+    --category <key>        Filter one public-raw category (e.g. emotion:confused)
+    --type <raw_type>       Filter one raw family (greenscreen, b_roll, ...)
+    --freshness-days <n>    Only raws newer than N days
+    --bookmark <raw_id>     Save that public raw into /raws/public/*     → POST /api/v1/public-raws/:rawId/bookmark
+    --limit <n>             Max results
   videos [query...]         List/search source INSPIRATIONS              → GET  /api/v1/videos
     --query <text>          Keyword search over the catalog
     --mine                  Only your own uploaded inspirations
     --limit <n>             Max results
   inspiration-add <url|file>  Ingest a TikTok/YT/IG/X URL — or upload a    → POST /discover/templates
                             local MP4/MOV/WebM file — as a private        (files: presign + PUT via
-                            template. --title (uploads; defaults to the    /discover/templates/upload)
-                            template id), --tagline, --notes optional.
-                            --raw (uploads) marks it as your own raw
-                            project footage — the editor won't auto-
-                            prompt Decompose on it.
+                            template. A TikTok PHOTO/slideshow URL is      /discover/templates/upload)
+                            ingested as a slideshow (ordered images + its
+                            audio) into an editable image timeline.
+                            --title (uploads; defaults to the template
+                            id), --tagline, --notes optional. --raw
+                            (uploads) marks it as your own raw project
+                            footage — the editor won't auto-prompt
+                            Decompose on it.
   inspiration-rm <id>       Delete a private inspiration/template you own → DELETE /discover/templates/:id
   inspiration-decompose <id>  AI-decompose an inspiration into scenes     → POST /api/v1/inspirations/:id/decompose
 
@@ -103,7 +114,9 @@ Make a video in one command (orchestrates ingest → decompose → fork):
                             the URL, AI-decompose/recreate its scenes,
                             and open an editable fork. --prompt "...and
                             make it about X" steers the recreation.
-                            --title, --no-fork optional.
+                            --title, --no-fork optional. A TikTok photo/
+                            slideshow URL skips decompose (already an
+                            editable image timeline) and forks directly.
   create "<prompt>"         Spin up a NEW video from a text prompt: AI-     → generate + ingest + decompose + fork
                             generate a base video, wrap it into an
                             editable template, decompose + fork. --duration
@@ -260,9 +273,9 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --replace <layer_key>   Swap the media into this existing scene/layer instead
     --kind <video|image|audio>   Media kind (inferred from the URL if omitted)
     --folder <name>         (raw) Save the import into /raws/<name> (also the tracer)
-    --clip [--prompt "..."] [--provider gemini|openai|openrouter]
+    --clip [--prompt "..."] [--provider gemini|openai|openrouter|nvidia]
                             (raw) AI-clip the video into matching moments instead of
-                            importing the whole thing (BYOK)
+                            importing the whole thing (BYOK; nvidia = lite clipping key)
 
 Raws (the third library — mine long-form video into a reusable raws store):
   raws scan <video-path>    Hunt short clips out of a long video.        LOCAL-FIRST: local ffmpeg +
@@ -281,9 +294,14 @@ Raws (the third library — mine long-form video into a reusable raws store):
   raws preset list|run <name>|save <name> --from-query '<...>'          → /raws/presets
   raws export <ids...> --to <dir>   Copy raw mp4s + metadata out
                             (run 'vidfarm raws' for the full raws help)
-  clipper <video-url|file>  Import a source into raws (the /tools/clipper twin).  → POST /raws/clip-range
-                            DEFAULT = the WHOLE video; --start/--end trims an       (or /raws/scan whole)
+  clipper <video-url|file>  Import a source into raws (the /tools/clipper twin).  LOCAL-FIRST by default;
+                            DEFAULT = the WHOLE video; --start/--end trims an       add --cloud for vidfarm.cc
                             EXACT subrange and saves one raw.
+                            Local URL imports resolve direct media from the page itself
+                            first (JSON-LD / og:video / player metadata), so you can
+                            browse manually and paste a source page URL without RapidAPI.
+                            For bulk ingestion, cloud catalog access, and reliable scale,
+                            sign up for vidfarm.cc.
     --start <t> --end <t>     In/out point — seconds (12.5) or HH:MM:SS:NNNN. Omit
                             BOTH to import the whole video (entirety); pass BOTH for
                             a subrange (one without the other is an error).
@@ -312,7 +330,7 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
                               takes an ElevenLabs voice_id (see: vidfarm voices).
     --own-key                 (--cloud) use your own ElevenLabs / BYOK key instead of the wallet
     --list-voices             List ElevenLabs voices and exit (same as: vidfarm voices)
-  music "<prompt>"          Prompt → music track (ElevenLabs).            CLOUD-ONLY (no local engine)
+  music "<prompt>"          Prompt → music track (ElevenLabs).            CLOUD/BYOK (no free local engine)
     --length <sec> | --length-ms <ms>   Duration (default 30s, max 5 min)
     --out <file>              Output mp3 path (default music-<id>.mp3)
     --own-key                 Use your own ElevenLabs key instead of the platform key + wallet
@@ -543,6 +561,12 @@ const GREEN = "\x1b[32m";
 const RED = "\x1b[31m";
 const RESET = "\x1b[0m";
 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) {
+        console.error(error.message);
+        process.exit(1);
+    }
     console.error(error instanceof Error ? error.stack ?? error.message : String(error));
     // Report only unexpected crashes (bugs), never the deliberate user-facing
     // `throw new Error(...)` above; no-op unless a devcli DSN is configured.
@@ -565,6 +589,8 @@ async function main() {
         // editor locally. The old cross-origin dev-serve/`?dev=` flow is gone.
         case "serve":
         case "edit":
+            if (!localBackendAvailable())
+                throw new LocalModeUnavailableError();
             await runServeCommand(rest);
             return;
         case "publish":
@@ -577,6 +603,9 @@ async function main() {
         case "discover":
             await runDiscoverCommand(rest);
             return;
+        case "public-raws":
+            await runPublicRawsCommand(rest);
+            return;
         case "videos":
             await runVideosCommand(rest);
             return;
@@ -729,11 +758,15 @@ async function main() {
             await runDirectoryCommand(rest);
             return;
         case "migrate-local": {
+            if (!localBackendAvailable())
+                throw new LocalModeUnavailableError();
             const { runMigrateLocalCommand } = await import("./devcli/migrate-local.js");
             await runMigrateLocalCommand(rest);
             return;
         }
         case "sync": {
+            if (!localBackendAvailable())
+                throw new LocalModeUnavailableError();
             const { runSyncCommand } = await import("./devcli/sync.js");
             await runSyncCommand(rest);
             return;
@@ -857,6 +890,30 @@ async function apiRequest(input) {
     }
     return { status: res.status, ok: res.ok, json, text };
 }
+async function detectCloudAuth(host, apiKey) {
+    const key = apiKey?.trim() || "";
+    if (!key) {
+        return { usable: false, reason: "missing", detail: "VIDFARM_API_KEY not set." };
+    }
+    try {
+        const res = await fetch(new URL("/api/v1/user/me", host), {
+            headers: { "vidfarm-api-key": key, accept: "application/json" }
+        });
+        if (res.ok)
+            return { usable: true, reason: "ok", detail: "authenticated" };
+        if (res.status === 401 || res.status === 403) {
+            return { usable: false, reason: "invalid", detail: `cloud auth rejected (${res.status})` };
+        }
+        return { usable: false, reason: "unreachable", detail: `cloud auth probe returned HTTP ${res.status}` };
+    }
+    catch (error) {
+        return {
+            usable: false,
+            reason: "unreachable",
+            detail: `cloud auth probe failed: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+}
 // Named commands should fail loudly (unlike the read-tolerant edit fetch).
 function assertApiOk(result, action) {
     if (result.ok)
@@ -907,7 +964,10 @@ function resolveTarget(values) {
     const envTarget = (process.env.VIDFARM_TARGET ?? "").trim().toLowerCase();
     if (envTarget === "cloud" || envTarget === "both" || envTarget === "local")
         return envTarget;
-    return "local";
+    // Local-first by default — but only when the in-process backend is present
+    // (a full source checkout). The published cloud-only CLI has no local backend,
+    // so it defaults to cloud instead of failing on every bare command.
+    return localBackendAvailable() ? "local" : "cloud";
 }
 function commonContext(values) {
     return {
@@ -964,6 +1024,9 @@ function editorFrontendUrl(host, templateId, forkId) {
 function discoverFrontendUrl(host) {
     return `${host}/discover`;
 }
+function publicRawsFrontendUrl(host) {
+    return `${host}/discover/raws/feed`;
+}
 // The devcli twin of the studio editor's "Create New" → /tools/image hand-off:
 // a deep link that opens the Tools image editor seeded with a source image so
 // the user can author a replacement. Mirrors buildInpaintEditUrl in
@@ -1029,7 +1092,9 @@ async function runServeCommand(argv) {
     if (!Number.isFinite(port) || port <= 0) {
         throw new Error(`Invalid --port: ${parsed.values.port}`);
     }
-    const dataDir = path.resolve(process.cwd(), parsed.values.dir ?? ".vidfarm-local");
+    const dataDir = parsed.values.dir
+        ? path.resolve(process.cwd(), parsed.values.dir)
+        : resolveLocalDataDir();
     mkdirSync(dataDir, { recursive: true });
     // Capture the ambient cloud key BEFORE we overwrite VIDFARM_API_KEY with the
     // local bootstrap key, so `--fork`/template seeding can still authenticate to
@@ -1043,6 +1108,10 @@ async function runServeCommand(argv) {
     const host = trimTrailingSlash(parsed.values.host);
     const templateId = parsed.positionals[0];
     const forkFlag = parsed.values.fork;
+    const requestedCloud = !parsed.values["no-cloud"];
+    const cloudAuth = requestedCloud
+        ? await detectCloudAuth(host, cloudApiKey)
+        : { usable: false, reason: "missing", detail: "--no-cloud set" };
     // Env MUST be set before importing runtime — config.ts reads it at module
     // load. Force the fully-local drivers.
     process.env.RECORDS_DRIVER = "local";
@@ -1077,7 +1146,7 @@ async function runServeCommand(argv) {
     // listing the upstream (cloud) catalog, templates seed onto disk on demand,
     // and the editor's Render button can hand off to the cloud renderer. The
     // upstream key is the AMBIENT cloud key (never the local bootstrap key).
-    const cloudEnabled = !parsed.values["no-cloud"];
+    const cloudEnabled = requestedCloud && cloudAuth.usable;
     process.env.VIDFARM_UPSTREAM_HOST = cloudEnabled ? host : "";
     process.env.VIDFARM_UPSTREAM_API_KEY = cloudEnabled ? (cloudApiKey ?? "") : "";
     const { startRuntime } = await import("./runtime.js");
@@ -1088,7 +1157,7 @@ async function runServeCommand(argv) {
     let openTemplateId = templateId;
     let openForkId = forkFlag;
     if ((templateId || forkFlag) && !cloudEnabled) {
-        console.warn("[vidfarm] serve: --no-cloud set — skipping cloud seed of the requested template/fork.");
+        console.warn(`[vidfarm] serve: cloud seed unavailable (${requestedCloud ? cloudAuth.detail : "--no-cloud set"}) — starting local-only.`);
     }
     else if (templateId || forkFlag) {
         try {
@@ -1109,11 +1178,22 @@ async function runServeCommand(argv) {
         }
     }
     const base = `http://localhost:${port}`;
+    const browseMode = !cloudEnabled && !openTemplateId && !openForkId;
     const editorPath = openTemplateId
         ? `/editor/${encodeURIComponent(openTemplateId)}${openForkId ? `/fork/${encodeURIComponent(openForkId)}` : ""}`
-        : "/discover";
+        : browseMode
+            ? "/tools/clipper"
+            : "/discover";
     const openUrl = `${base}/auto-login?api_key=${encodeURIComponent(apiKey)}&redirect=${encodeURIComponent(editorPath)}`;
-    printServeBanner({ base, dataDir, openUrl, editorPath, cloud: cloudEnabled ? { host, hasKey: Boolean(cloudApiKey) } : null });
+    printServeBanner({
+        base,
+        dataDir,
+        openUrl,
+        editorPath,
+        browseMode,
+        cloud: cloudEnabled ? { host, hasKey: true, detail: cloudAuth.detail } : null,
+        cloudDisabledReason: requestedCloud && !cloudEnabled ? cloudAuth.detail : null
+    });
     const shouldOpen = parsed.values.open && !parsed.values["no-open"];
     if (shouldOpen)
         openInBrowser(openUrl);
@@ -1147,14 +1227,21 @@ function printServeBanner(input) {
     console.log(`  data dir    ${input.dataDir}`);
     console.log(`  render      ${DIM}local (in-process HyperFrames render — free, no cloud charge)${RESET}`);
     if (input.cloud) {
-        console.log(`  cloud       ${input.cloud.host} ${DIM}(/discover + /library list the cloud catalog; templates seed locally on open${input.cloud.hasKey ? "; Render can hand off to the cloud renderer" : "; set VIDFARM_API_KEY for /library + cloud render"})${RESET}`);
+        console.log(`  cloud       ${input.cloud.host} ${DIM}(/discover + /library list the cloud catalog; templates seed locally on open; Render can hand off to the cloud renderer)${RESET}`);
     }
     else {
-        console.log(`  cloud       ${DIM}off (--no-cloud) — local data only${RESET}`);
+        console.log(`  cloud       ${DIM}off${input.cloudDisabledReason ? ` — ${input.cloudDisabledReason}` : " (--no-cloud)"}${RESET}`);
+    }
+    if (input.browseMode) {
+        console.log(`  mode        ${DIM}browse — local clipper opens instead of the cloud catalog${RESET}`);
     }
     console.log("");
     console.log(`  ${DIM}Agents: edit composition files under ${input.dataDir}/storage — the`);
     console.log(`  browser live-reloads on save. Multiple forks can be edited at once.${RESET}`);
+    if (input.browseMode) {
+        console.log(`  ${DIM}Browse externally yourself, then paste/select source pages in /tools/clipper.`);
+        console.log(`  For bulk ingestion, curated fresh data, and cloud rendering at scale, use vidfarm.cc.${RESET}`);
+    }
     console.log("");
     console.log(`  ${BOLD}Open (pre-authed):${RESET}`);
     console.log(`  ${FRONTEND}${input.openUrl}${RESET}`);
@@ -1360,7 +1447,12 @@ async function fetchCompositionFiles(input) {
     // "how to edit like this" companion to the video-context viral DNA (whose
     // `emotional_punch` captures the joke/vibe/intonation and, being decomposed
     // over the transcript too, the trending sound driving the emotion).
-    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json", "scene-annotations.json", "editor-harness.json"];
+    // replication-harness.json carries the TECHNICAL REPLICATION ANALYSIS (the
+    // 3-paintbrush cheap vs best-quality build plans — which beats are raw_clip
+    // vs hyperframes vs reusable_asset vs ai_gen, with reusable-asset guidance
+    // disciplined by viral DNA and a free-tier open-tools note, all under
+    // `.harness`) so an agent can rebuild the template WITHOUT burning AI credits.
+    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json", "scene-annotations.json", "editor-harness.json", "replication-harness.json"];
     for (const filename of files) {
         const target = path.join(input.dir, filename);
         if (existsSync(target) && !input.refetch) {
@@ -1408,6 +1500,7 @@ function readJsonStringList(value, max = 8) {
 function writeLocalAgentHarnessFiles(dir) {
     const videoContext = readJsonFile(path.join(dir, "video-context.json"));
     const editorHarness = readJsonFile(path.join(dir, "editor-harness.json"));
+    const replicationHarness = readJsonFile(path.join(dir, "replication-harness.json"));
     const sceneAnnotations = readJsonFile(path.join(dir, "scene-annotations.json"));
     const cast = readJsonFile(path.join(dir, "cast.json"));
     const viralDna = videoContext && readJsonString(videoContext.status) === "ready" && videoContext.viral_dna && typeof videoContext.viral_dna === "object"
@@ -1416,6 +1509,9 @@ function writeLocalAgentHarnessFiles(dir) {
     const harness = editorHarness && readJsonString(editorHarness.status) === "ready" && editorHarness.harness && typeof editorHarness.harness === "object"
         ? editorHarness.harness
         : null;
+    const replication = replicationHarness && readJsonString(replicationHarness.status) === "ready" && replicationHarness.harness && typeof replicationHarness.harness === "object"
+        ? replicationHarness.harness
+        : null;
     const annotations = sceneAnnotations && readJsonString(sceneAnnotations.status) === "done" && Array.isArray(sceneAnnotations.annotations)
         ? sceneAnnotations.annotations
         : [];
@@ -1431,6 +1527,7 @@ function writeLocalAgentHarnessFiles(dir) {
         composition_context: viralDna,
         static_vs_pivot: viralDna?.static_vs_pivot ?? null,
         editor_harness: harness,
+        replication_harness: replication,
         scenes: Array.isArray(videoContext?.scenes) ? videoContext?.scenes : [],
         scene_annotations: annotations,
         cast: castMembers,
@@ -1472,6 +1569,29 @@ function writeLocalAgentHarnessFiles(dir) {
         return slug ? `${slug}: ${item}` : item;
     }))
         .slice(0, 8);
+    // Replication harness (3-paintbrush cheap vs best-quality plans). Surface the
+    // RECOMMENDED plan's per-beat brush assignment concretely so a local agent can
+    // execute it without opening the raw JSON.
+    const recommendedStrategy = readJsonString(replication?.recommended_strategy) || "cheap_efficient";
+    const cheapPlan = replication?.cheap && typeof replication.cheap === "object" ? replication.cheap : null;
+    const qualityPlan = replication?.quality && typeof replication.quality === "object" ? replication.quality : null;
+    const recommendedPlan = recommendedStrategy === "best_quality" ? qualityPlan : cheapPlan;
+    const motionStyle = replication?.motion_style && typeof replication.motion_style === "object" ? replication.motion_style : null;
+    const planBeats = (plan) => {
+        const scenes = plan && Array.isArray(plan.scenes) ? plan.scenes : [];
+        return scenes.slice(0, 8).map((s) => {
+            const role = readJsonString(s.role) || "beat";
+            const ts = readJsonString(s.timestamp);
+            const method = readJsonString(s.method) || "?";
+            const credits = readJsonString(s.est_credits);
+            const technique = readJsonString(s.technique);
+            return `${ts ? `${ts} ` : ""}${role} → ${method}${credits ? ` (${credits} credits)` : ""}${technique ? `: ${technique}` : ""}`;
+        });
+    };
+    const recommendedBeats = planBeats(recommendedPlan);
+    const hyperframesCandidates = readJsonStringList(motionStyle?.hyperframes_candidates, 6);
+    const assetOpportunities = readJsonStringList(replication?.asset_opportunities, 6);
+    const dnaGuardrails = readJsonStringList(replication?.viral_dna_guardrails, 6);
     const agentMd = `# Vidfarm Local Harness
 
 Read \`.harness/context.json\` before making substantial edits. This fork was pulled from Vidfarm with decompose context; do not freestyle the rewrite from \`composition.html\` alone.
@@ -1479,6 +1599,7 @@ Read \`.harness/context.json\` before making substantial edits. This fork was pu
 Files to use:
 - \`video-context.json\`: transcript, scene descriptions, and viral DNA.
 - \`editor-harness.json\`: the technical editing brief under \`harness\` (pace, typography, audio, scene roles).
+- \`replication-harness.json\`: the technical replication analysis under \`harness\` — the 3-paintbrush cheap vs best-quality build plans (which beats are raw_clip / hyperframes / reusable_asset / ai_gen), reusable-asset guidance, and a free-tier note. See "Replication plan" below.
 - \`scene-annotations.json\`: per-scene replacement and regeneration DNA.
 - \`.harness/context.json\`: merged agent-facing snapshot generated by \`vidfarm pull\`.
 - \`.harness/agent-guide.md\`: Vidfarm-specific local scripting guidance generated by \`vidfarm pull\`.
@@ -1493,6 +1614,16 @@ 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.
 
+The three paintbrushes (Vidfarm is thrift-first — do NOT spend AI credits on every scene):
+- Paint each REPLACE beat with one of three brushes, cheapest first: (1) RAW CLIPS remixed from existing footage (\`vidfarm raws search\` the local/library first, then \`vidfarm raws scan <url|file>\` to hunt new ones — free local compute); (2) HTML/JS HYPERFRAMES — animate text/images/logos/stickers/charts with CSS or JS adapters (anime.js/GSAP/Lottie/Three) for titles, kinetic captions, data beats, brand cards; (3) PURE AI GENERATION (\`vidfarm generate image|video\`) — most expensive, AI video especially, last resort for beats no clip or hyperframe can cover.
+- A background video + a foreground video (greenscreen / picture-in-picture) covers most "video meme" formats with zero generation.
+- Reusable asset library (logos, stickers, reactions, b-roll, a-roll, brand media kit): have an opinion on when/where to reuse — but anchor every asset choice to the viral DNA + harness above. Reskinning past a load-bearing beat kills what made the format work. AI-generate a reusable element ONCE, then reuse it; don't regenerate per-scene.
+
+Two replication harnesses — pick one and name it to the user (default A). When \`replication-harness.json\` is present it holds a CONCRETE, per-beat version of both plans (see "Replication plan" below) — prefer its beat assignments over freestyling; this prose is the fallback when it's absent:
+- (A) CHEAP & EFFICIENT (default = \`replication-harness.json\`.harness.cheap): recaption text; background+foreground video memes; animate HTML/image elements with hyperframes; reuse library media; AI-generate a reusable element once then reuse; greenscreen; raw-clip long-form and remix; lean on the memes/reactions/b-roll/a-roll library + brand media kit; only if genuinely needed, AI image then (last) AI video/voice/music.
+- (B) BEST QUALITY (\`.harness.quality\`): AI video generation by default; storyboard with AI IMAGE first (cheap stills lock composition/subject), generate motion from those references; then adversarially grade the render with a coding agent (Claude Code/Codex) against this harness and iterate.
+- This harness is open source: an everyday AI agent can follow it to recreate a template with NO Vidfarm wallet — clipping, hyperframes, and local \`vidfarm serve\` render all run on free compute. Keep the plan self-contained; don't gate the cheap path behind paid primitives. \`replication-harness.json\`.harness.free_tier_note names the open path for THIS template.
+
 Current format snapshot:
 - Trend tagline: ${readJsonString(viralDna?.trend_tagline) || "unknown"}
 - Hook: ${readJsonString(viralDna?.hook) || "unknown"}
@@ -1513,6 +1644,26 @@ Static vs pivot:
 - Captions: ${readJsonString(captionsPivot?.overall) || "unknown"}${readJsonString(captionsPivot?.animation_dependency) ? ` — ${readJsonString(captionsPivot?.animation_dependency)}` : ""}
 - Visual rebuild: ${readJsonString(visualRebuild?.default_strategy) || "unknown"}${readJsonString(visualRebuild?.reason) ? ` — ${readJsonString(visualRebuild?.reason)}` : ""}
 
+Replication plan (from replication-harness.json — the recommended path for THIS template):
+- Recommended strategy: ${recommendedStrategy}${readJsonString(replication?.recommendation_reason) ? ` — ${readJsonString(replication?.recommendation_reason)}` : ""}
+- Summary: ${readJsonString(replication?.summary) || "unknown (run `vidfarm decompose`)"}
+- Paintbrush rationale: ${readJsonString(replication?.paintbrush_rationale) || "unknown"}
+- Cheap plan mix: ${readJsonString(cheapPlan?.method_mix) || readJsonString(cheapPlan?.one_liner) || "unknown"}
+- Best-quality mix: ${readJsonString(qualityPlan?.method_mix) || readJsonString(qualityPlan?.one_liner) || "unknown"}
+- Free-tier path: ${readJsonString(replication?.free_tier_note) || "unknown"}
+
+Recommended per-beat brush plan (${recommendedStrategy}):
+${recommendedBeats.length ? recommendedBeats.map((item) => `- ${item}`).join("\n") : "- none recorded (run `vidfarm decompose`)"}
+
+Do these in HTML/hyperframes (NOT AI video — save credits):
+${hyperframesCandidates.length ? hyperframesCandidates.map((item) => `- ${item}`).join("\n") : "- all on-screen text + graphic overlays"}
+
+Reusable-asset opportunities (logos/stickers/b-roll — generate once, reuse):
+${assetOpportunities.length ? assetOpportunities.map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
+Replication viral-DNA guardrails (never break these when swapping/reusing):
+${dnaGuardrails.length ? dnaGuardrails.map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
 Priority preserve beats:
 ${preserve.length ? preserve.map((item) => `- ${item}`).join("\n") : "- none recorded"}
 
@@ -2004,6 +2155,50 @@ async function runDiscoverCommand(argv) {
     assertApiOk(result, "discover");
     emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
 }
+async function runPublicRawsCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            limit: { type: "string" },
+            query: { type: "string" },
+            category: { type: "string" },
+            type: { type: "string" },
+            "freshness-days": { type: "string" },
+            bookmark: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const bookmark = parsed.values.bookmark?.trim();
+    if (bookmark) {
+        const result = await apiRequest({
+            method: "POST",
+            host: ctx.host,
+            path: `/api/v1/public-raws/${encodeURIComponent(bookmark)}/bookmark`,
+            auth: ctx.auth
+        });
+        assertApiOk(result, "public-raws bookmark");
+        emitResult(result, ctx.json, [["Drive ", `${ctx.host}/library/files?route=raws/public`]]);
+        return;
+    }
+    const query = (parsed.values.query ?? parsed.positionals.join(" ").trim()) || undefined;
+    const result = await apiRequest({
+        method: "GET",
+        host: ctx.host,
+        path: "/api/v1/public-raws",
+        auth: ctx.auth,
+        query: {
+            limit: parsed.values.limit,
+            q: query,
+            category: parsed.values.category,
+            raw_type: parsed.values.type,
+            freshness_days: parsed.values["freshness-days"]
+        }
+    });
+    assertApiOk(result, "public-raws");
+    emitResult(result, ctx.json, [["Browse ", publicRawsFrontendUrl(ctx.host)]]);
+}
 // `videos` lists source INSPIRATIONS (the raw viral videos), with the same
 // keyword search and an optional --mine for the caller's own uploads.
 async function runVideosCommand(argv) {
@@ -2232,12 +2427,24 @@ async function runReplicateCommand(argv) {
     if (!templateId)
         throw new Error("replicate: no template was minted from the source video.");
     // 3. Decompose (AI scene analysis + recreation), steered by --prompt.
-    if (!ctx.json)
-        process.stdout.write(`${DIM}Analyzing + recreating scenes (can take a minute)… ${RESET}`);
-    const decomposed = await decomposeInspiration(ctx, inspirationId, userPrompt);
-    if (!ctx.json)
-        console.log(`${GREEN}done${RESET}`);
-    const defaultForkId = decomposed.json?.default_fork_id;
+    // Slideshows (TikTok photo/carousel posts) have no source video to slice —
+    // they're already an editable image timeline — so skip decompose and fork the
+    // ready slideshow template directly.
+    const isSlideshow = String(ready.media_kind ?? "") === "slideshow";
+    let defaultForkId;
+    if (isSlideshow) {
+        const slideCount = Array.isArray(ready.slide_image_urls) ? ready.slide_image_urls.length : 0;
+        if (!ctx.json)
+            console.log(`${DIM}Slideshow (${slideCount} slides) — already an editable image timeline, skipping decompose.${RESET}`);
+    }
+    else {
+        if (!ctx.json)
+            process.stdout.write(`${DIM}Analyzing + recreating scenes (can take a minute)… ${RESET}`);
+        const decomposed = await decomposeInspiration(ctx, inspirationId, userPrompt);
+        if (!ctx.json)
+            console.log(`${GREEN}done${RESET}`);
+        defaultForkId = decomposed.json?.default_fork_id;
+    }
     // 4. Fork a personal editable copy (unless --no-fork opens the shared base).
     let forkId = defaultForkId;
     let openTemplate = templateId;
@@ -3436,8 +3643,8 @@ function speechKeyHint(kind) {
         : "OPENAI_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY";
     return `No local AI key found. Set ${preference} (or pass --gemini-key/--openai-key/--openrouter-key), or run with --cloud to use your saved Vidfarm provider keys.`;
 }
-async function downloadUrlToFile(url, dest) {
-    const res = await fetch(url);
+async function downloadUrlToFile(url, dest, headers) {
+    const res = await fetch(url, headers && Object.keys(headers).length ? { headers } : undefined);
     if (!res.ok || !res.body)
         throw new Error(`download failed (${res.status}) for ${url}`);
     mkdirSync(path.dirname(dest), { recursive: true });
@@ -3515,7 +3722,7 @@ async function runTtsCommand(argv) {
             // (speechKeyHint), speak through the local Kokoro engine so agents
             // always get audio out of the box.
             if (!json)
-                console.log(`${DIM}No provider key found — using the local Kokoro engine; pass --engine cloud + a key for BYOK voices. (${speechKeyHint("tts")})${RESET}`);
+                console.log(`${DIM}No provider key found — using the local Kokoro engine. For better voices or higher-throughput runs, bring your own audio key or use vidfarm cloud. (${speechKeyHint("tts")})${RESET}`);
             await runLocalKokoroTts({ text, voice, style, out: parsed.values.out, format: explicitFormat, json, fallback: true });
             return;
         }
@@ -3758,7 +3965,7 @@ async function runMusicCommand(argv) {
     if (parsed.values["own-key"])
         payload.use_wallet_credits = false;
     if (!ctx.json && !parsed.values["own-key"]) {
-        console.log(`${DIM}Composing with ElevenLabs on the platform key (wallet-billed). Add --own-key to use your own ElevenLabs key.${RESET}`);
+        console.log(`${DIM}Music generation runs through Vidfarm cloud on ElevenLabs (wallet-billed). Add --own-key to use your own ElevenLabs key; if you need a completely free local path, keep a human in the loop and skip AI music generation.${RESET}`);
     }
     const tracer = parsed.values.tracer ?? `devcli-music-${Date.now().toString(36)}`;
     const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/music/generate", auth: ctx.auth, body: { tracer, payload } });
@@ -3889,7 +4096,7 @@ async function runSttCommand(argv) {
             // (speechKeyHint), transcribe with the local whisper.cpp engine (word
             // timestamps, no speaker labels).
             if (!json)
-                console.log(`${DIM}No provider key found — using the local whisper.cpp engine; pass --engine cloud + a key for BYOK transcription (gemini adds speaker labels). (${speechKeyHint("stt")})${RESET}`);
+                console.log(`${DIM}No provider key found — using the local whisper.cpp engine. For better diarization or heavier workloads, bring your own audio key or use vidfarm cloud. (${speechKeyHint("stt")})${RESET}`);
             await runLocalWhisperStt({ target, out: parsed.values.out, json, language, fallback: true });
             return;
         }
@@ -4484,6 +4691,62 @@ function parseClipTime(value, label) {
         throw new Error(`--${label} "${raw}" isn't a valid number of seconds.`);
     return n;
 }
+function authHeadersForSourceUrl(sourceUrl, ctx) {
+    try {
+        const source = new URL(sourceUrl);
+        const host = new URL(ctx.host);
+        return source.origin === host.origin ? buildAuthHeaders(ctx.auth) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function uploadTemporaryFileToSpace(ctx, absPath, space) {
+    const form = new FormData();
+    form.append("file", new Blob([readFileSync(absPath)]), path.basename(absPath));
+    if (space === "local") {
+        const { withLocalBackend } = await import("./devcli/local-backend.js");
+        const backend = await withLocalBackend({ home: ctx.home, apiKey: ctx.auth.apiKey });
+        const res = await backend.app.request("/api/v1/user/me/temporary-files/upload", {
+            method: "POST",
+            headers: buildAuthHeaders({ apiKey: ctx.auth.apiKey || backend.apiKey, shareToken: ctx.auth.shareToken }),
+            body: form
+        });
+        const text = await res.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            json = null;
+        }
+        if (!res.ok)
+            throw new Error(`Upload failed (HTTP ${res.status}): ${(json && json.error) || text.slice(0, 200)}`);
+        const tempFileId = json?.file?.id ?? json?.id ?? json?.file_id;
+        if (!tempFileId)
+            throw new Error("Upload did not return a temporary file id.");
+        return String(tempFileId);
+    }
+    const res = await fetch(new URL("/api/v1/user/me/temporary-files/upload", ctx.host), {
+        method: "POST",
+        headers: buildAuthHeaders(ctx.auth),
+        body: form
+    });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    if (!res.ok)
+        throw new Error(`Upload failed (HTTP ${res.status}): ${(json && json.error) || text.slice(0, 200)}`);
+    const tempFileId = json?.file?.id ?? json?.id ?? json?.file_id;
+    if (!tempFileId)
+        throw new Error("Upload did not return a temporary file id.");
+    return String(tempFileId);
+}
 async function runClipperCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -4505,6 +4768,9 @@ async function runClipperCommand(argv) {
         throw new Error("clipper requires a source: `vidfarm clipper <video-url|file> [--start <t> --end <t>] [--tracer NAME] [--folder NAME] [--name NAME]`. Omit --start/--end to import the WHOLE video.");
     }
     const ctx = commonContext(parsed.values);
+    if (ctx.target === "both")
+        throw new Error("clipper only supports one backend at a time. Omit --cloud for the local-first path, or pass --cloud for vidfarm.cc.");
+    const target = ctx.target === "cloud" ? "cloud" : "local";
     const rawStart = (parsed.values.start ?? parsed.values.in);
     const rawEnd = (parsed.values.end ?? parsed.values.out);
     const hasStart = rawStart !== undefined && String(rawStart).trim() !== "";
@@ -4527,71 +4793,69 @@ async function runClipperCommand(argv) {
         body.name = String(parsed.values.name);
     if (audioOnly)
         body.audio_only = true;
-    // Resolve the source into the body once: a URL rides as source_url; a local
-    // file is staged into the temp store and referenced by temp_file_id.
-    if (/^https?:\/\//i.test(source)) {
-        body.source_url = source;
-    }
-    else {
-        const abs = path.resolve(process.cwd(), source.replace(/^@/, ""));
-        if (!existsSync(abs))
-            throw new Error(`No such file or URL: ${source}`);
-        const form = new FormData();
-        form.append("file", new Blob([readFileSync(abs)]), path.basename(abs));
-        const up = await fetch(new URL("/api/v1/user/me/temporary-files/upload", ctx.host), { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
-        const upText = await up.text();
-        let upJson = null;
-        try {
-            upJson = upText ? JSON.parse(upText) : null;
+    // Local-first: local URL clipping hands the source page URL straight to the
+    // local backend, which resolves direct media from page metadata/JSON-LD (and
+    // only falls back to RapidAPI when configured). Cloud mode still hands the
+    // URL to vidfarm.cc; local file paths are staged into the chosen backend.
+    const sourceIsUrl = /^https?:\/\//i.test(source);
+    let stagedDir = null;
+    try {
+        if (sourceIsUrl) {
+            body.source_url = source;
         }
-        catch {
-            upJson = null;
+        else {
+            const abs = path.resolve(process.cwd(), source.replace(/^@/, ""));
+            if (!existsSync(abs))
+                throw new Error(`No such file or URL: ${source}`);
+            body.temp_file_id = await uploadTemporaryFileToSpace(ctx, abs, target);
+            if (!body.name)
+                body.name = path.basename(abs);
+        }
+        if (wholeVideo) {
+            // Entirety → import the whole source as ONE raw (no trim/re-encode), the same
+            // import_only path as `upload-media --from raw` and the /tools/clipper page's
+            // Whole-video button.
+            body.import_only = true;
+            const res = target === "local"
+                ? await dispatch(ctx, { method: "POST", path: "/raws/scan", body }, "local")
+                : await apiRequest({ method: "POST", host: ctx.host, path: "/raws/scan", auth: ctx.auth, body });
+            assertApiOk(res, "clipper (whole-video import)");
+            if (ctx.json) {
+                printJson({ ok: true, mode: "whole", target, ...res.json });
+                return;
+            }
+            const j = res.json;
+            const dest = parsed.values.folder ? `/raws/${String(parsed.values.folder)}` : "your raws library";
+            console.log(`${GREEN}Imported the whole video → ${dest} (${target}, scan ${j?.scan_id ?? "?"}, status ${j?.status ?? "?"}).${RESET}`);
+            console.log(`${DIM}Grab an exact subrange instead with --start <t> --end <t>.${RESET}`);
+            return;
         }
-        if (!up.ok)
-            throw new Error(`Upload failed (HTTP ${up.status}): ${(upJson && upJson.error) || upText.slice(0, 200)}`);
-        const tempFileId = upJson?.file?.id ?? upJson?.id ?? upJson?.file_id;
-        if (!tempFileId)
-            throw new Error("Upload did not return a temporary file id.");
-        body.temp_file_id = String(tempFileId);
-        if (!body.name)
-            body.name = path.basename(abs);
-    }
-    if (wholeVideo) {
-        // Entirety → import the whole source as ONE raw (no trim/re-encode), the same
-        // import_only path as `upload-media --from raw` and the /tools/clipper page's
-        // Whole-video button.
-        body.import_only = true;
-        const res = await apiRequest({ method: "POST", host: ctx.host, path: "/raws/scan", auth: ctx.auth, body });
-        assertApiOk(res, "clipper (whole-video import)");
+        const startSec = parseClipTime(rawStart, "start");
+        const endSec = parseClipTime(rawEnd, "end");
+        if (endSec <= startSec)
+            throw new Error(`--end (${endSec}s) must be greater than --start (${startSec}s).`);
+        body.start_sec = Number(startSec.toFixed(3));
+        body.end_sec = Number(endSec.toFixed(3));
+        const res = target === "local"
+            ? await dispatch(ctx, { method: "POST", path: "/raws/clip-range", body }, "local")
+            : await apiRequest({ method: "POST", host: ctx.host, path: "/raws/clip-range", auth: ctx.auth, body });
+        assertApiOk(res, "clipper");
         if (ctx.json) {
-            printJson({ ok: true, mode: "whole", ...res.json });
+            printJson({ ok: true, mode: "range", target, ...res.json });
             return;
         }
         const j = res.json;
-        const dest = parsed.values.folder ? `/raws/${String(parsed.values.folder)}` : "your raws library";
-        console.log(`${GREEN}Imported the whole video → ${dest} (scan ${j?.scan_id ?? "?"}, status ${j?.status ?? "?"}).${RESET}`);
-        console.log(`${DIM}Grab an exact subrange instead with --start <t> --end <t>.${RESET}`);
-        return;
+        const dest = j?.folder_path ? `/raws/${j.folder_path}` : "your raws library";
+        const kindWord = (j?.media_kind === "audio" || audioOnly) ? "audio" : "clip";
+        console.log(`${GREEN}Clipped ${kindWord} ${(j?.duration_sec ?? (endSec - startSec)).toFixed?.(2) ?? j?.duration_sec}s → ${dest} (${target}, clip ${j?.clip_id ?? "?"}).${RESET}`);
+        if (j?.view_url)
+            console.log(`${DIM}Preview: ${new URL(j.view_url, ctx.host).toString()}${RESET}`);
+        console.log(`${DIM}Grab another range from the same source with the same --tracer/--folder.${RESET}`);
     }
-    const startSec = parseClipTime(rawStart, "start");
-    const endSec = parseClipTime(rawEnd, "end");
-    if (endSec <= startSec)
-        throw new Error(`--end (${endSec}s) must be greater than --start (${startSec}s).`);
-    body.start_sec = Number(startSec.toFixed(3));
-    body.end_sec = Number(endSec.toFixed(3));
-    const res = await apiRequest({ method: "POST", host: ctx.host, path: "/raws/clip-range", auth: ctx.auth, body });
-    assertApiOk(res, "clipper");
-    if (ctx.json) {
-        printJson({ ok: true, mode: "range", ...res.json });
-        return;
+    finally {
+        if (stagedDir)
+            rmSync(stagedDir, { recursive: true, force: true });
     }
-    const j = res.json;
-    const dest = j?.folder_path ? `/raws/${j.folder_path}` : "your raws library";
-    const kindWord = (j?.media_kind === "audio" || audioOnly) ? "audio" : "clip";
-    console.log(`${GREEN}Clipped ${kindWord} ${(j?.duration_sec ?? (endSec - startSec)).toFixed?.(2) ?? j?.duration_sec}s → ${dest} (clip ${j?.clip_id ?? "?"}).${RESET}`);
-    if (j?.view_url)
-        console.log(`${DIM}Preview: ${new URL(j.view_url, ctx.host).toString()}${RESET}`);
-    console.log(`${DIM}Grab another range from the same source with the same --tracer/--folder.${RESET}`);
 }
 async function runPullCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), dir: { type: "string" }, refetch: { type: "boolean", default: false } } });
@@ -4611,6 +4875,7 @@ async function runPullCommand(argv) {
     const hasCast = existsSync(path.join(dir, "cast.json"));
     const hasAnnotations = existsSync(path.join(dir, "scene-annotations.json"));
     const hasHarness = existsSync(path.join(dir, "editor-harness.json"));
+    const hasReplication = existsSync(path.join(dir, "replication-harness.json"));
     if (ctx.json) {
         printJson({
             ok: true,
@@ -4620,6 +4885,7 @@ async function runPullCommand(argv) {
             has_cast: hasCast,
             has_scene_annotations: hasAnnotations,
             has_editor_harness: hasHarness,
+            has_replication_harness: hasReplication,
             harness_context_path: harnessFiles.contextPath,
             harness_instructions_path: harnessFiles.instructionsPath,
             ...info
@@ -4634,7 +4900,7 @@ async function runPullCommand(argv) {
         const flags = [layer.is_timeline_proxy ? "proxy" : null, layer.is_full_canvas ? "full-canvas" : null].filter(Boolean).join(",");
         console.log(`  ${layer.key}  ${DIM}${layer.kind ?? "?"} ${layer.start}-${(layer.start + layer.duration).toFixed(2)}s track${layer.track}${flags ? ` [${flags}]` : ""}${layer.slug ? ` slug=${layer.slug}` : ""}${RESET}`);
     }
-    console.log(`${DIM}Grounding: ${hasContext ? "video-context.json ✓" : "video-context.json ✗ (run `vidfarm decompose`)"}, ${hasCast ? "cast.json ✓" : "cast.json ✗"}, ${hasAnnotations ? "scene-annotations.json ✓" : "scene-annotations.json ✗"}, ${hasHarness ? "editor-harness.json ✓ (style brief under .harness)" : "editor-harness.json ✗"}.${RESET}`);
+    console.log(`${DIM}Grounding: ${hasContext ? "video-context.json ✓" : "video-context.json ✗ (run `vidfarm decompose`)"}, ${hasCast ? "cast.json ✓" : "cast.json ✗"}, ${hasAnnotations ? "scene-annotations.json ✓" : "scene-annotations.json ✗"}, ${hasHarness ? "editor-harness.json ✓ (style brief under .harness)" : "editor-harness.json ✗"}, ${hasReplication ? "replication-harness.json ✓ (3-paintbrush build plan under .harness)" : "replication-harness.json ✗"}.${RESET}`);
     console.log(`${DIM}Agent brief: ${path.relative(dir, harnessFiles.instructionsPath) || path.basename(harnessFiles.instructionsPath)}; merged context: ${path.relative(dir, harnessFiles.contextPath)}.${RESET}`);
     console.log(`${DIM}Next: vidfarm generate video --prompt "..." --aspect-ratio ${info.aspect_ratio ?? "9:16"} --place ${dir} --at <gap start>|--replace <layer_key>${RESET}`);
 }
@@ -4848,7 +5114,7 @@ async function runAddProviderKeyCommand(argv) {
     const provider = parsed.positionals[0];
     const secret = parsed.positionals[1];
     if (!provider || !secret)
-        throw new Error("add-provider-key requires <provider> <secret> (provider: openai|gemini|openrouter|perplexity).");
+        throw new Error("add-provider-key requires <provider> <secret> (provider: openai|gemini|openrouter|perplexity|nvidia|elevenlabs).");
     const ctx = commonContext(parsed.values);
     const result = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/user/me/provider-keys", auth: ctx.auth, body: { provider, secret, label: parsed.values.label } });
     assertApiOk(result, "add-provider-key");