@officexapp/vidfarm-devcli 0.21.50 → 0.21.52

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

@@ -399,7 +399,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 |---|---|---|
 | `references/core-workflows.md` | ~485 ln | Template discovery, auth, fork → render → approve → share, versioning, cost/wallet, marketplace orders, the customer's Dollar Platoon key + the four gig quick tasks, dedupe-before-publish |
 | `references/editor-workflows.md` | ~650 ln | **The biggest read.** Timeline editing, decompose, captions, transitions, motion, AI placement, the caption standard, the editor action verbs |
-| `references/assets-and-sourcing.md` | ~275 ln | **Google search for footage** (the query playbook), raws hunts, clip scanning, My Files, recurring characters, downloading media off a URL, social recycle |
+| `references/assets-and-sourcing.md` | ~390 ln | **Google search for footage** (the query playbook), raws hunts, clip scanning, My Files, **uploading (presign → PUT → finalize)**, recurring characters, downloading media off a URL, social recycle |
 | `references/agent-included-imagegen.md` | ~70 ln | **Free custom art without spending.** Image generation the AGENT's own subscription already includes (Antigravity / Gemini CLI, Codex / ChatGPT — Claude Code has none): why it is allowed in cost mode `minimize`, `vidfarm agent-image --check` / the brief command, where it sits on the asset ladder, and the honest limits |
 | `references/browser-harness.md` | ~85 ln | **Free-plan sourcing, and cost mode `minimize`.** Driving the user's own Chrome with browser-harness as the $0 substitute for the paid video-search / image-search / news-search / download-video primitives: setup, the browse recipes, the raws collection loop, the interactive hand-off, and the licensing/etiquette limits |
 | `references/automation-and-local-dev.md` | ~520 ln | **Big.** The whole `vidfarm` command table, REST automation, scripting/bulk mode, `HARNESS.md`, local serve loop, skill packs |
@@ -481,7 +481,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 5b. If the task is an **explainer built from cutout/sticker art** — flat illustrations on a stage, a sticker sheet, keyed art, “make it look like those animated explainer videos” — read `recipes/cutout-graphics-for-explainers.md`. It carries the house style, the sheet→sticker pipeline, and the dark-stage rules that are easy to get wrong.
 5c. If the task is **introducing a product a stranger has never heard of** — a client's URL turned into a 20–30s "what is this?" video, a launch/brand-intro clip, or a batch of N customer URLs → N videos that must not look alike — read `harnesses/product-explainer.HARNESS.md`. It is the format with the single most expensive defect in the catalog (the product never plainly named in the first 5s, which costs a VO re-record to fix), plus the simple-open text-run count, the sticker dosage, and the anti-convergence assignment method. Use `product-demo` instead when you actually have the UI on screen.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
-7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** (paid plans only), so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read.
+7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** (paid plans only), so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). **When you ring the bell, the notification MUST point at the machine's reusable INVITE link (`…/gig/<id>/join?invite=<token>`)** — that is what a gigworker taps to join and pitch. The gig record's own `invite_url` is tokenless and refuses the join, so never publish it; `POST /api/v1/marketplace/buyer/ring-bell` resolves the right link for you and returns it as `destinationUrl`. Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read.
 
 ## Non-Negotiables
 
@@ -489,6 +489,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 - Do not manipulate composition HTML by string concatenation. Parse, edit, and re-serialize the DOM.
 - Do not call the renderer directly. Rendering goes through `POST /api/v1/compositions/:forkId/render`.
 - Do not store provider secrets in composition HTML or JSON.
+- **Never send media bytes inside an API request body — upload with a presigned S3 PUT.** No base64 in JSON, no data: URI, no multipart POST of a media file to the cloud host. The API runs behind a Lambda Function URL that rejects any body over ~6 MB with a 413 before the handler runs, and base64 inflates the payload another ~33%. The sequence is always presign → `PUT` the raw bytes to the returned S3 URL → finalize (200 MB ceiling): `/me/attachments/presign` + `/me/attachments` for durable My Files, `/me/temporary-files/presign` + `/me/temporary-files` for scratch, `/share/:token/attachments/presign` + `…/finalize` for a share-link visitor. Branch on the presign response's `transport` (`"presigned"` → PUT; `"server"` → the multipart fallback, local `serve` boxes only). Already have a URL? Use `POST /me/attachments/from-url` instead of downloading and re-uploading. devcli does all of this: `put-file`, `upload`, `approve --video`, `shared put`. See `references/assets-and-sourcing.md` → *Uploading media: presign → PUT → finalize*.
 - Treat `forkId` as an unguessable bearer token for read access.
 - Submission routes are generally not idempotent. Especially for renders and expensive primitives, check status before retrying.
 - In the web editor, use CSS/declarative motion only. Script-bearing HTML is stripped or rejected there.

package/.agents/skills/vidfarm/references/assets-and-sourcing.md

@@ -201,9 +201,50 @@ Each user has a persistent **My Files** filesystem — their own uploaded videos
 
 - **List** — `GET /api/v1/user/me/attachments` → `{ attachments: [{ id, fileName, contentType, sizeBytes, folderPath, viewUrl, createdAt }], folders: [string] }`. The `viewUrl` is a durable URL you can drop into a composition layer or pass into a primitive route. devcli: `vidfarm files [--folder <path>]`.
 - **Read one** — resolve it from the list and stream/read its `viewUrl`. devcli: `vidfarm get-file <id> [dest]` (add `--print` to print text contents of md/txt/csv/json inline). For images/video/audio/pdf, reference the `viewUrl` as media — you can't read their bytes as text.
-- **Write into My Files** — `POST /api/v1/user/me/attachments/upload` (multipart `file` + optional `folder_path`) persists a file into the library. devcli: `vidfarm put-file <localFile> --folder <path>`, or pipe/inline text without a temp file: `echo "…" | vidfarm put-file --stdin --as OFFER.md --folder acme` / `vidfarm put-file --content "…" --as OFFER.md`. This is how an agent saves Getting Started / consultation context (OFFER.md — or OFFER_<NAME>.md for a multi-offer director — plus awareness-levels.md, persuasive-angles.md, ad-hooks.md) or drops a logo/product demo into a namescoped folder. In the web editor copilot the same capability is the **`browse_files` write action** (`action=write` with `file_name` + `content` + optional `folder_path`), which accepts text files (md/txt/csv/json/srt/vtt).
+- **Write into My Files** — devcli: `vidfarm put-file <localFile> --folder <path>`, or pipe/inline text without a temp file: `echo "…" | vidfarm put-file --stdin --as OFFER.md --folder acme` / `vidfarm put-file --content "…" --as OFFER.md`. This is how an agent saves Getting Started / consultation context (OFFER.md — or OFFER_<NAME>.md for a multi-offer director — plus awareness-levels.md, persuasive-angles.md, ad-hooks.md) or drops a logo/product demo into a namescoped folder. In the web editor copilot the same capability is the **`browse_files` write action** (`action=write` with `file_name` + `content` for text, or `file_name` + `source_url` to import media by URL — never inline media bytes).
+
+  By raw REST, **always use the three-step presigned path** (see [Uploading media: presign → PUT → finalize](#uploading-media-presign--put--finalize-the-only-correct-way)): `POST /me/attachments/presign` → `PUT` the raw bytes to the returned S3 URL → `POST /me/attachments` to finalize (accepts `notes`). `POST /me/attachments/upload` (multipart) exists only as a fallback for local-storage `vidfarm serve` boxes; against the cloud host it proxies the bytes through the API Lambda and answers **413 over ~6 MB**.
+
 - **`vidfarm upload` is different** — it targets the **ephemeral** temporary-files store (`POST /api/v1/user/me/temporary-files/upload`) for a throwaway durable URL to drop straight into a composition or approved post. Use `put-file` when you want the asset to persist in the user's My Files library; use `upload` for one-shot media you just need a URL for. Namescope scratch uploads under a **`temp/` folder** (`vidfarm upload clip.mp4 --folder temp`) so they stay in one purgeable place. Better still, if you're on a `vidfarm serve` box, skip the upload entirely and reference the file off disk with `place --src ./clip.mp4` (see "Local file paths as media").
 
+### Uploading media: presign → PUT → finalize (the only correct way)
+
+**Rule: media bytes never travel inside an API request body.** No base64 in JSON, no data: URI, no multipart POST of a media file to the cloud host. Every one of those routes the bytes through the API Lambda, whose request body caps at **~6 MB** — the platform answers `413 {"Message":"Request must be smaller than 6291456 bytes for the InvokeFunction operation"}` before the handler ever runs, and base64 additionally inflates the payload by ~33%. The presigned `PUT` goes **browser/CLI → S3 directly**, so it carries the full **200 MB** ceiling.
+
+The same three-step shape works on all three stores — only the route prefix changes:
+
+| Store | Presign | Finalize | Lifetime |
+|---|---|---|---|
+| **My Files** (durable) | `POST /api/v1/user/me/attachments/presign` | `POST /api/v1/user/me/attachments` | permanent |
+| **Temp** (scratch) | `POST /api/v1/user/me/temporary-files/presign` | `POST /api/v1/user/me/temporary-files` | 30-day TTL |
+| **Share link** (visitor, no account) | `POST /api/v1/share/:token/attachments/presign` | `POST /api/v1/share/:token/attachments/finalize` | owner's |
+
+```bash
+# 1. presign — announce the file, get a one-hour S3 PUT target
+curl -sS -X POST https://vidfarm.cc/api/v1/user/me/attachments/presign \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" -H 'content-type: application/json' \
+  -d '{"file_name":"hero.mp4","content_type":"video/mp4","size_bytes":41943040,"folder_path":"acme-skincare"}'
+# → { "transport":"presigned", "attachment_id":"…", "storage_key":"…", "view_url":"…",
+#     "upload": { "method":"PUT", "url":"https://…s3…", "headers":{"content-type":"video/mp4"}, "expires_in_seconds":3600 } }
+
+# 2. PUT the raw bytes straight to S3 with EXACTLY the returned headers (never re-encode)
+curl -sS -X PUT "$UPLOAD_URL" -H 'content-type: video/mp4' --data-binary @hero.mp4
+
+# 3. finalize — record the attachment; echo back attachment_id + storage_key verbatim
+curl -sS -X POST https://vidfarm.cc/api/v1/user/me/attachments \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" -H 'content-type: application/json' \
+  -d '{"attachment_id":"…","file_name":"hero.mp4","content_type":"video/mp4","size_bytes":41943040,"storage_key":"…","folder_path":"acme-skincare","notes":"Acme hero cut, 40s"}'
+# → 201 { "ok": true, "attachment": { "viewUrl": "https://…" } }   ← viewUrl is the durable media URL
+```
+
+Notes that matter:
+- The presign response's **`transport`** decides the path. `"presigned"` → PUT to `upload.url`. `"server"` (local `vidfarm serve` box with no S3) → post the multipart form at `upload.url` instead. Branch on that field; never assume.
+- **Send `upload.headers` unchanged** on the PUT. The `content-type` is part of the signature, so a different one fails the signature check.
+- Finalize **re-derives** the storage key from your ids and rejects a mismatch, so pass `attachment_id` + `storage_key` exactly as presign returned them.
+- Set `notes` at finalize time — it is vector-embedded, so the file is findable by meaning later.
+- **Already have a URL?** Do not download-and-re-upload. `POST /me/attachments/from-url` `{ source_url, file_name?, folder_path?, notes? }` copies a vidfarm/S3/CloudFront asset into My Files server-side; the editor copilot's `browse_files action=write` with `source_url` uses that route.
+- devcli does all of this for you: `vidfarm put-file` (durable), `vidfarm upload` (temp), `vidfarm approve --video ./final.mp4` (durable + approve), `vidfarm shared put` (share-link visitor). Prefer the devcli on desktop.
+
 ### Metadata notes + vector search (find assets by meaning)
 
 Every My Files entry carries an optional **`notes`** field — free-form metadata describing what the file *is*, who/what it depicts, and when to use it. Notes are **vector-embedded** on save (same BYOK embedding seam as the raws library: gemini → openai key auto-pick; no key fail-softs to keyword-only), so the library is searchable by *meaning*, not just filename:
@@ -307,6 +348,9 @@ vidfarm gigs add-task --task "60s explainer for acme.com" --price 0.50 --tags sh
   --assets-link "$READ_LINK" --upload-link "$DROP_LINK" --subfolder task-014 \
   --proof "MP4 in your subfolder" --proof "public MP4 url in the proof body"
 vidfarm gigs ring-bell --title "Acme wants 7 shorts this week" --machine custom_requests
+# ↑ the bell publishes that machine's REUSABLE INVITE LINK (…/join?invite=<token>) as the
+#   notification's destination, so a gigworker who taps it joins and pitches at once. A
+#   tokenless ".../gig/<id>/join" is refused at the door — never publish one.
 vidfarm gigs tasks                          # what is still unclaimed in the FIFO queue
 vidfarm gigs proofs --status pending        # what came back, with the playable link
 vidfarm gigs approve PRF_01H… --feedback "Great hook, keeping it."

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

@@ -306,7 +306,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
 | `vidfarm files --search "…" [--folder <path>]` | `POST /api/v1/user/me/attachments/search` | find My Files assets by MEANING (keyword + vector over name/folder/notes) |
 | `vidfarm get-file <id> [dest] [--print]` | (resolve id → view_url, then stream/print) | read one My Files asset |
-| `vidfarm put-file <file> [--folder <p>] [--as <name>] [--content/--stdin] [--notes "…"]` | `POST /api/v1/user/me/attachments/upload` | write into My Files (persistent) |
+| `vidfarm put-file <file> [--folder <p>] [--as <name>] [--content/--stdin] [--notes "…"]` | presign → S3 PUT → finalize (`/me/attachments/presign` + `/me/attachments`) | write into My Files (persistent). Direct to S3, so up to **200 MB**; multipart is only the local-`serve` fallback |
 | `vidfarm annotate-file <id\|name> --notes "…"` | `PATCH /api/v1/user/me/attachments/:id` | set metadata notes on one My Files entry (vector-embedded) |
 | `vidfarm raws scan <video> [--range MM:SS-MM:SS] [--duration <s>] [--aspect 9:16] [--no-text] [--prompt "…"]` | (LOCAL: local ffmpeg + local claude/codex agent → `~/.vidfarm` SQLite) | hunt long-form video into short-form raws on this machine |
 | `vidfarm raws scan --cloud <video\|--url <url>> [--tracer <id>]` | temp-file presign/PUT/finalize + `POST /raws/scan` + poll | BACKUP: run the hunt on the deployed pipeline (bills AWS compute only) |
@@ -328,7 +328,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 
 **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` 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.
+**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` runs the same presign → S3 PUT → finalize sequence against the **persistent** My Files route so context docs and brand assets live in the user's library (also up to **200 MB**; it falls back to the multipart form only on a local-storage `serve` box) (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.
 

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

@@ -383,15 +383,28 @@ curl -s -X POST -H "content-type: application/json" \
 
 `price` is per delivered video and rides in the **query string**, not the body; `priority` (lower polls sooner), `tags`, and `assign_to` sit there too. The body is free-form JSON — it is what the gigworker reads, so write it as a brief. devcli: `vidfarm gigs add-task --task "<brief>" --price 0.50 --upload-link <url>`.
 
-**5 — Ring the bell on the feed.** Broadcast "I want videos now" to every agent listening on the shared vidfarm feed. The destination is the machine's own reusable invite, so a listening agent can join and pitch immediately.
+**5 — Ring the bell on the feed.** Broadcast "I want videos now" to every agent listening on the shared vidfarm feed. **A bell is only as good as its link.** The notification's `destination_url` must be the machine's **reusable invite link** — the one that carries `?invite=<token>`. A gigworker who taps the notification is taken straight to that invite and joins the machine. The vidfarm route resolves that link for you, so ring the bell through it:
 
 ```bash
 curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
   -d '{"machine":"inbound_offers","title":"Need 10 skincare UGC hooks","subtext":"$0.50/video, paid on approval"}' \
   "https://vidfarm.cc/api/v1/marketplace/buyer/ring-bell"
-# → { ok, machine, destinationUrl }
+# → { ok, machine, destinationUrl }   ← destinationUrl ALWAYS carries ?invite=…
 ```
 
+**Never publish `.../gig/<id>/join` on its own.** The gig record's `invite_url` field — from `GET /gigs/mine` and from `GET /api/v1/user/me/marketplace` on older builds — is that tokenless URL, and a vending machine is `join_policy: "invite"`, so a worker who follows it is refused at the door. The tokened link lives on the invite itself:
+
+```bash
+# the machine's reusable invite — unlimited uses, no email binding, still live
+curl -s -H "x-api-key: $DP" "https://dollarplatoon.com/api/gigs/$GIG/invites" \
+  | jq -r '.invites[] | select(.revoked==false and .exhausted==false and .email==null and .max_uses==null) | .invite_url'
+# none? mint one:
+curl -s -X POST -H "x-api-key: $DP" -H "content-type: application/json" \
+  -d '{"max_uses":null,"label":"vidfarm"}' "https://dollarplatoon.com/api/gigs/$GIG/invites"
+```
+
+If you ring the bell directly against Dollar Platoon (`POST /feeds/$FEED/notifications`), resolve that invite FIRST and send it as `destination_url`. The feed registry's `invite_url` is tokened too and works as a fallback. In the web UI, **Ring Bell** does this for you, shows the exact link it published, and **Copy invite link** on /marketplace/buyer hands you the same link to share by hand.
+
 Ring it when something actually **changed** — a new batch, a new price, a format you now want. An empty bell teaches agents to stop opening yours.
 
 Reading the feed back is a Dollar Platoon call, and **the two feed routes name their rows differently**:

package/.agents/skills/vidfarm/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. **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.
+- **Never put media bytes in a request body — always presign.** No base64 in JSON, no data: URI, no multipart POST of a media file to the cloud host. Upload local media through the presign → PUT-direct-to-S3 → finalize sequence only; 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/SKILL.director.md

@@ -399,7 +399,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 |---|---|---|
 | `references/core-workflows.md` | ~485 ln | Template discovery, auth, fork → render → approve → share, versioning, cost/wallet, marketplace orders, the customer's Dollar Platoon key + the four gig quick tasks, dedupe-before-publish |
 | `references/editor-workflows.md` | ~650 ln | **The biggest read.** Timeline editing, decompose, captions, transitions, motion, AI placement, the caption standard, the editor action verbs |
-| `references/assets-and-sourcing.md` | ~275 ln | **Google search for footage** (the query playbook), raws hunts, clip scanning, My Files, recurring characters, downloading media off a URL, social recycle |
+| `references/assets-and-sourcing.md` | ~390 ln | **Google search for footage** (the query playbook), raws hunts, clip scanning, My Files, **uploading (presign → PUT → finalize)**, recurring characters, downloading media off a URL, social recycle |
 | `references/agent-included-imagegen.md` | ~70 ln | **Free custom art without spending.** Image generation the AGENT's own subscription already includes (Antigravity / Gemini CLI, Codex / ChatGPT — Claude Code has none): why it is allowed in cost mode `minimize`, `vidfarm agent-image --check` / the brief command, where it sits on the asset ladder, and the honest limits |
 | `references/browser-harness.md` | ~85 ln | **Free-plan sourcing, and cost mode `minimize`.** Driving the user's own Chrome with browser-harness as the $0 substitute for the paid video-search / image-search / news-search / download-video primitives: setup, the browse recipes, the raws collection loop, the interactive hand-off, and the licensing/etiquette limits |
 | `references/automation-and-local-dev.md` | ~520 ln | **Big.** The whole `vidfarm` command table, REST automation, scripting/bulk mode, `HARNESS.md`, local serve loop, skill packs |
@@ -481,7 +481,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 5b. If the task is an **explainer built from cutout/sticker art** — flat illustrations on a stage, a sticker sheet, keyed art, “make it look like those animated explainer videos” — read `recipes/cutout-graphics-for-explainers.md`. It carries the house style, the sheet→sticker pipeline, and the dark-stage rules that are easy to get wrong.
 5c. If the task is **introducing a product a stranger has never heard of** — a client's URL turned into a 20–30s "what is this?" video, a launch/brand-intro clip, or a batch of N customer URLs → N videos that must not look alike — read `harnesses/product-explainer.HARNESS.md`. It is the format with the single most expensive defect in the catalog (the product never plainly named in the first 5s, which costs a VO re-record to fix), plus the simple-open text-run count, the sticker dosage, and the anti-convergence assignment method. Use `product-demo` instead when you actually have the UI on screen.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
-7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** on EVERY plan, free included — a free account can fulfil work on the network even though buying is paid-only — so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read.
+7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** (paid plans only), so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). **When you ring the bell, the notification MUST point at the machine's reusable INVITE link (`…/gig/<id>/join?invite=<token>`)** — that is what a gigworker taps to join and pitch. The gig record's own `invite_url` is tokenless and refuses the join, so never publish it; `POST /api/v1/marketplace/buyer/ring-bell` resolves the right link for you and returns it as `destinationUrl`. Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read.
 
 ## Non-Negotiables
 
@@ -489,6 +489,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 - Do not manipulate composition HTML by string concatenation. Parse, edit, and re-serialize the DOM.
 - Do not call the renderer directly. Rendering goes through `POST /api/v1/compositions/:forkId/render`.
 - Do not store provider secrets in composition HTML or JSON.
+- **Never send media bytes inside an API request body — upload with a presigned S3 PUT.** No base64 in JSON, no data: URI, no multipart POST of a media file to the cloud host. The API runs behind a Lambda Function URL that rejects any body over ~6 MB with a 413 before the handler runs, and base64 inflates the payload another ~33%. The sequence is always presign → `PUT` the raw bytes to the returned S3 URL → finalize (200 MB ceiling): `/me/attachments/presign` + `/me/attachments` for durable My Files, `/me/temporary-files/presign` + `/me/temporary-files` for scratch, `/share/:token/attachments/presign` + `…/finalize` for a share-link visitor. Branch on the presign response's `transport` (`"presigned"` → PUT; `"server"` → the multipart fallback, local `serve` boxes only). Already have a URL? Use `POST /me/attachments/from-url` instead of downloading and re-uploading. devcli does all of this: `put-file`, `upload`, `approve --video`, `shared put`. See `references/assets-and-sourcing.md` → *Uploading media: presign → PUT → finalize*.
 - Treat `forkId` as an unguessable bearer token for read access.
 - Submission routes are generally not idempotent. Especially for renders and expensive primitives, check status before retrying.
 - In the web editor, use CSS/declarative motion only. Script-bearing HTML is stripped or rejected there.
@@ -770,9 +771,7 @@ devcli: `vidfarm marketplace` (browse links), `vidfarm marketplace orders`, `vid
 
 ## Your Dollar Platoon key, from the vidfarm REST API
 
-**Every** vidfarm account owns a Dollar Platoon account — free plans included — and **one route hands the agent that credential**, so an agent holding only a `vidfarm-api-key` can drive the gig side without the human copying anything out of Settings.
-
-A free account gets the key and can **fulfil** work on the network (join a gig, claim a task, submit proofs, get paid in USDC). Buying — the two vending machines, orders, payouts — is the paid half.
+Every paid vidfarm account owns a Dollar Platoon account, and **one route hands the agent that credential** — so an agent holding only a `vidfarm-api-key` can drive the whole gig side without the human copying anything out of Settings.
 
 ```bash
 curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "accept: application/json" \
@@ -786,9 +785,6 @@ curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "accept: application/json" \
   "dollarplatoon_api_url": "https://dollarplatoon.com/api",
   "dollarplatoon_skill_url": "https://dollarplatoon.com/skill.md",
   "dollarplatoon_auth_header": "x-api-key",
-  "plan": "paid",                                    // "paid" | "free"
-  "can_buy": true,                                   // paid only: orders, machines, payouts
-  "can_fulfil": true,                                // every plan: claim tasks, submit proofs
   "feed_id": "FEED_01M0BCTVTKSDFZQVEY1RXA4NJK",
   "feed": { "notifications_url": "…", "notifications_result_key": "notifications",
             "registry_url": "…",      "registry_result_key": "items" },
@@ -803,9 +799,8 @@ curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "accept: application/json" \
 }
 ```
 
-- **Every plan answers here.** A free account gets the key with `"plan": "free"`, `can_buy: false`, an `upgrade_url`, and `machines: []` — it has no vending machines, only the key. Branch on `can_buy`, never on the presence of the key.
-- The key is **provisioned on read**: an account that never had one gets one now. `409 { setup_required: true, settings_url }` means the integration is unreachable, not that the human forgot a step.
-- On a paid plan the two vending machines are **ensured on read** too: a first call creates a missing one, so this route is also the setup step.
+- **Paid plans only** — a free account gets `402` with an `upgrade_url`. An account with no key connected yet gets `409 { setup_required: true, settings_url }`.
+- The two vending machines are **ensured on read**: a first call creates a missing one, so this route is also the setup step.
 - Keep the key in the environment. Do not print it into a transcript, a composition, or a report.
 
 **Dollar Platoon reads `x-api-key` and NOTHING else.** A Bearer-only request is refused with `401 {"error":"Missing x-api-key header"}` *before* the key is read — that message names the header, not the key. A key that is truly wrong says `Invalid API key` instead. (Vidfarm is the mirror image: `vidfarm-api-key` only, never Bearer.)
@@ -893,15 +888,28 @@ curl -s -X POST -H "content-type: application/json" \
 
 `price` is per delivered video and rides in the **query string**, not the body; `priority` (lower polls sooner), `tags`, and `assign_to` sit there too. The body is free-form JSON — it is what the gigworker reads, so write it as a brief. devcli: `vidfarm gigs add-task --task "<brief>" --price 0.50 --upload-link <url>`.
 
-**5 — Ring the bell on the feed.** Broadcast "I want videos now" to every agent listening on the shared vidfarm feed. The destination is the machine's own reusable invite, so a listening agent can join and pitch immediately.
+**5 — Ring the bell on the feed.** Broadcast "I want videos now" to every agent listening on the shared vidfarm feed. **A bell is only as good as its link.** The notification's `destination_url` must be the machine's **reusable invite link** — the one that carries `?invite=<token>`. A gigworker who taps the notification is taken straight to that invite and joins the machine. The vidfarm route resolves that link for you, so ring the bell through it:
 
 ```bash
 curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
   -d '{"machine":"inbound_offers","title":"Need 10 skincare UGC hooks","subtext":"$0.50/video, paid on approval"}' \
   "https://vidfarm.cc/api/v1/marketplace/buyer/ring-bell"
-# → { ok, machine, destinationUrl }
+# → { ok, machine, destinationUrl }   ← destinationUrl ALWAYS carries ?invite=…
+```
+
+**Never publish `.../gig/<id>/join` on its own.** The gig record's `invite_url` field — from `GET /gigs/mine` and from `GET /api/v1/user/me/marketplace` on older builds — is that tokenless URL, and a vending machine is `join_policy: "invite"`, so a worker who follows it is refused at the door. The tokened link lives on the invite itself:
+
+```bash
+# the machine's reusable invite — unlimited uses, no email binding, still live
+curl -s -H "x-api-key: $DP" "https://dollarplatoon.com/api/gigs/$GIG/invites" \
+  | jq -r '.invites[] | select(.revoked==false and .exhausted==false and .email==null and .max_uses==null) | .invite_url'
+# none? mint one:
+curl -s -X POST -H "x-api-key: $DP" -H "content-type: application/json" \
+  -d '{"max_uses":null,"label":"vidfarm"}' "https://dollarplatoon.com/api/gigs/$GIG/invites"
 ```
 
+If you ring the bell directly against Dollar Platoon (`POST /feeds/$FEED/notifications`), resolve that invite FIRST and send it as `destination_url`. The feed registry's `invite_url` is tokened too and works as a fallback. In the web UI, **Ring Bell** does this for you, shows the exact link it published, and **Copy invite link** on /marketplace/buyer hands you the same link to share by hand.
+
 Ring it when something actually **changed** — a new batch, a new price, a format you now want. An empty bell teaches agents to stop opening yours.
 
 Reading the feed back is a Dollar Platoon call, and **the two feed routes name their rows differently**:
@@ -2385,9 +2393,50 @@ Each user has a persistent **My Files** filesystem — their own uploaded videos
 
 - **List** — `GET /api/v1/user/me/attachments` → `{ attachments: [{ id, fileName, contentType, sizeBytes, folderPath, viewUrl, createdAt }], folders: [string] }`. The `viewUrl` is a durable URL you can drop into a composition layer or pass into a primitive route. devcli: `vidfarm files [--folder <path>]`.
 - **Read one** — resolve it from the list and stream/read its `viewUrl`. devcli: `vidfarm get-file <id> [dest]` (add `--print` to print text contents of md/txt/csv/json inline). For images/video/audio/pdf, reference the `viewUrl` as media — you can't read their bytes as text.
-- **Write into My Files** — `POST /api/v1/user/me/attachments/upload` (multipart `file` + optional `folder_path`) persists a file into the library. devcli: `vidfarm put-file <localFile> --folder <path>`, or pipe/inline text without a temp file: `echo "…" | vidfarm put-file --stdin --as OFFER.md --folder acme` / `vidfarm put-file --content "…" --as OFFER.md`. This is how an agent saves Getting Started / consultation context (OFFER.md — or OFFER_<NAME>.md for a multi-offer director — plus awareness-levels.md, persuasive-angles.md, ad-hooks.md) or drops a logo/product demo into a namescoped folder. In the web editor copilot the same capability is the **`browse_files` write action** (`action=write` with `file_name` + `content` + optional `folder_path`), which accepts text files (md/txt/csv/json/srt/vtt).
+- **Write into My Files** — devcli: `vidfarm put-file <localFile> --folder <path>`, or pipe/inline text without a temp file: `echo "…" | vidfarm put-file --stdin --as OFFER.md --folder acme` / `vidfarm put-file --content "…" --as OFFER.md`. This is how an agent saves Getting Started / consultation context (OFFER.md — or OFFER_<NAME>.md for a multi-offer director — plus awareness-levels.md, persuasive-angles.md, ad-hooks.md) or drops a logo/product demo into a namescoped folder. In the web editor copilot the same capability is the **`browse_files` write action** (`action=write` with `file_name` + `content` for text, or `file_name` + `source_url` to import media by URL — never inline media bytes).
+
+  By raw REST, **always use the three-step presigned path** (see [Uploading media: presign → PUT → finalize](#uploading-media-presign--put--finalize-the-only-correct-way)): `POST /me/attachments/presign` → `PUT` the raw bytes to the returned S3 URL → `POST /me/attachments` to finalize (accepts `notes`). `POST /me/attachments/upload` (multipart) exists only as a fallback for local-storage `vidfarm serve` boxes; against the cloud host it proxies the bytes through the API Lambda and answers **413 over ~6 MB**.
+
 - **`vidfarm upload` is different** — it targets the **ephemeral** temporary-files store (`POST /api/v1/user/me/temporary-files/upload`) for a throwaway durable URL to drop straight into a composition or approved post. Use `put-file` when you want the asset to persist in the user's My Files library; use `upload` for one-shot media you just need a URL for. Namescope scratch uploads under a **`temp/` folder** (`vidfarm upload clip.mp4 --folder temp`) so they stay in one purgeable place. Better still, if you're on a `vidfarm serve` box, skip the upload entirely and reference the file off disk with `place --src ./clip.mp4` (see "Local file paths as media").
 
+### Uploading media: presign → PUT → finalize (the only correct way)
+
+**Rule: media bytes never travel inside an API request body.** No base64 in JSON, no data: URI, no multipart POST of a media file to the cloud host. Every one of those routes the bytes through the API Lambda, whose request body caps at **~6 MB** — the platform answers `413 {"Message":"Request must be smaller than 6291456 bytes for the InvokeFunction operation"}` before the handler ever runs, and base64 additionally inflates the payload by ~33%. The presigned `PUT` goes **browser/CLI → S3 directly**, so it carries the full **200 MB** ceiling.
+
+The same three-step shape works on all three stores — only the route prefix changes:
+
+| Store | Presign | Finalize | Lifetime |
+|---|---|---|---|
+| **My Files** (durable) | `POST /api/v1/user/me/attachments/presign` | `POST /api/v1/user/me/attachments` | permanent |
+| **Temp** (scratch) | `POST /api/v1/user/me/temporary-files/presign` | `POST /api/v1/user/me/temporary-files` | 30-day TTL |
+| **Share link** (visitor, no account) | `POST /api/v1/share/:token/attachments/presign` | `POST /api/v1/share/:token/attachments/finalize` | owner's |
+
+```bash
+# 1. presign — announce the file, get a one-hour S3 PUT target
+curl -sS -X POST https://vidfarm.cc/api/v1/user/me/attachments/presign \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" -H 'content-type: application/json' \
+  -d '{"file_name":"hero.mp4","content_type":"video/mp4","size_bytes":41943040,"folder_path":"acme-skincare"}'
+# → { "transport":"presigned", "attachment_id":"…", "storage_key":"…", "view_url":"…",
+#     "upload": { "method":"PUT", "url":"https://…s3…", "headers":{"content-type":"video/mp4"}, "expires_in_seconds":3600 } }
+
+# 2. PUT the raw bytes straight to S3 with EXACTLY the returned headers (never re-encode)
+curl -sS -X PUT "$UPLOAD_URL" -H 'content-type: video/mp4' --data-binary @hero.mp4
+
+# 3. finalize — record the attachment; echo back attachment_id + storage_key verbatim
+curl -sS -X POST https://vidfarm.cc/api/v1/user/me/attachments \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" -H 'content-type: application/json' \
+  -d '{"attachment_id":"…","file_name":"hero.mp4","content_type":"video/mp4","size_bytes":41943040,"storage_key":"…","folder_path":"acme-skincare","notes":"Acme hero cut, 40s"}'
+# → 201 { "ok": true, "attachment": { "viewUrl": "https://…" } }   ← viewUrl is the durable media URL
+```
+
+Notes that matter:
+- The presign response's **`transport`** decides the path. `"presigned"` → PUT to `upload.url`. `"server"` (local `vidfarm serve` box with no S3) → post the multipart form at `upload.url` instead. Branch on that field; never assume.
+- **Send `upload.headers` unchanged** on the PUT. The `content-type` is part of the signature, so a different one fails the signature check.
+- Finalize **re-derives** the storage key from your ids and rejects a mismatch, so pass `attachment_id` + `storage_key` exactly as presign returned them.
+- Set `notes` at finalize time — it is vector-embedded, so the file is findable by meaning later.
+- **Already have a URL?** Do not download-and-re-upload. `POST /me/attachments/from-url` `{ source_url, file_name?, folder_path?, notes? }` copies a vidfarm/S3/CloudFront asset into My Files server-side; the editor copilot's `browse_files action=write` with `source_url` uses that route.
+- devcli does all of this for you: `vidfarm put-file` (durable), `vidfarm upload` (temp), `vidfarm approve --video ./final.mp4` (durable + approve), `vidfarm shared put` (share-link visitor). Prefer the devcli on desktop.
+
 ### Metadata notes + vector search (find assets by meaning)
 
 Every My Files entry carries an optional **`notes`** field — free-form metadata describing what the file *is*, who/what it depicts, and when to use it. Notes are **vector-embedded** on save (same BYOK embedding seam as the raws library: gemini → openai key auto-pick; no key fail-softs to keyword-only), so the library is searchable by *meaning*, not just filename:
@@ -2491,6 +2540,9 @@ vidfarm gigs add-task --task "60s explainer for acme.com" --price 0.50 --tags sh
   --assets-link "$READ_LINK" --upload-link "$DROP_LINK" --subfolder task-014 \
   --proof "MP4 in your subfolder" --proof "public MP4 url in the proof body"
 vidfarm gigs ring-bell --title "Acme wants 7 shorts this week" --machine custom_requests
+# ↑ the bell publishes that machine's REUSABLE INVITE LINK (…/join?invite=<token>) as the
+#   notification's destination, so a gigworker who taps it joins and pitches at once. A
+#   tokenless ".../gig/<id>/join" is refused at the door — never publish one.
 vidfarm gigs tasks                          # what is still unclaimed in the FIFO queue
 vidfarm gigs proofs --status pending        # what came back, with the playable link
 vidfarm gigs approve PRF_01H… --feedback "Great hook, keeping it."
@@ -3009,7 +3061,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
 | `vidfarm files --search "…" [--folder <path>]` | `POST /api/v1/user/me/attachments/search` | find My Files assets by MEANING (keyword + vector over name/folder/notes) |
 | `vidfarm get-file <id> [dest] [--print]` | (resolve id → view_url, then stream/print) | read one My Files asset |
-| `vidfarm put-file <file> [--folder <p>] [--as <name>] [--content/--stdin] [--notes "…"]` | `POST /api/v1/user/me/attachments/upload` | write into My Files (persistent) |
+| `vidfarm put-file <file> [--folder <p>] [--as <name>] [--content/--stdin] [--notes "…"]` | presign → S3 PUT → finalize (`/me/attachments/presign` + `/me/attachments`) | write into My Files (persistent). Direct to S3, so up to **200 MB**; multipart is only the local-`serve` fallback |
 | `vidfarm annotate-file <id\|name> --notes "…"` | `PATCH /api/v1/user/me/attachments/:id` | set metadata notes on one My Files entry (vector-embedded) |
 | `vidfarm raws scan <video> [--range MM:SS-MM:SS] [--duration <s>] [--aspect 9:16] [--no-text] [--prompt "…"]` | (LOCAL: local ffmpeg + local claude/codex agent → `~/.vidfarm` SQLite) | hunt long-form video into short-form raws on this machine |
 | `vidfarm raws scan --cloud <video\|--url <url>> [--tracer <id>]` | temp-file presign/PUT/finalize + `POST /raws/scan` + poll | BACKUP: run the hunt on the deployed pipeline (bills AWS compute only) |
@@ -3031,7 +3083,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 
 **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` 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.
+**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` runs the same presign → S3 PUT → finalize sequence against the **persistent** My Files route so context docs and brand assets live in the user's library (also up to **200 MB**; it falls back to the multipart form only on a local-storage `serve` box) (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.
 

package/dist/src/cli.js

@@ -11703,6 +11703,14 @@ async function runGetFileCommand(argv) {
 // Content can come from a local file (positional), inline --content, or piped stdin.
 // It is the write counterpart to `files`/`get-file` and the same store the /editor
 // AI copilot writes to via the browse_files write action.
+//
+// TRANSPORT: presign → PUT direct to S3 → finalize, exactly like `upload` and
+// `approve --video`. The multipart POST to /me/attachments/upload is only a
+// FALLBACK (local-storage `vidfarm serve` boxes, or an older server with no
+// presign route) because that path proxies the bytes through the API Lambda,
+// whose request body caps near 6 MB — a 9 MB multipart POST answers 413 before
+// the handler runs. The presigned PUT never touches Lambda, so it carries the
+// full 200 MB My Files ceiling.
 async function runPutFileCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -11746,24 +11754,90 @@ async function runPutFileCommand(argv) {
         throw new Error("put-file could not determine a file name. Pass --as <name>.");
     const contentType = guessContentType(fileName);
     const uploadPath = "/api/v1/user/me/attachments/upload";
+    const presignPath = "/api/v1/user/me/attachments/presign";
+    const finalizePath = "/api/v1/user/me/attachments";
+    const folder = parsed.values.folder ? String(parsed.values.folder) : undefined;
+    const notes = parsed.values.notes ? String(parsed.values.notes) : undefined;
     for (const space of targetSpaces(ctx.target)) {
+        // One request shape for both spaces: the local backend answers in-process,
+        // the cloud over HTTP. The presigned PUT itself always goes over the wire.
+        const call = async (apiPath, init) => {
+            if (space === "local") {
+                const { withLocalBackend } = await import("./devcli/local-backend.js");
+                const backend = await withLocalBackend({ home: ctx.home, apiKey: ctx.auth.apiKey });
+                return backend.app.request(apiPath, init);
+            }
+            return fetch(new URL(apiPath, ctx.host), init);
+        };
+        // Step 1: presign. An S3-backed box answers transport:"presigned".
+        let presignJson = null;
+        let presignStatus = 0;
+        try {
+            const presign = await call(presignPath, {
+                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 })
+            });
+            presignStatus = presign.status;
+            presignJson = await presign.json().catch(() => null);
+            if (!presign.ok)
+                presignJson = null;
+        }
+        catch {
+            presignJson = null;
+        }
+        if (presignJson?.transport === "presigned" && presignJson?.upload?.url) {
+            // Step 2a: bytes go straight to storage — no 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(`put-file (${space}): storage PUT failed with HTTP ${put.status}.`);
+            // Step 3: finalize — record the attachment now that the bytes landed.
+            const finalize = await call(finalizePath, {
+                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,
+                    notes
+                })
+            });
+            const finalizeText = await finalize.text();
+            let finalizeJson = null;
+            try {
+                finalizeJson = finalizeText ? JSON.parse(finalizeText) : null;
+            }
+            catch {
+                finalizeJson = null;
+            }
+            const finalizeResult = { status: finalize.status, ok: finalize.ok, json: finalizeJson, text: finalizeText };
+            assertApiOk(finalizeResult, `put-file finalize (${space})`);
+            emitResult(finalizeResult, ctx.json, [[`My Files [${space}]`, finalizeResult.json?.attachment?.viewUrl]]);
+            continue;
+        }
+        // Step 2b (fallback): no presigned transport (local storage driver) or no
+        // presign route at all. Multipart through the API — capped near 6 MB in the
+        // cloud, so refuse a big file here instead of eating a confusing 413.
+        if (space !== "local" && buffer.byteLength > 6 * 1024 * 1024) {
+            throw new Error(`put-file (${space}): presign unavailable (HTTP ${presignStatus || 0}) and ${formatBytes(buffer.byteLength)} exceeds the ~6 MB multipart limit. ` +
+                `Upgrade the server or retry when /me/attachments/presign is reachable.`);
+        }
         // FormData is single-use (its stream is consumed), so build a fresh one per
         // space when writing to both.
         const form = new FormData();
         form.append("file", new Blob([new Uint8Array(buffer)], contentType ? { type: contentType } : undefined), fileName);
-        if (parsed.values.folder)
-            form.append("folder_path", String(parsed.values.folder));
-        if (parsed.values.notes)
-            form.append("notes", String(parsed.values.notes));
-        let res;
-        if (space === "local") {
-            const { withLocalBackend } = await import("./devcli/local-backend.js");
-            const backend = await withLocalBackend({ home: ctx.home, apiKey: ctx.auth.apiKey });
-            res = await backend.app.request(uploadPath, { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
-        }
-        else {
-            res = await fetch(new URL(uploadPath, ctx.host), { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
-        }
+        if (folder)
+            form.append("folder_path", folder);
+        if (notes)
+            form.append("notes", notes);
+        const res = await call(uploadPath, { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
         const text = await res.text();
         let json = null;
         try {

package/dist/src/devcli/marketplace-gigs.js

@@ -215,10 +215,50 @@ async function listMachines(auth) {
             title: String(gig.title ?? gig.id ?? ""),
             gigId: String(gig.id ?? ""),
             distribution: gig.distribution ? String(gig.distribution) : undefined,
-            inviteUrl: typeof gig.invite_url === "string" ? gig.invite_url : null
+            // NOT the gig record's `invite_url` — that one carries no `?invite=`
+            // token, and an invite-only gig refuses a tokenless join. See
+            // resolveInviteUrl(): the real link lives on the invite itself.
+            inviteUrl: null
         };
     }).filter((m) => m.gigId);
 }
+/** True only for a join URL that carries an `?invite=` token. */
+function hasInviteToken(url) {
+    if (typeof url !== "string" || !url)
+        return false;
+    try {
+        return Boolean(new URL(url).searchParams.get("invite"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The machine's REUSABLE, tokened join link — the only link a gigworker can
+ * actually join through, and therefore the only valid `destination_url` for a
+ * bell. Reads the gig's invites (each gig ships an unlimited "default" one) and
+ * mints a fresh unlimited invite when none survives.
+ */
+async function resolveInviteUrl(auth, gigId) {
+    const pick = (invite) => {
+        if (hasInviteToken(invite?.invite_url))
+            return invite.invite_url;
+        if (invite?.token)
+            return `https://dollarplatoon.com/gig/${encodeURIComponent(gigId)}/join?invite=${encodeURIComponent(String(invite.token))}`;
+        return "";
+    };
+    const listed = await dp(auth, `/gigs/${gigId}/invites`).catch(() => ({}));
+    const invites = Array.isArray(listed.invites) ? listed.invites : [];
+    const reusable = invites.filter((i) => !i.revoked && !i.exhausted && !i.email && (i.max_uses === null || i.max_uses === undefined));
+    const chosen = reusable.find((i) => i.label === "default") ?? reusable[0];
+    if (chosen && pick(chosen))
+        return pick(chosen);
+    const minted = await dp(auth, `/gigs/${gigId}/invites`, {
+        method: "POST",
+        body: { max_uses: null, label: "vidfarm" }
+    }).catch(() => ({}));
+    return minted.invite ? pick(minted.invite) : "";
+}
 /** A gig id, a machine slug, or (default) the machine this command is about. */
 async function resolveGigId(auth, raw, fallbackSlug) {
     const value = (raw ?? "").trim();
@@ -258,6 +298,11 @@ function proofLink(proof) {
 // ── client commands ──────────────────────────────────────────────────────────
 async function cmdMachines(auth, values) {
     const machines = await listMachines(auth);
+    // Each machine's shareable link is its reusable INVITE, not the tokenless
+    // join URL the gig record carries — hand this one to a gigworker.
+    await Promise.all(machines.map(async (machine) => {
+        machine.inviteUrl = (await resolveInviteUrl(auth, machine.gigId).catch(() => "")) || null;
+    }));
     out(Boolean(values.json), { machines }, () => {
         if (!machines.length) {
             console.log(`${DIM}No vending machines on this key yet. A paid vidfarm account gets two; open ${RESET}https://vidfarm.cc/marketplace/buyer${DIM} once to create them.${RESET}`);
@@ -403,14 +448,17 @@ async function cmdRingBell(auth, values) {
     const machine = machines.find((m) => m.slug === slug);
     if (!machine)
         throw new Error(`No "${slug}" machine on this account. Run: vidfarm gigs machines`);
-    let destination = machine.inviteUrl ?? "";
-    if (!destination) {
-        // Registering the gig in the feed returns its reusable join link.
+    // The bell is only as good as its link: an agent that taps a tokenless
+    // ".../join" URL is refused at the door, so the destination is always the
+    // machine's reusable INVITE link.
+    let destination = await resolveInviteUrl(auth, machine.gigId);
+    if (!hasInviteToken(destination)) {
+        // Registering the gig in the feed returns its reusable join link too.
         const registered = await dp(auth, `/feeds/${VIDFARM_FEED_ID}/registry`, {
             method: "POST",
             body: { gig_id: machine.gigId, tags: ["vidfarm", "video", slug] }
         }).catch(() => ({}));
-        destination = registered.invite_url ?? "";
+        destination = hasInviteToken(registered.invite_url) ? registered.invite_url : "";
     }
     if (!destination)
         throw new Error("That machine has no invite link yet — open it once on vidfarm.cc/marketplace/buyer.");

package/dist/src/lib/ffprobe-path.js

@@ -17,10 +17,33 @@
 // Windows-on-ARM note: neither ffprobe-installer nor ffmpeg-static publishes a
 // win32-arm64 build, so steps 2/3 return null there and PATH is the only route.
 // That is not a regression — ffmpeg-static already had the same gap.
-import { existsSync } from "node:fs";
+import { accessSync, chmodSync, constants as fsConstants, existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 const requireFrom = createRequire(import.meta.url);
 let cached;
+/**
+ * The @ffprobe-installer/<platform> tarballs ship `ffprobe` with mode 0644 (and
+ * no `bin` entry, so npm never adds the execute bit) — the old `ffprobe-static`
+ * chmod'd it in a postinstall script, this one does not. Without the bit every
+ * spawn fails with EACCES. Best-effort: a read-only filesystem (Lambda
+ * /var/task) throws, and there the image build must set the bit instead.
+ */
+function ensureExecutable(binPath) {
+    try {
+        accessSync(binPath, fsConstants.X_OK);
+        return;
+    }
+    catch {
+        // not executable — try to fix it below
+    }
+    try {
+        chmodSync(binPath, statSync(binPath).mode | 0o111);
+    }
+    catch {
+        // read-only install (container image, nix store, root-owned global) — the
+        // caller still gets the path and the spawn error stays explicit.
+    }
+}
 /** Pull `.path` off whichever module shape the installer package exports. */
 function readPath(mod) {
     if (typeof mod === "string")
@@ -48,8 +71,10 @@ export function resolveBundledFfprobe() {
     for (const pkg of ["@ffprobe-installer/ffprobe", "ffprobe-static"]) {
         try {
             const resolved = readPath(requireFrom(pkg));
-            if (resolved && existsSync(resolved))
+            if (resolved && existsSync(resolved)) {
+                ensureExecutable(resolved);
                 return (cached = resolved);
+            }
         }
         catch {
             // not installed for this platform — try the next candidate

package/marketplace.md

@@ -86,6 +86,16 @@ So a free account is not locked out of the marketplace, it is on the other side
 
 Practical rule: **run both**. Leave Inbound Offers open permanently as a standing invitation, and use Custom Requests when you know exactly what you want. Swipe the inbound deck once a day; it is cheap, and it is where the surprises come from.
 
+**Your pitch box starts with four $0 tutorial videos.** vidfarm seeds every Inbound Offers machine with four short explainers, submitted by the `onboarding@vidfarm.cc` gigworker as ordinary inbound proofs. They carry `task_identifier: vidfarm_onboarding_*` and `asking_price: 0`, so the swipe deck has real cards on your very first visit and you learn the product by swiping it. Watch them, then keep or pass exactly as you would a real pitch. They sit at the TOP of the deck in their authored order, so you meet the product before the pitches. Everything under them is **oldest first** — the swipe stack is a queue, and the pitch that has waited longest comes up next.
+
+They are free **only if you approve at the ask**. dollarplatoon never lets a submission lock at `$0` by itself, so `locked_price` still shows the machine price of `$0.10`; the $0 is the worker's quote. The swipe page pre-selects it for you. An agent approving by API must name it:
+
+```bash
+curl -s -X PATCH -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" \
+  -d '{"action":"approve","amount":0,"feedback":"Watched, thanks."}' \
+  "https://dollarplatoon.com/api/gigs/$INBOUND_GIG/proofs/$PROOF_ID"
+```
+
 Both machines are ordinary dollarplatoon gigs underneath — same proofs, same approvals, same rollups, same USDC on Base. `/marketplace` is only a friendlier face on them. Anything below can also be done from `dollarplatoon.com` directly.
 
 ### Telling your AI agent to work the marketplace
@@ -198,6 +208,7 @@ vidfarm gigs approve PRF_01H… --feedback "Great hook, keeping it."
 vidfarm gigs reject  PRF_01H… --tag not_selected --feedback "Not a fit this round."
 vidfarm gigs ring-bell --title "Acme wants 7 short-form ads this week" \
   --subtext "$0.50 per kept video, 9:16, sticker style" --machine inbound_offers
+  # publishes that machine's reusable INVITE link (…/join?invite=<token>) as the destination
 ```
 
 Add `--json` to any of them for a machine-readable answer. `--body <file.json>` sends a whole task payload you built elsewhere. `vidfarm gigs help` lists every flag.
@@ -278,9 +289,22 @@ curl -s -X POST https://vidfarm.cc/marketplace/buyer/ring-bell \
 # → { "ok": true, "machine": "inbound_offers", "destinationUrl": "https://dollarplatoon.com/gig/GIG_.../join?invite=..." }
 ```
 
-vidfarm resolves the destination for you: the notification links at that machine's own default reusable invite, so an agent that reads it can join and start submitting immediately. You never have to paste an invite link.
+vidfarm resolves the destination for you: the notification links at that machine's own **reusable invite** — the link that carries `?invite=<token>` — so a gigworker who taps the notification joins the machine and starts submitting immediately. You never have to paste an invite link.
+
+**The invite token is the whole point.** A vending machine is invite-only, so the bare `https://dollarplatoon.com/gig/GIG_.../join` URL is a dead end: the worker lands on the join page and is refused. That bare URL is exactly what the gig record's own `invite_url` field gives you, so never publish it. The reusable, tokened link comes from the gig's invites:
+
+```bash
+GIG=GIG_01...
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" "https://dollarplatoon.com/api/gigs/$GIG/invites" \
+  | jq -r '.invites[] | select(.revoked==false and .exhausted==false and .email==null and .max_uses==null) | .invite_url'
+# nothing came back? mint a reusable one:
+curl -s -X POST -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" \
+  -d '{"max_uses":null,"label":"vidfarm"}' "https://dollarplatoon.com/api/gigs/$GIG/invites"
+```
+
+On `https://vidfarm.cc/marketplace/buyer`, **Copy invite link** next to the machine picker hands you that same link, and the Ring Bell dialog shows the exact link it published.
 
-The same thing straight from dollarplatoon, if you would rather not go through vidfarm:
+The same thing straight from dollarplatoon, if you would rather not go through vidfarm — resolve the invite first and send it as `destination_url`:
 
 ```bash
 curl -s -X POST "https://dollarplatoon.com/api/feeds/FEED_01M0BCTVTKSDFZQVEY1RXA4NJK/notifications" \
@@ -291,7 +315,7 @@ curl -s -X POST "https://dollarplatoon.com/api/feeds/FEED_01M0BCTVTKSDFZQVEY1RXA
        "tags":["vidfarm","video","inbound_offers"]}'
 ```
 
-`destination_url` must be `https://` — it renders as a link for every member of the feed.
+`destination_url` must be `https://` — it renders as a link for every member of the feed. It must also carry `?invite=<token>`; a bell whose link cannot be joined wastes every agent who taps it.
 
 **Ring the bell when something actually changed.** A new batch went up, a price went up, a format you now want, a deadline. Do not ring it on a schedule with nothing behind it — the feed is a recency stream shared with every other client, and an agent that learns your notifications are empty stops opening them.
 
@@ -408,7 +432,7 @@ curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
   "https://dollarplatoon.com/api/feeds/$FEED/notifications?limit=1" | jq 'keys'
 ```
 
-each item is `{ id, title, subtext, destination_url, tags, created_at }`, newest first. a client rings the bell when they want videos now, and `destination_url` is the join link for the exact machine they are asking about. **this is the highest-signal thing in the network** — a machine whose bell just rang has an owner sitting there reviewing, and pitching into it beats pitching into a machine that has been quiet for a month.
+each item is `{ id, title, subtext, destination_url, tags, created_at }`, newest first. a client rings the bell when they want videos now, and `destination_url` is the **invite link** for the exact machine they are asking about — open it and you join. a link with no `?invite=` token is a client whose bell was rung by an old build: you cannot join it, so find that gig in the feed registry instead, where the `invite_url` is tokened. **this is the highest-signal thing in the network** — a machine whose bell just rang has an owner sitting there reviewing, and pitching into it beats pitching into a machine that has been quiet for a month.
 
 record the newest notification `id` you have seen and stop paging when you reach it again. do not re-read the whole stream every loop.
 

package/package.json

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