@mevdragon/vidfarm-devcli 0.5.0 → 0.5.2

package/dist/src/cli.js

@@ -7,6 +7,7 @@ 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";
 // 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
@@ -40,7 +41,8 @@ Usage:
 
 Local editor loop:
   serve [template_id] [opts]  Boot the FULL editor locally (single origin, disk-backed).
-                              Records + storage run on disk; render stays on cloud.
+                              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.
@@ -56,19 +58,59 @@ Local editor loop:
   publish [template_id]     Push local composition.html/json to your fork  → PUT/PATCH composition + POST versions
 
 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
+
+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
@@ -96,13 +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
@@ -158,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;
@@ -170,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;
@@ -243,6 +314,10 @@ async function main() {
         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 to booting the local editor.
@@ -972,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`;
@@ -1032,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];
@@ -1168,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 }
     });
@@ -1212,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];
@@ -1526,6 +1999,76 @@ async function runGetFileCommand(argv) {
         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