@mevdragon/vidfarm-devcli 0.18.1 → 0.19.0

package/dist/src/cli.js

@@ -8,11 +8,11 @@ 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 { computeCompositionGaps, insertMediaLayer, inspectComposition, replaceLayerWithMedia, setLayerMedia } from "./devcli/composition-edit.js";
 import { runCaptionsCommand } from "./devcli/captions.js";
 import { runClipsCommand } from "./devcli/clips.js";
 import { runTransitionsCommand } from "./devcli/transitions.js";
-import { runKeyframesCommand, runMoveCommand, runRestackCommand, runRippleCommand, runTrimCommand } from "./devcli/timeline-edit.js";
+import { runDuplicateCommand, runKeyframesCommand, runMoveCommand, runRestackCommand, runRetimeCommand, runRippleCommand, runSetCompositionCommand, runSetIdentityCommand, runSetStyleCommand, runSetTextCommand, runSetVisualCommand, runSplitCommand, runTrimCommand } from "./devcli/timeline-edit.js";
 import { MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES, loadSpeechAudioLocally, localGenerateSpeech, localTranscribeSpeech, resolveLocalSpeechAuth } from "./devcli/speech.js";
 import { buildSrtFromSegments, inferSpeechProviderForVoice } from "./services/speech.js";
 import { formatCompositionLintIssues, lintCompositionHtml } from "./services/composition-lint.js";
@@ -132,10 +132,45 @@ 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)
+  inpaint <image|url>       Masked image EDIT — replace ONLY the painted region  → POST /api/v1/primitives/images/inpaint
+    --mask <png|@file|url>  Alpha-mask PNG: TRANSPARENT pixels = the editable region (required)
+    --prompt <text>         Whole-image edit instruction (what to put in the mask)
+    --region "<label>=<p>"  Per-region prompt (repeatable) — mirrors the web's colored masks
+    --ref <url|@file>       Reference image (repeatable) → reference_attachments
+    --aspect-ratio <r>      e.g. 9:16 (omit for auto)
+    --provider <p>          openai|gemini|openrouter (omit to auto-pick)
+    --out <file>            Download the finished image to this path
+    --no-wait               Return the job id instead of polling to the URL
+    --place <dir> --at <time>|--replace <layer_key>   Fuse onto a composition
+  create-overlay "<subject>"  Vox-style transparent OVERLAY — AI image on a forced
+                            green screen, chroma-keyed out in one job → transparent PNG
+                            → POST /api/v1/primitives/images/create-overlay
+    --key-color <c>         Background color to force + key (default #00FF00)
+    --aspect-ratio <r>      e.g. 1:1 (match how you'll place it)
+    --ref <url|@file>       Reference image (repeatable) → prompt_attachments
+    --tolerance <0..1>      Key radius (default 0.3); --softness <0..1> edge feather (0.1)
+    --no-despill            Skip edge color-fringe suppression
+    --provider <p> --model <m>   Image provider/model overrides (omit to auto-pick)
+    --out <file>            Download the transparent PNG to this path
+    --no-wait               Return the job id instead of polling to the URL
+    --place <dir> --at <time>|--replace <layer_key>   Fuse onto a composition
+  remove-background-greenscreen <image|url>   Cheap chroma-key removal of a FLAT
+                            solid background → transparent PNG (cloud primitive;
+                            differs from remove-background = local ONNX matting)
+                            → POST /api/v1/primitives/images/remove-background-greenscreen
+    --key-color <c>         Background color to key out (default #00FF00; e.g. #FFFFFF)
+    --tolerance <0..1>      Key radius (default 0.3); --softness <0..1> edge feather (0.1)
+    --no-despill            Skip edge color-fringe suppression
+    --out <file>            Download the transparent PNG to this path
   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|file>        Media to place (required). A URL is used as-is; a
+                            (fill a gap, replace a scene, or overlay an AUDIO
+                            track) — same clip markup the browser editor makes;
+                            serve live-morphs it.
+    --src <url|/root/path|file>   Media to place (required). A URL is used as-is;
+                            a MY FILES PATH (/files/… · /raws/… · /temp/… ·
+                            /projects/… · /approved/…) is resolved to its view URL
+                            via the directory API (the CLI twin of the
+                            /library/files picker; add --cloud for vidfarm.cc); 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
@@ -143,13 +178,27 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --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
+    --kind <video|image|audio>   Media kind (inferred from the URL/path if omitted).
+                            kind=audio lays a geometry-free <audio> track: multiple
+                            audio tracks mix together at render, each at its own
+                            --volume, so overlay narration (~1.0) + a low music bed
+                            (--volume 0.15) + SFX as separate "place --kind audio"
+                            calls. Split a template's baked music+narration into 2
+                            tracks this way when recreating it.
+    --volume <0..2>         Audio/video track level (default 1). Music bed ~0.1-0.2.
+    --muted                 Silence this track (or pass --volume 0)
+    --playback-start <s>    Media in-point for video/audio (skip into the file)
+    --at <time>             Start it at this time (seconds / mm:ss) — fill a gap.
+                            For audio, duration defaults to the rest of the timeline.
     --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)
+    --object-position <pos> Cover-crop focal point for aspect-mismatched media:
+                            a keyword (left|right|top|bottom|"top left"|...) or
+                            a percentage pair ("30% 50%") — keeps the subject in
+                            frame when a 16:9 clip fills a 9:16 canvas
     --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
@@ -165,9 +214,50 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             fade|fade-black|fade-white|flash|smoke|blur|
                             slide-*|wipe-*|zoom-in|zoom-out|circle-close
     --transition-out-duration <s>   Exit length in seconds 0.1-2.5 (default 0.5)
+  set-media <dir|composition.html>   Edit a media layer IN PLACE (the set_layer_media
+                            twin). Unlike 'place --replace' (delete + re-insert,
+                            new key), this keeps the SAME node/key/geometry/timing —
+                            it just mutates the chosen attributes. (alias: replace-media)
+    --layer <key|slug>      Media layer to edit (required)
+    --src <url|/root/path|file>   Swap the media source. Accepts a URL, a My Files
+                            path (/raws/… · /files/… — resolved via the directory
+                            API, add --cloud for vidfarm.cc), or a local file
+                            (imported like 'place --src').
+    --playback-start <s>    Media in-point (skip into the source file)
+    --source-out <s>        Media out-point (source seconds) → sets the timeline
+                            duration to (source_out − in-point), exactly like the
+                            web in/out segment picker. e.g. seconds 3-8 of a clip:
+                            --playback-start 3 --source-out 8
+    --duration <s>          Set the timeline duration directly (alt to --source-out)
+    --volume <0..2>         Track level        --muted / --no-muted   Silence toggle
+    --object-fit <fit>      cover|contain|fill|none|scale-down
+    --object-position <pos> Cover-crop focal point (keyword or "30% 50%")
+    --ken-burns <preset|none>   Still-image pan/zoom (see place); none clears
+    --ken-burns-intensity <n>   Travel/zoom strength 0.04-0.5
+    --transition <preset|none> [--transition-duration <s>]        Entrance transition
+    --transition-out <preset|none> [--transition-out-duration <s>]   Exit transition
+    --json
   remove-video-captions <forkId>   Read the two video sources:        → GET  .../compositions/:forkId/remove-video-captions
                             original vs decomposed (caption-free),
                             non-billing (alias: ghostcut)
+  upload-media <file|url|id>   The /editor "Upload media" button, from the CLI.
+                            Bring media in from one of three sources, then drop it
+                            onto a composition (alias: add-media).
+    --from computer|files|raw   computer = a LOCAL FILE; files = a My Files id/name,
+                            a directory path (/raws/… · /files/…), or a public URL;
+                            raw = import a VIDEO URL into the raws library. Inferred
+                            (computer vs files) when omitted.
+    --into <dir|composition.html>   Place the media onto this composition (computer/
+                            files). Without it, the resolved media URL is just printed.
+    --at <time>             Timeline start (seconds / mm:ss) — fill a gap
+    --in <s>                Source in-point (n-of-N segment start; --playback-start alias)
+    --duration <s>          Clip length in seconds (the "n" of the segment)
+    --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]
+                            (raw) AI-clip the video into matching moments instead of
+                            importing the whole thing (BYOK)
 
 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 +
@@ -179,12 +269,23 @@ Raws (the third library — mine long-form video into a reusable raws store):
     --no-text                 Prefer scenes WITHOUT captions/on-screen text (selection only)
     --cloud [--url <url>]     BACKUP: run on the deployed pipeline       → POST /raws/scan (+ poll)
                               (uploads to your temp folder — 30-day TTL — bills AWS compute only)
+    --folder <name>           (with --cloud) Save the mined clips into /raws/<name>
     --dry-run                 Show the estimated cost and stop (over $1 needs --yes/confirm)
   raws list                 List the local raws library                  → GET  /raws
   raws search "<text>"      Hybrid structured + semantic search          → POST /raws/search
   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)
+                            EXACT subrange and saves one raw.
+    --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).
+    --tracer <name>           Group this session's clips (also the default folder)
+    --folder <name>           Save the clip into /raws/<name>
+    --name <text>             Human name for the clip
+                            (multi-clip: re-run with a new range + same --tracer)
 
 Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit backup:
   tts "<text>"              Text → narration audio file.                 LOCAL: your OPENAI/GEMINI/
@@ -258,7 +359,10 @@ Fine timeline control (trackpad-level verbs on a pulled/served composition — l
                             'serve' host it renders in-process for FREE.
   render-status <forkId> <renderId>   Poll one render job               → GET  .../compositions/:forkId/renders/:renderId
   visibility <forkId> <private|public>   Set fork visibility            → PATCH .../compositions/:forkId/visibility
-  clone <forkId>            Clone a fork as a new starting point         → POST .../compositions/:forkId/clone
+  clone <forkId> [--from current|default] [--version N]
+                            New fork: --from current (default) branches this
+                            working copy; --from default starts fresh from the
+                            template's original default                  → POST .../compositions/:forkId/fork
   share-link <forkId>       Mint a share-token URL for a fork            → POST .../compositions/:forkId/share-links
 
 Local media engines & toolchain (all local, free, no account — no cloud key needed):
@@ -346,11 +450,17 @@ Files (multi-step flows the devcli handles for you):
   directory search <query>  Ranked search across the whole tree           → POST /api/v1/user/me/directory/search
     --path <scope>          Scope to a subtree · --mode auto|semantic|substring|path · --limit <n>
     --content-type <a,b>    Filter the /raws branch by shot-KIND tag (talking_head, b_roll, …)
-    (alias: dir)
+  directory rename <path> <new-name>  Rename a /files or /temp file/folder   → POST /api/v1/user/me/directory/rename
+    --file-id <id>          Rename a FILE (display name); omit to rename the folder at <path>
+  directory save-url <url>  Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
+    --folder <path>         Destination folder under /files (e.g. inpaints, promos)
+    --as <name>             Name the saved file · --notes <text> vector-embedded notes
+    (alias: dir · save-url|from-url|import-url — CLI twin of the "Save to Files" picker)
   put-file / get-file / files / annotate-file are the My Files (persistent) set;
   upload is the throwaway temp store for dropping media into a composition.
-  Annotate assets you'll want back — esp. character refs (character_sprite_card.png
-  + about_character.md) — so 'files --search "the mascot"' finds them later.
+  Annotate assets you'll want back — esp. recurring characters, kept under
+  /files/characters/<slug>/ as a trio (<character_id>.json e.g. character_zara.json
+  + character_sprite_card.png + character_about.md) — 'files --search "the mascot"' finds them.
   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
@@ -461,6 +571,18 @@ async function main() {
         case "generate":
             await runGenerateCommand(rest);
             return;
+        case "inpaint":
+            await runInpaintCommand(rest);
+            return;
+        case "create-overlay":
+        case "overlay":
+            await runCreateOverlayCommand(rest);
+            return;
+        case "remove-background-greenscreen":
+        case "rmbg-green":
+        case "greenscreen":
+            await runRemoveBackgroundGreenscreenCommand(rest);
+            return;
         case "tts":
             await runTtsCommand(rest);
             return;
@@ -471,6 +593,14 @@ async function main() {
         case "place":
             await runPlaceCommand(rest);
             return;
+        case "set-media":
+        case "replace-media":
+            await runSetMediaCommand(rest);
+            return;
+        case "upload-media":
+        case "add-media":
+            await runUploadMediaCommand(rest);
+            return;
         case "decompose":
             await runDecomposeCommand(rest);
             return;
@@ -556,10 +686,24 @@ async function main() {
         case "dir":
             await runDirectoryCommand(rest);
             return;
+        case "migrate-local": {
+            const { runMigrateLocalCommand } = await import("./devcli/migrate-local.js");
+            await runMigrateLocalCommand(rest);
+            return;
+        }
+        case "sync": {
+            const { runSyncCommand } = await import("./devcli/sync.js");
+            await runSyncCommand(rest);
+            return;
+        }
         case "raws":
         case "clips":
             await runClipsCommand(rest);
             return;
+        case "clipper":
+        case "clip-range":
+            await runClipperCommand(rest);
+            return;
         case "captions":
             await runCaptionsCommand(rest);
             return;
@@ -584,6 +728,31 @@ async function main() {
         case "zindex":
             await runRestackCommand(rest);
             return;
+        // Named layer-edit verbs — devcli twins of the web editor_action set.
+        case "set-style":
+            await runSetStyleCommand(rest);
+            return;
+        case "set-visual":
+            await runSetVisualCommand(rest);
+            return;
+        case "set-text":
+            await runSetTextCommand(rest);
+            return;
+        case "set-identity":
+            await runSetIdentityCommand(rest);
+            return;
+        case "duplicate":
+            await runDuplicateCommand(rest);
+            return;
+        case "split":
+            await runSplitCommand(rest);
+            return;
+        case "retime":
+            await runRetimeCommand(rest);
+            return;
+        case "set-composition":
+            await runSetCompositionCommand(rest);
+            return;
         // Local media engines + toolchain (bundled HyperFrames local commands —
         // free, no account — plus vidfarm-native lint/stills/doctor/skills).
         case "remove-background":
@@ -665,9 +834,33 @@ function commonOptions() {
         host: { type: "string", default: DEFAULT_HOST },
         "api-key": { type: "string" },
         share: { type: "string" },
-        json: { type: "boolean", default: false }
+        json: { type: "boolean", default: false },
+        // Dual local/cloud targeting (honored by directory/files/clips/sync). The
+        // devcli is LOCAL-FIRST: the file directory + raws library default to the
+        // on-disk backend `vidfarm serve` also reads. `--cloud` targets vidfarm.cc;
+        // `--both` queries and merges the two, labeling each item [local]/[cloud].
+        local: { type: "boolean", default: false },
+        cloud: { type: "boolean", default: false },
+        both: { type: "boolean", default: false },
+        home: { type: "string" }
     };
 }
+/** Resolve which backend a dual-target command should hit. Local-first: the
+ *  default is local unless --cloud/--both is given (or VIDFARM_TARGET overrides). */
+function resolveTarget(values) {
+    if (values.both)
+        return "both";
+    if (values.cloud && values.local)
+        return "both";
+    if (values.cloud)
+        return "cloud";
+    if (values.local)
+        return "local";
+    const envTarget = (process.env.VIDFARM_TARGET ?? "").trim().toLowerCase();
+    if (envTarget === "cloud" || envTarget === "both" || envTarget === "local")
+        return envTarget;
+    return "local";
+}
 function commonContext(values) {
     return {
         host: trimTrailingSlash(String(values.host ?? DEFAULT_HOST)),
@@ -675,9 +868,27 @@ function commonContext(values) {
             apiKey: values["api-key"] ?? process.env.VIDFARM_API_KEY,
             shareToken: values.share
         },
-        json: Boolean(values.json)
+        json: Boolean(values.json),
+        target: resolveTarget(values),
+        home: values.home
     };
 }
+/**
+ * One dispatch seam for dual local/cloud REST calls. `local` runs the request
+ * against the in-process app (disk backend); `cloud` fetches vidfarm.cc. Every
+ * dual-target command routes through here so it never branches on transport.
+ */
+async function dispatch(ctx, req, space) {
+    if (space === "local") {
+        const { localApiRequest } = await import("./devcli/local-backend.js");
+        return localApiRequest({ ...req, auth: ctx.auth, home: ctx.home });
+    }
+    return apiRequest({ ...req, host: ctx.host, auth: ctx.auth });
+}
+/** The concrete spaces a target expands to, in display order. */
+function targetSpaces(target) {
+    return target === "both" ? ["local", "cloud"] : [target];
+}
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
@@ -705,6 +916,32 @@ function editorFrontendUrl(host, templateId, forkId) {
 function discoverFrontendUrl(host) {
     return `${host}/discover`;
 }
+// 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
+// demo/src/HyperframesStudioEditor.tsx (the /tools/image page reads
+// source_image_url / source_image_name / tracer from the query string).
+function inpaintFrontendUrl(host, sourceImageUrl, sourceImageName) {
+    const params = new URLSearchParams();
+    if (sourceImageUrl) {
+        params.set("source_image_url", sourceImageUrl);
+        if (sourceImageName)
+            params.set("source_image_name", sourceImageName);
+    }
+    const query = params.toString();
+    return query ? `${host}/tools/image?${query}` : `${host}/tools/image`;
+}
+// Basename of a media URL (query/hash stripped), for a human-readable label.
+function fileNameFromMediaUrl(src) {
+    if (!src)
+        return undefined;
+    try {
+        return path.basename(new URL(src).pathname) || undefined;
+    }
+    catch {
+        return path.basename(src.split(/[?#]/)[0]) || undefined;
+    }
+}
 // Small arg helper: split "k=v" pairs for --query.
 function collectKeyValues(entries) {
     const out = {};
@@ -1068,7 +1305,11 @@ async function fetchCompositionFiles(input) {
     // 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"];
+    // editor-harness.json carries the technical EDITING DIRECTION (pace,
+    // typography, b-roll, transitions, audio, scene roles under `.harness`) so an
+    // agent can one-shot a clean, on-style edit — the "how to edit like this"
+    // companion to the video-context viral DNA.
+    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json", "scene-annotations.json", "editor-harness.json"];
     for (const filename of files) {
         const target = path.join(input.dir, filename);
         if (existsSync(target) && !input.refetch) {
@@ -2052,7 +2293,11 @@ async function resolveReferenceUrls(ctx, refs) {
     return out;
 }
 function inferMediaKindFromUrl(url) {
-    return /\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(url) ? "video" : "image";
+    if (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(url))
+        return "video";
+    if (/\.(mp3|wav|m4a|aac|ogg|oga|flac)(\?|#|$)/i.test(url))
+        return "audio";
+    return "image";
 }
 // Comma-separated shot-KIND filter (talking_head, b_roll, product_shot, …) →
 // the content_type array the /raws branch of the search endpoints honors.
@@ -2149,12 +2394,55 @@ async function uploadLocalToTempStore(ctx, absPath, folder) {
         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.
+// A value like "/raws/demos/hero.mp4" or "/files/logos/logo.png" is a My Files
+// directory path (one of the five unified roots), NOT a URL or a local disk
+// path — resolve it through the directory API. (Prefixes are inlined, not a
+// module const, because `void main()` runs before this line's module scope, so a
+// top-level const here would be in its temporal dead zone during dispatch.)
+function looksLikeMyFilesPath(value) {
+    const v = value.trim().toLowerCase();
+    return ["/files/", "/temp/", "/raws/", "/projects/", "/approved/"].some((prefix) => v.startsWith(prefix));
+}
+// Resolve a My Files path to its durable view URL by listing the parent folder
+// via the unified directory API — the CLI equivalent of picking a file in the
+// web /library/files selector. Honors --local/--cloud/--both (first match wins).
+async function resolveMyFilesPathToUrl(ctx, value) {
+    const canonical = value.trim().replace(/\/+$/, "");
+    const lastSlash = canonical.lastIndexOf("/");
+    const parent = lastSlash > 0 ? canonical.slice(0, lastSlash) : "/";
+    const basename = canonical.slice(lastSlash + 1);
+    for (const space of targetSpaces(ctx.target)) {
+        let res;
+        try {
+            res = await dispatch(ctx, { method: "GET", path: "/api/v1/user/me/directory", query: { path: parent } }, space);
+        }
+        catch {
+            continue;
+        }
+        if (!res.ok || !res.json)
+            continue;
+        const files = Array.isArray(res.json.files) ? res.json.files : [];
+        const match = files.find((f) => String(f?.path ?? "").toLowerCase() === canonical.toLowerCase()) ??
+            files.find((f) => String(f?.name ?? "") === basename);
+        if (match?.viewUrl)
+            return { url: String(match.viewUrl), name: String(match.name ?? basename) };
+    }
+    return null;
+}
+// Turn a --src value (http(s) URL, My Files path, 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 };
+    if (looksLikeMyFilesPath(value)) {
+        const resolved = await resolveMyFilesPathToUrl(ctx, value);
+        if (!resolved) {
+            const parent = value.replace(/\/[^/]*$/, "") || "/";
+            throw new Error(`--src "${rawSrc}" looks like a My Files path but no file was found there. Browse it with \`vidfarm directory ls ${parent}\` (add --cloud if it lives on vidfarm.cc), or pass the file's view URL.`);
+        }
+        return { src: resolved.url, origin: "url", detail: `myfiles:${value}` };
+    }
     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.`);
@@ -2183,12 +2471,16 @@ function placeMediaOnDisk(input) {
         width: input.width,
         height: input.height,
         objectFit: input.objectFit,
+        objectPosition: input.objectPosition,
         kenBurns: input.kenBurns,
         kenBurnsIntensity: input.kenBurnsIntensity,
         transition: input.transition,
         transitionDuration: input.transitionDuration,
         transitionOut: input.transitionOut,
         transitionOutDuration: input.transitionOutDuration,
+        volume: input.volume,
+        muted: input.muted,
+        playbackStart: input.playbackStart,
         slug: input.slug
     };
     const result = input.replace
@@ -2315,6 +2607,404 @@ async function runGenerateCommand(argv) {
             console.log(`${DIM}Place it with: vidfarm place <dir> --src "${mediaUrl}" --kind ${mediaType} --at <time>|--replace <layer_key>${RESET}`);
     }
 }
+// ── Inpaint: masked image edit ───────────────────────────────────────────────
+// The devcli twin of the web /tools/image page. The browser page rasterizes painted
+// strokes into an alpha mask (transparent = editable), composes one provider
+// instruction from a whole-image prompt + per-color region prompts via
+// buildInpaintInstruction, and POSTs to /api/v1/primitives/images/inpaint. This
+// command mirrors that exactly for scripted / agent use: it takes a source image
+// + an alpha-mask PNG + prompt(s), rebuilds the SAME INPAINTING SYSTEM WRAPPER,
+// submits the same payload shape, and polls to the finished URL — like `generate`
+// this is a cloud primitive job (apiRequest to ctx.host), not a local engine.
+// Parse repeatable --region "<label>=<prompt>" (also accepts "label: prompt").
+// Mirrors the web page's per-color mask prompts; the label is a text tag only.
+function parseInpaintRegions(values) {
+    const out = [];
+    for (const raw of values ?? []) {
+        const v = String(raw);
+        const eq = v.indexOf("=");
+        const colon = v.indexOf(":");
+        const sep = eq === -1 ? colon : colon === -1 ? eq : Math.min(eq, colon);
+        if (sep === -1) {
+            const prompt = v.trim();
+            if (prompt)
+                out.push({ label: `region ${out.length + 1}`, prompt });
+            continue;
+        }
+        const label = v.slice(0, sep).trim() || `region ${out.length + 1}`;
+        const prompt = v.slice(sep + 1).trim();
+        if (prompt)
+            out.push({ label, prompt });
+    }
+    return out;
+}
+// Port of buildInpaintInstruction() from src/reskin/inpaint-page.ts — keep the
+// wrapper text in sync so CLI and web edits behave identically at the provider.
+function buildCliInpaintInstruction(globalPrompt, regions, refCount) {
+    const g = globalPrompt.trim();
+    const rs = regions
+        .map((r) => ({ label: r.label.toUpperCase(), prompt: r.prompt.trim() }))
+        .filter((r) => r.prompt);
+    if (!g && !rs.length)
+        return "";
+    const refNotes = refCount > 0
+        ? "Reference image scope: " + Array.from({ length: refCount }, (_unused, i) => "reference image " + (i + 1) + " applies to the whole image instruction").join("; ") + ". Use each reference only for its stated scope and do not copy unrelated reference details into unmasked areas."
+        : "";
+    return [
+        "INPAINTING SYSTEM WRAPPER:",
+        "You are editing an existing image with an alpha mask. Treat transparent mask pixels as the only editable region. Everything outside the editable mask must remain the same image: preserve identity, layout, pose, camera angle, framing, background, lighting, colors, textures, text, logos, and all unmasked details.",
+        "Do not redraw, reinterpret, beautify, crop, zoom, rotate, expand, stylize, or otherwise alter unmasked content. Do not render the UI mask colors; they are labels only.",
+        "The final image must keep the original dimensions and aspect ratio unless the user explicitly asks for a dimension change.",
+        g ? "Whole image prompt: " + g + ". Apply this only as guidance for the masked edit and overall consistency; it does not permit changing unmasked content." : "",
+        rs.map((r) => "Masked region " + r.label + ": replace only that marked area with " + r.prompt + ". Match the surrounding perspective, lighting, grain, shadows, and edge blending.").join(" "),
+        refNotes
+    ].filter(Boolean).join(" ");
+}
+// Resolve a single source/mask arg to a durable URL: http(s) passes through,
+// @file / bare path uploads to the ephemeral temp store. Same rules as --ref.
+async function resolveSingleMediaUrl(ctx, value) {
+    const [url] = await resolveReferenceUrls(ctx, [value]);
+    if (!url)
+        throw new Error(`Could not resolve media: ${value}`);
+    return url;
+}
+async function runInpaintCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            source: { type: "string" },
+            mask: { type: "string" },
+            prompt: { type: "string" },
+            instruction: { type: "string" },
+            region: { type: "string", multiple: true },
+            ref: { type: "string", multiple: true },
+            "aspect-ratio": { type: "string" },
+            provider: { type: "string" },
+            out: { type: "string" },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" },
+            // Fused placement onto a local composition.html (same as `generate`).
+            place: { type: "string" },
+            at: { type: "string" },
+            replace: { type: "string" },
+            track: { type: "string" },
+            "ken-burns": { type: "string" },
+            "ken-burns-intensity": { type: "string" },
+            transition: { type: "string" },
+            "transition-duration": { type: "string" },
+            "transition-out": { type: "string" },
+            "transition-out-duration": { type: "string" },
+            "layer-key": { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const sourceArg = parsed.values.source ?? parsed.positionals[0];
+    if (!sourceArg)
+        throw new Error("inpaint requires a source image: `vidfarm inpaint <image|url> --mask <mask.png> --prompt \"...\"`.");
+    const maskArg = parsed.values.mask;
+    if (!maskArg)
+        throw new Error("inpaint requires --mask <alpha-png|url>: TRANSPARENT pixels mark the ONLY editable region.");
+    const globalPrompt = (parsed.values.instruction ?? parsed.values.prompt ?? "").trim();
+    const regions = parseInpaintRegions(parsed.values.region);
+    if (!globalPrompt && !regions.length) {
+        throw new Error("inpaint requires --prompt \"what to put in the masked area\" (or one or more --region \"label=prompt\").");
+    }
+    // Upload local source/mask/ref files to durable URLs (URLs pass through).
+    const [sourceUrl, maskUrl] = await Promise.all([
+        resolveSingleMediaUrl(ctx, sourceArg),
+        resolveSingleMediaUrl(ctx, maskArg)
+    ]);
+    const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
+    const instruction = buildCliInpaintInstruction(globalPrompt, regions, refs.length);
+    const payload = {
+        source_image_url: sourceUrl,
+        mask_url: maskUrl,
+        instruction,
+        reference_attachments: refs,
+        size: "auto",
+        output_format: "png"
+    };
+    if (parsed.values.provider)
+        payload.provider = parsed.values.provider;
+    if (parsed.values["aspect-ratio"])
+        payload.aspect_ratio = parsed.values["aspect-ratio"];
+    const tracer = parsed.values.tracer ?? `devcli-inpaint-${Date.now().toString(36)}`;
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/images/inpaint", auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "inpaint");
+    const jobId = submit.json?.job_id;
+    const wait = !parsed.values["no-wait"];
+    if (!wait || !jobId) {
+        if (!ctx.json && jobId)
+            console.log(`${DIM}Queued ${jobId} (tracer ${tracer}). Poll: vidfarm api GET /api/v1/user/me/jobs/${jobId} — or drop --no-wait to auto-poll.${RESET}`);
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json)
+        console.log(`${DIM}Editing image (${jobId})… polling every 5s.${RESET}`);
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const mediaUrl = resolveJobMediaUrl(job);
+    const status = String(job?.status ?? "");
+    if (!mediaUrl) {
+        if (ctx.json) {
+            printJson({ ok: false, job_id: jobId, status, job });
+        }
+        else {
+            console.log(`${RED}Inpaint ${status || "did not finish"} — no media URL.${RESET}`);
+            printJson(job);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    let outPath = null;
+    if (parsed.values.out) {
+        outPath = path.resolve(process.cwd(), String(parsed.values.out));
+        await downloadUrlToFile(mediaUrl, outPath);
+    }
+    // Optional fused placement onto a local composition.html (image kind).
+    let placement = null;
+    if (parsed.values.place) {
+        const htmlPath = resolveCompositionHtmlPath(String(parsed.values.place));
+        placement = placeMediaOnDisk({
+            htmlPath,
+            src: mediaUrl,
+            kind: "image",
+            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,
+            transition: parsed.values.transition,
+            transitionDuration: parsed.values["transition-duration"] ? Number(parsed.values["transition-duration"]) : undefined,
+            transitionOut: parsed.values["transition-out"],
+            transitionOutDuration: parsed.values["transition-out-duration"] ? Number(parsed.values["transition-out-duration"]) : undefined,
+            layerKey: parsed.values["layer-key"]
+        });
+        if (!ctx.json)
+            console.log(`${GREEN}Placed as ${placement.layerKey} in ${htmlPath}. Run \`vidfarm publish --dir ${path.dirname(htmlPath)}\` (or it live-morphs under \`serve\`).${RESET}`);
+    }
+    if (ctx.json) {
+        printJson({ ok: true, job_id: jobId, media_url: mediaUrl, out: outPath, placement });
+    }
+    else {
+        console.log(`${GREEN}Image edit ready:${RESET} ${mediaUrl}`);
+        if (outPath)
+            console.log(`${DIM}Saved to ${outPath}${RESET}`);
+        if (!placement)
+            console.log(`${DIM}Place it with: vidfarm place <dir> --src "${mediaUrl}" --kind image --at <time>|--replace <layer_key>${RESET}`);
+    }
+}
+// ── Create media overlay (Vox-style) ─────────────────────────────────────────
+// The devcli twin of the media_overlay primitive: generate an AI image on a
+// forced flat key-color background (BYOK image keys) then chroma-key it out to a
+// transparent PNG in ONE cloud job. Like `generate`/`inpaint` this is a cloud
+// primitive (apiRequest to ctx.host), and it shares the fused --place placement.
+async function runCreateOverlayCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            prompt: { type: "string" },
+            ref: { type: "string", multiple: true },
+            "aspect-ratio": { type: "string" },
+            "image-size": { type: "string" },
+            "key-color": { type: "string" },
+            tolerance: { type: "string" },
+            softness: { type: "string" },
+            "no-despill": { type: "boolean", default: false },
+            "output-format": { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            out: { type: "string" },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" },
+            // Fused placement onto a local composition.html (same as `generate`).
+            place: { type: "string" },
+            at: { type: "string" },
+            replace: { type: "string" },
+            track: { type: "string" },
+            "ken-burns": { type: "string" },
+            "ken-burns-intensity": { type: "string" },
+            transition: { type: "string" },
+            "transition-duration": { type: "string" },
+            "transition-out": { type: "string" },
+            "transition-out-duration": { type: "string" },
+            "layer-key": { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const prompt = (parsed.values.prompt ?? parsed.positionals.join(" ")).trim();
+    if (!prompt) {
+        throw new Error("create-overlay requires a subject prompt: `vidfarm create-overlay \"a cartoon rocket ship\" [--key-color #00FF00] [--out overlay.png]`. Describe ONLY the subject — the flat key-color background is added for you.");
+    }
+    const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
+    const payload = { prompt };
+    if (refs.length)
+        payload.prompt_attachments = refs.slice(0, 16);
+    if (parsed.values["aspect-ratio"])
+        payload.aspect_ratio = parsed.values["aspect-ratio"];
+    if (parsed.values["image-size"])
+        payload.image_size = parsed.values["image-size"];
+    if (parsed.values["key-color"])
+        payload.key_color = parsed.values["key-color"];
+    if (parsed.values.tolerance)
+        payload.tolerance = Number(parsed.values.tolerance);
+    if (parsed.values.softness)
+        payload.softness = Number(parsed.values.softness);
+    if (parsed.values["no-despill"])
+        payload.despill = false;
+    if (parsed.values["output-format"])
+        payload.output_format = parsed.values["output-format"];
+    if (parsed.values.provider)
+        payload.provider = parsed.values.provider;
+    if (parsed.values.model)
+        payload.model = parsed.values.model;
+    const tracer = parsed.values.tracer ?? `devcli-overlay-${Date.now().toString(36)}`;
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/images/create-overlay", auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "create-overlay");
+    const jobId = submit.json?.job_id;
+    const wait = !parsed.values["no-wait"];
+    if (!wait || !jobId) {
+        if (!ctx.json && jobId)
+            console.log(`${DIM}Queued ${jobId} (tracer ${tracer}). Poll: vidfarm api GET /api/v1/user/me/jobs/${jobId} — or drop --no-wait to auto-poll.${RESET}`);
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json)
+        console.log(`${DIM}Creating transparent overlay (${jobId})… polling every 5s.${RESET}`);
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const mediaUrl = resolveJobMediaUrl(job);
+    const status = String(job?.status ?? "");
+    if (!mediaUrl) {
+        if (ctx.json) {
+            printJson({ ok: false, job_id: jobId, status, job });
+        }
+        else {
+            console.log(`${RED}Overlay ${status || "did not finish"} — no media URL.${RESET}`);
+            printJson(job);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    let outPath = null;
+    if (parsed.values.out) {
+        outPath = path.resolve(process.cwd(), String(parsed.values.out));
+        await downloadUrlToFile(mediaUrl, outPath);
+    }
+    // Optional fused placement onto a local composition.html (image kind).
+    let placement = null;
+    if (parsed.values.place) {
+        const htmlPath = resolveCompositionHtmlPath(String(parsed.values.place));
+        placement = placeMediaOnDisk({
+            htmlPath,
+            src: mediaUrl,
+            kind: "image",
+            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,
+            transition: parsed.values.transition,
+            transitionDuration: parsed.values["transition-duration"] ? Number(parsed.values["transition-duration"]) : undefined,
+            transitionOut: parsed.values["transition-out"],
+            transitionOutDuration: parsed.values["transition-out-duration"] ? Number(parsed.values["transition-out-duration"]) : undefined,
+            layerKey: parsed.values["layer-key"]
+        });
+        if (!ctx.json)
+            console.log(`${GREEN}Placed as ${placement.layerKey} in ${htmlPath}. Run \`vidfarm publish --dir ${path.dirname(htmlPath)}\` (or it live-morphs under \`serve\`).${RESET}`);
+    }
+    if (ctx.json) {
+        printJson({ ok: true, job_id: jobId, media_url: mediaUrl, out: outPath, placement, greenscreen_source_url: job?.result?.greenscreen_source_url ?? null });
+    }
+    else {
+        console.log(`${GREEN}Transparent overlay ready:${RESET} ${mediaUrl}`);
+        if (outPath)
+            console.log(`${DIM}Saved to ${outPath}${RESET}`);
+        if (!placement)
+            console.log(`${DIM}Place it with: vidfarm place <dir> --src "${mediaUrl}" --kind image --at <time>|--replace <layer_key>${RESET}`);
+    }
+}
+// ── Green-screen (chroma-key) background removal ──────────────────────────────
+// The devcli twin of the image_remove_background_greenscreen primitive: cheap
+// local chroma key on a flat, solid background. A cloud primitive job (distinct
+// from `vidfarm remove-background`, which is the free LOCAL ONNX matting engine).
+async function runRemoveBackgroundGreenscreenCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            source: { type: "string" },
+            "key-color": { type: "string" },
+            tolerance: { type: "string" },
+            softness: { type: "string" },
+            "no-despill": { type: "boolean", default: false },
+            "output-format": { type: "string" },
+            out: { type: "string" },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const sourceArg = parsed.values.source ?? parsed.positionals[0];
+    if (!sourceArg) {
+        throw new Error("remove-background-greenscreen requires a source image: `vidfarm remove-background-greenscreen <image|url> [--key-color #00FF00] [--out cutout.png]`.");
+    }
+    const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
+    const payload = { source_image_url: sourceUrl };
+    if (parsed.values["key-color"])
+        payload.key_color = parsed.values["key-color"];
+    if (parsed.values.tolerance)
+        payload.tolerance = Number(parsed.values.tolerance);
+    if (parsed.values.softness)
+        payload.softness = Number(parsed.values.softness);
+    if (parsed.values["no-despill"])
+        payload.despill = false;
+    if (parsed.values["output-format"])
+        payload.output_format = parsed.values["output-format"];
+    const tracer = parsed.values.tracer ?? `devcli-gsbg-${Date.now().toString(36)}`;
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/images/remove-background-greenscreen", auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "remove-background-greenscreen");
+    const jobId = submit.json?.job_id;
+    const wait = !parsed.values["no-wait"];
+    if (!wait || !jobId) {
+        if (!ctx.json && jobId)
+            console.log(`${DIM}Queued ${jobId} (tracer ${tracer}). Poll: vidfarm api GET /api/v1/user/me/jobs/${jobId} — or drop --no-wait to auto-poll.${RESET}`);
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json)
+        console.log(`${DIM}Keying out background (${jobId})… polling every 5s.${RESET}`);
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const mediaUrl = resolveJobMediaUrl(job);
+    const status = String(job?.status ?? "");
+    if (!mediaUrl) {
+        if (ctx.json) {
+            printJson({ ok: false, job_id: jobId, status, job });
+        }
+        else {
+            console.log(`${RED}Chroma key ${status || "did not finish"} — no media URL.${RESET}`);
+            printJson(job);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    let outPath = null;
+    if (parsed.values.out) {
+        outPath = path.resolve(process.cwd(), String(parsed.values.out));
+        await downloadUrlToFile(mediaUrl, outPath);
+    }
+    if (ctx.json) {
+        printJson({ ok: true, job_id: jobId, media_url: mediaUrl, out: outPath, keyed_fraction: job?.result?.keyed_fraction ?? null });
+    }
+    else {
+        console.log(`${GREEN}Transparent cut-out ready:${RESET} ${mediaUrl}`);
+        if (outPath)
+            console.log(`${DIM}Saved to ${outPath}${RESET}`);
+    }
+}
 // ── Speech: tts / stt ────────────────────────────────────────────────────────
 // LOCAL-FIRST like `raws scan`: both commands default to running on the
 // user's OWN AI key (GEMINI_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY or
@@ -2896,14 +3586,24 @@ async function runPlaceCommand(argv) {
             width: { type: "string" },
             height: { type: "string" },
             "object-fit": { type: "string" },
+            "object-position": { type: "string" },
             "ken-burns": { type: "string" },
             "ken-burns-intensity": { type: "string" },
             transition: { type: "string" },
             "transition-duration": { type: "string" },
             "transition-out": { type: "string" },
             "transition-out-duration": { type: "string" },
+            // Audio (and video) level: --volume 0-2 (default 1), --muted to silence.
+            // These make `place --kind audio` a first-class way to overlay a
+            // narration / low-volume music bed / SFX as its own mixed track.
+            volume: { type: "string" },
+            muted: { type: "boolean", default: false },
+            "playback-start": { type: "string" },
             "layer-key": { type: "string" },
             slug: { type: "string" },
+            // Print the /tools/image "Create New" deep-link for the placed image (the
+            // devcli twin of the web editor's Create New button).
+            "print-inpaint-url": { type: "boolean", default: false },
             // Local file support: where a serve box serves /storage from, and which
             // temp folder cloud uploads land under.
             "base-url": { type: "string" },
@@ -2925,8 +3625,9 @@ async function runPlaceCommand(argv) {
         folder: parsed.values.folder
     });
     const src = resolvedSrc.src;
-    const kind = parsed.values.kind === "video" || parsed.values.kind === "image"
-        ? parsed.values.kind
+    const explicitKind = parsed.values.kind;
+    const kind = explicitKind === "video" || explicitKind === "image" || explicitKind === "audio"
+        ? explicitKind
         : inferMediaKindFromUrl(rawSrc);
     const num = (v) => (v !== undefined ? Number(v) : undefined);
     const placement = placeMediaOnDisk({
@@ -2942,17 +3643,24 @@ async function runPlaceCommand(argv) {
         width: num(parsed.values.width),
         height: num(parsed.values.height),
         objectFit: parsed.values["object-fit"],
+        objectPosition: parsed.values["object-position"],
         kenBurns: parsed.values["ken-burns"],
         kenBurnsIntensity: num(parsed.values["ken-burns-intensity"]),
         transition: parsed.values.transition,
         transitionDuration: num(parsed.values["transition-duration"]),
         transitionOut: parsed.values["transition-out"],
         transitionOutDuration: num(parsed.values["transition-out-duration"]),
+        volume: num(parsed.values.volume),
+        muted: Boolean(parsed.values.muted),
+        playbackStart: num(parsed.values["playback-start"]),
         layerKey: parsed.values["layer-key"],
         slug: parsed.values.slug
     });
+    // The /tools/image "Create New" hand-off only makes sense for images (masked
+    // inpaint is image-only), seeded with the freshly-placed src so the user can remix it.
+    const inpaintUrl = kind === "image" ? inpaintFrontendUrl(ctx.host, src, fileNameFromMediaUrl(src)) : null;
     if (ctx.json) {
-        printJson({ ok: true, layer_key: placement.layerKey, path: htmlPath, src, media_origin: resolvedSrc.origin, timeline_gaps: placement.gaps });
+        printJson({ ok: true, layer_key: placement.layerKey, path: htmlPath, src, media_origin: resolvedSrc.origin, timeline_gaps: placement.gaps, ...(inpaintUrl ? { inpaint_url: inpaintUrl } : {}) });
     }
     else {
         if (resolvedSrc.origin === "local-serve") {
@@ -2963,9 +3671,377 @@ async function runPlaceCommand(argv) {
         }
         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}`);
+        if (inpaintUrl && parsed.values["print-inpaint-url"]) {
+            console.log(`${DIM}Create New (remix this image in Inpaint): ${inpaintUrl}${RESET}`);
+        }
         console.log(`${DIM}Publish with: vidfarm publish --dir ${path.dirname(htmlPath)} --fork <forkId>  (or it live-morphs under \`serve\`).${RESET}`);
     }
 }
+// The devcli twin of the web editor's set_layer_media (and the inspector's
+// "Replace media" + segment). Edits a media layer IN PLACE — a --src swap keeps
+// the SAME node/key/geometry/timing (unlike `place --replace`, which deletes and
+// re-inserts with a fresh key). --src accepts a URL, a My Files path
+// (/raws/… · /files/… · …), or a local file (imported like `place --src`).
+async function runSetMediaCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            layer: { type: "string" },
+            src: { type: "string" },
+            volume: { type: "string" },
+            muted: { type: "boolean" },
+            "no-muted": { type: "boolean" },
+            "playback-start": { type: "string" },
+            "source-out": { type: "string" },
+            duration: { type: "string" },
+            "object-fit": { type: "string" },
+            "object-position": { type: "string" },
+            "ken-burns": { type: "string" },
+            "ken-burns-intensity": { type: "string" },
+            transition: { type: "string" },
+            "transition-duration": { type: "string" },
+            "transition-out": { type: "string" },
+            "transition-out-duration": { type: "string" },
+            "base-url": { type: "string" },
+            folder: { type: "string" }
+        }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("set-media requires a composition path: `vidfarm set-media <dir-or-composition.html> --layer <key> [--src <url|/raws/…|file>] ...`.");
+    const layer = parsed.values.layer?.trim();
+    if (!layer)
+        throw new Error("set-media requires --layer <layerKey|slug>.");
+    const ctx = commonContext(parsed.values);
+    const htmlPath = resolveCompositionHtmlPath(target);
+    let resolvedSrc;
+    let srcOrigin = null;
+    if (parsed.values.src !== undefined) {
+        const baseUrl = parsed.values["base-url"] ?? "http://localhost:3000";
+        const r = await resolvePlaceableMediaSrc(ctx, String(parsed.values.src), {
+            htmlPath,
+            baseUrl,
+            folder: parsed.values.folder
+        });
+        resolvedSrc = r.src;
+        srcOrigin = r.origin;
+    }
+    const muted = parsed.values.muted ? true : (parsed.values["no-muted"] ? false : undefined);
+    const num = (v) => (v !== undefined ? Number(v) : undefined);
+    const result = setLayerMedia(readFileSync(htmlPath, "utf8"), layer, {
+        src: resolvedSrc,
+        volume: num(parsed.values.volume),
+        muted,
+        playbackStart: num(parsed.values["playback-start"]),
+        sourceOut: num(parsed.values["source-out"]),
+        duration: num(parsed.values.duration),
+        objectFit: parsed.values["object-fit"],
+        objectPosition: parsed.values["object-position"],
+        kenBurns: parsed.values["ken-burns"],
+        kenBurnsIntensity: num(parsed.values["ken-burns-intensity"]),
+        transition: parsed.values.transition,
+        transitionDuration: num(parsed.values["transition-duration"]),
+        transitionOut: parsed.values["transition-out"],
+        transitionOutDuration: num(parsed.values["transition-out-duration"])
+    });
+    writeFileSync(htmlPath, result.html);
+    const gaps = computeCompositionGaps(result.html);
+    if (ctx.json) {
+        printJson({ ok: true, layer_key: result.layerKey, kind: result.kind, changed: result.changed, path: htmlPath, ...(resolvedSrc ? { src: resolvedSrc, media_origin: srcOrigin } : {}), timeline_gaps: gaps });
+        return;
+    }
+    if (srcOrigin === "local-serve")
+        console.log(`${DIM}Local file → serve disk store; renders on this serve box only.${RESET}`);
+    else if (srcOrigin === "cloud-temp")
+        console.log(`${DIM}Local file → ephemeral temp store on ${ctx.host}.${RESET}`);
+    console.log(`${GREEN}Edited ${result.kind} layer ${result.layerKey} in place (${result.changed.join(" ")}).${RESET}`);
+    console.log(`${DIM}Remaining timeline gaps: ${gaps.length ? 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}`);
+}
+// The devcli twin of the /editor "Upload media" button: bring media in via one
+// of three sources and (for computer/files) drop it onto a composition, honoring
+// a chosen segment (--in / --duration). "raw" imports a video into the Raws
+// library (optionally AI-clipped) under a named --folder.
+async function runUploadMediaCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            from: { type: "string" },
+            into: { type: "string" },
+            at: { type: "string" },
+            // The source in-point (n-of-N segment start). --in is the friendly alias.
+            in: { type: "string" },
+            "playback-start": { type: "string" },
+            duration: { type: "string" },
+            kind: { type: "string" },
+            track: { type: "string" },
+            replace: { type: "string" },
+            "base-url": { type: "string" },
+            // raw mode: destination Raws folder + AI-clip controls.
+            folder: { type: "string" },
+            clip: { type: "boolean", default: false },
+            prompt: { type: "string" },
+            provider: { type: "string" }
+        }
+    });
+    const source = parsed.positionals[0];
+    if (!source) {
+        throw new Error("upload-media requires a source: `vidfarm upload-media <file|url|id> --from computer|files|raw [--into <composition>] [--at N --in N --duration N] [--folder NAME --clip]`.");
+    }
+    const ctx = commonContext(parsed.values);
+    const explicitFrom = parsed.values.from?.trim();
+    const localCandidate = path.resolve(process.cwd(), source.replace(/^@/, ""));
+    const from = explicitFrom ?? (existsSync(localCandidate) ? "computer" : "files");
+    if (from !== "computer" && from !== "files" && from !== "raw") {
+        throw new Error(`--from must be computer | files | raw (got "${from}").`);
+    }
+    // ── Clip from Raw: import a video URL into the raws library (whole or AI-clipped). ──
+    if (from === "raw") {
+        if (!/^https?:\/\//i.test(source))
+            throw new Error("upload-media --from raw needs a video URL (TikTok / YouTube / Instagram / X / direct link).");
+        const clip = Boolean(parsed.values.clip);
+        const folderName = parsed.values.folder?.trim();
+        const body = { source_url: source };
+        if (clip) {
+            body.prompt = parsed.values.prompt?.trim() ?? "";
+            if (parsed.values.provider)
+                body.provider = parsed.values.provider;
+        }
+        else {
+            body.import_only = true;
+        }
+        if (folderName) {
+            body.folder_path = folderName;
+            body.tracer = folderName;
+        }
+        const res = await apiRequest({ method: "POST", host: ctx.host, path: "/raws/scan", auth: ctx.auth, body });
+        assertApiOk(res, "raws import");
+        const dest = folderName ? `/raws/${folderName}` : "your raws library";
+        if (ctx.json) {
+            printJson({ ok: true, ...res.json });
+            return;
+        }
+        console.log(`${GREEN}${clip ? "Started clip scan" : "Imported video"} → ${dest} (scan ${res.json?.scan_id ?? "?"}, status ${res.json?.status ?? "?"}).${RESET}`);
+        if (clip)
+            console.log(`${DIM}AI clipping runs on your saved key; new clips appear in the Raws library shortly.${RESET}`);
+        return;
+    }
+    // ── Upload from Computer / Attach from Files → a placeable media URL. ──
+    const into = parsed.values.into;
+    let mediaUrl;
+    let mediaName;
+    if (from === "files") {
+        if (/^https?:\/\//i.test(source)) {
+            mediaUrl = source;
+            mediaName = fileNameFromMediaUrl(source);
+        }
+        else if (looksLikeMyFilesPath(source)) {
+            // A unified directory path (/raws/… · /temp/… · /projects/… · /approved/… ·
+            // /files/…) — the CLI twin of picking a file in the /library/files selector.
+            const resolved = await resolveMyFilesPathToUrl(ctx, source);
+            if (!resolved)
+                throw new Error(`No My Files item at path "${source}". Browse with \`vidfarm directory ls ${source.replace(/\/[^/]*$/, "") || "/"}\` (add --cloud for vidfarm.cc), or pass an id/name/URL.`);
+            mediaUrl = resolved.url;
+            mediaName = resolved.name;
+        }
+        else {
+            const list = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/attachments", auth: ctx.auth });
+            assertApiOk(list, "My Files list");
+            const items = (list.json?.attachments ?? list.json?.files ?? []);
+            const match = items.find((a) => a.id === source || a.attachmentId === source || a.attachment_id === source) ??
+                items.find((a) => (a.fileName ?? a.file_name ?? a.name) === source);
+            if (!match)
+                throw new Error(`No My Files item with id or name "${source}". Run \`vidfarm files\` to list, or pass a public URL.`);
+            mediaUrl = String(match.viewUrl ?? match.view_url ?? match.publicUrl ?? match.url ?? "");
+            mediaName = (match.fileName ?? match.file_name ?? match.name);
+            if (!mediaUrl)
+                throw new Error("That My Files item has no resolvable URL.");
+        }
+    }
+    else {
+        // computer: resolve a local file → serve-disk store (when --into is a serve
+        // box's fork) or the ephemeral temp store, exactly like `place --src <file>`.
+        const baseUrl = parsed.values["base-url"] ?? "http://localhost:3000";
+        const htmlPath = into ? resolveCompositionHtmlPath(into) : path.resolve(process.cwd(), "composition.html");
+        const resolved = await resolvePlaceableMediaSrc(ctx, source, { htmlPath, baseUrl, folder: "uploads" });
+        mediaUrl = resolved.src;
+        mediaName = path.basename(localCandidate);
+    }
+    // No target composition → just report the URL (place it later with `place`).
+    if (!into) {
+        if (ctx.json) {
+            printJson({ ok: true, from, src: mediaUrl, name: mediaName ?? null });
+            return;
+        }
+        console.log(`${GREEN}Resolved media: ${mediaUrl}${RESET}`);
+        console.log(`${DIM}Place it with: vidfarm place <composition> --src "${mediaUrl}" [--at N --playback-start N --duration N]${RESET}`);
+        return;
+    }
+    const htmlPath = resolveCompositionHtmlPath(into);
+    const explicitKind = parsed.values.kind;
+    const kind = explicitKind === "video" || explicitKind === "image" || explicitKind === "audio" ? explicitKind : inferMediaKindFromUrl(mediaUrl);
+    const num = (v) => (v !== undefined ? Number(v) : undefined);
+    const inPoint = parsed.values.in ?? parsed.values["playback-start"];
+    const placement = placeMediaOnDisk({
+        htmlPath,
+        src: mediaUrl,
+        kind,
+        at: parsed.values.at ? parseTimeToSeconds(String(parsed.values.at)) : undefined,
+        duration: num(parsed.values.duration),
+        replace: parsed.values.replace,
+        track: num(parsed.values.track),
+        playbackStart: inPoint !== undefined ? Number(inPoint) : undefined
+    });
+    if (ctx.json) {
+        printJson({ ok: true, from, layer_key: placement.layerKey, path: htmlPath, src: mediaUrl, timeline_gaps: placement.gaps });
+        return;
+    }
+    console.log(`${GREEN}Added ${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}`);
+}
+// The devcli twin of the web /tools/clipper page: cut an EXACT subrange out of a
+// source video (URL or local file) straight into the raws library. Trims just the
+// [--start, --end] window via POST /raws/clip-range — reusable, multi-clip (run it
+// again with a new range for another clip under the same --tracer/--folder).
+// Times accept seconds (12.5) or HH:MM:SS:NNNN / MM:SS / SS[:NNNN] timecodes.
+function parseClipTime(value, label) {
+    const raw = (value ?? "").trim();
+    if (!raw)
+        throw new Error(`clipper needs --${label} (seconds or HH:MM:SS:NNNN).`);
+    if (raw.includes(":")) {
+        const parts = raw.split(":").map((p) => p.trim());
+        let h = 0, m = 0, s = 0, frac = 0;
+        if (parts.length === 4) {
+            [h, m, s] = parts.slice(0, 3).map(Number);
+            frac = Number(parts[3]) / Math.pow(10, parts[3].length || 4);
+        }
+        else if (parts.length === 3) {
+            [m, s] = parts.slice(0, 2).map(Number);
+            frac = Number(parts[2]) / Math.pow(10, parts[2].length || 4);
+        }
+        else if (parts.length === 2) {
+            s = Number(parts[0]);
+            frac = Number(parts[1]) / Math.pow(10, parts[1].length || 4);
+        }
+        else {
+            s = Number(parts[0]);
+        }
+        const total = h * 3600 + m * 60 + s + frac;
+        if (!Number.isFinite(total))
+            throw new Error(`--${label} "${raw}" isn't a valid timecode.`);
+        return total;
+    }
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        throw new Error(`--${label} "${raw}" isn't a valid number of seconds.`);
+    return n;
+}
+async function runClipperCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            start: { type: "string" },
+            in: { type: "string" },
+            end: { type: "string" },
+            out: { type: "string" },
+            tracer: { type: "string" },
+            folder: { type: "string" },
+            name: { type: "string" }
+        }
+    });
+    const source = parsed.positionals[0];
+    if (!source) {
+        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);
+    const rawStart = (parsed.values.start ?? parsed.values.in);
+    const rawEnd = (parsed.values.end ?? parsed.values.out);
+    const hasStart = rawStart !== undefined && String(rawStart).trim() !== "";
+    const hasEnd = rawEnd !== undefined && String(rawEnd).trim() !== "";
+    // Default = ENTIRETY: no range → import the whole source. A range trims exactly.
+    const wholeVideo = !hasStart && !hasEnd;
+    if (!wholeVideo && (!hasStart || !hasEnd)) {
+        throw new Error("clipper needs BOTH --start and --end for an exact subrange, or NEITHER to import the whole video.");
+    }
+    const body = {};
+    if (parsed.values.tracer)
+        body.tracer = String(parsed.values.tracer);
+    if (parsed.values.folder)
+        body.folder_path = String(parsed.values.folder);
+    if (parsed.values.name)
+        body.name = String(parsed.values.name);
+    // 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;
+        }
+        catch {
+            upJson = null;
+        }
+        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)");
+        if (ctx.json) {
+            printJson({ ok: true, mode: "whole", ...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 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;
+    }
+    const j = res.json;
+    const dest = j?.folder_path ? `/raws/${j.folder_path}` : "your raws library";
+    console.log(`${GREEN}Clipped ${(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 } } });
     const forkId = parsed.positionals[0];
@@ -2982,8 +4058,9 @@ async function runPullCommand(argv) {
     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"));
+    const hasHarness = existsSync(path.join(dir, "editor-harness.json"));
     if (ctx.json) {
-        printJson({ ok: true, fork_id: forkId, dir, has_video_context: hasContext, has_cast: hasCast, has_scene_annotations: hasAnnotations, ...info });
+        printJson({ ok: true, fork_id: forkId, dir, has_video_context: hasContext, has_cast: hasCast, has_scene_annotations: hasAnnotations, has_editor_harness: hasHarness, ...info });
         return;
     }
     console.log(`${GREEN}Pulled ${forkId} → ${dir}${RESET}`);
@@ -2994,7 +4071,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 ✗"}.${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}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) {
@@ -3010,17 +4087,20 @@ async function runVisibilityCommand(argv) {
     emitResult(result, ctx.json, templateId ? [["Open editor ", editorFrontendUrl(ctx.host, templateId, forkId)]] : undefined);
 }
 async function runCloneCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), version: { type: "string" }, title: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), version: { type: "string" }, title: { type: "string" }, from: { type: "string" } } });
     const forkId = parsed.positionals[0];
     if (!forkId)
         throw new Error("clone requires a fork id.");
+    const from = parsed.values.from === "default" ? "default" : "current";
     const ctx = commonContext(parsed.values);
+    // Unified fork endpoint: from=current branches this working copy (default),
+    // from=default starts fresh from the template's original default composition.
     const result = await apiRequest({
         method: "POST",
         host: ctx.host,
-        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/clone`,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/fork`,
         auth: ctx.auth,
-        body: { parent_version: parsed.values.version, title: parsed.values.title }
+        body: { from, parent_version: parsed.values.version, title: parsed.values.title }
     });
     assertApiOk(result, "clone");
     const newForkId = result.json?.fork_id;
@@ -3277,36 +4357,45 @@ async function runFilesCommand(argv) {
     const ctx = commonContext(parsed.values);
     const folderFilter = parsed.values.folder ? String(parsed.values.folder).replace(/^\/+|\/+$/g, "") : undefined;
     const contentTypes = parseContentTypeFlag(parsed.values["content-type"]);
-    if (parsed.values.search) {
-        // Meaning-first lookup: keyword + vector search over every file's
-        // name/folder/notes (BYOK embeddings; keyword-only without a saved key).
-        // content_type filters the /raws branch by shot-KIND tag (server-honored).
-        const result = await apiRequest({
-            method: "POST",
-            host: ctx.host,
-            path: "/api/v1/user/me/attachments/search",
-            auth: ctx.auth,
-            body: { query: String(parsed.values.search), ...(folderFilter ? { folder_path: folderFilter } : {}), ...(contentTypes.length ? { content_type: contentTypes } : {}) }
-        });
-        assertApiOk(result, "files --search");
+    const spaces = targetSpaces(ctx.target);
+    const multi = spaces.length > 1;
+    for (const space of spaces) {
+        if (multi && !ctx.json)
+            console.log(`${BOLD}── ${space} ──${RESET}`);
+        if (parsed.values.search) {
+            // Meaning-first lookup: keyword + vector search over every file's
+            // name/folder/notes (BYOK embeddings; keyword-only without a saved key).
+            // content_type filters the /raws branch by shot-KIND tag (server-honored).
+            const result = await dispatch(ctx, {
+                method: "POST",
+                path: "/api/v1/user/me/attachments/search",
+                body: { query: String(parsed.values.search), ...(folderFilter ? { folder_path: folderFilter } : {}), ...(contentTypes.length ? { content_type: contentTypes } : {}) }
+            }, space);
+            assertApiOk(result, `files --search (${space})`);
+            emitResult(result, ctx.json);
+            continue;
+        }
+        const result = await dispatch(ctx, { method: "GET", path: "/api/v1/user/me/attachments" }, space);
+        assertApiOk(result, `files (${space})`);
+        if (folderFilter && result.json && Array.isArray(result.json.attachments)) {
+            result.json = {
+                ...result.json,
+                attachments: result.json.attachments.filter((file) => (file?.folderPath ?? "") === folderFilter)
+            };
+        }
         emitResult(result, ctx.json);
-        return;
-    }
-    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/attachments", auth: ctx.auth });
-    assertApiOk(result, "files");
-    if (folderFilter && result.json && Array.isArray(result.json.attachments)) {
-        result.json = {
-            ...result.json,
-            attachments: result.json.attachments.filter((file) => (file?.folderPath ?? "") === folderFilter)
-        };
     }
-    emitResult(result, ctx.json);
 }
 // ── directory (unified virtual file tree) ────────────────────────────────────
-// Browse + search the three file roots (/files, /temp, /raws) as one tree via
-// the cloud REST directory endpoints. Same cloud auth (--api-key/VIDFARM_API_KEY,
-// --host, --json) as the rest of the wrapper commands.
-const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/files · /temp · /raws)
+// Browse + search the file roots (/files · /temp · /raws · /projects · /approved)
+// as one tree. LOCAL-FIRST: by default this reads the on-disk backend that
+// `vidfarm serve` also serves (so a `clips scan` is instantly browsable); pass
+// --cloud to read vidfarm.cc, or --both to merge the two ([local]/[cloud] tags).
+const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/files · /temp · /raws · /projects · /approved)
+
+  Target:  --local (default) · --cloud (vidfarm.cc) · --both (merge, tagged [local]/[cloud])
+           --home <dir> or VIDFARM_HOME (local backend home; default ~/.vidfarm)
+
 
   directory ls [path]              List folders + files under a path (default "/")   → GET /api/v1/user/me/directory
     --limit <n> --offset <n>       Paginate (server returns next_offset when more)
@@ -3320,6 +4409,20 @@ const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/fil
                                    reaction, interview, establishing, lifestyle, text_graphic)
     --limit <n> --json
 
+  directory rename <path> <new-name>   Rename a file or folder in /files or /temp  → POST /api/v1/user/me/directory/rename
+    --file-id <id>                 Rename a FILE (its display name); omit to rename the folder at <path>
+    --json                         Raw JSON response
+    e.g. vidfarm directory rename /files/characters/zara zara-fox
+         vidfarm directory rename /files/characters/zara/notes.md character_about.md --file-id att_123
+
+  directory save-url <url>         Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
+    --folder <path>                Destination folder under /files (e.g. inpaints, promos)
+    --as <name>                    Name the saved file (else derived from the URL)
+    --notes <text>                 Metadata notes (what it is / when to use it) — vector-embedded
+    --json                         Raw JSON response
+    e.g. vidfarm directory save-url "https://…/inpaint-out.png" --folder inpaints --as hero.png
+    (server fetches the URL — handles cross-origin S3; the CLI twin of the pop-panel "Save to Files")
+
   Aliases: directory | dir   ·   Auth: --api-key <key> or VIDFARM_API_KEY, --host <url>
   Move a raw between folders with: vidfarm api PATCH /raws/<clipId> --data '{"folder_path":"…"}'`;
 async function runDirectoryCommand(argv) {
@@ -3332,6 +4435,13 @@ async function runDirectoryCommand(argv) {
         case "search":
         case "find":
             return runDirectorySearch(rest);
+        case "rename":
+        case "mv":
+            return runDirectoryRename(rest);
+        case "save-url":
+        case "from-url":
+        case "import-url":
+            return runDirectorySaveUrl(rest);
         case undefined:
         case "help":
         case "--help":
@@ -3352,23 +4462,27 @@ async function runDirectoryLs(argv) {
     });
     const ctx = commonContext(parsed.values);
     const dirPath = parsed.positionals[0] ?? "/";
-    const result = await apiRequest({
-        method: "GET",
-        host: ctx.host,
-        path: "/api/v1/user/me/directory",
-        auth: ctx.auth,
-        query: {
-            path: dirPath,
-            limit: parsed.values.limit,
-            offset: parsed.values.offset
-        }
-    });
-    assertApiOk(result, "directory ls");
+    const spaces = targetSpaces(ctx.target);
+    const parts = [];
+    for (const space of spaces) {
+        const result = await dispatch(ctx, {
+            method: "GET",
+            path: "/api/v1/user/me/directory",
+            query: {
+                path: dirPath,
+                limit: parsed.values.limit,
+                offset: parsed.values.offset
+            }
+        }, space);
+        assertApiOk(result, `directory ls (${space})`);
+        parts.push({ space, data: result.json });
+    }
+    const merged = mergeListings(parts);
     if (ctx.json) {
-        printJson(result.json ?? result.text);
+        printJson(merged);
         return;
     }
-    printDirectoryListing(result.json, dirPath);
+    printDirectoryListing(merged, dirPath, spaces.length > 1 ? "both" : spaces[0]);
 }
 async function runDirectorySearch(argv) {
     const parsed = parseArgs({
@@ -3379,7 +4493,7 @@ async function runDirectorySearch(argv) {
     const ctx = commonContext(parsed.values);
     const query = parsed.positionals.join(" ").trim();
     if (!query) {
-        throw new Error('directory search requires a query: vidfarm directory search "<query>" [--path /raws] [--mode auto|semantic|substring|path] [--content-type talking_head,b_roll] [--limit N]');
+        throw new Error('directory search requires a query: vidfarm directory search "<query>" [--path /raws] [--mode auto|semantic|substring|path] [--content-type talking_head,b_roll] [--limit N] [--cloud|--both]');
     }
     const mode = parsed.values.mode;
     if (mode && !["auto", "semantic", "substring", "path"].includes(mode)) {
@@ -3387,25 +4501,152 @@ async function runDirectorySearch(argv) {
     }
     const contentTypes = parseContentTypeFlag(parsed.values["content-type"]);
     const limit = parsed.values.limit != null ? Number(parsed.values.limit) : undefined;
-    const result = await apiRequest({
+    const spaces = targetSpaces(ctx.target);
+    const body = {
+        query,
+        ...(parsed.values.path ? { path: String(parsed.values.path) } : {}),
+        ...(mode ? { mode } : {}),
+        ...(contentTypes.length ? { content_type: contentTypes } : {}),
+        ...(limit != null && Number.isFinite(limit) ? { limit } : {})
+    };
+    const parts = [];
+    for (const space of spaces) {
+        const result = await dispatch(ctx, { method: "POST", path: "/api/v1/user/me/directory/search", body }, space);
+        assertApiOk(result, `directory search (${space})`);
+        parts.push({ space, data: result.json });
+    }
+    const merged = mergeSearch(parts, limit);
+    if (ctx.json) {
+        printJson(merged);
+        return;
+    }
+    printDirectorySearch(merged, query, spaces.length > 1 ? "both" : spaces[0]);
+}
+async function runDirectoryRename(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), "file-id": { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const targetPath = parsed.positionals[0];
+    const newName = parsed.positionals.slice(1).join(" ").trim();
+    if (!targetPath || !newName) {
+        throw new Error('directory rename requires a path and a new name: vidfarm directory rename <path> <new-name> [--file-id <id>]');
+    }
+    const fileId = parsed.values["file-id"];
+    // Rename is a mutation — apply it in exactly one space (the first the target
+    // resolves to; local unless --cloud). "both" doesn't fan a rename out.
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, {
         method: "POST",
-        host: ctx.host,
-        path: "/api/v1/user/me/directory/search",
-        auth: ctx.auth,
+        path: "/api/v1/user/me/directory/rename",
         body: {
-            query,
-            ...(parsed.values.path ? { path: String(parsed.values.path) } : {}),
-            ...(mode ? { mode } : {}),
-            ...(contentTypes.length ? { content_type: contentTypes } : {}),
-            ...(limit != null && Number.isFinite(limit) ? { limit } : {})
+            path: targetPath,
+            new_name: newName,
+            ...(fileId ? { file_id: fileId } : {})
         }
+    }, space);
+    assertApiOk(result, "directory rename");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const newPath = result.json?.path ?? "";
+    console.log(`${GREEN}✓${RESET} Renamed to ${BOLD}${newName}${RESET} ${DIM}[${space}]${RESET}${newPath ? `  ${DIM}${newPath}${RESET}` : ""}`);
+}
+// Save a durable media URL (e.g. a finished job's output) INTO My Files at a
+// folder — the CLI twin of the pop-panel "Save to Files" picker. Server fetches
+// the URL (handles cross-origin S3), so no local download round-trip needed.
+async function runDirectorySaveUrl(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), folder: { type: "string" }, as: { type: "string" }, notes: { type: "string" } }
     });
-    assertApiOk(result, "directory search");
+    const ctx = commonContext(parsed.values);
+    const sourceUrl = parsed.positionals[0];
+    if (!sourceUrl) {
+        throw new Error('directory save-url requires a URL: vidfarm directory save-url <url> [--folder promos] [--as name.png] [--notes "…"]');
+    }
+    const body = {
+        source_url: sourceUrl,
+        ...(parsed.values.folder ? { folder_path: String(parsed.values.folder) } : {}),
+        ...(parsed.values.as ? { file_name: String(parsed.values.as) } : {}),
+        ...(parsed.values.notes ? { notes: String(parsed.values.notes) } : {})
+    };
+    // A mutation — apply in exactly one space (first the target resolves to).
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, { method: "POST", path: "/api/v1/user/me/attachments/from-url", body }, space);
+    assertApiOk(result, `directory save-url (${space})`);
     if (ctx.json) {
         printJson(result.json ?? result.text);
         return;
     }
-    printDirectorySearch(result.json, query);
+    const saved = result.json?.attachment;
+    emitResult(result, false, [[`My Files [${space}]`, saved?.viewUrl]]);
+}
+// ── Dual-target merge helpers ───────────────────────────────────────────────
+// Local is queried first, so on a same-path collision the local (working) copy
+// wins the de-dupe and the cloud duplicate is dropped.
+function mergeListings(parts) {
+    const multi = parts.length > 1;
+    const folders = [];
+    const files = [];
+    const seen = new Set();
+    for (const { space, data } of parts) {
+        for (const f of Array.isArray(data?.folders) ? data.folders : []) {
+            const key = "d:" + (f?.path ?? f?.name ?? "");
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            folders.push(multi ? { ...f, origin: space } : f);
+        }
+        for (const f of Array.isArray(data?.files) ? data.files : []) {
+            const key = "f:" + (f?.path ?? f?.id ?? f?.name ?? "");
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            files.push(multi ? { ...f, origin: space } : f);
+        }
+    }
+    if (multi)
+        folders.sort((a, b) => String(a?.name ?? "").localeCompare(String(b?.name ?? "")));
+    const base = parts[0]?.data ?? {};
+    return {
+        path: base.path,
+        root: base.root,
+        folders,
+        files,
+        // Merged listings can't page coherently across two backends; single-space
+        // keeps the backend's own paging cursor.
+        next_offset: multi ? null : base.next_offset ?? null
+    };
+}
+function mergeSearch(parts, limit) {
+    const multi = parts.length > 1;
+    const results = [];
+    const seen = new Set();
+    for (const { space, data } of parts) {
+        for (const r of Array.isArray(data?.results) ? data.results : []) {
+            const key = (r?.path ?? r?.name ?? "") + "|" + (r?.kind ?? "");
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            results.push(multi ? { ...r, origin: space } : r);
+        }
+    }
+    if (multi) {
+        results.sort((a, b) => (Number(b?.score) || 0) - (Number(a?.score) || 0));
+    }
+    const capped = multi && limit != null && Number.isFinite(limit) ? results.slice(0, limit) : results;
+    const base = parts[0]?.data ?? {};
+    return {
+        results: capped,
+        scope: base.scope,
+        mode: base.mode,
+        semantic: parts.some((p) => p?.data?.semantic === true)
+    };
 }
 // Compact "12.3s · 4.2 MB · video/mp4" line for a directory file item.
 function directoryFileMeta(item) {
@@ -3418,21 +4659,31 @@ function directoryFileMeta(item) {
         parts.push(item.contentType);
     return parts.join(" · ");
 }
-function printDirectoryListing(data, requestedPath) {
+// A dim `[local]`/`[cloud]` tag for an item that carries an origin (set only on
+// --both merges, so single-space listings stay clean).
+function originBadge(item) {
+    return item?.origin ? `${DIM}[${item.origin}]${RESET} ` : "";
+}
+function spaceHeaderLabel(space) {
+    if (!space)
+        return "";
+    return ` ${DIM}·${RESET} ${BOLD}${space}${RESET}`;
+}
+function printDirectoryListing(data, requestedPath, space) {
     const listedPath = data && typeof data.path === "string" ? data.path : requestedPath;
     const root = data?.root ? ` ${DIM}[${data.root}]${RESET}` : "";
-    console.log(`${BOLD}${listedPath}${RESET}${root}`);
+    console.log(`${BOLD}${listedPath}${RESET}${root}${spaceHeaderLabel(space)}`);
     const folders = Array.isArray(data?.folders) ? data.folders : [];
     const files = Array.isArray(data?.files) ? data.files : [];
     if (folders.length === 0 && files.length === 0) {
         console.log(`  ${DIM}(empty)${RESET}`);
     }
     for (const f of folders) {
-        console.log(`  ${DIM}dir ${RESET}  ${f?.name ?? ""}/    ${DIM}${f?.path ?? ""}${RESET}`);
+        console.log(`  ${DIM}dir ${RESET}  ${originBadge(f)}${f?.name ?? ""}/    ${DIM}${f?.path ?? ""}${RESET}`);
     }
     for (const f of files) {
         const meta = directoryFileMeta(f);
-        console.log(`  file  ${f?.name ?? ""}${meta ? `    ${DIM}${meta}${RESET}` : ""}    ${DIM}${f?.path ?? ""}${RESET}`);
+        console.log(`  file  ${originBadge(f)}${f?.name ?? ""}${meta ? `    ${DIM}${meta}${RESET}` : ""}    ${DIM}${f?.path ?? ""}${RESET}`);
         if (f?.viewUrl)
             console.log(`        ${FRONTEND}${f.viewUrl}${RESET}`);
     }
@@ -3440,12 +4691,12 @@ function printDirectoryListing(data, requestedPath) {
     const more = data?.next_offset != null ? `  (more: --offset ${data.next_offset})` : "";
     console.log(`\n  ${total} item${total === 1 ? "" : "s"} (${folders.length} folder${folders.length === 1 ? "" : "s"}, ${files.length} file${files.length === 1 ? "" : "s"})${more}`);
 }
-function printDirectorySearch(data, query) {
+function printDirectorySearch(data, query, space) {
     const results = Array.isArray(data?.results) ? data.results : [];
     const scope = data?.scope ? ` in ${data.scope}` : "";
     const modeLabel = data?.mode ? ` · mode=${data.mode}` : "";
     const semantic = data?.semantic === true ? " · semantic" : data?.semantic === false ? " · keyword-only" : "";
-    console.log(`${BOLD}"${query}"${RESET}${scope}${modeLabel}${semantic}  →  ${results.length} result${results.length === 1 ? "" : "s"}\n`);
+    console.log(`${BOLD}"${query}"${RESET}${scope}${modeLabel}${semantic}${spaceHeaderLabel(space)}  →  ${results.length} result${results.length === 1 ? "" : "s"}\n`);
     if (results.length === 0) {
         console.log(`  ${DIM}(no matches)${RESET}`);
         return;
@@ -3453,7 +4704,7 @@ function printDirectorySearch(data, query) {
     results.forEach((r, i) => {
         const score = typeof r?.score === "number" ? ` ${DIM}score=${r.score.toFixed(3)}${RESET}` : "";
         const kind = r?.kind === "folder" ? "dir " : "file";
-        console.log(`  ${String(i + 1).padStart(2)}. ${kind}  ${r?.path ?? r?.name ?? ""}${score}`);
+        console.log(`  ${String(i + 1).padStart(2)}. ${kind}  ${originBadge(r)}${r?.path ?? r?.name ?? ""}${score}`);
         const meta = directoryFileMeta(r);
         if (meta)
             console.log(`      ${DIM}${meta}${RESET}`);
@@ -3575,28 +4826,37 @@ async function runPutFileCommand(argv) {
     if (!fileName)
         throw new Error("put-file could not determine a file name. Pass --as <name>.");
     const contentType = guessContentType(fileName);
-    const form = new FormData();
-    form.append("file", new Blob([new Uint8Array(buffer)], contentType ? { type: contentType } : undefined), fileName);
-    if (parsed.values.folder)
-        form.append("folder_path", String(parsed.values.folder));
-    if (parsed.values.notes)
-        form.append("notes", String(parsed.values.notes));
-    const res = await fetch(new URL("/api/v1/user/me/attachments/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;
+    const uploadPath = "/api/v1/user/me/attachments/upload";
+    for (const space of targetSpaces(ctx.target)) {
+        // FormData is single-use (its stream is consumed), so build a fresh one per
+        // space when writing to both.
+        const form = new FormData();
+        form.append("file", new Blob([new Uint8Array(buffer)], contentType ? { type: contentType } : undefined), fileName);
+        if (parsed.values.folder)
+            form.append("folder_path", String(parsed.values.folder));
+        if (parsed.values.notes)
+            form.append("notes", String(parsed.values.notes));
+        let res;
+        if (space === "local") {
+            const { withLocalBackend } = await import("./devcli/local-backend.js");
+            const backend = await withLocalBackend({ home: ctx.home, apiKey: ctx.auth.apiKey });
+            res = await backend.app.request(uploadPath, { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
+        }
+        else {
+            res = await fetch(new URL(uploadPath, 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;
+        }
+        const result = { status: res.status, ok: res.ok, json, text };
+        assertApiOk(result, `put-file (${space})`);
+        emitResult(result, ctx.json, [[`My Files [${space}]`, result.json?.attachment?.viewUrl]]);
     }
-    const result = { status: res.status, ok: res.ok, json, text };
-    assertApiOk(result, "put-file");
-    emitResult(result, ctx.json, [["My Files URL", result.json?.attachment?.viewUrl]]);
 }
 // ── Local media engines + toolchain ─────────────────────────────────────────
 // Wrappers over the bundled hyperframes LOCAL commands (free, no account, no