@mevdragon/vidfarm-devcli 0.20.1 → 0.20.3

package/dist/src/cli.js

@@ -25,8 +25,8 @@ import { initTelemetry, reportCliCrash } from "./devcli/telemetry.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.
+// editor and a coding agent share one source of truth. Render can run locally
+// in-process or hand off to cloud; the remaining commands wrap 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
@@ -35,18 +35,21 @@ const SKILL_TARGETS = {
     "vidfarm-director": { route: "/skill/vidfarm-director", bundled: "SKILL.director.md" },
     "vidfarm-platform": { route: "/skill/vidfarm-platform", bundled: "SKILL.platform.md" }
 };
-// Every command below is a thin wrapper over ONE Vidfarm REST call (the `→`
-// line documents the exact route). The devcli adds nothing the raw API can't
-// do — it just resolves your fork, sets the `vidfarm-api-key` header, prints
-// the prod frontend URL to open, and handles the multi-step upload/download +
-// render-polling flows that are awkward to do by hand. Prefer the raw REST API
-// (or `vidfarm api <METHOD> <path>`) whenever you want full control; reach for
-// the named commands when you want the ergonomics and the frontend links.
+// Most commands below are thin wrappers over ONE Vidfarm REST call (the `→`
+// line documents the exact route). A few convenience commands compose the raw
+// API for you when that is the ergonomic default. The devcli adds nothing the
+// raw API can't do — it just resolves your fork, sets the `vidfarm-api-key`
+// header, prints the prod frontend URL to open, and handles the multi-step
+// upload/download + render-polling flows that are awkward to do by hand.
+// Prefer the raw REST API (or `vidfarm api <METHOD> <path>`) whenever you want
+// full control; reach for the named commands when you want the ergonomics and
+// the frontend links.
 const HELP = `vidfarm-devcli — command-line bridge for the Vidfarm video studio
 
-Every named command maps 1:1 to a single REST route (shown as → below). Use
-raw REST (or \`vidfarm api\`) when you want control; use named commands for the
-ergonomics + prod frontend links. Auth: --api-key <key> or VIDFARM_API_KEY.
+Most named commands map 1:1 to a REST route (shown as → below). A few compose
+the same routes for file-backed scripting. Use raw REST (or \`vidfarm api\`) when
+you want control; use named commands for ergonomics + prod frontend links.
+Auth: --api-key <key> or VIDFARM_API_KEY.
 
 Usage:
   vidfarm <template_id> [opts]              Start local editor session (default)
@@ -118,7 +121,7 @@ Composition lifecycle (fork → decompose → snapshot → render):
   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
+  generate <image|video>    Generate AI media, poll to the finished public 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
@@ -372,9 +375,17 @@ Fine timeline control (trackpad-level verbs on a pulled/served composition — l
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
   render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/render
+                            --dir <dir|composition.html> pushes local
+                            composition.html + composition.json first
+                            --target local|cloud chooses in-process or
+                            cloud handoff when the backend supports both
                             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
+  template run <template_id> <operation_name>
+                            Run one template operation via REST          → POST /api/v1/templates/:templateId/operations/:operationName
+                            --payload-file / --payload supply the input
+                            --wait polls GET /api/v1/user/me/jobs/:jobId
   visibility <forkId> <private|public>   Set fork visibility            → PATCH .../compositions/:forkId/visibility
   clone <forkId> [--from current|default] [--version N]
                             New fork: --from current (default) branches this
@@ -495,7 +506,10 @@ Cost spectrum (default to the cheapest approach that works; see SKILL.director.m
 Escape hatch — call ANY route directly:
   api <METHOD> <path>       Raw REST call with auth + pretty errors
     --data <json>           JSON request body (or --data-file <path>)
+    --body-file <path>      Literal request body file (for HTML/text payloads)
+    --content-type <mime>   Content-Type for --body-file (default text/plain)
     --query k=v             Repeatable query param
+    --raw                   Print the exact response body, not pretty JSON
   Examples:
     vidfarm api GET /discover/feed
     vidfarm api POST /api/v1/compositions --data '{"template_id":"template_..."}'
@@ -643,6 +657,9 @@ async function main() {
         case "render-status":
             await runRenderStatusCommand(rest);
             return;
+        case "template":
+            await runTemplateCommand(rest);
+            return;
         case "visibility":
             await runVisibilityCommand(rest);
             return;
@@ -818,8 +835,14 @@ async function apiRequest(input) {
     const headers = { ...buildAuthHeaders(input.auth), accept: "application/json" };
     let body;
     if (input.body !== undefined) {
-        headers["content-type"] = "application/json";
-        body = JSON.stringify(input.body);
+        if (typeof input.body === "string") {
+            body = input.body;
+            headers["content-type"] = input.contentType ?? "text/plain; charset=utf-8";
+        }
+        else {
+            headers["content-type"] = input.contentType ?? "application/json";
+            body = JSON.stringify(input.body);
+        }
     }
     const res = await fetch(url, { method: input.method.toUpperCase(), headers, body });
     const text = await res.text();
@@ -1329,9 +1352,12 @@ async function fetchCompositionFiles(input) {
     // literal + viral DNA an agent needs to REPLACE a scene from the clip library
     // or RE-CREATE it from scratch (recreation_prompt + recreation_notes).
     // editor-harness.json carries the technical EDITING DIRECTION (pace,
-    // typography, b-roll, transitions, audio, scene roles under `.harness`) so an
-    // agent can one-shot a clean, on-style edit — the "how to edit like this"
-    // companion to the video-context viral DNA.
+    // typography, b-roll, transitions, audio, scene roles, PLUS an `emotional`
+    // block — comedic_timing/intonation/vibe_anchors — for keeping the FEELING,
+    // all under `.harness`) so an agent can one-shot a clean, on-style edit — the
+    // "how to edit like this" companion to the video-context viral DNA (whose
+    // `emotional_punch` captures the joke/vibe/intonation and, being decomposed
+    // over the transcript too, the trending sound driving the emotion).
     const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json", "scene-annotations.json", "editor-harness.json"];
     for (const filename of files) {
         const target = path.join(input.dir, filename);
@@ -1631,7 +1657,15 @@ async function runApiCommand(argv) {
     const parsed = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { ...commonOptions(), data: { type: "string" }, "data-file": { type: "string" }, query: { type: "string", multiple: true } }
+        options: {
+            ...commonOptions(),
+            data: { type: "string" },
+            "data-file": { type: "string" },
+            "body-file": { type: "string" },
+            "content-type": { type: "string" },
+            query: { type: "string", multiple: true },
+            raw: { type: "boolean", default: false }
+        }
     });
     const method = parsed.positionals[0];
     const routePath = parsed.positionals[1];
@@ -1639,10 +1673,16 @@ async function runApiCommand(argv) {
         throw new Error(`api requires <METHOD> <path>.\n\nExample: vidfarm api GET /discover/feed`);
     }
     const ctx = commonContext(parsed.values);
+    if (parsed.values["data-file"] && parsed.values["body-file"]) {
+        throw new Error("api accepts either --data-file (JSON) or --body-file (literal), not both.");
+    }
     let body;
     if (parsed.values["data-file"]) {
         body = JSON.parse(readFileSync(path.resolve(process.cwd(), String(parsed.values["data-file"])), "utf8"));
     }
+    else if (parsed.values["body-file"]) {
+        body = readFileSync(path.resolve(process.cwd(), String(parsed.values["body-file"])), "utf8");
+    }
     else if (parsed.values.data) {
         body = JSON.parse(String(parsed.values.data));
     }
@@ -1652,16 +1692,139 @@ async function runApiCommand(argv) {
         path: routePath,
         auth: ctx.auth,
         query: collectKeyValues(parsed.values.query),
-        body
+        body,
+        contentType: parsed.values["body-file"] ? parsed.values["content-type"] : undefined
     });
     if (!ctx.json) {
         const color = result.ok ? GREEN : RED;
         console.log(`${color}${method.toUpperCase()} ${routePath} → ${result.status}${RESET}`);
     }
-    printJson(result.json ?? result.text);
+    if (parsed.values.raw)
+        process.stdout.write(result.text);
+    else
+        printJson(result.json ?? result.text);
     if (!result.ok)
         process.exitCode = 1;
 }
+function parseJsonInput(raw, label) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${label} must be valid JSON.`);
+    }
+}
+async function waitForJobCompletion(ctx, jobId, pollMs) {
+    const intervalMs = Number.isFinite(pollMs) && pollMs > 0 ? pollMs : 2000;
+    while (true) {
+        const result = await dispatch(ctx, {
+            method: "GET",
+            path: `/api/v1/user/me/jobs/${encodeURIComponent(jobId)}`
+        }, ctx.target === "cloud" ? "cloud" : "local");
+        if (!result.ok) {
+            return result;
+        }
+        const status = String(result.json?.status ?? "").toLowerCase();
+        if (!["queued", "running", "waiting_for_provider", "waiting_for_render", "waiting_for_child", "waiting_for_human"].includes(status)) {
+            return result;
+        }
+        await sleep(intervalMs);
+    }
+}
+async function runTemplateCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            tracer: { type: "string" },
+            wait: { type: "boolean", default: false },
+            "poll-ms": { type: "string" },
+            body: { type: "string" },
+            "body-file": { type: "string" },
+            payload: { type: "string" },
+            "payload-file": { type: "string" },
+            "webhook-url": { type: "string" }
+        }
+    });
+    const subcommand = parsed.positionals[0];
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h" || !subcommand) {
+        console.log(`vidfarm template — run template operations via REST
+  template run <template_id> <operation_name> [--payload-file payload.json | --payload '{...}']
+    [--tracer <id>] [--webhook-url <url>] [--wait] [--poll-ms 2000]
+    --body-file / --body can send the exact REST envelope instead of auto-wrapping
+`);
+        return;
+    }
+    if (subcommand !== "run") {
+        throw new Error(`Unknown template subcommand: ${subcommand}`);
+    }
+    const templateId = parsed.positionals[1];
+    const operationName = parsed.positionals[2];
+    if (!templateId || !operationName) {
+        throw new Error("template run requires <template_id> <operation_name>.");
+    }
+    const ctx = commonContext(parsed.values);
+    if (ctx.target === "both") {
+        throw new Error("template run only supports one backend at a time. Use --cloud or omit it for the local backend.");
+    }
+    const rawBody = parsed.values["body-file"]
+        ? readFileSync(path.resolve(process.cwd(), String(parsed.values["body-file"])), "utf8")
+        : typeof parsed.values.body === "string"
+            ? parsed.values.body
+            : null;
+    const payloadSource = parsed.values["payload-file"]
+        ? readFileSync(path.resolve(process.cwd(), String(parsed.values["payload-file"])), "utf8")
+        : typeof parsed.values.payload === "string"
+            ? parsed.values.payload
+            : null;
+    let body;
+    if (rawBody !== null) {
+        body = parseJsonInput(rawBody, "template body");
+    }
+    else {
+        const payload = payloadSource === null ? {} : parseJsonInput(payloadSource, "template payload");
+        if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+            throw new Error("template payload must be a JSON object.");
+        }
+        body = {
+            tracer: typeof parsed.values.tracer === "string" && parsed.values.tracer.trim()
+                ? parsed.values.tracer.trim()
+                : `template_run_${templateId}_${operationName}_${Date.now()}`,
+            payload,
+            ...(typeof parsed.values["webhook-url"] === "string" && parsed.values["webhook-url"].trim()
+                ? { webhook_url: parsed.values["webhook-url"].trim() }
+                : {})
+        };
+    }
+    const result = await dispatch(ctx, {
+        method: "POST",
+        path: `/api/v1/templates/${encodeURIComponent(templateId)}/operations/${encodeURIComponent(operationName)}`,
+        body
+    }, ctx.target);
+    if (!result.ok && result.status !== 202) {
+        assertApiOk(result, `template run ${templateId}:${operationName}`);
+    }
+    if (!parsed.values.wait) {
+        emitResult(result, ctx.json);
+        return;
+    }
+    const jobId = result.json?.job_id;
+    if (typeof jobId !== "string" || !jobId.trim()) {
+        emitResult(result, ctx.json);
+        return;
+    }
+    const pollMs = Number(parsed.values["poll-ms"] ?? 2000);
+    const final = await waitForJobCompletion(ctx, jobId, pollMs);
+    emitResult(final, ctx.json);
+    const finalStatus = String(final.json?.status ?? "").toLowerCase();
+    if (!final.ok || !["succeeded", "completed"].includes(finalStatus)) {
+        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
@@ -2168,18 +2331,40 @@ async function runRenderCommand(argv) {
     const parsed = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { ...commonOptions(), title: { type: "string" }, tracer: { type: "string" }, wait: { type: "boolean", default: false } }
+        options: {
+            ...commonOptions(),
+            dir: { type: "string" },
+            title: { type: "string" },
+            tracer: { type: "string" },
+            target: { type: "string", default: "local" },
+            wait: { type: "boolean", default: false }
+        }
     });
     const forkId = parsed.positionals[0];
     if (!forkId)
         throw new Error("render requires a fork id.");
     const ctx = commonContext(parsed.values);
+    const renderTarget = String(parsed.values.target ?? "local");
+    if (renderTarget !== "local" && renderTarget !== "cloud") {
+        throw new Error(`render --target must be local or cloud, got: ${renderTarget}`);
+    }
+    const sourceDir = parsed.values.dir ? resolveCompositionSourceDir(String(parsed.values.dir)) : null;
+    if (sourceDir) {
+        await pushCompositionFromDir({
+            forkId,
+            rootDir: sourceDir,
+            host: ctx.host,
+            auth: ctx.auth,
+            json: ctx.json,
+            action: "render"
+        });
+    }
     const result = await apiRequest({
         method: "POST",
         host: ctx.host,
         path: `/api/v1/compositions/${encodeURIComponent(forkId)}/render`,
         auth: ctx.auth,
-        body: { title: parsed.values.title, tracer: parsed.values.tracer }
+        body: { title: parsed.values.title, tracer: parsed.values.tracer, render_target: renderTarget }
     });
     assertApiOk(result, "render");
     const renderId = result.json?.renderId;
@@ -2187,7 +2372,7 @@ async function runRenderCommand(argv) {
         if (!ctx.json && renderId) {
             console.log(`${DIM}Poll with: vidfarm render-status ${forkId} ${renderId} (or add --wait next time).${RESET}`);
         }
-        emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.outputUrl]]);
+        emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.expectedOutputPublicUrl ?? result.json?.outputUrl]]);
         return;
     }
     // --wait: poll the render job until it settles.
@@ -2206,10 +2391,52 @@ async function runRenderCommand(argv) {
         if (status === "SUCCEEDED" || status === "FAILED")
             break;
     }
-    emitResult(last, ctx.json, [["Rendered MP4 ", last.json?.outputUrl]]);
+    emitResult(last, ctx.json, [["Rendered MP4 ", last.json?.expectedOutputPublicUrl ?? last.json?.outputUrl]]);
     if (String(last.json?.status) === "FAILED")
         process.exitCode = 1;
 }
+function resolveCompositionSourceDir(inputPath) {
+    const absolute = path.resolve(process.cwd(), inputPath);
+    if (!existsSync(absolute)) {
+        throw new Error(`render --dir path does not exist: ${absolute}`);
+    }
+    const stat = statSync(absolute);
+    if (stat.isDirectory())
+        return absolute;
+    if (stat.isFile() && path.basename(absolute) === "composition.html")
+        return path.dirname(absolute);
+    throw new Error("render --dir must point to a directory or composition.html.");
+}
+async function pushCompositionFromDir(input) {
+    const htmlPath = path.join(input.rootDir, "composition.html");
+    if (!existsSync(htmlPath)) {
+        throw new Error(`No composition.html at ${htmlPath}.`);
+    }
+    const html = readFileSync(htmlPath, "utf8");
+    if (!html.includes("data-composition-id=")) {
+        throw new Error("composition.html is missing data-composition-id — refusing to render a malformed composition.");
+    }
+    const jsonPath = path.join(input.rootDir, "composition.json");
+    const compositionJson = existsSync(jsonPath) ? readFileSync(jsonPath, "utf8") : null;
+    if (compositionJson !== null) {
+        try {
+            JSON.parse(compositionJson || "{}");
+        }
+        catch (error) {
+            throw new Error(`composition.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (!input.json)
+        console.log(`[vidfarm] ${input.action}: pushing ${input.rootDir} → ${input.forkId}`);
+    await putComposition(`${input.host}/api/v1/compositions/${encodeURIComponent(input.forkId)}/composition.html`, "PUT", html, "text/html; charset=utf-8", input.auth);
+    if (!input.json)
+        console.log(`[vidfarm] pushed composition.html (${Buffer.byteLength(html)} bytes)`);
+    if (compositionJson !== null) {
+        await putComposition(`${input.host}/api/v1/compositions/${encodeURIComponent(input.forkId)}/composition.json`, "PATCH", compositionJson, "application/json", input.auth);
+        if (!input.json)
+            console.log(`[vidfarm] pushed composition.json (${Buffer.byteLength(compositionJson)} bytes)`);
+    }
+}
 async function runRenderStatusCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
     const forkId = parsed.positionals[0];
@@ -2219,7 +2446,7 @@ async function runRenderStatusCommand(argv) {
     const ctx = commonContext(parsed.values);
     const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/renders/${encodeURIComponent(renderId)}`, auth: ctx.auth });
     assertApiOk(result, "render-status");
-    emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.outputUrl]]);
+    emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.expectedOutputPublicUrl ?? result.json?.outputUrl]]);
 }
 // ── AI generation + timeline placement (for local coding agents) ────────────
 // `generate` submits an AI image/video primitive job and (by default) polls it

package/dist/src/devcli/sync.js

@@ -66,16 +66,42 @@ async function readBytes(ctx, space, item) {
         const { withLocalBackend } = await import("./local-backend.js");
         const backend = await withLocalBackend({ home: ctx.home, apiKey: ctx.apiKey });
         const u = new URL(item.viewUrl, "http://vidfarm.local");
+        if (!isLocalFileViewPath(u.pathname)) {
+            throw new Error(`Refusing local sync read outside Vidfarm file storage: ${item.path}`);
+        }
         const res = await backend.app.request(u.pathname + u.search, { headers: authHeaders(ctx.apiKey) });
         if (!res.ok)
             throw new Error(`local read ${item.path} → HTTP ${res.status}`);
         return Buffer.from(await res.arrayBuffer());
     }
-    const res = await fetch(item.viewUrl, { headers: authHeaders(ctx.apiKey) });
+    const url = validateCloudFileViewUrl(ctx, item);
+    const res = await fetch(url, { headers: authHeaders(ctx.apiKey) });
     if (!res.ok)
         throw new Error(`cloud read ${item.path} → HTTP ${res.status}`);
     return Buffer.from(await res.arrayBuffer());
 }
+function isLocalFileViewPath(pathname) {
+    return pathname === "/api/v1/user/me/files/view" || pathname === "/template-media" || pathname.startsWith("/storage/");
+}
+function validateCloudFileViewUrl(ctx, item) {
+    let url;
+    try {
+        url = new URL(item.viewUrl || "", ctx.host);
+    }
+    catch {
+        throw new Error(`Invalid cloud view URL for ${item.path}`);
+    }
+    const host = new URL(ctx.host);
+    const isSameOrigin = url.origin === host.origin;
+    const isS3 = /^https:\/\/[^/]+\.s3[.-][a-z0-9-]+\.amazonaws\.com$/i.test(url.origin)
+        || /^https:\/\/s3[.-][a-z0-9-]+\.amazonaws\.com$/i.test(url.origin)
+        || /\.s3[.-][a-z0-9-]+\.amazonaws\.com$/i.test(url.hostname);
+    if (isSameOrigin && isLocalFileViewPath(url.pathname))
+        return url;
+    if (isS3)
+        return url;
+    throw new Error(`Refusing cloud sync read from non-Vidfarm URL for ${item.path}`);
+}
 /** Upload bytes into a space's My Files at folderPath/fileName (multipart — the
  *  one transport that works on both S3 and local storage). */
 async function uploadBytes(ctx, space, input) {
@@ -213,9 +239,10 @@ export async function runSyncCommand(argv) {
         home: values.home
     };
     // Scope: a /files subtree (default the whole root).
-    let rootPath = (positionals[0] ?? "/files").trim();
-    if (!rootPath.startsWith("/files")) {
-        throw new Error(`sync currently covers the /files (My Files) root — got "${rootPath}". Raws sync is a follow-up.`);
+    const rawRootPath = positionals[0] ?? "/files";
+    const rootPath = normalizeSyncRoot(rawRootPath);
+    if (!rootPath) {
+        throw new Error(`sync currently covers the /files (My Files) root — got "${rawRootPath}". Raws sync is a follow-up.`);
     }
     const srcSpace = direction === "push" ? "local" : "cloud";
     const dstSpace = direction === "push" ? "cloud" : "local";
@@ -235,7 +262,7 @@ export async function runSyncCommand(argv) {
                 console.log(`  ${GREEN}+ new${RESET}     ${src.path}`);
             }
             else {
-                await transfer(ctx, srcSpace, dstSpace, src, src.name);
+                await transfer(ctx, srcSpace, dstSpace, src, fileNameFromSyncPath(src.path));
                 console.log(`  ${GREEN}✓ sent${RESET}    ${src.path}`);
             }
             transferred += 1;
@@ -260,14 +287,15 @@ export async function runSyncCommand(argv) {
             continue;
         }
         if (resolution === "keep-both") {
-            await transfer(ctx, srcSpace, dstSpace, src, suffixName(src.name, srcSpace));
-            console.log(`  ${YELLOW}✓ both${RESET}    ${src.path} ${DIM}→ ${suffixName(src.name, srcSpace)}${RESET}`);
+            const keepBothName = suffixName(fileNameFromSyncPath(src.path), srcSpace);
+            await transfer(ctx, srcSpace, dstSpace, src, keepBothName);
+            console.log(`  ${YELLOW}✓ both${RESET}    ${src.path} ${DIM}→ ${keepBothName}${RESET}`);
         }
         else {
             // Overwrite: drop the target copy first so we replace rather than dup.
             if (dst.id)
                 await deleteAttachment(ctx, dstSpace, dst.id);
-            await transfer(ctx, srcSpace, dstSpace, src, src.name);
+            await transfer(ctx, srcSpace, dstSpace, src, fileNameFromSyncPath(src.path));
             console.log(`  ${GREEN}✓ over${RESET}    ${src.path}`);
         }
         transferred += 1;
@@ -277,15 +305,44 @@ export async function runSyncCommand(argv) {
         console.log(`  ${DIM}(dry run — nothing was written)${RESET}`);
 }
 async function transfer(ctx, from, to, item, fileName) {
+    if (!item.path.startsWith("/files/")) {
+        throw new Error(`Refusing to sync item outside /files: ${item.path}`);
+    }
+    const folderPath = folderPathFromSyncPath(item.path);
     const bytes = await readBytes(ctx, from, item);
     await uploadBytes(ctx, to, {
         fileName,
-        folderPath: item.folderPath.replace(/^files\/?/, "").replace(/^\/+|\/+$/g, ""),
+        folderPath,
         contentType: item.contentType,
         notes: item.notes,
         bytes
     });
 }
+function normalizeSyncRoot(value) {
+    const raw = value.trim();
+    const withSlash = raw.startsWith("/") ? raw : `/${raw}`;
+    const normalized = path.posix.normalize(withSlash).replace(/\/+$/, "") || "/files";
+    if (normalized === "/files" || normalized.startsWith("/files/"))
+        return normalized;
+    return null;
+}
+function fileNameFromSyncPath(value) {
+    const name = path.posix.basename(value);
+    if (!name || name === "." || name === ".." || name.includes("/")) {
+        throw new Error(`Invalid sync file path: ${value}`);
+    }
+    return name;
+}
+function folderPathFromSyncPath(value) {
+    if (!value.startsWith("/files/"))
+        throw new Error(`Invalid sync file path: ${value}`);
+    const dir = path.posix.dirname(value);
+    if (dir === "/files")
+        return "";
+    if (!dir.startsWith("/files/"))
+        throw new Error(`Invalid sync file path: ${value}`);
+    return dir.slice("/files/".length);
+}
 function normalizePolicy(v) {
     const s = String(v ?? "").trim().toLowerCase();
     if (["newest", "skip", "keep-both", "local", "cloud"].includes(s))

package/dist/src/editor-chat.js

@@ -87,7 +87,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "READ THE EXACT MARKUP WHEN YOU NEED IT: editor_context is a derived summary, not the raw HTML. When you need the precise current composition markup — to author or fix a replace_composition_html, to inspect exact inline styles, class names, or data-* attributes on a layer, or to copy an existing structure — fetch it with http_request GET /api/v1/compositions/{composition_id}/composition.html (composition_id is in editor_context). Prefer the targeted editor_action verbs for ordinary edits; pull the HTML only when you genuinely need byte-level detail.",
         "FORKING IS AUTOMATIC — you never manually 'create a fork' before editing. The editor_context reports the project state so you know what you're holding: composition_origin ('inspiration' = a decomposed catalog template opened as a structural reference — the common case; 'raw' = the user's own new project), has_saved_fork (whether edits are currently persisting to a real editable copy), and is_new_project. When has_saved_fork is false on a REAL template (a template_… id, a catalog reference, or any decomposed composition), just start editing — the FIRST mutating editor_action mints the user their OWN private editable fork and every edit after it persists normally; do NOT ask permission to fork, wait for the user to fork, or announce 'forking'. The ONE exception is is_new_project:true (composition_id \"original\"): that is a BLANK project with no template behind it yet, so there is nothing to fork and editor_action edits will NOT persist. In that state don't promise saves — mint a real composition first: on a blank project the create_video tool IS available (call it to build a brand-new video from the user's idea via mode=generate, or to recreate a pasted TikTok/YouTube/Instagram/X URL via mode=replicate — it runs the ingest→decompose→fork pipeline and drops an 'Open in editor' link), or point the user at a fitting existing template (GET /discover/feed?q=<their idea>). Once a real composition is open, edit it normally. A save_status:\"error\" / is_read_only immediately after editing a brand-new project means the auto-fork itself failed — say so plainly instead of claiming the edit saved. The ONLY time you fork ON PURPOSE is when the user EXPLICITLY asks to branch / duplicate / 'save as' / 'make a copy' / 'try a variation' / 'keep this version and start another' — then call editor_action action_type=fork_composition with fork_from='current' (branch a new copy that keeps all current edits) or fork_from='default' (start a fresh copy from the original template, discarding the current edits). This mints a NEW fork and opens it in the editor; it is the same 'New fork' action available in the editor's ⋯ menu. Never call fork_composition just to begin editing — that is what the automatic first-edit fork is for.",
         "AGENTIC VIDEO EDITING — THE THREE AXES (your core mental model for this editor). Almost every /editor session is the user taking a template, fork, or project and RE-WORKING it, and a re-work only ever touches three independent axes: SCENES (the video/image clips that carry the visuals), AUDIO (narration/voiceover, music, SFX), and TEXT (on-screen captions, titles, overlays). On each axis the intent sits somewhere on a SWAP↔REPLACE spectrum, and the three axes in one request can sit at DIFFERENT points — read the request and place each axis before you act. SWAP (light, cheap, the common case) keeps the existing structure and changes content IN PLACE: rewrite a caption/text layer (set_layer_text / set_captions), swap one clip's media for another of the same kind while keeping its timing and geometry (set_layer_media), or re-voice the narration (regenerate-speech, then mute the original span and add_layer the new audio). Many sessions are ONLY a text swap — that is a two-minute job, so just do it and confirm. REPLACE (heavy) throws out that axis's content and rebuilds it: restructure the scenes outright (new clip count / new beats via remove_layer + add_layer / generate_layer, or one replace_composition_html), lay down a brand-new audio bed, or rewrite every caption. The HARDEST end is a full re-theme where the ONLY thing preserved is the VIRAL DNA — the hook shape, pacing, scene-count rhythm, and transition/caption style — while every scene, every word, and the audio are all replaced for the user's new subject. Name your plan back to the user in these terms (e.g. 'I'll SWAP the captions and REPLACE the scenes'), then execute axis by axis. Be proactive at the heavy end: propose the whole re-work and drive it scene by scene instead of waiting to be micro-managed one layer at a time. This is first-class agentic editing — you are expected to carry a total transformation, not just nudge single layers.",
-        "EDITOR HARNESS — YOUR STYLE-EXECUTION BRIEF (read it before any nontrivial edit). editor_context.editor_harness is the decompose pass's TECHNICAL EDITING DIRECTION: how to edit so the result recreates the source's STYLE. It is the 'how to edit like this' companion to composition_context's viral DNA ('why it works'). When present it carries: one_liner (the style in a sentence); pacing (cut_rhythm fast|medium|slow|varied, avg_scene_seconds, cuts_per_10s, energy_curve); typography (caption_style, placement, font_character, emphasis, text_density); broll (reliance, sourcing, shot_kinds, cadence); transitions (default, intro, outro, usage); audio (voiceover, music, sfx, captions_from); scenes[] (each a beat's role + importance + must_keep + edit_bias); important_scenes; editing_bias; do; dont. USE IT to pick concrete moves: map typography.caption_style straight to a set_captions caption_style preset (karaoke/word-pop/spotlight/stack-up/neon/bounce); map transitions.default/intro/outro to a set_transitions call; honor pacing (keep cut rhythm / avg_scene_seconds when adding or splitting scenes); follow broll.reliance + sourcing to decide whether to HUNT raws (/clips/scan) vs generate_layer and at what cadence; lay audio per audio.*; and above all PROTECT the beats in important_scenes and any scene with must_keep:true or importance 'critical' (swapping their subject is fine, but preserve their timing, role, and caption cadence — that is where the style lives). Treat editing_bias/do/dont as hard constraints for this composition. The harness sets defaults, not a straitjacket — an explicit user instruction always wins. The local devcli agent reads the SAME brief from editor-harness.json (under `.harness`); the web editor gets it inline here. If editor_harness is absent, the fork wasn't decomposed with the harness pass — fall back to composition_context + the video_context tool.",
+        "EDITOR HARNESS — YOUR STYLE-EXECUTION BRIEF (read it before any nontrivial edit). editor_context.editor_harness is the decompose pass's TECHNICAL EDITING DIRECTION: how to edit so the result recreates the source's STYLE. It is the 'how to edit like this' companion to composition_context's viral DNA ('why it works'). When present it carries: one_liner (the style in a sentence); pacing (cut_rhythm fast|medium|slow|varied, avg_scene_seconds, cuts_per_10s, energy_curve); typography (caption_style, placement, font_character, emphasis, text_density); broll (reliance, sourcing, shot_kinds, cadence); transitions (default, intro, outro, usage); audio (voiceover, music, sfx, captions_from); emotional (target_feeling, tone, comedic_timing, intonation, vibe_anchors — HOW to edit so the FEELING survives); scenes[] (each a beat's role + importance + must_keep + edit_bias); important_scenes; editing_bias; do; dont. USE IT to pick concrete moves: map typography.caption_style straight to a set_captions caption_style preset (karaoke/word-pop/spotlight/stack-up/neon/bounce); map transitions.default/intro/outro to a set_transitions call; honor pacing (keep cut rhythm / avg_scene_seconds when adding or splitting scenes); follow broll.reliance + sourcing to decide whether to HUNT raws (/clips/scan) vs generate_layer and at what cadence; lay audio per audio.*; treat emotional.* as a HARD constraint — the vibe, the joke, and the intonation are the first things a remix flattens, so preserve emotional.comedic_timing (the held beat / pause / hard cut that sells the joke), keep the delivery cadence in emotional.intonation when you rewrite or re-voice narration, and honor every one of emotional.vibe_anchors when you re-cut or re-time; and above all PROTECT the beats in important_scenes and any scene with must_keep:true or importance 'critical' (swapping their subject is fine, but preserve their timing, role, and caption cadence — that is where the style lives). Treat editing_bias/do/dont as hard constraints for this composition. The harness sets defaults, not a straitjacket — an explicit user instruction always wins. The local devcli agent reads the SAME brief from editor-harness.json (under `.harness`); the web editor gets it inline here. If editor_harness is absent, the fork wasn't decomposed with the harness pass — fall back to composition_context + the video_context tool.",
         "RE-THEME / REUSE A TEMPLATE AS A REFERENCE — the single most common editor intent. Users open a template to keep its VIRAL DNA (structure, scene count, pacing, hook shape, transitions, caption style) while changing the SUBJECT to their own topic — e.g. 'make this book-recap template about \"The Richest Man in Babylon\"', 'do this one for my coffee brand'. Treat it as a first-class flow: PRESERVE the DNA and format (read composition_context and, when you need the scene beats/arc, the video_context tool) and REPLACE the content — rewrite every on-screen text/caption layer to the new subject IN THE TEMPLATE'S VOICE (set_layer_text / set_captions, per the format rule above), regenerate the narration in the SAME speaker's voice for the new script (/audio/regenerate-speech, then swap per the speech rule), and swap the visuals to match (generate_layer to replace scene clips, or reuse the user's own footage from My Files / raws via browse_files). Keep the clip timings, transitions, and caption animation intact so the proven format survives the swap. You don't ask permission to fork — the first edit auto-forks it into the user's own copy (see FORKING IS AUTOMATIC). Before rewriting, PROPOSE a short plan and ask ONLY what you can't infer: the specifics of the new subject (e.g. which of the book's ideas to feature — offer to pick the strongest N to match the scene count), whether to keep the current narrator voice, any brand assets/images they want used (else you'll generate them), and a target length if it differs from the template. Don't interrogate — one concise proposal plus a couple of questions, then execute scene by scene. Example opener for the book case: 'I'll keep this template's N-scene structure, pacing and caption style and re-theme it to The Richest Man in Babylon — rewriting the narration around the book's core money lessons and swapping the visuals to match. Any specific lessons you want featured (or I'll pick the strongest N)? Keep the current narrator voice? Have a cover image or should I generate the visuals?'",
         "FUEL A SCENE REPLACE WITH RAW CLIPS (don't default to expensive AI video). A heavy REPLACE of the SCENES axis needs footage, and you have three sources in cost order: (1) the user's own library — browse_files search across /raws and /files for clips that already fit the new scenes; (2) HUNTING new raws out of a long-form source — the cheap way to get REAL footage; (3) AI generation (generate_layer) — the expensive last resort, only for scenes no real clip can cover. When a scene replace needs footage the user could plausibly supply and their library doesn't already have it, PROACTIVELY offer to mine it: if they have or name a podcast, stream VOD, webinar, or any YouTube/TikTok/IG/X URL, call POST /clips/scan (alias /raws/scan) with body { tracer, source_url|temp_file_id|attachment_id, prompt: <what the new scenes need>, aspect: <the editor_context aspect_ratio>, target_duration_sec?, avoid_text?, ranges? } — an async hunt (202 + scan_id; bills AWS compute only, its BYOK AI tagging is free) that cuts the source into short, tagged, searchable raws. Poll GET /clips/scan/:scanId, then browse GET /raws/feed?source=<source_video_id> or POST /raws/search { query } and drop the picks onto the timeline (set_layer_media to swap a clip in place keeping timing+geometry, add_layer for net-new scenes). Hunting real clips is dramatically cheaper than AI-generating every scene and usually more authentic, so reach for it FIRST when a heavy scene REPLACE needs footage — reserve generate_layer for the gaps real footage cannot fill. If the user describes a big scene re-work but hasn't given you footage, ASK them for a source video to hunt (or point them at their /raws library) BEFORE reaching for AI generation.",
         "CRITICAL — verify your edits actually landed. An editor_action tool result only echoes the arguments you sent; it is NOT proof the change was applied or saved. The real outcome shows up in the NEXT <editor_context>. Before telling the user an edit succeeded, check that block: (1) if it contains save_status:\"error\" (or is_read_only:true / a save_error message), the composition is NOT being saved — do NOT claim any edit worked; tell the user exactly what save_error says (e.g. the video is read-only from this link and they should open their own copy to edit) and stop making mutating editor_action calls until it clears; (2) if it contains recent_action_results, each entry with ok:false is an edit from your previous turn that FAILED (read its error) — acknowledge the failure and retry or explain it rather than repeating a false success; (3) otherwise confirm the intended change is reflected in the layers (e.g. the new text on the target layer) before saying it's done. Never report a timeline edit as successful without this check.",
@@ -117,7 +117,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "KNOWLEDGE ON DEMAND (load_skill): deeper authoring knowledge ships as vidfarm skill packs you can read mid-conversation with the load_skill tool — YOUR OWN capability map for this editor (editor-capabilities: the editor_action verb catalog, editor_context fields, forking rules, the three-axes SWAP↔REPLACE re-theme model, and fueling a scenes replace with raws — load it before a full re-theme, a multi-scene rebuild, or when you need an exact verb/param), the composition HTML contract (hyperframes-core), motion/animation craft and transition doctrine (hyperframes-animation), seek-safe keyframe patterns (hyperframes-keyframes), creative direction/palettes/typography (hyperframes-creative), caption identities (embedded-captions), media/audio resolution (vidfarm-media), and end-to-end workflow playbooks (product-launch-video, faceless-explainer, website-to-video, general-video, motion-graphics, slideshow, talking-head-recut). Call load_skill with the pack name to read its SKILL.md; it lists reference files you can then load by relative path (e.g. file='references/step-4-vo.md'). Use it when a request needs craft beyond the built-in preset vocabulary — designing a whole composition via replace_composition_html, picking motion or transition language for a style, or following a named workflow. NOTE: hyperframes-animation and hyperframes-keyframes describe BOTH script-driven adapters (anime.js/GSAP/Lottie/Three.js) AND script-free CSS techniques — in the web editor apply only the CSS @keyframes / declarative-preset half (the JS adapters are stripped on save; see the web-editor motion rule), and reserve the adapter half for local devcli work. Load only what the task needs, never bulk-load packs, and never paste large skill content back to the user.",
         "replace_composition_html is validated before it reaches the editor: when the HTML violates the composition contract (missing data-composition-id, invalid clip timing, same-track overlaps, unknown preset names, media without src) the tool result comes back with rejected=true and lint_errors, and NOTHING is applied — fix the reported issues and call it again. lint_warnings are advisory and the action still applies.",
         "MOTION IN THE WEB EDITOR IS DECLARATIVE / CSS ONLY — no author <script>. This editor strips every <script> tag on save (stored-XSS defense), so replace_composition_html that contains a <script> is REJECTED (rejected=true), not applied. That means the JavaScript runtime animation adapters — anime.js, GSAP, Lottie, Three.js, TypeGPU, WAAPI-driven code — are NOT available here; they are a local-devcli-only capability. Author all motion for the web editor with the durable, script-free vocabulary: (1) built-in preset actions — set_layer_media ken_burns (still-image pan/zoom), set_transitions / transition + transition_out (scene entrances/exits), set_captions / caption_animation (word-by-word captions); and (2) plain CSS — @keyframes rules in a <style> block plus an inline animation on the layer element (the renderer scrubs and bakes CSS @keyframes deterministically into the final MP4, exactly like the preview). Never try to drive motion with anime.js/GSAP/etc. in the web editor, and never claim you added a scripted animation here. If the user explicitly wants a JS-adapter animation (a Lottie file, a GSAP timeline, a Three.js scene), tell them that is a local devcli / hyperframes-CLI workflow and offer the CSS/preset equivalent for the web editor instead.",
-        "TEMPLATE FORMAT — MATCH IT WHEN WRITING TEXT: the COMPOSITION BRIEF (stable template context in the system prompt) carries composition_context — WHAT THIS TEMPLATE IS: its format/genre and narrative arc (trend_tagline, hook, retention, payoff, preserve, avoid). ALWAYS read it before writing or adjusting ANY captions, text layers, or on-screen copy, and make your copy fit the template's format and voice — do NOT default to generic product/app ad copy. The format dictates the caption style: a text-message / DM / iMessage conversation template's captions must read like short back-and-forth chat messages between people (in-character, conversational), a 'story time' / talking-head template reads like first-person spoken narration, a listicle reads like punchy numbered items, a fake-news / headline template reads like a news chyron, etc. `preserve` usually names format cues that must stay (e.g. the messaging-bubble layout); `avoid` names what to keep out. When the template's format is a conversation, skit, or roleplay, keep the captions in that voice and only weave the product in the way that format allows (subtly, in-dialogue) rather than replacing the messages with feature bullets. If the brief's composition_context is thin or you are unsure what the video actually shows, call video_context (scene visual descriptions + transcript) to ground the format BEFORE writing captions.",
+        "TEMPLATE FORMAT — MATCH IT WHEN WRITING TEXT: the COMPOSITION BRIEF (stable template context in the system prompt) carries composition_context — WHAT THIS TEMPLATE IS: its format/genre and narrative arc (trend_tagline, hook, retention, payoff, preserve, avoid) plus emotional_punch (core_emotion, tone, arc, peak_moment, mechanism, humor, delivery, preserve) — the FEELING the format delivers and what makes it land. ALWAYS read it before writing or adjusting ANY captions, text layers, or on-screen copy, and make your copy fit the template's format and voice — do NOT default to generic product/app ad copy. emotional_punch is the part a remix most often flattens: if the format is a joke, keep emotional_punch.humor's mechanic (rebuild the SAME joke around the new subject, don't drop it for a feature bullet); match emotional_punch.tone and emotional_punch.delivery so intonation, comedic timing, and vibe survive; and never trade the peak_moment's payoff for a flat product plug. The format dictates the caption style: a text-message / DM / iMessage conversation template's captions must read like short back-and-forth chat messages between people (in-character, conversational), a 'story time' / talking-head template reads like first-person spoken narration, a listicle reads like punchy numbered items, a fake-news / headline template reads like a news chyron, etc. `preserve` usually names format cues that must stay (e.g. the messaging-bubble layout); `avoid` names what to keep out. When the template's format is a conversation, skit, or roleplay, keep the captions in that voice and only weave the product in the way that format allows (subtly, in-dialogue) rather than replacing the messages with feature bullets. If the brief's composition_context is thin or you are unsure what the video actually shows, call video_context (scene visual descriptions + transcript) to ground the format BEFORE writing captions.",
         "FILE DIRECTORY: the user's files live in ONE navigable directory with three canonical roots, each with nested subfolders and a copyable path per file: (1) /files — durable 'My Files' assets they keep and reuse (videos mp4/mov/webm, images png/jpg/jpeg/gif/webp/svg, audio mp3/wav/m4a/aac, documents pdf/md/txt/csv), vector-searchable via metadata notes; (2) /temp — scratch space auto-foldered by date (YYYY-MM-DD) and auto-deleted after 30 days; (3) /raws — the reusable clip / source-footage library, foldered by source (e.g. /raws/<source-slug>/). A file's canonical path looks like /raws/product-demos/clip.mp4 or /files/acme-skincare/logo.png. Use the browse_files tool to navigate, search, read, write, and reorganize it: action=list with path (e.g. path='/', '/raws', '/files/brand-assets') enumerates that folder's subfolders + files as canonical items (path, name, kind, view_url); action=search with a plain-language query finds files by MEANING across roots — it combines semantic vector match, substring, and absolute-path match (scope with path='/raws' for footage, '/files' for durable assets, '/' for everything; force one signal with mode=semantic|substring|path). Prefer search over paging list when the library is large or the user references an asset vaguely. When you omit path entirely, list/search now default to '/' (the whole directory) so /raws and /temp are never hidden — but pass path='/raws' to stay in footage. For /raws you can add content_type to filter by EXACT shot kind (talking_head, b_roll, product_shot, screen_recording, demo, reaction, interview, establishing, lifestyle, text_graphic; comma-separate to OR them) — this is an exact tag filter, distinct from the semantic query. For a big folder, list returns next_offset; pass it back as offset to page deeper (with limit up to 500). action=read with a file_id (copied from a prior list/search) fetches one file; action=write with file_name + content (or source_url) SAVES a text/media file into /files; action=annotate with file_id + notes attaches vector-embedded metadata to a /files entry; action=move with file_id + a target path (e.g. path='/raws/demos') reorganizes a raw between /raws folders; action=rename with path + new_name (+ file_id for a file) renames a /files or /temp file or folder in place — use it to keep the directory tidy (e.g. fix a character folder or file name). When the user references their own footage, brand assets, logos, music, a brief, a script, or raw clips ('use my product photo', 'the video I uploaded', 'my brand logo', 'that clip of the founder'), browse_files search or list first to find it rather than asking them to re-upload or paste a URL. For text files (md/txt/csv/srt/vtt/json), read returns the full text_content inline so you can read a brief or script directly. For images/video/audio/pdf, read returns only a durable view_url — use that URL as media: drop it into the timeline via editor_action add_layer/set_layer_media, or pass it into primitive routes (images/edit source_image_url, videos/generate input_references, videos/download). Never invent file ids, paths, or view URLs — always list or search to discover the real ones first.",
         "SAVING CONTEXT TO MY FILES: browse_files action=write persists durable, reusable context the user (and future chats/agents) can read back. write saves text files (md/txt/csv/json/srt/vtt) via content, and IMPORTS media into the library via source_url (a durable URL from a finished primitive job or existing asset) — use source_url to persist a generated asset the user will want again (a character sprite card, a recurring background, a logo variant) instead of leaving it stranded in a job result. Use write to capture the Getting Started artifacts as Markdown: a product About.md (basic offer/product context) or a deeper Interview.md, plus awareness-levels.md, persuasive-angles.md, and ad-hooks.md distilled from the matching brainstorm outputs. When a brainstorm job returns strategy the user wants to keep, offer to save it (or save it) as the corresponding .md so it is not lost when the chat ends. Namescope every write under the right product/offer folder (see MY FILES IS MULTI-OFFER) — e.g. folder_path='acme-skincare', file_name='About.md'. Pass notes on write (or annotate afterwards) for any asset worth finding again: notes describe what the file is, who/what it depicts, and when to use it, and they are vector-embedded so action=search finds the file by meaning in future sessions. Before overwriting an existing file of the same name in the same folder, confirm with the user (writing the same name replaces it).",
         "RECURRING CHARACTERS ARE FIRST-CLASS: mascots, spokespeople, avatars, and product characters that must look the same across videos live in a dedicated, browsable home — the /files/characters/ folder, one subfolder per character keyed by a URL-safe SLUG (lowercase, hyphenated), e.g. /files/characters/zara/. Each character is a TRIO of files in that folder: (1) <character_id>.json — the machine-readable MANIFEST, named after the character's id which is 'character_'+slug (e.g. slug 'zara' → id 'character_zara' → file character_zara.json; the id ALREADY carries the 'character_' prefix, so never double it to character_character_zara.json): { id:'character_<slug>', slug, name, role, appearance (face/build/hair/skin), wardrobe, palette (signature colors), voice (tone/accent/energy), do, dont, sprite_card_path:'/files/characters/<slug>/character_sprite_card.png', about_path:'/files/characters/<slug>/character_about.md', created_at }; (2) character_sprite_card.png — ONE reference-sheet image (full body front/side/back plus a face close-up on a neutral background); (3) character_about.md — the prose the .json summarizes, for richer wording when prompting. AWARENESS: when a user refers to 'our mascot', 'the same character', 'the fox', or names a character, FIRST browse_files list path='/files/characters' (or search) to see who already exists and read that character's manifest + about — never re-imagine a saved character from memory; that is how characters drift off-model. CONSISTENCY: on every generation featuring the character, pass the sprite card's view_url as the reference input (prompt_attachments for images/generate + images/edit, input_references for videos/generate and generate_layer) and lift wording from the manifest/about into the prompt.",