@mevdragon/vidfarm-devcli 0.4.1 → 0.5.1

package/dist/src/cli.js

@@ -7,10 +7,12 @@ import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-// vidfarm-devcli — thin CLI that pairs a local composition directory with the
-// hosted Trackpad Editor at https://vidfarm.cc/editor/. Point it at a template
-// id, and it: resolves the user's fork, downloads the current composition,
-// starts a local dev-serve, and prints the editor URL to open in the browser.
+import { computeCompositionGaps, insertMediaLayer, inspectComposition, replaceLayerWithMedia } from "./services/composition-edit.js";
+// vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
+// `serve` command boots the FULL editor locally (single origin, disk-backed
+// records + storage) so power users edit compositions on disk while a browser
+// editor and a coding agent share one source of truth; render stays on the
+// cloud. The remaining commands are thin 1:1 wrappers over the REST API.
 const DEFAULT_HOST = "https://vidfarm.cc";
 const DEFAULT_PORT = 4321;
 // Agent skill files the `update-skill` command can install from the live host
@@ -38,23 +40,77 @@ Usage:
   vidfarm --help
 
 Local editor loop:
-  <template_id> [opts]      Fetch composition + media, dev-serve, print editor URL
+  serve [template_id] [opts]  Boot the FULL editor locally (single origin, disk-backed).
+                              Records + storage run on disk; render runs in-process on
+                              this box for FREE (no cloud, no wallet charge).
+                              With a template_id or --fork, pulls that composition
+                              (or the template's default/shared decomposition) from
+                              the cloud host onto local disk to edit offline.
+    --port <n>                Server port (default: 3000)
+    --dir <path>              Local data dir (default: ./.vidfarm-local)
+    --key <api-key>           Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
+    --fork <id>               Pull + open a specific cloud fork
+    --host <url>              Cloud host to pull from (default: ${DEFAULT_HOST})
+    --api-key <key>           Cloud key for the pull (default: VIDFARM_API_KEY)
+    --refetch                 Overwrite local composition with the cloud copy
+    --no-open                 Don't auto-open the browser
+  <template_id> [opts]      Alias for 'serve <template_id>' (boot the local editor)
   publish [template_id]     Push local composition.html/json to your fork  → PUT/PATCH composition + POST versions
-  dev-serve                 Serve an existing local dir only (no fetch)
 
 Discover & inspiration (browse the viral-video catalog, add your own source):
-  discover                  List the template/inspiration feed          → GET  /discover/feed
+  discover [query...]       List/search TEMPLATES (best for an offer)    → GET  /discover/feed
+    --query <text>          Keyword search (e.g. "weight loss app")
+    --limit <n>             Max results
+  videos [query...]         List/search source INSPIRATIONS              → GET  /api/v1/videos
+    --query <text>          Keyword search over the catalog
+    --mine                  Only your own uploaded inspirations
+    --limit <n>             Max results
   inspiration-add <url>     Ingest a TikTok/YT/IG/X video as a template  → POST /discover/templates
   inspiration-rm <id>       Delete a private inspiration/template you own → DELETE /discover/templates/:id
   inspiration-decompose <id>  AI-decompose an inspiration into scenes     → POST /api/v1/inspirations/:id/decompose
 
 Composition lifecycle (fork → decompose → snapshot → render):
   fork <template_id>        Fork a template into an editable composition → POST /api/v1/compositions
+  pull <forkId>             Sync composition.html/json + video-context   → GET  .../compositions/:forkId/{composition.html,...}
+                            + cast.json to disk, then print timeline gaps
+                            (blank space) and scene/layer keys to target.
+    --dir <path>            Local dir (default: .vidfarm/<forkId>)
+    --refetch               Overwrite local copies with the cloud version
   decompose <forkId>        Split the fork's source into scenes (smart)  → POST .../compositions/:forkId/auto-decompose
-  ghostcut <forkId>         Read subtitle-removal status (non-billing)   → GET  .../compositions/:forkId/ghostcut
+
+Generate AI media and drop it on the timeline (for local coding agents):
+  generate <image|video>    Generate AI media, poll to the finished URL  → POST /api/v1/primitives/{images,videos}/generate
+    --prompt <text>         What to generate (required)
+    --ref <url|@file>       Reference image (repeatable): input_references
+                            for video, prompt_attachments for image. @file
+                            auto-uploads a local image and uses its URL.
+    --aspect-ratio <r>      e.g. 9:16 (match the composition canvas)
+    --duration <n>          Video only: seconds of footage (e.g. 4)
+    --resolution <r>        Video only: 480p|720p|1080p|1K|2K|4K
+    --audio                 Video only: generate an audio track
+    --provider <p>          openai|gemini|openrouter (omit to auto-pick)
+    --model <m>             Model override (omit for provider defaults)
+    --no-wait               Return the job id instead of polling to the URL
+    --place <dir>           After generating, place it into that composition
+    --at <time> | --replace <layer_key>   Placement (fill gap vs replace scene)
+  place <dir|composition.html>   Insert a media URL into a local composition
+                            (fill a gap or replace a scene) — same clip markup
+                            the browser editor makes; serve live-morphs it.
+    --src <url>             Direct media URL to place (required)
+    --kind <video|image>    Media kind (inferred from the URL if omitted)
+    --at <time>             Start it at this time (seconds / mm:ss) — fill a gap
+    --replace <layer_key>   Replace this scene/layer (copies its timing+geometry)
+    --duration <n>          Timeline length in seconds
+    --track <n>             Timeline layer index (auto if omitted)
+    --x --y --width --height   Geometry as % (default full canvas 0/0/100/100)
+    --object-fit <fit>      cover|contain|fill|none|scale-down (default cover)
+  ghostcut <forkId>         Read the two video sources: original vs      → GET  .../compositions/:forkId/ghostcut
+                            decomposed (caption-free), non-billing
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
-  render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/export
+  render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/render
+                            Cloud render costs ~$0.01-$0.10; against a local
+                            '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
@@ -82,8 +138,30 @@ Agent skill (install the latest director skill so your AI agent can act):
     --print                 Print the skill to stdout instead of writing a file
 
 Files (multi-step flows the devcli handles for you):
-  upload <file>             Upload a local file, print its durable URL   → POST /api/v1/user/me/temporary-files/upload
+  upload <file>             Upload to the EPHEMERAL temp store, print URL → POST /api/v1/user/me/temporary-files/upload
+    --folder <path>         Namescope the upload under a product/offer folder
+  put-file [file]           Write a file INTO My Files (persistent lib)  → POST /api/v1/user/me/attachments/upload
+    --folder <path>         Namescope under a product/offer folder (e.g. acme-skincare)
+    --as <name>             Name the saved file (required for --content/--stdin)
+    --content <text>        Inline text to save (needs --as); or pipe stdin with --stdin
+                            e.g. vidfarm put-file About.md --folder acme-skincare
+                                 echo "..." | vidfarm put-file --stdin --as About.md --folder acme
   download <url> [dest]     Stream any Vidfarm/media URL to disk
+  files                     List My Files assets + folders               → GET /api/v1/user/me/attachments
+    --folder <path>         Only files under this folder (e.g. a product/offer)
+  get-file <id> [dest]      Resolve a My Files id to its URL and download it
+    --print                 Print text contents (md/txt/csv/json) instead of saving
+  put-file / get-file / files are the My Files (persistent) read+write set;
+  upload is the throwaway temp store for dropping media into a composition.
+
+Cost spectrum (default to the cheapest approach that works; see SKILL.director.md):
+  free        Reuse a decomposed template, swap captions/images/existing MP4s
+              (My Files / your computer / web search), render on a local 'serve' box.
+  ~$0.001-$0.03   Same reuse, but cloud 'render' (~$0.01-$0.10). Image gen is cheap too.
+  ~$1        AI-generate a few scenes for specificity (generate video ...).
+  $10+       Heavy AI generation (many/long AI clips, custom characters).
+  Notes: image gen is cheap (use freely); AI VIDEO gen is expensive (ask the user
+  first). Decompose is a one-time ~$0.10 — or skip it by forking a decomposed template.
 
 Escape hatch — call ANY route directly:
   api <METHOD> <path>       Raw REST call with auth + pretty errors
@@ -99,11 +177,12 @@ Common options (any command):
   --share <token>     Share token for a shared fork (public read)
   --json              Print only the raw JSON response (agent-friendly)
 
-Editor-mode options:
-  --port <n>          Local dev-serve port (default: ${DEFAULT_PORT})
-  --dir <path>        Local composition directory (default: .vidfarm/<template_id>)
-  --fork <id>         Fork id (default: auto-resolve for the current user)
-  --refetch           Overwrite local composition files with the latest remote copy
+Serve-mode options:
+  --port <n>          Local server port (default: 3000)
+  --dir <path>        Local data dir for disk records + storage (default: ./.vidfarm-local)
+  --key <api-key>     Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
+  --fork <id>         Open a specific fork (multiple forks editable at once)
+  --no-open           Don't auto-open the browser
 
 Publish-mode options:
   --message <text>    Message attached to the published version snapshot
@@ -122,13 +201,11 @@ async function main() {
     const command = argv[0];
     const rest = argv.slice(1);
     switch (command) {
-        case "dev-serve": {
-            const { runDevServeCommand } = await import("./dev-serve.js");
-            await runDevServeCommand(rest);
-            return;
-        }
+        // `serve` (and the bare `<template_id>` / legacy `edit` alias) boot the full
+        // editor locally. The old cross-origin dev-serve/`?dev=` flow is gone.
+        case "serve":
         case "edit":
-            await runEditCommand(rest);
+            await runServeCommand(rest);
             return;
         case "publish":
             await runPublishCommand(rest);
@@ -140,6 +217,9 @@ async function main() {
         case "discover":
             await runDiscoverCommand(rest);
             return;
+        case "videos":
+            await runVideosCommand(rest);
+            return;
         case "inspiration-add":
             await runInspirationAddCommand(rest);
             return;
@@ -152,6 +232,15 @@ async function main() {
         case "fork":
             await runForkCommand(rest);
             return;
+        case "pull":
+            await runPullCommand(rest);
+            return;
+        case "generate":
+            await runGenerateCommand(rest);
+            return;
+        case "place":
+            await runPlaceCommand(rest);
+            return;
         case "decompose":
             await runDecomposeCommand(rest);
             return;
@@ -219,10 +308,20 @@ async function main() {
         case "download":
             await runDownloadCommand(rest);
             return;
+        case "files":
+            await runFilesCommand(rest);
+            return;
+        case "get-file":
+            await runGetFileCommand(rest);
+            return;
+        case "put-file":
+        case "save-file":
+            await runPutFileCommand(rest);
+            return;
         default:
             if (!command.startsWith("-")) {
-                // Positional template id → default `edit` command.
-                await runEditCommand(argv);
+                // Positional template id → default to booting the local editor.
+                await runServeCommand(argv);
                 return;
             }
             throw new Error(`Unknown option before command: ${command}\n\n${HELP}`);
@@ -337,61 +436,205 @@ function collectKeyValues(entries) {
     }
     return out;
 }
-async function runEditCommand(argv) {
+// `vidfarm serve` — boot the FULL Vidfarm backend locally (single origin), on
+// disk-backed records + storage, so power users edit compositions locally while
+// a browser editor and a coding agent share one source of truth. Render stays
+// on the cloud (see Phase 4). This replaces the cross-origin `?dev=` shim.
+async function runServeCommand(argv) {
     const parsed = parseArgs({
         args: argv,
         allowPositionals: true,
         options: {
-            port: { type: "string", default: String(DEFAULT_PORT) },
+            port: { type: "string", default: "3000" },
             dir: { type: "string" },
-            host: { type: "string", default: DEFAULT_HOST },
+            key: { type: "string" },
             fork: { type: "string" },
+            host: { type: "string", default: DEFAULT_HOST },
             "api-key": { type: "string" },
             share: { type: "string" },
-            refetch: { type: "boolean", default: false }
+            refetch: { type: "boolean", default: false },
+            open: { type: "boolean", default: true },
+            "no-open": { type: "boolean", default: false }
         }
     });
-    const templateId = parsed.positionals[0];
-    if (!templateId) {
-        throw new Error(`edit requires a template id.\n\n${HELP}`);
-    }
     const port = Number(parsed.values.port);
     if (!Number.isFinite(port) || port <= 0) {
         throw new Error(`Invalid --port: ${parsed.values.port}`);
     }
+    const dataDir = path.resolve(process.cwd(), parsed.values.dir ?? ".vidfarm-local");
+    mkdirSync(dataDir, { recursive: true });
+    // Capture the ambient cloud key BEFORE we overwrite VIDFARM_API_KEY with the
+    // local bootstrap key, so `--fork`/template seeding can still authenticate to
+    // the cloud host.
+    const envKey = process.env.VIDFARM_API_KEY;
+    // A stable local bootstrap key: first --key, else VIDFARM_API_KEY, else a
+    // fixed dev key. The same value auto-provisions the paid customer (via
+    // tryBootstrapFromEnv) and pre-auths the browser through /auto-login.
+    const apiKey = parsed.values.key ?? envKey ?? "vidfarm-local-dev-key";
+    const cloudApiKey = parsed.values["api-key"] ?? envKey;
     const host = trimTrailingSlash(parsed.values.host);
-    const apiKey = parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY;
-    const shareToken = parsed.values.share;
-    const rootDir = path.resolve(process.cwd(), parsed.values.dir ?? path.join(".vidfarm", templateId));
-    mkdirSync(rootDir, { recursive: true });
-    const forkId = parsed.values.fork ?? await resolveForkId({ host, templateId, apiKey, shareToken });
-    if (!forkId) {
-        throw new Error(`Could not resolve a fork id for template ${templateId}. Pass --fork <id>, or open ${host}/editor/${templateId} once so a fork is created.`);
-    }
-    await fetchCompositionFiles({
-        host,
-        forkId,
-        dir: rootDir,
-        apiKey,
-        shareToken,
-        refetch: parsed.values.refetch
-    });
-    // Give local coding agents (Claude Code / Codex / opencode) the actual media
-    // to look at: the original source video, the composition's decomposed source
-    // (which may differ after ghostcut subtitle-removal), one still frame per
-    // scene, and a sources.json manifest tying it all together. Best-effort —
-    // never blocks the editor session if a download or frame extraction fails.
+    const templateId = parsed.positionals[0];
+    const forkFlag = parsed.values.fork;
+    // Env MUST be set before importing runtime — config.ts reads it at module
+    // load. Force the fully-local drivers; keep any cloud creds already present
+    // in the environment so render passthrough still works.
+    process.env.RECORDS_DRIVER = "local";
+    process.env.STORAGE_DRIVER = "local";
+    process.env.AWS_S3_BUCKET = "";
+    process.env.VIDFARM_DATA_DIR = dataDir;
+    process.env.VIDFARM_API_KEY = apiKey;
+    process.env.PORT = String(port);
+    if (!process.env.NODE_ENV)
+        process.env.NODE_ENV = "development";
+    const { startRuntime } = await import("./runtime.js");
+    await startRuntime();
+    // If a template/fork was requested, pull its composition from the cloud host
+    // onto local disk and materialize the matching local records so the editor
+    // resolves it. Best-effort: a failure just drops us to /discover.
+    let openTemplateId = templateId;
+    let openForkId = forkFlag;
+    if (templateId || forkFlag) {
+        try {
+            const seeded = await seedForkFromCloud({
+                host,
+                templateId,
+                forkId: forkFlag,
+                cloudApiKey,
+                shareToken: parsed.values.share,
+                bootstrapKey: apiKey,
+                refetch: parsed.values.refetch
+            });
+            if (seeded) {
+                openTemplateId = seeded.templateId;
+                openForkId = seeded.forkId;
+            }
+        }
+        catch (error) {
+            console.warn(`[vidfarm] serve: cloud seed failed (${error instanceof Error ? error.message : String(error)}); starting empty.`);
+        }
+    }
+    const base = `http://localhost:${port}`;
+    const editorPath = openTemplateId
+        ? `/editor/${encodeURIComponent(openTemplateId)}${openForkId ? `?fork=${encodeURIComponent(openForkId)}` : ""}`
+        : "/discover";
+    const openUrl = `${base}/auto-login?api_key=${encodeURIComponent(apiKey)}&redirect=${encodeURIComponent(editorPath)}`;
+    printServeBanner({ base, dataDir, openUrl, editorPath });
+    const shouldOpen = parsed.values.open && !parsed.values["no-open"];
+    if (shouldOpen)
+        openInBrowser(openUrl);
+    // startRuntime() keeps the process alive via its HTTP server; nothing else to do.
+}
+// Pull a cloud fork's composition onto local disk and create the local
+// template + fork records so the editor resolves it. The fork is either an
+// explicit --fork or the template's default fork (which may be another user's
+// public decomposition). Media stays on cloud URLs — only the composition +
+// records are localized. Runs in-process after startRuntime(), so it shares the
+// server's disk-backed records/storage singletons.
+async function seedForkFromCloud(input) {
+    const { serverlessRecords } = await import("./services/serverless-records.js");
+    const { StorageService } = await import("./services/storage.js");
+    const { ServerlessAuthService } = await import("./services/serverless-auth.js");
+    const storage = new StorageService();
+    const auth = new ServerlessAuthService();
+    // Ensure the local bootstrap customer exists and grab its id to own the seed.
+    const customer = await auth.authenticate(input.bootstrapKey);
+    const authHeaders = buildAuthHeaders({ apiKey: input.cloudApiKey, shareToken: input.shareToken });
+    // 1. Resolve the source fork: explicit --fork wins, else the template's
+    //    default fork (grabs the shared decomposition even if another user owns it).
+    let cloudForkId = input.forkId ?? null;
+    if (!cloudForkId && input.templateId) {
+        cloudForkId = await resolveForkId({ host: input.host, templateId: input.templateId, apiKey: input.cloudApiKey, shareToken: input.shareToken });
+    }
+    if (!cloudForkId) {
+        console.warn("[vidfarm] serve: no --fork and no default fork resolvable from cloud; starting empty.");
+        return null;
+    }
+    // 2. Read the serialized fork for its template id + title.
+    const forkMetaRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}`, { headers: authHeaders });
+    const forkMeta = forkMetaRes.ok ? (await forkMetaRes.json().catch(() => null)) : null;
+    const templateId = input.templateId ?? (typeof forkMeta?.template_id === "string" ? forkMeta.template_id : null);
+    if (!templateId || !templateId.startsWith("template_")) {
+        console.warn(`[vidfarm] serve: could not determine a template id for fork ${cloudForkId}; starting empty.`);
+        return null;
+    }
+    const title = (typeof forkMeta?.title === "string" && forkMeta.title) || `Local · ${templateId}`;
+    // 3. Materialize the local template record (the editor 404s without it).
+    const existingTemplate = await serverlessRecords.getTemplate(templateId);
+    if (!existingTemplate) {
+        await serverlessRecords.createTemplate({
+            id: templateId,
+            inspirationId: `local:${templateId}`,
+            customerId: customer.id,
+            originalUrl: typeof forkMeta?.original_url === "string" ? forkMeta.original_url : "",
+            sourceHost: "local",
+            title,
+            visibility: "public"
+        });
+    }
+    // 4. Materialize the local fork (reuse the cloud id for stable URLs).
+    const localForkId = cloudForkId;
+    const existingFork = await serverlessRecords.getCompositionFork(localForkId);
+    if (!existingFork) {
+        await serverlessRecords.createCompositionFork({
+            id: localForkId,
+            customerId: customer.id,
+            templateId,
+            title,
+            visibility: "private"
+        });
+    }
+    // 5. Pull composition.html/json onto disk (skip if present unless --refetch,
+    //    so local edits aren't clobbered on re-serve).
+    const htmlKey = storage.compositionForkWorkingKey(localForkId, "composition.html");
+    const jsonKey = storage.compositionForkWorkingKey(localForkId, "composition.json");
+    const hasLocalHtml = Boolean(await storage.readText(htmlKey));
+    if (!hasLocalHtml || input.refetch) {
+        const htmlRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}/composition.html`, { headers: authHeaders });
+        if (!htmlRes.ok) {
+            console.warn(`[vidfarm] serve: could not fetch composition.html for ${cloudForkId} (${htmlRes.status}); starting empty.`);
+            return null;
+        }
+        await storage.putText(htmlKey, await htmlRes.text(), "text/html; charset=utf-8");
+        const jsonRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}/composition.json`, { headers: authHeaders });
+        if (jsonRes.ok)
+            await storage.putBuffer(jsonKey, Buffer.from(await jsonRes.text(), "utf8"), "application/json");
+        console.log(`[vidfarm] seeded fork ${localForkId} from ${input.host}`);
+    }
+    else {
+        console.log(`[vidfarm] fork ${localForkId} already local (use --refetch to overwrite)`);
+    }
+    // 6. Point the template's default fork at the local copy so a bare
+    //    /editor/:templateId resolves it too.
+    await serverlessRecords.stampDefaultForkIfUnset({ templateId, forkId: localForkId });
+    return { templateId, forkId: localForkId };
+}
+function printServeBanner(input) {
+    const line = `${DIM}${"─".repeat(74)}${RESET}`;
+    console.log("");
+    console.log(line);
+    console.log(`${BOLD}${GREEN}  Vidfarm local server${RESET}  ${DIM}(fully local — records + storage on disk)${RESET}`);
+    console.log(line);
+    console.log(`  server      ${input.base}`);
+    console.log(`  data dir    ${input.dataDir}`);
+    console.log(`  render      ${DIM}cloud (submitted to the deployed renderer)${RESET}`);
+    console.log("");
+    console.log(`  ${DIM}Agents: edit composition files under ${input.dataDir}/storage — the`);
+    console.log(`  browser live-reloads on save. Multiple forks can be edited at once.${RESET}`);
+    console.log("");
+    console.log(`  ${BOLD}Open (pre-authed):${RESET}`);
+    console.log(`  ${FRONTEND}${input.openUrl}${RESET}`);
+    console.log(line);
+    console.log("");
+}
+function openInBrowser(url) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
     try {
-        await fetchVideoAssets({ dir: rootDir, apiKey, shareToken, refetch: parsed.values.refetch });
+        spawnSync(opener, args, { stdio: "ignore" });
     }
-    catch (error) {
-        console.warn(`[vidfarm] video assets skipped: ${error instanceof Error ? error.message : String(error)}`);
+    catch {
+        // Non-fatal: the banner already printed the URL to open manually.
     }
-    const devSource = `http://localhost:${port}`;
-    const editorUrl = `${host}/editor/${encodeURIComponent(templateId)}?fork=${encodeURIComponent(forkId)}&dev=${encodeURIComponent(devSource)}`;
-    printEditorBanner({ templateId, forkId, dir: rootDir, port, editorUrl });
-    const { runDevServeCommand } = await import("./dev-serve.js");
-    await runDevServeCommand(["--dir", rootDir, "--port", String(port)]);
 }
 async function runPublishCommand(argv) {
     const parsed = parseArgs({
@@ -564,7 +807,9 @@ async function fetchCompositionFiles(input) {
     // video-context.json carries the source video's audio transcript and
     // per-scene visual descriptions so desktop agents (Claude Code, Codex)
     // can ground edits in what the video actually says and shows.
-    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json"];
+    // cast.json carries the identified recurring people/characters plus their
+    // reference-still URLs so agents can reuse "the same person" in new gens.
+    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json"];
     for (const filename of files) {
         const target = path.join(input.dir, filename);
         if (existsSync(target) && !input.refetch) {
@@ -588,10 +833,10 @@ async function fetchVideoAssets(input) {
         console.log("[vidfarm] no source video URL found in composition — skipping video assets");
         return;
     }
-    // "decomposed video in composition" = the source the composition currently
-    // renders from (post-ghostcut if applicable). "original" = the raw source the
-    // decompose ran against, before any processing. They coincide when the fork
-    // was never ghostcut/subtitle-removed.
+    // "decomposed video" = the source the composition currently renders from
+    // (caption-free after subtitle removal, if applicable). "original video" =
+    // the raw source the decompose ran against, before any processing. They
+    // coincide when the fork was never subtitle-removed.
     const compositionUrl = refs.compositionSourceUrl ?? refs.originalSourceUrl;
     const originalUrl = refs.originalSourceUrl ?? refs.compositionSourceUrl;
     const sameSource = compositionUrl === originalUrl;
@@ -630,19 +875,20 @@ async function fetchVideoAssets(input) {
         : new Map();
     const manifest = {
         generated_by: "vidfarm-devcli",
-        note: "Local media references for coding agents. `original.mp4` is the raw source video; " +
-            "`source.mp4` is the video the composition timeline renders from (may differ from the " +
-            "original after ghostcut subtitle-removal). Scene entries map timeline segments to a still " +
-            "frame you can open as an image. Run `--refetch` to refresh.",
+        note: "Local media references for coding agents. Two video sources: `original.mp4` is the " +
+            "ORIGINAL video (raw source, captions intact); `source.mp4` is the DECOMPOSED video, the " +
+            "processed caption-free copy the composition timeline renders from (differs from the original " +
+            "only when the fork was decomposed with subtitle removal). Scene entries map timeline segments " +
+            "to a still frame you can open as an image. Run `--refetch` to refresh.",
         videos: {
             decomposed: {
-                role: "video the composition timeline renders from (decomposed source)",
+                role: "decomposed video: processed caption-free source the composition timeline renders from",
                 url: compositionUrl,
                 path: decomposed ? decomposedName : null,
                 bytes: decomposed?.bytes ?? null
             },
             original: {
-                role: "raw original source video (before any processing)",
+                role: "original video: raw source before any processing",
                 url: originalUrl,
                 path: original ? original.path : null,
                 bytes: original?.bytes ?? null,
@@ -801,6 +1047,39 @@ function safeSize(target) {
         return 0;
     }
 }
+// Guess a content type from a file name so My Files stores text docs as text/*
+// (a bare multipart Blob otherwise defaults to application/octet-stream, which
+// makes browsers download .md/.txt instead of showing them). Mirrors the common
+// cases of the server's inferAttachmentContentType; returns "" when unknown so
+// the server can fall back to its own inference.
+function guessContentType(fileName) {
+    const dot = fileName.lastIndexOf(".");
+    const ext = dot >= 0 ? fileName.slice(dot).toLowerCase() : "";
+    switch (ext) {
+        case ".md": return "text/markdown; charset=utf-8";
+        case ".txt": return "text/plain; charset=utf-8";
+        case ".csv": return "text/csv; charset=utf-8";
+        case ".json": return "application/json";
+        case ".srt":
+        case ".vtt": return "text/plain; charset=utf-8";
+        case ".png": return "image/png";
+        case ".jpg":
+        case ".jpeg": return "image/jpeg";
+        case ".gif": return "image/gif";
+        case ".webp": return "image/webp";
+        case ".svg": return "image/svg+xml";
+        case ".mp4":
+        case ".m4v": return "video/mp4";
+        case ".mov": return "video/quicktime";
+        case ".webm": return "video/webm";
+        case ".mp3": return "audio/mpeg";
+        case ".wav": return "audio/wav";
+        case ".m4a": return "audio/mp4";
+        case ".aac": return "audio/aac";
+        case ".pdf": return "application/pdf";
+        default: return "";
+    }
+}
 function formatBytes(bytes) {
     if (bytes >= 1024 * 1024)
         return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
@@ -818,29 +1097,6 @@ function buildAuthHeaders(input) {
         headers["vidfarm-share-token"] = input.shareToken;
     return headers;
 }
-function printEditorBanner(input) {
-    const bold = "\x1b[1m";
-    const green = "\x1b[32m";
-    const cyan = "\x1b[36m";
-    const dim = "\x1b[2m";
-    const reset = "\x1b[0m";
-    const line = `${dim}${"─".repeat(74)}${reset}`;
-    console.log("");
-    console.log(line);
-    console.log(`${bold}${green}  Vidfarm local editor${reset}`);
-    console.log(line);
-    console.log(`  template    ${input.templateId}`);
-    console.log(`  fork        ${input.forkId}`);
-    console.log(`  local dir   ${input.dir}`);
-    console.log(`  dev-serve   http://localhost:${input.port}`);
-    console.log("");
-    console.log(`  ${dim}Agent media: original.mp4, source.mp4, frames/*.png, sources.json${reset}`);
-    console.log("");
-    console.log(`  ${bold}Open in browser:${reset}`);
-    console.log(`  ${cyan}${input.editorUrl}${reset}`);
-    console.log(line);
-    console.log("");
-}
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, "");
 }
@@ -884,13 +1140,33 @@ async function runApiCommand(argv) {
         process.exitCode = 1;
 }
 // ── Discover & inspiration ──────────────────────────────────────────────────
+// `discover` lists TEMPLATES; `--query` keyword-searches the catalog so an agent
+// CLI (Claude Code / Codex) can answer "which templates suit my <offer>?". Each
+// result carries decompose-derived promotions/keywords/summary to reason over.
 async function runDiscoverCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: false, options: { ...commonOptions(), limit: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), limit: { type: "string" }, query: { type: "string" } } });
     const ctx = commonContext(parsed.values);
-    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/discover/feed", auth: ctx.auth, query: { limit: parsed.values.limit } });
+    const query = (parsed.values.query ?? parsed.positionals.join(" ").trim()) || undefined;
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/discover/feed", auth: ctx.auth, query: { limit: parsed.values.limit, q: query } });
     assertApiOk(result, "discover");
     emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
 }
+// `videos` lists source INSPIRATIONS (the raw viral videos), with the same
+// keyword search and an optional --mine for the caller's own uploads.
+async function runVideosCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), limit: { type: "string" }, query: { type: "string" }, mine: { type: "boolean", default: false } } });
+    const ctx = commonContext(parsed.values);
+    const query = (parsed.values.query ?? parsed.positionals.join(" ").trim()) || undefined;
+    const result = await apiRequest({
+        method: "GET",
+        host: ctx.host,
+        path: "/api/v1/videos",
+        auth: ctx.auth,
+        query: { limit: parsed.values.limit, q: query, mine: parsed.values.mine ? "true" : undefined }
+    });
+    assertApiOk(result, "videos");
+    emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
+}
 async function runInspirationAddCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), tagline: { type: "string" }, notes: { type: "string" } } });
     const sourceUrl = parsed.positionals[0];
@@ -931,6 +1207,12 @@ async function runInspirationDecomposeCommand(argv) {
         body: { user_prompt: parsed.values.prompt ?? null }
     });
     assertApiOk(result, "inspiration-decompose");
+    if (!ctx.json && result.json?.default_fork_id) {
+        const forkId = result.json.default_fork_id;
+        console.log(result.json.became_default_fork
+            ? `${DIM}This decompose set the template default fork (${forkId}) — everyone now forks off it.${RESET}`
+            : `${DIM}Template already has a default fork (${forkId}); left it unchanged.${RESET}`);
+    }
     emitResult(result, ctx.json);
 }
 // ── Composition lifecycle ───────────────────────────────────────────────────
@@ -1014,7 +1296,7 @@ async function runRenderCommand(argv) {
     const result = await apiRequest({
         method: "POST",
         host: ctx.host,
-        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/export`,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/render`,
         auth: ctx.auth,
         body: { title: parsed.values.title, tracer: parsed.values.tracer }
     });
@@ -1058,6 +1340,351 @@ async function runRenderStatusCommand(argv) {
     assertApiOk(result, "render-status");
     emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.outputUrl]]);
 }
+// ── AI generation + timeline placement (for local coding agents) ────────────
+// `generate` submits an AI image/video primitive job and (by default) polls it
+// to the finished media URL — the async poll the raw `api` command can't do for
+// you. `place` drops any media URL into a local composition.html (fill a gap or
+// replace a scene), producing the SAME clip markup the browser editor makes, so
+// `serve` live-morphs it and `publish` pushes it. Together they let a Claude
+// Code / Codex agent do end-to-end "generate → insert" without hand-editing HTML.
+// Parse "5", "5.5", "mm:ss", or "hh:mm:ss" into seconds.
+function parseTimeToSeconds(raw) {
+    const trimmed = raw.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed))
+        return Number(trimmed);
+    const parts = trimmed.split(":").map((p) => Number(p));
+    if (parts.some((n) => !Number.isFinite(n)))
+        throw new Error(`Invalid time: ${raw} (use seconds, mm:ss, or hh:mm:ss).`);
+    return parts.reduce((acc, n) => acc * 60 + n, 0);
+}
+// Pull the finished media URL out of a settled primitive job (GET /me/jobs/:id).
+// Mirrors the server's extractOutputUrlFromJob.
+function resolveJobMediaUrl(job) {
+    if (!job || typeof job !== "object")
+        return null;
+    const readStr = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
+    const result = (job.result && typeof job.result === "object") ? job.result : {};
+    const output = (result.output && typeof result.output === "object") ? result.output : result;
+    const direct = readStr(output.primary_file_url)
+        ?? readStr(output.video?.file_url)
+        ?? readStr(output.image?.file_url)
+        ?? readStr(output.render?.output_url);
+    if (direct)
+        return direct;
+    if (Array.isArray(output.files)) {
+        for (const f of output.files) {
+            const u = readStr(typeof f === "string" ? f : (f?.file_url ?? f?.url));
+            if (u)
+                return u;
+        }
+    }
+    if (Array.isArray(job.artifacts)) {
+        for (const a of job.artifacts) {
+            const u = readStr(a?.public_url);
+            if (u)
+                return u;
+        }
+    }
+    return null;
+}
+// Poll a primitive job until it settles (or times out). Returns the final job.
+async function pollPrimitiveJob(ctx, jobId) {
+    const MAX_WAIT_MS = 8 * 60 * 1000;
+    const startedAt = Date.now();
+    let last = null;
+    for (;;) {
+        await sleep(5000);
+        const res = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/user/me/jobs/${encodeURIComponent(jobId)}`, auth: ctx.auth });
+        if (res.ok && res.json) {
+            last = res.json;
+            const status = String(last.status ?? "");
+            if (!ctx.json)
+                console.log(`${DIM}  ${status}${typeof last.progress === "number" ? ` ${Math.round(last.progress * 100)}%` : ""}${RESET}`);
+            if (status === "succeeded" || status === "failed" || status === "cancelled")
+                return last;
+            if (resolveJobMediaUrl(last))
+                return last;
+        }
+        if (Date.now() - startedAt > MAX_WAIT_MS)
+            return last ?? { status: "timeout" };
+    }
+}
+// Upload a local file to the ephemeral temp store, returning its durable URL.
+// Used to turn `--ref @local.png` into a direct asset URL for reference images.
+async function uploadTempFileForRef(ctx, absPath) {
+    if (!existsSync(absPath))
+        throw new Error(`No such reference file: ${absPath}`);
+    const form = new FormData();
+    form.append("file", new Blob([readFileSync(absPath)]), path.basename(absPath));
+    const res = await fetch(new URL("/api/v1/user/me/temporary-files/upload", ctx.host), { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    if (!res.ok)
+        throw new Error(`reference upload failed (${res.status}): ${text.slice(0, 200)}`);
+    const url = json?.file?.view_url ?? json?.file?.s3_url;
+    if (!url)
+        throw new Error("reference upload returned no durable URL.");
+    return url;
+}
+// Resolve --ref values: pass http(s) URLs through; upload @local files.
+async function resolveReferenceUrls(ctx, refs) {
+    const out = [];
+    for (const raw of refs ?? []) {
+        const value = raw.trim();
+        if (!value)
+            continue;
+        if (value.startsWith("@")) {
+            out.push(await uploadTempFileForRef(ctx, path.resolve(process.cwd(), value.slice(1))));
+        }
+        else if (/^https?:\/\//i.test(value)) {
+            out.push(value);
+        }
+        else {
+            // Bare path with no @ — treat as a local file too, for convenience.
+            out.push(await uploadTempFileForRef(ctx, path.resolve(process.cwd(), value)));
+        }
+    }
+    return out;
+}
+function inferMediaKindFromUrl(url) {
+    return /\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(url) ? "video" : "image";
+}
+// Resolve a composition.html on disk from a file path or a directory holding one.
+function resolveCompositionHtmlPath(target) {
+    const abs = path.resolve(process.cwd(), target);
+    if (existsSync(abs) && statSync(abs).isDirectory()) {
+        const inside = path.join(abs, "composition.html");
+        if (!existsSync(inside))
+            throw new Error(`No composition.html inside ${abs}. Run \`vidfarm pull <forkId> --dir ${target}\` first.`);
+        return inside;
+    }
+    if (!existsSync(abs))
+        throw new Error(`No such composition file or dir: ${abs}.`);
+    return abs;
+}
+// Apply an insert/replace of a media URL onto a composition.html on disk.
+function placeMediaOnDisk(input) {
+    const html = readFileSync(input.htmlPath, "utf8");
+    const opts = {
+        kind: input.kind,
+        src: input.src,
+        layerKey: input.layerKey,
+        start: input.at,
+        duration: input.duration,
+        track: input.track,
+        x: input.x,
+        y: input.y,
+        width: input.width,
+        height: input.height,
+        objectFit: input.objectFit,
+        slug: input.slug
+    };
+    const result = input.replace
+        ? replaceLayerWithMedia(html, input.replace, opts)
+        : insertMediaLayer(html, opts);
+    writeFileSync(input.htmlPath, result.html);
+    return { layerKey: result.layerKey, gaps: computeCompositionGaps(result.html) };
+}
+async function runGenerateCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            prompt: { type: "string" },
+            ref: { type: "string", multiple: true },
+            "aspect-ratio": { type: "string" },
+            duration: { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            resolution: { type: "string" },
+            audio: { type: "boolean", default: false },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" },
+            // Fused placement onto a local composition.html.
+            place: { type: "string" },
+            at: { type: "string" },
+            replace: { type: "string" },
+            track: { type: "string" },
+            "layer-key": { type: "string" }
+        }
+    });
+    const mediaType = parsed.positionals[0];
+    if (mediaType !== "image" && mediaType !== "video") {
+        throw new Error("generate requires a media type: `vidfarm generate image ...` or `vidfarm generate video ...`.");
+    }
+    const prompt = parsed.values.prompt;
+    if (!prompt || !prompt.trim())
+        throw new Error("generate requires --prompt \"...\".");
+    const ctx = commonContext(parsed.values);
+    const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
+    const payload = { prompt };
+    if (parsed.values["aspect-ratio"])
+        payload.aspect_ratio = parsed.values["aspect-ratio"];
+    if (parsed.values.provider)
+        payload.provider = parsed.values.provider;
+    if (parsed.values.model)
+        payload.model = parsed.values.model;
+    if (mediaType === "video") {
+        if (parsed.values.duration)
+            payload.duration = Math.round(Number(parsed.values.duration));
+        if (parsed.values.resolution)
+            payload.resolution = parsed.values.resolution;
+        if (parsed.values.audio)
+            payload.generate_audio = true;
+        if (refs.length)
+            payload.input_references = refs.slice(0, 8);
+    }
+    else if (refs.length) {
+        payload.prompt_attachments = refs.slice(0, 16);
+    }
+    const tracer = parsed.values.tracer ?? `devcli-gen-${Date.now().toString(36)}`;
+    const route = mediaType === "video" ? "/api/v1/primitives/videos/generate" : "/api/v1/primitives/images/generate";
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: route, auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "generate");
+    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}Generating ${mediaType} (${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}Generation ${status || "did not finish"} — no media URL.${RESET}`);
+            printJson(job);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // Optional fused placement onto a local composition.html.
+    let placement = null;
+    if (parsed.values.place) {
+        const htmlPath = resolveCompositionHtmlPath(String(parsed.values.place));
+        placement = placeMediaOnDisk({
+            htmlPath,
+            src: mediaUrl,
+            kind: mediaType,
+            at: parsed.values.at ? parseTimeToSeconds(String(parsed.values.at)) : undefined,
+            replace: parsed.values.replace,
+            track: parsed.values.track ? Number(parsed.values.track) : 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, media_type: mediaType, placement });
+    }
+    else {
+        console.log(`${GREEN}${mediaType} ready:${RESET} ${mediaUrl}`);
+        if (!placement)
+            console.log(`${DIM}Place it with: vidfarm place <dir> --src "${mediaUrl}" --kind ${mediaType} --at <time>|--replace <layer_key>${RESET}`);
+    }
+}
+async function runPlaceCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            src: { type: "string" },
+            kind: { type: "string" },
+            at: { type: "string" },
+            duration: { type: "string" },
+            replace: { type: "string" },
+            track: { type: "string" },
+            x: { type: "string" },
+            y: { type: "string" },
+            width: { type: "string" },
+            height: { type: "string" },
+            "object-fit": { type: "string" },
+            "layer-key": { type: "string" },
+            slug: { type: "string" }
+        }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("place requires a composition path: `vidfarm place <dir-or-composition.html> --src <url> ...`.");
+    const src = parsed.values.src;
+    if (!src || !/^https?:\/\//i.test(src))
+        throw new Error("place requires --src <direct media URL>.");
+    const ctx = commonContext(parsed.values);
+    const htmlPath = resolveCompositionHtmlPath(target);
+    const kind = parsed.values.kind === "video" || parsed.values.kind === "image"
+        ? parsed.values.kind
+        : inferMediaKindFromUrl(src);
+    const num = (v) => (v !== undefined ? Number(v) : undefined);
+    const placement = placeMediaOnDisk({
+        htmlPath,
+        src,
+        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),
+        x: num(parsed.values.x),
+        y: num(parsed.values.y),
+        width: num(parsed.values.width),
+        height: num(parsed.values.height),
+        objectFit: parsed.values["object-fit"],
+        layerKey: parsed.values["layer-key"],
+        slug: parsed.values.slug
+    });
+    if (ctx.json) {
+        printJson({ ok: true, layer_key: placement.layerKey, path: htmlPath, timeline_gaps: placement.gaps });
+    }
+    else {
+        console.log(`${GREEN}Placed ${kind} as ${placement.layerKey}${parsed.values.replace ? ` (replaced ${parsed.values.replace})` : ""} in ${htmlPath}.${RESET}`);
+        console.log(`${DIM}Remaining timeline gaps: ${placement.gaps.length ? placement.gaps.map((g) => `${g.start}-${g.end}s`).join(", ") : "none"}.${RESET}`);
+        console.log(`${DIM}Publish with: vidfarm publish --dir ${path.dirname(htmlPath)} --fork <forkId>  (or it live-morphs under \`serve\`).${RESET}`);
+    }
+}
+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];
+    if (!forkId)
+        throw new Error("pull requires a fork id: `vidfarm pull <forkId> [--dir <path>]`.");
+    const ctx = commonContext(parsed.values);
+    const dir = path.resolve(process.cwd(), parsed.values.dir ?? path.join(".vidfarm", forkId));
+    mkdirSync(dir, { recursive: true });
+    await fetchCompositionFiles({ host: ctx.host, forkId, dir, apiKey: ctx.auth.apiKey, shareToken: ctx.auth.shareToken, refetch: Boolean(parsed.values.refetch) });
+    const htmlPath = path.join(dir, "composition.html");
+    if (!existsSync(htmlPath))
+        throw new Error(`pull did not fetch composition.html for ${forkId} (check credentials / fork id).`);
+    const info = inspectComposition(readFileSync(htmlPath, "utf8"));
+    const hasContext = existsSync(path.join(dir, "video-context.json"));
+    const hasCast = existsSync(path.join(dir, "cast.json"));
+    if (ctx.json) {
+        printJson({ ok: true, fork_id: forkId, dir, has_video_context: hasContext, has_cast: hasCast, ...info });
+        return;
+    }
+    console.log(`${GREEN}Pulled ${forkId} → ${dir}${RESET}`);
+    console.log(`${DIM}Canvas ${info.width ?? "?"}x${info.height ?? "?"} (${info.aspect_ratio ?? "?"}), ${info.duration_seconds}s, ${info.layers.length} layers.${RESET}`);
+    console.log(`${BOLD}Timeline gaps (blank space to fill):${RESET} ${info.gaps.length ? info.gaps.map((g) => `${g.start}-${g.end}s (${g.duration}s)`).join(", ") : "none"}`);
+    console.log(`${BOLD}Scenes / layers (keys to replace):${RESET}`);
+    for (const layer of info.layers) {
+        const flags = [layer.is_timeline_proxy ? "proxy" : null, layer.is_full_canvas ? "full-canvas" : null].filter(Boolean).join(",");
+        console.log(`  ${layer.key}  ${DIM}${layer.kind ?? "?"} ${layer.start}-${(layer.start + layer.duration).toFixed(2)}s track${layer.track}${flags ? ` [${flags}]` : ""}${layer.slug ? ` slug=${layer.slug}` : ""}${RESET}`);
+    }
+    console.log(`${DIM}Grounding: ${hasContext ? "video-context.json ✓" : "video-context.json ✗ (run `vidfarm decompose`)"}, ${hasCast ? "cast.json ✓" : "cast.json ✗"}.${RESET}`);
+    console.log(`${DIM}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) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
     const forkId = parsed.positionals[0];
@@ -1316,6 +1943,132 @@ async function runDownloadCommand(argv) {
         console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
     }
 }
+// Browse the user's My Files library — the persistent per-user asset store
+// (videos, images, audio, docs) organized into virtual folders. `files` lists
+// them (optionally scoped to a folder); `get-file` resolves one attachment id to
+// its durable URL and either streams the bytes to disk or prints text contents.
+// This is the same filesystem the /editor AI agent browses via the browse_files
+// tool, so an agent CLI (Claude Code / Codex) can find assets the same way.
+async function runFilesCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" } } });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/attachments", auth: ctx.auth });
+    assertApiOk(result, "files");
+    const folderFilter = parsed.values.folder ? String(parsed.values.folder).replace(/^\/+|\/+$/g, "") : undefined;
+    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);
+}
+async function runGetFileCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), print: { type: "boolean", default: false } } });
+    const fileId = parsed.positionals[0];
+    if (!fileId)
+        throw new Error("get-file requires a file id (run `files` to list ids).");
+    const ctx = commonContext(parsed.values);
+    const list = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/attachments", auth: ctx.auth });
+    assertApiOk(list, "get-file");
+    const attachments = Array.isArray(list.json?.attachments) ? list.json.attachments : [];
+    const match = attachments.find((file) => file?.id === fileId) ?? attachments.find((file) => file?.fileName === fileId);
+    if (!match)
+        throw new Error(`No file with id or name "${fileId}" in My Files. Run \`files\` to list ids.`);
+    const viewUrl = match.viewUrl;
+    if (!viewUrl)
+        throw new Error(`File "${match.fileName}" has no resolvable URL.`);
+    const absoluteUrl = new URL(viewUrl, ctx.host).toString();
+    const res = await fetch(absoluteUrl, { headers: buildAuthHeaders(ctx.auth) });
+    if (!res.ok || !res.body)
+        throw new Error(`get-file failed: ${res.status} ${res.statusText} (${absoluteUrl}).`);
+    if (parsed.values.print) {
+        const text = await res.text();
+        process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+        return;
+    }
+    const dest = parsed.positionals[1]
+        ? path.resolve(process.cwd(), parsed.positionals[1])
+        : path.resolve(process.cwd(), match.fileName || path.basename(new URL(absoluteUrl).pathname) || "download.bin");
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(dest));
+    const bytes = safeSize(dest);
+    if (ctx.json) {
+        printJson({ ok: true, file_id: match.id, file_name: match.fileName, url: absoluteUrl, path: dest, bytes });
+    }
+    else {
+        console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
+    }
+}
+// Write a file INTO My Files — the persistent per-user library (`/me/attachments`),
+// NOT the ephemeral temporary-files store that `upload` targets. This is what an
+// agent uses to save durable context docs during Getting Started (About.md,
+// Interview.md, awareness-levels.md, persuasive-angles.md, ad-hooks.md) or to drop
+// brand assets under /brand-assets, product demos under /product-demos, etc.
+// Content can come from a local file (positional), inline --content, or piped stdin.
+// It is the write counterpart to `files`/`get-file` and the same store the /editor
+// AI copilot writes to via the browse_files write action.
+async function runPutFileCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            folder: { type: "string" },
+            as: { type: "string" },
+            content: { type: "string" },
+            stdin: { type: "boolean", default: false }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const localPath = parsed.positionals[0];
+    const asName = parsed.values.as ? String(parsed.values.as) : undefined;
+    let buffer;
+    let fileName = asName;
+    if (parsed.values.stdin) {
+        if (!fileName)
+            throw new Error("put-file --stdin requires --as <name> to name the file in My Files.");
+        buffer = readFileSync(0); // fd 0 = stdin (piped content)
+    }
+    else if (parsed.values.content != null) {
+        if (!fileName)
+            throw new Error("put-file --content requires --as <name> to name the file in My Files.");
+        buffer = Buffer.from(String(parsed.values.content), "utf8");
+    }
+    else if (localPath) {
+        const abs = path.resolve(process.cwd(), localPath);
+        if (!existsSync(abs))
+            throw new Error(`No such file: ${abs}`);
+        buffer = readFileSync(abs);
+        if (!fileName)
+            fileName = path.basename(abs);
+    }
+    else {
+        throw new Error("put-file requires a local file path, or --content/--stdin with --as <name>.");
+    }
+    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));
+    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 result = { status: res.status, ok: res.ok, json, text };
+    assertApiOk(result, "put-file");
+    emitResult(result, ctx.json, [["My Files URL", result.json?.attachment?.viewUrl]]);
+}
 // ── Agent skill ───────────────────────────────────────────────────────────────
 // Install the latest director skill onto disk as a Claude Code / agent skill so
 // the user's AI agent can read SKILL.director.md and act. We pull the freshest