@mevdragon/vidfarm-devcli 0.20.1 → 0.20.2

package/SKILL.director.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm-director
-description: Use Vidfarm as a director. Browse/add inspiration videos, fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as a raw REST route and as a 1:1 `vidfarm-devcli` command.
+description: Use Vidfarm as a director. Browse/add inspiration videos, fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as raw REST; `vidfarm-devcli` wraps those routes and composes the file-backed scripting flows.
 ---
 
 # Vidfarm Director
@@ -136,6 +136,19 @@ Content-Type: application/json
 
 Returns the same fork metadata shape as `POST /api/v1/compositions` (201). devcli: `vidfarm clone <forkId> [--from current|default] [--version N] [--title …]`. In the in-editor AI chat this is the `editor_action` `fork_composition` action (`fork_from: current|default`).
 
+## Automate a template via REST
+
+Templates now have the same job-backed REST pattern as primitives, so a script can run them repeatably without the editor UI:
+
+```
+POST /api/v1/templates/:templateId/operations/:operationName
+Content-Type: application/json
+
+{ "tracer": "my-run", "payload": { ... }, "webhook_url": "https://..." }
+```
+
+The route returns `202` with a `job_id`, and you can poll the job with `GET /api/v1/user/me/jobs/:jobId` or the template-scoped `GET /api/v1/templates/:templateId/jobs/:jobId`. devcli wraps the same flow as `vidfarm template run <templateId> <operationName> --payload-file payload.json --wait`.
+
 ## Agentic editing: the three axes (SWAP ↔ REPLACE)
 
 Almost every editor session is a director taking a template / fork / project and **re-working** it, and a re-work only ever touches three independent axes — **SCENES** (the video/image clips carrying the visuals), **AUDIO** (narration/voiceover, music, SFX), and **TEXT** (captions, titles, overlays). On each axis the intent sits on a **SWAP ↔ REPLACE** spectrum, and the three axes in one request can sit at different points — decide each before you act:
@@ -439,7 +452,7 @@ Beyond the Ken Burns / transition / animated-caption presets, the copilot can ha
 
 ## Render (publish to MP4)
 
-Rendering publishes the fork's current working state to an MP4 using HyperFrames (cloud Lambda fan-out on the deployed host, or the free in-process renderer on a local `vidfarm serve` box). In the Trackpad Editor this is the **Render** button. The REST route is `/render`; the older `/export` path is kept as a deprecated alias for already-published devcli clients (treat "Render", "publish", `/render`, and `/export` as the same operation). The devcli exposes it as `vidfarm render <forkId> [--wait]`.
+Rendering publishes the fork's current working state to an MP4 using HyperFrames (cloud Lambda fan-out on the deployed host, or the free in-process renderer on a local `vidfarm serve` box). In the Trackpad Editor this is the **Render** button. The REST route is `/render`; the older `/export` path is kept as a deprecated alias for already-published devcli clients (treat "Render", "publish", `/render`, and `/export` as the same operation). The devcli exposes it as `vidfarm render <forkId> [--wait]`; scripted local dirs can use `vidfarm render <forkId> --dir ./work --wait`.
 
 ```
 POST /api/v1/compositions/:forkId/render
@@ -448,16 +461,18 @@ Content-Type: application/json
 { "title": "optional", "version": null, "tracer": "optional-trace-id", "html": "optional HTML to save to working state before rendering" }
 ```
 
-Returns 202 with `{ ok, renderId, status, progress, outputUrl, cost, title, version, ... }` where `version` is the snapshot version created for this publish. Failure modes: `402` if the fork owner is not on a paid plan, `409` while GhostCut subtitle removal is still `pending` (retry after `/remove-video-captions-poll` reports done/failed), `412` if the provider-key preflight fails. Poll:
+Returns 202 with `{ ok, renderId, status, progress, expectedOutputPublicUrl, outputUrl, cost, title, version, ... }` where `expectedOutputPublicUrl` is the deterministic public MP4 URL and `version` is the snapshot version created for this publish. Failure modes: `402` if the fork owner is not on a paid plan, `409` while GhostCut subtitle removal is still `pending` (retry after `/remove-video-captions-poll` reports done/failed), `412` if the provider-key preflight fails. Poll:
 
 ```
 GET /api/v1/compositions/:forkId/renders/:renderId
 ```
 
-Response includes `{ ok, renderId, status: "RUNNING" | "SUCCEEDED" | "FAILED", progress, framesRendered, totalFrames, cost, outputUrl, outputS3Uri, errors }` (`progress` is 0..1). On success, `outputUrl` is the durable MP4 URL.
+Response includes `{ ok, renderId, status: "RUNNING" | "SUCCEEDED" | "FAILED", progress, framesRendered, totalFrames, cost, expectedOutputPublicUrl, outputUrl, outputS3Uri, errors }` (`progress` is 0..1). On success, `expectedOutputPublicUrl` is the durable public MP4 URL and `outputUrl` remains the completion-time field.
 
 Every publish creates an immutable version snapshot at `versions/<N>/composition.html` and `versions/<N>/composition.json`.
 
+The Web UI **Render** button and devcli render both use this same endpoint. The fast `202` response includes the deterministic `expectedOutputPublicUrl` so a caller can store or pass along the final public S3 URL before the render has completed, then poll by `renderId` until `status` settles.
+
 ## Approve a finished post
 
 A render produces a bare MP4 URL. **Approving** wraps that MP4 (plus caption, title, pinned comment, and any carousel slides) into a shareable preview page — the phone-mockup page a human opens to review and copy the post.
@@ -600,16 +615,73 @@ For agents that operate Vidfarm headlessly, the typical loop is:
 3. `PATCH /api/v1/compositions/:forkId/composition.json` → update metadata
 4. `POST /api/v1/compositions/:forkId/render { tracer }` → render
 5. Poll `GET /api/v1/compositions/:forkId/renders/:renderId` until `SUCCEEDED`
-6. Use `outputUrl` in the next stage
+6. Use `expectedOutputPublicUrl` in the next stage when you need the stable public URL immediately; otherwise fall back to `outputUrl` after completion
 
 Send a stable `tracer` on export so retries are traceable and filterable in job history — but note that submission is **not idempotent**: every POST creates a new job (and a new charge) even with the same tracer. Do not blind-retry expensive submissions; check the render status first.
 
+## Scripting mode
+
+**Scripting mode** is the recommended posture for repeatable template automation. Use it when a director wants to take a template they like, agree on a base fork, and then drive bulk or one-off edits entirely through REST or `vidfarm api` from a script, Lambda, or local machine.
+
+Contract:
+
+1. Pick the template once, then fork once and treat the resulting `forkId` as the stable base.
+2. Read the working state with `GET /api/v1/compositions/:forkId/composition.html` and `GET /api/v1/compositions/:forkId/composition.json`.
+3. Modify the composition deterministically in your script.
+4. Write back with `PUT /api/v1/compositions/:forkId/composition.html` and `PATCH /api/v1/compositions/:forkId/composition.json`.
+5. Snapshot with `POST /api/v1/compositions/:forkId/versions` before or after render, depending on whether you want the version to capture the exact render input or the post-render state.
+6. Render with `POST /api/v1/compositions/:forkId/render`, choosing local or cloud based on the host and runtime.
+
+Devcli shortcut:
+
+```bash
+vidfarm render "$FORK_ID" --dir ./work --tracer "batch-2026-07-09-row-42" --wait
+```
+
+That command validates `./work/composition.html`, shallow-patches `./work/composition.json` if present, then submits the same `POST /api/v1/compositions/:forkId/render` call used by the Web UI. `--dir` may also point directly at `composition.html`.
+
+Best practices:
+
+- Prefer one canonical base fork per automation run, then branch from that fork if you need variants.
+- Treat `composition.json` as a shallow merged metadata document. The server merges the posted JSON object into the existing object; it is not RFC 6902 JSON Patch.
+- Keep edits idempotent in your script. Re-run the script against the same fork only if it computes the same desired state.
+- Use a stable `tracer` on render jobs so logs and job history stay searchable.
+- Use the same REST sequence in Lambda, CI, or a local shell. The only thing that changes is the host and auth.
+
+Canonical shell shape:
+
+```bash
+BASE_TEMPLATE_ID="template_..."
+FORK_ID="$(vidfarm api POST /api/v1/compositions --data "{\"template_id\":\"${BASE_TEMPLATE_ID}\"}" --json | jq -r '.fork_id')"
+
+vidfarm api GET "/api/v1/compositions/${FORK_ID}/composition.html" --raw > /tmp/composition.html
+vidfarm api GET "/api/v1/compositions/${FORK_ID}/composition.json" --raw > /tmp/composition.json
+
+# edit /tmp/composition.html and /tmp/composition.json in your script
+
+vidfarm api PUT "/api/v1/compositions/${FORK_ID}/composition.html" --body-file /tmp/composition.html --content-type "text/html; charset=utf-8"
+vidfarm api PATCH "/api/v1/compositions/${FORK_ID}/composition.json" --data-file /tmp/composition.json
+vidfarm api POST "/api/v1/compositions/${FORK_ID}/versions" --data '{"message":"scripting mode snapshot"}'
+vidfarm api POST "/api/v1/compositions/${FORK_ID}/render" --data '{"tracer":"scripting-mode"}'
+```
+
+If you need many variants, keep the base fork fixed and fan out by cloning that fork or by reapplying the same edit function to multiple fork ids. Use the raw REST routes directly when you want maximum control; use `vidfarm-devcli` when you want auth, polling, and file helpers without writing the plumbing yourself.
+
 ## `vidfarm-devcli` — full command surface
 
-`@mevdragon/vidfarm-devcli` wraps the **entire director REST flow** as CLI commands. It is a thin shell over the REST API, not a second implementation: **every named command maps 1:1 to exactly one REST route**, and all it adds is fork auto-resolution, the `vidfarm-api-key` header, prod frontend links in the output, render-poll waiting, and the multi-step upload/download flows. Auth via `--api-key <key>` or `VIDFARM_API_KEY`.
+`@mevdragon/vidfarm-devcli` wraps the **entire director REST flow** as CLI commands. It is a thin shell over the REST API, not a second implementation: most named commands map 1:1 to one REST route, and the file-backed commands compose the documented routes for upload/download + render-polling. Auth via `--api-key <key>` or `VIDFARM_API_KEY`.
 
 **Raw REST vs devcli — your choice.** If you want full control, call the REST API directly (or use the raw passthrough `vidfarm api <METHOD> <path> [--data <json>] [--query k=v]`). If you want ergonomics + openable frontend URLs, use the named commands. They are interchangeable — pick per call.
 
+**Scripting mode recommendation.** For automation, prefer:
+
+- `vidfarm api` for the actual REST calls
+- `--data-file` for file-backed payloads
+- a single pinned base fork id per template family
+- `POST /api/v1/compositions/:forkId/versions` as the versioning boundary
+- `POST /api/v1/compositions/:forkId/render` with a stable `tracer`, or `vidfarm render <forkId> --dir ./work --wait` for the same composed flow
+- `render_target: "cloud"` when you want cloud handoff from a local `vidfarm serve` box, or the default local renderer when you want free in-process output
+
 | Command | REST route | Flow step |
 |---|---|---|
 | `vidfarm discover [query]` | `GET /discover/feed[?q=]` | browse/search templates |
@@ -636,7 +708,7 @@ Send a stable `tracer` on export so retries are traceable and filterable in job
 | `vidfarm remove-video-captions <forkId>` (alias: `ghostcut`) | `GET .../compositions/:forkId/remove-video-captions` | subtitle-removal status |
 | `vidfarm snapshot <forkId>` | `POST .../compositions/:forkId/versions` | save composition fork version |
 | `vidfarm versions <forkId>` | `GET .../compositions/:forkId/versions` | list versions |
-| `vidfarm render <forkId> [--wait]` | `POST .../compositions/:forkId/render` | render video to MP4 |
+| `vidfarm render <forkId> [--dir <dir\|composition.html>] [--wait] [--target local\|cloud]` | `PUT/PATCH working files, then POST .../compositions/:forkId/render` | script-friendly render to MP4; no `--dir` uses the fork's current working state |
 | `vidfarm render-status <forkId> <renderId>` | `GET .../compositions/:forkId/renders/:renderId` | poll a render |
 | `vidfarm visibility <forkId> <private\|public>` | `PATCH .../compositions/:forkId/visibility` | set visibility |
 | `vidfarm clone <forkId>` | `POST .../compositions/:forkId/clone` | clone a fork |

package/SKILL.platform.md

@@ -205,8 +205,8 @@ Publish flow:
 3. API resolves the caller's provider keys (preflight check for required models)
 4. API creates a `job` record and invokes the `hyperframes_render` primitive Lambda
 5. The renderer runs HyperFrames: on the deployed host it stages the composition and dispatches to the shared HyperFrames render state machine (chunked Lambda fan-out); on a local `vidfarm serve` box with no cloud stack it renders in-process (headless Chromium → ffmpeg) for free. See `HyperframesService` in `src/services/hyperframes.ts`.
-6. On success, the primitive returns `{ primary_file_url: "s3://.../output.mp4" }`, the API creates a `ForkVersionRecord` with `reason: "publish"`, writes the snapshot to `versions/<N>/`, and updates the fork's `latestVersion` and `currentRenderJobId`
-7. Client polls `GET /api/v1/compositions/:forkId/renders/:renderId` for `{ status: "RUNNING" | "SUCCEEDED" | "FAILED", progress, outputUrl, cost }` (see `adaptJobToPublishStatus` in `src/app.ts`)
+6. On success, the primitive returns `{ primary_file_url: "s3://.../output.mp4" }`, the API creates a `ForkVersionRecord` with `reason: "publish"`, writes the snapshot to `versions/<N>/`, updates the fork's `latestVersion` and `currentRenderJobId`, and now also exposes the deterministic public artifact URL immediately as `expected_output_public_url`
+7. Client polls `GET /api/v1/compositions/:forkId/renders/:renderId` for `{ status: "RUNNING" | "SUCCEEDED" | "FAILED", progress, expectedOutputPublicUrl, outputUrl, cost }` (see `adaptJobToPublishStatus` in `src/app.ts`); `expectedOutputPublicUrl` is the stable public S3 URL, while `outputUrl` remains the completion-time field
 
 The HyperFrames render state machine is **shared across all templates and forks** — it's an infrastructure primitive, not a per-template deployment. Its ARN/bucket are passed to the Vidfarm stack as env vars (`HYPERFRAMES_RENDER_*`). Remotion has been fully removed.
 

package/dist/src/app.js

@@ -24,6 +24,7 @@ import { writeForkManifest } from "./services/fork-manifest.js";
 import { renderHelpPage } from "./help-page.js";
 import { renderHomepage } from "./homepage.js";
 import { renderLandingPage } from "./landing-page.js";
+import { createTemplateJobContext } from "./context.js";
 import { renderReskinIndex } from "./reskin/index-page.js";
 import { renderReskinSettings } from "./reskin/settings-page.js";
 import { renderReskinLibrary } from "./reskin/library-page.js";
@@ -7805,7 +7806,7 @@ async function publishCompositionToRenderer(input) {
         fps: 30,
         chunk_size: 240,
         max_parallel_chunks: 8,
-        output_key: `renders/vidfarm/${slugId}/${Date.now().toString(36)}/output.mp4`,
+        output_key: "output.mp4",
         project_files: projectFiles,
         composition_data: compositionData ?? undefined
     });
@@ -7894,6 +7895,48 @@ async function runPrimitiveJobInProcess(jobId) {
         throw error;
     }
 }
+async function runTemplateJobInProcess(jobId) {
+    const job = await jobs.getJobAsync(jobId);
+    if (!job)
+        throw new Error(`Job not found: ${jobId}`);
+    const failContract = async (message) => {
+        await jobs.failJob(job.id, { message, type: "local_runner_contract_error" });
+        throw new Error(message);
+    };
+    const customer = await serverlessRecords.getCustomerById(job.customerId);
+    if (!customer)
+        return failContract(`Customer not found: ${job.customerId}`);
+    const template = await templateRegistry.getExecutable(job.templateId);
+    if (!template)
+        return failContract(`Template not found: ${job.templateId}`);
+    const workflow = template.jobs[job.workflowName];
+    if (!workflow)
+        return failContract(`Template workflow not found: ${job.workflowName}`);
+    const workerId = createId("local_worker");
+    try {
+        await jobs.markRunning(job.id);
+        const ctx = createTemplateJobContext({
+            customer,
+            job,
+            template,
+            workerId,
+            storage,
+            jobs,
+            billing,
+            providers,
+            hyperframes
+        });
+        const result = await workflow(ctx, job.payload);
+        await jobs.succeedJob(job.id, result.output ?? {}, result.progress ?? 1);
+    }
+    catch (error) {
+        await jobs.failJob(job.id, {
+            message: error instanceof Error ? error.message : "Local template job failed",
+            type: "local_render_failed"
+        });
+        throw error;
+    }
+}
 function mapJobStatusToPublishPhase(status) {
     const normalized = String(status ?? "").toLowerCase();
     if (normalized === "completed" || normalized === "succeeded")
@@ -7977,6 +8020,7 @@ function adaptJobToPublishStatus(job, fallbackTitle) {
         cost,
         outputS3Uri: readNonEmptyString(asRecord(result.output)?.s3_uri) ?? readNonEmptyString(renderBlock.output_s3_uri),
         outputUrl,
+        expectedOutputPublicUrl: readNonEmptyString(record.expected_output_public_url) ?? expectedHyperframesRenderOutputPublicUrl(job),
         title: readNonEmptyString(asRecord(record.payload)?.title) ?? fallbackTitle,
         fatalErrorEncountered: Boolean(publishErrorMessage),
         errors: publishErrorMessage ? [{ error: publishErrorMessage }] : []
@@ -16449,8 +16493,10 @@ async function serializeJob(job) {
         customerId: job.customerId,
         templateId: job.templateId
     });
+    const expectedOutputPublicUrl = expectedHyperframesRenderOutputPublicUrl(job);
     return {
         job_id: job.id,
+        customer_id: job.customerId,
         template_id: job.templateId,
         operation_name: job.operationName,
         workflow_name: job.workflowName,
@@ -16466,6 +16512,7 @@ async function serializeJob(job) {
             event_count: jobBilling.eventCount,
             consumed_usd: jobBilling.totalChargeUsd
         },
+        expected_output_public_url: expectedOutputPublicUrl,
         parent_job_id: job.parentJobId,
         created_at: job.createdAt,
         updated_at: job.updatedAt,
@@ -16485,6 +16532,19 @@ function serializeArtifact(artifact) {
         created_at: artifact.createdAt
     };
 }
+function expectedHyperframesRenderOutputPublicUrl(job) {
+    const record = asRecord(job);
+    if (!record)
+        return null;
+    const templateId = readNonEmptyString(record.templateId) ?? readNonEmptyString(record.template_id);
+    const customerId = readNonEmptyString(record.customerId) ?? readNonEmptyString(record.customer_id);
+    const jobId = readNonEmptyString(record.id) ?? readNonEmptyString(record.job_id);
+    if (templateId !== "primitive:hyperframes_render" || !customerId || !jobId)
+        return null;
+    const outputKey = readNonEmptyString(asRecord(record.payload)?.output_key) ?? "output.mp4";
+    const storageKey = storage.primitiveJobKey(templateId, customerId, jobId, outputKey);
+    return storage.getPublicUrl(storageKey);
+}
 async function buildJobDebugBundle(input) {
     const job = input.job;
     const startTime = input.startTime ?? offsetIso(job.createdAt, -60_000);
@@ -17020,7 +17080,7 @@ async function deriveProviderHint(input) {
     ];
     return useHintIfAvailable(configCandidates.find(isProviderType));
 }
-async function listPrimitiveJobsForCustomer(input) {
+async function listJobsForCustomerByTemplateId(input) {
     const target = clampPageLimit(input.limit, 100) + 1;
     const collected = [];
     let cursor = input.cursor ?? null;
@@ -17037,7 +17097,8 @@ async function listPrimitiveJobsForCustomer(input) {
             break;
         }
         for (const job of batch) {
-            if (job.templateId.startsWith("primitive:") && (!input.primitiveId || job.templateId === input.primitiveId)) {
+            if ((!input.templateId || job.templateId === input.templateId) &&
+                (!input.templateIdPrefix || job.templateId.startsWith(input.templateIdPrefix))) {
                 collected.push(job);
                 if (collected.length >= target) {
                     break;
@@ -17058,6 +17119,16 @@ async function listPrimitiveJobsForCustomer(input) {
     }
     return collected;
 }
+async function getJobForCustomerByTemplateId(input) {
+    const job = await jobs.getJobAsync(input.jobId);
+    if (!job || job.customerId !== input.customerId) {
+        return null;
+    }
+    if (input.templateId && job.templateId !== input.templateId) {
+        return null;
+    }
+    return job;
+}
 async function createPrimitiveJob(c, input) {
     const customer = requireCustomer(c);
     const primitive = primitiveRegistry.get(input.primitiveId);
@@ -17145,6 +17216,90 @@ async function createPrimitiveJob(c, input) {
         operation_name: input.operationName
     }, 202);
 }
+async function createTemplateJob(c, input) {
+    const customer = requireCustomer(c);
+    const template = await templateRegistry.getExecutable(input.templateId);
+    if (!template) {
+        return c.json({ error: "Template not found" }, 404);
+    }
+    const operation = template.operations[input.operationName];
+    if (!operation) {
+        return c.json({ error: "Template operation not found" }, 404);
+    }
+    let body;
+    let payload;
+    try {
+        body = primitiveEnvelopeSchema.parse(await c.req.json());
+        payload = operation.inputSchema.parse(body.payload);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            return c.json({
+                error: "Invalid template request.",
+                issues: error.issues
+            }, 400);
+        }
+        if (isJsonBodyParseError(error)) {
+            return c.json({
+                error: "Invalid template request.",
+                detail: "Request body must be valid JSON with top-level tracer and payload fields."
+            }, 400);
+        }
+        throw error;
+    }
+    const providerPreflight = await preflightAiProviderKeys({
+        customerId: customer.id,
+        templateId: template.id,
+        operationName: input.operationName,
+        operationHint: operation.providerHint,
+        payload
+    });
+    if (providerPreflight) {
+        return c.json(providerPreflight, 412);
+    }
+    let job;
+    try {
+        await assertWalletCanQueueJobs(customer.id);
+        job = await jobs.createRootJob({
+            templateId: template.id,
+            operationName: input.operationName,
+            workflowName: operation.workflow,
+            tracer: body.tracer,
+            payload,
+            webhookUrl: body.webhook_url,
+            customer,
+            providerHint: await deriveProviderHint({
+                customerId: customer.id,
+                templateId: template.id,
+                operationName: input.operationName,
+                operationHint: operation.providerHint,
+                payload
+            })
+        });
+    }
+    catch (error) {
+        if (error instanceof InsufficientWalletFundsError) {
+            return insufficientFundsResponse(c, error);
+        }
+        if (error instanceof ActiveJobLimitExceededError) {
+            return activeJobLimitExceededResponse(c, error);
+        }
+        throw error;
+    }
+    if (!config.VIDFARM_JOB_STATE_MACHINE_ARN) {
+        void runTemplateJobInProcess(job.id).catch((error) => {
+            console.error("local template job failed", job.id, error instanceof Error ? error.message : error);
+        });
+    }
+    return c.json({
+        job_id: job.id,
+        tracer: job.tracer,
+        status: job.status,
+        template_id: template.id,
+        template_type: "template",
+        operation_name: input.operationName
+    }, 202);
+}
 function resolvePrimitiveRouteTarget(primitiveParam) {
     const normalized = primitiveParam.trim();
     if (!normalized) {
@@ -17185,6 +17340,12 @@ app.post(`${PRIMITIVES_PREFIX}/:primitiveKind/operations/:operationName`, async
         operationName: c.req.param("operationName")
     });
 });
+app.post(`${TEMPLATES_PREFIX}/:templateId/operations/:operationName`, async (c) => {
+    return createTemplateJob(c, {
+        templateId: c.req.param("templateId"),
+        operationName: c.req.param("operationName")
+    });
+});
 app.get(`${PRIMITIVES_PREFIX}/jobs`, async (c) => {
     const customer = requireCustomer(c);
     const query = listJobsQuerySchema.parse({
@@ -17195,8 +17356,9 @@ app.get(`${PRIMITIVES_PREFIX}/jobs`, async (c) => {
         limit: c.req.query("limit")
     });
     const limit = clampPageLimit(query.limit, 100);
-    const listedJobs = await listPrimitiveJobsForCustomer({
+    const listedJobs = await listJobsForCustomerByTemplateId({
         customerId: customer.id,
+        templateIdPrefix: "primitive:",
         tracer: query.tracer,
         startTime: query.start_time,
         endTime: query.end_time,
@@ -17206,9 +17368,40 @@ app.get(`${PRIMITIVES_PREFIX}/jobs`, async (c) => {
     const page = paginateDescendingByCreatedAt(listedJobs, limit);
     return c.json({ primitive_jobs: await Promise.all(page.items.map(serializePrimitiveJob)), next_cursor: page.nextCursor });
 });
+app.get(`${TEMPLATES_PREFIX}/:templateId/jobs`, async (c) => {
+    const customer = requireCustomer(c);
+    const template = await templateRegistry.getExecutable(c.req.param("templateId"));
+    if (!template) {
+        return c.json({ error: "Template not found" }, 404);
+    }
+    const query = listJobsQuerySchema.parse({
+        tracer: c.req.query("tracer"),
+        start_time: c.req.query("start_time"),
+        end_time: c.req.query("end_time"),
+        cursor: c.req.query("cursor"),
+        limit: c.req.query("limit")
+    });
+    const limit = clampPageLimit(query.limit, 100);
+    const listedJobs = await listJobsForCustomerByTemplateId({
+        customerId: customer.id,
+        templateId: template.id,
+        tracer: query.tracer,
+        startTime: query.start_time,
+        endTime: query.end_time,
+        limit,
+        cursor: parseCreatedAtIdCursor(query.cursor)
+    });
+    const page = paginateDescendingByCreatedAt(listedJobs, limit);
+    return c.json({
+        template_id: template.id,
+        template_type: "template",
+        jobs: await Promise.all(page.items.map(serializeJob)),
+        next_cursor: page.nextCursor
+    });
+});
 app.get(`${PRIMITIVES_PREFIX}/jobs/:jobId`, async (c) => {
     const customer = requireCustomer(c);
-    const job = await getPrimitiveJobForCustomer({
+    const job = await getJobForCustomerByTemplateId({
         jobId: c.req.param("jobId"),
         customerId: customer.id
     });
@@ -17217,9 +17410,25 @@ app.get(`${PRIMITIVES_PREFIX}/jobs/:jobId`, async (c) => {
     }
     return c.json(await serializePrimitiveJob(job));
 });
+app.get(`${TEMPLATES_PREFIX}/:templateId/jobs/:jobId`, async (c) => {
+    const customer = requireCustomer(c);
+    const template = await templateRegistry.getExecutable(c.req.param("templateId"));
+    if (!template) {
+        return c.json({ error: "Template not found" }, 404);
+    }
+    const job = await getJobForCustomerByTemplateId({
+        jobId: c.req.param("jobId"),
+        customerId: customer.id,
+        templateId: template.id
+    });
+    if (!job) {
+        return c.json({ error: "Template job not found" }, 404);
+    }
+    return c.json(await serializeJob(job));
+});
 app.get(`${PRIMITIVES_PREFIX}/jobs/:jobId/artifacts`, async (c) => {
     const customer = requireCustomer(c);
-    const job = await getPrimitiveJobForCustomer({
+    const job = await getJobForCustomerByTemplateId({
         jobId: c.req.param("jobId"),
         customerId: customer.id
     });
@@ -17242,9 +17451,40 @@ app.get(`${PRIMITIVES_PREFIX}/jobs/:jobId/artifacts`, async (c) => {
         next_cursor: page.nextCursor
     });
 });
+app.get(`${TEMPLATES_PREFIX}/:templateId/jobs/:jobId/artifacts`, async (c) => {
+    const customer = requireCustomer(c);
+    const template = await templateRegistry.getExecutable(c.req.param("templateId"));
+    if (!template) {
+        return c.json({ error: "Template not found" }, 404);
+    }
+    const job = await getJobForCustomerByTemplateId({
+        jobId: c.req.param("jobId"),
+        customerId: customer.id,
+        templateId: template.id
+    });
+    if (!job) {
+        return c.json({ error: "Template job not found" }, 404);
+    }
+    const limit = clampPageLimit(Number(c.req.query("limit") || "100"), 100);
+    const page = await listArtifactsForJobPage({
+        jobId: job.id,
+        customerId: customer.id,
+        templateId: job.templateId,
+        limit,
+        cursor: parseCreatedAtIdCursor(c.req.query("cursor"))
+    });
+    return c.json({
+        job_id: job.id,
+        tracer: job.tracer,
+        template_id: job.templateId,
+        template_type: "template",
+        artifacts: page.items.map(serializeArtifact),
+        next_cursor: page.nextCursor
+    });
+});
 app.get(`${PRIMITIVES_PREFIX}/jobs/:jobId/logs`, async (c) => {
     const customer = requireCustomer(c);
-    const job = await getPrimitiveJobForCustomer({
+    const job = await getJobForCustomerByTemplateId({
         jobId: c.req.param("jobId"),
         customerId: customer.id
     });
@@ -17268,9 +17508,40 @@ app.get(`${PRIMITIVES_PREFIX}/jobs/:jobId/logs`, async (c) => {
     const page = paginateDescendingByCreatedAt(logs, limit);
     return c.json({ job_id: job.id, tracer: job.tracer, logs: page.items, next_cursor: page.nextCursor });
 });
+app.get(`${TEMPLATES_PREFIX}/:templateId/jobs/:jobId/logs`, async (c) => {
+    const customer = requireCustomer(c);
+    const template = await templateRegistry.getExecutable(c.req.param("templateId"));
+    if (!template) {
+        return c.json({ error: "Template not found" }, 404);
+    }
+    const job = await getJobForCustomerByTemplateId({
+        jobId: c.req.param("jobId"),
+        customerId: customer.id,
+        templateId: template.id
+    });
+    if (!job) {
+        return c.json({ error: "Template job not found" }, 404);
+    }
+    const query = listJobsQuerySchema.parse({
+        start_time: c.req.query("start_time"),
+        end_time: c.req.query("end_time"),
+        cursor: c.req.query("cursor"),
+        limit: c.req.query("limit")
+    });
+    const limit = clampPageLimit(query.limit, 100);
+    const logs = await jobs.listLogs({
+        jobId: job.id,
+        startTime: query.start_time,
+        endTime: query.end_time,
+        limit: limit + 1,
+        cursor: parseCreatedAtIdCursor(query.cursor)
+    });
+    const page = paginateDescendingByCreatedAt(logs, limit);
+    return c.json({ job_id: job.id, tracer: job.tracer, logs: page.items, next_cursor: page.nextCursor });
+});
 app.post(`${PRIMITIVES_PREFIX}/jobs/:jobId/cancel`, async (c) => {
     const customer = requireCustomer(c);
-    const job = await getPrimitiveJobForCustomer({
+    const job = await getJobForCustomerByTemplateId({
         jobId: c.req.param("jobId"),
         customerId: customer.id
     });
@@ -17280,6 +17551,23 @@ app.post(`${PRIMITIVES_PREFIX}/jobs/:jobId/cancel`, async (c) => {
     await jobs.cancelJobAsync(job.id);
     return c.json({ ok: true, job_id: job.id, status: "cancelled" });
 });
+app.post(`${TEMPLATES_PREFIX}/:templateId/jobs/:jobId/cancel`, async (c) => {
+    const customer = requireCustomer(c);
+    const template = await templateRegistry.getExecutable(c.req.param("templateId"));
+    if (!template) {
+        return c.json({ error: "Template not found" }, 404);
+    }
+    const job = await getJobForCustomerByTemplateId({
+        jobId: c.req.param("jobId"),
+        customerId: customer.id,
+        templateId: template.id
+    });
+    if (!job) {
+        return c.json({ error: "Template job not found" }, 404);
+    }
+    await jobs.cancelJobAsync(job.id);
+    return c.json({ ok: true, job_id: job.id, status: "cancelled" });
+});
 app.get(`${PRIMITIVES_PREFIX}/:primitiveKind/jobs`, async (c) => {
     const customer = requireCustomer(c);
     const primitive = resolvePrimitiveRouteTarget(c.req.param("primitiveKind"));
@@ -17294,9 +17582,9 @@ app.get(`${PRIMITIVES_PREFIX}/:primitiveKind/jobs`, async (c) => {
         limit: c.req.query("limit")
     });
     const limit = clampPageLimit(query.limit, 100);
-    const listedJobs = await listPrimitiveJobsForCustomer({
+    const listedJobs = await listJobsForCustomerByTemplateId({
         customerId: customer.id,
-        primitiveId: primitive.id,
+        templateId: primitive.id,
         tracer: query.tracer,
         startTime: query.start_time,
         endTime: query.end_time,
@@ -17317,10 +17605,10 @@ app.get(`${PRIMITIVES_PREFIX}/:primitiveKind/jobs/:jobId`, async (c) => {
     if (!primitive) {
         return c.json({ error: "Primitive not found" }, 404);
     }
-    const job = await getPrimitiveJobForCustomer({
+    const job = await getJobForCustomerByTemplateId({
         jobId: c.req.param("jobId"),
         customerId: customer.id,
-        primitiveId: primitive.id
+        templateId: primitive.id
     });
     if (!job) {
         return c.json({ error: "Primitive job not found" }, 404);
@@ -17333,10 +17621,10 @@ app.get(`${PRIMITIVES_PREFIX}/:primitiveKind/jobs/:jobId/artifacts`, async (c) =
     if (!primitive) {
         return c.json({ error: "Primitive not found" }, 404);
     }
-    const job = await getPrimitiveJobForCustomer({
+    const job = await getJobForCustomerByTemplateId({
         jobId: c.req.param("jobId"),
         customerId: customer.id,
-        primitiveId: primitive.id
+        templateId: primitive.id
     });
     if (!job) {
         return c.json({ error: "Primitive job not found" }, 404);
@@ -17364,10 +17652,10 @@ app.get(`${PRIMITIVES_PREFIX}/:primitiveKind/jobs/:jobId/logs`, async (c) => {
     if (!primitive) {
         return c.json({ error: "Primitive not found" }, 404);
     }
-    const job = await getPrimitiveJobForCustomer({
+    const job = await getJobForCustomerByTemplateId({
         jobId: c.req.param("jobId"),
         customerId: customer.id,
-        primitiveId: primitive.id
+        templateId: primitive.id
     });
     if (!job) {
         return c.json({ error: "Primitive job not found" }, 404);
@@ -17402,10 +17690,10 @@ app.post(`${PRIMITIVES_PREFIX}/:primitiveKind/jobs/:jobId/cancel`, async (c) =>
     if (!primitive) {
         return c.json({ error: "Primitive not found" }, 404);
     }
-    const job = await getPrimitiveJobForCustomer({
+    const job = await getJobForCustomerByTemplateId({
         jobId: c.req.param("jobId"),
         customerId: customer.id,
-        primitiveId: primitive.id
+        templateId: primitive.id
     });
     if (!job) {
         return c.json({ error: "Primitive job not found" }, 404);

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();
@@ -1631,7 +1654,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 +1670,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 +1689,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 +2328,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 +2369,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 +2388,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 +2443,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/services/hyperframes.js

@@ -469,7 +469,7 @@ export class HyperframesService {
         });
         const timestamp = Date.now().toString(36);
         const renderId = `vfimg-${metadata.compositionId.slice(0, 40)}-${timestamp}-${randomUUID().slice(0, 8)}`;
-        const framesDir = path.join(config.VIDFARM_DATA_DIR, "hyperframes-projects", `${renderId}-frames`);
+        const framesDir = path.join(config.VIDFARM_DATA_DIR, "vidfarm-projects", `${renderId}-frames`);
         await mkdir(framesDir, { recursive: true });
         devLog("hyperframes.render_still.start", {
             composition_id: metadata.compositionId,
@@ -3113,7 +3113,7 @@ async function resolveHyperframesStack() {
     return value;
 }
 async function stageProject(input) {
-    const root = path.join(config.VIDFARM_DATA_DIR, "hyperframes-projects");
+    const root = path.join(config.VIDFARM_DATA_DIR, "vidfarm-projects");
     const projectDir = path.join(root, `${Date.now().toString(36)}-${safeIdentifier(input.compositionId)}-${randomUUID().slice(0, 8)}`);
     await rm(projectDir, { recursive: true, force: true });
     await mkdir(projectDir, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {