@officexapp/vidfarm-devcli 0.21.10 → 0.21.12

package/.agents/skills/hyperframes-core/SKILL.md

@@ -48,6 +48,8 @@ The standalone root needs an explicit **sized box** (`width`/`height` in px), an
 
 Each composition registers **exactly one** `gsap.timeline({ paused: true })` at `window.__timelines["<id>"]` (key = root `data-composition-id`), built **synchronously** at page load. Render duration = root `data-duration`, not timeline length. Don't manually nest sub-timelines into the host. Full contract (incl. non-GSAP runtimes) → `references/determinism-rules.md` + `hyperframes-animation/adapters/`.
 
+Because the timeline is paused and seek-safe, **the frame at t=0 is whatever the DOM computes at time 0** — and that frame doubles as the video's preview thumbnail (autoplay-off feeds, share cards, `<video>` poster, file/scrubber thumbnails). If the opening scene animates its elements in from `opacity:0`/offset, t=0 is a blank/black poster that nobody clicks. Design the opening scene's initial state as a real, interesting still. Craft guidance → `hyperframes-creative/references/beat-direction.md` ("The opening frame is the poster").
+
 ### Non-negotiable rules (silent bugs `lint`/`validate`/`inspect` won't catch)
 
 Surfaced here; full rationale in the linked reference. Do not violate:

package/.agents/skills/hyperframes-creative/SKILL.md

@@ -40,6 +40,7 @@ For motion patterns, scene blueprints, transitions, and CSS marker effects, use
 | Structured expansion for open-ended prompts                              | `references/prompt-expansion.md`               |
 | Video-medium density, scale, color, frame composition                    | `references/video-composition.md`              |
 | Per-beat direction, rhythm planning, transition timing                   | `references/beat-direction.md`                 |
+| Opening/first frame as the preview thumbnail (t=0 must not be empty)      | `references/beat-direction.md`                 |
 | Post-authoring spec verification (colors, type, corners, spacing, depth) | `references/design-adherence.md`               |
 | High-level motion guardrails and GSAP-quality rules                      | `references/motion-principles.md`              |
 | Font selection, pairings, rendered-video type guardrails                 | `references/typography.md`                     |

package/.agents/skills/hyperframes-creative/references/beat-direction.md

@@ -4,6 +4,7 @@ How to plan and direct individual scenes (beats) in a multi-scene composition. R
 
 ## Contents
 
+- The opening frame is the poster
 - Per-beat direction
 - Concept
 - Mood direction
@@ -16,6 +17,22 @@ How to plan and direct individual scenes (beats) in a multi-scene composition. R
 
 ---
 
+## The Opening Frame Is the Poster
+
+**The very first frame (t=0) is the video's preview thumbnail** — it's the still the viewer stares at *before* they press play (feed autoplay-off, share cards, `<video>` poster, file thumbnails, the editor's timeline scrubber at 0). A blank, black, or half-built opening frame is a dead thumbnail: nobody presses play on empty. Treat t=0 as a designed poster that has to sell the click.
+
+The trap is mechanical: most beats animate their elements IN from `opacity:0` / offset / blur, so at t=0 — before the entrance runs — the frame is empty. That's fine for beat 2 onward (the previous beat covers the cut), but for **beat 1 it means the poster is a black screen.** Seek-safe rendering shows exactly whatever the DOM computes at 0, so whatever your entrance starts from IS the thumbnail.
+
+Fix it deliberately — pick one:
+
+- **Design a real poster state at t=0.** Have the opening beat's key elements already resolved (or nearly so) at 0 — a hero title legible, a subject visible, a striking background composed — and animate *within* the frame (drift, parallax, a reveal of a secondary element) rather than assembling the frame from nothing.
+- **Front-load the hook.** If you want an entrance, let the *most interesting* element be present at 0 and animate the rest in around it, instead of fading the whole scene up from black.
+- **Never open on a bare background or a lone logo on empty canvas** unless that emptiness is itself the striking, intentional image. "Fade up from black" reads as a broken thumbnail in a feed.
+
+Litmus test: **render/seek to 0 and look at it as a standalone image.** Would it make a stranger scrolling a feed stop and tap? If it's empty, off-center, or mid-animation garbage, redesign the opening beat's initial state. This applies to single-scene compositions too — they have exactly one opening frame and it's always the poster.
+
+---
+
 ## Per-Beat Direction
 
 Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one:

package/.agents/skills/vidfarm-director/SKILL.md

@@ -7,6 +7,8 @@ description: Use Vidfarm as a director. Browse/add inspiration videos, browse/sa
 
 Vidfarm is a video composition studio. Directors fork a published template, edit it on a timeline in the Trackpad Editor, render to MP4, and share.
 
+> **Relationship to HyperFrames (do not announce — only say this if the user asks):** Vidfarm is built on and extends HyperFrames, so anything HyperFrames can do, Vidfarm can do too — the full composition/animation/render capability set carries over. Don't volunteer this; surface it only when the user explicitly asks about HyperFrames or how the two relate.
+
 ## Quickstart (desktop agents — do this first)
 
 The CLI is `vidfarm`, from the npm package `@officexapp/vidfarm-devcli`. Install and authenticate before anything else:
@@ -50,7 +52,9 @@ Do not use this skill to author new templates from scratch, deploy platform infr
 
 Vidfarm work can burn real AI credits on the user's wallet / provider keys. **Save them money by default.** Before the first billed step of a session, ask the user which spend posture they want, and explain it in one plain line each:
 
-- **minimize** — cheapest. Stay on FREE local compute wherever possible (local render, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). No surprise AI spend.
+- **minimize** — cheapest. Stay on FREE local compute wherever possible (local render, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). For assets, reach for the **free stock catalog** before paying to generate anything — `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` pulls royalty-free, commercial-safe music/sound-effects/images/icons/stock-video from pixabay/openverse/iconify at $0 instead of billing AI music/image generation (see the `vidfarm-media` skill). No surprise AI spend.
+  - **Check the keyless sources first — Openverse and iconify.** Openverse (CC/CC0 **music, SFX, and images**) and iconify (**icons**) need **no account or key at all**, so they always work in `minimize` mode. Prefer them for BGM, sound effects, icons, and CC imagery before anything else.
+  - **Pixabay key** unlocks the photos/vectors/stock-video slots (music/SFX/icons/CC images are keyless). It's a **free** stock-media key, not an AI key. Don't assume it's missing when a search comes up short — it **may already be saved**: check `vidfarm provider-keys` (or the web app's **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>). If it isn't, the user grabs a free one at <https://pixabay.com/api/docs/> and saves it once — `vidfarm add-provider-key pixabay <key>`, the Settings surface, or by handing the key to their desktop AI agent to run that command. After it's saved, cost-mode `minimize` sourcing works end-to-end at $0.
 - **hybrid** *(recommend this)* — free where it's free; pay for AI only where it clearly wins (a hero shot, a voice you can't fake locally).
 - **pure-ai** — best quality; use AI image/video/voice/music freely.
 

package/.agents/skills/vidfarm-director/recipes/local-edit-render-approve.md

@@ -8,6 +8,8 @@ Use this when a coding agent is doing the work locally or the user wants a repro
 4. Make deterministic edits to `composition.html` and optionally `composition.json`.
 5. Validate with `vidfarm lint` or `vidfarm stills` when useful.
 6. Render with `vidfarm render <forkId> --dir ./work --wait`.
-7. Approve the finished MP4 with `vidfarm approve --video <url> --caption "..."`.
+7. Approve the finished MP4 with `vidfarm approve --video <url|./final.mp4> --caption "..."`. This prints the shareable `share_url`.
+
+**Approving a locally rendered file → cloud preview link.** Approve takes media by **URL**, not bytes, and an approved post is **permanent** — so the local MP4 must land in **durable My Files**, not the 30-day temp store (a temp video would 404 the share page after 30 days). The devcli presigns, PUTs the bytes **direct to S3**, finalizes, then approves with that durable URL — so `vidfarm approve --video ./final.mp4` handles files up to **200 MB**, bypasses the ~6 MB Lambda request-body limit, and the share link never breaks. By raw REST: `POST /api/v1/user/me/attachments/presign` → PUT to the returned S3 URL → `POST /api/v1/user/me/attachments` (finalize) → pass the returned `viewUrl` in the approve `media` array. Do not multipart-POST a big file to `.../attachments/upload` against the cloud host (Lambda-bound, ~6 MB cap). Add `vidfarm approve --temp` only when you want a disposable 30-day preview.
 
 Prefer this path for batch work, CI-like edits, or when the user wants free local rendering through `vidfarm serve`.

package/.agents/skills/vidfarm-director/references/automation-and-local-dev.md

@@ -148,7 +148,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm visibility <forkId> <private\|public>` | `PATCH .../compositions/:forkId/visibility` | set visibility |
 | `vidfarm clone <forkId>` | `POST .../compositions/:forkId/clone` | clone a fork |
 | `vidfarm share-link <forkId>` | `POST .../compositions/:forkId/share-links` | mint a share URL |
-| `vidfarm approve --video <url\|file> --caption "…"` | `POST /api/v1/approved/posts` | approve post (local `--video`/`--media` auto-upload to `temp/`; prints `share_url`) |
+| `vidfarm approve --video <url\|file> --caption "…"` | `POST /api/v1/approved/posts` | approve post — takes media by **`url`**. Local `--video`/`--media` auto-upload to **durable My Files** via presign→S3→finalize (up to **200 MB**, bypasses the ~6 MB Lambda limit) then approve with that URL, so the share video **never expires**; also accepts a `/files…` path. `--temp` opts into the 30-day temp store (throwaway preview only). Prints `share_url` |
 | `vidfarm posts` / `vidfarm post <id>` | `GET /api/v1/approved/posts[/:id]` | browse approved posts |
 | `vidfarm schedule <postId> --at <iso> --to <dest>` | `POST /api/v1/approved/posts/:postId/schedules` | schedule a post |
 | `vidfarm schedules <postId>` | `GET /api/v1/approved/posts/:postId/schedules` | browse scheduled posts |
@@ -157,7 +157,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm cost-mode [minimize\|hybrid\|pure-ai]` | (local `~/.vidfarm/cost-mode.json`) | show/set the money-saving preference every billed command respects; no arg = show + explain the three; `--clear` forgets it |
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only, paid plan. Aliases: `spend`, `costs` |
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
-| `vidfarm upload <file> [--folder <path>]` | `POST /api/v1/user/me/temporary-files/upload` | upload → durable URL (ephemeral; prefer `--folder temp` for scratch) |
+| `vidfarm upload <file> [--folder <path>]` | presign → S3 PUT → finalize (`.../temporary-files/presign` + `.../temporary-files`) | upload → durable URL (ephemeral, 30-day TTL; prefer `--folder temp` for scratch). Goes direct to S3, so large files (up to **200 MB**) bypass the ~6 MB Lambda body limit |
 | `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
 | `vidfarm download-post <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | download a social/media post into a durable MP4 or slideshow |
 | `vidfarm download-post-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download a social/media post's audio into a durable audio file |
@@ -182,13 +182,15 @@ If a local AI script rewrites text or scenes without consuming those files first
 
 **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/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.
+**Uploads/downloads/My-Files writes live in the devcli** because they are genuine multi-step / streaming flows: `upload` presigns the **ephemeral** temporary-files route, PUTs the bytes **direct to S3**, finalizes, and prints the durable URL to drop into a composition or approved post — going direct to S3 means large files (up to **200 MB**) never hit the ~6 MB Lambda request-body limit; `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.
+
+**Approving a locally rendered MP4 (the URL-first rule + the durability rule).** The approve route (`POST /api/v1/approved/posts`) and every media-taking route accept a `url`, never raw file bytes — so you never "upload to approve" in one shot. An approved post is a **permanent** share page, so the media must live in **durable My Files**, not the 30-day temp store (a temp-hosted video would 404 the share page after 30 days). The correct sequence for a big local file is: (1) `POST /api/v1/user/me/attachments/presign` with `{ file_name, content_type, size_bytes }` → (2) PUT the raw bytes to the returned presigned S3 URL → (3) `POST /api/v1/user/me/attachments` (finalize) → use the returned durable `viewUrl` as the approve media `url`. `vidfarm approve --video ./final.mp4` does all of this automatically (durable by default; up to **200 MB**). Never POST a large file as multipart to `.../attachments/upload` against the cloud host: that path proxies through Lambda and caps near 6 MB (it exists only as a fallback for local-storage `vidfarm serve` boxes). Only use the temp-store route (`.../temporary-files/*`, or `vidfarm approve --temp`) for a **throwaway** preview you don't mind losing in 30 days.
 
 ## Cost mode — the devcli's money-saving guardrail
 
-`vidfarm cost-mode <minimize|hybrid|pure-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, all the file-editing verbs).
+`vidfarm cost-mode <minimize|hybrid|pure-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates.
 
-- **minimize** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative. Use this to guarantee no surprise AI spend.
+- **minimize** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command.
 - **hybrid** *(default recommendation)* — billed ops run but print a one-line cost notice each.
 - **pure-ai** — billed ops run without gating; cost is still printed.
 
@@ -209,7 +211,7 @@ npx -y @officexapp/vidfarm-devcli serve <template_id>
 
 The **editor and its data** run locally (`RECORDS_DRIVER=local`, `STORAGE_DRIVER=local`) and rendering happens **in-process on this box for free**. Everything catalog-shaped still mirrors the cloud host ("cloud passthrough"): `/discover`, `/api/v1/videos`, and `/library` list the **cloud** catalog and the cloud account's approved posts next to anything local, opening a cloud template **seeds** its composition onto disk on demand, Add Template ingests into the cloud account, and approved-post actions (schedules, archive, delete) on cloud posts proxy through. Media a seeded composition already references stays on its cloud URLs — but you can also drop your **own local files** onto the timeline without any upload: `vidfarm place --src ./clip.mp4` copies the file into this box's disk store and references it by a `localhost/storage` URL (see "Local file paths as media" above), so the free in-process renderer plays it back with zero S3 involvement. Pass `--no-cloud` for a fully-offline box.
 
-**Rendering from a serve box** — the editor's **Render** button becomes a popover with two options when a cloud `--api-key` is configured: **Render Local (Free)** (in-process HyperFrames render, no charge) and **Render in Cloud** (hands the render to the cloud renderer, billed to the cloud account's wallet). Over REST, pass `render_target: "cloud"` in the `POST /render` body; the local box resolves (or clones, once) a publishable cloud fork, remembers the mapping in the fork's `upstream-link.json`, and `GET /renders/:renderId` transparently proxies the cloud job status.
+**Rendering from a serve box** — the editor's **Render** button becomes a popover with two options when a cloud `--api-key` is configured: **Render Local (Free)** (in-process Vidfarm render, no charge) and **Render in Cloud** (hands the render to the cloud renderer, billed to the cloud account's wallet). Over REST, pass `render_target: "cloud"` in the `POST /render` body; the local box resolves (or clones, once) a publishable cloud fork, remembers the mapping in the fork's `upstream-link.json`, and `GET /renders/:renderId` transparently proxies the cloud job status.
 
 How the loop works:
 - The composition lives on disk at `<data-dir>/storage/compositions/forks/<forkId>/working/composition.html` (default `<data-dir>` is `./.vidfarm-local`). Point your agent at that file.

package/.agents/skills/vidfarm-director/references/core-workflows.md

@@ -260,7 +260,7 @@ There is no single price for a video. The **approach** the director picks sets t
 
 | 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** — reference files straight off disk with `place --src ./file`, no upload — or a **web search**), and render **locally** via `vidfarm serve` (native in-process HyperFrames render — free and unguarded, no cloud). |
+| **Reuse + render locally** | **free** | Fork an already-decomposed template, swap captions / images / video with existing MP4s (from **My Files**, the director's **local computer** — reference files straight off disk with `place --src ./file`, no upload — or a **web search**), and render **locally** via `vidfarm serve` (native in-process Vidfarm 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. |

package/.agents/skills/vidfarm-director/references/editor-workflows.md

@@ -291,6 +291,19 @@ Two surfaces:
 - **Editor web/serve copilot** — `editor_action` `action_type=set_layer_media` with `object_fit` and `object_position` (both also seedable on `add_layer`/`generate_layer`). `editor_context.layers[]` reports each clip's current `object_fit`/`object_position` so you can read before re-cropping.
 - **Desktop agents (devcli)** — `vidfarm place ./work --src <url> --object-fit cover --object-position "25% 50%"` (also on `--replace <layer_key>`).
 
+### The opening frame is the post's thumbnail
+
+**The composition's first frame (t=0) is the still that represents the whole video before anyone presses play** — it's the poster on the approved-post share page, the `/discover` card, the autoplay-off feed preview, and the file/scrubber thumbnail. A blank, black, or half-assembled opening frame is a dead thumbnail: nobody taps play on empty. Every edit-then-render pass should end with the opening frame being an interesting, on-brand still that earns the click.
+
+The trap is mechanical: a scene whose layers animate in from `opacity:0` / offset / blur is **empty at t=0**, because the render is seek-safe and shows exactly the DOM state at time 0. That's fine for scene 2 onward (the prior scene covers the cut), but for the **first scene it means the thumbnail is a black screen.** Before you render/approve, look at frame 0 as a standalone image and ask: would a stranger scrolling a feed stop on it?
+
+Fix it in the editor when frame 0 is empty or dull:
+- Make the opening scene's key layers **already visible at t=0** (a legible hero title, a visible subject/clip, a composed background) and animate *within* the frame — use `set_layer_keyframes` starting from `offset:0, opacity:1` (drift/parallax/scale) rather than fading the whole scene up from black; or `nudge_layers`/`trim_layer` so the hero layer starts at 0 while secondary elements enter after.
+- If the opening clip is a video that starts on a dark/blank frame, `trim_layer edge=start` to move its in-point onto a stronger frame, or re-cover it full-canvas.
+- Preview the poster deterministically: seek the editor timeline to 0, or capture just frame 0 of a local composition with `vidfarm hf snapshot --at 0` (HyperFrames-CLI passthrough; seconds, not a full render), and judge that image on its own.
+
+This is the vidfarm-workflow reminder; the composition-authoring craft (poster-state design, front-loading the hook) lives in `hyperframes-creative/references/beat-direction.md` → "The opening frame is the poster". Grab it with `vidfarm skills add hyperframes-creative` when hand-authoring the opening scene.
+
 ### Ken Burns — animate still images (slow pan/zoom)
 
 Still images can carry a **Ken Burns effect**: a slow pan or zoom that runs across the clip's full duration, in the editor preview and both render paths identically. This is what makes a slideshow of stills feel like motion footage. It is a first-class layer property — the image layer's `<img>` gets `data-kenburns="<preset>"`; there is no separate keyframe authoring.
@@ -362,6 +375,6 @@ Beyond the Ken Burns / transition / animated-caption presets, the copilot can ha
   vidfarm render <forkId>            # local, $0.00
   ```
   If you ran `serve --port <N>`, pass `--base-url http://localhost:<N>` so the reference URL points at the right origin. A localhost `/storage` URL only resolves against the serve box that holds the file, so these compositions render/preview **locally**; to render in the cloud or share them, upload the media instead (below).
-- **Anywhere else (e.g. a `vidfarm pull` dir headed for cloud render/publish)** — the cloud renderer can't reach your disk, so a local `--src` file is **uploaded to the ephemeral temp store** first, namescoped under a throwaway `temp/` folder by default (override with `--folder`). Use this when the output must be a durable, shareable URL.
+- **Anywhere else (e.g. a `vidfarm pull` dir headed for cloud render/publish)** — the cloud renderer can't reach your disk, so a local `--src` file is **uploaded to the ephemeral temp store** first, namescoped under a throwaway `temp/` folder by default (override with `--folder`). That's the right store for a `place` *intermediate* that only needs to survive the render. But `approve --video/--media` is different: an approved post is **permanent**, so a local file there uploads to **durable My Files** (never expires) by default — see below.
 
-**`/temp` folder convention.** When you *do* need to upload throwaway media to Vidfarm (cloud render, `approve`, one-off URLs), keep it under a dedicated `temp/` folder — `vidfarm upload clip.mp4 --folder temp`, `vidfarm place … --folder temp`, `vidfarm approve … --folder temp` — so scratch assets stay quarantined in one place you can periodically purge, instead of cluttering your persistent My Files library or the temp-store root.
+**Pick the store by lifetime.** A throwaway intermediate (cloud render source, a `place` scratch asset) belongs in the 30-day `temp/` store: `vidfarm upload clip.mp4 --folder temp`, `vidfarm place … --folder temp` — quarantined in one place you can periodically purge. Anything you **approve/share is permanent**, so `vidfarm approve --video ./final.mp4` uploads to **durable My Files** by default (the share video would otherwise 404 after the temp store's 30-day deletion). Only add `vidfarm approve --temp` when you deliberately want a disposable 30-day preview.

package/.agents/skills/vidfarm-director/references/primitives.md

@@ -122,7 +122,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 HyperFrames render (via `hyperframes_lambda` on prod cloud render; free on a local serve box)
+- Billing: metered as a Vidfarm render (via `hyperframes_lambda` on prod cloud render; free on a local serve box)
 
 Payload fields:
 

package/.agents/skills/vidfarm-director/references/rest-api.md

@@ -72,7 +72,7 @@ Use environment variables or a secret manager for keys. Never paste secrets into
 - Follow `next_cursor`/cursor fields until exhausted when the user asks for all records; do not call the first page the full dataset.
 - Treat submission and generation routes as non-idempotent unless the route explicitly states otherwise. Check existing state before retrying.
 - Poll asynchronous jobs at the documented status endpoint and stop on terminal success or failure. Do not fabricate completion from an accepted response.
-- Upload local media through the documented presign/upload/finalize sequence. The devcli is recommended on desktop because it performs this sequence automatically.
+- Upload local media through the documented presign/upload/finalize sequence. The devcli is recommended on desktop because it performs this sequence automatically. **Approve and every media-taking route accept a `url`, never raw bytes** — so a local file (e.g. a locally rendered MP4) must first become a URL. Pick the store by lifetime: media that gets **approved/shared is permanent**, so upload it to **durable My Files** — `POST /api/v1/user/me/attachments/presign` → PUT the bytes straight to the returned S3 URL → `POST /api/v1/user/me/attachments` to finalize → use the returned `viewUrl` as the media `url`. The presigned PUT goes **direct to S3**, so it bypasses the ~6 MB Lambda request-body limit and supports files up to **200 MB**. Do **not** POST large files as multipart to `.../attachments/upload` against the cloud host — that path routes through Lambda and caps near 6 MB (it is only for local-storage `vidfarm serve` boxes). The parallel `.../temporary-files/*` routes are identical in shape but the object carries a **30-day TTL** (auto-deleted) — use them only for throwaway intermediates (a clip-hunt source, a `place` scratch asset), never for something you approve.
 - Parse and mutate composition HTML as a DOM. Never edit it by string concatenation.
 - Render through `POST /api/v1/compositions/:forkId/render`; do not call the underlying renderer directly.
 - Surface wallet/provider costs before expensive operations and preserve returned job IDs for audit and retries.

package/.agents/skills/vidfarm-media/SKILL.md

@@ -141,18 +141,33 @@ Same ownership rule, resolved through the file directory:
 
 ### Free media catalog — sources & keys
 
-Still no customer signup: the catalog runs on **keyless** sources and **platform-held** keys, never a per-user account.
+In **cost-mode `minimize`**, prefer these keyless sources before spending anything: **Openverse** (CC/CC0 music, SFX, images) and **iconify** (icons) need no account or key, so they always resolve at $0. Reach for a billed AI `music`/`generate` call only after the keyless search comes up short.
+
+Icons + CC images/audio are **keyless**. Pixabay (stock photos/vectors/video) is
+**BYOK** — each user saves their own free Pixabay key, exactly like their OpenAI /
+Gemini keys, through the same provider-key surface (Settings → Bring your own keys,
+`POST /api/v1/user/me/provider-keys` with `provider: "pixabay"`, or
+`vidfarm add-provider-key pixabay <key>`). It is a stock-media key, not an AI key —
+it never counts as a qualified AI provider and never touches editor chat.
 
 | Source | Serves | Key |
 | --- | --- | --- |
 | **iconify** | `icon` (SVG) | keyless — always on |
 | **openverse** | `image` (CC), `bgm`, `sfx` (CC/CC0 audio) | keyless — always on |
-| **pixabay** | `image`, `vector`, `video` (photos/illustrations/stock video) | needs a **platform** `PIXABAY_API_KEY` |
-
-**Recommend keys when a search comes up short.** If `image`/`vector`/`video`
-returns nothing (or `providers_used` omits `pixabay`), the platform's Pixabay key
-isn't set — tell the operator they can unlock stock photos/vectors/video with a
-**free** key from <https://pixabay.com/api/docs/> (set `PIXABAY_API_KEY` server-side;
-`OPENVERSE_API_TOKEN` is optional and only raises rate limits). Icons, CC images,
-and bgm/sfx keep working without any key. This is an operator/platform key — the
-end user still never signs up for anything.
+| **pixabay** | `image`, `vector`, `video` (photos/illustrations/stock video) | **BYOK** — the user's own free `pixabay` provider key |
+
+**Check for the key before assuming it's missing.** A short `image`/`vector`/`video`
+result (or `providers_used` omitting `pixabay`) usually means no Pixabay key — but it
+**may already be saved**. Look first: `vidfarm provider-keys`, or the web app's
+**Settings → Bring your own keys** (<https://vidfarm.cc/settings/developer>). If it's
+genuinely absent, the user grabs a **free** one at <https://pixabay.com/api/docs/> and
+saves it once, via any of three paths:
+- **devcli:** `vidfarm add-provider-key pixabay <key>`
+- **web app:** Settings → Bring your own keys → add a `pixabay` key
+- **desktop AI agent:** hand the agent the key and let it run the `add-provider-key` command
+
+It's a stock-media key, not an AI key — it never counts as a qualified AI provider and
+never touches editor chat, so it's exactly what cost-mode `minimize` wants for $0 asset
+sourcing. Icons, CC images, and bgm/sfx keep working without any key. (An operator may
+still set a platform `PIXABAY_API_KEY` server-side as a fallback for users who haven't
+saved their own, but the default posture is bring-your-own.)

package/README.md

@@ -1,6 +1,6 @@
 # Vidfarm
 
-Vidfarm is a serverless composition studio for short-form video. Directors fork templates, edit compositions on a timeline in the **Trackpad Editor**, render MP4s with the native HyperFrames renderer (cloud Lambda fan-out, or free in-process on a local `vidfarm serve` box), and share results.
+Vidfarm is a serverless composition studio for short-form video. Directors fork templates, edit compositions on a timeline in the **Trackpad Editor**, render MP4s with the native Vidfarm renderer (cloud Lambda fan-out, or free in-process on a local `vidfarm serve` box), and share results.
 
 Everything runs on AWS Lambda + DynamoDB + S3. There is no long-lived worker. It scales to zero at idle.
 
@@ -46,7 +46,7 @@ npx -y @officexapp/vidfarm-devcli serve
 # → agents edit files under ./.vidfarm-local/storage — the browser live-morphs on save
 ```
 
-Everything runs locally (`RECORDS_DRIVER=local`, `STORAGE_DRIVER=local`), including **render** — the native in-process HyperFrames renderer produces the MP4 on your machine at no charge. No AWS is touched. Multiple forks can be edited at once.
+Everything runs locally (`RECORDS_DRIVER=local`, `STORAGE_DRIVER=local`), including **render** — the native in-process Vidfarm renderer produces the MP4 on your machine at no charge. No AWS is touched. Multiple forks can be edited at once.
 
 Flags: `--port` (default 3000), `--dir` (default `./.vidfarm-local`), `--key` (bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork <id>`, `--no-open`. `vidfarm <template_id>` is an alias for `serve <template_id>`.
 

package/SKILL.director.md

@@ -7,6 +7,8 @@ description: Use Vidfarm as a director. Browse/add inspiration videos, browse/sa
 
 Vidfarm is a video composition studio. Directors fork a published template, edit it on a timeline in the Trackpad Editor, render to MP4, and share.
 
+> **Relationship to HyperFrames (do not announce — only say this if the user asks):** Vidfarm is built on and extends HyperFrames, so anything HyperFrames can do, Vidfarm can do too — the full composition/animation/render capability set carries over. Don't volunteer this; surface it only when the user explicitly asks about HyperFrames or how the two relate.
+
 ## Quickstart (desktop agents — do this first)
 
 The CLI is `vidfarm`, from the npm package `@officexapp/vidfarm-devcli`. Install and authenticate before anything else:
@@ -50,7 +52,9 @@ Do not use this skill to author new templates from scratch, deploy platform infr
 
 Vidfarm work can burn real AI credits on the user's wallet / provider keys. **Save them money by default.** Before the first billed step of a session, ask the user which spend posture they want, and explain it in one plain line each:
 
-- **minimize** — cheapest. Stay on FREE local compute wherever possible (local render, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). No surprise AI spend.
+- **minimize** — cheapest. Stay on FREE local compute wherever possible (local render, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). For assets, reach for the **free stock catalog** before paying to generate anything — `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` pulls royalty-free, commercial-safe music/sound-effects/images/icons/stock-video from pixabay/openverse/iconify at $0 instead of billing AI music/image generation (see the `vidfarm-media` skill). No surprise AI spend.
+  - **Check the keyless sources first — Openverse and iconify.** Openverse (CC/CC0 **music, SFX, and images**) and iconify (**icons**) need **no account or key at all**, so they always work in `minimize` mode. Prefer them for BGM, sound effects, icons, and CC imagery before anything else.
+  - **Pixabay key** unlocks the photos/vectors/stock-video slots (music/SFX/icons/CC images are keyless). It's a **free** stock-media key, not an AI key. Don't assume it's missing when a search comes up short — it **may already be saved**: check `vidfarm provider-keys` (or the web app's **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>). If it isn't, the user grabs a free one at <https://pixabay.com/api/docs/> and saves it once — `vidfarm add-provider-key pixabay <key>`, the Settings surface, or by handing the key to their desktop AI agent to run that command. After it's saved, cost-mode `minimize` sourcing works end-to-end at $0.
 - **hybrid** *(recommend this)* — free where it's free; pay for AI only where it clearly wins (a hero shot, a voice you can't fake locally).
 - **pure-ai** — best quality; use AI image/video/voice/music freely.
 
@@ -440,7 +444,7 @@ There is no single price for a video. The **approach** the director picks sets t
 
 | 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** — reference files straight off disk with `place --src ./file`, no upload — or a **web search**), and render **locally** via `vidfarm serve` (native in-process HyperFrames render — free and unguarded, no cloud). |
+| **Reuse + render locally** | **free** | Fork an already-decomposed template, swap captions / images / video with existing MP4s (from **My Files**, the director's **local computer** — reference files straight off disk with `place --src ./file`, no upload — or a **web search**), and render **locally** via `vidfarm serve` (native in-process Vidfarm 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. |
@@ -773,6 +777,19 @@ Two surfaces:
 - **Editor web/serve copilot** — `editor_action` `action_type=set_layer_media` with `object_fit` and `object_position` (both also seedable on `add_layer`/`generate_layer`). `editor_context.layers[]` reports each clip's current `object_fit`/`object_position` so you can read before re-cropping.
 - **Desktop agents (devcli)** — `vidfarm place ./work --src <url> --object-fit cover --object-position "25% 50%"` (also on `--replace <layer_key>`).
 
+### The opening frame is the post's thumbnail
+
+**The composition's first frame (t=0) is the still that represents the whole video before anyone presses play** — it's the poster on the approved-post share page, the `/discover` card, the autoplay-off feed preview, and the file/scrubber thumbnail. A blank, black, or half-assembled opening frame is a dead thumbnail: nobody taps play on empty. Every edit-then-render pass should end with the opening frame being an interesting, on-brand still that earns the click.
+
+The trap is mechanical: a scene whose layers animate in from `opacity:0` / offset / blur is **empty at t=0**, because the render is seek-safe and shows exactly the DOM state at time 0. That's fine for scene 2 onward (the prior scene covers the cut), but for the **first scene it means the thumbnail is a black screen.** Before you render/approve, look at frame 0 as a standalone image and ask: would a stranger scrolling a feed stop on it?
+
+Fix it in the editor when frame 0 is empty or dull:
+- Make the opening scene's key layers **already visible at t=0** (a legible hero title, a visible subject/clip, a composed background) and animate *within* the frame — use `set_layer_keyframes` starting from `offset:0, opacity:1` (drift/parallax/scale) rather than fading the whole scene up from black; or `nudge_layers`/`trim_layer` so the hero layer starts at 0 while secondary elements enter after.
+- If the opening clip is a video that starts on a dark/blank frame, `trim_layer edge=start` to move its in-point onto a stronger frame, or re-cover it full-canvas.
+- Preview the poster deterministically: seek the editor timeline to 0, or capture just frame 0 of a local composition with `vidfarm hf snapshot --at 0` (HyperFrames-CLI passthrough; seconds, not a full render), and judge that image on its own.
+
+This is the vidfarm-workflow reminder; the composition-authoring craft (poster-state design, front-loading the hook) lives in `hyperframes-creative/references/beat-direction.md` → "The opening frame is the poster". Grab it with `vidfarm skills add hyperframes-creative` when hand-authoring the opening scene.
+
 ### Ken Burns — animate still images (slow pan/zoom)
 
 Still images can carry a **Ken Burns effect**: a slow pan or zoom that runs across the clip's full duration, in the editor preview and both render paths identically. This is what makes a slideshow of stills feel like motion footage. It is a first-class layer property — the image layer's `<img>` gets `data-kenburns="<preset>"`; there is no separate keyframe authoring.
@@ -844,9 +861,9 @@ Beyond the Ken Burns / transition / animated-caption presets, the copilot can ha
   vidfarm render <forkId>            # local, $0.00
   ```
   If you ran `serve --port <N>`, pass `--base-url http://localhost:<N>` so the reference URL points at the right origin. A localhost `/storage` URL only resolves against the serve box that holds the file, so these compositions render/preview **locally**; to render in the cloud or share them, upload the media instead (below).
-- **Anywhere else (e.g. a `vidfarm pull` dir headed for cloud render/publish)** — the cloud renderer can't reach your disk, so a local `--src` file is **uploaded to the ephemeral temp store** first, namescoped under a throwaway `temp/` folder by default (override with `--folder`). Use this when the output must be a durable, shareable URL.
+- **Anywhere else (e.g. a `vidfarm pull` dir headed for cloud render/publish)** — the cloud renderer can't reach your disk, so a local `--src` file is **uploaded to the ephemeral temp store** first, namescoped under a throwaway `temp/` folder by default (override with `--folder`). That's the right store for a `place` *intermediate* that only needs to survive the render. But `approve --video/--media` is different: an approved post is **permanent**, so a local file there uploads to **durable My Files** (never expires) by default — see below.
 
-**`/temp` folder convention.** When you *do* need to upload throwaway media to Vidfarm (cloud render, `approve`, one-off URLs), keep it under a dedicated `temp/` folder — `vidfarm upload clip.mp4 --folder temp`, `vidfarm place … --folder temp`, `vidfarm approve … --folder temp` — so scratch assets stay quarantined in one place you can periodically purge, instead of cluttering your persistent My Files library or the temp-store root.
+**Pick the store by lifetime.** A throwaway intermediate (cloud render source, a `place` scratch asset) belongs in the 30-day `temp/` store: `vidfarm upload clip.mp4 --folder temp`, `vidfarm place … --folder temp` — quarantined in one place you can periodically purge. Anything you **approve/share is permanent**, so `vidfarm approve --video ./final.mp4` uploads to **durable My Files** by default (the share video would otherwise 404 after the temp store's 30-day deletion). Only add `vidfarm approve --temp` when you deliberately want a disposable 30-day preview.
 
 ## Raws (long-form → short-form raws)
 
@@ -1116,7 +1133,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm visibility <forkId> <private\|public>` | `PATCH .../compositions/:forkId/visibility` | set visibility |
 | `vidfarm clone <forkId>` | `POST .../compositions/:forkId/clone` | clone a fork |
 | `vidfarm share-link <forkId>` | `POST .../compositions/:forkId/share-links` | mint a share URL |
-| `vidfarm approve --video <url\|file> --caption "…"` | `POST /api/v1/approved/posts` | approve post (local `--video`/`--media` auto-upload to `temp/`; prints `share_url`) |
+| `vidfarm approve --video <url\|file> --caption "…"` | `POST /api/v1/approved/posts` | approve post — takes media by **`url`**. Local `--video`/`--media` auto-upload to **durable My Files** via presign→S3→finalize (up to **200 MB**, bypasses the ~6 MB Lambda limit) then approve with that URL, so the share video **never expires**; also accepts a `/files…` path. `--temp` opts into the 30-day temp store (throwaway preview only). Prints `share_url` |
 | `vidfarm posts` / `vidfarm post <id>` | `GET /api/v1/approved/posts[/:id]` | browse approved posts |
 | `vidfarm schedule <postId> --at <iso> --to <dest>` | `POST /api/v1/approved/posts/:postId/schedules` | schedule a post |
 | `vidfarm schedules <postId>` | `GET /api/v1/approved/posts/:postId/schedules` | browse scheduled posts |
@@ -1125,7 +1142,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm cost-mode [minimize\|hybrid\|pure-ai]` | (local `~/.vidfarm/cost-mode.json`) | show/set the money-saving preference every billed command respects; no arg = show + explain the three; `--clear` forgets it |
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only, paid plan. Aliases: `spend`, `costs` |
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
-| `vidfarm upload <file> [--folder <path>]` | `POST /api/v1/user/me/temporary-files/upload` | upload → durable URL (ephemeral; prefer `--folder temp` for scratch) |
+| `vidfarm upload <file> [--folder <path>]` | presign → S3 PUT → finalize (`.../temporary-files/presign` + `.../temporary-files`) | upload → durable URL (ephemeral, 30-day TTL; prefer `--folder temp` for scratch). Goes direct to S3, so large files (up to **200 MB**) bypass the ~6 MB Lambda body limit |
 | `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
 | `vidfarm download-post <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | download a social/media post into a durable MP4 or slideshow |
 | `vidfarm download-post-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download a social/media post's audio into a durable audio file |
@@ -1150,13 +1167,15 @@ If a local AI script rewrites text or scenes without consuming those files first
 
 **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/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.
+**Uploads/downloads/My-Files writes live in the devcli** because they are genuine multi-step / streaming flows: `upload` presigns the **ephemeral** temporary-files route, PUTs the bytes **direct to S3**, finalizes, and prints the durable URL to drop into a composition or approved post — going direct to S3 means large files (up to **200 MB**) never hit the ~6 MB Lambda request-body limit; `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.
+
+**Approving a locally rendered MP4 (the URL-first rule + the durability rule).** The approve route (`POST /api/v1/approved/posts`) and every media-taking route accept a `url`, never raw file bytes — so you never "upload to approve" in one shot. An approved post is a **permanent** share page, so the media must live in **durable My Files**, not the 30-day temp store (a temp-hosted video would 404 the share page after 30 days). The correct sequence for a big local file is: (1) `POST /api/v1/user/me/attachments/presign` with `{ file_name, content_type, size_bytes }` → (2) PUT the raw bytes to the returned presigned S3 URL → (3) `POST /api/v1/user/me/attachments` (finalize) → use the returned durable `viewUrl` as the approve media `url`. `vidfarm approve --video ./final.mp4` does all of this automatically (durable by default; up to **200 MB**). Never POST a large file as multipart to `.../attachments/upload` against the cloud host: that path proxies through Lambda and caps near 6 MB (it exists only as a fallback for local-storage `vidfarm serve` boxes). Only use the temp-store route (`.../temporary-files/*`, or `vidfarm approve --temp`) for a **throwaway** preview you don't mind losing in 30 days.
 
 ## Cost mode — the devcli's money-saving guardrail
 
-`vidfarm cost-mode <minimize|hybrid|pure-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, all the file-editing verbs).
+`vidfarm cost-mode <minimize|hybrid|pure-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates.
 
-- **minimize** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative. Use this to guarantee no surprise AI spend.
+- **minimize** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command.
 - **hybrid** *(default recommendation)* — billed ops run but print a one-line cost notice each.
 - **pure-ai** — billed ops run without gating; cost is still printed.
 
@@ -1177,7 +1196,7 @@ npx -y @officexapp/vidfarm-devcli serve <template_id>
 
 The **editor and its data** run locally (`RECORDS_DRIVER=local`, `STORAGE_DRIVER=local`) and rendering happens **in-process on this box for free**. Everything catalog-shaped still mirrors the cloud host ("cloud passthrough"): `/discover`, `/api/v1/videos`, and `/library` list the **cloud** catalog and the cloud account's approved posts next to anything local, opening a cloud template **seeds** its composition onto disk on demand, Add Template ingests into the cloud account, and approved-post actions (schedules, archive, delete) on cloud posts proxy through. Media a seeded composition already references stays on its cloud URLs — but you can also drop your **own local files** onto the timeline without any upload: `vidfarm place --src ./clip.mp4` copies the file into this box's disk store and references it by a `localhost/storage` URL (see "Local file paths as media" above), so the free in-process renderer plays it back with zero S3 involvement. Pass `--no-cloud` for a fully-offline box.
 
-**Rendering from a serve box** — the editor's **Render** button becomes a popover with two options when a cloud `--api-key` is configured: **Render Local (Free)** (in-process HyperFrames render, no charge) and **Render in Cloud** (hands the render to the cloud renderer, billed to the cloud account's wallet). Over REST, pass `render_target: "cloud"` in the `POST /render` body; the local box resolves (or clones, once) a publishable cloud fork, remembers the mapping in the fork's `upstream-link.json`, and `GET /renders/:renderId` transparently proxies the cloud job status.
+**Rendering from a serve box** — the editor's **Render** button becomes a popover with two options when a cloud `--api-key` is configured: **Render Local (Free)** (in-process Vidfarm render, no charge) and **Render in Cloud** (hands the render to the cloud renderer, billed to the cloud account's wallet). Over REST, pass `render_target: "cloud"` in the `POST /render` body; the local box resolves (or clones, once) a publishable cloud fork, remembers the mapping in the fork's `upstream-link.json`, and `GET /renders/:renderId` transparently proxies the cloud job status.
 
 How the loop works:
 - The composition lives on disk at `<data-dir>/storage/compositions/forks/<forkId>/working/composition.html` (default `<data-dir>` is `./.vidfarm-local`). Point your agent at that file.
@@ -1396,7 +1415,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 HyperFrames render (via `hyperframes_lambda` on prod cloud render; free on a local serve box)
+- Billing: metered as a Vidfarm render (via `hyperframes_lambda` on prod cloud render; free on a local serve box)
 
 Payload fields:
 
@@ -1625,7 +1644,9 @@ Use this when a coding agent is doing the work locally or the user wants a repro
 4. Make deterministic edits to `composition.html` and optionally `composition.json`.
 5. Validate with `vidfarm lint` or `vidfarm stills` when useful.
 6. Render with `vidfarm render <forkId> --dir ./work --wait`.
-7. Approve the finished MP4 with `vidfarm approve --video <url> --caption "..."`.
+7. Approve the finished MP4 with `vidfarm approve --video <url|./final.mp4> --caption "..."`. This prints the shareable `share_url`.
+
+**Approving a locally rendered file → cloud preview link.** Approve takes media by **URL**, not bytes, and an approved post is **permanent** — so the local MP4 must land in **durable My Files**, not the 30-day temp store (a temp video would 404 the share page after 30 days). The devcli presigns, PUTs the bytes **direct to S3**, finalizes, then approves with that durable URL — so `vidfarm approve --video ./final.mp4` handles files up to **200 MB**, bypasses the ~6 MB Lambda request-body limit, and the share link never breaks. By raw REST: `POST /api/v1/user/me/attachments/presign` → PUT to the returned S3 URL → `POST /api/v1/user/me/attachments` (finalize) → pass the returned `viewUrl` in the approve `media` array. Do not multipart-POST a big file to `.../attachments/upload` against the cloud host (Lambda-bound, ~6 MB cap). Add `vidfarm approve --temp` only when you want a disposable 30-day preview.
 
 Prefer this path for batch work, CI-like edits, or when the user wants free local rendering through `vidfarm serve`.
 

package/dist/src/cli.js

@@ -504,12 +504,19 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
 
 Approve & schedule (publish a finished MP4 as a shareable post):
   approve                   Approve media into a preview/share page      → POST /api/v1/approved/posts
-    --video <url|file>      Primary MP4 (URL, or a local file auto-uploaded to temp/)
-    --media <url|file>      Extra media (repeatable; local files auto-upload to temp/)
-    --folder <path>         Temp-store folder for uploaded local files (default: temp)
+    --video <url|file>      Primary MP4 (URL, /files path, or local file → durable My Files)
+    --media <url|file>      Extra media (repeatable; local files → durable My Files)
+    --folder <path>         Destination subfolder for uploaded local files (default: approved)
+    --temp                  Upload local files to the 30-day TEMP store instead of
+                            durable My Files (throwaway preview; share video dies at day 30)
     --caption <text>        Post caption (required)
-                            Direct local-file upload is supported here:
+                            An approved post is PERMANENT, so a local file uploads
+                            to DURABLE My Files (never expires) by default —
+                            presigned + PUT straight to S3 + finalized (up to
+                            200 MB, bypassing the ~6 MB Lambda body). A locally
+                            rendered MP4 gets a share link that never breaks:
                             'vidfarm approve --video ./final.mp4 --caption "..."'
+                            (add --temp only for a disposable 30-day preview.)
   posts                     List your approved posts                     → GET  /api/v1/approved/posts
   post <postId>             Read one approved post (prints share URL)    → GET  /api/v1/approved/posts/:postId
   schedule <postId>         Schedule an approved post to a channel       → POST /api/v1/approved/posts/:postId/schedules
@@ -532,10 +539,12 @@ Agent skill (install the latest director skill so your AI agent can act):
                             (copy/share artifact; not the canonical install)
 
 Files (multi-step flows the devcli handles for you):
-  upload <file>             Upload to the EPHEMERAL temp store, print URL → POST /api/v1/user/me/temporary-files/upload
+  upload <file>             Upload to the EPHEMERAL temp store, print URL → presign + S3 PUT + finalize
     --folder <path>         Namescope the upload under a folder. Prefer a
                             throwaway 'temp' folder (--folder temp) for scratch
                             media so it never clutters your durable library.
+                            Bytes go direct to S3, so large files (up to 200 MB)
+                            skip the ~6 MB Lambda request-body limit.
   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)
@@ -601,7 +610,11 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
   Local file paths: to avoid uploading assets to Vidfarm S3 at all, reference
   them straight from disk with 'place --src ./clip.mp4' on a 'serve' box (copied
   to that box's local disk store, free local render). When you DO need a durable
-  URL (cloud render/approve), keep it under a throwaway 'temp/' folder.
+  URL, mind the store: a 'place'/edit intermediate can live in the throwaway
+  'temp/' folder (30-day TTL), but anything you APPROVE is permanent — 'approve'
+  uploads local files to DURABLE My Files by default so the share link never dies
+  (the 'temp/' store would delete the video after 30 days; use --temp only for a
+  disposable preview).
 
 Cost spectrum (default to the cheapest approach that works; see SKILL.director.md):
   free        Reuse a decomposed template, swap captions/images/existing MP4s
@@ -1546,7 +1559,7 @@ function printServeBanner(input) {
     console.log(line);
     console.log(`  server      ${input.base}`);
     console.log(`  data dir    ${input.dataDir}`);
-    console.log(`  render      ${DIM}local (in-process HyperFrames render — free, no cloud charge)${RESET}`);
+    console.log(`  render      ${DIM}local (in-process Vidfarm render — free, no cloud charge)${RESET}`);
     if (input.login) {
         console.log(`  login       ${GREEN}${input.login.email}${RESET} ${input.login.isPaidPlan ? DIM + "(paid)" + RESET : DIM + "(free)" + RESET}`);
     }
@@ -2819,7 +2832,8 @@ async function runCreateCommand(argv) {
     guardBilled(ctx, {
         label: "create (AI base-VIDEO generation + decompose)",
         estimate: "expensive, ~$1+ (AI video)",
-        freeAlternative: "fork a template and paint scenes with raw clips + HTML hyperframes instead of AI video"
+        freeAlternative: "fork a template and paint scenes with raw clips + HTML hyperframes, or drop in free stock via " +
+            'vidfarm media search "<meaning>" --type video|image (Pixabay/Openverse, $0) instead of AI video'
     });
     const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
     // 1. Generate the base video from the prompt.
@@ -3135,7 +3149,7 @@ async function runRenderCommand(argv) {
                 console.log(`${DIM}Media prep: ${prepCuts.map((n) => `${n.action} ×${n.refs} (${n.url.slice(0, 60)}…)`).join("; ")}${RESET}`);
             }
             console.log(`${GREEN}Rendered locally in ${(result.durationMs / 1000).toFixed(1)}s → ${result.outputPath}${RESET}`);
-            console.log(`${DIM}$0.00 — local render, no cloud charge.${RESET}`);
+            console.log(`${DIM}$0.00 — local Vidfarm render, no cloud charge.${RESET}`);
         }
         return;
     }
@@ -3412,11 +3426,65 @@ function serveStorageUrl(baseUrl, key) {
 }
 // Upload a local file to the EPHEMERAL temp store on ctx.host, optionally
 // namescoped under a folder, and return its durable URL.
+//
+// Prefers the presign → PUT-to-S3 → finalize path so the bytes never traverse
+// the Lambda request body (which caps at ~6 MB). This is what lets a locally
+// rendered MP4 (up to 200 MB) be uploaded to the cloud for approval + a
+// shareable preview link. Falls back to the multipart POST when the box runs on
+// local storage (presign transport === "server"), where there is no S3.
 async function uploadLocalToTempStore(ctx, absPath, folder) {
     if (!existsSync(absPath))
         throw new Error(`No such local file: ${absPath}`);
+    const buffer = readFileSync(absPath);
+    const fileName = path.basename(absPath);
+    const contentType = guessContentType(fileName);
+    // Step 1: presign. On an S3-backed box this returns a direct PUT URL.
+    const presign = await fetch(new URL("/api/v1/user/me/temporary-files/presign", ctx.host), {
+        method: "POST",
+        headers: { ...buildAuthHeaders(ctx.auth), "content-type": "application/json" },
+        body: JSON.stringify({ file_name: fileName, content_type: contentType, size_bytes: buffer.byteLength, folder_path: folder })
+    });
+    const presignJson = await presign.json().catch(() => null);
+    if (presign.ok && presignJson?.transport === "presigned" && presignJson?.upload?.url) {
+        // Step 2a: PUT the bytes straight to S3 (bypasses the Lambda body limit).
+        const put = await fetch(presignJson.upload.url, {
+            method: presignJson.upload.method || "PUT",
+            headers: presignJson.upload.headers || {},
+            body: new Uint8Array(buffer)
+        });
+        if (!put.ok)
+            throw new Error(`local media upload failed with HTTP ${put.status}.`);
+        // Step 3: finalize — record the temp file now that the bytes have landed.
+        const finalize = await fetch(new URL("/api/v1/user/me/temporary-files", ctx.host), {
+            method: "POST",
+            headers: { ...buildAuthHeaders(ctx.auth), "content-type": "application/json" },
+            body: JSON.stringify({
+                file_id: presignJson.file_id,
+                file_name: presignJson.file_name || fileName,
+                content_type: presignJson.content_type || contentType,
+                size_bytes: buffer.byteLength,
+                storage_key: presignJson.storage_key,
+                folder_path: presignJson.folder_path
+            })
+        });
+        const finalizeText = await finalize.text();
+        let finalizeJson = null;
+        try {
+            finalizeJson = finalizeText ? JSON.parse(finalizeText) : null;
+        }
+        catch {
+            finalizeJson = null;
+        }
+        if (!finalize.ok)
+            throw new Error(`local media upload finalize failed (${finalize.status}): ${finalizeText.slice(0, 200)}`);
+        const url = readUploadedFileUrl(finalizeJson) ?? presignJson.view_url ?? presignJson.s3_url ?? null;
+        if (!url)
+            throw new Error("local media upload returned no durable URL.");
+        return url;
+    }
+    // Step 2b (fallback): local-storage box — POST the bytes as multipart form.
     const form = new FormData();
-    form.append("file", new Blob([readFileSync(absPath)]), path.basename(absPath));
+    form.append("file", new Blob([buffer], { type: contentType }), fileName);
     if (folder)
         form.append("folder_path", folder);
     const res = await fetch(new URL("/api/v1/user/me/temporary-files/upload", ctx.host), { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
@@ -3435,6 +3503,92 @@ async function uploadLocalToTempStore(ctx, absPath, folder) {
         throw new Error("local media upload returned no durable URL.");
     return url;
 }
+// Pull the durable view URL out of an /me/attachments finalize (or presign)
+// response. Finalize returns { attachment: { viewUrl } }; presign returns a
+// top-level view_url before the bytes land.
+function readAttachmentUrl(json) {
+    const a = json?.attachment ?? {};
+    return a.viewUrl ?? a.view_url ?? a.publicUrl ?? a.public_url ?? json?.view_url ?? json?.s3_url ?? null;
+}
+// Upload a local file to DURABLE My Files (root `files`, via /me/attachments),
+// optionally namescoped under a folder, and return its permanent URL.
+//
+// This is the durable twin of uploadLocalToTempStore: same presign → PUT-to-S3
+// → finalize shape (so a big MP4 never traverses the ~6 MB Lambda body), but the
+// object is NOT temp-tagged, so it never hits the 30-day lifecycle deletion.
+// Use it for anything that must outlive 30 days — chiefly a locally rendered MP4
+// being approved into a shareable cloud post.
+async function uploadLocalToMyFiles(ctx, absPath, folder) {
+    if (!existsSync(absPath))
+        throw new Error(`No such local file: ${absPath}`);
+    const buffer = readFileSync(absPath);
+    const fileName = path.basename(absPath);
+    const contentType = guessContentType(fileName);
+    // Step 1: presign. On an S3-backed box this returns a direct PUT URL.
+    const presign = await fetch(new URL("/api/v1/user/me/attachments/presign", ctx.host), {
+        method: "POST",
+        headers: { ...buildAuthHeaders(ctx.auth), "content-type": "application/json" },
+        body: JSON.stringify({ file_name: fileName, content_type: contentType, size_bytes: buffer.byteLength, folder_path: folder })
+    });
+    const presignJson = await presign.json().catch(() => null);
+    if (presign.ok && presignJson?.transport === "presigned" && presignJson?.upload?.url) {
+        // Step 2a: PUT the bytes straight to S3 (bypasses the Lambda body limit).
+        const put = await fetch(presignJson.upload.url, {
+            method: presignJson.upload.method || "PUT",
+            headers: presignJson.upload.headers || {},
+            body: new Uint8Array(buffer)
+        });
+        if (!put.ok)
+            throw new Error(`My Files upload failed with HTTP ${put.status}.`);
+        // Step 3: finalize — record the durable attachment now that the bytes landed.
+        const finalize = await fetch(new URL("/api/v1/user/me/attachments", ctx.host), {
+            method: "POST",
+            headers: { ...buildAuthHeaders(ctx.auth), "content-type": "application/json" },
+            body: JSON.stringify({
+                attachment_id: presignJson.attachment_id,
+                file_name: presignJson.file_name || fileName,
+                content_type: presignJson.content_type || contentType,
+                size_bytes: buffer.byteLength,
+                storage_key: presignJson.storage_key,
+                folder_path: presignJson.folder_path
+            })
+        });
+        const finalizeText = await finalize.text();
+        let finalizeJson = null;
+        try {
+            finalizeJson = finalizeText ? JSON.parse(finalizeText) : null;
+        }
+        catch {
+            finalizeJson = null;
+        }
+        if (!finalize.ok)
+            throw new Error(`My Files upload finalize failed (${finalize.status}): ${finalizeText.slice(0, 200)}`);
+        const url = readAttachmentUrl(finalizeJson) ?? presignJson.view_url ?? null;
+        if (!url)
+            throw new Error("My Files upload returned no durable URL.");
+        return url;
+    }
+    // Step 2b (fallback): local-storage box — POST the bytes as multipart form.
+    const form = new FormData();
+    form.append("file", new Blob([buffer], { type: contentType }), fileName);
+    if (folder)
+        form.append("folder_path", 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;
+    }
+    if (!res.ok)
+        throw new Error(`My Files upload failed (${res.status}): ${text.slice(0, 200)}`);
+    const url = readAttachmentUrl(json);
+    if (!url)
+        throw new Error("My Files upload returned no durable URL.");
+    return url;
+}
 // A value like "/raws/demos/hero.mp4" or "/files/logos/logo.png" is a My Files
 // directory path (one of the five unified roots), NOT a URL or a local disk
 // path — resolve it through the directory API. (Prefixes are inlined, not a
@@ -3573,9 +3727,17 @@ async function runGenerateCommand(argv) {
         ? {
             label: "AI video generation",
             estimate: "expensive, ~$1+",
-            freeAlternative: "reuse a raw clip (vidfarm raws) or author the beat as an HTML hyperframe"
-        }
-        : { label: "AI image generation", estimate: "cheap, ~$0.01–$0.05" });
+            freeAlternative: 'free stock video — vidfarm media search "<meaning>" --type video (Pixabay, $0; needs a free ' +
+                "pixabay key — it may already be saved: check vidfarm provider-keys), reuse a raw clip (vidfarm " +
+                "raws), or author the beat as an HTML hyperframe"
+        }
+        : {
+            label: "AI image generation",
+            estimate: "cheap, ~$0.01–$0.05",
+            freeAlternative: 'free stock image/vector — vidfarm media search "<meaning>" --type image|vector ($0). ' +
+                "Openverse (CC images) is keyless and always on — check it first; a free Pixabay key adds " +
+                "photos/vectors and may already be saved (check vidfarm provider-keys)"
+        });
     const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
     const payload = { prompt };
     if (parsed.values["aspect-ratio"])
@@ -4457,7 +4619,8 @@ async function runMusicCommand(argv) {
     guardBilled(ctx, {
         label: `AI music generation${parsed.values["own-key"] ? " (your ElevenLabs key)" : ""}`,
         estimate: "billed (ElevenLabs)",
-        freeAlternative: "reuse a track from My Files / your library, or a licensed BGM asset"
+        freeAlternative: 'free stock music/SFX — vidfarm media search "<meaning>" --type bgm|sfx (Openverse CC/CC0, $0, ' +
+            "no key needed), or reuse a track from My Files / your library"
     });
     let musicLengthMs;
     const lengthMs = parsed.values["length-ms"]?.trim();
@@ -4599,7 +4762,7 @@ async function runMediaCommand(argv) {
     if (!items.length) {
         console.log(`${DIM}No results. Try a broader query, another --type, or a specific --provider (pixabay|openverse|iconify).${RESET}`);
         if (type === "image" || type === "vector" || type === "video") {
-            console.log(`${DIM}(photos/vectors/video need the platform PIXABAY_API_KEY set server-side; openverse covers CC images keyless.)${RESET}`);
+            console.log(`${DIM}(photos/vectors/video need YOUR OWN free Pixabay key — get one at https://pixabay.com/api/docs/ then save it: 'vidfarm add-provider-key pixabay <key>'. openverse covers CC images keyless.)${RESET}`);
         }
         return;
     }
@@ -5559,6 +5722,7 @@ async function runApproveCommand(argv) {
             title: { type: "string" },
             pinned: { type: "string" },
             folder: { type: "string" },
+            temp: { type: "boolean" },
             tracer: { type: "string" }
         }
     });
@@ -5566,15 +5730,29 @@ async function runApproveCommand(argv) {
     const caption = parsed.values.caption;
     if (!caption)
         throw new Error("approve requires --caption <text>.");
-    // An approved post is a shareable cloud page, so any media must be a durable
-    // URL the page can load. Pass an http(s) URL through; a local file is uploaded
-    // to the ephemeral temp store (default folder `temp/`) first.
-    const uploadFolder = parsed.values.folder ?? "temp";
+    // An approved post is a PERMANENT shareable cloud page, so its media must live
+    // as long as the page. A local file therefore uploads to DURABLE My Files by
+    // default (never expires). `--temp` opts into the 30-day temp store for a
+    // throwaway preview — the share video then stops loading after 30 days.
+    const useTemp = Boolean(parsed.values.temp);
+    const uploadFolder = parsed.values.folder ?? (useTemp ? "temp" : "approved");
     const resolveApproveMedia = async (value) => {
-        if (/^https?:\/\//i.test(value.trim()))
-            return value.trim();
-        const abs = path.resolve(process.cwd(), value.trim());
-        return uploadLocalToTempStore(ctx, abs, uploadFolder);
+        const v = value.trim();
+        if (/^https?:\/\//i.test(v))
+            return v;
+        // A My Files path (/files/… · /raws/… · /projects/… · /approved/… · /temp/…)
+        // already lives server-side — resolve it to its view URL instead of
+        // re-uploading. (A /temp/… path stays 30-day; the caller chose it.)
+        if (looksLikeMyFilesPath(v)) {
+            const resolved = await resolveMyFilesPathToUrl(ctx, v);
+            if (!resolved)
+                throw new Error(`approve media "${value}" looks like a My Files path but no file was found there. Browse it with \`vidfarm directory ls ${v.replace(/\/[^/]*$/, "") || "/"}\` (add --cloud if it lives on vidfarm.cc), or pass the file's view URL.`);
+            return resolved.url;
+        }
+        const abs = path.resolve(process.cwd(), v);
+        return useTemp
+            ? uploadLocalToTempStore(ctx, abs, uploadFolder)
+            : uploadLocalToMyFiles(ctx, abs, uploadFolder);
     };
     const media = [];
     if (parsed.values.video)
@@ -5868,7 +6046,7 @@ async function runAddProviderKeyCommand(argv) {
     const provider = parsed.positionals[0];
     const secret = parsed.positionals[1];
     if (!provider || !secret)
-        throw new Error("add-provider-key requires <provider> <secret> (provider: openai|gemini|openrouter|perplexity|nvidia|elevenlabs).");
+        throw new Error("add-provider-key requires <provider> <secret> (provider: openai|gemini|openrouter|perplexity|nvidia|elevenlabs|pixabay).");
     const ctx = commonContext(parsed.values);
     const result = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/user/me/provider-keys", auth: ctx.auth, body: { provider, secret, label: parsed.values.label } });
     assertApiOk(result, "add-provider-key");

package/dist/src/devcli/cost-mode.js

@@ -87,8 +87,12 @@ export function resolveCostMode(values) {
 }
 export const COST_MODE_BLURB = {
     minimize: "Minimize costs — stay on FREE local compute wherever possible (local render, " +
-        "local TTS/STT, local greenscreen/matting, reused clips + HTML motion). Billed " +
-        "cloud/AI generation is refused unless you re-confirm it (--yes).",
+        "local TTS/STT, local greenscreen/matting, reused clips + HTML motion). For assets, " +
+        'reach for the free stock catalog first — vidfarm media search "<meaning>" --type ' +
+        "bgm|sfx|image|vector|icon|video. Check the KEYLESS sources first: Openverse (CC/CC0 " +
+        "music, SFX, images) and iconify (icons) need no account at all. A free Pixabay key adds " +
+        "photos/vectors/stock-video and may already be saved (check vidfarm provider-keys). " +
+        "Billed cloud/AI generation is refused unless you re-confirm it (--yes).",
     hybrid: "Hybrid (recommended) — free where it's free, spend AI credits only where they " +
         "clearly win (a hero shot, a voice you can't fake locally). Billed ops run but " +
         "each prints its cost so nothing is a surprise.",
@@ -104,9 +108,14 @@ export function costModeSummaryLine(resolved) {
 export function costModeExplainer() {
     return [
         "How much do you want Vidfarm to spend on AI credits?",
-        "  • minimize — cheapest: free local compute, no surprise AI spend.",
+        "  • minimize — cheapest: free local compute + free stock media, no surprise AI spend.",
         "  • hybrid   — recommended: free where free, pay AI only where it clearly wins.",
-        "  • pure-ai  — best quality: use AI image/video/voice/music freely."
+        "  • pure-ai  — best quality: use AI image/video/voice/music freely.",
+        "Tip: before paying to generate music/SFX/images/video, try the free stock catalog —",
+        '  vidfarm media search "<meaning>" --type bgm|sfx|image|vector|icon|video.',
+        "  Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons)",
+        "  need no account. A free Pixabay key adds photos/vectors/stock-video (it may already be saved —",
+        "  check `vidfarm provider-keys` or vidfarm.cc/settings/developer; add via `vidfarm add-provider-key pixabay <key>`)."
     ].join("\n");
 }
 export class CostModeBlockedError extends Error {

package/dist/src/devcli/local-frontend-server.js

@@ -420,7 +420,7 @@ function localRenderStatusJson(renderId, record) {
         title: record.title,
         status: record.status,
         progress,
-        cost: "$0.00 (local render)",
+        cost: "$0.00 (local Vidfarm render)",
         outputUrl: record.status === "SUCCEEDED" ? `/local-renders/${encodeURIComponent(renderId)}.mp4` : undefined,
         error: record.error,
         fatalErrorEncountered: record.status === "FAILED" ? true : undefined

package/package.json

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

package/public/serve-shells/editor.html

@@ -1266,12 +1266,25 @@ html,body{margin:0;background:#050604;color:#fffbe6}
   // Desktop-agents nudge banner: a full-width alert pinned to the top of the
   // /editor and /chat surfaces pointing to the setup guide. Both surfaces embed
   // this chrome script, so gate strictly by pathname. Dismissible per session.
+  // The nudge is aimed at the DIRECTOR (the paid operator who drives Vidfarm with
+  // a desktop AI agent). A client reviewing a shared video in the editor should
+  // NOT be told to go install Claude Code / Codex — so on the editor we suppress
+  // it for free-tier (client / reviewer) sessions, read from the editor boot JSON.
   (function mountDesktopAgentsBanner() {
     try {
       var path = location.pathname;
       var onEditor = path === '/editor' || path.indexOf('/editor/') === 0;
       var onChat = path === '/chat' || path.indexOf('/chat/') === 0;
       if (!onEditor && !onChat) return;
+      if (onEditor) {
+        var bootEl = document.getElementById('hf-boot');
+        if (bootEl) {
+          try {
+            var boot = JSON.parse(bootEl.textContent || '{}');
+            if (boot && boot.freeTier) return;
+          } catch (e) {}
+        }
+      }
       if (document.querySelector('.vf-topbanner')) return;
       if (sessionStorage.getItem('vf-topbanner-dismissed') === '1') return;
       var GUIDE = '/blog/desktop-ai-agents';

package/public/serve-shells/library-files.html

@@ -1575,12 +1575,25 @@ button.rk-clips-thumb{appearance:none;-webkit-appearance:none;border:0;margin:0;
   // Desktop-agents nudge banner: a full-width alert pinned to the top of the
   // /editor and /chat surfaces pointing to the setup guide. Both surfaces embed
   // this chrome script, so gate strictly by pathname. Dismissible per session.
+  // The nudge is aimed at the DIRECTOR (the paid operator who drives Vidfarm with
+  // a desktop AI agent). A client reviewing a shared video in the editor should
+  // NOT be told to go install Claude Code / Codex — so on the editor we suppress
+  // it for free-tier (client / reviewer) sessions, read from the editor boot JSON.
   (function mountDesktopAgentsBanner() {
     try {
       var path = location.pathname;
       var onEditor = path === '/editor' || path.indexOf('/editor/') === 0;
       var onChat = path === '/chat' || path.indexOf('/chat/') === 0;
       if (!onEditor && !onChat) return;
+      if (onEditor) {
+        var bootEl = document.getElementById('hf-boot');
+        if (bootEl) {
+          try {
+            var boot = JSON.parse(bootEl.textContent || '{}');
+            if (boot && boot.freeTier) return;
+          } catch (e) {}
+        }
+      }
       if (document.querySelector('.vf-topbanner')) return;
       if (sessionStorage.getItem('vf-topbanner-dismissed') === '1') return;
       var GUIDE = '/blog/desktop-ai-agents';

package/public/serve-shells/library-raws.html

@@ -2529,12 +2529,25 @@ button.rk-clips-thumb{appearance:none;-webkit-appearance:none;border:0;margin:0;
   // Desktop-agents nudge banner: a full-width alert pinned to the top of the
   // /editor and /chat surfaces pointing to the setup guide. Both surfaces embed
   // this chrome script, so gate strictly by pathname. Dismissible per session.
+  // The nudge is aimed at the DIRECTOR (the paid operator who drives Vidfarm with
+  // a desktop AI agent). A client reviewing a shared video in the editor should
+  // NOT be told to go install Claude Code / Codex — so on the editor we suppress
+  // it for free-tier (client / reviewer) sessions, read from the editor boot JSON.
   (function mountDesktopAgentsBanner() {
     try {
       var path = location.pathname;
       var onEditor = path === '/editor' || path.indexOf('/editor/') === 0;
       var onChat = path === '/chat' || path.indexOf('/chat/') === 0;
       if (!onEditor && !onChat) return;
+      if (onEditor) {
+        var bootEl = document.getElementById('hf-boot');
+        if (bootEl) {
+          try {
+            var boot = JSON.parse(bootEl.textContent || '{}');
+            if (boot && boot.freeTier) return;
+          } catch (e) {}
+        }
+      }
       if (document.querySelector('.vf-topbanner')) return;
       if (sessionStorage.getItem('vf-topbanner-dismissed') === '1') return;
       var GUIDE = '/blog/desktop-ai-agents';

package/public/serve-shells/tools-clipper.html

@@ -2116,12 +2116,25 @@ body.vf-has-topbanner.rk-has-sidebar .rk-content{padding-top:var(--vf-topbanner-
   // Desktop-agents nudge banner: a full-width alert pinned to the top of the
   // /editor and /chat surfaces pointing to the setup guide. Both surfaces embed
   // this chrome script, so gate strictly by pathname. Dismissible per session.
+  // The nudge is aimed at the DIRECTOR (the paid operator who drives Vidfarm with
+  // a desktop AI agent). A client reviewing a shared video in the editor should
+  // NOT be told to go install Claude Code / Codex — so on the editor we suppress
+  // it for free-tier (client / reviewer) sessions, read from the editor boot JSON.
   (function mountDesktopAgentsBanner() {
     try {
       var path = location.pathname;
       var onEditor = path === '/editor' || path.indexOf('/editor/') === 0;
       var onChat = path === '/chat' || path.indexOf('/chat/') === 0;
       if (!onEditor && !onChat) return;
+      if (onEditor) {
+        var bootEl = document.getElementById('hf-boot');
+        if (bootEl) {
+          try {
+            var boot = JSON.parse(bootEl.textContent || '{}');
+            if (boot && boot.freeTier) return;
+          } catch (e) {}
+        }
+      }
       if (document.querySelector('.vf-topbanner')) return;
       if (sessionStorage.getItem('vf-topbanner-dismissed') === '1') return;
       var GUIDE = '/blog/desktop-ai-agents';

package/public/serve-shells/tools-image.html

@@ -3709,12 +3709,25 @@ body.vf-has-topbanner.rk-has-sidebar .rk-content{padding-top:var(--vf-topbanner-
   // Desktop-agents nudge banner: a full-width alert pinned to the top of the
   // /editor and /chat surfaces pointing to the setup guide. Both surfaces embed
   // this chrome script, so gate strictly by pathname. Dismissible per session.
+  // The nudge is aimed at the DIRECTOR (the paid operator who drives Vidfarm with
+  // a desktop AI agent). A client reviewing a shared video in the editor should
+  // NOT be told to go install Claude Code / Codex — so on the editor we suppress
+  // it for free-tier (client / reviewer) sessions, read from the editor boot JSON.
   (function mountDesktopAgentsBanner() {
     try {
       var path = location.pathname;
       var onEditor = path === '/editor' || path.indexOf('/editor/') === 0;
       var onChat = path === '/chat' || path.indexOf('/chat/') === 0;
       if (!onEditor && !onChat) return;
+      if (onEditor) {
+        var bootEl = document.getElementById('hf-boot');
+        if (bootEl) {
+          try {
+            var boot = JSON.parse(bootEl.textContent || '{}');
+            if (boot && boot.freeTier) return;
+          } catch (e) {}
+        }
+      }
       if (document.querySelector('.vf-topbanner')) return;
       if (sessionStorage.getItem('vf-topbanner-dismissed') === '1') return;
       var GUIDE = '/blog/desktop-ai-agents';

package/public/serve-shells/tools-video.html

@@ -2529,12 +2529,25 @@ body.vf-has-topbanner.rk-has-sidebar .rk-content{padding-top:var(--vf-topbanner-
   // Desktop-agents nudge banner: a full-width alert pinned to the top of the
   // /editor and /chat surfaces pointing to the setup guide. Both surfaces embed
   // this chrome script, so gate strictly by pathname. Dismissible per session.
+  // The nudge is aimed at the DIRECTOR (the paid operator who drives Vidfarm with
+  // a desktop AI agent). A client reviewing a shared video in the editor should
+  // NOT be told to go install Claude Code / Codex — so on the editor we suppress
+  // it for free-tier (client / reviewer) sessions, read from the editor boot JSON.
   (function mountDesktopAgentsBanner() {
     try {
       var path = location.pathname;
       var onEditor = path === '/editor' || path.indexOf('/editor/') === 0;
       var onChat = path === '/chat' || path.indexOf('/chat/') === 0;
       if (!onEditor && !onChat) return;
+      if (onEditor) {
+        var bootEl = document.getElementById('hf-boot');
+        if (bootEl) {
+          try {
+            var boot = JSON.parse(bootEl.textContent || '{}');
+            if (boot && boot.freeTier) return;
+          } catch (e) {}
+        }
+      }
       if (document.querySelector('.vf-topbanner')) return;
       if (sessionStorage.getItem('vf-topbanner-dismissed') === '1') return;
       var GUIDE = '/blog/desktop-ai-agents';