@mevdragon/vidfarm-devcli 0.5.0 → 0.5.1

package/SKILL.director.md

@@ -72,7 +72,8 @@ Priority: Gemini → OpenAI → OpenRouter. If a director has no keys, smart dec
 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 `/discover`
-- API: `GET /discover/feed` — returns `{ templates: [{ templateId, slugId, title, previewUrl, viralDna, durationSeconds, sourceType, ... }], next_cursor }`
+- API: `GET /discover/feed` — returns `{ templates: [{ templateId, slugId, title, previewUrl, viralDna, durationSeconds, sourceType, promotions, keywords, summary, ... }], next_cursor }`
+- Search: `GET /discover/feed?q=<offer>&limit=20` keyword-searches the catalog so you can answer "which templates suit my `<offer>`?" (e.g. `?q=weight%20loss%20app`). Ranking is a coarse keyword match over each template's title, viral DNA, and the decompose-derived `promotions` (offer categories the format can sell), `keywords`, and `summary` — read those fields to judge fit and rank the best 3-6 semantically. `GET /api/v1/videos?q=<offer>&limit=20[&mine=true]` runs the same search over source **inspirations**. `promotions`/`keywords`/`summary` are populated by the decompose pass, so a freshly ingested template that has not been decomposed yet won't match on them — decompose it (or fall back to broader/synonym terms) if a search comes up empty.
 
 Each template exposes a public preview:
 
@@ -90,7 +91,7 @@ To bring a new viral video into the catalog as a **private** template you own, i
 - `DELETE /discover/templates/:entryId` — remove a private inspiration/template you own (accepts either the `inspiration_...` or minted `template_...` id).
 - `POST /api/v1/inspirations/:inspirationId/decompose { user_prompt? }` — AI-decompose an inspiration's downloaded video into scenes (requires a saved provider key; same 120s source cap as auto-decompose).
 
-devcli: `vidfarm inspiration-add <url>`, `vidfarm inspiration-rm <id>`, `vidfarm inspiration-decompose <id>`, and `vidfarm discover` to browse.
+devcli: `vidfarm inspiration-add <url>`, `vidfarm inspiration-rm <id>`, `vidfarm inspiration-decompose <id>`, `vidfarm discover [query]` to browse/search templates, and `vidfarm videos [query] [--mine]` to browse/search source inspirations.
 
 ## Fork a template
 
@@ -122,7 +123,7 @@ The editor is a full timeline surface:
 - **Timeline** — multi-track, drag/trim/split clips, group/ungroup layers
 - **Inspector panel** — per-layer property editor (text, color, font, position, size, media source, playback start, volume)
 - **Canvas frame overlay** — 8-handle resize + WYSIWYG positioning
-- **Chat panel** — AI assistant that can programmatically edit the composition (13 action types: `add_layer`, `remove_layer`, `set_layer_start`, `set_layer_duration`, `group_layers`, `replace_composition_html`, ...). The assistant uses the caller's saved provider keys.
+- **Chat panel** — AI assistant that can programmatically edit the composition (`add_layer`, `remove_layer`, `set_layer_timing/visual/style/media/text`, `group_layers`, `generate_layer`, `replace_composition_html`, ...). The assistant uses the caller's saved provider keys. **`generate_layer`** is the one-shot "generate AI media and place it": it submits the `/videos/generate` or `/images/generate` primitive job, drops a placeholder clip into the target slot (fill a blank gap, replace a scene, or overlay), and auto-swaps in the finished media when the job settles — no manual polling. In-flight generations surface in `editor_context.pending_generations`.
 - **Auto-save** — every commit writes composition.html + composition.json to the working state. No explicit save button.
 
 The editor persists to:
@@ -203,12 +204,42 @@ Use it whenever you need to know what the video says or shows: writing/translati
 - **Editor chat (frontend AI)** exposes this as the optional `video_context` tool — the copilot calls it on demand.
 - **Desktop agents (Claude Code / Codex)**: fetch the `video-context.json` route directly (e.g. `vidfarm api GET /api/v1/compositions/<forkId>/video-context.json`) to ground edits in what the video says and shows.
 
+## Generate AI media and drop it on the timeline
+
+Both surfaces can generate a NEW AI video/image (optionally conditioned on reference images) and place it into the timeline — filling a blank gap or replacing a scene — using the async generation primitives (`POST /api/v1/primitives/videos/generate`, `/images/generate`). Generation is a **queued job**: the POST returns `202 { job_id }`, and the finished media URL only appears after the job settles (`result.primary_file_url` / `video.file_url` / an artifact `public_url`). Poll `GET /api/v1/user/me/jobs/:jobId` until `status: "succeeded"`.
+
+**Cost gate (see the Cost spectrum section):** AI **video** generation is the expensive end of the spectrum ($1–$10+/video) — **ask the director's permission before generating video**, and prefer reusing existing footage (My Files / their computer / a web search) or filming when it would do. **Image** generation is cheap — use it freely without asking. When a director wants specificity that only AI video can deliver and their budget allows, this is the right tool; just confirm first.
+
+- **Editor web copilot**: use the `generate_layer` editor_action — it does the whole flow (submit job → placeholder clip → auto-swap on completion) and reads `pending_generations` from `editor_context`. Set `media_type`, `prompt`, `aspect_ratio` (match the canvas), and `intent` (`fill_gap` with `start`/`duration`, `replace_layer` with `replace_layer_key`, or `add`). For character consistency pass a cast `reference_url` in `input_references` (video) / `prompt_attachments` (image).
+
+- **Desktop agents (Claude Code / Codex)** — two devcli commands:
+  ```bash
+  # 1) Sync the fork to disk and see where the blank space and scenes are
+  vidfarm pull <forkId> --dir ./work
+  #   → prints timeline gaps (e.g. 4-7s) and scene/layer keys, canvas aspect ratio,
+  #     and whether video-context.json / cast.json are present for grounding.
+
+  # 2) Generate + place in one call (fill a gap)
+  vidfarm generate video --prompt "her walking through the door" \
+      --ref ./cast/girl.png --aspect-ratio 9:16 --duration 4 \
+      --place ./work --at 4
+  #   → polls the job to the finished MP4, then inserts it at 4s in ./work/composition.html
+
+  # …or replace a scene with a generated still
+  vidfarm generate image --prompt "product hero on marble" --aspect-ratio 9:16 \
+      --place ./work --replace <layer_key>
+
+  # 3) Push it back (or it live-morphs automatically under `vidfarm serve`)
+  vidfarm publish --dir ./work --fork <forkId>
+  ```
+  `--ref @localfile` (or a bare path) auto-uploads the image and uses its durable URL as a reference. `generate` prints the media URL (drop `--place` to just get the URL); `place` can be run separately on any media URL (`vidfarm place ./work --src <url> --at <time>|--replace <layer_key>`). Placement produces the exact same clip markup the browser editor makes, so a human can finish it in the Trackpad Editor.
+
 ## Render (publish to MP4)
 
-Rendering publishes the fork's current working state to an MP4 using shared Remotion Lambda. In the Trackpad Editor this is the **Render** button; the REST route is still named `/export` (the route name predates the UI rename — treat "Render", "publish", and `/export` as the same operation). The devcli exposes it as `vidfarm render <forkId> [--wait]`.
+Rendering publishes the fork's current working state to an MP4 using HyperFrames (cloud Lambda fan-out on the deployed host, or the free in-process renderer on a local `vidfarm serve` box). In the Trackpad Editor this is the **Render** button. The REST route is `/render`; the older `/export` path is kept as a deprecated alias for already-published devcli clients (treat "Render", "publish", `/render`, and `/export` as the same operation). The devcli exposes it as `vidfarm render <forkId> [--wait]`.
 
 ```
-POST /api/v1/compositions/:forkId/export
+POST /api/v1/compositions/:forkId/render
 Content-Type: application/json
 
 { "title": "optional", "version": null, "tracer": "optional-trace-id", "html": "optional HTML to save to working state before rendering" }
@@ -314,15 +345,40 @@ DELETE /api/v1/compositions/:forkId
 
 Soft-delete only. The fork's `deletedAt` is set. Versions and share links are preserved for audit.
 
+## Cost spectrum (free → $10+/video) — default to saving the director money
+
+There is no single price for a video. The **approach** the director picks sets the cost, across a wide spectrum. Always steer toward the cheapest approach that still meets their goal, and make the tradeoff explicit rather than silently choosing an expensive path.
+
+| Approach | Typical cost | How |
+|---|---|---|
+| **Reuse + render locally** | **free** | Fork an already-decomposed template, swap captions / images / video with existing MP4s (from **My Files**, the director's **local computer**, or a **web search**), and render **locally** via `vidfarm serve` (native in-process HyperFrames render — free and unguarded, no cloud). |
+| **Reuse + cloud render** | **~$0.001 – $0.03** | Same reuse, but render on the cloud renderer (`POST /compositions/:forkId/render`, ~$0.01–$0.10 depending on length/res). Cheap **image** generation/edits fit in this band too. |
+| **AI-generate some scenes** | **~$1** | Replace a few scenes with AI-generated video clips for high specificity/customization (see the "Generate AI media" section). |
+| **Heavy AI generation** | **$10+** | Many/long AI video clips, custom characters, fully bespoke scenes. |
+
+Rules of thumb:
+
+- **Reusing existing footage — or footage the director films themselves — is the cheapest.** AI-generating characters/scenes is the most expensive. Editing captions/images on a reused template is nearly free.
+- **Local render is free; cloud render costs pennies.** If the director is iterating with a coding agent on a `vidfarm serve` box, they can render locally at no charge until they want the durable cloud MP4.
+- **Decompose is a one-time ~$0.10** (smart decompose ≈ provider passthrough + GhostCut ~$0.10/30s) per **new** source video — but the director can **skip it entirely** by forking a template that's **already decomposed** in the catalog.
+- **Image generation is cheap** — use it freely, no need to ask permission.
+- **AI video generation is expensive — ask the director's permission before using it.** Default to reuse/local/image approaches unless they've okayed video gen or told you the budget covers it.
+- **Ask about budget.** During Getting Started (and whenever it's relevant per editor project, or when the director asks about cost), ask roughly what they want to spend per video, and pick the approach band that fits. If they haven't said, assume the cheapest approach that works.
+
+The director always chooses the method that works for them — the point is to surface the tradeoff and default to thrift, not to force the cheapest path.
+
 ## Billing
 
 Vidfarm charges directly in USD from the caller's wallet. There are no credits.
 
 - **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
+- **Cost anchors** (see the Cost spectrum section above for how these combine per approach):
+  - Local render on a `vidfarm serve` box (in-process HyperFrames): **free**
+  - Cloud render (HyperFrames Lambda fan-out): typically $0.01 – $0.10 per MP4 depending on length/resolution
+  - Image generation / edit: cheap (provider passthrough) — use freely
+  - AI **video** generation: expensive ($1–$10+/video territory) — ask permission first
+  - Auto-decompose smart mode: pass-through of caller's AI provider spend (~$0.10 one-time with GhostCut), or skip it by forking an already-decomposed template
   - Auto-decompose time-slice: free
   - GhostCut subtitle removal: ~$0.10 per 30 seconds of source video
 
@@ -339,7 +395,7 @@ For agents that operate Vidfarm headlessly, the typical loop is:
 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/export { tracer }` → render
+4. `POST /api/v1/compositions/:forkId/render { tracer }` → render
 5. Poll `GET /api/v1/compositions/:forkId/renders/:renderId` until `SUCCEEDED`
 6. Use `outputUrl` in the next stage
 
@@ -353,16 +409,20 @@ Send a stable `tracer` on export so retries are traceable and filterable in job
 
 | Command | REST route | Flow step |
 |---|---|---|
-| `vidfarm discover` | `GET /discover/feed` | browse inspiration/templates |
+| `vidfarm discover [query]` | `GET /discover/feed[?q=]` | browse/search templates |
+| `vidfarm videos [query] [--mine]` | `GET /api/v1/videos[?q=&mine=]` | browse/search source inspirations |
 | `vidfarm inspiration-add <url>` | `POST /discover/templates` | add your own source |
 | `vidfarm inspiration-rm <id>` | `DELETE /discover/templates/:id` | remove a private one |
 | `vidfarm inspiration-decompose <id>` | `POST /api/v1/inspirations/:id/decompose` | AI-decompose an inspiration |
 | `vidfarm fork <template_id>` | `POST /api/v1/compositions` | fork a template |
+| `vidfarm pull <forkId> [--dir <p>]` | `GET .../compositions/:forkId/{composition.html,json,video-context.json,cast.json}` | sync a fork to disk + print gaps/scene keys |
+| `vidfarm generate <image\|video> --prompt "…"` | `POST /api/v1/primitives/{images,videos}/generate` (polls job) | generate AI media → finished URL |
+| `vidfarm place <dir> --src <url> [--at\|--replace]` | (edits local composition.html) | drop media into a gap / over a scene |
 | `vidfarm decompose <forkId>` | `POST .../compositions/:forkId/auto-decompose` | split source into scenes |
 | `vidfarm ghostcut <forkId>` | `GET .../compositions/:forkId/ghostcut` | subtitle-removal status |
 | `vidfarm snapshot <forkId>` | `POST .../compositions/:forkId/versions` | save composition fork version |
 | `vidfarm versions <forkId>` | `GET .../compositions/:forkId/versions` | list versions |
-| `vidfarm render <forkId> [--wait]` | `POST .../compositions/:forkId/export` | render video to MP4 |
+| `vidfarm render <forkId> [--wait]` | `POST .../compositions/:forkId/render` | render video to MP4 |
 | `vidfarm render-status <forkId> <renderId>` | `GET .../compositions/:forkId/renders/:renderId` | poll a render |
 | `vidfarm visibility <forkId> <private\|public>` | `PATCH .../compositions/:forkId/visibility` | set visibility |
 | `vidfarm clone <forkId>` | `POST .../compositions/:forkId/clone` | clone a fork |
@@ -374,12 +434,28 @@ Send a stable `tracer` on export so retries are traceable and filterable in job
 | `vidfarm login <email>` / `vidfarm verify <email> <code>` | `POST /api/v1/user/request-otp` · `verify-otp` | get an API key |
 | `vidfarm whoami` | `GET /api/v1/user/me` | who am I |
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
-| `vidfarm upload <file>` | `POST /api/v1/user/me/temporary-files/upload` | upload → durable URL |
+| `vidfarm upload <file> [--folder <path>]` | `POST /api/v1/user/me/temporary-files/upload` | upload → durable URL (ephemeral) |
 | `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
+| `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
+| `vidfarm get-file <id> [dest] [--print]` | (resolve id → view_url, then stream/print) | read one My Files asset |
+| `vidfarm put-file <file> [--folder <p>] [--as <name>] [--content/--stdin]` | `POST /api/v1/user/me/attachments/upload` | write into My Files (persistent) |
 
 **Frontend URLs are first-class output.** Every command that has a human-openable page (editor, discover, approved-post preview, share link) prints that prod frontend URL as a highlighted line. `render --wait` polls to completion and prints the final MP4 URL; `approve` prints the approved-post `share_url`. Add `--json` to any command for pure JSON (agent-friendly, no banners).
 
-**Uploads/downloads live in the devcli** because they are genuine multi-step / streaming flows: `upload` posts the file as multipart to the temporary-files route and prints the durable URL to drop into a composition or approved post; `download` streams any Vidfarm/media URL to disk.
+**Uploads/downloads/My-Files writes live in the devcli** because they are genuine multi-step / streaming flows: `upload` posts the file as multipart to the **ephemeral** temporary-files route and prints the durable URL to drop into a composition or approved post; `put-file` posts to the **persistent** My Files route (`/me/attachments/upload`) so context docs and brand assets live in the user's library (accepts a local file, `--content <text>`, or piped `--stdin` with `--as <name>`); `download` streams any Vidfarm/media URL to disk.
+
+## My Files (the user's asset library)
+
+Each user has a persistent **My Files** filesystem — their own uploaded videos (mp4/mov/webm), images (png/jpg/jpeg/gif/webp/svg), audio (mp3/wav/m4a/aac), and documents (pdf/md/txt/csv) — organized into **virtual folders**. This is where a user keeps footage, brand assets, logos, music, briefs, scripts, and the durable strategy docs from Getting Started (About.md, awareness-levels.md, etc.). Both the editor AI copilot and an agent CLI can **read and write** it to find or save assets instead of asking the user to re-upload or paste URLs.
+
+- **List** — `GET /api/v1/user/me/attachments` → `{ attachments: [{ id, fileName, contentType, sizeBytes, folderPath, viewUrl, createdAt }], folders: [string] }`. The `viewUrl` is a durable URL you can drop into a composition layer or pass into a primitive route. devcli: `vidfarm files [--folder <path>]`.
+- **Read one** — resolve it from the list and stream/read its `viewUrl`. devcli: `vidfarm get-file <id> [dest]` (add `--print` to print text contents of md/txt/csv/json inline). For images/video/audio/pdf, reference the `viewUrl` as media — you can't read their bytes as text.
+- **Write into My Files** — `POST /api/v1/user/me/attachments/upload` (multipart `file` + optional `folder_path`) persists a file into the library. devcli: `vidfarm put-file <localFile> --folder <path>`, or pipe/inline text without a temp file: `echo "…" | vidfarm put-file --stdin --as About.md --folder acme` / `vidfarm put-file --content "…" --as About.md`. This is how an agent saves Getting Started context (About.md, Interview.md, awareness-levels.md, persuasive-angles.md, ad-hooks.md) or drops a logo/product demo into a namescoped folder. In the web editor copilot the same capability is the **`browse_files` write action** (`action=write` with `file_name` + `content` + optional `folder_path`), which accepts text files (md/txt/csv/json/srt/vtt).
+- **`vidfarm upload` is different** — it targets the **ephemeral** temporary-files store (`POST /api/v1/user/me/temporary-files/upload`) for a throwaway durable URL to drop straight into a composition or approved post. Use `put-file` when you want the asset to persist in the user's My Files library; use `upload` for one-shot media you just need a URL for.
+
+**Assume My Files is multi-offer.** A user often runs more than one product, offer, brand, or region, and namescopes assets into folders accordingly — by product (`acme-skincare/`, `zensleep/`), by offer/campaign (`summer-sale/`), by region (`us/`, `eu/`), by asset type (`logos/`, `ugc-clips/`), or any arbitrary scheme. There is **no fixed layout** — read the `folders` tree first and reason about how this user organized things. Before pulling assets for a task, infer which folder(s) match the product/offer/region the current composition is about (match folder names to the composition title, video context, and what the user said), then scope reads to that folder so you never mix one brand's logo/product-shot/music into another brand's video. If the target offer is ambiguous, ask which product/offer/region (or which folder) this work is for rather than guessing across offers.
+
+In the editor web copilot the same filesystem is exposed via the **`browse_files` tool** (`action=list` / `action=read` / `action=write`), so the copilot follows the identical reasoning: list folders, pick the right offer's folder, then read an asset — or `write` a text doc (About.md, awareness-levels.md, …) into that folder. The devcli equivalents are `vidfarm files` / `get-file` / `put-file`.
 
 ## Local dev loop (`vidfarm serve`)
 
@@ -409,7 +485,7 @@ To *analyze* the source media locally (videos, transcript, recurring cast), read
 
 - 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 `POST /api/v1/compositions/:forkId/export` so billing, retries, cost caps, and Lambda quotas are enforced.
+- Do **not** call the renderer directly. Publishing goes through `POST /api/v1/compositions/:forkId/render` 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
@@ -420,6 +496,22 @@ Vidfarm is in active development. Endpoints, response shapes, and the editor UI
 - 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
 
+## Getting started / onboarding a new director
+
+Only run this flow when the director signals they **don't know where to start** ("getting started", "help me set up", "I don't know where to begin"). If they already know what they want, skip straight to it — never force onboarding. Directors can also jump to any single step (e.g. "just find me a good template for X" → go straight to template discovery).
+
+The point of onboarding is to build **durable, reusable context** in My Files, namescoped under the director's product/offer folder, so future chats and agents can read it back. Save each artifact as Markdown with `browse_files` write (web copilot) or `vidfarm put-file` (devcli):
+
+1. **Product context** → `About.md` (basic offer/product) or a deeper `Interview.md` if they want depth. Drive the interview questions with `brainstorm/coldstart`.
+2. **Awareness level** (Eugene Schwartz — problem-aware, solution-unaware, …) → `awareness-levels.md`. If it's genuinely unknown after thinking it through, note that ads for **every** level should be made and tested. Use `brainstorm/awareness_stages`.
+3. **Persuasive angles** → `persuasive-angles.md`, via `brainstorm/angles`.
+4. **Hooks** → `ad-hooks.md`, via `brainstorm/hooks`.
+5. **Brand assets & demos** — ask if they have logos/mascots/themes (suggest a `/brand-assets/` folder, e.g. `/brand-assets/logo.png`) or product demos / screen recordings (suggest a `/product-demos/` folder). `browse_files list` / `vidfarm files` first to see what they already uploaded; filenames should be descriptive so assets are findable.
+6. **Budget** — ask roughly what they want to spend per video, and map it to the Cost spectrum (free reuse+local render → pennies for cloud render → ~$1 for some AI scenes → $10+ for heavy AI gen). This sets which approach you default to and whether AI **video** generation is on the table (ask permission before using it; image gen is cheap and fine). Budget can also be revisited per editor project.
+7. **Recommend & adapt a template** — pair what you now know about the offer against the decomposed template catalog (`GET /discover/feed?q=<offer>`, read each result's `promotions`/`keywords`/`summary`), recommend the best 3-6, then fork and **modify** the winner to fit their offer. Prefer already-decomposed templates so the director skips the ~$0.10 decompose cost.
+
+**Assume multiple offers.** My Files is multi-offer (see the My Files section) — namescope every onboarding artifact under the right product/offer/region folder (`acme-skincare/About.md`, not a bare `About.md`) so one brand's context never bleeds into another's.
+
 ## Default assistance pattern
 
 When a director asks "make me a video", the default sequence is:
@@ -459,7 +551,7 @@ Apply subtle camouflage transforms (zoom, tilt, rotate, saturation, playback spe
 - 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)
+- Billing: metered as a HyperFrames render (via `hyperframes_lambda` on prod cloud render; free on a local serve box)
 
 Payload fields:
 

package/SKILL.platform.md

@@ -1,11 +1,11 @@
 ---
 name: vidfarm-platform
-description: Vidfarm platform architecture reference. Use this for questions about how compositions, forks, versions, storage, DynamoDB records, the Trackpad Editor runtime, Remotion render Lambda, 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.
+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 a shared Remotion Lambda, and share results.
+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.
 
@@ -184,15 +184,15 @@ The editor is a single monolithic React component (~9k lines). It builds cleanly
 
 Publish flow:
 
-1. Client `POST /api/v1/compositions/:forkId/export` (the route is named `export`; the editor button and devcli command are both **Render**; treat "render", "publish", and `/export` as the same operation)
+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 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
+5. The renderer runs HyperFrames: on the deployed host it stages the composition and dispatches to the shared HyperFrames render state machine (chunked Lambda fan-out); on a local `vidfarm serve` box with no cloud stack it renders in-process (headless Chromium → ffmpeg) for free. See `HyperframesService` in `src/services/hyperframes.ts`.
 6. On success, the primitive returns `{ primary_file_url: "s3://.../output.mp4" }`, the API creates a `ForkVersionRecord` with `reason: "publish"`, writes the snapshot to `versions/<N>/`, and updates the fork's `latestVersion` and `currentRenderJobId`
 7. Client polls `GET /api/v1/compositions/:forkId/renders/:renderId` for `{ status: "RUNNING" | "SUCCEEDED" | "FAILED", progress, outputUrl, cost }` (see `adaptJobToPublishStatus` in `src/app.ts`)
 
-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.
+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
 
@@ -237,12 +237,14 @@ Configuration: `GHOSTCUT_KEY` and `GHOSTCUT_SECRET` env vars per stage. Pass-thr
 
 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`, and `browse_files`. `browse_files` reads **and writes** the caller's My Files library — `action=list`/`read`/`write`, where `write` saves a text file (md/txt/csv/json/srt/vtt) via `POST /me/attachments/upload`. Write is what lets the copilot persist Getting Started context (About.md, awareness-levels.md, persuasive-angles.md, ad-hooks.md) namescoped under a product/offer folder; the system prompt in `src/editor-chat.ts` drives when to save. The devcli mirror is `vidfarm put-file`.
+
 ## 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` — Remotion HTML → PNG
+- `create_html_image` — HyperFrames HTML → PNG (in-process headless Chromium)
 - `remove_background` — RapidAPI-backed image background removal → durable PNG/WebP
 - `download_media_video` — social/media URL → durable MP4
 - `hyperframes_render` — composition HTML → MP4 (the render primitive publishing uses)
@@ -258,8 +260,11 @@ 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 (Remotion render, GhostCut, storage) has a small safety buffer applied
+- Platform infrastructure (cloud render, GhostCut, storage) has a small safety buffer applied
 - 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.
 
@@ -267,7 +272,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** — 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).
+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.
@@ -281,7 +286,6 @@ Per-stage config is loaded via `.env.<stage>`. Critical variables:
 - `VIDFARM_<STAGE>_ENCRYPTION_SECRET` — DynamoDB field encryption
 - `VIDFARM_<STAGE>_API_KEY_SALT` — API key hashing
 - `VIDFARM_<STAGE>_BOOTSTRAP_*` — initial admin user
-- `VIDFARM_<STAGE>_REMOTION_*` — shared Remotion Lambda ARN + region
 - `VIDFARM_<STAGE>_RESEND_*` — email
 - `VIDFARM_<STAGE>_SENTRY_*` — Sentry DSN
 - `GHOSTCUT_KEY`, `GHOSTCUT_SECRET` — GhostCut credentials
@@ -339,7 +343,7 @@ Legacy but 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. Remotion asset preflight failures usually mean a broken media URL in composition.html.
+- **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.
@@ -362,7 +366,7 @@ Legacy but still active:
 
 ## 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` (→ `/export`), `approve`, `schedule`, `posts`/`schedules`, `upload`/`download`, `login`/`whoami`/`provider-keys`, plus a raw `api <METHOD> <path>` passthrough. Each command prints its prod frontend URL as a first-class output, and `--json` gives pure JSON for agents. The command↔route table lives in `SKILL.director.md`.
+`@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` (My Files read+write), `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.

package/dist/src/cli.js

@@ -7,6 +7,7 @@ import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { computeCompositionGaps, insertMediaLayer, inspectComposition, replaceLayerWithMedia } from "./services/composition-edit.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
 // `serve` command boots the FULL editor locally (single origin, disk-backed
 // records + storage) so power users edit compositions on disk while a browser
@@ -40,7 +41,8 @@ Usage:
 
 Local editor loop:
   serve [template_id] [opts]  Boot the FULL editor locally (single origin, disk-backed).
-                              Records + storage run on disk; render stays on cloud.
+                              Records + storage run on disk; render runs in-process on
+                              this box for FREE (no cloud, no wallet charge).
                               With a template_id or --fork, pulls that composition
                               (or the template's default/shared decomposition) from
                               the cloud host onto local disk to edit offline.
@@ -56,19 +58,59 @@ Local editor loop:
   publish [template_id]     Push local composition.html/json to your fork  → PUT/PATCH composition + POST versions
 
 Discover & inspiration (browse the viral-video catalog, add your own source):
-  discover                  List the template/inspiration feed          → GET  /discover/feed
+  discover [query...]       List/search TEMPLATES (best for an offer)    → GET  /discover/feed
+    --query <text>          Keyword search (e.g. "weight loss app")
+    --limit <n>             Max results
+  videos [query...]         List/search source INSPIRATIONS              → GET  /api/v1/videos
+    --query <text>          Keyword search over the catalog
+    --mine                  Only your own uploaded inspirations
+    --limit <n>             Max results
   inspiration-add <url>     Ingest a TikTok/YT/IG/X video as a template  → POST /discover/templates
   inspiration-rm <id>       Delete a private inspiration/template you own → DELETE /discover/templates/:id
   inspiration-decompose <id>  AI-decompose an inspiration into scenes     → POST /api/v1/inspirations/:id/decompose
 
 Composition lifecycle (fork → decompose → snapshot → render):
   fork <template_id>        Fork a template into an editable composition → POST /api/v1/compositions
+  pull <forkId>             Sync composition.html/json + video-context   → GET  .../compositions/:forkId/{composition.html,...}
+                            + cast.json to disk, then print timeline gaps
+                            (blank space) and scene/layer keys to target.
+    --dir <path>            Local dir (default: .vidfarm/<forkId>)
+    --refetch               Overwrite local copies with the cloud version
   decompose <forkId>        Split the fork's source into scenes (smart)  → POST .../compositions/:forkId/auto-decompose
+
+Generate AI media and drop it on the timeline (for local coding agents):
+  generate <image|video>    Generate AI media, poll to the finished URL  → POST /api/v1/primitives/{images,videos}/generate
+    --prompt <text>         What to generate (required)
+    --ref <url|@file>       Reference image (repeatable): input_references
+                            for video, prompt_attachments for image. @file
+                            auto-uploads a local image and uses its URL.
+    --aspect-ratio <r>      e.g. 9:16 (match the composition canvas)
+    --duration <n>          Video only: seconds of footage (e.g. 4)
+    --resolution <r>        Video only: 480p|720p|1080p|1K|2K|4K
+    --audio                 Video only: generate an audio track
+    --provider <p>          openai|gemini|openrouter (omit to auto-pick)
+    --model <m>             Model override (omit for provider defaults)
+    --no-wait               Return the job id instead of polling to the URL
+    --place <dir>           After generating, place it into that composition
+    --at <time> | --replace <layer_key>   Placement (fill gap vs replace scene)
+  place <dir|composition.html>   Insert a media URL into a local composition
+                            (fill a gap or replace a scene) — same clip markup
+                            the browser editor makes; serve live-morphs it.
+    --src <url>             Direct media URL to place (required)
+    --kind <video|image>    Media kind (inferred from the URL if omitted)
+    --at <time>             Start it at this time (seconds / mm:ss) — fill a gap
+    --replace <layer_key>   Replace this scene/layer (copies its timing+geometry)
+    --duration <n>          Timeline length in seconds
+    --track <n>             Timeline layer index (auto if omitted)
+    --x --y --width --height   Geometry as % (default full canvas 0/0/100/100)
+    --object-fit <fit>      cover|contain|fill|none|scale-down (default cover)
   ghostcut <forkId>         Read the two video sources: original vs      → GET  .../compositions/:forkId/ghostcut
                             decomposed (caption-free), non-billing
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
-  render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/export
+  render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/render
+                            Cloud render costs ~$0.01-$0.10; against a local
+                            'serve' host it renders in-process for FREE.
   render-status <forkId> <renderId>   Poll one render job               → GET  .../compositions/:forkId/renders/:renderId
   visibility <forkId> <private|public>   Set fork visibility            → PATCH .../compositions/:forkId/visibility
   clone <forkId>            Clone a fork as a new starting point         → POST .../compositions/:forkId/clone
@@ -96,13 +138,30 @@ Agent skill (install the latest director skill so your AI agent can act):
     --print                 Print the skill to stdout instead of writing a file
 
 Files (multi-step flows the devcli handles for you):
-  upload <file>             Upload a local file, print its durable URL   → POST /api/v1/user/me/temporary-files/upload
+  upload <file>             Upload to the EPHEMERAL temp store, print URL → POST /api/v1/user/me/temporary-files/upload
     --folder <path>         Namescope the upload under a product/offer folder
+  put-file [file]           Write a file INTO My Files (persistent lib)  → POST /api/v1/user/me/attachments/upload
+    --folder <path>         Namescope under a product/offer folder (e.g. acme-skincare)
+    --as <name>             Name the saved file (required for --content/--stdin)
+    --content <text>        Inline text to save (needs --as); or pipe stdin with --stdin
+                            e.g. vidfarm put-file About.md --folder acme-skincare
+                                 echo "..." | vidfarm put-file --stdin --as About.md --folder acme
   download <url> [dest]     Stream any Vidfarm/media URL to disk
   files                     List My Files assets + folders               → GET /api/v1/user/me/attachments
     --folder <path>         Only files under this folder (e.g. a product/offer)
   get-file <id> [dest]      Resolve a My Files id to its URL and download it
     --print                 Print text contents (md/txt/csv/json) instead of saving
+  put-file / get-file / files are the My Files (persistent) read+write set;
+  upload is the throwaway temp store for dropping media into a composition.
+
+Cost spectrum (default to the cheapest approach that works; see SKILL.director.md):
+  free        Reuse a decomposed template, swap captions/images/existing MP4s
+              (My Files / your computer / web search), render on a local 'serve' box.
+  ~$0.001-$0.03   Same reuse, but cloud 'render' (~$0.01-$0.10). Image gen is cheap too.
+  ~$1        AI-generate a few scenes for specificity (generate video ...).
+  $10+       Heavy AI generation (many/long AI clips, custom characters).
+  Notes: image gen is cheap (use freely); AI VIDEO gen is expensive (ask the user
+  first). Decompose is a one-time ~$0.10 — or skip it by forking a decomposed template.
 
 Escape hatch — call ANY route directly:
   api <METHOD> <path>       Raw REST call with auth + pretty errors
@@ -158,6 +217,9 @@ async function main() {
         case "discover":
             await runDiscoverCommand(rest);
             return;
+        case "videos":
+            await runVideosCommand(rest);
+            return;
         case "inspiration-add":
             await runInspirationAddCommand(rest);
             return;
@@ -170,6 +232,15 @@ async function main() {
         case "fork":
             await runForkCommand(rest);
             return;
+        case "pull":
+            await runPullCommand(rest);
+            return;
+        case "generate":
+            await runGenerateCommand(rest);
+            return;
+        case "place":
+            await runPlaceCommand(rest);
+            return;
         case "decompose":
             await runDecomposeCommand(rest);
             return;
@@ -243,6 +314,10 @@ async function main() {
         case "get-file":
             await runGetFileCommand(rest);
             return;
+        case "put-file":
+        case "save-file":
+            await runPutFileCommand(rest);
+            return;
         default:
             if (!command.startsWith("-")) {
                 // Positional template id → default to booting the local editor.
@@ -972,6 +1047,39 @@ function safeSize(target) {
         return 0;
     }
 }
+// Guess a content type from a file name so My Files stores text docs as text/*
+// (a bare multipart Blob otherwise defaults to application/octet-stream, which
+// makes browsers download .md/.txt instead of showing them). Mirrors the common
+// cases of the server's inferAttachmentContentType; returns "" when unknown so
+// the server can fall back to its own inference.
+function guessContentType(fileName) {
+    const dot = fileName.lastIndexOf(".");
+    const ext = dot >= 0 ? fileName.slice(dot).toLowerCase() : "";
+    switch (ext) {
+        case ".md": return "text/markdown; charset=utf-8";
+        case ".txt": return "text/plain; charset=utf-8";
+        case ".csv": return "text/csv; charset=utf-8";
+        case ".json": return "application/json";
+        case ".srt":
+        case ".vtt": return "text/plain; charset=utf-8";
+        case ".png": return "image/png";
+        case ".jpg":
+        case ".jpeg": return "image/jpeg";
+        case ".gif": return "image/gif";
+        case ".webp": return "image/webp";
+        case ".svg": return "image/svg+xml";
+        case ".mp4":
+        case ".m4v": return "video/mp4";
+        case ".mov": return "video/quicktime";
+        case ".webm": return "video/webm";
+        case ".mp3": return "audio/mpeg";
+        case ".wav": return "audio/wav";
+        case ".m4a": return "audio/mp4";
+        case ".aac": return "audio/aac";
+        case ".pdf": return "application/pdf";
+        default: return "";
+    }
+}
 function formatBytes(bytes) {
     if (bytes >= 1024 * 1024)
         return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
@@ -1032,13 +1140,33 @@ async function runApiCommand(argv) {
         process.exitCode = 1;
 }
 // ── Discover & inspiration ──────────────────────────────────────────────────
+// `discover` lists TEMPLATES; `--query` keyword-searches the catalog so an agent
+// CLI (Claude Code / Codex) can answer "which templates suit my <offer>?". Each
+// result carries decompose-derived promotions/keywords/summary to reason over.
 async function runDiscoverCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: false, options: { ...commonOptions(), limit: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), limit: { type: "string" }, query: { type: "string" } } });
     const ctx = commonContext(parsed.values);
-    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/discover/feed", auth: ctx.auth, query: { limit: parsed.values.limit } });
+    const query = (parsed.values.query ?? parsed.positionals.join(" ").trim()) || undefined;
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/discover/feed", auth: ctx.auth, query: { limit: parsed.values.limit, q: query } });
     assertApiOk(result, "discover");
     emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
 }
+// `videos` lists source INSPIRATIONS (the raw viral videos), with the same
+// keyword search and an optional --mine for the caller's own uploads.
+async function runVideosCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), limit: { type: "string" }, query: { type: "string" }, mine: { type: "boolean", default: false } } });
+    const ctx = commonContext(parsed.values);
+    const query = (parsed.values.query ?? parsed.positionals.join(" ").trim()) || undefined;
+    const result = await apiRequest({
+        method: "GET",
+        host: ctx.host,
+        path: "/api/v1/videos",
+        auth: ctx.auth,
+        query: { limit: parsed.values.limit, q: query, mine: parsed.values.mine ? "true" : undefined }
+    });
+    assertApiOk(result, "videos");
+    emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
+}
 async function runInspirationAddCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), tagline: { type: "string" }, notes: { type: "string" } } });
     const sourceUrl = parsed.positionals[0];
@@ -1168,7 +1296,7 @@ async function runRenderCommand(argv) {
     const result = await apiRequest({
         method: "POST",
         host: ctx.host,
-        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/export`,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/render`,
         auth: ctx.auth,
         body: { title: parsed.values.title, tracer: parsed.values.tracer }
     });
@@ -1212,6 +1340,351 @@ async function runRenderStatusCommand(argv) {
     assertApiOk(result, "render-status");
     emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.outputUrl]]);
 }
+// ── AI generation + timeline placement (for local coding agents) ────────────
+// `generate` submits an AI image/video primitive job and (by default) polls it
+// to the finished media URL — the async poll the raw `api` command can't do for
+// you. `place` drops any media URL into a local composition.html (fill a gap or
+// replace a scene), producing the SAME clip markup the browser editor makes, so
+// `serve` live-morphs it and `publish` pushes it. Together they let a Claude
+// Code / Codex agent do end-to-end "generate → insert" without hand-editing HTML.
+// Parse "5", "5.5", "mm:ss", or "hh:mm:ss" into seconds.
+function parseTimeToSeconds(raw) {
+    const trimmed = raw.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed))
+        return Number(trimmed);
+    const parts = trimmed.split(":").map((p) => Number(p));
+    if (parts.some((n) => !Number.isFinite(n)))
+        throw new Error(`Invalid time: ${raw} (use seconds, mm:ss, or hh:mm:ss).`);
+    return parts.reduce((acc, n) => acc * 60 + n, 0);
+}
+// Pull the finished media URL out of a settled primitive job (GET /me/jobs/:id).
+// Mirrors the server's extractOutputUrlFromJob.
+function resolveJobMediaUrl(job) {
+    if (!job || typeof job !== "object")
+        return null;
+    const readStr = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
+    const result = (job.result && typeof job.result === "object") ? job.result : {};
+    const output = (result.output && typeof result.output === "object") ? result.output : result;
+    const direct = readStr(output.primary_file_url)
+        ?? readStr(output.video?.file_url)
+        ?? readStr(output.image?.file_url)
+        ?? readStr(output.render?.output_url);
+    if (direct)
+        return direct;
+    if (Array.isArray(output.files)) {
+        for (const f of output.files) {
+            const u = readStr(typeof f === "string" ? f : (f?.file_url ?? f?.url));
+            if (u)
+                return u;
+        }
+    }
+    if (Array.isArray(job.artifacts)) {
+        for (const a of job.artifacts) {
+            const u = readStr(a?.public_url);
+            if (u)
+                return u;
+        }
+    }
+    return null;
+}
+// Poll a primitive job until it settles (or times out). Returns the final job.
+async function pollPrimitiveJob(ctx, jobId) {
+    const MAX_WAIT_MS = 8 * 60 * 1000;
+    const startedAt = Date.now();
+    let last = null;
+    for (;;) {
+        await sleep(5000);
+        const res = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/user/me/jobs/${encodeURIComponent(jobId)}`, auth: ctx.auth });
+        if (res.ok && res.json) {
+            last = res.json;
+            const status = String(last.status ?? "");
+            if (!ctx.json)
+                console.log(`${DIM}  ${status}${typeof last.progress === "number" ? ` ${Math.round(last.progress * 100)}%` : ""}${RESET}`);
+            if (status === "succeeded" || status === "failed" || status === "cancelled")
+                return last;
+            if (resolveJobMediaUrl(last))
+                return last;
+        }
+        if (Date.now() - startedAt > MAX_WAIT_MS)
+            return last ?? { status: "timeout" };
+    }
+}
+// Upload a local file to the ephemeral temp store, returning its durable URL.
+// Used to turn `--ref @local.png` into a direct asset URL for reference images.
+async function uploadTempFileForRef(ctx, absPath) {
+    if (!existsSync(absPath))
+        throw new Error(`No such reference file: ${absPath}`);
+    const form = new FormData();
+    form.append("file", new Blob([readFileSync(absPath)]), path.basename(absPath));
+    const res = await fetch(new URL("/api/v1/user/me/temporary-files/upload", ctx.host), { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    if (!res.ok)
+        throw new Error(`reference upload failed (${res.status}): ${text.slice(0, 200)}`);
+    const url = json?.file?.view_url ?? json?.file?.s3_url;
+    if (!url)
+        throw new Error("reference upload returned no durable URL.");
+    return url;
+}
+// Resolve --ref values: pass http(s) URLs through; upload @local files.
+async function resolveReferenceUrls(ctx, refs) {
+    const out = [];
+    for (const raw of refs ?? []) {
+        const value = raw.trim();
+        if (!value)
+            continue;
+        if (value.startsWith("@")) {
+            out.push(await uploadTempFileForRef(ctx, path.resolve(process.cwd(), value.slice(1))));
+        }
+        else if (/^https?:\/\//i.test(value)) {
+            out.push(value);
+        }
+        else {
+            // Bare path with no @ — treat as a local file too, for convenience.
+            out.push(await uploadTempFileForRef(ctx, path.resolve(process.cwd(), value)));
+        }
+    }
+    return out;
+}
+function inferMediaKindFromUrl(url) {
+    return /\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(url) ? "video" : "image";
+}
+// Resolve a composition.html on disk from a file path or a directory holding one.
+function resolveCompositionHtmlPath(target) {
+    const abs = path.resolve(process.cwd(), target);
+    if (existsSync(abs) && statSync(abs).isDirectory()) {
+        const inside = path.join(abs, "composition.html");
+        if (!existsSync(inside))
+            throw new Error(`No composition.html inside ${abs}. Run \`vidfarm pull <forkId> --dir ${target}\` first.`);
+        return inside;
+    }
+    if (!existsSync(abs))
+        throw new Error(`No such composition file or dir: ${abs}.`);
+    return abs;
+}
+// Apply an insert/replace of a media URL onto a composition.html on disk.
+function placeMediaOnDisk(input) {
+    const html = readFileSync(input.htmlPath, "utf8");
+    const opts = {
+        kind: input.kind,
+        src: input.src,
+        layerKey: input.layerKey,
+        start: input.at,
+        duration: input.duration,
+        track: input.track,
+        x: input.x,
+        y: input.y,
+        width: input.width,
+        height: input.height,
+        objectFit: input.objectFit,
+        slug: input.slug
+    };
+    const result = input.replace
+        ? replaceLayerWithMedia(html, input.replace, opts)
+        : insertMediaLayer(html, opts);
+    writeFileSync(input.htmlPath, result.html);
+    return { layerKey: result.layerKey, gaps: computeCompositionGaps(result.html) };
+}
+async function runGenerateCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            prompt: { type: "string" },
+            ref: { type: "string", multiple: true },
+            "aspect-ratio": { type: "string" },
+            duration: { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            resolution: { type: "string" },
+            audio: { type: "boolean", default: false },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" },
+            // Fused placement onto a local composition.html.
+            place: { type: "string" },
+            at: { type: "string" },
+            replace: { type: "string" },
+            track: { type: "string" },
+            "layer-key": { type: "string" }
+        }
+    });
+    const mediaType = parsed.positionals[0];
+    if (mediaType !== "image" && mediaType !== "video") {
+        throw new Error("generate requires a media type: `vidfarm generate image ...` or `vidfarm generate video ...`.");
+    }
+    const prompt = parsed.values.prompt;
+    if (!prompt || !prompt.trim())
+        throw new Error("generate requires --prompt \"...\".");
+    const ctx = commonContext(parsed.values);
+    const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
+    const payload = { prompt };
+    if (parsed.values["aspect-ratio"])
+        payload.aspect_ratio = parsed.values["aspect-ratio"];
+    if (parsed.values.provider)
+        payload.provider = parsed.values.provider;
+    if (parsed.values.model)
+        payload.model = parsed.values.model;
+    if (mediaType === "video") {
+        if (parsed.values.duration)
+            payload.duration = Math.round(Number(parsed.values.duration));
+        if (parsed.values.resolution)
+            payload.resolution = parsed.values.resolution;
+        if (parsed.values.audio)
+            payload.generate_audio = true;
+        if (refs.length)
+            payload.input_references = refs.slice(0, 8);
+    }
+    else if (refs.length) {
+        payload.prompt_attachments = refs.slice(0, 16);
+    }
+    const tracer = parsed.values.tracer ?? `devcli-gen-${Date.now().toString(36)}`;
+    const route = mediaType === "video" ? "/api/v1/primitives/videos/generate" : "/api/v1/primitives/images/generate";
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: route, auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "generate");
+    const jobId = submit.json?.job_id;
+    const wait = !parsed.values["no-wait"];
+    if (!wait || !jobId) {
+        if (!ctx.json && jobId)
+            console.log(`${DIM}Queued ${jobId} (tracer ${tracer}). Poll: vidfarm api GET /api/v1/user/me/jobs/${jobId} — or drop --no-wait to auto-poll.${RESET}`);
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json)
+        console.log(`${DIM}Generating ${mediaType} (${jobId})… polling every 5s.${RESET}`);
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const mediaUrl = resolveJobMediaUrl(job);
+    const status = String(job?.status ?? "");
+    if (!mediaUrl) {
+        if (ctx.json) {
+            printJson({ ok: false, job_id: jobId, status, job });
+        }
+        else {
+            console.log(`${RED}Generation ${status || "did not finish"} — no media URL.${RESET}`);
+            printJson(job);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // Optional fused placement onto a local composition.html.
+    let placement = null;
+    if (parsed.values.place) {
+        const htmlPath = resolveCompositionHtmlPath(String(parsed.values.place));
+        placement = placeMediaOnDisk({
+            htmlPath,
+            src: mediaUrl,
+            kind: mediaType,
+            at: parsed.values.at ? parseTimeToSeconds(String(parsed.values.at)) : undefined,
+            replace: parsed.values.replace,
+            track: parsed.values.track ? Number(parsed.values.track) : undefined,
+            layerKey: parsed.values["layer-key"]
+        });
+        if (!ctx.json)
+            console.log(`${GREEN}Placed as ${placement.layerKey} in ${htmlPath}. Run \`vidfarm publish --dir ${path.dirname(htmlPath)}\` (or it live-morphs under \`serve\`).${RESET}`);
+    }
+    if (ctx.json) {
+        printJson({ ok: true, job_id: jobId, media_url: mediaUrl, media_type: mediaType, placement });
+    }
+    else {
+        console.log(`${GREEN}${mediaType} ready:${RESET} ${mediaUrl}`);
+        if (!placement)
+            console.log(`${DIM}Place it with: vidfarm place <dir> --src "${mediaUrl}" --kind ${mediaType} --at <time>|--replace <layer_key>${RESET}`);
+    }
+}
+async function runPlaceCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            src: { type: "string" },
+            kind: { type: "string" },
+            at: { type: "string" },
+            duration: { type: "string" },
+            replace: { type: "string" },
+            track: { type: "string" },
+            x: { type: "string" },
+            y: { type: "string" },
+            width: { type: "string" },
+            height: { type: "string" },
+            "object-fit": { type: "string" },
+            "layer-key": { type: "string" },
+            slug: { type: "string" }
+        }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("place requires a composition path: `vidfarm place <dir-or-composition.html> --src <url> ...`.");
+    const src = parsed.values.src;
+    if (!src || !/^https?:\/\//i.test(src))
+        throw new Error("place requires --src <direct media URL>.");
+    const ctx = commonContext(parsed.values);
+    const htmlPath = resolveCompositionHtmlPath(target);
+    const kind = parsed.values.kind === "video" || parsed.values.kind === "image"
+        ? parsed.values.kind
+        : inferMediaKindFromUrl(src);
+    const num = (v) => (v !== undefined ? Number(v) : undefined);
+    const placement = placeMediaOnDisk({
+        htmlPath,
+        src,
+        kind,
+        at: parsed.values.at ? parseTimeToSeconds(String(parsed.values.at)) : undefined,
+        duration: num(parsed.values.duration),
+        replace: parsed.values.replace,
+        track: num(parsed.values.track),
+        x: num(parsed.values.x),
+        y: num(parsed.values.y),
+        width: num(parsed.values.width),
+        height: num(parsed.values.height),
+        objectFit: parsed.values["object-fit"],
+        layerKey: parsed.values["layer-key"],
+        slug: parsed.values.slug
+    });
+    if (ctx.json) {
+        printJson({ ok: true, layer_key: placement.layerKey, path: htmlPath, timeline_gaps: placement.gaps });
+    }
+    else {
+        console.log(`${GREEN}Placed ${kind} as ${placement.layerKey}${parsed.values.replace ? ` (replaced ${parsed.values.replace})` : ""} in ${htmlPath}.${RESET}`);
+        console.log(`${DIM}Remaining timeline gaps: ${placement.gaps.length ? placement.gaps.map((g) => `${g.start}-${g.end}s`).join(", ") : "none"}.${RESET}`);
+        console.log(`${DIM}Publish with: vidfarm publish --dir ${path.dirname(htmlPath)} --fork <forkId>  (or it live-morphs under \`serve\`).${RESET}`);
+    }
+}
+async function runPullCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), dir: { type: "string" }, refetch: { type: "boolean", default: false } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("pull requires a fork id: `vidfarm pull <forkId> [--dir <path>]`.");
+    const ctx = commonContext(parsed.values);
+    const dir = path.resolve(process.cwd(), parsed.values.dir ?? path.join(".vidfarm", forkId));
+    mkdirSync(dir, { recursive: true });
+    await fetchCompositionFiles({ host: ctx.host, forkId, dir, apiKey: ctx.auth.apiKey, shareToken: ctx.auth.shareToken, refetch: Boolean(parsed.values.refetch) });
+    const htmlPath = path.join(dir, "composition.html");
+    if (!existsSync(htmlPath))
+        throw new Error(`pull did not fetch composition.html for ${forkId} (check credentials / fork id).`);
+    const info = inspectComposition(readFileSync(htmlPath, "utf8"));
+    const hasContext = existsSync(path.join(dir, "video-context.json"));
+    const hasCast = existsSync(path.join(dir, "cast.json"));
+    if (ctx.json) {
+        printJson({ ok: true, fork_id: forkId, dir, has_video_context: hasContext, has_cast: hasCast, ...info });
+        return;
+    }
+    console.log(`${GREEN}Pulled ${forkId} → ${dir}${RESET}`);
+    console.log(`${DIM}Canvas ${info.width ?? "?"}x${info.height ?? "?"} (${info.aspect_ratio ?? "?"}), ${info.duration_seconds}s, ${info.layers.length} layers.${RESET}`);
+    console.log(`${BOLD}Timeline gaps (blank space to fill):${RESET} ${info.gaps.length ? info.gaps.map((g) => `${g.start}-${g.end}s (${g.duration}s)`).join(", ") : "none"}`);
+    console.log(`${BOLD}Scenes / layers (keys to replace):${RESET}`);
+    for (const layer of info.layers) {
+        const flags = [layer.is_timeline_proxy ? "proxy" : null, layer.is_full_canvas ? "full-canvas" : null].filter(Boolean).join(",");
+        console.log(`  ${layer.key}  ${DIM}${layer.kind ?? "?"} ${layer.start}-${(layer.start + layer.duration).toFixed(2)}s track${layer.track}${flags ? ` [${flags}]` : ""}${layer.slug ? ` slug=${layer.slug}` : ""}${RESET}`);
+    }
+    console.log(`${DIM}Grounding: ${hasContext ? "video-context.json ✓" : "video-context.json ✗ (run `vidfarm decompose`)"}, ${hasCast ? "cast.json ✓" : "cast.json ✗"}.${RESET}`);
+    console.log(`${DIM}Next: vidfarm generate video --prompt "..." --aspect-ratio ${info.aspect_ratio ?? "9:16"} --place ${dir} --at <gap start>|--replace <layer_key>${RESET}`);
+}
 async function runVisibilityCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
     const forkId = parsed.positionals[0];
@@ -1526,6 +1999,76 @@ async function runGetFileCommand(argv) {
         console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
     }
 }
+// Write a file INTO My Files — the persistent per-user library (`/me/attachments`),
+// NOT the ephemeral temporary-files store that `upload` targets. This is what an
+// agent uses to save durable context docs during Getting Started (About.md,
+// Interview.md, awareness-levels.md, persuasive-angles.md, ad-hooks.md) or to drop
+// brand assets under /brand-assets, product demos under /product-demos, etc.
+// Content can come from a local file (positional), inline --content, or piped stdin.
+// It is the write counterpart to `files`/`get-file` and the same store the /editor
+// AI copilot writes to via the browse_files write action.
+async function runPutFileCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            folder: { type: "string" },
+            as: { type: "string" },
+            content: { type: "string" },
+            stdin: { type: "boolean", default: false }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const localPath = parsed.positionals[0];
+    const asName = parsed.values.as ? String(parsed.values.as) : undefined;
+    let buffer;
+    let fileName = asName;
+    if (parsed.values.stdin) {
+        if (!fileName)
+            throw new Error("put-file --stdin requires --as <name> to name the file in My Files.");
+        buffer = readFileSync(0); // fd 0 = stdin (piped content)
+    }
+    else if (parsed.values.content != null) {
+        if (!fileName)
+            throw new Error("put-file --content requires --as <name> to name the file in My Files.");
+        buffer = Buffer.from(String(parsed.values.content), "utf8");
+    }
+    else if (localPath) {
+        const abs = path.resolve(process.cwd(), localPath);
+        if (!existsSync(abs))
+            throw new Error(`No such file: ${abs}`);
+        buffer = readFileSync(abs);
+        if (!fileName)
+            fileName = path.basename(abs);
+    }
+    else {
+        throw new Error("put-file requires a local file path, or --content/--stdin with --as <name>.");
+    }
+    if (!fileName)
+        throw new Error("put-file could not determine a file name. Pass --as <name>.");
+    const contentType = guessContentType(fileName);
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(buffer)], contentType ? { type: contentType } : undefined), fileName);
+    if (parsed.values.folder)
+        form.append("folder_path", String(parsed.values.folder));
+    const res = await fetch(new URL("/api/v1/user/me/attachments/upload", ctx.host), {
+        method: "POST",
+        headers: buildAuthHeaders(ctx.auth),
+        body: form
+    });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    const result = { status: res.status, ok: res.ok, json, text };
+    assertApiOk(result, "put-file");
+    emitResult(result, ctx.json, [["My Files URL", result.json?.attachment?.viewUrl]]);
+}
 // ── Agent skill ───────────────────────────────────────────────────────────────
 // Install the latest director skill onto disk as a Claude Code / agent skill so
 // the user's AI agent can read SKILL.director.md and act. We pull the freshest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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": {
@@ -63,9 +63,6 @@
     "@fontsource/tiktok-sans": "^5.2.4",
     "@hono/node-server": "^1.14.4",
     "@hyperframes/aws-lambda": "^0.7.21",
-    "@remotion/bundler": "4.0.355",
-    "@remotion/lambda": "4.0.355",
-    "@remotion/renderer": "4.0.355",
     "@sentry/aws-serverless": "^10.56.0",
     "@sentry/hono": "^10.56.0",
     "@sentry/node": "^10.56.0",
@@ -81,7 +78,6 @@
     "linkedom": "^0.18.12",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "remotion": "4.0.355",
     "sharp": "^0.34.5",
     "zod": "^3.25.28"
   },