@mevdragon/vidfarm-devcli 0.7.0 → 0.8.0

package/dist/src/cli.js

@@ -1,13 +1,15 @@
 #!/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";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { computeCompositionGaps, insertMediaLayer, inspectComposition, replaceLayerWithMedia } from "./devcli/composition-edit.js";
+import { runClipsCommand } from "./devcli/clips.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
@@ -71,7 +73,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
 
@@ -99,20 +104,42 @@ 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)
+    --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)
+
+Clip curation (the third library — mine long-form video into a reusable clip store):
+  clips scan <video-path>   Detect scenes → tag + transcribe (Gemini)    LOCAL: ffmpeg + BYOK Gemini
+                            → embed → persist to ~/.vidfarm/clips.db.     (cloud: POST /clips/scan)
+    --tier flash|flash-lite   Gemini tier (default flash-lite, cheapest)
+    --dry-run                 Show the estimated cost and stop (over $1 needs --yes/confirm)
+  clips list                List the local clip library                  → GET  /clips
+  clips search "<text>"     Hybrid structured + semantic search          → POST /clips/search
+  clips preset list|run <name>|save <name> --from-query '<...>'          → /clips/presets
+  clips export <ids...> --to <dir>   Copy clip mp4s + metadata out
+                            (run 'vidfarm clips' for the full clips help)
   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
@@ -125,6 +152,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
@@ -146,7 +177,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)
@@ -160,6 +193,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
@@ -326,6 +363,9 @@ async function main() {
         case "save-file":
             await runPutFileCommand(rest);
             return;
+        case "clips":
+            await runClipsCommand(rest);
+            return;
         default:
             if (!command.startsWith("-")) {
                 // Positional template id → default to booting the local editor.
@@ -496,6 +536,12 @@ async function runServeCommand(argv) {
     // 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);
@@ -772,7 +818,10 @@ async function fetchCompositionFiles(input) {
     // can ground edits in what the video actually says and shows.
     // cast.json carries the identified recurring people/characters plus their
     // reference-still URLs so agents can reuse "the same person" in new gens.
-    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json"];
+    // scene-annotations.json carries the detected content format + per-scene
+    // literal + viral DNA an agent needs to REPLACE a scene from the clip library
+    // or RE-CREATE it from scratch (recreation_prompt + recreation_notes).
+    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json", "scene-annotations.json"];
     for (const filename of files) {
         const target = path.join(input.dir, filename);
         if (existsSync(target) && !input.refetch) {
@@ -1131,17 +1180,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)]]);
@@ -1214,6 +1323,43 @@ async function runDecomposeCommand(argv) {
     if (!ctx.json && result.json?.ghostcut_pending) {
         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}`);
     }
+    // The scene-annotation pass (per-scene clip-match + recreation DNA + content
+    // format) is seeded "pending" by decompose and runs as its own bounded vision
+    // call — kept out of the decompose request so that stays under the origin
+    // timeout. Drive it to completion here so CLI/agent users get annotations
+    // without needing the editor. Each poll is one call; usually one round
+    // finishes it. Best-effort: transient failures leave it pending for another
+    // client (or a later `vidfarm pull`) to finish.
+    if (!ctx.json)
+        process.stdout.write(`${DIM}Annotating scenes (clip-match + recreation DNA)… ${RESET}`);
+    let annotationStatus = "pending";
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        let poll;
+        try {
+            poll = await apiRequest({
+                method: "POST",
+                host: ctx.host,
+                path: `/api/v1/compositions/${encodeURIComponent(forkId)}/scene-annotations-poll`,
+                auth: ctx.auth,
+                body: {}
+            });
+        }
+        catch {
+            break;
+        }
+        annotationStatus = typeof poll.json?.status === "string" ? poll.json.status : "none";
+        if (annotationStatus === "none" || annotationStatus === "done" || annotationStatus === "failed")
+            break;
+        await sleep(3000);
+    }
+    if (!ctx.json) {
+        if (annotationStatus === "done")
+            console.log(`${GREEN}done${RESET}`);
+        else if (annotationStatus === "failed")
+            console.log(`${RED}failed${RESET} ${DIM}(run \`vidfarm api POST /api/v1/compositions/${forkId}/scene-annotations-poll\` to retry)${RESET}`);
+        else
+            console.log(`${DIM}still running — poll .../scene-annotations-poll until done${RESET}`);
+    }
     emitResult(result, ctx.json);
 }
 async function runRemoveVideoCaptionsCommand(argv) {
@@ -1375,25 +1521,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) {
@@ -1431,6 +1559,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");
@@ -1446,6 +1668,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
@@ -1475,6 +1699,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" }
         }
     });
@@ -1546,6 +1772,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)
@@ -1577,21 +1805,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,
@@ -1606,13 +1847,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}`);
@@ -1633,8 +1882,9 @@ async function runPullCommand(argv) {
     const info = inspectComposition(readFileSync(htmlPath, "utf8"));
     const hasContext = existsSync(path.join(dir, "video-context.json"));
     const hasCast = existsSync(path.join(dir, "cast.json"));
+    const hasAnnotations = existsSync(path.join(dir, "scene-annotations.json"));
     if (ctx.json) {
-        printJson({ ok: true, fork_id: forkId, dir, has_video_context: hasContext, has_cast: hasCast, ...info });
+        printJson({ ok: true, fork_id: forkId, dir, has_video_context: hasContext, has_cast: hasCast, has_scene_annotations: hasAnnotations, ...info });
         return;
     }
     console.log(`${GREEN}Pulled ${forkId} → ${dir}${RESET}`);
@@ -1645,7 +1895,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 ✗"}.${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 ✗"}.${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}`);
 }
 async function runVisibilityCommand(argv) {
@@ -1706,6 +1956,7 @@ async function runApproveCommand(argv) {
             caption: { type: "string" },
             title: { type: "string" },
             pinned: { type: "string" },
+            folder: { type: "string" },
             tracer: { type: "string" }
         }
     });
@@ -1713,11 +1964,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}`);
     }
@@ -1883,7 +2144,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() });

package/dist/src/composition-runtime.js

@@ -146,6 +146,31 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
     }
   }
 
+  // Ken Burns image clips carry a CSS transform animation (vf-kb-* keyframes)
+  // directly on the [data-kenburns] <img>. CSS animations run on the wall clock,
+  // not player time, so the runtime scrubs them: pause + set currentTime from
+  // normalized clip progress. Normalizing against data-duration (instead of
+  // trusting the inline --vf-kb-dur) keeps the preview correct even while a
+  // timeline resize has not yet re-synced the inline duration.
+  function syncKenBurnsClip(clip, timing) {
+    if (typeof clip.getAnimations !== "function") return;
+    const progress = timing.duration > 0
+      ? Math.max(0, Math.min(1, (time - timing.start) / timing.duration))
+      : 0;
+    let anims = [];
+    try { anims = clip.getAnimations({ subtree: true }); } catch { return; }
+    for (const anim of anims) {
+      if (typeof anim.animationName !== "string" || anim.animationName.indexOf("vf-kb-") !== 0) continue;
+      let total = 0;
+      try { total = Number(anim.effect?.getComputedTiming?.().duration) || 0; } catch {}
+      if (!total) continue;
+      try {
+        anim.pause();
+        anim.currentTime = progress * total;
+      } catch {}
+    }
+  }
+
   function apply(nextTime, options = {}) {
     const forceSeek = Boolean(options.forceSeek);
     const fromClock = Boolean(options.fromClock);
@@ -160,6 +185,7 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
         } else {
           setVisibility(clip, active);
         }
+        if (clip.hasAttribute("data-kenburns")) syncKenBurnsClip(clip, timing);
       }
       if (clip instanceof HTMLMediaElement) {
         applyMediaState(clip);

package/dist/src/config.js

@@ -108,6 +108,12 @@ const schema = z.object({
     VIDFARM_RATE_LIMITS_TABLE_NAME: z.string().optional(),
     VIDFARM_SERVERLESS_MAIN_TABLE_NAME: z.string().optional(),
     VIDFARM_JOB_STATE_MACHINE_ARN: z.string().optional(),
+    // Clip-curation scan pipeline (Step Functions). Optional: when unset, the
+    // /clips/scan route records the scan request but doesn't dispatch the machine.
+    VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN: z.string().optional(),
+    VIDFARM_CLIP_VECTOR_BACKEND: z.enum(["dynamo", "s3vectors"]).default("dynamo"),
+    VIDFARM_CLIP_VECTORS_BUCKET: z.string().optional(),
+    VIDFARM_CLIP_VECTORS_INDEX: z.string().optional(),
     SENTRY_DSN: z.string().optional(),
     SENTRY_ENVIRONMENT: z.string().optional(),
     SENTRY_RELEASE: z.string().optional(),