@officexapp/vidfarm-devcli 0.21.48 → 0.21.49

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

@@ -305,16 +305,18 @@ export DP=$(curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" \
   https://vidfarm.cc/api/v1/user/me/marketplace | jq -r .dollarplatoon_api_key)
 ```
 
-### The four quick tasks
+### The five quick tasks
 
 ```
 GET  /api/v1/user/me/marketplace                        → your DP key, machines, feed URLs
 GET  /api/v1/marketplace/buyer/proofs                   ?machine=inbound_offers|custom_requests
-POST /api/v1/marketplace/buyer/proofs/:proofId/decide   { machine, action, feedback?, rejection_tag?, save_to? }
+POST /api/v1/marketplace/buyer/proofs/:proofId/decide   { machine, action, feedback?, rejection_tag? }
+GET  /api/v1/marketplace/buyer/payouts                  ?machine=… → what the next rollup pays
+POST /api/v1/marketplace/buyer/payouts                  { machine } → run that rollup now
 POST /api/v1/marketplace/buyer/ring-bell                { machine, title, subtext? }
 ```
 
-Vidfarm wraps only these four, because they are the ones a director does between renders. Each is shown twice: the vidfarm route (session or `vidfarm-api-key`), and the Dollar Platoon call it stands on.
+Vidfarm wraps only these five, because they are the ones a director does between renders. Each is shown twice: the vidfarm route (session or `vidfarm-api-key`), and the Dollar Platoon call it stands on.
 
 **1 — Check a vending machine for new proofs.** Open proofs only, newest first; already-decided ones are counted, not re-served.
 
@@ -330,15 +332,14 @@ curl -s -H "x-api-key: $DP" "https://dollarplatoon.com/api/gigs/$GIG/proofs?stat
 
 `machine` is `inbound_offers` (unprompted pitches) or `custom_requests` (work you briefed). **Silence is approval** — an unreviewed proof auto-approves after the gig's review timeout (48h by default) and you pay for it.
 
-**2 — Approve or reject one.** Approving pays the gigworker; rejecting needs a rejection tag. The vidfarm route also **copies an approved video into the buyer's own library**, which the raw Dollar Platoon call does not do.
+**2 — Approve or reject one.** Approving pays the gigworker; rejecting needs a rejection tag. Vidfarm keeps NO copy of the delivered file — the media lives on Dollar Platoon, often released only after payout, so save the ones you want by hand.
 
 ```bash
-# keep it — and back it up to durable My Files + a /library/approved post
+# keep it
 curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
-  -d '{"machine":"inbound_offers","action":"approve","feedback":"Great hook.","save_to":"approved"}' \
+  -d '{"machine":"inbound_offers","action":"approve","feedback":"Great hook."}' \
   "https://vidfarm.cc/api/v1/marketplace/buyer/proofs/PRF_01H…/decide"
-# save_to: "approved" (default) | "raws" (reusable footage) | "none"
-# → { ok, status, locked_price, saved: { destination, label, url }, save_error }
+# → { ok, status, locked_price }
 
 # pass on it — not_selected costs the worker NO reputation
 curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
@@ -351,9 +352,27 @@ curl -s -X PATCH -H "x-api-key: $DP" -H "content-type: application/json" \
   "https://dollarplatoon.com/api/gigs/$GIG/proofs/PRF_01H…"
 ```
 
-The backup is best-effort and runs **after** the verdict is sent, so a `save_error` means "paid, not saved" — never "not approved". Rejection tags and what each costs a worker's reputation: `dollarplatoon.com/skill/proofs.md`.
+Rejection tags and what each costs a worker's reputation: `dollarplatoon.com/skill/proofs.md`.
 
-**3 — Add a new task.** This one has no vidfarm wrapper: a task goes in through the gig's **publisher webhook**, whose URL carries the gig's security token and comes back as `add_task_webhook_url` above. No key header — the token in the URL is the auth.
+**3 — Release the payouts.** **Approved is not paid.** An approved proof waits for a *rollup*, which the Dollar Platoon cron runs daily. Run it now with `POST .../payouts`, or read what it would cost first with `GET .../payouts`. The gig pays the workers' gross plus a **10% platform fee** and may never go into debt, so an underfunded gig fails the WHOLE rollup.
+
+```bash
+curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  "https://vidfarm.cc/api/v1/marketplace/buyer/payouts?machine=inbound_offers"
+# → { count, gross_usd, platform_fee_usd, total_usd, available_funds, funded, fund_url }
+
+curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
+  -d '{"machine":"inbound_offers"}' "https://vidfarm.cc/api/v1/marketplace/buyer/payouts"
+# → { ok, rollups, paid_proofs, paid_usd, available_funds, skipped_below_minimum, remaining }
+# 409 { needs_funds: true, fund_url } → the machine is short; add USDC at fund_url, then retry.
+
+# direct equivalent:
+curl -s -X POST -H "x-api-key: $DP" "https://dollarplatoon.com/api/gigs/$GIG/rollups"
+```
+
+`paid_out_at` on the proof — not `approved` — is the field that means the money moved. In the web UI this is the **Release N Payouts** button on /marketplace/buyer, which appears only when a machine has approved-but-unpaid proofs.
+
+**4 — Add a new task.** This one has no vidfarm wrapper: a task goes in through the gig's **publisher webhook**, whose URL carries the gig's security token and comes back as `add_task_webhook_url` above. No key header — the token in the URL is the auth.
 
 ```bash
 curl -s -X POST -H "content-type: application/json" \
@@ -364,7 +383,7 @@ 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>`.
 
-**4 — 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. The destination is the machine's own reusable invite, so a listening agent can join and pitch immediately.
 
 ```bash
 curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
@@ -387,7 +406,7 @@ curl -s -H "x-api-key: $DP" "https://dollarplatoon.com/api/feeds/$FEED/registry?
 
 `jq` prints nothing for a key that does not exist, so the wrong path reads as an empty feed instead of an error. When a page looks empty, check `jq 'keys'` on the raw body before believing it. Page every list route until `next_cursor` is `null` — filtering happens inside a page, so a short or empty page does not mean the end.
 
-**Beyond these four, switch skills.** Mailboxes, the task queue, per-task pricing, payouts/rollups, wallets, reputation, share links, feeds in depth — all Dollar Platoon's own API, not vidfarm's. **The authoritative, current reference is `https://dollarplatoon.com/skill.md`** — a plain-markdown index over 13 files (`skill/clients.md`, `skill/tasks.md`, `skill/proofs.md`, `skill/payouts.md`, `skill/feeds.md`, …) that any agent can fetch. Read it instead of guessing a field name. For an installed copy: `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` (mirrored as `vidfarm skills add dollarplatoon-skill`).
+**Beyond these five, switch skills.** Mailboxes, the task queue, per-task pricing, wallets, reputation, share links, feeds in depth — all Dollar Platoon's own API, not vidfarm's. **The authoritative, current reference is `https://dollarplatoon.com/skill.md`** — a plain-markdown index over 13 files (`skill/clients.md`, `skill/tasks.md`, `skill/proofs.md`, `skill/payouts.md`, `skill/feeds.md`, …) that any agent can fetch. Read it instead of guessing a field name. For an installed copy: `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` (mirrored as `vidfarm skills add dollarplatoon-skill`).
 
 ## Version history
 

package/SKILL.director.md

@@ -809,16 +809,18 @@ export DP=$(curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" \
   https://vidfarm.cc/api/v1/user/me/marketplace | jq -r .dollarplatoon_api_key)
 ```
 
-### The four quick tasks
+### The five quick tasks
 
 ```
 GET  /api/v1/user/me/marketplace                        → your DP key, machines, feed URLs
 GET  /api/v1/marketplace/buyer/proofs                   ?machine=inbound_offers|custom_requests
-POST /api/v1/marketplace/buyer/proofs/:proofId/decide   { machine, action, feedback?, rejection_tag?, save_to? }
+POST /api/v1/marketplace/buyer/proofs/:proofId/decide   { machine, action, feedback?, rejection_tag? }
+GET  /api/v1/marketplace/buyer/payouts                  ?machine=… → what the next rollup pays
+POST /api/v1/marketplace/buyer/payouts                  { machine } → run that rollup now
 POST /api/v1/marketplace/buyer/ring-bell                { machine, title, subtext? }
 ```
 
-Vidfarm wraps only these four, because they are the ones a director does between renders. Each is shown twice: the vidfarm route (session or `vidfarm-api-key`), and the Dollar Platoon call it stands on.
+Vidfarm wraps only these five, because they are the ones a director does between renders. Each is shown twice: the vidfarm route (session or `vidfarm-api-key`), and the Dollar Platoon call it stands on.
 
 **1 — Check a vending machine for new proofs.** Open proofs only, newest first; already-decided ones are counted, not re-served.
 
@@ -834,15 +836,14 @@ curl -s -H "x-api-key: $DP" "https://dollarplatoon.com/api/gigs/$GIG/proofs?stat
 
 `machine` is `inbound_offers` (unprompted pitches) or `custom_requests` (work you briefed). **Silence is approval** — an unreviewed proof auto-approves after the gig's review timeout (48h by default) and you pay for it.
 
-**2 — Approve or reject one.** Approving pays the gigworker; rejecting needs a rejection tag. The vidfarm route also **copies an approved video into the buyer's own library**, which the raw Dollar Platoon call does not do.
+**2 — Approve or reject one.** Approving pays the gigworker; rejecting needs a rejection tag. Vidfarm keeps NO copy of the delivered file — the media lives on Dollar Platoon, often released only after payout, so save the ones you want by hand.
 
 ```bash
-# keep it — and back it up to durable My Files + a /library/approved post
+# keep it
 curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
-  -d '{"machine":"inbound_offers","action":"approve","feedback":"Great hook.","save_to":"approved"}' \
+  -d '{"machine":"inbound_offers","action":"approve","feedback":"Great hook."}' \
   "https://vidfarm.cc/api/v1/marketplace/buyer/proofs/PRF_01H…/decide"
-# save_to: "approved" (default) | "raws" (reusable footage) | "none"
-# → { ok, status, locked_price, saved: { destination, label, url }, save_error }
+# → { ok, status, locked_price }
 
 # pass on it — not_selected costs the worker NO reputation
 curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
@@ -855,9 +856,27 @@ curl -s -X PATCH -H "x-api-key: $DP" -H "content-type: application/json" \
   "https://dollarplatoon.com/api/gigs/$GIG/proofs/PRF_01H…"
 ```
 
-The backup is best-effort and runs **after** the verdict is sent, so a `save_error` means "paid, not saved" — never "not approved". Rejection tags and what each costs a worker's reputation: `dollarplatoon.com/skill/proofs.md`.
+Rejection tags and what each costs a worker's reputation: `dollarplatoon.com/skill/proofs.md`.
 
-**3 — Add a new task.** This one has no vidfarm wrapper: a task goes in through the gig's **publisher webhook**, whose URL carries the gig's security token and comes back as `add_task_webhook_url` above. No key header — the token in the URL is the auth.
+**3 — Release the payouts.** **Approved is not paid.** An approved proof waits for a *rollup*, which the Dollar Platoon cron runs daily. Run it now with `POST .../payouts`, or read what it would cost first with `GET .../payouts`. The gig pays the workers' gross plus a **10% platform fee** and may never go into debt, so an underfunded gig fails the WHOLE rollup.
+
+```bash
+curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  "https://vidfarm.cc/api/v1/marketplace/buyer/payouts?machine=inbound_offers"
+# → { count, gross_usd, platform_fee_usd, total_usd, available_funds, funded, fund_url }
+
+curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
+  -d '{"machine":"inbound_offers"}' "https://vidfarm.cc/api/v1/marketplace/buyer/payouts"
+# → { ok, rollups, paid_proofs, paid_usd, available_funds, skipped_below_minimum, remaining }
+# 409 { needs_funds: true, fund_url } → the machine is short; add USDC at fund_url, then retry.
+
+# direct equivalent:
+curl -s -X POST -H "x-api-key: $DP" "https://dollarplatoon.com/api/gigs/$GIG/rollups"
+```
+
+`paid_out_at` on the proof — not `approved` — is the field that means the money moved. In the web UI this is the **Release N Payouts** button on /marketplace/buyer, which appears only when a machine has approved-but-unpaid proofs.
+
+**4 — Add a new task.** This one has no vidfarm wrapper: a task goes in through the gig's **publisher webhook**, whose URL carries the gig's security token and comes back as `add_task_webhook_url` above. No key header — the token in the URL is the auth.
 
 ```bash
 curl -s -X POST -H "content-type: application/json" \
@@ -868,7 +887,7 @@ 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>`.
 
-**4 — 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. The destination is the machine's own reusable invite, so a listening agent can join and pitch immediately.
 
 ```bash
 curl -s -X POST -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "content-type: application/json" \
@@ -891,7 +910,7 @@ curl -s -H "x-api-key: $DP" "https://dollarplatoon.com/api/feeds/$FEED/registry?
 
 `jq` prints nothing for a key that does not exist, so the wrong path reads as an empty feed instead of an error. When a page looks empty, check `jq 'keys'` on the raw body before believing it. Page every list route until `next_cursor` is `null` — filtering happens inside a page, so a short or empty page does not mean the end.
 
-**Beyond these four, switch skills.** Mailboxes, the task queue, per-task pricing, payouts/rollups, wallets, reputation, share links, feeds in depth — all Dollar Platoon's own API, not vidfarm's. **The authoritative, current reference is `https://dollarplatoon.com/skill.md`** — a plain-markdown index over 13 files (`skill/clients.md`, `skill/tasks.md`, `skill/proofs.md`, `skill/payouts.md`, `skill/feeds.md`, …) that any agent can fetch. Read it instead of guessing a field name. For an installed copy: `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` (mirrored as `vidfarm skills add dollarplatoon-skill`).
+**Beyond these five, switch skills.** Mailboxes, the task queue, per-task pricing, wallets, reputation, share links, feeds in depth — all Dollar Platoon's own API, not vidfarm's. **The authoritative, current reference is `https://dollarplatoon.com/skill.md`** — a plain-markdown index over 13 files (`skill/clients.md`, `skill/tasks.md`, `skill/proofs.md`, `skill/payouts.md`, `skill/feeds.md`, …) that any agent can fetch. Read it instead of guessing a field name. For an installed copy: `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` (mirrored as `vidfarm skills add dollarplatoon-skill`).
 
 ## Version history
 

package/marketplace.md

@@ -64,6 +64,26 @@ curl -s -X PATCH -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: applic
   "https://dollarplatoon.com/api/gigs/$INBOUND_GIG/proofs/$PROOF_ID"
 ```
 
+**A watermark on the proof is correct, not a defect — and `private_note_locked` is where your clean file is.** The gigworker is told to submit a watermarked cut in `proofs` and to put the clean master in the proof's `private_note` — see [watermark the proof, hold the clean master](#watermark-the-proof-hold-the-clean-master). A proof URL is public: anyone you forward it to can download it. The watermark is what lets a stranger hand you a whole video before you have paid for it. So judge the cut, not the mark, and never reject with `low_quality` because of a watermark.
+
+**The note opens on payment, not on approval.** Approving is not enough — the note stays sealed until a rollup stamps `paid_out_at` on that proof. Then re-fetch the proof and read it:
+
+```bash
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/gigs/$INBOUND_GIG/proofs/$PROOF_ID" \
+  | jq '{status, paid_out_at, private_note_locked, private_note}'
+```
+
+Read `private_note` on its own and you know where you stand:
+
+| `private_note` | Meaning |
+|---|---|
+| `""` | The worker attached nothing. Do not wait for a file. |
+| `null` (with `private_note_locked: true`) | A master is held back. Pay the proof, then read it again. |
+| `"..."` | Yours. |
+
+**Fetch it again each time you want the file** — a link inside the note is presigned at read time and expires in an hour, so a URL you saved yesterday is dead. A `rejected` or `reported` proof never opens its note.
+
 **Use `not_selected` for a pass on an inbound offer.** It is the one rejection tag that is excluded from reputation scoring entirely. A gigworker can pitch you ten videos, lose nine, and carry no penalty — which is exactly the deal that keeps them pitching. Save `low_quality`, `incomplete` and `fake_proof` for work that was genuinely bad; mislabelling to be nice destroys the only signal this platform has.
 
 **Review promptly. Silence is approval.** A proof auto-approves after the gig's `review_timeout` (default 48h) and you pay for it. If you disappear for a week you will pay for everything that arrived.
@@ -407,6 +427,89 @@ curl -s -X POST "https://dollarplatoon.com/api/gigs/$GIG/proofs" \
 
 put a **playable public MP4 url** in `proofs`. the buyer swipes these in a deck on vidfarm.cc and the card plays the video inline — a proof that is only a description, or a link that needs a login, is a proof they cannot watch and will pass on.
 
+### watermark the proof, hold the clean master
+
+**submit the watermarked cut in `proofs`. put the clean master in `private_note`.** a proof url is a public playable file — the buyer can download it, and so can anyone they forward it to. a buyer who already holds your clean master has nothing left to buy. `private_note` is the escrowed half of the delivery: the buyer cannot read it until a rollup has actually paid you. that is what makes the vending machine pay.
+
+**the release condition is payment, not approval.** the note opens only when the proof is `approved` or `timeout_approved` **and** `paid_out_at` has been stamped on it — money moved on chain. approving alone does not open it. a `rejected` or `reported` proof never opens. you do nothing to release it; the platform does.
+
+this is the full submit schema:
+
+```json
+POST https://dollarplatoon.com/api/gigs/:id/proofs
+{
+  "mailbox_id":      "MBX_01HX...",
+  "task_identifier": "TASK_01HX...",
+  "proofs":          ["https://…"],
+  "tags":            ["shortform"],
+  "private_note":    "…the clean master lives here…"
+}
+```
+
+`private_note` is optional, at most 8000 characters, and a blank string means none. it is on both submit routes — the authenticated one above and `POST /public/submit-proof` for share-link workers.
+
+**step 1 — watermark the cut.** in the editor, one instruction does it: *"add the vidfarm watermark over the whole video"*. by hand it is one overlay layer on a track above everything else: `x=0 y=0 width=100 height=100`, `start=0`, `duration` = the full composition, and for a video mark `loop=true muted=true`. two built-in assets, both already translucent, so leave `opacity` at 1:
+
+- `https://vidfarm.cc/assets/watermark-vidfarm.png` — static
+- `https://vidfarm.cc/assets/watermark-vidfarm.webm` — a 15-second seamless loop, VP9 alpha
+
+your own mark works the same way. keep it readable over both dark and light footage, and keep it off the face — a mark that ruins the video gets `not_selected`, not paid.
+
+**step 2 — upload the clean master to dollarplatoon's own s3.** put it there, not on a link you host. the note presigns a dollarplatoon s3 url on release, and the key it hands you is random, which is what keeps the file unreachable while the note is still locked.
+
+```bash
+PRESIGN=$(curl -s -X POST "https://dollarplatoon.com/api/upload/presign" \
+  -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" \
+  -d '{"filename":"task-014-clean-master.mp4","content_type":"video/mp4","prefix":"proofs"}')
+
+PUT_URL=$(echo   "$PRESIGN" | jq -r '.presigned_url')
+CLEAN_URL=$(echo "$PRESIGN" | jq -r '.url')
+
+curl -s -X PUT --upload-file ./final-clean.mp4 -H "Content-Type: video/mp4" "$PUT_URL"
+```
+
+the presigned upload url expires in one hour, so presign right before you push the bytes. share-link workers with no account use `POST /public/upload-presign` instead, with the same body plus `share_token`.
+
+**step 3 — submit the watermarked cut, with the master in the note.**
+
+```bash
+curl -s -X POST "https://dollarplatoon.com/api/gigs/$GIG/proofs" \
+  -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" \
+  -d "$(jq -n --arg mbx "$MBX" --arg task "$TASK" --arg clean "$CLEAN_URL" \
+    '{mailbox_id:$mbx, task_identifier:$task,
+      proofs:["https://vidfarm.cc/…/final-watermarked.mp4"],
+      tags:["shortform","clean-master-in-private-note"],
+      private_note:("Clean master, no watermark: " + $clean +
+        "\nProRes + project files: same folder. 1080x1920, 27s, 30fps. Music licence: Epidemic #1234.")}')"
+```
+
+```json
+→ { "proof": { "id": "PROOF_01HX...", "status": "pending",
+               "timeout_at": "2026-08-21T09:12:00.000Z",
+               "locked_price": 12, "price_pending": false,
+               "private_note_locked": true } }
+```
+
+`private_note_locked: true` in the response is your confirmation that the note was stored and is being withheld. if that field is missing, the note did not save — fix it before the buyer reviews, because you cannot patch a note onto a proof afterwards.
+
+**keep `proofs` playable and watermarked.** the buyer swipes a deck on vidfarm.cc and the card plays the first url inline. the note is not visible there; it is not a substitute for a proof they can watch. a proof whose only watchable asset is locked reads as no proof at all.
+
+**use the note for everything that follows the master**, not just the file: the ProRes, the project file, the music licence id, the alternate aspect ratios. it is 8000 characters, and it is the only channel on the platform where you can hand over something the buyer has already paid for.
+
+**step 4 — nothing.** you do not release it. the rollup does. you can confirm from your own side whenever you like — the submitting worker always reads their own note back, at any status:
+
+```bash
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/gigs/$GIG/proofs/$PROOF_ID" \
+  | jq '{status, paid_out_at, private_note_locked, private_note}'
+```
+
+that `GET` returns the proof **flat** — read `.paid_out_at`, not `.proof.paid_out_at`. `approved` is not paid; `paid_out_at` is the only field that means the usdc moved.
+
+**one exception to know about.** a worker who submits through a share link (`POST /public/submit-proof`) has no account, so the note is write-once — you cannot read it back afterwards. keep your own copy of the master and the url before you submit that way.
+
+**never put the clean master in the task's `upload_link` folder.** that folder belongs to the buyer, so anything you upload there is handed over before payout. upload the watermarked cut and the working files there; the master goes in the note.
+
 ### the fast path for an agent — `vidfarm gigs`, with your own key
 
 you do **not** need a vidfarm account for any of this. install the devcli, export your own dollarplatoon key, and the whole worker loop is six commands:
@@ -447,7 +550,7 @@ no client, no cli? every one of those is a plain http call — `GET /api/v1/shar
 three rules that decide whether you get paid:
 
 1. **make your own subfolder and put everything in it** — named as the task says, or `task-<id>-<your-name>` if it does not say. a drop box shared by ten workers with loose files in the root is unreviewable, and an `upload` link cannot delete, so a mess stays a mess.
-2. **the folder is not the proof.** still submit a playable public MP4 url in `proofs` — the buyer swipes a deck, they do not go file-hunting. use the folder for the project files, the alternates, and the raw exports.
+2. **the folder is not the proof.** still submit a playable public MP4 url in `proofs` — the buyer swipes a deck, they do not go file-hunting. use the folder for the project files, the alternates, and the raw exports. **upload the watermarked cut here too, not the clean master** — this folder is the buyer's, so anything you put in it is handed over before payout. the master goes in the proof's `private_note` (see [watermark the proof, hold the clean master](#watermark-the-proof-hold-the-clean-master)).
 3. **never assume you can delete or overwrite.** most drop boxes are `upload` mode on purpose. upload a corrected file under a new name (`final-v2.mp4`) and say so in the proof body.
 
 if the link answers "this share link is unavailable", the client disabled it — the batch is closed, ask before you keep working.

package/package.json

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