@mevdragon/vidfarm-devcli 0.20.6 → 0.20.8

package/SKILL.platform.md

@@ -1,432 +0,0 @@
----
-name: vidfarm-platform
-description: Vidfarm platform architecture reference. Use this for questions about how compositions, forks, versions, storage, DynamoDB records, the Trackpad Editor runtime, HyperFrames render, editor-chat, primitives, and billing fit together. This is not a director skill (see SKILL.director.md) and not a runbook — it explains the system.
----
-
-# Vidfarm Platform Architecture
-
-Vidfarm is a **serverless composition studio** for short-form video. Directors fork templates, edit compositions on a timeline (the Trackpad Editor), publish MP4s via HyperFrames render (shared cloud Lambda fan-out, or free in-process render on a local serve box), and share results.
-
-This document is the architectural reference — what runs where, what data lives where, and how the pieces connect. Use it when planning changes, debugging cross-cutting behavior, or onboarding to the platform.
-
-For customer-facing usage patterns, see `SKILL.director.md`.
-
-## Runtime shape
-
-Vidfarm runs entirely on AWS serverless:
-
-- **API** — a single Hono app deployed as a container Lambda behind an API Gateway custom domain per stage
-- **Editor Chat** — a separate Lambda + custom domain for streaming AI editor sessions
-- **Primitive Media** — a separate Lambda + custom domain for standalone media primitives (image gen, video generation, etc.)
-- **Ready Post Zip** — a separate Lambda + custom domain for scheduled/approved-post ZIP downloads
-- **Billing** — a separate Lambda + custom domain for Stripe webhooks, wallet top-ups, and idempotent charge processing
-- **Job Runner** — a Lambda invoked by the API to execute template operations
-- **Job Sweeper** — a scheduled Lambda that stalls / retries / cleans up in-flight jobs
-
-Stages:
-
-- `staging` — `staging.vidfarm.cc` (+ sibling subdomains for billing, editor-chat, primitive-media, zip)
-- `production` — `vidfarm.cc`
-
-Every stage is a separate CDK stack with fully separate DynamoDB tables, S3 buckets, Lambdas, and DNS.
-
-There is no EC2, no SQLite, no long-lived worker. Everything scales to zero at idle.
-
-## Data model
-
-### DynamoDB — single-table
-
-One main table per stage: `VidfarmMainTable`. Partitioned by `entity_type`. Records include:
-
-- `customer` — director account, wallet, provider keys reference, timestamps
-- `customer_api_key` — API key hash + salt
-- `template` — imported template registration (slug, source repo, active release pointer)
-- `template_release` — a specific artifact for a template
-- `job` — an in-flight or completed job execution
-- `job_log_event` — structured log lines per job (transient — pruned)
-- `api_call_history` — request audit trail (transient)
-- `editor_chat_message` — chat history (transient)
-- `serverless_record#composition_fork` — an editable composition fork
-- `serverless_record#fork_version` — an immutable version snapshot for a fork
-- `serverless_record#fork_permission` — a per-user grant on a fork
-- `serverless_record#fork_share_link` — a share-token URL for a fork
-- `submitted_video` — a source video uploaded by a director
-- `provider_key_lease` — short-lived AI key leases for job runners
-- `billing_event` — wallet transactions and Stripe events
-
-Query patterns use GSIs on `customerId`, `forkId`, `granteeId`, `slug`, and `status`.
-
-### S3 — composition storage
-
-Bucket per stage. Layout is **ownership-agnostic** — the customerId does not appear in the S3 key.
-
-```
-compositions/forks/<forkId>/
-├── working/
-│   ├── 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)
-│   └── smart-decompose.json   # raw smart-decompose snapshot: scenes (with visual descriptions), captions, viral DNA, audio transcript (optional)
-└── versions/<version>/
-    ├── composition.html
-    ├── composition.json
-    └── manifest.json          # frozen version manifest
-```
-
-The `compositions/forks/*` prefix is **public-read** in the bucket resource policy — any client with a `forkId` can fetch `composition.html` / `composition.json` / `manifest.json` directly from S3 without a Lambda proxy hop. The `forkId` is treated as an unguessable bearer token (revoking share = generating a new fork). Write access is still gated at the API by `assertForkAccess(..., "edit" | "publish" | "share" | "delete")`. See `isPublicStorageKey` in `src/services/storage.ts`.
-
-Additional prefixes:
-
-- `renders/vidfarm/<slug>/<render-id>/output.mp4` — published MP4s
-- `submissions/<videoId>/...` — raw source video uploads
-- `template-assets/<slug>/...` — template media
-- `user-attachments/<customerId>/...` — chat panel uploads (only ownership-keyed area remaining)
-- `users/<customerId>/temporary/<folder>/<fileId>/<name>` — ephemeral temp-store uploads (`POST /me/temporary-files/upload`, 90-day TTL). The devcli namescopes throwaway media under a `temp/` folder here so scratch assets stay quarantined and purgeable rather than polluting the durable library.
-- `users/local-media/<uuid>/<name>` — **local-only**, never on S3. On a `vidfarm serve` box (`STORAGE_DRIVER=local`), `vidfarm place --src ./file` copies a local media file into the box's disk store under this key and references it by the box's own `http://localhost:<port>/storage/<key>` URL, so power users can bulk-build compositions from local assets and render in-process for free without uploading anything to S3. These localhost URLs only resolve against the serve box that holds the file (local render/preview only). See `importLocalMediaToServeStore` / `resolvePlaceableMediaSrc` in `src/cli.ts`.
-
-Old ownership-keyed composition paths (`compositions/users/<customerId>/forks/...`) were migrated away by `scripts/migrate-compositions-to-ownership-agnostic.ts`. Old `decomposition.json` was renamed to `composition.json` by `scripts/migrate-decomposition-to-composition.ts`. Forks written before the manifest rollout won't have `manifest.json` until their next mutation — reads must tolerate 404.
-
-### manifest.json
-
-Written next to `composition.html` / `composition.json` in both `working/` and `versions/<n>/`. Lets clients traverse fork genealogy and jump between versions without a DynamoDB round-trip.
-
-```json
-{
-  "fork_id": "...",
-  "customer_id": "...",
-  "is_working": true,
-  "version": null,
-  "latest_version": 3,
-  "parent_fork_id": "fork_abc" | null,
-  "parent_version": 2 | null,
-  "source_slug_id": "...",
-  "source_video_id": "..." | null,
-  "visibility": "private" | "unlisted" | "public",
-  "title": "...",
-  "composition_url": "https://.../composition.html",
-  "composition_json_url": "https://.../composition.json",
-  "manifest_url": "https://.../manifest.json",
-  "parent_manifest_url": "https://.../versions/2/manifest.json" | null,
-  "created_at": "...",
-  "updated_at": "..."
-}
-```
-
-Writes are centralized in `writeForkManifest()` in `src/services/fork-manifest.ts`. `snapshotForkVersion()` writes both the version manifest AND refreshes the working manifest (so `latest_version` stays in sync). Every working-only mutation site (create, PUT html, PATCH json, visibility, decompose, ghostcut swap, export) also calls it.
-
-## Composition model
-
-A composition is a single HTML document plus a JSON sidecar.
-
-**composition.html** is a self-contained document. Top-level structure:
-
-```html
-<div data-composition-id="<forkId>@v<version>" data-viral-dna="{...}">
-  <div data-vf-timeline-proxy="video" data-src="..." data-start="0" data-duration="12" />
-  <div data-hf-id="clip_1" data-layer-kind="video"
-       data-start="0" data-duration="3.5" data-track-index="0"
-       data-playback-start="0.25" data-src="...">
-    ...
-  </div>
-  <div data-hf-id="caption_1" data-layer-kind="caption"
-       data-start="0.5" data-duration="2.0" data-track-index="1"
-       style="position:absolute;left:5%;top:60%;...">
-    HOOK LINE
-  </div>
-  <!-- ANIMATED caption cue (word-by-word): the layer carries the preset +
-       per-cue vars; each word is a span whose inline animation-delay/duration
-       IS its spoken window relative to the layer's data-start. -->
-  <div data-hf-id="element_cap_x_0" data-layer-kind="caption"
-       data-caption-animation="highlight-pop" data-caption-uppercase="1"
-       data-start="3.0" data-duration="1.8" data-track-index="2"
-       style="...;--vf-cap-hl:#7C3AED;text-transform:uppercase;overflow:visible">
-    <span data-vf-text-lines="true"><span data-vf-text-inline="true">
-      <span data-cap-word="true" data-word-start="0" data-word-end="0.4"
-            style="animation-delay:0s;animation-duration:0.4s">Stop</span>
-      <span data-cap-word="true" data-word-start="0.4" data-word-end="1.1"
-            style="animation-delay:0.4s;animation-duration:0.7s">scrolling</span>
-    </span></span>
-  </div>
-  <!-- more layers... -->
-  <script type="module"><!-- composition-runtime.ts injected inline --></script>
-</div>
-```
-
-**composition.json** carries the semantic metadata parsed once at auto-decompose time and used by the editor sidebar, chat context, and publish payload:
-
-```json
-{
-  "summary": "...",
-  "scenes": [{ "slug": "hook_reveal", "start": 0, "duration": 1.5, "label": "...", "viral_note": "..." }],
-  "captions": [{ "slug": "caption_1", "text": "...", "start": 0, "duration": 1.5, "x": 5, "y": 60 }],
-  "viralDna": { "hook": "...", "retention": "...", "payoff": "...", "emotional_punch": { "core_emotion": "...", "tone": "...", "mechanism": "...", "humor": "...", "delivery": "...", "preserve": [...] }, "preserve": [...], "avoid": [...] },
-  "width": 1080,
-  "height": 1920,
-  "durationSeconds": 10.5,
-  "source_assets": [{ "type": "video", "url": "...", "width": ..., "height": ..., "duration": ... }]
-}
-```
-
-All three files (`composition.html`, `composition.json`, `manifest.json`) are treated as immutable per version. The working state is mutable.
-
-## Composition runtime
-
-`src/composition-runtime.ts` generates a browser-side script that gets injected into every composition HTML. It provides:
-
-- **Playback control** — reads all `[data-start][data-duration][data-track-index]` layers, toggles their visibility based on the current time, and syncs media element `currentTime` per clip
-- **Player adapter** — exposes `window.__player = { play(), pause(), seek(t), setTime(t), duration, playing, playbackRate, previewMuted, refreshClips() }` for the editor to control the iframe
-- **Media coordination** — respects `data-playback-start`, `data-volume`, and clip-specific mute
-- **Selection sync** — listens for `postMessage({ source: "hf-parent", ... })` from the parent editor to highlight/deselect clips
-- **Origin-scoped messaging** — the runtime rejects inbound `message` events unless `event.source === window.parent`, so sibling iframes / popups cannot spoof play/pause/seek by forging `data.source`. Outbound `window.parent.postMessage(...)` calls are pinned to the parent's origin (seeded from `document.referrer` and refreshed from the first accepted control message) instead of `"*"`, so preview frame coordinates and layer ids no longer leak to any embedding third-party page.
-
-The same runtime is used inside the Trackpad Editor iframe AND when a published fork is embedded elsewhere. It is agnostic to whether it's being edited or viewed.
-
-## The Trackpad Editor
-
-`demo/src/HyperframesStudioEditor.tsx` is the timeline editor. It:
-
-- Renders a `<Timeline>` and `<Player>` from `@hyperframes/studio` — a shared package with the timeline UI, drag/trim logic, and player state store (Zustand)
-- Loads `composition.html` + `composition.json` from the fork's working state
-- Renders the composition into a preview iframe using a `blob:` URL
-- Bidirectionally syncs timeline drag → HTML `data-start`/`data-duration` mutations, and inspector edits → text/style changes
-- Persists every commit back to the API as PUT `composition.html` and PATCH `composition.json`
-- Exposes an **Editor Action API** so the Chat panel can invoke typed actions (`add_layer`, `remove_layer`, `set_layer_start`, `set_layer_duration`, `set_layer_style`, `set_layer_keyframes` — script-free CSS `@keyframes` motion on one layer (opacity/translate/scale/rotate over the clip) — `set_captions` — animated word-by-word caption runs — `group_layers`, `ungroup_layers`, `nudge_layers` (relative timeline move), `ripple_edit` (insert/close time at a point, shifting downstream clips), `trim_layer` (move one edge; a left-trim advances the media in-point), `set_layer_zindex` (restack == track index), `replace_composition_html`, etc.)
-- Runs the composition-runtime script inside the preview iframe to keep timeline scrub in sync with the current time. That runtime also scrubs **Ken Burns** image animations (CSS pan/zoom on `[data-kenburns]` `<img>` layers) and **animated captions** (word-by-word `vf-cap-*` animations on `[data-caption-animation]` caption layers — Ken Burns normalizes to clip progress, captions seek to the absolute offset `time − data-start` because each word's inline delay/duration is its spoken window) to the playhead, so the preview matches the render frame-for-frame. Presets and keyframes live in `src/hyperframes/composition.ts` (`KEN_BURNS_CSS`, `CAPTION_ANIM_CSS` + `CAPTION_STYLE_PRESETS`), mirrored into the editor bundle and the serve-time HTML rewrite; `normalizePublishHtml` re-injects both stylesheets (marker-guarded) into legacy compositions at render time. Caption gotcha: the layer's inline `text-transform`/`overflow` must be set on the element (the stylesheet's `[data-caption-uppercase]` rule loses to inline styles), and cue text edits must rebuild the word spans (`refreshCaptionWordSpans`) rather than setting `textContent`. Speech→captions REST surfaces: `primitive:captions` (`POST /api/v1/primitives/audio/captions`, src/primitive-registry.ts) is the composition-agnostic job — STT with `wordTimestamps` (openai/whisper-1 real, others estimated via `estimateCaptionWords`) paged by `src/services/captions.ts` into cues + a ready `set_captions_action`; `POST /api/v1/compositions/:forkId/captions` (src/app.ts, next to the composition.html PUT) is the one-step variant that resolves the fork's narration, transcribes on raw customer keys (`loadCustomerVisionKeys` + `transcribeSpeechWithKey`), applies via `insertCaptionLayers` (shared with the devcli), and persists through the same sanitize path — intentionally NOT watch-suppressed so serve tabs live-morph; not for open cloud editor sessions (auto-save clobber). Scrub-stability guard (both `syncCaptionClip` copies — `src/composition-runtime.ts` + the editor's `runtimeScript()`): Chrome permanently drops a CSS-paused `fill:none` animation once its `currentTime` is pushed past the effect end, so the scrub parks `fill:none` word animations at 0 when the playhead is past their window (visually identical resting state, keeps them alive for scrub-back) while `fill:forwards` presets overshoot to hold their final keyframe; missing word animations are restarted by cycling `animation-name` through `none`. Live element patches that rebuild word spans must re-scrub via the `__player.syncCaptions()` runtime API (the editor calls it after `patchLiveElement`/`previewLiveElement`) or fresh spans sit paused-at-0 (invisible for word-pop/stack-up) until the next seek.
-
-The editor is a single monolithic React component (~9k lines). It builds cleanly to a static bundle deployed to CloudFront under `/editor/`.
-
-## Publishing (render pipeline)
-
-Publish flow:
-
-1. Client `POST /api/v1/compositions/:forkId/render` (`/export` is a deprecated alias; the editor button and devcli command are both **Render**; treat "render", "publish", `/render`, and `/export` as the same operation)
-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 renderer runs HyperFrames: on the deployed host it stages the composition and dispatches to the shared HyperFrames render state machine (chunked Lambda fan-out); on a local `vidfarm serve` box with no cloud stack it renders in-process (headless Chromium → ffmpeg) for free. See `HyperframesService` in `src/services/hyperframes.ts`.
-6. On success, the primitive returns `{ primary_file_url: "s3://.../output.mp4" }`, the API creates a `ForkVersionRecord` with `reason: "publish"`, writes the snapshot to `versions/<N>/`, updates the fork's `latestVersion` and `currentRenderJobId`, and now also exposes the deterministic public artifact URL immediately as `expected_output_public_url`
-7. Client polls `GET /api/v1/compositions/:forkId/renders/:renderId` for `{ status: "RUNNING" | "SUCCEEDED" | "FAILED", progress, expectedOutputPublicUrl, outputUrl, cost }` (see `adaptJobToPublishStatus` in `src/app.ts`); `expectedOutputPublicUrl` is the stable public S3 URL, while `outputUrl` remains the completion-time field
-
-The HyperFrames render state machine is **shared across all templates and forks** — it's an infrastructure primitive, not a per-template deployment. Its ARN/bucket are passed to the Vidfarm stack as env vars (`HYPERFRAMES_RENDER_*`). Remotion has been fully removed.
-
-## Auto-decompose
-
-`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, 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"`. 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)** — 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.
-
-## GhostCut integration
-
-GhostCut is an external AI subtitle-removal service. Vidfarm proxies to it via `src/services/ghostcut.ts`:
-
-- `submitSubtitleRemoval(sourceUrl)` — queue the removal task
-- `pollStatus(taskId)` — check status (`pending` | `processing` | `queued` | `done` | `failed`)
-- `mirrorGhostcutVideoToStorage()` — copy the clean output back to Vidfarm S3
-
-State is persisted per fork at `compositions/forks/<forkId>/working/ghostcut.json`. The client polls `POST /api/v1/compositions/:forkId/remove-video-captions-poll` (legacy alias: `/ghostcut-poll`) every few seconds during smart decompose.
-
-Read-only companion: `GET /api/v1/compositions/:forkId/remove-video-captions` (legacy alias: `/ghostcut`) returns `{ status, task_id, original_source_url, mirrored_url, submitted_at_ms, completed_at_ms, failure_reason }` without touching GhostCut. Non-billing. Exposed for two reasons: (1) the editor chat harness / AI copilot uses it to look up both video URLs on demand so downstream primitive calls can pick raw-upload vs caption-free-mirror without hardcoding either in chat context; (2) it's `http_request`-allowlisted under `COMPOSITIONS_PREFIX` in `src/app.ts`, which is why the editor chat system prompt (`src/editor-chat.ts`) directs the model to call it before feeding a video into a primitive route. The AI is instructed **not** to call `POST /remove-video-captions-poll` unless the user explicitly asks to advance subtitle removal.
-
-Standalone primitive: `POST /api/v1/primitives/videos/remove-captions` (alias: `POST /api/v1/primitives/remove-video-captions`; id `primitive:video_remove_captions` in `src/primitive-registry.ts`) exposes the same GhostCut pipeline for ANY video URL, decoupled from forks and decompose. The job probes the source (duration prices the task), submits, polls GhostCut to completion inside the job runner (12-minute budget, vs the fork routes where the client drives completion), mirrors `captions-removed.mp4` into primitive storage, and bills the `ghostcut_subtitle_removal` cost center per 30s chunk.
-
-Configuration: `GHOSTCUT_KEY` and `GHOSTCUT_SECRET` env vars per stage. Pass-through cost: `GHOSTCUT_USD_PER_30S` (default 0.10). **Guard:** the primitive hard-fails sources longer than `GHOSTCUT_MAX_DURATION_SEC` (default 900s) — GhostCut is a per-finished-clip tool; long-form "no captions" requests are served by the clip-hunt `avoid_text` scene-selection filter instead, never by laundering a whole long video through GhostCut.
-
-## Clip hunting pipeline (long-form → short-form)
-
-`POST /raws/scan` starts a Step Functions STANDARD workflow (`…ClipScanWorkflow`): `probe_and_detect` → `Map(process_scene, maxConcurrency 5)` → `finalize`, all three states dispatching the same `infra/lambda/clip-scan.ts` on an `action` field. Business logic lives in the shared `src/services/clip-curation/` core (also consumed by devcli and the Hono API), with the hunt controls in `hunt.ts`:
-
-- **`hunt_spec`** — windows (time ranges; ffmpeg input-seeks per window so only the requested footage is DECODED — the actual cost saving), a soft `duration_band` (`resolveDurationBand`: 10→5-20s, 30→20-40s via ±target/3), output `aspect` + `crop_focus` (smart-centre ffmpeg crop applied to clips, thumbnails, AND tagging keyframes so the model judges the framed output), `avoid_text` (rides the keep/drop/merge refine pass as a selection filter), and `source_url` (RapidAPI ingest → the user's temp folder). The spec travels as ONE opaque JsonPath object through the state machine, so new hunt fields are Lambda-code-only changes — no state-machine redeploy.
-- **Sources are temporary** — URL ingests and uploads land at `users/{id}/temporary/clip-sources/…` with a hard 30-day TTL enforced three ways: tag-scoped S3 lifecycle (`vidfarm-temp=1`, tagged server-side at temp-file finalize/upload), native DynamoDB TTL (`expires_at_epoch_seconds`, top-level on the item), and the list-route sweep. Hunted clips (`clips/{owner}/…`) are durable.
-- **Billing: AWS compute ONLY.** Every Lambda invocation post-hoc bills its GB-seconds to the `clip_scan_lambda` cost center (idempotent on `awsRequestId`); `finalize` adds `step_functions_standard` scaled by scene count (3 + N transitions); URL ingest adds the existing `rapidapi_video_download` pass-through. `jobId = scan_id`, and the caller's `tracer` rides every event (gsi2-tracer rollups). The BYOK tagging/embedding spend (gemini/openai/openrouter keys in the state input) is deliberately never wallet-billed. Submission is wallet-gated (`assertWalletCanQueueJobs` → 402); the 202 response carries a pre-scan `compute_estimate`.
-- **Failure reconciliation** — the workflow has no failure hook into records, so `GET /raws/scan/:scanId` lazily `DescribeExecution`s a running scan and flips the scan+source records to `failed` (or `complete`) so pollers converge.
-- **devcli is LOCAL-FIRST** — `vidfarm raws scan` runs local ffmpeg and, by default, the user's local claude/codex CLI subscription (`LocalAgentClipClient`, implementing the same `ClipHuntModelClient` interface as the API providers; refine's model call lives on the client as `decideScenes` to make them swappable). Provider keys are the fallback; `--cloud` is the explicit backup that presign-uploads to the temp folder and drives this pipeline.
-- **Bundling gotcha** — the clip-scan and primitive-media Lambdas bundle `ffmpeg-static`/`ffprobe-static` with `forceDockerBundling: true`: ffmpeg-static downloads the binary for the platform it is installed on, so a mac-local bundle ships a darwin ffmpeg the Lambda cannot exec (`exit 126`). They also need `VIDFARM_DATA_DIR=/tmp/vidfarm` because `config.ts` mkdirs at import.
-- **Exact-subrange clipper** — separate from the AI hunt, the **Clipper** cuts one precise `[start,end]` into a single raw. `POST /raws/resolve-source` `{ source_url }` returns a DIRECT `preview_url` (via `pickBestVideoMedia`, no download/re-host) so the web `/tools/clipper` page can play the source and pick an in/out; `POST /raws/clip-range` `{ source_url|preview_url|temp_file_id, start_sec, end_sec, tracer?, folder_path?, name? }` runs `importSubrangeAsRaw` inline on the request Lambda (fetch source → `extractClip` ffmpeg trim → `storage.putFile clips/<owner>/<id>.mp4` + thumbnail + `clipRecords.putClip`), landing one raw under `/raws/<folder>` (defaults to the tracer). Compute-only (RapidAPI billed only when a social `source_url` must be resolved). Same operation is exposed to the copilot (system prompt in `src/editor-chat.ts`) and devcli (`vidfarm clipper`). The three creative tools now live under `/tools/*` (`/tools/image` masked-image inpaint, `/tools/video` time-scoped video edits, `/tools/clipper`); the legacy `/inpaint/*` paths 302-redirect there, and the `images/inpaint` primitive keeps its name.
-
-## Editor Chat
-
-`infra/lambda/editor-chat.ts` is a separate Lambda that streams AI-driven edits to the Trackpad Editor. Client opens an SSE stream to `/api/v1/editor-chat`, sends the current composition snapshot + user prompt + attachments, and receives:
-
-- assistant text
-- tool calls that map to the Editor Action API (`add_layer`, `set_layer_start`, ...)
-- token usage + billing events
-
-The chat model uses the **caller's provider keys**. No Vidfarm-owned model calls happen in this path.
-
-Beyond the Editor Action API, the chat harness registers shared tools defined in **two synced copies** (`src/app.ts` for the in-process dev server and `infra/lambda/editor-chat.ts` for the deployed Lambda — keep them in lockstep): `http_request` (allowlisted REST/primitive calls), `frontend_action` (tracer/thread state), `video_context`, `load_skill`, and `browse_files`. `load_skill` is the copilot's knowledge-on-demand seam: it fetches vendored skill-pack content (SKILL.md or a reference file) from the host's public `/skill/:name` + `/skill-pack/:name/files/*` mirror routes (backed by `.agents/skills/`, shipped in the api Docker image), size-capped, with the pack catalog + one-liners defined once in `EDITOR_CHAT_SKILL_PACKS` (`src/editor-chat.ts`) and shared by both copies. Loadable packs are the hyperframes suite (`hyperframes`, `hyperframes-core`, `hyperframes-animation`, `hyperframes-keyframes`, `hyperframes-creative`, `hyperframes-cli`) plus the workflow packs (`embedded-captions`, `product-launch-video`, `faceless-explainer`, `website-to-video`, `general-video`, `motion-graphics`, `slideshow`, `talking-head-recut`, `vidfarm-media`); the `.claude/skills/*` entries are just Claude Code discovery symlinks to the same `.agents/skills/` dirs. In the web editor the copilot applies only the CSS / `@keyframes` + declarative-preset half of the animation/keyframes packs — their JS-adapter techniques are devcli-only. The stream-loop guardrails (`redactUnverifiedJobIds`, `buildEditorChatGuardrailNotice`, async-job handoff text) also live in `src/editor-chat.ts` and are imported by both copies — never re-implement them locally. `editor_action`'s `replace_composition_html` is lint-gated in the tool `execute` via `src/services/composition-lint.ts` (a rejected result carries `rejected: true` + `lint_errors` and omits `action_type`, so the browser never applies it). Web-editor motion is **declarative/CSS only**: the JS runtime adapters (anime.js / GSAP / Lottie / Three.js / TypeGPU) are stripped on save and `replace_composition_html` additionally rejects any `<script>`-bearing HTML, so the copilot authors motion with `set_layer_keyframes` (a CSS `@keyframes` animation on one layer) / `<style>` `@keyframes` + the preset vocabulary; scripted / adapter-driven compositions are a devcli-only (`vidfarm render`) capability. The `editor_context` snapshot the model receives now carries each layer's `transition` / `transition_out` / `transition_duration`, `ken_burns` preset, and `animation` (custom CSS keyframe name), and `recent_action_results` reports successes (`ok: true` + summary) as well as failures; the model can also GET `…/compositions/:forkId/composition.html` for exact markup. `browse_files` reads **and writes** the caller's file directory — `action=list`/`search`/`read`/`write`/`annotate`/`move`/`rename`. `action=rename` renames a file or **folder** in place via `POST /me/directory/rename` (`path` + `new_name`, plus `file_id` for a file — a metadata-only rename that leaves the S3 key/view URL intact). File rename is `/files`/`/temp` only, but **folder rename works in every root including `/raws` and `/approved`** — renaming a `/raws` folder re-points every clip inside it (`clipRecords.moveClipsFolder`) and renaming an `/approved` folder re-points every post (`serverlessRecords.moveReadyPostFolder`), which is how an auto-named folder like `/raws/lvlldspajcg` or `/approved/q3-promo` gets a real name; the `/library/raws` and `/library/approved` explorers each expose the same rename on every folder tile's kebab. `action=move` reorganizes a `/raws` clip (`PATCH /raws/:id`) or an `/approved` post (`PATCH /api/v1/approved/posts/:id`) between folders. There are now **four roots**: `/files`, `/temp`, `/raws`, and `/approved` (finished ready-to-post cuts, foldered — new posts self-file into a folder named after their tracer; `ReadyPostRecord.folderPath`). `action=list` defaults to `path='/'` when `path` is omitted, so the `/raws` (hunted raws), `/temp` (scratch), and `/approved` (published cuts) roots surface alongside the My Files folders instead of being hidden; a `/raws` listing accepts a `content_type` shot-kind filter (`talking_head`/`b_roll`/`product_shot`/`screen_recording`/…) and paginates via `offset`/`limit`. `write` saves a text file (md/txt/csv/json/srt/vtt) via `POST /me/attachments/upload`, or **imports a durable media URL** into the library when `source_url` is passed (how a generated `character_sprite_card.png` gets persisted instead of stranding in a job result). `annotate` sets free-form metadata `notes` on any entry (`PATCH /me/attachments/:id`); notes are **vector-embedded server-side** (BYOK, same gemini→openai auto-pick seam as clip search; no key fail-softs to keyword-only) and `search` runs the hybrid keyword+semantic lookup over every file's name/folder/notes via `POST /me/attachments/search` — the My Files mirror of `/raws/search`. Write+annotate are what let the copilot persist Getting Started context (About.md, awareness-levels.md, persuasive-angles.md, ad-hooks.md) and **recurring characters** — a first-class `/files/characters/<slug>/` trio (`<character_id>.json` manifest — named after the id `character_`+slug, e.g. `character_zara.json` + `character_sprite_card.png` + `character_about.md`) the copilot lists/reads before generating a saved character; the system prompt in `src/editor-chat.ts` drives when to save, annotate, and rename. The devcli mirrors are `vidfarm put-file [--notes]`, `annotate-file`, `files --search`, and `directory rename`.
-
-## Primitives
-
-Primitives are hosted operations that are NOT templates — they're reusable building blocks:
-
-- `create_image`, `edit_image`, `inpaint_image` — image generation
-- `create_html_image` — HyperFrames HTML → PNG (in-process headless Chromium)
-- `remove_background` — RapidAPI-backed AI matting for arbitrary/messy-background photos → durable PNG/WebP
-- `image_remove_background_greenscreen` — CHEAP local `sharp` chroma-key removal for flat solid backgrounds (green screen or any `key_color`) → durable transparent PNG/WebP; compute-only, prefer over `remove_background` when the background is a controlled solid fill
-- `media_overlay` ("create media overlay", Vox-style) — one job: BYOK AI image gen on a forced flat key-color background + local chroma key → ready-to-composite transparent overlay PNG/WebP. The go-to primitive for floating illustration/prop/cut-out overlays
-- `download_media_video` — social/media URL → durable MP4
-- `hyperframes_render` — composition HTML → MP4 (the render primitive publishing uses)
-- `brainstorm` — LLM brainstorm route
-- `music` / `tts` / `stt` — ElevenLabs audio (music, narration, transcription) with a `use_wallet_credits` flag that **defaults true**. `POST /api/v1/primitives/music/generate` (`primitive:music`) generates music from a prompt or composition plan. `POST /api/v1/primitives/audio/speech` (`primitive:tts`) turns text into narration with a promptable style (`instructions`) and an ElevenLabs `voice_id` (browse via `GET /api/v1/primitives/audio/voices` → `providers.listElevenLabsVoices`). `POST /api/v1/primitives/audio/transcribe` (`primitive:stt`) transcribes any video/audio URL (video demuxes through the primitive-media ffmpeg seam first, 64kbps mono, ~40min/20MB cap) into **two formats** — simple subtitles (text + SRT) and speaker-attributed segments. **Routing (`src/services/providers.ts` `resolveAudioAuthPlan`):** `use_wallet_credits: true` (default) → the platform `ELEVENLABS_API_KEY`, billed to the wallet (`elevenlabs_music`/`elevenlabs_tts`/`elevenlabs_stt` cost centers); `false` → the customer's own saved `elevenlabs` key (no charge), else a BYOK gemini/openai/openrouter key (TTS/STT only), else the platform key + wallet. The ElevenLabs calls live in `src/services/elevenlabs.ts`; the openai/gemini/openrouter speech calls in `src/services/speech.ts`. The `elevenlabs` provider key is **audio-only** — it never counts as a qualified text/image/video key. devcli: `vidfarm music`, `vidfarm voices`, and `vidfarm tts`/`vidfarm stt` (LOCAL-FIRST on the user's env key; `--cloud` hits ElevenLabs, `--own-key` uses the user's own key).
-
-Directors call primitives when they want a one-off asset before feeding it into a template. Templates call primitives internally as workflow steps. Each primitive declares one of three billing modes: **WALLET** — a metered platform charge (e.g. `remove_background` / `image_remove_background` RapidAPI pass-through, `video_remove_captions` GhostCut, cloud `hyperframes_render`, the local `image_remove_background_greenscreen` chroma key, `media_overlay`, and **platform ElevenLabs music/TTS/STT when `use_wallet_credits` is on** — the default); **BYOK** — the AI spend rides the caller's own provider key and is never wallet-billed (smart decompose, clip tagging/embedding, and music/TTS/STT run with `use_wallet_credits: false` on the user's own ElevenLabs/openai/gemini/openrouter key); or **COMPUTE-ONLY** — only the AWS Lambda / Step-Functions compute bills (clip hunts, the stt audio-demux step). So "all primitives are metered against the caller's wallet" holds only for the compute/platform legs — every BYOK AI call is excepted.
-
-## Billing
-
-Billing is USD wallet-based, not credits. Every metered operation writes a `billing_event` record and debits the wallet in the same DynamoDB transaction. Stripe webhooks land on the billing Lambda, which validates the signature, marks the invoice as processed idempotently, and credits the wallet.
-
-Key mechanics:
-
-- Every wallet mutation carries a `tracer` (idempotency key)
-- Provider spend is passed through at cost — no markup on AI provider calls
-- Platform infrastructure (cloud render, GhostCut, storage) has a small safety buffer applied
-- Clip hunts bill **AWS compute only** (`clip_scan_lambda` GB-seconds + `step_functions_standard` transitions, keyed to `jobId = scan_id`); the hunt's AI tagging runs on the caller's own provider keys (BYOK) and never touches the wallet
-- Failed jobs are refunded automatically when the failure is on the platform side
-- **Local `vidfarm serve` render is free + unguarded** — `publishCompositionToRenderer` runs the render in-process (`runPrimitiveJobInProcess`) and skips the wallet/paid guard when no cloud state machine is wired; only cloud render/templates are paid + wallet-guarded
-
-**Cost spectrum (director-facing framing; the same guidance lives in `SKILL.director.md` and the editor-chat system prompt).** Per-video cost is set by the *approach*, not a fixed price: FREE (reuse a decomposed template, swap captions/images/existing MP4s, render locally) → ~$0.001–$0.03 (same reuse + cloud render ~$0.01–$0.10) → ~$1 (AI-generate a few scenes) → $10+ (heavy AI generation). Image generation is cheap; AI **video** generation is the expensive end — the copilot is instructed to ask permission before video gen but not before image gen. Smart decompose is a ~$0.10 one-time per new source (provider passthrough + GhostCut) and is avoided by forking already-decomposed catalog templates. The AI defaults to the cheapest approach that meets the goal and surfaces the tradeoff.
-
-The billing Lambda has its own custom domain because Stripe webhooks require a stable URL not tied to the main API.
-
-## Template model
-
-There are two kinds of things directors can fork:
-
-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/` for any custom assets. 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.
-
-## Configuration and env
-
-Per-stage config is loaded via `.env.<stage>`. Critical variables:
-
-- `AWS_REGION`, AWS credentials
-- `VIDFARM_<STAGE>_PUBLIC_BASE_URL` — the API base
-- `VIDFARM_<STAGE>_ENCRYPTION_SECRET` — DynamoDB field encryption
-- `VIDFARM_<STAGE>_API_KEY_SALT` — API key hashing. Rotating it invalidates previously-issued keys on that stage only; the shared staging table can hold keys hashed under several salts (deployed stage vs local dev boxes). `getVisibleApiKey` (src/app.ts) is salt-aware: it returns the newest active key whose `key_hash` validates under THIS server's salt (minting one if none do), so boot pages / Settings never hand the browser a key the serving box would reject — the editor chat and all its server-executed tools authenticate with that embedded key.
-- `VIDFARM_<STAGE>_BOOTSTRAP_*` — initial admin user
-- `VIDFARM_<STAGE>_RESEND_*` — email
-- `VIDFARM_<STAGE>_SENTRY_*` — Sentry DSN
-- `GHOSTCUT_KEY`, `GHOSTCUT_SECRET` — GhostCut credentials
-- `RAPIDAPI_KEY` — shared RapidAPI credential used by the `video_download` and `image_remove_background` primitives. Same key is set in both `.env.staging` and `.env.production`.
-- Provider fallback keys for platform-owned features that don't have a caller yet (bootstrap only)
-- `HYPERFRAMES_NO_TELEMETRY=1` + `HYPERFRAMES_SKIP_SKILLS=1` — baked into every vidfarm-managed environment (api Docker image, CDK `hyperframesLambdaEnvironment`, devcli serve/spawns). The bundled hyperframes CLI defaults telemetry ON and auto-refreshes skills from its upstream GitHub org; these kill both. Never unset them, and never run `hyperframes auth`/`cloud`/`publish`/`play`/`feedback` — those are third-party account/hosting surfaces vidfarm replaces.
-
-Never commit `.env.staging` or `.env.production` — both are gitignored.
-
-## Skill packs (vendored mirror)
-
-`.agents/skills/` holds the vidfarm-scrubbed skill packs (the HyperFrames suite with every upstream-vendor dependency replaced by vidfarm primitives, plus `vidfarm-media` — the shared audio engine implementing the neutral `audio_request.json` → `audio_engine_meta.json` contract). `.claude/skills/*` are symlinks into it. The api serves the packs publicly: `GET /skill/:name` (SKILL.md), `GET /skill-pack/index.json` (catalog), `GET /skill-pack/:name/manifest.json` (file list + sha256), `GET /skill-pack/:name/files/<path>` (bytes, path-guarded) — `src/app.ts` next to `PUBLIC_SKILL_FILES`. Consumers: `vidfarm skills list|add|update` (devcli installer, writes `skills-lock.json` with reproducible folder hashes) and the web copilot's `load_skill` tool. When editing a pack, edit `.agents/skills/<name>` directly (the canonical copy), keep it free of upstream vendor accounts/endpoints, and re-run `vidfarm skills update`-side hash pinning as needed.
-
-## Deployment
-
-CDK stacks are under `infra/cdk/`:
-
-- `bin/vidfarm-serverless-staging.ts` → `lib/vidfarm-serverless-staging-stack.ts`
-- `bin/vidfarm-prod.ts` → `lib/vidfarm-prod-stack.ts`
-
-Deploy commands are in `package.json`:
-
-- `npm run cdk:synth:staging-serverless`
-- `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 — 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.
-
-## Migration scripts
-
-One-shot scripts under `scripts/`:
-
-- `migrate-sqlite-to-dynamodb.ts` — one-time, completed on 2026-06-22. Do not re-run.
-- `migrate-compositions-to-ownership-agnostic.ts` — moves forks from `compositions/users/<customerId>/forks/<forkId>/` to `compositions/forks/<forkId>/working/`. Idempotent. Must be run against each stage where the old layout ever existed.
-- `migrate-decomposition-to-composition.ts` — renames `decomposition.json` → `composition.json` in S3 for all forks + versions. Idempotent. Supports `--delete-old` for cleanup.
-- `copy-dynamodb-prod-to-staging.ts` — copies prod DynamoDB items into staging for testing. Excludes transient rows by default.
-
-Run migrations with `--dry-run` first. Always.
-
-## Directory reference
-
-Top-level:
-
-- `src/` — API server + all backend services
-- `demo/` — Trackpad Editor React app
-- `infra/` — CDK stacks and Lambda entry points
-- `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 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:
-
-- `auto-create-templates/` — extractor prompts for the older template creation flow. Only `extractor-system-prompt.md` and `production-graph.schema.json` are still live (loaded by `demo/scripts/dev.mjs`); the rest is inert docs kept for reference.
-- `src/account-pages-legacy.ts`, `src/dev-app-legacy.ts` — HTML-string page renderers wrapped by `.tsx` React shells (`account-pages.tsx`, `dev-app.tsx`). Still active.
-
-## Common failure modes
-
-- **Fork loads 404** — check ownership-agnostic migration ran; the fork may still be at the old `compositions/users/.../forks/` path.
-- **Publish stuck in RUNNING** — check the primitive Lambda's CloudWatch logs. HyperFrames asset preflight failures usually mean a broken media URL in composition.html.
-- **Smart decompose falls back to time-slice** — the caller has no provider keys, or all their keys returned errors. Check `provider_key_lease` records.
-- **GhostCut task hangs** — client shows `pending` forever. Check the fork's `ghostcut.json` and the GhostCut dashboard. There is currently no cancel UI; the poll times out at 15 minutes.
-- **Editor edits don't persist** — verify `PUT /composition.html` is 200. If the composition.html doesn't include `data-composition-id`, the API rejects the PUT at publish time.
-
-## Where to look for things
-
-- 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 creation has ONE source-of-truth helper trio in `src/app.ts` — `seedForkWorkingFromFork` (copies the 5 canonical working files, optionally from a pinned version) + `forkCompositionFromTemplateDefault` (fresh from the template's canonical default) + `forkCompositionFromExistingFork` (branch a working copy + snapshot). `POST /compositions` (template entry), `POST /:forkId/fork { from: current|default }` (the unified New-fork endpoint behind the ⋯ menu / AI `fork_composition` / devcli `clone --from`), and the legacy `POST /:forkId/clone` alias all funnel through them, so seed logic stays uniform. grep the helper names.
-- 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`
-- Composition runtime script — `src/composition-runtime.ts`
-- 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 (`vidfarm serve`)
-
-`@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` (→ `/render`), `approve`, `schedule`, `posts`/`schedules`, `upload`/`download`, `files`/`get-file`/`put-file`/`annotate-file` (My Files read+write+notes; `files --search` is the hybrid keyword+vector lookup over names/folders/notes), `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
-# 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
-
-# Pull a specific cloud fork instead of the template default:
-vidfarm-devcli serve --fork <forkId> --host https://vidfarm.cc --api-key <key>
-```
-
-Flags: `--port` (3000), `--dir` (`./.vidfarm-local`), `--key` (local bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork`, `--host`, `--api-key` (cloud key for pulls, /library, and cloud render), `--refetch`, `--no-cloud`, `--no-open`. `vidfarm <template_id>` aliases `serve <template_id>`.
-
-**Cloud passthrough** (`src/services/upstream.ts`; on unless `--no-cloud`): only the editor's data is local — the box mirrors the upstream host (`VIDFARM_UPSTREAM_HOST` + `VIDFARM_UPSTREAM_API_KEY`, set by serve from `--host`/`--api-key`). `/discover/feed` and `GET /api/v1/videos` merge the upstream catalog behind local entries (dedup by id); `/library` and `GET /api/v1/approved/posts` merge the cloud account's approved posts, and `:postId` actions on posts that don't resolve locally proxy through (`maybeProxyUnknownReadyPostToUpstream`); `POST /discover/templates` (Add Template) proxies so ingest lands in the cloud account — its `/upload/presign` sibling proxies too, so file uploads PUT straight to cloud S3 (the multipart fallback `/discover/templates/upload` never proxies: the proxy is text-only; a locally-stored upload key is the one Add Template body handled locally); `/editor/:templateId` seeds an unknown template/fork from upstream on first open (`seedFromUpstream` — same path as boot seeding, cloud fork id reused locally). The editor boot gains `localRender` + `cloudRenderAvailable`, which turn the Render button into a popover: **Render Local (Free)** vs **Render in Cloud**. `render_target: "cloud"` on `POST /render` resolves (or clones, once) a publishable upstream fork (mapping persisted in the fork's working `upstream-link.json`), starts the render upstream with the submitted html, writes a `cloud-render-<renderId>.json` marker, and `GET /renders/:renderId` proxies status through that marker. serve force-clears `VIDFARM_JOB_STATE_MACHINE_ARN` so local renders never silently route to a cloud state machine picked up from a dev-shell `.env`.
-
-**Architecture** (fully local editor; cloud passthrough is read/proxy-only):
-- **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>`. This is also what makes **local file paths as media** free: `vidfarm place --src ./file` against a serve working copy copies the file to `<data-dir>/storage/users/local-media/<uuid>/<name>` and references the box's own `/storage/<key>` URL — no S3, the in-process renderer fetches it over localhost (`resolvePlaceableMediaSrc` in `src/cli.ts` detects the serve tree structurally). Off a serve box, `place`/`approve` fall back to uploading a local file to the ephemeral temp store under a `temp/` folder.
-- **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** — in-process on this box (free, unguarded — `runPrimitiveJobInProcess` + headless-Chromium HyperFrames). Cloud rendering is the explicit `render_target: "cloud"` upstream handoff described above; the ambient `VIDFARM_JOB_STATE_MACHINE_ARN` is force-cleared by serve.
-- Lambdas — `infra/lambda/*.ts`

package/demo/README.md

@@ -1,28 +0,0 @@
-# HyperFrames Layer Editor Demo
-
-This is a self-contained React demo for decomposing a short vertical video into editable HyperFrames-style layers.
-
-Run it from this folder:
-
-```bash
-npm run dev
-```
-
-The editor currently supports:
-
-- Editable media URLs for video and image layers.
-- Editable text, timing, track, z-index, size, position, opacity, and colors.
-- A live 9:16 stage preview.
-- A scrub/play timeline with layer tracks.
-- Generated HyperFrames-style HTML using `data-start`, `data-duration`, and `data-track-index`.
-- A generated project URL targeting `https://hyperframes.heygen.com/` with the layer payload encoded in the query string.
-- Local MP4 decomposition via `POST /api/decompose`.
-- Gemini-powered extraction of viral DNA, visual DNA, production graph intent, and editable semantic layer timelines.
-
-The decomposition demo reads:
-
-```text
-../drafts/inspiration-posts/best-at-what-cost.mp4
-```
-
-It loads `GEMINI_API_KEY` from `../.env.production` and defaults to `gemini-3.5-flash`. Use the `Decompose MP4` button in the UI to sample frames, call Gemini, and replace the editor layers with the returned semantic timeline.