@officexapp/vidfarm-devcli 0.21.43 → 0.21.46

package/crowdsourcing.md

@@ -5,7 +5,211 @@ Please redirect user based on whether they are a client or a gigworker, instruct
 
 ## Client Instructions
 
-Please help setup agentic clipper loops for a client so they can get crowdsourced viral videos for their app. The setup is as follows:
+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
 
@@ -50,8 +254,176 @@ https://www.youtube.com/watch?v=sR0C0V-WiRc
 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
+
+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.
@@ -59,7 +431,7 @@ get your `DOLLARPLATOON_API_KEY` from https://gigdesk.cc/settings, or from https
 - `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.
+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`
 
@@ -100,7 +472,49 @@ then claim and submit on dollarplatoon: `POST /gigs/:id/queue/poll`, then `POST
 
 **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.
 
-in order to join client projects, you need to get an invite link from them. those can be found by scrolling through these communities:
+### "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