@officexapp/vidfarm-devcli 0.21.45 → 0.21.47

package/experiments.md

@@ -129,7 +129,7 @@ That is the strong starting checkpoint. It is not arbitrary — it is the cheape
 Test **N videos regardless of their composition params.** Every video may differ in format, hook, angle, pacing, everything. You are not isolating a variable; you are **searching a wide space fast** for outliers.
 
 - **Best for:** new users, cold starts, any product with no performance history at all.
-- **Editing:** thrives with **distributed task forces** — other people's AI agents (gigworkers) doing the editing. Variance between editors is a *feature* here: it widens the search. Set up the loop from `https://vidfarm.cc/crowdsourcing.md` (client POV — a Dollar Platoon vending machine, one task per video, batches of 7 because that is a week of content).
+- **Editing:** thrives with **distributed task forces** — other people's AI agents (gigworkers) doing the editing. Variance between editors is a *feature* here: it widens the search. Set up the loop from `https://vidfarm.cc/marketplace.md` (client POV — a Dollar Platoon vending machine, one task per video, batches of 7 because that is a week of content).
 - **Typical shape:** the user brings the selling angles; the gigworkers take creative liberty on everything else. You get diverse videos, and diversity gets you to an outlier fastest.
 - **What you learn:** *that* something works. Not yet why.
 
@@ -420,6 +420,6 @@ When you accumulate winners, you are building the real deliverable: **a library
 ## Where to go next
 
 - **Making the videos:** `https://vidfarm.cc/skill.md` (and the director skill it points to — hooks, harnesses, review, cost mode, interactive vs autonomous)
-- **Crowdsourcing the editing (Creative Mode, client POV):** `https://vidfarm.cc/crowdsourcing.md`
+- **Crowdsourcing the editing (Creative Mode, client POV):** `https://vidfarm.cc/marketplace.md`
 - **The agentic clipper loop programme:** `https://vidfarm.cc/clipper.md`
 - **Scheduling and analytics:** the `flockposter` skill, or the Vidfarm email channel scheduling flow

package/marketplace.md

@@ -0,0 +1,549 @@
+# Marketplace.md
+
+How to crowdsource videos from the vidfarm.cc marketplace.
+Please redirect user based on whether they are a client or a gigworker, instructions below.
+
+> Served at `https://vidfarm.cc/marketplace.md`. The older `https://vidfarm.cc/crowdsourcing.md`
+> redirects here — same document, one canonical name.
+
+## Client Instructions
+
+Please help setup agentic clipper loops for a client so they can get crowdsourced viral videos for their app.
+
+### Start at vidfarm.cc/marketplace — you already have two vending machines
+
+You do not have to create a gig to start. Every **paid** vidfarm.cc account is provisioned with a dollarplatoon.com account **and two standing vending machines**. `https://vidfarm.cc/marketplace` opens straight onto them, and the Marketplace link appears in the sidebar. If your account predates this, just visit the page — it re-creates anything missing on load. The marketplace is a paid-plan feature: a free account sees the upgrade wall, and its machines are only created when it upgrades.
+
+| Machine | slug | dollarplatoon distribution | What it is |
+|---|---|---|---|
+| **Inbound Offers** | `inbound_offers` | `inbound_proof` | An open pitch box. **No tasks are handed out.** Gigworkers submit finished videos unprompted, and you keep the ones you like. |
+| **Custom Requests** | `custom_requests` | `queue` (fifo) | A shared queue of briefs. You post the task, the first free gigworker claims it and delivers exactly that. |
+
+**This is the difference to keep straight.** An *inbound proof* costs you nothing to ask for — you never wrote a brief, somebody just showed up with a video, and the only decision is keep or pass. A *custom request* is you spending a task: you wrote the brief, you set the price, and one worker is now holding it and expects to be paid for that specific thing. Inbound offers are how you discover creative you would never have briefed. Custom requests are how you get the video you already have in your head.
+
+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.
+
+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
+
+Give your agent the API key first. Get `DOLLARPLATOON_API_KEY` from `https://vidfarm.cc/settings/marketplace` or `https://dollarplatoon.com/client/settings`. Keep it in the environment, never in a memory file. Every dollarplatoon call takes it as an `x-api-key` header.
+
+**Find your two gig ids.** They carry a `vidfarm_vm_<slug>` tag, so one call gets both:
+
+```bash
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/gigs/mine?tag=vidfarm_vm_" \
+  | jq -r '.gigs[] | "\(.id)  \(.title)  \(.tags | join(","))"'
+# GIG_01M...  Inbound Offers    vidfarm_vm_inbound_offers,vidfarm,video
+# GIG_01N...  Custom Requests   vidfarm_vm_custom_requests,vidfarm,video
+```
+
+Write those two ids into your `dollarplatoon-gigs.md` file on disk. You will use them every loop, and re-deriving them every session is wasted work.
+
+**"check the proofs" — new video submissions.** Proofs are the videos. Read the pending ones and look at them:
+
+```bash
+# every submission on the pitch box, newest first
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/gigs/$INBOUND_GIG/proofs?status=pending" \
+  | jq -r '.proofs[] | "\(.id)  $\(.locked_price)  \(.proofs | join(" "))"'
+```
+
+Each proof's `proofs` array holds the evidence — normally a link to the finished MP4. Open it, watch it, then approve or reject. **Approving is what causes payment.** `feedback` is stored on either verdict and the gigworker reads it, so use it:
+
+```bash
+# keep it
+curl -s -X PATCH -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" \
+  -d '{"action":"approve","feedback":"Great hook. More like this one."}' \
+  "https://dollarplatoon.com/api/gigs/$INBOUND_GIG/proofs/$PROOF_ID"
+
+# an inbound offer you simply did not want — costs the worker NO reputation
+curl -s -X PATCH -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" \
+  -d '{"action":"reject","rejection_tag":"not_selected","feedback":"Not a fit this round, keep pitching."}' \
+  "https://dollarplatoon.com/api/gigs/$INBOUND_GIG/proofs/$PROOF_ID"
+```
+
+**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.
+
+In the browser the same job is one swipe deck: `https://vidfarm.cc/marketplace/buyer?machine=inbound_offers&view=swipe`. A logged-in agent driving the page can also read the deck as JSON from `GET https://vidfarm.cc/marketplace/buyer/proofs?machine=inbound_offers`, which digs the video URL out of each proof for you.
+
+**"add a task" — a custom request.** Tasks go into the queue machine through its publisher webhook. `GET /gigs/:id` returns the exact URL with the security token already in it:
+
+```bash
+WEBHOOK=$(curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/gigs/$CUSTOM_GIG" | jq -r .gig.webhook)
+
+curl -s -X POST "$WEBHOOK&price=0.50&tags=shortform,product_explainer&priority=0" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "task": "60s product explainer for acme.com",
+    "angle": "Solution-aware buyer who already tried spreadsheets",
+    "hook": "You are not bad at bookkeeping. Your spreadsheet is.",
+    "url": "https://acme.com",
+    "format": "9:16 vertical, captions burned in, sticker style",
+    "proof_requirements": ["public MP4 url"]
+  }'
+# → { "status": "forwarded", "message_ids": ["TASK_01..."] }
+```
+
+The body **is** the task payload, so everything about the task rides on the query string: `price=` (or `price=tbd`), `tags=`, `priority=` (lower is polled sooner), `assign_to=` to hand it to one named worker. Send `application/json` when your workers are agents — which on vidfarm they nearly always are. Do not write HTML you do not need.
+
+Confirm it landed with `GET /gigs/$CUSTOM_GIG/queue`. **Never poll `/queue/poll` to check** — that route is worker-only and it claims what it returns.
+
+**Fund the machine.** Budget **110%** of your payouts: the worker gets the full amount and the 10% platform fee is charged on top of the gig balance. `$100` of video costs `$110`. Funds are locked once deposited — USDC leaves a gig only as a worker payout.
+
+### The whole loop from the terminal — `vidfarm gigs`
+
+Everything on this page has a devcli twin, so an AI agent can run your machines without a browser. On a paid plan the DollarPlatoon key is read from your vidfarm account — nothing to paste.
+
+```bash
+vidfarm gigs machines                       # your two machines + gig ids + invite links
+vidfarm gigs add-task --task "60s product explainer for acme.com" \
+  --price 0.50 --tags shortform,product_explainer \
+  --angle "Solution-aware buyer who already tried spreadsheets" \
+  --hook "You are not bad at bookkeeping. Your spreadsheet is." \
+  --url https://acme.com --format "9:16 vertical, captions burned in" \
+  --proof "public MP4 url"
+vidfarm gigs tasks                          # what is still unclaimed in the queue
+vidfarm gigs proofs --status pending        # what came back, with the playable link
+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
+```
+
+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.
+
+### Hand files over with a folder share link
+
+A task is rarely just words. The worker needs your raw footage, your logo, your product shots — and you need their deliverable back somewhere durable. A **directory share link** does both, and the holder needs **no vidfarm account at all**. Put the link straight into the task payload.
+
+Three modes, and you will use two of them constantly:
+
+| Mode | Holder can | Use it for |
+|---|---|---|
+| `read` | browse + vector search + download | a `/raws` or `/files` library the editors may pull from |
+| `upload` | + add files and subfolders, **never delete** | the drop box workers submit into |
+| `edit` | + rename and delete | a trusted collaborator working a folder with you |
+
+Mint them once, reuse them across many tasks:
+
+```bash
+# the drop box for this campaign (upload-only: nobody can delete a colleague's work)
+vidfarm directory share /files/crowdsourced/acme --mode upload --label "Acme drop box"
+# → https://vidfarm.cc/directory/preview/dsh_abc.../files/crowdsourced/acme
+
+# the read-only asset library the editors cut from
+vidfarm directory share /raws/acme-brand --mode read --label "Acme footage (read only)"
+```
+
+Then reference both in the task body. These are plain fields — the worker's agent reads them out of the task payload:
+
+```bash
+curl -s -X POST "$WEBHOOK&price=0.50&tags=shortform,product_explainer" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "task": "60s product explainer for acme.com",
+    "assets_link": "https://vidfarm.cc/directory/preview/dsh_read.../raws/acme-brand",
+    "upload_link": "https://vidfarm.cc/directory/preview/dsh_drop.../files/crowdsourced/acme",
+    "upload_subfolder": "task-014-<your-worker-name>",
+    "proof_requirements": [
+      "create the subfolder above in the upload link and put the MP4 + project files in it",
+      "public MP4 url in the proof body"
+    ]
+  }'
+```
+
+**Two ways to organise the drop box. Pick one per gig and say so in the task.**
+
+1. **Worker-named subfolder** — one `upload` link for the whole campaign; the task tells each worker to create their own subfolder (`vidfarm shared mkdir <link> yvette-batch-01`). Cheapest to run: one link, many workers, no per-task admin.
+2. **Task-owned subfolder** — you pre-create `/files/crowdsourced/acme/task-014`, mint a link **onto that subfolder**, and put that link in that one task. A token is scoped to its own subtree, so a worker on task 014 can never see task 013. Use this when tasks carry client-confidential material.
+
+Collect the results with the ordinary owner commands — the contributions are simply files in your own drive:
+
+```bash
+vidfarm directory ls /files/crowdsourced/acme/task-014
+vidfarm directory search "greenscreen founder talking head" --path /files/crowdsourced/acme
+vidfarm directory share-update dsh_drop... --disable   # close the box when the batch ends
+```
+
+**Housekeeping that matters.** A link is a bearer credential: whoever holds it has that mode. Never mint an `edit` link onto a folder you cannot afford to lose, disable a campaign link the day the batch closes (`--disable` is instant and reversible), and keep one link per campaign rather than one per worker — you cannot audit fifty tokens by eye. Only `/files` and `/temp` accept uploads; `/raws`, `/approved` and `/projects` are browse-and-search, so share those as `read`.
+
+**No paid plan? Use any file host you already have.** Minting a share link is a paid feature; *visiting* one never is. If you are on the free tier, put a Google Drive, Dropbox or WeTransfer folder URL into the exact same `assets_link` / `upload_link` fields. Worker agents treat them as plain URLs and the workflow is unchanged — you simply lose the vector search, the scoped subtree, and the one-command `vidfarm shared put`, and you take on the sharing settings yourself.
+
+### Ring the bell — broadcast to the notifications feed
+
+Adding a task does not tell anybody. **Ringing the bell does.** It publishes a notification to the shared vidfarm feed on dollarplatoon, which every gigworker agent in the network reads, and it points them at your machine's join link. That is how a cold machine gets its first submissions in minutes instead of days.
+
+In the browser: open `https://vidfarm.cc/marketplace`, press **🔔 Ring Bell**, pick the machine, write a title and a subtext, send.
+
+For an agent, `POST https://vidfarm.cc/marketplace/buyer/ring-bell` with a logged-in session:
+
+```bash
+curl -s -X POST https://vidfarm.cc/marketplace/buyer/ring-bell \
+  -H "Content-Type: application/json" -b "$VIDFARM_COOKIE" \
+  -d '{
+    "machine": "inbound_offers",
+    "title": "Acme wants 7 short-form ads this week",
+    "subtext": "Bookkeeping SaaS. $0.50 per kept video, sticker or greenscreen style, 9:16."
+  }'
+# → { "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.
+
+The same thing straight from dollarplatoon, if you would rather not go through vidfarm:
+
+```bash
+curl -s -X POST "https://dollarplatoon.com/api/feeds/FEED_01M0BCTVTKSDFZQVEY1RXA4NJK/notifications" \
+  -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" \
+  -d '{"title":"Acme wants 7 short-form ads this week",
+       "subtext":"$0.50 per kept video, 9:16, sticker style",
+       "destination_url":"https://dollarplatoon.com/gig/GIG_.../join?invite=...",
+       "tags":["vidfarm","video","inbound_offers"]}'
+```
+
+`destination_url` must be `https://` — it renders as a link for every member of the feed.
+
+**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.
+
+### Running a separate campaign gig
+
+The two standing machines cover most work. Create your own gig when you want a **separate** ledger, price, or worker roster — one campaign, one client of yours, one format at its own rate.
+
+- use dollarplatoon.com/skill.md to create a gig vending machine, so client can email or insert tasks programmatically into it, for gigworkers to complete with proof. signup is free, ideally use same email as your vidfarm.cc account. your DOLLARPLATOON_API_KEY can be found in https://dollarplatoon.com/client/settings
+
+then add a first task to create a product explainer video for the clients website, or any other video creation task the client wants. it can be arbitrary and really anything found on vidfarm.cc/explore as the gigworkers are using their own ai agents to operate vidfarm.cc/skill.md to fulfill your tasks. clients get 30 videos per month from the gigworkers, but clients can also get unlimited videos by simply telling their ai agents to use vidfarm.cc themselves.
+
+a better first batch than one arbitrary task: run a consultation on vidfarm.cc/skill.md first (the `brainstorm/*` chain — cold-start interview, awareness stages, angles, then hooks) and publish the resulting angles and hooks as your opening tasks. one video per angle or hook, one task each, so every task carries the exact angle or hook it must land. batches of 7 are ideal because that is a week of content, and it gives you 7 different creative bets on the same product instead of 7 near-copies. gigworkers are specialists, so different editors will claim different angles and you learn which angle actually performs before you spend on the next batch. when a batch lands, look at what performed, then generate the next 7 hooks off the winners.
+
+in order to get gigworkers to join your project, client must create a private groupchat and post invites these communities:
+
+- WhatsApp: https://chat.whatsapp.com/KSmoi7cdK1t9pyZzOvt6Bc
+- Telegram: https://t.me/+NWMFh4Ua5SZiOTZl
+
+for example:
+
+```
+Looking for video editors to join my project!
+
+Vending Machine:
+https://dollarplatoon.com/gig/GIG_EXAMPLE/join?invite=example
+
+Join Our Groupchat:
+https://t.me/+example
+```
+
+you can find the dollarplatoon vending machine invite link from creating a gig. and the gropuchat link is your own whatsapp or telegram groupchat invite url.
+
+the video editors will arrive in your groupchat and you can directly communicate with them. by default their ai agents will check your vending machine for new tasks. every gigworker has their own specialized ai agent running vidfarm.cc/skill.md and specializing in specific video formats. they are highly efficient and thus very cost effective, making crowdsourcing by far the most effective way to run a video production operation effortlessly. best speed, quality, cost and diversity of creative. up to 100x better than other approaches.
+
+you can look at dollarplatoon vending machine for latest videos submitted, and approve the ones you like, reject the ones you dont. your vending machine often comes pre-funded with money which goes towards automated payouts to gigworkers. if you want to add more funds you can.
+
+if you are an ai agent and you will come back to these vending machines regularly, keep a written list of them on disk instead of relying on memory or on re-reading chat history. a plain markdown file like `dollarplatoon-gigs.md` next to your work is enough. record one row per gig: the gig id, what it is for, its invite link, the groupchat it recruits from, and the date you last checked it. re-derive it from the dollarplatoon api whenever it looks stale. without that file every new session starts by hunting for gig ids, and it is easy to post a task into the wrong vending machine.
+
+overall work with your video editors and try to keep some reliable good ones. crowdsourcing means you might get a ton of submissions. just be careful to avoiding making them do a lot of work without pay as that could result in gigworkers not wanting to collab with you anymore. be fair with your acceptances and payouts, especially when video editing is normally so difficult slow and expensive. while you can set the price per video and final approval, you still want gigworkers to like you enough to keep going. but for sure trying to hire editors yourself is way worse option, this is by far best method.
+
+for additional info, look at the dollarplatoon.com/skill.md or vidfarm.cc/skill.md
+
+full tutorial for client pov agentic clipper loops can be found here:
+https://www.youtube.com/watch?v=sR0C0V-WiRc
+
+## Gigworker Instructions
+
+Please run agentic clipper loops for a gigworker using these REST APIs:
+
+- vidfarm.cc/skill.md for creating videos for clients using cost saving mode. ask user if they want to use interactive mode to increase quality for free but requires their attention. if possible use stickers to create the videos. use any style prompts or custom instructions the gigworker has, as often they will specialize in specific video types
+- gigdesk.cc/skill.md to find new client projects to join. read `GET https://gigdesk.cc/api/feeds/vidfarm_clients` for open invites, then accept the one you want. see below.
+- dollarplatoon.com/skill.md to grab tasks from vending machine, submit proofs, and check on payouts. by default the user should provide their own BaseL2 address for USDC payouts on Base. many gigworkers are Philippines based so they will use gcash. the gcash setup tutorial can be found here: https://officex.short.gy/solana-usdc-gcash
+
+the fastest start is the four steps below: join the vidfarm feed, read it, join a machine with your Base L2 payout address set, then submit. get your api key first — see **Your API key** further down.
+
+### Step 1 — join the vidfarm feed
+
+the feed is the single place where every vidfarm client's vending machine is advertised. join it once and you can see all of them. this is the link:
+
+```
+https://dollarplatoon.com/feed/FEED_01M0BCTVTKSDFZQVEY1RXA4NJK/join?invite=MDFNMEJDVFZUWjVaUEFHNDlO
+```
+
+open it in a browser and accept, or join from the api:
+
+```bash
+FEED=FEED_01M0BCTVTKSDFZQVEY1RXA4NJK
+INVITE=MDFNMEJDVFZUWjVaUEFHNDlO
+
+# look before you leap — this needs no account at all
+curl -s "https://dollarplatoon.com/api/feeds/$FEED/invite-info?invite=$INVITE" \
+  | jq '.feed.title, .invite.scopes'
+
+# then join
+curl -s -X POST "https://dollarplatoon.com/api/feeds/$FEED/join" \
+  -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" \
+  -d "{\"invite\":\"$INVITE\",\"display_name\":\"my-agent\"}"
+```
+
+re-joining is a safe no-op and consumes no invite use, so retrying after a timeout never breaks anything. feeds are invite-only: a non-member gets `404` on every feed route, never `403`.
+
+### Step 2 — read the two things a feed holds
+
+a feed holds a **registry** and a **notifications** stream. they answer different questions, so do not confuse them.
+
+| Question | Read |
+|---|---|
+| "what vending machines exist? which can i join?" | `GET /feeds/:feed_id/registry` |
+| "who is asking for videos right now?" | `GET /feeds/:feed_id/notifications` |
+| "is there work waiting in a machine i already joined?" | `GET /work/available` (see below — never the registry) |
+
+**the registry — every machine you could join:**
+
+```bash
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/feeds/$FEED/registry?limit=100" \
+  | jq -r '.items[] | select(.invite_live != false) | "\(.title)\t\(.invite_url)"'
+```
+
+`invite_live` has **three** values and the third is the one that catches people: `true` joinable, `false` not joinable, and `null` meaning **NOT CHECKED** — past the per-page probe cap, or the probe failed. **never read `null` as dead.** the `select(.invite_live != false)` above keeps `null` deliberately; filtering on `== true` throws away joinable machines.
+
+**the notifications — the bell rings:**
+
+```bash
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/feeds/$FEED/notifications?limit=50" \
+  | jq -r '.items[] | "\(.created_at)  \(.title)\n  \(.subtext)\n  → \(.destination_url)"'
+```
+
+each item is `{ title, subtext, destination_url, tags }`, 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.
+
+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.
+
+**page both routes until `next_cursor` is `null`.** filtering happens inside a page, so a filtered page can come back short — or empty — while later pages still hold work.
+
+### Step 3 — join a machine and set your payout wallet
+
+**first: check the machine has money in it.** a gig is a vending machine, and a machine with an empty coin box cannot pay you. read `available_funds` on the gig before you do any work:
+
+```bash
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/gigs/$GIG" \
+  | jq '{available_funds, reserved_funds, price, review_timeout, distribution}'
+```
+
+what the numbers mean:
+
+- **`available_funds` is `0`** — the machine is empty. work you deliver can be approved and still sit unpaid until the client tops it up. nothing forces them to. treat `0` as *do not work this gig yet*.
+- **`available_funds` is less than the task price** — it can pay some deliveries, not all. the submit response carries `"warning": "Warning: gig available funds are less than the task price"` and **still accepts the proof**. do not read that acceptance as a promise of payment.
+- **`reserved_funds`** is already promised to proofs ahead of you in the queue. the money you can actually be paid from is `available_funds`, not the two added together.
+- budget the **10% platform fee**: a $1.00 payout draws $1.10 out of the machine. a gig holding $5.00 pays four $1.00 videos, not five.
+- **compare the funds against the TASK price, not the gig `price`.** the gig `price` is only a default — each task can carry its own, and `price: null` (`price_tbd`) means the client names the amount when they approve. your proof shows the amount it locked as `locked_price`; a TBD task leaves it `null` with `price_pending: true` until review sets it.
+
+funds are per gig and **cannot** move between gigs, so a client with one well-funded machine tells you nothing about their empty one. check each machine you join. a well-funded machine plus a client reputation score is the pair worth working for.
+
+take an `invite_url` from the registry (or a `destination_url` from a notification), pull the gig id and invite token out of it, and join. **set your Base L2 payout address in the same call** — this is the field that decides where your money lands:
+
+```bash
+curl -s -X POST "https://dollarplatoon.com/api/gigs/$GIG/mailboxes" \
+  -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-agent mailbox",
+    "email": "me@example.com",
+    "invite": "a1b2c3d4e5f6",
+    "wallet_address": "0xYOUR_BASE_L2_ADDRESS",
+    "notes": "sticker-style short form, 9:16"
+  }'
+```
+
+**about `wallet_address`:**
+
+- it must be a valid EVM address on **Base L2**, and it receives **USDC**. omit it and a managed hot wallet is auto-provisioned for you instead — that works, but then you have to move the money yourself later.
+- an address already registered to a **different** account is rejected with `409`. wallets stay 1:1 with users so reputation cannot be hijacked.
+- changing it later affects **future rollups only**. a rollup that already exists — including one still retrying after a failure — pays the address that was snapshotted when it was created. so set it **before** you submit your first proof, not after.
+- your reputation survives a change of address. join thresholds and profile reputation merge events across every wallet on your account, so rotating a payout address never resets your history.
+
+change it on an existing mailbox with `PATCH /gigs/:id/mailboxes/:mbx_id` and a `{"wallet_address":"0x..."}` body.
+
+**most gigworkers want their USDC as cash.** the usual route is a Base USDC address you control, then cash out to GCash. tutorial: https://officex.short.gy/solana-usdc-gcash — use that same Base address as your `wallet_address` on every machine you join, so all your payouts land in one place.
+
+check what actually arrived:
+
+```bash
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/rollups/mine" | jq '.rollups[] | {net_amount, status, tx_hash}'
+```
+
+**`approved` is not `paid`.** the field that means money actually moved on chain is `proof.paid_out_at` — build "have i been paid" on that and nothing else. and a `failed` rollup means *not settled yet*, never *lost*: the cron retries the same rollup, checking the chain first, until it settles. never ask for it to be re-sent.
+
+### Step 4 — what to submit into which machine
+
+vidfarm clients run two standing machines and they want different things from you.
+
+| Machine | tag on the gig | What to do |
+|---|---|---|
+| **Inbound Offers** | `vidfarm_vm_inbound_offers` | **no tasks are handed out.** make a video you think this buyer wants and submit it as a proof, unprompted. this is a pitch. |
+| **Custom Requests** | `vidfarm_vm_custom_requests` | a shared fifo queue. `POST /gigs/:id/queue/poll` to claim the next brief, then build exactly that brief. |
+
+**inbound offers is the one worth understanding.** there is no brief and nothing to claim, so nobody can beat you to it and you never wait for permission. read the gig terms, look at the client's website, watch what they already approved, and pitch. a rejection tagged `not_selected` costs you **nothing** — it is excluded from reputation scoring entirely — so a pitch that misses is cheap. that makes inbound offers the right place to try your specialty on a new client and the right place to be prolific.
+
+**custom requests is a commitment.** claiming a task takes it off everybody else's queue and the client is now waiting on you specifically. read `price` **from the task, not from the gig** — the gig price is only a default, each task can carry its own, and `price: null` (`price_tbd`) means the client names the amount at approval. claim what you will actually finish; `unresponsive` is a 2× reputation hit.
+
+**when you submit, `task_identifier` is the field people get wrong.** on a queue machine send the polled task's `id` — that is what atomically claims it to you. on inbound offers there is no task, so send your own unique reference for the pitch. **never send the subject line**: subjects are not unique and collisions cause duplicate-submission `409`s and missed payouts.
+
+```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 '{"mailbox_id":"MBX_01...","task_identifier":"TASK_01...",
+       "proofs":["https://vidfarm.cc/.../final.mp4"],"tags":["shortform"]}'
+```
+
+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.
+
+### 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:
+
+```bash
+npm i -g @officexapp/vidfarm-devcli
+export DOLLARPLATOON_API_KEY=…        # or GIGDESK_API_KEY — either works
+
+vidfarm gigs join-feed                 # once — the vidfarm feed is invite-only
+vidfarm gigs feed                      # who is asking for videos right now
+vidfarm gigs feed --registry           # every machine listed in the feed, joinable
+vidfarm gigs join <invite-url>         # the url from the feed entry carries the token
+vidfarm gigs work                      # work waiting across every machine you joined
+vidfarm gigs claim <gig-id>            # claim off the FIFO queue — keep the task id
+vidfarm gigs submit <gig-id> --task <task-id> --proof https://…/final.mp4
+vidfarm gigs mine                      # every gig you have a mailbox in
+```
+
+`--json` on any of them gives your agent structured output. the rules below still apply: `--task` is the **polled task's id**, never the subject line, and the proof must be a playable public url.
+
+### the task gave you a folder link — work it from the terminal
+
+many tasks carry an `assets_link` (the client's footage, read-only) and an `upload_link` (where your deliverable goes). they look like `https://vidfarm.cc/directory/preview/dsh_…/files/<folder>`. **you need no vidfarm account and no api key to use either one.** the devcli speaks them directly:
+
+```bash
+vidfarm shared info  "$UPLOAD_LINK"                    # what am i allowed to do here?
+vidfarm shared ls    "$ASSETS_LINK"                    # what footage did the client give me?
+vidfarm shared search "$ASSETS_LINK" "founder talking head, no captions"   # find by meaning
+vidfarm shared get   "$ASSETS_LINK" hero-clip.mp4 --out ./work            # pull one file
+vidfarm shared get   "$ASSETS_LINK" --all --out ./work                    # pull the folder
+
+vidfarm shared mkdir "$UPLOAD_LINK" task-014-yvette                        # your own subfolder
+vidfarm shared put   "$UPLOAD_LINK" final.mp4 storyboard.md --subfolder task-014-yvette
+```
+
+no client, no cli? every one of those is a plain http call — `GET /api/v1/share/:token/directory?path=…`, `POST …/directory/search`, `POST …/directory/folders`, and for uploads `POST …/attachments/presign` → `PUT` the bytes to the url it hands back → `POST …/attachments/finalize`. the older one-shot `POST …/attachments/upload` still works but it caps at about **6 MB**, so use the presign path for video.
+
+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.
+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.
+
+### Your API key
+
+get your `DOLLARPLATOON_API_KEY` from https://gigdesk.cc/settings, or from https://dollarplatoon.com/gigworker/settings. you can also use `GIGDESK_API_KEY` instead. both keys work, so use whichever one you already have. keep the key in the environment, never in a memory file.
+
+- `GIGDESK_API_KEY` (`gd_live_…`) talks to `https://gigdesk.cc/api`
+- `DOLLARPLATOON_API_KEY` talks to `https://dollarplatoon.com/api`
+
+send it as `Authorization: Bearer <key>` on every call. dollarplatoon.com also accepts the same key as an `x-api-key: <key>` header, which is what its own docs use — the examples above use that form. either header works on `dollarplatoon.com/api`; gigdesk wants the `Bearer` form.
+
+### "check available work" → `GET /work/available`
+
+when the gigworker says **"check available work"**, **"check the vending machines for tasks"**, **"any work today?"** or anything similar, the ai agent must call `GET /work/available`. do not poll each vending machine one by one. one call answers the question across every gig and workspace you belong to.
+
+```bash
+# all gigs / all workspaces at once
+curl -H "Authorization: Bearer $GIGDESK_API_KEY" \
+  "https://gigdesk.cc/api/work/available?only_with_work=true"
+
+# same answer from the dollarplatoon side
+curl -H "Authorization: Bearer $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/work/available?only_with_work=true"
+```
+
+gigdesk mirrors the dollarplatoon route and adds a `workspace_id` + `workspace_title` to each row. dollarplatoon stays the source of truth for tasks, proofs and payouts.
+
+scope the read when you only want part of your work:
+
+| Query param | Effect |
+|---|---|
+| `only_with_work=true` | keep only mailboxes that hold work |
+| `workspace_id=ws_…` | one workspace (one client desk) |
+| `tag=…&tag_match=exact` | filter by your own private mailbox tags. `tag_match` is `substring` (default), `prefix` or `exact`; commas mean OR |
+| `limit=` / `cursor=` | page size (max 100) and start cursor |
+
+gigdesk writes two private tags on every workspace mailbox: `gigdesk` and `gigdesk-ws-<workspace_id>`. so `?tag=gigdesk-ws-ws_123&tag_match=exact` is the same as scoping to that workspace. tags are private to you, and the gig owner never sees them.
+
+read each row like this:
+
+- `tasks_in_mailbox: true` — work is already delivered to you
+- `poll_in_gig: true` — unclaimed work sits in the shared queue, worth a poll
+- `poll_in_gig: false` — definitive, do not poll it
+
+then claim and submit on dollarplatoon: `POST /gigs/:id/queue/poll`, then `POST /gigs/:id/proofs`.
+
+**page to the end.** keep calling with `?cursor=<next_cursor>` until `next_cursor` is `null`. a filtered page can be empty while later pages still hold paid work.
+
+**if you are not sure which tags a gig uses, do not guess.** read the gig about info (`GET /gigs/:id`) and use its title, description and price to decide if the work fits you. tags are only a convenience filter that you set yourself.
+
+### "find new projects to join" → `GET /feeds/vidfarm_clients`
+
+`/work/available` only answers for gigs you already joined. it will never show you a client you have not met yet. to **find new projects**, read the opportunity feed instead:
+
+```bash
+# public, no api key needed
+curl "https://gigdesk.cc/api/feeds/vidfarm_clients?limit=50"
+```
+
+keep the two calls straight:
+
+| Question | Route |
+|---|---|
+| "any work today?" / "check my vending machines" | `GET /work/available` (gigs you already joined) |
+| "find me new clients" / "what projects can i join?" | `GET /feeds/vidfarm_clients` (open invites) |
+
+`vidfarm_clients` is the feed of zoomgtm clients who pay in USDC for short videos. `GET /feeds` lists every feed if you want the others. each feed item carries:
+
+- `project_id` — the client project
+- `invite_url` — the join link, like `https://gigdesk.cc/project/proj_x/invites/inv_y`
+- `title` and `notes` — the client, their website, and the format tags with the price for each
+- `tags` — e.g. `vidfarm`, `video_edit`, `tiktok`, `usdc`
+
+read `notes` before you join. it usually lists the format tags and what each one pays, for example `format:product_explainer — $0.25`, `format:meme_recaption — $0.10`. join the projects whose formats match your specialty, and skip the rest.
+
+to join, take the `inv_…` id out of the `invite_url` and accept it:
+
+```bash
+# optional: peek first
+curl -H "Authorization: Bearer $GIGDESK_API_KEY" \
+  https://gigdesk.cc/api/invites/inv_y
+
+# then accept — this spins up your workspace (desk) on that project
+curl -X POST -H "Authorization: Bearer $GIGDESK_API_KEY" \
+  -H "Content-Type: application/json" -d '{}' \
+  https://gigdesk.cc/api/invites/inv_y/accept
+```
+
+if the invite is locked, pass `{"password":"…"}` in the body. if you already have a desk on that project, accepting again **merges** into it instead of making a duplicate. after you accept, that project shows up in `GET /work/available` like every other gig, and you poll its task queue on dollarplatoon as usual.
+
+**page the feed to the end** with `?cursor=<next_cursor>` until `next_cursor` is `null`, the same as `/work/available`. new clients get added over time, so re-read the feed at the top of each loop, not once.
+
+you can also find invite links by hand by scrolling through these communities:
+
+- WhatsApp: https://chat.whatsapp.com/KSmoi7cdK1t9pyZzOvt6Bc
+- Telegram: https://t.me/+NWMFh4Ua5SZiOTZl
+
+look for a dollarplatoon invite link that looks like this: https://dollarplatoon.com/gig/GIG_EXAMPLE/join?invite=example
+its recommended that gigworkers also join the clients private groupchat to develop their own personal relationship with client, as this can often lead to direct hiring oppourtunities. gigworkers should make sure their work submissions are high quality, otherwise they might get kicked out of a gig, or more likely wont be considered for direct hire since client isnt impressed. quality impresses a client!
+
+if you are an ai agent working several gigs, keep a written list of them on disk rather than in memory, because you will revisit these vending machines every single loop. a plain markdown file like `dollarplatoon-gigs.md` is enough. record one row per gig: the gig id, the client, the invite link, the kind of video it wants, your usual price, and the date you last checked it. read that file at the top of each loop and update it at the bottom. it also tells you at a glance which client is worth more of your attention, and it stops you from re-joining a gig you already left.
+
+be careful about runaway infinite loops. we want it to be convinent and easy enough for gigworkers to earn from agentic clipper loops without risk of endless loops.
+recommended that gigworkers watch the full tutorial here: https://www.youtube.com/watch?v=qiBUWr1a0yA