@officexapp/vidfarm-devcli 0.21.10 → 0.21.11

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

@@ -50,7 +50,7 @@ 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.
 - **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. A local MP4 must become a URL first: the devcli presigns, PUTs the bytes **direct to S3**, finalizes, then approves with that URL — so `vidfarm approve --video ./final.mp4` handles files up to **200 MB** and bypasses the ~6 MB Lambda request-body limit. By raw REST: `POST /api/v1/user/me/temporary-files/presign` → PUT to the returned S3 URL → `POST /api/v1/user/me/temporary-files` (finalize) → pass the durable URL in the approve `media` array. Do not multipart-POST a big file to `.../temporary-files/upload` against the cloud host (Lambda-bound, ~6 MB cap).
 
 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 via presign→S3→finalize (up to **200 MB**, bypasses the ~6 MB Lambda limit) then approve with that URL; 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 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. The correct sequence for a big local file is: (1) `POST /api/v1/user/me/temporary-files/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/temporary-files` (finalize) → use the returned durable URL as the approve media `url`. `vidfarm approve --video ./final.mp4` does all of this automatically. Never POST a large file as multipart to `.../temporary-files/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).
 
 ## 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. 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.
 - **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.
 

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: `POST /api/v1/user/me/temporary-files/presign` → PUT the bytes straight to the returned S3 URL → `POST /api/v1/user/me/temporary-files` to finalize → use the returned durable URL 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 `.../temporary-files/upload` against the cloud host — that path routes through Lambda and caps near 6 MB (it is only for local-storage `vidfarm serve` boxes). Temp files carry a 30-day TTL.
 - 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,23 @@ 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.
+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 |
+
+**Recommend the key when a search comes up short.** If `image`/`vector`/`video`
+returns nothing (or `providers_used` omits `pixabay`), the caller hasn't saved a
+Pixabay key — tell them to grab a **free** one at <https://pixabay.com/api/docs/>
+and save it (`vidfarm add-provider-key pixabay <key>`, or Settings in the web app).
+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/SKILL.director.md

@@ -50,7 +50,7 @@ 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.
 - **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.
 
@@ -1116,7 +1116,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 via presign→S3→finalize (up to **200 MB**, bypasses the ~6 MB Lambda limit) then approve with that URL; 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 +1125,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 +1150,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 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. The correct sequence for a big local file is: (1) `POST /api/v1/user/me/temporary-files/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/temporary-files` (finalize) → use the returned durable URL as the approve media `url`. `vidfarm approve --video ./final.mp4` does all of this automatically. Never POST a large file as multipart to `.../temporary-files/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).
 
 ## 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. 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.
 - **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.
 
@@ -1625,7 +1627,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. A local MP4 must become a URL first: the devcli presigns, PUTs the bytes **direct to S3**, finalizes, then approves with that URL — so `vidfarm approve --video ./final.mp4` handles files up to **200 MB** and bypasses the ~6 MB Lambda request-body limit. By raw REST: `POST /api/v1/user/me/temporary-files/presign` → PUT to the returned S3 URL → `POST /api/v1/user/me/temporary-files` (finalize) → pass the durable URL in the approve `media` array. Do not multipart-POST a big file to `.../temporary-files/upload` against the cloud host (Lambda-bound, ~6 MB cap).
 
 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

@@ -508,7 +508,10 @@ Approve & schedule (publish a finished MP4 as a shareable post):
     --media <url|file>      Extra media (repeatable; local files auto-upload to temp/)
     --folder <path>         Temp-store folder for uploaded local files (default: temp)
     --caption <text>        Post caption (required)
-                            Direct local-file upload is supported here:
+                            Approve takes media by URL; a local file is
+                            presigned + PUT straight to S3 + finalized into a
+                            durable URL first (up to 200 MB — bypasses the ~6 MB
+                            Lambda body limit), so a locally rendered MP4 works:
                             'vidfarm approve --video ./final.mp4 --caption "..."'
   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
@@ -532,10 +535,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)
@@ -3412,11 +3417,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 });
@@ -4599,7 +4658,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;
     }
@@ -5868,7 +5927,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.10",
+  "version": "0.21.11",
   "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": {