@mevdragon/vidfarm-devcli 0.6.0 → 0.7.1

package/dist/src/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { createWriteStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, createWriteStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
@@ -43,6 +44,11 @@ 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 template_id or --fork, pulls that composition
                               (or the template's default/shared decomposition) from
                               the cloud host onto local disk to edit offline.
@@ -51,8 +57,9 @@ Local editor loop:
     --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})
-    --api-key <key>           Cloud key for the pull (default: VIDFARM_API_KEY)
+    --api-key <key>           Cloud key for pulls/library/cloud render (default: VIDFARM_API_KEY)
     --refetch                 Overwrite local composition with the cloud copy
+    --no-cloud                Fully local: no cloud catalog, seeding, or cloud render
     --no-open                 Don't auto-open the browser
   <template_id> [opts]      Alias for 'serve <template_id>' (boot the local editor)
   publish [template_id]     Push local composition.html/json to your fork  → PUT/PATCH composition + POST versions
@@ -65,7 +72,10 @@ Discover & inspiration (browse the viral-video catalog, add your own source):
     --query <text>          Keyword search over the catalog
     --mine                  Only your own uploaded inspirations
     --limit <n>             Max results
-  inspiration-add <url>     Ingest a TikTok/YT/IG/X video as a template  → POST /discover/templates
+  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.
   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
 
@@ -93,19 +103,31 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --no-wait               Return the job id instead of polling to the URL
     --place <dir>           After generating, place it into that composition
     --at <time> | --replace <layer_key>   Placement (fill gap vs replace scene)
-  place <dir|composition.html>   Insert a media URL into a local composition
+  place <dir|composition.html>   Insert media into a local composition
                             (fill a gap or replace a scene) — same clip markup
                             the browser editor makes; serve live-morphs it.
-    --src <url>             Direct media URL to place (required)
-    --kind <video|image>    Media kind (inferred from the URL if omitted)
+    --src <url|file>        Media to place (required). A URL is used as-is; a
+                            LOCAL FILE PATH is imported without bloating S3 — a
+                            serve working copy copies it onto the box's own disk
+                            store (free, local render only); any other dir
+                            uploads it to the ephemeral temp store (folder below).
+    --base-url <url>        Serve box origin that hosts /storage (default
+                            http://localhost:3000) — set if you ran serve --port.
+    --folder <path>         Temp-store folder for uploaded local files (default: temp)
+    --kind <video|image>    Media kind (inferred from the URL/path if omitted)
     --at <time>             Start it at this time (seconds / mm:ss) — fill a gap
     --replace <layer_key>   Replace this scene/layer (copies its timing+geometry)
     --duration <n>          Timeline length in seconds
     --track <n>             Timeline layer index (auto if omitted)
     --x --y --width --height   Geometry as % (default full canvas 0/0/100/100)
     --object-fit <fit>      cover|contain|fill|none|scale-down (default cover)
-  ghostcut <forkId>         Read the two video sources: original vs      → GET  .../compositions/:forkId/ghostcut
-                            decomposed (caption-free), non-billing
+    --ken-burns <preset>    Animate a still image (slow pan/zoom): zoom-in|
+                            zoom-out|pan-left|pan-right|pan-up|pan-down|
+                            zoom-in-left|zoom-in-right
+    --ken-burns-intensity <n>   Travel/zoom strength 0.04-0.5 (default 0.18)
+  remove-video-captions <forkId>   Read the two video sources:        → GET  .../compositions/:forkId/remove-video-captions
+                            original vs decomposed (caption-free),
+                            non-billing (alias: ghostcut)
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
   render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/render
@@ -118,6 +140,10 @@ Generate AI media and drop it on the timeline (for local coding agents):
 
 Approve & schedule (publish a finished MP4 as a shareable post):
   approve                   Approve media into a preview/share page      → POST /api/v1/approved/posts
+    --video <url|file>      Primary MP4 (URL, or a local file auto-uploaded to temp/)
+    --media <url|file>      Extra media (repeatable; local files auto-upload to temp/)
+    --folder <path>         Temp-store folder for uploaded local files (default: temp)
+    --caption <text>        Post caption (required)
   posts                     List your approved posts                     → GET  /api/v1/approved/posts
   post <postId>             Read one approved post (prints share URL)    → GET  /api/v1/approved/posts/:postId
   schedule <postId>         Schedule an approved post to a channel       → POST /api/v1/approved/posts/:postId/schedules
@@ -139,7 +165,9 @@ Agent skill (install the latest director skill so your AI agent can act):
 
 Files (multi-step flows the devcli handles for you):
   upload <file>             Upload to the EPHEMERAL temp store, print URL → POST /api/v1/user/me/temporary-files/upload
-    --folder <path>         Namescope the upload under a product/offer folder
+    --folder <path>         Namescope the upload under a folder. Prefer a
+                            throwaway 'temp' folder (--folder temp) for scratch
+                            media so it never clutters your durable library.
   put-file [file]           Write a file INTO My Files (persistent lib)  → POST /api/v1/user/me/attachments/upload
     --folder <path>         Namescope under a product/offer folder (e.g. acme-skincare)
     --as <name>             Name the saved file (required for --content/--stdin)
@@ -153,6 +181,10 @@ Files (multi-step flows the devcli handles for you):
     --print                 Print text contents (md/txt/csv/json) instead of saving
   put-file / get-file / files are the My Files (persistent) read+write set;
   upload is the throwaway temp store for dropping media into a composition.
+  Local file paths: to avoid uploading assets to Vidfarm S3 at all, reference
+  them straight from disk with 'place --src ./clip.mp4' on a 'serve' box (copied
+  to that box's local disk store, free local render). When you DO need a durable
+  URL (cloud render/approve), keep it under a throwaway 'temp/' folder.
 
 Cost spectrum (default to the cheapest approach that works; see SKILL.director.md):
   free        Reuse a decomposed template, swap captions/images/existing MP4s
@@ -244,8 +276,9 @@ async function main() {
         case "decompose":
             await runDecomposeCommand(rest);
             return;
+        case "remove-video-captions":
         case "ghostcut":
-            await runGhostcutCommand(rest);
+            await runRemoveVideoCaptionsCommand(rest);
             return;
         case "versions":
             await runVersionsCommand(rest);
@@ -454,7 +487,10 @@ async function runServeCommand(argv) {
             share: { type: "string" },
             refetch: { type: "boolean", default: false },
             open: { type: "boolean", default: true },
-            "no-open": { type: "boolean", default: false }
+            "no-open": { type: "boolean", default: false },
+            // Disable the cloud passthrough entirely: /discover and /library list
+            // only local data and the editor offers no "Render in Cloud".
+            "no-cloud": { type: "boolean", default: false }
         }
     });
     const port = Number(parsed.values.port);
@@ -476,16 +512,33 @@ async function runServeCommand(argv) {
     const templateId = parsed.positionals[0];
     const forkFlag = parsed.values.fork;
     // Env MUST be set before importing runtime — config.ts reads it at module
-    // load. Force the fully-local drivers; keep any cloud creds already present
-    // in the environment so render passthrough still works.
+    // load. Force the fully-local drivers.
     process.env.RECORDS_DRIVER = "local";
     process.env.STORAGE_DRIVER = "local";
     process.env.AWS_S3_BUCKET = "";
+    // A dev-shell .env can carry the staging Step Functions ARN, which would
+    // silently route this box's renders to the cloud state machine. serve is
+    // local-render by definition — cloud rendering is the EXPLICIT
+    // render_target="cloud" upstream handoff (the editor's "Render in Cloud").
+    process.env.VIDFARM_JOB_STATE_MACHINE_ARN = "";
+    // Same trap as the state machine ARN: a dev-shell .env can carry the staging
+    // media-lambda URL, which would route probe/thumbnail/trim/etc. to a cloud
+    // Lambda that cannot fetch this box's localhost storage URLs ("fetch
+    // failed"). Media ops on a serve box always run in-process.
+    process.env.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_URL = "";
+    process.env.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_SECRET = "";
     process.env.VIDFARM_DATA_DIR = dataDir;
     process.env.VIDFARM_API_KEY = apiKey;
     process.env.PORT = String(port);
     if (!process.env.NODE_ENV)
         process.env.NODE_ENV = "development";
+    // Cloud passthrough: only the editor is local — /discover and /library keep
+    // 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"];
+    process.env.VIDFARM_UPSTREAM_HOST = cloudEnabled ? host : "";
+    process.env.VIDFARM_UPSTREAM_API_KEY = cloudEnabled ? (cloudApiKey ?? "") : "";
     const { startRuntime } = await import("./runtime.js");
     await startRuntime();
     // If a template/fork was requested, pull its composition from the cloud host
@@ -493,13 +546,14 @@ async function runServeCommand(argv) {
     // resolves it. Best-effort: a failure just drops us to /discover.
     let openTemplateId = templateId;
     let openForkId = forkFlag;
-    if (templateId || forkFlag) {
+    if ((templateId || forkFlag) && !cloudEnabled) {
+        console.warn("[vidfarm] serve: --no-cloud set — skipping cloud seed of the requested template/fork.");
+    }
+    else if (templateId || forkFlag) {
         try {
             const seeded = await seedForkFromCloud({
-                host,
                 templateId,
                 forkId: forkFlag,
-                cloudApiKey,
                 shareToken: parsed.values.share,
                 bootstrapKey: apiKey,
                 refetch: parsed.values.refetch
@@ -518,105 +572,45 @@ async function runServeCommand(argv) {
         ? `/editor/${encodeURIComponent(openTemplateId)}${openForkId ? `?fork=${encodeURIComponent(openForkId)}` : ""}`
         : "/discover";
     const openUrl = `${base}/auto-login?api_key=${encodeURIComponent(apiKey)}&redirect=${encodeURIComponent(editorPath)}`;
-    printServeBanner({ base, dataDir, openUrl, editorPath });
+    printServeBanner({ base, dataDir, openUrl, editorPath, cloud: cloudEnabled ? { host, hasKey: Boolean(cloudApiKey) } : null });
     const shouldOpen = parsed.values.open && !parsed.values["no-open"];
     if (shouldOpen)
         openInBrowser(openUrl);
     // startRuntime() keeps the process alive via its HTTP server; nothing else to do.
 }
 // Pull a cloud fork's composition onto local disk and create the local
-// template + fork records so the editor resolves it. The fork is either an
-// explicit --fork or the template's default fork (which may be another user's
-// public decomposition). Media stays on cloud URLs — only the composition +
-// records are localized. Runs in-process after startRuntime(), so it shares the
-// server's disk-backed records/storage singletons.
+// template + fork records so the editor resolves it. Thin wrapper over
+// services/upstream.ts seedFromUpstream (which reads VIDFARM_UPSTREAM_HOST/
+// _API_KEY — set above from --host/--api-key). Runs in-process after
+// startRuntime(), so it shares the server's disk-backed records/storage.
 async function seedForkFromCloud(input) {
-    const { serverlessRecords } = await import("./services/serverless-records.js");
-    const { StorageService } = await import("./services/storage.js");
     const { ServerlessAuthService } = await import("./services/serverless-auth.js");
-    const storage = new StorageService();
-    const auth = new ServerlessAuthService();
+    const { seedFromUpstream } = await import("./services/upstream.js");
     // Ensure the local bootstrap customer exists and grab its id to own the seed.
-    const customer = await auth.authenticate(input.bootstrapKey);
-    const authHeaders = buildAuthHeaders({ apiKey: input.cloudApiKey, shareToken: input.shareToken });
-    // 1. Resolve the source fork: explicit --fork wins, else the template's
-    //    default fork (grabs the shared decomposition even if another user owns it).
-    let cloudForkId = input.forkId ?? null;
-    if (!cloudForkId && input.templateId) {
-        cloudForkId = await resolveForkId({ host: input.host, templateId: input.templateId, apiKey: input.cloudApiKey, shareToken: input.shareToken });
-    }
-    if (!cloudForkId) {
-        console.warn("[vidfarm] serve: no --fork and no default fork resolvable from cloud; starting empty.");
-        return null;
-    }
-    // 2. Read the serialized fork for its template id + title.
-    const forkMetaRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}`, { headers: authHeaders });
-    const forkMeta = forkMetaRes.ok ? (await forkMetaRes.json().catch(() => null)) : null;
-    const templateId = input.templateId ?? (typeof forkMeta?.template_id === "string" ? forkMeta.template_id : null);
-    if (!templateId || !templateId.startsWith("template_")) {
-        console.warn(`[vidfarm] serve: could not determine a template id for fork ${cloudForkId}; starting empty.`);
-        return null;
-    }
-    const title = (typeof forkMeta?.title === "string" && forkMeta.title) || `Local · ${templateId}`;
-    // 3. Materialize the local template record (the editor 404s without it).
-    const existingTemplate = await serverlessRecords.getTemplate(templateId);
-    if (!existingTemplate) {
-        await serverlessRecords.createTemplate({
-            id: templateId,
-            inspirationId: `local:${templateId}`,
-            customerId: customer.id,
-            originalUrl: typeof forkMeta?.original_url === "string" ? forkMeta.original_url : "",
-            sourceHost: "local",
-            title,
-            visibility: "public"
-        });
-    }
-    // 4. Materialize the local fork (reuse the cloud id for stable URLs).
-    const localForkId = cloudForkId;
-    const existingFork = await serverlessRecords.getCompositionFork(localForkId);
-    if (!existingFork) {
-        await serverlessRecords.createCompositionFork({
-            id: localForkId,
-            customerId: customer.id,
-            templateId,
-            title,
-            visibility: "private"
-        });
-    }
-    // 5. Pull composition.html/json onto disk (skip if present unless --refetch,
-    //    so local edits aren't clobbered on re-serve).
-    const htmlKey = storage.compositionForkWorkingKey(localForkId, "composition.html");
-    const jsonKey = storage.compositionForkWorkingKey(localForkId, "composition.json");
-    const hasLocalHtml = Boolean(await storage.readText(htmlKey));
-    if (!hasLocalHtml || input.refetch) {
-        const htmlRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}/composition.html`, { headers: authHeaders });
-        if (!htmlRes.ok) {
-            console.warn(`[vidfarm] serve: could not fetch composition.html for ${cloudForkId} (${htmlRes.status}); starting empty.`);
-            return null;
-        }
-        await storage.putText(htmlKey, await htmlRes.text(), "text/html; charset=utf-8");
-        const jsonRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}/composition.json`, { headers: authHeaders });
-        if (jsonRes.ok)
-            await storage.putBuffer(jsonKey, Buffer.from(await jsonRes.text(), "utf8"), "application/json");
-        console.log(`[vidfarm] seeded fork ${localForkId} from ${input.host}`);
-    }
-    else {
-        console.log(`[vidfarm] fork ${localForkId} already local (use --refetch to overwrite)`);
-    }
-    // 6. Point the template's default fork at the local copy so a bare
-    //    /editor/:templateId resolves it too.
-    await serverlessRecords.stampDefaultForkIfUnset({ templateId, forkId: localForkId });
-    return { templateId, forkId: localForkId };
+    const customer = await new ServerlessAuthService().authenticate(input.bootstrapKey);
+    return seedFromUpstream({
+        customerId: customer.id,
+        templateId: input.templateId,
+        forkId: input.forkId,
+        shareToken: input.shareToken,
+        refetch: input.refetch
+    });
 }
 function printServeBanner(input) {
     const line = `${DIM}${"─".repeat(74)}${RESET}`;
     console.log("");
     console.log(line);
-    console.log(`${BOLD}${GREEN}  Vidfarm local server${RESET}  ${DIM}(fully local — records + storage on disk)${RESET}`);
+    console.log(`${BOLD}${GREEN}  Vidfarm local server${RESET}  ${DIM}(local editor — records + storage on disk)${RESET}`);
     console.log(line);
     console.log(`  server      ${input.base}`);
     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}`);
+    }
+    else {
+        console.log(`  cloud       ${DIM}off (--no-cloud) — local data only${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}`);
@@ -1168,17 +1162,77 @@ async function runVideosCommand(argv) {
     emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
 }
 async function runInspirationAddCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), tagline: { type: "string" }, notes: { type: "string" } } });
-    const sourceUrl = parsed.positionals[0];
-    if (!sourceUrl)
-        throw new Error("inspiration-add requires a video URL (TikTok/YouTube/Instagram/X).");
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), title: { type: "string" }, tagline: { type: "string" }, notes: { type: "string" } } });
+    const source = parsed.positionals[0];
+    if (!source)
+        throw new Error("inspiration-add requires a video URL (TikTok/YouTube/Instagram/X) or a local video file path.");
     const ctx = commonContext(parsed.values);
+    // Local file → upload flow: presign, PUT the bytes (straight to S3, or the
+    // server multipart fallback on a local-storage box), then finalize with the
+    // storage key. Anything that parses as http(s) keeps the classic URL ingest.
+    const isUrl = /^https?:\/\//i.test(source);
+    const localPath = isUrl ? null : path.resolve(process.cwd(), source);
+    if (localPath) {
+        if (!existsSync(localPath)) {
+            throw new Error(`inspiration-add: "${source}" is not an http(s) URL and no such local file exists.`);
+        }
+        const fileName = path.basename(localPath);
+        const buffer = readFileSync(localPath);
+        const contentType = guessContentType(fileName);
+        const presign = await apiRequest({
+            method: "POST",
+            host: ctx.host,
+            path: "/discover/templates/upload/presign",
+            auth: ctx.auth,
+            body: { file_name: fileName, content_type: contentType, size_bytes: buffer.byteLength }
+        });
+        assertApiOk(presign, "inspiration-add (presign)");
+        let storageKey = presign.json?.storage_key;
+        let uploadedName = presign.json?.file_name || fileName;
+        if (presign.json?.transport === "presigned" && presign.json?.upload?.url) {
+            const upload = presign.json.upload;
+            const put = await fetch(upload.url, {
+                method: upload.method || "PUT",
+                headers: upload.headers || {},
+                body: new Uint8Array(buffer)
+            });
+            if (!put.ok)
+                throw new Error(`inspiration-add upload failed with HTTP ${put.status}.`);
+        }
+        else {
+            const form = new FormData();
+            form.append("file", new Blob([new Uint8Array(buffer)], { type: contentType }), fileName);
+            const res = await fetch(new URL(presign.json?.upload?.url || "/discover/templates/upload", ctx.host), {
+                method: "POST",
+                headers: buildAuthHeaders(ctx.auth),
+                body: form
+            });
+            const json = await res.json().catch(() => null);
+            if (!res.ok || !json?.storage_key) {
+                throw new Error(`inspiration-add upload failed with HTTP ${res.status}${json?.error ? `: ${json.error}` : ""}.`);
+            }
+            storageKey = json.storage_key;
+            uploadedName = json.file_name || fileName;
+        }
+        if (!storageKey)
+            throw new Error("inspiration-add upload did not return a storage key.");
+        const result = await apiRequest({
+            method: "POST",
+            host: ctx.host,
+            path: "/discover/templates",
+            auth: ctx.auth,
+            body: { upload: { storage_key: storageKey, file_name: uploadedName }, title: parsed.values.title, tagline: parsed.values.tagline, notes: parsed.values.notes }
+        });
+        assertApiOk(result, "inspiration-add");
+        emitResult(result, ctx.json, [["Discover ", discoverFrontendUrl(ctx.host)]]);
+        return;
+    }
     const result = await apiRequest({
         method: "POST",
         host: ctx.host,
         path: "/discover/templates",
         auth: ctx.auth,
-        body: { source_url: sourceUrl, tagline: parsed.values.tagline, notes: parsed.values.notes }
+        body: { source_url: source, tagline: parsed.values.tagline, notes: parsed.values.notes }
     });
     assertApiOk(result, "inspiration-add");
     emitResult(result, ctx.json, [["Discover ", discoverFrontendUrl(ctx.host)]]);
@@ -1249,18 +1303,18 @@ async function runDecomposeCommand(argv) {
     });
     assertApiOk(result, "decompose");
     if (!ctx.json && result.json?.ghostcut_pending) {
-        console.log(`${DIM}GhostCut subtitle-removal is running in the background — poll \`vidfarm api POST /api/v1/compositions/${forkId}/ghostcut-poll\` or GET .../ghostcut until done.${RESET}`);
+        console.log(`${DIM}Subtitle removal (GhostCut) is running in the background — poll \`vidfarm api POST /api/v1/compositions/${forkId}/remove-video-captions-poll\` or GET .../remove-video-captions until done.${RESET}`);
     }
     emitResult(result, ctx.json);
 }
-async function runGhostcutCommand(argv) {
+async function runRemoveVideoCaptionsCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
     const forkId = parsed.positionals[0];
     if (!forkId)
-        throw new Error("ghostcut requires a fork id.");
+        throw new Error("remove-video-captions requires a fork id.");
     const ctx = commonContext(parsed.values);
-    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/ghostcut`, auth: ctx.auth });
-    assertApiOk(result, "ghostcut");
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/remove-video-captions`, auth: ctx.auth });
+    assertApiOk(result, "remove-video-captions");
     emitResult(result, ctx.json);
 }
 async function runVersionsCommand(argv) {
@@ -1412,25 +1466,7 @@ async function pollPrimitiveJob(ctx, jobId) {
 // Upload a local file to the ephemeral temp store, returning its durable URL.
 // Used to turn `--ref @local.png` into a direct asset URL for reference images.
 async function uploadTempFileForRef(ctx, absPath) {
-    if (!existsSync(absPath))
-        throw new Error(`No such reference file: ${absPath}`);
-    const form = new FormData();
-    form.append("file", new Blob([readFileSync(absPath)]), path.basename(absPath));
-    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(`reference upload failed (${res.status}): ${text.slice(0, 200)}`);
-    const url = json?.file?.view_url ?? json?.file?.s3_url;
-    if (!url)
-        throw new Error("reference upload returned no durable URL.");
-    return url;
+    return uploadLocalToTempStore(ctx, absPath);
 }
 // Resolve --ref values: pass http(s) URLs through; upload @local files.
 async function resolveReferenceUrls(ctx, refs) {
@@ -1468,6 +1504,100 @@ function resolveCompositionHtmlPath(target) {
         throw new Error(`No such composition file or dir: ${abs}.`);
     return abs;
 }
+// ── Local file paths as media (no S3 upload) ────────────────────────────────
+// Power users bulk-building compositions want to reference media that lives on
+// their own disk WITHOUT uploading every asset to Vidfarm storage. Two cases:
+//
+//   1. The composition is a `vidfarm serve` working copy (its path runs through
+//      <data-dir>/storage/compositions/forks/<forkId>/working/). That box renders
+//      IN-PROCESS for free and serves /storage/:key off local disk, so we just
+//      copy the file into the same disk store and reference it by the box's own
+//      localhost URL. Nothing ever touches S3.
+//   2. Any other composition dir (e.g. a `vidfarm pull` dir headed for cloud
+//      render/publish). The cloud renderer can't reach the user's disk, so a
+//      local file has to become a durable URL — we upload it to the EPHEMERAL
+//      temp store, namescoped under a folder (default `temp/`) so it stays easy
+//      to find and purge instead of bloating the durable library.
+//
+// A localhost /storage URL only resolves against the serve box that owns the
+// file, so case-1 compositions are for local render/preview; to render in the
+// cloud or share, upload the media (case 2) instead.
+// Read the durable URL out of a temporary-files upload response, tolerating both
+// the camelCase (viewUrl/s3Url) and snake_case (view_url/s3_url) shapes the API
+// has used across versions.
+function readUploadedFileUrl(json) {
+    const file = json?.file ?? {};
+    return file.viewUrl ?? file.view_url ?? file.s3Url ?? file.s3_url ?? null;
+}
+// If `htmlPath` sits inside a `vidfarm serve` disk store, return that store's
+// root (`<data-dir>/storage`); otherwise null. Detected structurally from the
+// canonical working-copy layout rather than any running server.
+function findServeStorageRoot(htmlPath) {
+    const norm = path.resolve(htmlPath);
+    const marker = `${path.sep}storage${path.sep}compositions${path.sep}forks${path.sep}`;
+    const idx = norm.indexOf(marker);
+    if (idx === -1)
+        return null;
+    return norm.slice(0, idx + `${path.sep}storage`.length);
+}
+// Copy a local media file into a serve box's disk store under a public-read key
+// and return that storage key. The key is stable-random so re-placing the same
+// file never collides.
+function importLocalMediaToServeStore(storageRoot, absFile) {
+    const safeName = path.basename(absFile).replace(/[^\w.\-]+/g, "_") || "media.bin";
+    const key = `users/local-media/${randomUUID()}/${safeName}`;
+    const dest = path.join(storageRoot, ...key.split("/"));
+    mkdirSync(path.dirname(dest), { recursive: true });
+    copyFileSync(absFile, dest);
+    return key;
+}
+function serveStorageUrl(baseUrl, key) {
+    return `${trimTrailingSlash(baseUrl)}/storage/${encodeURIComponent(key)}`;
+}
+// Upload a local file to the EPHEMERAL temp store on ctx.host, optionally
+// namescoped under a folder, and return its durable URL.
+async function uploadLocalToTempStore(ctx, absPath, folder) {
+    if (!existsSync(absPath))
+        throw new Error(`No such local file: ${absPath}`);
+    const form = new FormData();
+    form.append("file", new Blob([readFileSync(absPath)]), path.basename(absPath));
+    if (folder)
+        form.append("folder_path", folder);
+    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(`local media upload failed (${res.status}): ${text.slice(0, 200)}`);
+    const url = readUploadedFileUrl(json);
+    if (!url)
+        throw new Error("local media upload returned no durable URL.");
+    return url;
+}
+// Turn a --src value (http(s) URL or local file path) into a fetchable media
+// URL, importing/uploading local files as described above.
+async function resolvePlaceableMediaSrc(ctx, rawSrc, opts) {
+    const value = rawSrc.trim();
+    if (/^https?:\/\//i.test(value))
+        return { src: value, origin: "url", detail: null };
+    const abs = path.resolve(process.cwd(), value.startsWith("@") ? value.slice(1) : value);
+    if (!existsSync(abs)) {
+        throw new Error(`place --src "${rawSrc}" is neither an http(s) URL nor an existing local file.`);
+    }
+    const storageRoot = findServeStorageRoot(opts.htmlPath);
+    if (storageRoot) {
+        const key = importLocalMediaToServeStore(storageRoot, abs);
+        return { src: serveStorageUrl(opts.baseUrl, key), origin: "local-serve", detail: key };
+    }
+    const folder = opts.folder ?? "temp";
+    const url = await uploadLocalToTempStore(ctx, abs, folder);
+    return { src: url, origin: "cloud-temp", detail: folder };
+}
 // Apply an insert/replace of a media URL onto a composition.html on disk.
 function placeMediaOnDisk(input) {
     const html = readFileSync(input.htmlPath, "utf8");
@@ -1483,6 +1613,8 @@ function placeMediaOnDisk(input) {
         width: input.width,
         height: input.height,
         objectFit: input.objectFit,
+        kenBurns: input.kenBurns,
+        kenBurnsIntensity: input.kenBurnsIntensity,
         slug: input.slug
     };
     const result = input.replace
@@ -1512,6 +1644,8 @@ async function runGenerateCommand(argv) {
             at: { type: "string" },
             replace: { type: "string" },
             track: { type: "string" },
+            "ken-burns": { type: "string" },
+            "ken-burns-intensity": { type: "string" },
             "layer-key": { type: "string" }
         }
     });
@@ -1583,6 +1717,8 @@ async function runGenerateCommand(argv) {
             at: parsed.values.at ? parseTimeToSeconds(String(parsed.values.at)) : undefined,
             replace: parsed.values.replace,
             track: parsed.values.track ? Number(parsed.values.track) : undefined,
+            kenBurns: parsed.values["ken-burns"],
+            kenBurnsIntensity: parsed.values["ken-burns-intensity"] ? Number(parsed.values["ken-burns-intensity"]) : undefined,
             layerKey: parsed.values["layer-key"]
         });
         if (!ctx.json)
@@ -1614,21 +1750,34 @@ async function runPlaceCommand(argv) {
             width: { type: "string" },
             height: { type: "string" },
             "object-fit": { type: "string" },
+            "ken-burns": { type: "string" },
+            "ken-burns-intensity": { type: "string" },
             "layer-key": { type: "string" },
-            slug: { type: "string" }
+            slug: { type: "string" },
+            // Local file support: where a serve box serves /storage from, and which
+            // temp folder cloud uploads land under.
+            "base-url": { type: "string" },
+            folder: { type: "string" }
         }
     });
     const target = parsed.positionals[0];
     if (!target)
-        throw new Error("place requires a composition path: `vidfarm place <dir-or-composition.html> --src <url> ...`.");
-    const src = parsed.values.src;
-    if (!src || !/^https?:\/\//i.test(src))
-        throw new Error("place requires --src <direct media URL>.");
+        throw new Error("place requires a composition path: `vidfarm place <dir-or-composition.html> --src <url|file> ...`.");
+    const rawSrc = parsed.values.src;
+    if (!rawSrc)
+        throw new Error("place requires --src <media URL or local file path>.");
     const ctx = commonContext(parsed.values);
     const htmlPath = resolveCompositionHtmlPath(target);
+    const baseUrl = parsed.values["base-url"] ?? "http://localhost:3000";
+    const resolvedSrc = await resolvePlaceableMediaSrc(ctx, rawSrc, {
+        htmlPath,
+        baseUrl,
+        folder: parsed.values.folder
+    });
+    const src = resolvedSrc.src;
     const kind = parsed.values.kind === "video" || parsed.values.kind === "image"
         ? parsed.values.kind
-        : inferMediaKindFromUrl(src);
+        : inferMediaKindFromUrl(rawSrc);
     const num = (v) => (v !== undefined ? Number(v) : undefined);
     const placement = placeMediaOnDisk({
         htmlPath,
@@ -1643,13 +1792,21 @@ async function runPlaceCommand(argv) {
         width: num(parsed.values.width),
         height: num(parsed.values.height),
         objectFit: parsed.values["object-fit"],
+        kenBurns: parsed.values["ken-burns"],
+        kenBurnsIntensity: num(parsed.values["ken-burns-intensity"]),
         layerKey: parsed.values["layer-key"],
         slug: parsed.values.slug
     });
     if (ctx.json) {
-        printJson({ ok: true, layer_key: placement.layerKey, path: htmlPath, timeline_gaps: placement.gaps });
+        printJson({ ok: true, layer_key: placement.layerKey, path: htmlPath, src, media_origin: resolvedSrc.origin, timeline_gaps: placement.gaps });
     }
     else {
+        if (resolvedSrc.origin === "local-serve") {
+            console.log(`${DIM}Local file → serve disk store (${resolvedSrc.detail}); referenced as ${src}. No S3 upload. Renders on this serve box only.${RESET}`);
+        }
+        else if (resolvedSrc.origin === "cloud-temp") {
+            console.log(`${DIM}Local file → uploaded to ephemeral temp store under "${resolvedSrc.detail}/" on ${ctx.host}; referenced as ${src}.${RESET}`);
+        }
         console.log(`${GREEN}Placed ${kind} as ${placement.layerKey}${parsed.values.replace ? ` (replaced ${parsed.values.replace})` : ""} in ${htmlPath}.${RESET}`);
         console.log(`${DIM}Remaining timeline gaps: ${placement.gaps.length ? placement.gaps.map((g) => `${g.start}-${g.end}s`).join(", ") : "none"}.${RESET}`);
         console.log(`${DIM}Publish with: vidfarm publish --dir ${path.dirname(htmlPath)} --fork <forkId>  (or it live-morphs under \`serve\`).${RESET}`);
@@ -1743,6 +1900,7 @@ async function runApproveCommand(argv) {
             caption: { type: "string" },
             title: { type: "string" },
             pinned: { type: "string" },
+            folder: { type: "string" },
             tracer: { type: "string" }
         }
     });
@@ -1750,11 +1908,21 @@ async function runApproveCommand(argv) {
     const caption = parsed.values.caption;
     if (!caption)
         throw new Error("approve requires --caption <text>.");
+    // An approved post is a shareable cloud page, so any media must be a durable
+    // URL the page can load. Pass an http(s) URL through; a local file is uploaded
+    // to the ephemeral temp store (default folder `temp/`) first.
+    const uploadFolder = parsed.values.folder ?? "temp";
+    const resolveApproveMedia = async (value) => {
+        if (/^https?:\/\//i.test(value.trim()))
+            return value.trim();
+        const abs = path.resolve(process.cwd(), value.trim());
+        return uploadLocalToTempStore(ctx, abs, uploadFolder);
+    };
     const media = [];
     if (parsed.values.video)
-        media.push({ url: parsed.values.video, kind: "video", role: "primary" });
+        media.push({ url: await resolveApproveMedia(String(parsed.values.video)), kind: "video", role: "primary" });
     for (const url of parsed.values.media ?? [])
-        media.push({ url });
+        media.push({ url: await resolveApproveMedia(String(url)) });
     if (media.length === 0) {
         console.warn(`${DIM}[vidfarm] no --video / --media given; approving a text-only post.${RESET}`);
     }
@@ -1920,7 +2088,7 @@ async function runUploadCommand(argv) {
     }
     const result = { status: res.status, ok: res.ok, json, text };
     assertApiOk(result, "upload");
-    emitResult(result, ctx.json, [["Durable URL ", result.json?.file?.view_url ?? result.json?.file?.s3_url]]);
+    emitResult(result, ctx.json, [["Durable URL ", readUploadedFileUrl(result.json)]]);
 }
 async function runDownloadCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });