@mevdragon/vidfarm-devcli 0.4.1 → 0.5.0

package/README.md

@@ -35,19 +35,19 @@ npm run cdk:deploy:prod-serverless
 
 Never call bare `cdk deploy` — the npm scripts load the correct `.env.<stage>` and select the right stack.
 
-## Local editor: `@mevdragon/vidfarm-devcli`
+## Local editor: `vidfarm serve`
 
-Pair a local composition directory with the hosted Trackpad Editor so an AI agent (Claude Code, Codex, etc.) or a human can edit `composition.html` on disk and see live preview in the browser.
+Boot the **full** Vidfarm editor locally — single origin, disk-backed records + storage — so an AI agent (Claude Code, Codex, etc.) edits composition files on disk while a human finishes in the browser, both sharing one source of truth with live sync. Render stays on the cloud.
 
 ```bash
-npx -y @mevdragon/vidfarm-devcli <template_id>
-# → downloads the current composition into .vidfarm/<template_id>/
-# → starts dev-serve on localhost:4321
-# → prints an https://vidfarm.cc/editor/<template_id>?fork=…&dev=… URL to open
+npx -y @mevdragon/vidfarm-devcli serve
+# → boots the full backend on http://localhost:3000 (records + storage on disk)
+# → auto-provisions a local user and opens the editor, pre-authed
+# → agents edit files under ./.vidfarm-local/storage — the browser live-morphs on save
 ```
 
-Flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or `VIDFARM_API_KEY`), `--share`, `--refetch`. Use `dev-serve` as an explicit subcommand to skip the fetch step and just serve an existing directory.
+Everything runs locally (`RECORDS_DRIVER=local`, `STORAGE_DRIVER=local`); no AWS is touched except **render**, which submits to the deployed cloud renderer when `VIDFARM_JOB_STATE_MACHINE_ARN` + `HYPERFRAMES_RENDER_*` are set (copy them from `.env.staging`). Multiple forks can be edited at once.
 
-Beyond the local editor loop, the devcli also wraps the **entire director REST flow** as 1:1 commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render`, `approve`, `schedule`, `posts`, `upload`/`download`, plus a raw `vidfarm api <METHOD> <path>` passthrough. Each maps to exactly one REST route and prints the prod frontend URL to open. Run `vidfarm --help` for the full surface, or see `SKILL.director.md` § "`vidfarm-devcli` — full command surface".
+Flags: `--port` (default 3000), `--dir` (default `./.vidfarm-local`), `--key` (bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork <id>`, `--no-open`. `vidfarm <template_id>` is an alias for `serve <template_id>`.
 
-See `SKILL.platform.md` § "Local editor dev loop" for the request-rewrite / SSE reload flow.
+Beyond the local editor, the devcli also wraps the **entire director REST flow** as 1:1 commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render`, `approve`, `schedule`, `posts`, `upload`/`download`, plus a raw `vidfarm api <METHOD> <path>` passthrough. Each maps to exactly one REST route and prints the prod frontend URL to open. Run `vidfarm --help` for the full surface, or see `SKILL.director.md` § "`vidfarm-devcli` — full command surface".

package/SKILL.director.md

@@ -166,7 +166,7 @@ Response:
 
 If `ghostcut_pending: true`, poll `POST /api/v1/compositions/:forkId/ghostcut-poll` until status transitions to `done` or `failed`.
 
-Read-only state (does **not** advance the job or bill): `GET /api/v1/compositions/:forkId/ghostcut`. Returns `{ status, task_id, original_source_url, mirrored_url, submitted_at_ms, completed_at_ms, failure_reason }`. Use this when you want to know both video URLs without triggering another poll — the AI copilot uses it to pick between the raw upload and the caption-free mirror before feeding a video into a primitive route (image extract, dedupe, trim, ai video edit, etc.). Prefer `mirrored_url` when `status === "done"` and the downstream call should be caption-free; prefer `original_source_url` when the user explicitly wants the raw upload or when `status !== "done"`.
+Read-only state (does **not** advance the job or bill): `GET /api/v1/compositions/:forkId/ghostcut`. Returns `{ status, task_id, original_source_url, mirrored_url, submitted_at_ms, completed_at_ms, failure_reason }`. This is how you read the composition's **two video sources**: `original_source_url` is the **original video** (raw upload, captions intact) and `mirrored_url` is the **decomposed video** (the processed, caption-free copy the timeline renders from). Use this when you want both URLs without triggering another poll — the AI copilot uses it to pick between the original video and the decomposed video before feeding a video into a primitive route (image extract, dedupe, trim, ai video edit, etc.). Prefer the **decomposed video** (`mirrored_url`) when `status === "done"` and the downstream call should be caption-free; prefer the **original video** (`original_source_url`) when the user explicitly wants the raw upload or when `status !== "done"`.
 
 ## Video context (transcript + scene descriptions)
 
@@ -201,7 +201,7 @@ Read-only state (does **not** advance the job or bill): `GET /api/v1/composition
 Use it whenever you need to know what the video says or shows: writing/translating captions, matching hooks or dubs to spoken audio, or planning scene-level edits.
 
 - **Editor chat (frontend AI)** exposes this as the optional `video_context` tool — the copilot calls it on demand.
-- **Desktop agents (Claude Code / Codex)**: `vidfarm edit <template_id>` syncs the same payload to `video-context.json` on disk next to `composition.html` (use `--refetch` to refresh it after a new decompose), or fetch the route directly.
+- **Desktop agents (Claude Code / Codex)**: fetch the `video-context.json` route directly (e.g. `vidfarm api GET /api/v1/compositions/<forkId>/video-context.json`) to ground edits in what the video says and shows.
 
 ## Render (publish to MP4)
 
@@ -381,39 +381,29 @@ Send a stable `tracer` on export so retries are traceable and filterable in job
 
 **Uploads/downloads live in the devcli** because they are genuine multi-step / streaming flows: `upload` posts the file as multipart to the temporary-files route and prints the durable URL to drop into a composition or approved post; `download` streams any Vidfarm/media URL to disk.
 
-## Local dev loop (edit on disk)
+## Local dev loop (`vidfarm serve`)
 
-For iterating on a composition on disk (e.g. Claude Code editing HTML directly), pair the hosted editor with a local composition directory:
+Run the **full** editor locally so a coding agent (Claude Code / Codex) edits composition files on disk while a human finishes in the browser — one source of truth, live sync both ways.
 
 ```bash
-npx -y @mevdragon/vidfarm-devcli <template_id>
-# → downloads composition.html/json + manifest.json + video-context.json into .vidfarm/<template_id>/
-# → downloads the videos + per-scene frames for local analysis (see below)
-# → starts dev-serve on http://localhost:4321
-# → prints https://vidfarm.cc/editor/<template_id>?fork=<forkId>&dev=http%3A%2F%2Flocalhost%3A4321
+npx -y @mevdragon/vidfarm-devcli serve <template_id>
+# → boots the full backend on http://localhost:3000 (records + storage on disk)
+# → pulls that template's default fork (or --fork <id>) from the cloud onto disk
+# → auto-provisions a local user and opens the editor, pre-authed
 ```
 
-### Local media for analysis (`sources.json`, videos, frames)
+Everything runs locally (`RECORDS_DRIVER=local`, `STORAGE_DRIVER=local`) — no AWS touched **except render**, which submits to the deployed cloud renderer when `VIDFARM_JOB_STATE_MACHINE_ARN` + `HYPERFRAMES_RENDER_*` are set (copy them from `.env.staging`); otherwise the editor's render button returns a clear `render_unavailable` message. Media referenced by the composition stays on its cloud URLs.
 
-So a coding agent can *see* what it is editing — not just read URLs — `vidfarm edit` also drops the actual media next to the composition:
+How the loop works:
+- The composition lives on disk at `<data-dir>/storage/compositions/forks/<forkId>/working/composition.html` (default `<data-dir>` is `./.vidfarm-local`). Point your agent at that file.
+- When the agent saves it, the server's `fs.watch` fans a `reload` for that fork over **same-origin** SSE (`GET /api/v1/dev/events`) and the open editor tab live-morphs the change — no reload, playback state preserved (keyed DOM morph on `data-hf-id`).
+- When the human edits in the browser, the editor `PUT`s the composition back to the same file; the server suppresses that self-write so it doesn't echo. Multiple forks can be edited at once under one server.
 
-- **`original.mp4`** — the raw source video, before any processing.
-- **`source.mp4`** — the video the composition timeline actually renders from. This differs from `original.mp4` only when the fork was ghostcut/subtitle-removed; otherwise `sources.json` marks them `same_as_decomposed: true` and only `source.mp4` is written.
-- **`frames/<scene>.png`** — one still per timeline scene, sampled at the scene midpoint from `source.mp4`. Open these as images to analyze what each scene shows. Requires `ffmpeg` (bundled via `ffmpeg-static`); if unavailable the videos still download and frames are skipped.
-- **`sources.json`** — the manifest tying it together: each video's role/url/local path/byte size, the total duration, and per-scene `{ slug, start, duration, label, description, transcript_excerpt, frame }`.
+Seeding from the cloud: `serve <template_id>` pulls the template's **default fork** (which may be another user's public decomposition); `serve --fork <id>` pulls a specific fork. Only the composition + records are localized — media stays on cloud URLs. Re-serving keeps local edits unless you pass `--refetch`.
 
-This is best-effort and never blocks the editor session. Re-run with `--refetch` to refresh the media after a new decompose or ghostcut. For deeper text grounding (full transcript, per-scene visual descriptions) read `video-context.json` — the media files complement it with the pixels.
+Flags: `--port` (default 3000), `--dir` (default `./.vidfarm-local`), `--key` (bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork <id>`, `--host` (cloud host to pull from, default `https://vidfarm.cc`), `--api-key` (cloud key for the pull), `--refetch`, `--no-open`. `vidfarm <template_id>` is an alias for `serve <template_id>`.
 
-Open the printed URL in your browser. An orange **LOCAL DEV MODE** banner pins to the top with an Exit button. All fork API fetches now route to your local dir instead of the deployed API; disk edits push an SSE reload event and the editor re-fetches automatically.
-
-Flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or set `VIDFARM_API_KEY`), `--share`, `--refetch`. For a fork that already has composition files on disk (or that you've populated manually), use `vidfarm-devcli dev-serve --dir ./my-fork --port 4321` to skip the fetch step.
-
-The dev source is persisted in `localStorage.VIDFARM_DEV_SOURCE`, so you don't need to keep the `?dev=` param in the URL after the first load.
-
-`dev-serve` (`vidfarm-devcli` 0.3.2+) is realtime-safe:
-- Writes coming through `PUT /composition.html` / `PATCH /composition.json` **do not loop back** as reload events — the server suppresses filesystem notifications for the just-written file for 500ms so the editor's own save never triggers a self-reload.
-- The SSE `hello` event carries an `instance` id + a monotonic `cursor`. If the client reconnects after a server restart the browser detects the new instance and fires a `vidfarm:dev-reload` so the editor resyncs from disk. A 20s heartbeat keeps the SSE connection alive through intermediate proxies.
-- Port collisions surface as a clear `[dev-serve] port <n> is already in use` message instead of a raw stack trace. Request bodies are capped at 8MB and time out after 15s so a stuck client can't hang the server. File paths are canonicalised so `../etc/passwd`-style paths cannot escape `--dir`.
+To *analyze* the source media locally (videos, transcript, recurring cast), read the `video-context.json` / `cast.json` routes, or pull a media URL with `vidfarm download <url>`.
 
 ## What NOT to do
 
@@ -553,7 +543,7 @@ Analyze a source video and identify where a product can be organically placed so
 
 - `POST /api/v1/primitives/brainstorm/product_placement`
 - Body: `{ "tracer": "...", "payload": { "source_video_url": "...", "offer_description": "...", "count"?: 8, "provider"?: "gemini" }, "webhook_url"?: "..." }`
-  - `source_video_url` (required, URL) — the exact durable/public video to analyze. Aliases accepted: `video_url`, `source_url`, `url`. For a fork's composition, call `GET /api/v1/compositions/:forkId/ghostcut` first and pass the correct raw-upload vs caption-free-mirror URL.
+  - `source_video_url` (required, URL) — the exact durable/public video to analyze. Aliases accepted: `video_url`, `source_url`, `url`. For a fork's composition, call `GET /api/v1/compositions/:forkId/ghostcut` first and pass the correct URL — the **original video** (`original_source_url`) or the **decomposed video** (`mirrored_url`).
   - `offer_description` (required) — the product/offer to place. Aliases: `offer`, `description`, `details`.
   - `count` (optional, 3–30, default 8) — number of opportunities; only send when the user asks for a specific number.
 - Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` to completion, then read `result.json` (also surfaced on the job output as `opportunities[]`), where each entry has `timestamp`, `scene`, `placement_type`, `placement_idea`, and `why_it_works`.

package/SKILL.platform.md

@@ -209,7 +209,7 @@ Both modes update the composition.html and composition.json in place, and create
 
 1. **Editor chat** — the optional `video_context` tool (registered alongside `http_request` in both `src/app.ts` and `infra/lambda/editor-chat.ts`) fetches it on demand; the shared system prompt in `src/editor-chat.ts` tells the model when to reach for it (what does the video say/show, caption/dub matching, scene-level edit planning).
 2. **`http_request`** — the route lives under `COMPOSITIONS_PREFIX`, so chat can also GET it directly (e.g. for a different fork).
-3. **Desktop agents (Claude Code / Codex)** — the devcli (`src/cli.ts`) syncs it to `video-context.json` on disk next to `composition.html` during `vidfarm edit`; `--refetch` refreshes it after a new decompose.
+3. **Desktop agents (Claude Code / Codex)** — fetch the `video-context.json` route directly (e.g. `vidfarm api GET /api/v1/compositions/<forkId>/video-context.json`) to ground on-disk edits in what the video says and shows.
 
 **Source-duration guardrail.** `probeMediaAsset()` in `src/services/media-processing.ts` enforces a hard cap of `MAX_PROBE_DURATION_SECONDS` (120s). If the probed source exceeds it, the probe throws `MediaDurationExceededError` and the route responds with `400 { code: "source_too_long", duration_seconds, max_duration_seconds }`. The same cap applies to inspiration ingest (`ensureInspirationReadyThenFork`) — over-long submissions land as `InspirationRecord { status: "failed", errorMessage }` without ever creating a Template or fork. This is baked into the probe (not the route) so every consumer — auto-decompose, ingest, `video_probe` / `audio_probe` primitives — is protected from repeated probes of long videos being used to burn Lambda / ffmpeg / vision-API budget.
 
@@ -351,39 +351,36 @@ Legacy but still active:
 - Storage keys + public-read prefix list — `src/services/storage.ts`
 - Fork manifest.json helper — `src/services/fork-manifest.ts`
 - Composition runtime script — `src/composition-runtime.ts`
-- Trackpad Editor — `demo/src/HyperframesStudioEditor.tsx`
-- Editor local-mode bootstrap — `demo/src/dev-mode.ts`
-- Devcli (`vidfarm-devcli`) — `src/cli.ts` (edit-mode fetch + banner, the REST-wrapper commands, and the shared `apiRequest()` helper), `src/dev-serve.ts` (raw HTTP shim)
+- Trackpad Editor — `demo/src/HyperframesStudioEditor.tsx` (the same-origin live-reload `EventSource` on `/api/v1/dev/events` lives here)
+- Local records/auth disk shim — `src/services/local-dynamo.ts` (`RECORDS_DRIVER=local`)
+- Local live-reload watcher — `src/services/composition-watch.ts` (`fs.watch` → SSE, `STORAGE_DRIVER=local`)
+- Devcli (`vidfarm-devcli`) — `src/cli.ts` (`serve` = boot the full app locally + cloud-seed, the REST-wrapper commands, and the shared request helper)
 - Auto-decompose logic — `src/hyperframes/composition.ts` (time-slice), `src/services/hyperframes.ts` (smart)
 - Publish flow — `src/app.ts` `publishCompositionToRenderer()`
 - Ghostcut — `src/services/ghostcut.ts`
 - CDK stack — `infra/cdk/lib/vidfarm-serverless-staging-stack.ts`, `infra/cdk/lib/vidfarm-prod-stack.ts`
 
-## Local editor dev loop
+## Local editor dev loop (`vidfarm serve`)
 
-`@mevdragon/vidfarm-devcli` (`src/cli.ts` + `src/dev-serve.ts`) has two roles. First, it pairs a local directory of composition files with the hosted Trackpad Editor so Claude Code, Codex, or a human can edit `composition.html` on disk and see instant preview reload in the browser (the `edit`/`publish`/`dev-serve` commands, detailed below). Second, it wraps the **entire director REST flow** as 1:1 CLI commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render` (→ `/export`), `approve`, `schedule`, `posts`/`schedules`, `upload`/`download`, `login`/`whoami`/`provider-keys`, plus a raw `api <METHOD> <path>` passthrough. Every wrapper routes through a single `apiRequest()` helper (auth + host + JSON), so it never duplicates route logic; the command↔route table and the raw-REST-vs-devcli guidance live in `SKILL.director.md`. Each command prints its prod frontend URL (editor / discover / approved-post `share_url`) as a first-class output, and `--json` gives pure JSON for agents.
+`@mevdragon/vidfarm-devcli` (`src/cli.ts`) has two roles. First, `serve` boots the **full** Vidfarm backend locally — single origin, disk-backed records + storage — so Claude Code, Codex, or a human can edit `composition.html` on disk and see the browser live-morph the change (detailed below). Second, it wraps the **entire director REST flow** as 1:1 CLI commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render` (→ `/export`), `approve`, `schedule`, `posts`/`schedules`, `upload`/`download`, `login`/`whoami`/`provider-keys`, plus a raw `api <METHOD> <path>` passthrough. Each command prints its prod frontend URL as a first-class output, and `--json` gives pure JSON for agents. The command↔route table lives in `SKILL.director.md`.
 
 ```bash
-# One-shot: fetch composition, start dev-serve, print editor URL.
-vidfarm-devcli <template_id>
-# → downloads composition.html/json + manifest.json into .vidfarm/<template_id>/
-# → listens on http://localhost:4321
-# → prints https://vidfarm.cc/editor/<template_id>?fork=<forkId>&dev=http%3A%2F%2Flocalhost%3A4321
-
-# Advanced: skip fetch, serve an existing directory.
-vidfarm-devcli dev-serve --dir ./my-fork --port 4321
-# Then open the editor with ?dev=1 (or ?dev=host:port / ?dev=<full-url>)
-```
+# Boot the full editor locally, pull a template's default fork onto disk, open pre-authed.
+vidfarm-devcli serve <template_id>
+# → http://localhost:3000, records + storage under ./.vidfarm-local
+# → composition at ./.vidfarm-local/storage/compositions/forks/<forkId>/working/composition.html
 
-Edit flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or `VIDFARM_API_KEY`), `--share`, `--refetch`.
+# Pull a specific cloud fork instead of the template default:
+vidfarm-devcli serve --fork <forkId> --host https://vidfarm.cc --api-key <key>
+```
 
-`dev-serve` behavior (`vidfarm-devcli` 0.3.2+):
-- Serves `composition.html` / `composition.json` / `manifest.json` (and `/versions/{n}/…`) with CORS `*`.
-- Accepts `PUT /composition.html` and `PATCH /composition.json`.
-- Watches the dir with `fs.watch`, coalesces bursts (80ms), fans out reload events via `GET /_events` SSE.
-- Reload loop prevention: any successful `PUT` / `PATCH` marks the target file "self-write suppressed" for 500ms so the fs.watch event fired by the write we just performed does NOT round-trip back to the editor as a reload event.
-- SSE `hello` includes `{ at, instance, cursor }`. `instance` changes on every dev-serve restart so a reconnecting client can detect a restart and force a resync; `cursor` is a monotonic counter that bumps on every broadcast reload. Heartbeat `: heartbeat <ts>` every 20s keeps intermediate proxies from timing out the connection.
-- Safety rails: request bodies capped at 8MB with a 15s body-read timeout; path resolution runs through `path.relative(rootDir, ...)` so `versions/../../etc/passwd`-style paths cannot escape the served directory; `EADDRINUSE` produces a plain-English error instead of a raw stack; broadcast iterates a snapshot of the client set so a mid-broadcast disconnect can't skip healthy clients; `SIGINT` + `SIGTERM` both close cleanly with a 2s hard-exit fallback.
+Flags: `--port` (3000), `--dir` (`./.vidfarm-local`), `--key` (local bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork`, `--host`, `--api-key` (cloud pull key), `--refetch`, `--no-open`. `vidfarm <template_id>` aliases `serve <template_id>`.
 
-The editor side lives in `demo/src/dev-mode.ts` — a self-installing module imported at the top of `demo/src/main.tsx`. It reads `?dev=<url>` (persisted to `localStorage.VIDFARM_DEV_SOURCE`), monkey-patches `window.fetch` to rewrite `/api/v1/compositions/{forkId}/*` → `${devSource}/*`, injects a persistent orange banner with an Exit button, and dispatches `vidfarm:dev-reload` on SSE reload events. It also caches the `hello.instance` and re-dispatches `vidfarm:dev-reload` with `{ reason: "server-restart" }` when a reconnect sees a different instance. `HyperframesStudioEditor.tsx` listens for that event and re-runs the composition fetch effect with `cache: "reload"`.
+**Architecture** (fully local; render is the only cloud dependency):
+- **Records/auth** — `src/services/local-dynamo.ts` is a drop-in `.send()` shim for the DynamoDB DocumentClient used by `serverless-records.ts` + `serverless-auth.ts`, servicing Get/Put/Delete/Query/Scan/Update against JSON files under `<data-dir>/dynamo/<table>/`. Selected by `config.RECORDS_DRIVER` (`z.enum(["local","dynamo"]).default("dynamo")` — deployed envs are unaffected). The 25 call sites are unchanged; only the client construction switches.
+- **Storage** — `StorageService` already writes to disk when `STORAGE_DRIVER=local` / `AWS_S3_BUCKET=""` (files under `<data-dir>/storage/`). Composition public URLs become `${PUBLIC_BASE_URL}/storage/<key>`.
+- **Auth** — no seeding: `VIDFARM_API_KEY` + the existing `tryBootstrapFromEnv` auto-provisions a paid customer; `serve` opens `/auto-login?api_key=…&redirect=/editor/…` to plant the session cookie so the browser lands pre-authed.
+- **Live push** — `src/services/composition-watch.ts` (`fs.watch` on the forks dir, only when `STORAGE_DRIVER=local`) coalesces bursts (80ms) and broadcasts `{ forkId, file }` to `GET /api/v1/dev/events` (Hono `streamSSE`, cookie-authed). The editor opens an `EventSource` there gated on the boot flag `liveReload`, and on a `reload` for its fork refetches `composition.html` and runs `applyExternalCompositionHtml` → `morphLiveCompositionDom` (keyed on `data-hf-id`; media buffers + playback survive). The composition write routes call `compositionWatch.suppressFork(forkId)` so the editor's own `PUT` doesn't echo.
+- **Cloud-seed** — `serve` pulls the composition for `--fork` (or the template's default fork via `resolveForkId`, which follows the cloud `/editor` redirect and grabs even another user's public decomposition), then materializes a local template + fork record and writes the composition to the working key so `/editor/:templateId?fork=:id` resolves offline. Media stays on cloud URLs.
+- **Render** — cloud only (no local job runner; hyperframes render is a Lambda fan-out). `publishCompositionToRenderer` returns `render_unavailable` (501) when `VIDFARM_JOB_STATE_MACHINE_ARN` is unset; wire the `HYPERFRAMES_RENDER_*` + state-machine env from `.env.staging` to submit to the deployed renderer.
 - Lambdas — `infra/lambda/*.ts`

package/dist/src/cli.js

@@ -7,10 +7,11 @@ import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-// vidfarm-devcli — thin CLI that pairs a local composition directory with the
-// hosted Trackpad Editor at https://vidfarm.cc/editor/. Point it at a template
-// id, and it: resolves the user's fork, downloads the current composition,
-// starts a local dev-serve, and prints the editor URL to open in the browser.
+// vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
+// `serve` command boots the FULL editor locally (single origin, disk-backed
+// records + storage) so power users edit compositions on disk while a browser
+// editor and a coding agent share one source of truth; render stays on the
+// cloud. The remaining commands are thin 1:1 wrappers over the REST API.
 const DEFAULT_HOST = "https://vidfarm.cc";
 const DEFAULT_PORT = 4321;
 // Agent skill files the `update-skill` command can install from the live host
@@ -38,9 +39,21 @@ Usage:
   vidfarm --help
 
 Local editor loop:
-  <template_id> [opts]      Fetch composition + media, dev-serve, print editor URL
+  serve [template_id] [opts]  Boot the FULL editor locally (single origin, disk-backed).
+                              Records + storage run on disk; render stays on cloud.
+                              With a template_id or --fork, pulls that composition
+                              (or the template's default/shared decomposition) from
+                              the cloud host onto local disk to edit offline.
+    --port <n>                Server port (default: 3000)
+    --dir <path>              Local data dir (default: ./.vidfarm-local)
+    --key <api-key>           Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
+    --fork <id>               Pull + open a specific cloud fork
+    --host <url>              Cloud host to pull from (default: ${DEFAULT_HOST})
+    --api-key <key>           Cloud key for the pull (default: VIDFARM_API_KEY)
+    --refetch                 Overwrite local composition with the cloud copy
+    --no-open                 Don't auto-open the browser
+  <template_id> [opts]      Alias for 'serve <template_id>' (boot the local editor)
   publish [template_id]     Push local composition.html/json to your fork  → PUT/PATCH composition + POST versions
-  dev-serve                 Serve an existing local dir only (no fetch)
 
 Discover & inspiration (browse the viral-video catalog, add your own source):
   discover                  List the template/inspiration feed          → GET  /discover/feed
@@ -51,7 +64,8 @@ Discover & inspiration (browse the viral-video catalog, add your own source):
 Composition lifecycle (fork → decompose → snapshot → render):
   fork <template_id>        Fork a template into an editable composition → POST /api/v1/compositions
   decompose <forkId>        Split the fork's source into scenes (smart)  → POST .../compositions/:forkId/auto-decompose
-  ghostcut <forkId>         Read subtitle-removal status (non-billing)   → GET  .../compositions/:forkId/ghostcut
+  ghostcut <forkId>         Read the two video sources: original vs      → GET  .../compositions/:forkId/ghostcut
+                            decomposed (caption-free), non-billing
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
   render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/export
@@ -83,7 +97,12 @@ Agent skill (install the latest director skill so your AI agent can act):
 
 Files (multi-step flows the devcli handles for you):
   upload <file>             Upload a local file, print its durable URL   → POST /api/v1/user/me/temporary-files/upload
+    --folder <path>         Namescope the upload under a product/offer folder
   download <url> [dest]     Stream any Vidfarm/media URL to disk
+  files                     List My Files assets + folders               → GET /api/v1/user/me/attachments
+    --folder <path>         Only files under this folder (e.g. a product/offer)
+  get-file <id> [dest]      Resolve a My Files id to its URL and download it
+    --print                 Print text contents (md/txt/csv/json) instead of saving
 
 Escape hatch — call ANY route directly:
   api <METHOD> <path>       Raw REST call with auth + pretty errors
@@ -99,11 +118,12 @@ Common options (any command):
   --share <token>     Share token for a shared fork (public read)
   --json              Print only the raw JSON response (agent-friendly)
 
-Editor-mode options:
-  --port <n>          Local dev-serve port (default: ${DEFAULT_PORT})
-  --dir <path>        Local composition directory (default: .vidfarm/<template_id>)
-  --fork <id>         Fork id (default: auto-resolve for the current user)
-  --refetch           Overwrite local composition files with the latest remote copy
+Serve-mode options:
+  --port <n>          Local server port (default: 3000)
+  --dir <path>        Local data dir for disk records + storage (default: ./.vidfarm-local)
+  --key <api-key>     Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
+  --fork <id>         Open a specific fork (multiple forks editable at once)
+  --no-open           Don't auto-open the browser
 
 Publish-mode options:
   --message <text>    Message attached to the published version snapshot
@@ -122,13 +142,11 @@ async function main() {
     const command = argv[0];
     const rest = argv.slice(1);
     switch (command) {
-        case "dev-serve": {
-            const { runDevServeCommand } = await import("./dev-serve.js");
-            await runDevServeCommand(rest);
-            return;
-        }
+        // `serve` (and the bare `<template_id>` / legacy `edit` alias) boot the full
+        // editor locally. The old cross-origin dev-serve/`?dev=` flow is gone.
+        case "serve":
         case "edit":
-            await runEditCommand(rest);
+            await runServeCommand(rest);
             return;
         case "publish":
             await runPublishCommand(rest);
@@ -219,10 +237,16 @@ async function main() {
         case "download":
             await runDownloadCommand(rest);
             return;
+        case "files":
+            await runFilesCommand(rest);
+            return;
+        case "get-file":
+            await runGetFileCommand(rest);
+            return;
         default:
             if (!command.startsWith("-")) {
-                // Positional template id → default `edit` command.
-                await runEditCommand(argv);
+                // Positional template id → default to booting the local editor.
+                await runServeCommand(argv);
                 return;
             }
             throw new Error(`Unknown option before command: ${command}\n\n${HELP}`);
@@ -337,61 +361,205 @@ function collectKeyValues(entries) {
     }
     return out;
 }
-async function runEditCommand(argv) {
+// `vidfarm serve` — boot the FULL Vidfarm backend locally (single origin), on
+// disk-backed records + storage, so power users edit compositions locally while
+// a browser editor and a coding agent share one source of truth. Render stays
+// on the cloud (see Phase 4). This replaces the cross-origin `?dev=` shim.
+async function runServeCommand(argv) {
     const parsed = parseArgs({
         args: argv,
         allowPositionals: true,
         options: {
-            port: { type: "string", default: String(DEFAULT_PORT) },
+            port: { type: "string", default: "3000" },
             dir: { type: "string" },
-            host: { type: "string", default: DEFAULT_HOST },
+            key: { type: "string" },
             fork: { type: "string" },
+            host: { type: "string", default: DEFAULT_HOST },
             "api-key": { type: "string" },
             share: { type: "string" },
-            refetch: { type: "boolean", default: false }
+            refetch: { type: "boolean", default: false },
+            open: { type: "boolean", default: true },
+            "no-open": { type: "boolean", default: false }
         }
     });
-    const templateId = parsed.positionals[0];
-    if (!templateId) {
-        throw new Error(`edit requires a template id.\n\n${HELP}`);
-    }
     const port = Number(parsed.values.port);
     if (!Number.isFinite(port) || port <= 0) {
         throw new Error(`Invalid --port: ${parsed.values.port}`);
     }
+    const dataDir = path.resolve(process.cwd(), parsed.values.dir ?? ".vidfarm-local");
+    mkdirSync(dataDir, { recursive: true });
+    // Capture the ambient cloud key BEFORE we overwrite VIDFARM_API_KEY with the
+    // local bootstrap key, so `--fork`/template seeding can still authenticate to
+    // the cloud host.
+    const envKey = process.env.VIDFARM_API_KEY;
+    // A stable local bootstrap key: first --key, else VIDFARM_API_KEY, else a
+    // fixed dev key. The same value auto-provisions the paid customer (via
+    // tryBootstrapFromEnv) and pre-auths the browser through /auto-login.
+    const apiKey = parsed.values.key ?? envKey ?? "vidfarm-local-dev-key";
+    const cloudApiKey = parsed.values["api-key"] ?? envKey;
     const host = trimTrailingSlash(parsed.values.host);
-    const apiKey = parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY;
-    const shareToken = parsed.values.share;
-    const rootDir = path.resolve(process.cwd(), parsed.values.dir ?? path.join(".vidfarm", templateId));
-    mkdirSync(rootDir, { recursive: true });
-    const forkId = parsed.values.fork ?? await resolveForkId({ host, templateId, apiKey, shareToken });
-    if (!forkId) {
-        throw new Error(`Could not resolve a fork id for template ${templateId}. Pass --fork <id>, or open ${host}/editor/${templateId} once so a fork is created.`);
-    }
-    await fetchCompositionFiles({
-        host,
-        forkId,
-        dir: rootDir,
-        apiKey,
-        shareToken,
-        refetch: parsed.values.refetch
-    });
-    // Give local coding agents (Claude Code / Codex / opencode) the actual media
-    // to look at: the original source video, the composition's decomposed source
-    // (which may differ after ghostcut subtitle-removal), one still frame per
-    // scene, and a sources.json manifest tying it all together. Best-effort —
-    // never blocks the editor session if a download or frame extraction fails.
+    const templateId = parsed.positionals[0];
+    const forkFlag = parsed.values.fork;
+    // Env MUST be set before importing runtime — config.ts reads it at module
+    // load. Force the fully-local drivers; keep any cloud creds already present
+    // in the environment so render passthrough still works.
+    process.env.RECORDS_DRIVER = "local";
+    process.env.STORAGE_DRIVER = "local";
+    process.env.AWS_S3_BUCKET = "";
+    process.env.VIDFARM_DATA_DIR = dataDir;
+    process.env.VIDFARM_API_KEY = apiKey;
+    process.env.PORT = String(port);
+    if (!process.env.NODE_ENV)
+        process.env.NODE_ENV = "development";
+    const { startRuntime } = await import("./runtime.js");
+    await startRuntime();
+    // If a template/fork was requested, pull its composition from the cloud host
+    // onto local disk and materialize the matching local records so the editor
+    // resolves it. Best-effort: a failure just drops us to /discover.
+    let openTemplateId = templateId;
+    let openForkId = forkFlag;
+    if (templateId || forkFlag) {
+        try {
+            const seeded = await seedForkFromCloud({
+                host,
+                templateId,
+                forkId: forkFlag,
+                cloudApiKey,
+                shareToken: parsed.values.share,
+                bootstrapKey: apiKey,
+                refetch: parsed.values.refetch
+            });
+            if (seeded) {
+                openTemplateId = seeded.templateId;
+                openForkId = seeded.forkId;
+            }
+        }
+        catch (error) {
+            console.warn(`[vidfarm] serve: cloud seed failed (${error instanceof Error ? error.message : String(error)}); starting empty.`);
+        }
+    }
+    const base = `http://localhost:${port}`;
+    const editorPath = openTemplateId
+        ? `/editor/${encodeURIComponent(openTemplateId)}${openForkId ? `?fork=${encodeURIComponent(openForkId)}` : ""}`
+        : "/discover";
+    const openUrl = `${base}/auto-login?api_key=${encodeURIComponent(apiKey)}&redirect=${encodeURIComponent(editorPath)}`;
+    printServeBanner({ base, dataDir, openUrl, editorPath });
+    const shouldOpen = parsed.values.open && !parsed.values["no-open"];
+    if (shouldOpen)
+        openInBrowser(openUrl);
+    // startRuntime() keeps the process alive via its HTTP server; nothing else to do.
+}
+// Pull a cloud fork's composition onto local disk and create the local
+// template + fork records so the editor resolves it. The fork is either an
+// explicit --fork or the template's default fork (which may be another user's
+// public decomposition). Media stays on cloud URLs — only the composition +
+// records are localized. Runs in-process after startRuntime(), so it shares the
+// server's disk-backed records/storage singletons.
+async function seedForkFromCloud(input) {
+    const { serverlessRecords } = await import("./services/serverless-records.js");
+    const { StorageService } = await import("./services/storage.js");
+    const { ServerlessAuthService } = await import("./services/serverless-auth.js");
+    const storage = new StorageService();
+    const auth = new ServerlessAuthService();
+    // Ensure the local bootstrap customer exists and grab its id to own the seed.
+    const customer = await auth.authenticate(input.bootstrapKey);
+    const authHeaders = buildAuthHeaders({ apiKey: input.cloudApiKey, shareToken: input.shareToken });
+    // 1. Resolve the source fork: explicit --fork wins, else the template's
+    //    default fork (grabs the shared decomposition even if another user owns it).
+    let cloudForkId = input.forkId ?? null;
+    if (!cloudForkId && input.templateId) {
+        cloudForkId = await resolveForkId({ host: input.host, templateId: input.templateId, apiKey: input.cloudApiKey, shareToken: input.shareToken });
+    }
+    if (!cloudForkId) {
+        console.warn("[vidfarm] serve: no --fork and no default fork resolvable from cloud; starting empty.");
+        return null;
+    }
+    // 2. Read the serialized fork for its template id + title.
+    const forkMetaRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}`, { headers: authHeaders });
+    const forkMeta = forkMetaRes.ok ? (await forkMetaRes.json().catch(() => null)) : null;
+    const templateId = input.templateId ?? (typeof forkMeta?.template_id === "string" ? forkMeta.template_id : null);
+    if (!templateId || !templateId.startsWith("template_")) {
+        console.warn(`[vidfarm] serve: could not determine a template id for fork ${cloudForkId}; starting empty.`);
+        return null;
+    }
+    const title = (typeof forkMeta?.title === "string" && forkMeta.title) || `Local · ${templateId}`;
+    // 3. Materialize the local template record (the editor 404s without it).
+    const existingTemplate = await serverlessRecords.getTemplate(templateId);
+    if (!existingTemplate) {
+        await serverlessRecords.createTemplate({
+            id: templateId,
+            inspirationId: `local:${templateId}`,
+            customerId: customer.id,
+            originalUrl: typeof forkMeta?.original_url === "string" ? forkMeta.original_url : "",
+            sourceHost: "local",
+            title,
+            visibility: "public"
+        });
+    }
+    // 4. Materialize the local fork (reuse the cloud id for stable URLs).
+    const localForkId = cloudForkId;
+    const existingFork = await serverlessRecords.getCompositionFork(localForkId);
+    if (!existingFork) {
+        await serverlessRecords.createCompositionFork({
+            id: localForkId,
+            customerId: customer.id,
+            templateId,
+            title,
+            visibility: "private"
+        });
+    }
+    // 5. Pull composition.html/json onto disk (skip if present unless --refetch,
+    //    so local edits aren't clobbered on re-serve).
+    const htmlKey = storage.compositionForkWorkingKey(localForkId, "composition.html");
+    const jsonKey = storage.compositionForkWorkingKey(localForkId, "composition.json");
+    const hasLocalHtml = Boolean(await storage.readText(htmlKey));
+    if (!hasLocalHtml || input.refetch) {
+        const htmlRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}/composition.html`, { headers: authHeaders });
+        if (!htmlRes.ok) {
+            console.warn(`[vidfarm] serve: could not fetch composition.html for ${cloudForkId} (${htmlRes.status}); starting empty.`);
+            return null;
+        }
+        await storage.putText(htmlKey, await htmlRes.text(), "text/html; charset=utf-8");
+        const jsonRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}/composition.json`, { headers: authHeaders });
+        if (jsonRes.ok)
+            await storage.putBuffer(jsonKey, Buffer.from(await jsonRes.text(), "utf8"), "application/json");
+        console.log(`[vidfarm] seeded fork ${localForkId} from ${input.host}`);
+    }
+    else {
+        console.log(`[vidfarm] fork ${localForkId} already local (use --refetch to overwrite)`);
+    }
+    // 6. Point the template's default fork at the local copy so a bare
+    //    /editor/:templateId resolves it too.
+    await serverlessRecords.stampDefaultForkIfUnset({ templateId, forkId: localForkId });
+    return { templateId, forkId: localForkId };
+}
+function printServeBanner(input) {
+    const line = `${DIM}${"─".repeat(74)}${RESET}`;
+    console.log("");
+    console.log(line);
+    console.log(`${BOLD}${GREEN}  Vidfarm local server${RESET}  ${DIM}(fully local — records + storage on disk)${RESET}`);
+    console.log(line);
+    console.log(`  server      ${input.base}`);
+    console.log(`  data dir    ${input.dataDir}`);
+    console.log(`  render      ${DIM}cloud (submitted to the deployed renderer)${RESET}`);
+    console.log("");
+    console.log(`  ${DIM}Agents: edit composition files under ${input.dataDir}/storage — the`);
+    console.log(`  browser live-reloads on save. Multiple forks can be edited at once.${RESET}`);
+    console.log("");
+    console.log(`  ${BOLD}Open (pre-authed):${RESET}`);
+    console.log(`  ${FRONTEND}${input.openUrl}${RESET}`);
+    console.log(line);
+    console.log("");
+}
+function openInBrowser(url) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
     try {
-        await fetchVideoAssets({ dir: rootDir, apiKey, shareToken, refetch: parsed.values.refetch });
+        spawnSync(opener, args, { stdio: "ignore" });
     }
-    catch (error) {
-        console.warn(`[vidfarm] video assets skipped: ${error instanceof Error ? error.message : String(error)}`);
+    catch {
+        // Non-fatal: the banner already printed the URL to open manually.
     }
-    const devSource = `http://localhost:${port}`;
-    const editorUrl = `${host}/editor/${encodeURIComponent(templateId)}?fork=${encodeURIComponent(forkId)}&dev=${encodeURIComponent(devSource)}`;
-    printEditorBanner({ templateId, forkId, dir: rootDir, port, editorUrl });
-    const { runDevServeCommand } = await import("./dev-serve.js");
-    await runDevServeCommand(["--dir", rootDir, "--port", String(port)]);
 }
 async function runPublishCommand(argv) {
     const parsed = parseArgs({
@@ -564,7 +732,9 @@ async function fetchCompositionFiles(input) {
     // video-context.json carries the source video's audio transcript and
     // per-scene visual descriptions so desktop agents (Claude Code, Codex)
     // can ground edits in what the video actually says and shows.
-    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json"];
+    // cast.json carries the identified recurring people/characters plus their
+    // reference-still URLs so agents can reuse "the same person" in new gens.
+    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json"];
     for (const filename of files) {
         const target = path.join(input.dir, filename);
         if (existsSync(target) && !input.refetch) {
@@ -588,10 +758,10 @@ async function fetchVideoAssets(input) {
         console.log("[vidfarm] no source video URL found in composition — skipping video assets");
         return;
     }
-    // "decomposed video in composition" = the source the composition currently
-    // renders from (post-ghostcut if applicable). "original" = the raw source the
-    // decompose ran against, before any processing. They coincide when the fork
-    // was never ghostcut/subtitle-removed.
+    // "decomposed video" = the source the composition currently renders from
+    // (caption-free after subtitle removal, if applicable). "original video" =
+    // the raw source the decompose ran against, before any processing. They
+    // coincide when the fork was never subtitle-removed.
     const compositionUrl = refs.compositionSourceUrl ?? refs.originalSourceUrl;
     const originalUrl = refs.originalSourceUrl ?? refs.compositionSourceUrl;
     const sameSource = compositionUrl === originalUrl;
@@ -630,19 +800,20 @@ async function fetchVideoAssets(input) {
         : new Map();
     const manifest = {
         generated_by: "vidfarm-devcli",
-        note: "Local media references for coding agents. `original.mp4` is the raw source video; " +
-            "`source.mp4` is the video the composition timeline renders from (may differ from the " +
-            "original after ghostcut subtitle-removal). Scene entries map timeline segments to a still " +
-            "frame you can open as an image. Run `--refetch` to refresh.",
+        note: "Local media references for coding agents. Two video sources: `original.mp4` is the " +
+            "ORIGINAL video (raw source, captions intact); `source.mp4` is the DECOMPOSED video, the " +
+            "processed caption-free copy the composition timeline renders from (differs from the original " +
+            "only when the fork was decomposed with subtitle removal). Scene entries map timeline segments " +
+            "to a still frame you can open as an image. Run `--refetch` to refresh.",
         videos: {
             decomposed: {
-                role: "video the composition timeline renders from (decomposed source)",
+                role: "decomposed video: processed caption-free source the composition timeline renders from",
                 url: compositionUrl,
                 path: decomposed ? decomposedName : null,
                 bytes: decomposed?.bytes ?? null
             },
             original: {
-                role: "raw original source video (before any processing)",
+                role: "original video: raw source before any processing",
                 url: originalUrl,
                 path: original ? original.path : null,
                 bytes: original?.bytes ?? null,
@@ -818,29 +989,6 @@ function buildAuthHeaders(input) {
         headers["vidfarm-share-token"] = input.shareToken;
     return headers;
 }
-function printEditorBanner(input) {
-    const bold = "\x1b[1m";
-    const green = "\x1b[32m";
-    const cyan = "\x1b[36m";
-    const dim = "\x1b[2m";
-    const reset = "\x1b[0m";
-    const line = `${dim}${"─".repeat(74)}${reset}`;
-    console.log("");
-    console.log(line);
-    console.log(`${bold}${green}  Vidfarm local editor${reset}`);
-    console.log(line);
-    console.log(`  template    ${input.templateId}`);
-    console.log(`  fork        ${input.forkId}`);
-    console.log(`  local dir   ${input.dir}`);
-    console.log(`  dev-serve   http://localhost:${input.port}`);
-    console.log("");
-    console.log(`  ${dim}Agent media: original.mp4, source.mp4, frames/*.png, sources.json${reset}`);
-    console.log("");
-    console.log(`  ${bold}Open in browser:${reset}`);
-    console.log(`  ${cyan}${input.editorUrl}${reset}`);
-    console.log(line);
-    console.log("");
-}
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, "");
 }
@@ -931,6 +1079,12 @@ async function runInspirationDecomposeCommand(argv) {
         body: { user_prompt: parsed.values.prompt ?? null }
     });
     assertApiOk(result, "inspiration-decompose");
+    if (!ctx.json && result.json?.default_fork_id) {
+        const forkId = result.json.default_fork_id;
+        console.log(result.json.became_default_fork
+            ? `${DIM}This decompose set the template default fork (${forkId}) — everyone now forks off it.${RESET}`
+            : `${DIM}Template already has a default fork (${forkId}); left it unchanged.${RESET}`);
+    }
     emitResult(result, ctx.json);
 }
 // ── Composition lifecycle ───────────────────────────────────────────────────
@@ -1316,6 +1470,62 @@ async function runDownloadCommand(argv) {
         console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
     }
 }
+// Browse the user's My Files library — the persistent per-user asset store
+// (videos, images, audio, docs) organized into virtual folders. `files` lists
+// them (optionally scoped to a folder); `get-file` resolves one attachment id to
+// its durable URL and either streams the bytes to disk or prints text contents.
+// This is the same filesystem the /editor AI agent browses via the browse_files
+// tool, so an agent CLI (Claude Code / Codex) can find assets the same way.
+async function runFilesCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" } } });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/attachments", auth: ctx.auth });
+    assertApiOk(result, "files");
+    const folderFilter = parsed.values.folder ? String(parsed.values.folder).replace(/^\/+|\/+$/g, "") : undefined;
+    if (folderFilter && result.json && Array.isArray(result.json.attachments)) {
+        result.json = {
+            ...result.json,
+            attachments: result.json.attachments.filter((file) => (file?.folderPath ?? "") === folderFilter)
+        };
+    }
+    emitResult(result, ctx.json);
+}
+async function runGetFileCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), print: { type: "boolean", default: false } } });
+    const fileId = parsed.positionals[0];
+    if (!fileId)
+        throw new Error("get-file requires a file id (run `files` to list ids).");
+    const ctx = commonContext(parsed.values);
+    const list = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/attachments", auth: ctx.auth });
+    assertApiOk(list, "get-file");
+    const attachments = Array.isArray(list.json?.attachments) ? list.json.attachments : [];
+    const match = attachments.find((file) => file?.id === fileId) ?? attachments.find((file) => file?.fileName === fileId);
+    if (!match)
+        throw new Error(`No file with id or name "${fileId}" in My Files. Run \`files\` to list ids.`);
+    const viewUrl = match.viewUrl;
+    if (!viewUrl)
+        throw new Error(`File "${match.fileName}" has no resolvable URL.`);
+    const absoluteUrl = new URL(viewUrl, ctx.host).toString();
+    const res = await fetch(absoluteUrl, { headers: buildAuthHeaders(ctx.auth) });
+    if (!res.ok || !res.body)
+        throw new Error(`get-file failed: ${res.status} ${res.statusText} (${absoluteUrl}).`);
+    if (parsed.values.print) {
+        const text = await res.text();
+        process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+        return;
+    }
+    const dest = parsed.positionals[1]
+        ? path.resolve(process.cwd(), parsed.positionals[1])
+        : path.resolve(process.cwd(), match.fileName || path.basename(new URL(absoluteUrl).pathname) || "download.bin");
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(dest));
+    const bytes = safeSize(dest);
+    if (ctx.json) {
+        printJson({ ok: true, file_id: match.id, file_name: match.fileName, url: absoluteUrl, path: dest, bytes });
+    }
+    else {
+        console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
+    }
+}
 // ── Agent skill ───────────────────────────────────────────────────────────────
 // Install the latest director skill onto disk as a Claude Code / agent skill so
 // the user's AI agent can read SKILL.director.md and act. We pull the freshest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Local bridge for the Vidfarm Trackpad Editor. Point it at a template id, edit composition.html on disk (Claude Code, Codex, etc.), preview live in the browser at https://vidfarm.cc/editor/.",
   "type": "module",
   "bin": {
@@ -9,7 +9,6 @@
   },
   "files": [
     "dist/src/cli.js",
-    "dist/src/dev-serve.js",
     "README.md",
     "SKILL.director.md",
     "SKILL.platform.md",

package/dist/src/dev-serve.js

@@ -1,340 +0,0 @@
-import { createServer } from "node:http";
-import { existsSync, mkdirSync, readFileSync, statSync, watch, writeFileSync } from "node:fs";
-import path from "node:path";
-import { parseArgs } from "node:util";
-// vidfarm dev-serve — a tiny HTTP layer that lets the browser editor point at
-// a local directory of composition files instead of the deployed API. The
-// editor detects dev mode from `?dev=<url>` (or localStorage) and rewrites
-// its fork API calls to hit this server. File changes fan out via SSE so the
-// editor can reload the composition on save-from-disk (e.g. Claude Code
-// edits the file directly).
-const CORS_HEADERS = {
-    "access-control-allow-origin": "*",
-    "access-control-allow-methods": "GET,PUT,PATCH,POST,OPTIONS",
-    // The editor page (vidfarm.cc) fetches us cross-origin and its Sentry
-    // instrumentation attaches distributed-tracing headers (sentry-trace,
-    // baggage). List them so the preflight passes; the OPTIONS handler also
-    // echoes whatever the browser actually asks for, which is the real guard.
-    "access-control-allow-headers": "content-type,authorization,vidfarm-api-key,vidfarm-share-token,sentry-trace,baggage",
-    "access-control-max-age": "600"
-};
-// Cap request bodies at 8MB so a runaway or malicious client can't OOM the
-// dev server. A composition.html + inlined asset is normally <1MB.
-const MAX_REQUEST_BODY_BYTES = 8 * 1024 * 1024;
-// Ignore filesystem events for this long after we write from an HTTP handler,
-// so the editor's own PUT/PATCH doesn't trigger a self-reload loop. `fs.watch`
-// on macOS fires 1–3 events per rename, plus a tail event from the editor's
-// auto-format step.
-const SELF_WRITE_SUPPRESS_MS = 500;
-// Bump on every new dev-serve process so a reconnecting SSE client can tell
-// whether the server restarted (and therefore whether it must resync files).
-const SERVER_INSTANCE_ID = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-export async function runDevServeCommand(argv) {
-    const parsed = parseArgs({
-        args: argv,
-        options: {
-            dir: { type: "string", default: "." },
-            port: { type: "string", default: "4321" }
-        }
-    });
-    const rootDir = path.resolve(process.cwd(), parsed.values.dir);
-    const port = Number(parsed.values.port);
-    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
-        throw new Error(`Invalid --port: ${parsed.values.port}`);
-    }
-    if (!existsSync(rootDir)) {
-        mkdirSync(rootDir, { recursive: true });
-    }
-    let nextClientId = 1;
-    let mutationCursor = 0;
-    const clients = new Set();
-    const selfWriteSuppressUntil = new Map();
-    function broadcast(event, data) {
-        const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
-        // Snapshot the client set before iterating: `client.res.write` can
-        // synchronously destroy the response (broken pipe), which mutates the
-        // Set mid-iteration and can skip healthy clients.
-        for (const client of [...clients]) {
-            try {
-                client.res.write(payload);
-            }
-            catch {
-                clients.delete(client);
-            }
-        }
-    }
-    function isSelfWriteSuppressed(filename) {
-        if (!filename)
-            return false;
-        const until = selfWriteSuppressUntil.get(filename);
-        if (!until)
-            return false;
-        if (Date.now() > until) {
-            selfWriteSuppressUntil.delete(filename);
-            return false;
-        }
-        return true;
-    }
-    function suppressReloadFromSelfWrite(filePath) {
-        const rel = path.relative(rootDir, filePath);
-        if (!rel || rel.startsWith(".."))
-            return;
-        // fs.watch reports filenames relative to the watched root — match both the
-        // basename and the relative path, since macOS emits either form.
-        selfWriteSuppressUntil.set(rel, Date.now() + SELF_WRITE_SUPPRESS_MS);
-        selfWriteSuppressUntil.set(path.basename(filePath), Date.now() + SELF_WRITE_SUPPRESS_MS);
-    }
-    // fs.watch fires on any child change. Coalesce bursts so a single save
-    // doesn't spam the editor with 3 reload events. Also drop events for files
-    // we JUST wrote ourselves so PUT/PATCH doesn't loop into a client reload.
-    let reloadTimer = null;
-    let pendingReloadFile = null;
-    const scheduleReload = (filename) => {
-        if (isSelfWriteSuppressed(filename))
-            return;
-        pendingReloadFile = filename ?? pendingReloadFile;
-        if (reloadTimer)
-            clearTimeout(reloadTimer);
-        reloadTimer = setTimeout(() => {
-            reloadTimer = null;
-            const file = pendingReloadFile;
-            pendingReloadFile = null;
-            mutationCursor += 1;
-            broadcast("reload", { file, at: Date.now(), cursor: mutationCursor });
-            console.log(`[dev-serve] reload → ${file ?? "(unknown)"}`);
-        }, 80);
-    };
-    try {
-        watch(rootDir, { recursive: true }, (_type, filename) => {
-            scheduleReload(filename ?? null);
-        });
-    }
-    catch (error) {
-        console.warn(`[dev-serve] watch failed: ${error instanceof Error ? error.message : String(error)}`);
-        console.warn("[dev-serve] file changes will NOT trigger editor reloads. On Linux, install inotify-tools or run inside a supported filesystem.");
-    }
-    const server = createServer((req, res) => handleRequest(req, res, {
-        rootDir,
-        clients,
-        clientId: nextClientId++,
-        mutationCursor: () => mutationCursor,
-        suppressReloadFromSelfWrite
-    }));
-    server.on("error", (error) => {
-        if (error.code === "EADDRINUSE") {
-            console.error(`[dev-serve] port ${port} is already in use.`);
-            console.error(`[dev-serve] pass --port <n> to pick a different port, or stop the process bound to ${port}.`);
-            process.exit(1);
-        }
-        console.error(`[dev-serve] server error: ${error.message}`);
-        process.exit(1);
-    });
-    server.listen(port, () => {
-        console.log(`[dev-serve] serving ${rootDir}`);
-        console.log(`[dev-serve] listening on http://localhost:${port}`);
-        console.log(`[dev-serve] editor: open with ?dev=${encodeURIComponent(`http://localhost:${port}`)}`);
-    });
-    let shuttingDown = false;
-    const shutdown = () => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        console.log("\n[dev-serve] shutting down");
-        for (const client of clients) {
-            try {
-                client.res.end();
-            }
-            catch { }
-        }
-        clients.clear();
-        server.close(() => process.exit(0));
-        // Fallback: if in-flight sockets keep the server open, force-exit after 2s.
-        setTimeout(() => process.exit(0), 2000).unref();
-    };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-}
-function handleRequest(req, res, ctx) {
-    const method = (req.method ?? "GET").toUpperCase();
-    const url = new URL(req.url ?? "/", `http://localhost`);
-    const pathname = url.pathname;
-    if (method === "OPTIONS") {
-        // Echo the exact headers the browser requested so a preflight never fails
-        // over an unexpected header (Sentry tracing, etc.). This is a local dev
-        // tool, so permissive CORS is fine.
-        const requested = req.headers["access-control-request-headers"];
-        res.writeHead(204, {
-            ...CORS_HEADERS,
-            "access-control-allow-headers": typeof requested === "string" && requested ? requested : CORS_HEADERS["access-control-allow-headers"]
-        });
-        res.end();
-        return;
-    }
-    if (pathname === "/_events" && method === "GET") {
-        res.writeHead(200, {
-            ...CORS_HEADERS,
-            "content-type": "text/event-stream",
-            "cache-control": "no-cache",
-            connection: "keep-alive",
-            "x-accel-buffering": "no"
-        });
-        // Include instance id + current cursor so a reconnecting client can tell
-        // if the server restarted (missed events) or if it just needs to catch up.
-        res.write(`event: hello\ndata: ${JSON.stringify({
-            at: Date.now(),
-            instance: SERVER_INSTANCE_ID,
-            cursor: ctx.mutationCursor()
-        })}\n\n`);
-        const client = { res, id: ctx.clientId };
-        ctx.clients.add(client);
-        // Heartbeat keeps intermediate proxies (and iOS Safari) from timing out
-        // the long-lived SSE connection.
-        const heartbeat = setInterval(() => {
-            try {
-                res.write(`: heartbeat ${Date.now()}\n\n`);
-            }
-            catch { }
-        }, 20_000);
-        const cleanup = () => {
-            clearInterval(heartbeat);
-            ctx.clients.delete(client);
-        };
-        req.on("close", cleanup);
-        req.on("error", cleanup);
-        return;
-    }
-    const filePath = resolveFilePath(ctx.rootDir, pathname);
-    if (!filePath) {
-        respondJson(res, 404, { ok: false, error: `Not found: ${pathname}` });
-        return;
-    }
-    if (method === "GET") {
-        if (!existsSync(filePath)) {
-            respondJson(res, 404, { ok: false, error: `Missing ${path.basename(filePath)}` });
-            return;
-        }
-        try {
-            const body = readFileSync(filePath);
-            const stat = statSync(filePath);
-            const contentType = pathname.endsWith(".html") ? "text/html; charset=utf-8" : "application/json";
-            res.writeHead(200, {
-                ...CORS_HEADERS,
-                "content-type": contentType,
-                "cache-control": "no-store",
-                etag: `"${stat.size}-${stat.mtimeMs}"`
-            });
-            res.end(body);
-        }
-        catch (error) {
-            respondJson(res, 500, { ok: false, error: `Read failed: ${error instanceof Error ? error.message : String(error)}` });
-        }
-        return;
-    }
-    if (method === "PUT" && pathname.endsWith("/composition.html")) {
-        readBody(req).then((body) => {
-            const html = body.toString("utf8");
-            if (!html.includes("data-composition-id=")) {
-                respondJson(res, 400, { ok: false, error: "Composition HTML is missing data-composition-id" });
-                return;
-            }
-            try {
-                mkdirSync(path.dirname(filePath), { recursive: true });
-                ctx.suppressReloadFromSelfWrite(filePath);
-                writeFileSync(filePath, html, "utf8");
-                respondJson(res, 200, { ok: true, bytes: html.length });
-            }
-            catch (error) {
-                respondJson(res, 500, { ok: false, error: `Write failed: ${error instanceof Error ? error.message : String(error)}` });
-            }
-        }).catch((error) => respondJson(res, 400, { ok: false, error: String(error) }));
-        return;
-    }
-    if (method === "PATCH" && pathname.endsWith("/composition.json")) {
-        readBody(req).then((body) => {
-            try {
-                const patch = JSON.parse(body.toString("utf8") || "{}");
-                const existing = existsSync(filePath) ? JSON.parse(readFileSync(filePath, "utf8") || "{}") : {};
-                const merged = { ...existing, ...patch };
-                mkdirSync(path.dirname(filePath), { recursive: true });
-                ctx.suppressReloadFromSelfWrite(filePath);
-                writeFileSync(filePath, JSON.stringify(merged, null, 2), "utf8");
-                respondJson(res, 200, merged);
-            }
-            catch (error) {
-                respondJson(res, 400, { ok: false, error: `PATCH failed: ${error instanceof Error ? error.message : String(error)}` });
-            }
-        }).catch((error) => respondJson(res, 400, { ok: false, error: String(error) }));
-        return;
-    }
-    respondJson(res, 405, { ok: false, error: `Method ${method} not allowed on ${pathname}` });
-}
-// Restrict served paths to the working/version composition files. Anything
-// else 404s so this server isn't a random static host. Also canonicalise the
-// resolved path so `..` segments cannot escape rootDir even through a future
-// refactor of the allowlist.
-function resolveFilePath(rootDir, pathname) {
-    const clean = pathname.replace(/^\/+/, "");
-    const parts = clean.split("/").filter(Boolean);
-    if (parts.length === 0)
-        return null;
-    const filename = parts[parts.length - 1];
-    const allowed = ["composition.html", "composition.json", "manifest.json"];
-    if (!allowed.includes(filename))
-        return null;
-    let candidate;
-    // Allow: `composition.html`, `versions/1/composition.html`.
-    if (parts.length === 1)
-        candidate = path.join(rootDir, filename);
-    else if (parts.length === 3 && parts[0] === "versions" && /^\d+$/.test(parts[1])) {
-        candidate = path.join(rootDir, "versions", parts[1], filename);
-    }
-    else {
-        return null;
-    }
-    const resolved = path.resolve(candidate);
-    const rootResolved = path.resolve(rootDir);
-    const rel = path.relative(rootResolved, resolved);
-    if (rel.startsWith("..") || path.isAbsolute(rel))
-        return null;
-    return resolved;
-}
-function respondJson(res, status, body) {
-    res.writeHead(status, { ...CORS_HEADERS, "content-type": "application/json" });
-    res.end(JSON.stringify(body));
-}
-function readBody(req) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let total = 0;
-        let settled = false;
-        // Guard against a slow client stringing the connection open forever.
-        const timeout = setTimeout(() => {
-            if (settled)
-                return;
-            settled = true;
-            req.destroy();
-            reject(new Error("Request body read timed out after 15s."));
-        }, 15_000);
-        const done = (fn) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timeout);
-            fn();
-        };
-        req.on("data", (chunk) => {
-            if (settled)
-                return;
-            total += chunk.length;
-            if (total > MAX_REQUEST_BODY_BYTES) {
-                done(() => reject(new Error(`Request body exceeds ${MAX_REQUEST_BODY_BYTES} bytes.`)));
-                req.destroy();
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on("end", () => done(() => resolve(Buffer.concat(chunks))));
-        req.on("error", (error) => done(() => reject(error)));
-    });
-}
-//# sourceMappingURL=dev-serve.js.map