@mevdragon/vidfarm-devcli 0.3.3 → 0.3.5

package/SKILL.director.md

@@ -26,7 +26,7 @@ A Vidfarm composition is an **HTML document + JSON metadata**. Each layer (video
 
 Every director workflow goes through three concepts:
 
-1. **Template** — a published composition anyone can fork. Templates live at `/hyperframes/:slug` and have a source video, a decomposed timeline, and metadata (viral DNA, captions, scenes).
+1. **Template** — a published composition anyone can fork. Template ids start with `template_`; each template opens in the editor at `/editor/:templateId` and has a source video, a decomposed timeline, and metadata (viral DNA, captions, scenes).
 2. **Composition fork** — a private editable copy of a template. Every fork has a `forkId`, an owner, a working state, and a version history. The Trackpad Editor operates on a fork.
 3. **Publish** — render the current fork state to MP4 via a Lambda render job. Each publish snapshots the current working state as an immutable version.
 
@@ -39,42 +39,46 @@ The current API base URLs are:
 - staging: `https://staging.vidfarm.cc`
 - production: `https://vidfarm.cc`
 
-Every browser action is authenticated by the session cookie set at `/login`. Every headless action needs the `vidfarm-api-key` header set to the caller's API key (from Settings → API Keys).
+Every browser action is authenticated by the session cookie set at `/login`. Headless API-key auth uses the `vidfarm-api-key` header set to the caller's API key (from Settings → API Keys).
+
+**Auth contract: API-key auth is the `vidfarm-api-key: <key>` request header and nothing else. `Authorization: Bearer <key>` is NOT supported — the server never reads the `authorization` header (see `requireAuth` in `src/app.ts`).**
 
 ```
-vidfarm-api-key: vf_key_<32 hex>
+vidfarm-api-key: vf_key_<id>
 ```
 
+Scope note (verified against `src/app.ts`): the `vidfarm-api-key` header authenticates **every** authenticated surface — the `requireAuth` routes (`/api/v1/user/*`, `/api/v1/agency/*`, `/api/v1/templates/*`, `/api/v1/primitives/*`, `/api/v1/rate-limit-status`, editor-chat threads) **and** the `/api/v1/compositions/*` + `/api/v1/videos/*` + editor page routes, where an explicit API key takes precedence over any browser session cookie. Cookies remain how the web UI authenticates; headless callers never need one. Reads on composition routes also work without any credential because the `forkId` acts as an unguessable view bearer token, and share-link tokens (header `vidfarm-share-token` or `?share=` query) can grant `viewer`/`editor`/`publisher` roles.
+
 ## Login flow
 
 Directors log in with OTP:
 
-1. `POST /api/v1/auth/otp/request { email }` — sends a code to email
-2. `POST /api/v1/auth/otp/verify { email, code }` — sets session cookie, returns `{ user, apiKey }`
+1. `POST /api/v1/user/request-otp { email }` — sends a code to email; returns `{ ok, delivery }` (plus `dev_code` when delivery is `console` outside production)
+2. `POST /api/v1/user/verify-otp { email, code, name? }` — returns `{ customer, apiKey }` and mints a fresh API key
 
-Save the `apiKey` in the client and use it for automation.
+Save the `apiKey` in the client and use it for automation (as the `vidfarm-api-key` header). The browser login form uses the session-cookie variants `POST /login/otp/request` and `POST /login/otp/verify` instead.
 
 ## Provider keys
 
 Vidfarm executes many features (smart auto-decompose, editor chat) with the **caller's own AI provider keys**. Directors save keys once via:
 
 - UI: Settings → Provider Keys
-- API: `PUT /api/v1/user/me/provider-keys { openai, gemini, openrouter, perplexity }`
+- API: `POST /api/v1/user/me/provider-keys { provider, secret, label? }` — one key per call; `provider` is `"openai" | "gemini" | "openrouter" | "perplexity"`. The key is validated against the provider before it is saved. List saved keys with `GET /api/v1/user/me/provider-keys`.
 
 Priority: Gemini → OpenAI → OpenRouter. If a director has no keys, smart decompose falls back to a deterministic time-based split.
 
 ## Discover templates
 
-Templates are listed on the Vidfarm homepage under `/hyperframes/`. Each has a slug, a preview MP4, source video metadata, and viral DNA.
+Templates are listed on the Vidfarm homepage and `/discover`. Each has a `template_...` id, a preview MP4, source video metadata, and viral DNA.
 
-- Browser: browse the homepage
-- API: `GET /api/v1/hyperframes` — returns template summaries
+- Browser: browse `/discover`
+- API: `GET /discover/feed` — returns `{ templates: [{ templateId, slugId, title, previewUrl, viralDna, durationSeconds, sourceType, ... }], next_cursor }`
 
 Each template exposes a public preview:
 
-- `GET /hyperframes/:slug` — HTML preview
-- `GET /hyperframes/:slug/composition` — composition HTML
-- `GET /hyperframes/:slug/composition.json` — composition metadata (scenes, captions, viral DNA)
+- `GET /editor/:templateId` — opens the Trackpad Editor for the template (redirects to your fork of it, or to `/login`)
+- `GET /editor/:templateId/composition` — raw composition HTML built from the template's source video
+- `GET /discover/skills/:templateId` — the template's SKILL.md content as JSON (registry templates only)
 
 Directors don't edit templates directly. They fork.
 
@@ -84,19 +88,19 @@ Directors don't edit templates directly. They fork.
 POST /api/v1/compositions
 Content-Type: application/json
 
-{ "source_slug_id": "<template slug>", "title": "Optional title" }
+{ "template_id": "template_<...>", "title": "Optional title" }
 ```
 
-Returns the new fork's metadata:
+`template_id` is required and must start with `template_` (the handler also accepts the same value under the key `source`). Returns the new fork's metadata (201):
 
 ```
-{ "id": "<forkId>", "sourceSlugId": "...", "title": "...", "visibility": "private", "latestVersion": 0, ... }
+{ "fork_id": "<forkId>", "template_id": "template_...", "parent_fork_id": "...", "parent_version": 1, "title": "...", "visibility": "private", "latest_version": 0, "composition_url": "...", "composition_data_url": "...", "versions_url": "...", "role": "owner", "capabilities": { ... } }
 ```
 
-Take the returned `forkId` and open the Trackpad Editor at:
+Take the returned `fork_id` and open the Trackpad Editor at:
 
 ```
-/editor/?fork=<forkId>
+/editor/<templateId>?fork=<forkId>
 ```
 
 The editor loads `composition.html` and `composition.json` from the fork's working state.
@@ -139,7 +143,7 @@ Content-Type: application/json
 
 Two modes:
 
-- **`smart`** — uses the caller's Gemini/OpenAI/OpenRouter key. Samples frames, extracts scenes with labels and viral notes, extracts on-screen captions with positions, and detects viral DNA (hook, retention, payoff). Takes 30-60 seconds. Auto-fires GhostCut for subtitle removal in the background.
+- **`smart`** — uses the caller's Gemini/OpenAI/OpenRouter key. Samples frames, extracts scenes with labels, literal visual **descriptions**, and viral notes, extracts on-screen captions with positions, **transcribes the audio track verbatim** (timestamped segments; Gemini first, OpenAI Whisper fallback; skipped when the video has no audio), and detects viral DNA (hook, retention, payoff). Takes 30-60 seconds. Auto-fires GhostCut for subtitle removal in the background.
 - **`time-slice`** — deterministic equal-duration split. Instant. No AI provider needed.
 
 **Source length cap.** Vidfarm caps auto-decompose (and all inspiration ingest) at **120 seconds** of source video. If the source is longer, the API responds with `400 { ok: false, code: "source_too_long", duration_seconds, max_duration_seconds }` and no scenes are written. Trim the source before forking / ingesting.
@@ -154,24 +158,59 @@ If `ghostcut_pending: true`, poll `POST /api/v1/compositions/:forkId/ghostcut-po
 
 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"`.
 
+## Video context (transcript + scene descriptions)
+
+`GET /api/v1/compositions/:forkId/video-context.json` — read-only, non-billing. Returns everything the smart decompose learned about the source video, so an agent can ground its work in what the video actually **says** and **shows**:
+
+```
+{
+  "ok": true,
+  "status": "ready" | "none",
+  "summary": "...",
+  "duration_seconds": 12.4,
+  "transcript": {
+    "text": "full verbatim transcript",
+    "language": "en",
+    "provider": "gemini",
+    "segments": [{ "start": 0.0, "end": 2.4, "text": "..." }]
+  },
+  "scenes": [{
+    "slug": "hook_reveal",
+    "start": 0, "duration": 2.5,
+    "label": "Hook",
+    "description": "Literal visual description of what's on screen in this scene",
+    "viral_note": "...",
+    "transcript_excerpt": "what is spoken during this scene"
+  }],
+  "viral_dna": { ... }
+}
+```
+
+`status: "none"` means the fork was never smart-decomposed — run `POST /auto-decompose` with `mode: "smart"` first. `transcript` is `null` when the source has no audio track or transcription failed.
+
+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.
+
 ## Publish
 
-Publishing renders the fork's current working state to an MP4 using shared Remotion Lambda.
+Publishing renders the fork's current working state to an MP4 using shared Remotion Lambda. The route is `/export`:
 
 ```
-POST /api/v1/compositions/:forkId/publish
+POST /api/v1/compositions/:forkId/export
 Content-Type: application/json
 
-{ "title": "optional", "version": null, "tracer": "optional-idempotency-key" }
+{ "title": "optional", "version": null, "tracer": "optional-trace-id", "html": "optional HTML to save to working state before rendering" }
 ```
 
-Returns `{ render_id, job_id, snapshot_version }`. Poll:
+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 `/ghostcut-poll` reports done/failed), `412` if the provider-key preflight fails. Poll:
 
 ```
 GET /api/v1/compositions/:forkId/renders/:renderId
 ```
 
-Response includes `{ phase: "RUNNING" | "SUCCEEDED" | "FAILED", progress, output_url, cost_usd }`. On success, `output_url` is the durable MP4 URL.
+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.
 
 Every publish creates an immutable version snapshot at `versions/<N>/composition.html` and `versions/<N>/composition.json`.
 
@@ -181,7 +220,7 @@ Every publish creates an immutable version snapshot at `versions/<N>/composition
 GET /api/v1/compositions/:forkId/versions?limit=100
 ```
 
-Returns the version list with `{ version, reason, message, created_at }`. Reason is `publish`, `clone`, `manual`, or `migration`.
+Returns `{ versions: [{ version, reason, message, created_by, created_at, render_job_id, composition_url, composition_data_url }], next_cursor }`. Reason is `publish`, `clone`, `manual`, or `migration`. To snapshot the working state manually, `POST /api/v1/compositions/:forkId/versions { "message": "optional" }`.
 
 To view a past cut without reverting:
 
@@ -199,12 +238,12 @@ Every fork has a visibility: `private` (default), `unlisted` (legacy), or `publi
 PATCH /api/v1/compositions/:forkId/visibility { "visibility": "public" }
 ```
 
-Public forks are accessible at `/editor/?fork=<forkId>` (view-only for non-owners). Public visibility is the simplest sharing surface.
+Public forks are accessible at `/editor/<templateId>?fork=<forkId>` (view-only for non-owners). Public visibility is the simplest sharing surface.
 
-Fine-grained sharing uses per-user permissions and share links:
+Fine-grained sharing uses per-user permissions and share links (all body fields are snake_case):
 
-- `POST /api/v1/compositions/:forkId/permissions { granteeType, granteeId, role, expiresAt? }` — grant a specific user access. Roles: `viewer`, `editor`, `publisher`.
-- `POST /api/v1/compositions/:forkId/share-links { role, expiresAt? }` — create a token URL. Anyone with the token gets the role.
+- `POST /api/v1/compositions/:forkId/permissions { grantee_email | grantee_customer_id, role, expires_at? }` — grant a specific registered user access. Exactly one of `grantee_email` or `grantee_customer_id` is required. Roles: `viewer`, `editor`, `publisher`. Returns `{ permission_id, fork_id, grantee_type, grantee_id, role, granted_by, expires_at, created_at }`.
+- `POST /api/v1/compositions/:forkId/share-links { role, expires_at? }` — create a token URL. Anyone with the token gets the role. Returns `{ token, share_url, role, expires_at, ... }`.
 - `GET /api/v1/compositions/shared/:token` — access via share link
 - `DELETE /api/v1/compositions/:forkId/permissions/:permissionId` — revoke a grant
 - `DELETE /api/v1/compositions/:forkId/share-links/:token` — revoke a link
@@ -214,10 +253,13 @@ Fine-grained sharing uses per-user permissions and share links:
 Directors can clone another fork (their own or a shared one) as a new starting point:
 
 ```
-POST /api/v1/compositions { "parent_fork_id": "<forkId>", "parent_version": <N or omit for latest> }
+POST /api/v1/compositions/:forkId/clone
+Content-Type: application/json
+
+{ "parent_version": "<N or omit for latest>", "title": "optional" }
 ```
 
-The new fork inherits the parent's HTML/JSON at the specified version and creates a version-1 snapshot with `reason: "clone"`.
+The `:forkId` in the path is the fork being cloned. The new fork inherits the parent's HTML/JSON at the specified version and creates a version-1 snapshot with `reason: "clone"`.
 
 ## Delete a fork
 
@@ -231,8 +273,8 @@ Soft-delete only. The fork's `deletedAt` is set. Versions and share links are pr
 
 Vidfarm charges directly in USD from the caller's wallet. There are no credits.
 
-- **Wallet top-up** — Stripe checkout via `POST /api/v1/user/me/wallet/checkout`
-- **Balance** — `GET /api/v1/user/me/wallet`
+- **Wallet top-up** — Stripe checkout via the Settings UI, backed by `POST /settings/wallet/funding-link` (browser session; returns `{ checkout_url, client_reference_id }`)
+- **Balance & history** — shown on the Settings page; billing events via `GET /u/:customerId/settings/wallet/events` (browser session). There is no `/api/v1/user/me/wallet` REST endpoint.
 - **Cost anchors**:
   - Publish (Remotion Lambda render): typically $0.01 – $0.10 per MP4 depending on length/resolution
   - Auto-decompose smart mode: pass-through of caller's AI provider spend
@@ -249,14 +291,14 @@ Framing:
 
 For agents that operate Vidfarm headlessly, the typical loop is:
 
-1. `POST /api/v1/compositions { source_slug_id }` → fork
+1. `POST /api/v1/compositions { template_id }` → fork
 2. `PUT /api/v1/compositions/:forkId/composition.html` → apply edits
 3. `PATCH /api/v1/compositions/:forkId/composition.json` → update metadata
-4. `POST /api/v1/compositions/:forkId/publish { tracer }` → render
+4. `POST /api/v1/compositions/:forkId/export { tracer }` → render
 5. Poll `GET /api/v1/compositions/:forkId/renders/:renderId` until `SUCCEEDED`
-6. Use `output_url` in the next stage
+6. Use `outputUrl` in the next stage
 
-Always send a stable `tracer` on publish to make retries idempotent.
+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.
 
 ## Local dev loop with `vidfarm-devcli`
 
@@ -284,7 +326,7 @@ The dev source is persisted in `localStorage.VIDFARM_DEV_SOURCE`, so you don't n
 
 - Do **not** manipulate composition HTML by string concatenation. Always parse, edit, and re-serialize the DOM. The editor and runtime rely on `data-start`, `data-duration`, `data-track-index`, `data-hf-id`, `data-composition-id` attributes being well-formed.
 - Do **not** save AI provider keys in the composition HTML or JSON. They belong in the caller's provider-keys record.
-- Do **not** call Remotion directly. Publishing goes through `/publish` so billing, retries, cost caps, and Lambda quotas are enforced.
+- Do **not** call Remotion directly. Publishing goes through `POST /api/v1/compositions/:forkId/export` so billing, retries, cost caps, and Lambda quotas are enforced.
 - Do **not** re-invent scene manipulation as REST commands (`AddScene`, `RemoveScene`, `UpdateSceneField`). The Trackpad Editor is the surface for that. The pattern is: mutate the composition HTML DOM, PUT it back.
 
 ## Alpha posture
@@ -292,7 +334,7 @@ The dev source is persisted in `localStorage.VIDFARM_DEV_SOURCE`, so you don't n
 Vidfarm is in active development. Endpoints, response shapes, and the editor UI can change. When something behaves unexpectedly:
 
 - prefer `GET /api/v1/compositions/:forkId` over cached state
-- treat `latestVersion` as the source of truth for what the editor loaded
+- treat `latest_version` as the source of truth for what the editor loaded
 - if a publish fails, check `renders/:renderId` for the error phase and stderr before retrying
 
 ## Default assistance pattern
@@ -300,7 +342,7 @@ Vidfarm is in active development. Endpoints, response shapes, and the editor UI
 When a director asks "make me a video", the default sequence is:
 
 1. Ask what source material and what template style they want
-2. Discover a matching template with `GET /api/v1/hyperframes`
+2. Discover a matching template with `GET /discover/feed`
 3. Fork it
 4. If they want an entirely new source video, guide them to `auto-decompose` first
 5. Open the Trackpad Editor and let them make edits
@@ -321,7 +363,7 @@ Example:
 
 ```bash
 curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/remove-background" \
-  -H "authorization: Bearer $VIDFARM_API_KEY" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
   -H "content-type: application/json" \
   -d '{"source_image_url": "https://cdn.example.com/photo.jpg"}'
 ```
@@ -332,6 +374,7 @@ Apply subtle camouflage transforms (zoom, tilt, rotate, saturation, playback spe
 
 - `POST /api/v1/primitives/media/dedupe`
 - Body: `{ "tracer": "...", "payload": { ...fields... }, "webhook_url"?: "..." }`
+  - Note: webhook delivery is not yet active — `webhook_url` is accepted and persisted on the job but never fired. Poll the job endpoints (`GET /api/v1/primitives/jobs/:jobId`) for completion.
 - Response: standard primitive job. Poll to completion, then read `primary_file_url` (also `video.file_url` for MP4 or `image.file_url` for stills)
 - Billing: metered as a Remotion render (via `remotion_lambda` on prod, local fallback in dev)
 
@@ -362,7 +405,7 @@ Video example (camouflage a reused clip):
 
 ```bash
 curl -X POST "$VIDFARM_BASE/api/v1/primitives/media/dedupe" \
-  -H "authorization: Bearer $VIDFARM_API_KEY" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
   -H "content-type: application/json" \
   -d '{
     "tracer": "dedupe-2026-07-01-abc",
@@ -388,7 +431,7 @@ Image example:
 
 ```bash
 curl -X POST "$VIDFARM_BASE/api/v1/primitives/media/dedupe" \
-  -H "authorization: Bearer $VIDFARM_API_KEY" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
   -H "content-type: application/json" \
   -d '{
     "tracer": "dedupe-still-01",
@@ -400,3 +443,39 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/media/dedupe" \
     }
   }'
 ```
+
+## Brainstorm primitives
+
+The `brainstorm/*` primitives are the strategy toolkit. They are reusable, billable AI reasoning steps — the same family the AI Copilot exposes as chip suggestions. Treat **product placement** as a first-class member of this family, right alongside angles and hooks:
+
+- `POST /api/v1/primitives/brainstorm/coldstart` — `{ payload: { user_message } }` → foundational questionnaire for a customer starting from zero.
+- `POST /api/v1/primitives/brainstorm/awareness_stages` — `{ payload: { offer_description } }` → which Eugene-Schwartz awareness stages to target first.
+- `POST /api/v1/primitives/brainstorm/angles` — `{ payload: { offer_description, problem_awareness, solution_awareness } }` → persuasive angles.
+- `POST /api/v1/primitives/brainstorm/hooks` — `{ payload: { offer_description } }` → many TikTok-native hooks.
+- `POST /api/v1/primitives/brainstorm/product_placement` — `{ payload: { source_video_url, offer_description } }` → **watches the video** and returns concrete, timestamped opportunities to natively place the product.
+
+### Primitive: brainstorm_product_placement
+
+Analyze a source video and identify where a product can be organically placed so it feels native rather than bolted on. This is a **multimodal** primitive: it feeds the actual video to a vision-capable model, so prefer a saved **Gemini** key (native video understanding). OpenRouter multimodal models also work; plain OpenAI chat keys cannot watch video.
+
+- `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.
+  - `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`.
+
+You can also satisfy a quick, conversational product-placement question by reasoning over an attached video directly instead of calling this primitive — use the primitive when you want a durable, structured, billable artifact the customer can save and reuse.
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/brainstorm/product_placement" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{
+    "tracer": "product-placement-01",
+    "payload": {
+      "source_video_url": "https://cdn.example.com/source.mp4",
+      "offer_description": "A $29/mo AI meal-planning app for busy parents."
+    }
+  }'
+```

package/SKILL.platform.md

@@ -66,7 +66,8 @@ compositions/forks/<forkId>/
 │   ├── composition.html       # current editor state
 │   ├── composition.json       # current metadata (scenes, captions, viral DNA)
 │   ├── manifest.json          # fork identity + genealogy pointer
-│   └── ghostcut.json          # GhostCut subtitle-removal task state (optional)
+│   ├── ghostcut.json          # GhostCut subtitle-removal task state (optional)
+│   └── smart-decompose.json   # raw smart-decompose snapshot: scenes (with visual descriptions), captions, viral DNA, audio transcript (optional)
 └── versions/<version>/
     ├── composition.html
     ├── composition.json
@@ -183,13 +184,13 @@ The editor is a single monolithic React component (~9k lines). It builds cleanly
 
 Publish flow:
 
-1. Client `POST /api/v1/compositions/:forkId/publish`
+1. Client `POST /api/v1/compositions/:forkId/export` (the route is named `export`; the concept is "publish")
 2. API stamps `data-composition-id="<forkId>@v<N>"` into the composition HTML, PUTs the stamped HTML to working, and reads composition.json
 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 primitive Lambda uploads the composition as a Remotion site, calls `renderMediaOnLambda` with the shared Remotion render Lambda ARN, waits for the MP4 to land in S3
 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 `{ phase, progress, output_url, cost_usd }`
+7. Client polls `GET /api/v1/compositions/:forkId/renders/:renderId` for `{ status: "RUNNING" | "SUCCEEDED" | "FAILED", progress, outputUrl, cost }` (see `adaptJobToPublishStatus` in `src/app.ts`)
 
 The Remotion Lambda is **shared across all templates and forks** — it's an infrastructure primitive, not a per-template deployment. Its ARN is passed to the Vidfarm stack as an env var.
 
@@ -198,9 +199,17 @@ The Remotion Lambda is **shared across all templates and forks** — it's an inf
 `POST /api/v1/compositions/:forkId/auto-decompose` splits a raw source video into a Trackpad-editable composition. Two modes:
 
 - **`time-slice`** (deterministic) — `src/hyperframes/composition.ts`'s `decomposeUndecomposedComposition()` splits the source duration into N equal-length scenes, wraps each in a `<div data-vf-timeline-proxy="video">` layer with `data-start`/`data-duration`/`data-playback-start`. Instant. No AI.
-- **`smart`** (AI) — `src/services/hyperframes.ts`'s `smartDecomposeVideo()` downloads the source, samples frames, calls Gemini/OpenAI/OpenRouter vision (in priority order) using the caller's saved keys, extracts scenes with labels and viral notes, extracts on-screen captions with position, and generates viral DNA. Then it also submits an async **GhostCut** subtitle-removal task if the source has hardcoded subs. Takes 30-60s + async ghostcut poll.
+- **`smart`** (AI) — `src/services/hyperframes.ts`'s `smartDecomposeVideo()` downloads the source, samples frames, calls Gemini/OpenAI/OpenRouter vision (in priority order) using the caller's saved keys, extracts scenes with labels, literal visual **descriptions**, and viral notes, extracts on-screen captions with position, and generates viral DNA. It also demuxes the audio track to WAV and **transcribes it verbatim** with timestamped segments (`transcribeAudioWithFallback()`: Gemini inline-audio first, OpenAI Whisper fallback; non-fatal — a silent video or transcription failure yields `transcript: null`). Then it also submits an async **GhostCut** subtitle-removal task if the source has hardcoded subs. Takes 30-60s + async ghostcut poll.
 
-Both modes update the composition.html and composition.json in place, and create a fork version snapshot with `reason: "manual"`.
+Both modes update the composition.html and composition.json in place, and create a fork version snapshot with `reason: "manual"`. Smart mode additionally persists the raw result — scenes with descriptions, captions, viral DNA, and the transcript — to `working/smart-decompose.json`.
+
+### Video context (transcript + scene descriptions)
+
+`GET /api/v1/compositions/:forkId/video-context.json` assembles a read-only, non-billing view over `smart-decompose.json`: the full verbatim transcript (`{ text, language, segments[] }`), every scene with its literal visual `description` and a computed `transcript_excerpt` (transcript segments overlapping the scene's time window), plus summary and viral DNA. Returns `{ status: "none" }` for forks that were never smart-decomposed. Same surface, three consumers:
+
+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.
 
 **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.
 
@@ -258,7 +267,7 @@ The billing Lambda has its own custom domain because Stripe webhooks require a s
 
 There are two kinds of things directors can fork:
 
-1. **Draft templates** (`/hyperframes/:slug`) — pre-decomposed compositions checked into the repo under `templates/vidfarm_template_XXXX/`. Each has a `composition.html`, `composition.json`, `template.config.json`, a `SKILL.md`, and a `src/` if it needs custom Remotion.
+1. **Draft templates** — pre-decomposed compositions checked into the repo under `templates/vidfarm_template_XXXX/`. Each has a `composition.html`, `composition.json`, `template.config.json`, a `SKILL.md`, and a `src/` if it needs custom Remotion. Registered templates open in the browser at `/editor/:templateId` (there is no `/hyperframes/:slug` route).
 2. **Submitted videos** — raw uploads from directors, decomposed on demand via auto-decompose.
 
 Templates are static. Compositions/forks are the mutable working copies.
@@ -291,10 +300,10 @@ CDK stacks are under `infra/cdk/`:
 Deploy commands are in `package.json`:
 
 - `npm run cdk:synth:staging-serverless`
-- `npm run cdk:deploy:staging-serverless`
-- `npm run cdk:deploy:prod`
+- `npm run cdk:deploy:staging-serverless` (and `npm run cdk:deploy:staging-serverless:hotswap` for Lambda-code-only iteration)
+- `npm run cdk:deploy:prod-serverless` (and `npm run cdk:deploy:prod-serverless:hotswap`)
 
-Never call bare `cdk deploy`. Always go through the npm scripts so the correct `.env.<stage>` is loaded.
+Never call bare `cdk deploy`. Always go through the npm scripts — the `cdk:*` scripts load `.env.<stage>` via `dotenv-cli` (`dotenv -e .env.<stage> -- npx aws-cdk ...`) and pick the right stack app.
 
 Deploy order: **staging first**, then production. Never skip staging.
 
@@ -319,7 +328,7 @@ Top-level:
 - `templates/` — draft template sources
 - `auto-create-hyperframe-templates/` — extractor prompts / schemas for new template creation
 - `scripts/` — one-shot ops scripts and migration scripts
-- `data/` — local dev SQLite + storage (gitignored)
+- `data/` — local dev storage (gitignored). Also holds leftover `*.sqlite` / `vidfarm.db` files from the retired SQLite/EC2 era — the runtime no longer reads SQLite anywhere; DynamoDB is the only database.
 - `.env.staging`, `.env.production` — stage config (gitignored)
 
 Legacy but still active:
@@ -337,7 +346,7 @@ Legacy but still active:
 
 ## Where to look for things
 
-- Composition endpoints — `src/app.ts` under `COMPOSITIONS_PREFIX` (~line 6970+)
+- Composition endpoints — `src/app.ts`: grep for `COMPOSITIONS_PREFIX` (the block runs from `app.post(COMPOSITIONS_PREFIX` fork creation through the `versions` routes; line numbers drift, always grep the symbol)
 - Fork CRUD & permissions — `src/services/serverless-records.ts`, `src/services/fork-access.ts`
 - Storage keys + public-read prefix list — `src/services/storage.ts`
 - Fork manifest.json helper — `src/services/fork-manifest.ts`

package/dist/src/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 // vidfarm-devcli — thin CLI that pairs a local composition directory with the
@@ -12,6 +12,7 @@ const HELP = `vidfarm-devcli — local editor bridge for the Vidfarm Trackpad Ed
 
 Usage:
   vidfarm-devcli <template_id> [options]        Start local editor session
+  vidfarm-devcli publish <template_id> [opts]   Push local composition to your fork
   vidfarm-devcli dev-serve [options]            Serve an existing local dir only
   vidfarm-devcli --help                         Show this help
 
@@ -24,6 +25,14 @@ Options (edit mode):
   --share <token>     Share token for a shared fork (public read)
   --refetch           Overwrite local composition files with the latest remote copy
 
+Options (publish mode):
+  --dir <path>        Local composition directory (default: .vidfarm/<template_id>)
+  --host <url>        Vidfarm host to publish to (default: ${DEFAULT_HOST})
+  --fork <id>         Fork id to publish into (default: auto-resolve for the current user)
+  --api-key <key>     Vidfarm API key (or set VIDFARM_API_KEY) — required to write
+  --message <text>    Optional message attached to the published version snapshot
+  --no-snapshot       Only update the working copy; skip the version snapshot
+
 Options (dev-serve mode):
   --dir <path>        Directory to serve (default: current dir)
   --port <n>          Port to listen on (default: ${DEFAULT_PORT})
@@ -48,6 +57,10 @@ async function main() {
         await runEditCommand(argv.slice(1));
         return;
     }
+    if (command === "publish") {
+        await runPublishCommand(argv.slice(1));
+        return;
+    }
     if (!command.startsWith("-")) {
         // Positional template id → default `edit` command.
         await runEditCommand(argv);
@@ -100,6 +113,147 @@ async function runEditCommand(argv) {
     const { runDevServeCommand } = await import("./dev-serve.js");
     await runDevServeCommand(["--dir", rootDir, "--port", String(port)]);
 }
+async function runPublishCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            dir: { type: "string" },
+            host: { type: "string", default: DEFAULT_HOST },
+            fork: { type: "string" },
+            "api-key": { type: "string" },
+            share: { type: "string" },
+            message: { type: "string" },
+            "no-snapshot": { type: "boolean", default: false }
+        }
+    });
+    const templateId = parsed.positionals[0];
+    if (!templateId && !parsed.values.dir) {
+        throw new Error(`publish requires a template id (or --dir).\n\n${HELP}`);
+    }
+    const host = trimTrailingSlash(parsed.values.host);
+    const apiKey = parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY;
+    const shareToken = parsed.values.share;
+    if (!apiKey && !shareToken) {
+        throw new Error("publish needs credentials to write. Pass --api-key <key> or set VIDFARM_API_KEY.");
+    }
+    const rootDir = path.resolve(process.cwd(), parsed.values.dir ?? path.join(".vidfarm", templateId ?? ""));
+    const forkId = parsed.values.fork ?? (templateId
+        ? await resolveForkId({ host, templateId, apiKey, shareToken })
+        : null);
+    if (!forkId) {
+        throw new Error(`Could not resolve a fork id. Pass --fork <id>${templateId ? "" : " (no template id was given to auto-resolve)"}.`);
+    }
+    const htmlPath = path.join(rootDir, "composition.html");
+    if (!existsSync(htmlPath)) {
+        throw new Error(`No composition.html at ${htmlPath}. Run \`vidfarm-devcli ${templateId ?? "<template>"} --fork ${forkId}\` first, or pass --dir.`);
+    }
+    const html = readFileSync(htmlPath, "utf8");
+    if (!html.includes("data-composition-id=")) {
+        throw new Error("composition.html is missing data-composition-id — refusing to publish a malformed composition.");
+    }
+    const jsonPath = path.join(rootDir, "composition.json");
+    const json = existsSync(jsonPath) ? readFileSync(jsonPath, "utf8") : null;
+    if (json !== null) {
+        try {
+            JSON.parse(json || "{}");
+        }
+        catch (error) {
+            throw new Error(`composition.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const auth = { apiKey, shareToken };
+    console.log(`[vidfarm] publishing ${forkId} → ${host}`);
+    // 1) Working copy: composition.html (required) then composition.json (if any).
+    await putComposition(`${host}/api/v1/compositions/${encodeURIComponent(forkId)}/composition.html`, "PUT", html, "text/html; charset=utf-8", auth);
+    console.log(`[vidfarm] pushed composition.html (${Buffer.byteLength(html)} bytes)`);
+    if (json !== null) {
+        await putComposition(`${host}/api/v1/compositions/${encodeURIComponent(forkId)}/composition.json`, "PATCH", json, "application/json", auth);
+        console.log(`[vidfarm] pushed composition.json (${Buffer.byteLength(json)} bytes)`);
+    }
+    // 2) Optional immutable version snapshot.
+    let publishedVersion = null;
+    if (!parsed.values["no-snapshot"]) {
+        const snapshot = await postJson(`${host}/api/v1/compositions/${encodeURIComponent(forkId)}/versions`, { message: parsed.values.message ?? null }, auth);
+        publishedVersion = typeof snapshot?.version === "number" ? snapshot.version : null;
+        console.log(`[vidfarm] snapshotted version ${publishedVersion ?? "(unknown)"}`);
+    }
+    printPublishBanner({ forkId, dir: rootDir, host, version: publishedVersion, snapshotted: !parsed.values["no-snapshot"] });
+}
+// Writes one composition file to the remote fork. Unlike the edit-mode
+// fetchCompositionFiles (which tolerates misses), publish MUST fail loudly — a
+// silent skip would make the user think their work is safely stored when it is
+// not.
+async function putComposition(url, method, body, contentType, auth) {
+    const res = await fetch(url, {
+        method,
+        headers: { ...buildAuthHeaders(auth), "content-type": contentType },
+        body
+    });
+    if (!res.ok) {
+        throw new Error(await describeHttpFailure(res, url));
+    }
+}
+async function postJson(url, body, auth) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { ...buildAuthHeaders(auth), "content-type": "application/json" },
+        body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+        throw new Error(await describeHttpFailure(res, url));
+    }
+    return await res.json().catch(() => ({}));
+}
+async function describeHttpFailure(res, url) {
+    let detail = "";
+    try {
+        const text = await res.text();
+        if (text) {
+            try {
+                const parsed = JSON.parse(text);
+                detail = parsed.error ? ` — ${parsed.error}${parsed.type ? ` (${parsed.type})` : ""}` : ` — ${text.slice(0, 300)}`;
+            }
+            catch {
+                detail = ` — ${text.slice(0, 300)}`;
+            }
+        }
+    }
+    catch {
+        // ignore body read failure
+    }
+    const hint = res.status === 401 || res.status === 403
+        ? " Check your --api-key and that you own (or have edit rights on) this fork."
+        : res.status === 413
+            ? " The composition exceeds the server size limit."
+            : res.status === 429
+                ? " You are being rate-limited; wait and retry."
+                : "";
+    return `Publish failed: ${res.status} ${res.statusText}${detail} (${url}).${hint}`;
+}
+function printPublishBanner(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}  Published to Vidfarm${reset}`);
+    console.log(line);
+    console.log(`  fork        ${input.forkId}`);
+    console.log(`  local dir   ${input.dir}`);
+    if (input.snapshotted) {
+        console.log(`  version     ${input.version ?? "(unknown)"}`);
+    }
+    else {
+        console.log(`  version     ${dim}skipped (--no-snapshot)${reset}`);
+    }
+    console.log(`  live html   ${cyan}${input.host}/api/v1/compositions/${input.forkId}/composition.html${reset}`);
+    console.log(line);
+    console.log("");
+}
 async function resolveForkId(input) {
     // /editor/<template_id> issues a 302 → /editor/<template_id>?fork=<id>
     // whenever the caller (or the template's default fork) has one. Follow the
@@ -127,7 +281,10 @@ async function resolveForkId(input) {
     return null;
 }
 async function fetchCompositionFiles(input) {
-    const files = ["composition.html", "composition.json", "manifest.json"];
+    // 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"];
     for (const filename of files) {
         const target = path.join(input.dir, filename);
         if (existsSync(target) && !input.refetch) {
@@ -147,10 +304,12 @@ async function fetchCompositionFiles(input) {
 }
 function buildAuthHeaders(input) {
     const headers = { accept: "text/html,application/json" };
+    // The server reads exactly these header names (see requireAuth and
+    // readShareToken in src/app.ts) — Bearer/authorization is not supported.
     if (input.apiKey)
-        headers.authorization = `Bearer ${input.apiKey}`;
+        headers["vidfarm-api-key"] = input.apiKey;
     if (input.shareToken)
-        headers["x-vidfarm-share-token"] = input.shareToken;
+        headers["vidfarm-share-token"] = input.shareToken;
     return headers;
 }
 function printEditorBanner(input) {

package/dist/src/dev-serve.js

@@ -11,7 +11,11 @@ import { parseArgs } from "node:util";
 const CORS_HEADERS = {
     "access-control-allow-origin": "*",
     "access-control-allow-methods": "GET,PUT,PATCH,POST,OPTIONS",
-    "access-control-allow-headers": "content-type,authorization",
+    // 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
@@ -155,7 +159,14 @@ function handleRequest(req, res, ctx) {
     const url = new URL(req.url ?? "/", `http://localhost`);
     const pathname = url.pathname;
     if (method === "OPTIONS") {
-        res.writeHead(204, CORS_HEADERS);
+        // 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;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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": {
@@ -39,11 +39,11 @@
     "build": "npm run build:frontend && npm run build:hyperframes-editor && node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
     "start": "node --import ./dist/src/instrument.js --enable-source-maps dist/src/index.js",
     "check": "tsc -p tsconfig.json --noEmit",
-    "cdk:synth": "npm run build && npx aws-cdk synth --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",
-    "cdk:deploy": "npm run build && npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",
-    "cdk:deploy:prod-serverless": "npm run build && npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",
-    "cdk:synth:staging-serverless": "npm run build && npx aws-cdk synth --app 'node dist/infra/cdk/bin/vidfarm-serverless-staging.js'",
-    "cdk:deploy:staging-serverless": "npm run build && npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-serverless-staging.js'",
+    "cdk:deploy:prod-serverless": "npm run build && dotenv -e .env.production -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",
+    "cdk:synth:staging-serverless": "npm run build && dotenv -e .env.staging -- npx aws-cdk synth --app 'node dist/infra/cdk/bin/vidfarm-serverless-staging.js'",
+    "cdk:deploy:staging-serverless": "npm run build && dotenv -e .env.staging -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-serverless-staging.js'",
+    "cdk:deploy:staging-serverless:hotswap": "npm run build && dotenv -e .env.staging -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-serverless-staging.js' --hotswap-fallback --require-approval never",
+    "cdk:deploy:prod-serverless:hotswap": "npm run build && dotenv -e .env.production -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js' --hotswap-fallback --require-approval never",
     "prepack": "npm run build"
   },
   "dependencies": {
@@ -92,6 +92,7 @@
     "@types/react-dom": "^18.3.7",
     "aws-cdk-lib": "^2.196.0",
     "constructs": "^10.4.2",
+    "dotenv-cli": "^11.0.0",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "zustand": "^5.0.13"