@officexapp/vidfarm-devcli 0.21.55 → 0.21.57

package/marketplace.md

@@ -25,8 +25,50 @@ that file is what they are asking for. It is not a synonym for "a person who edi
 the machines, the proof rules, the payout rules. The harness tells you *what loop to run*; this file
 tells you *what each call does*. Read the harness for your side first, then use this as the manual.
 
+### "help me earn on vidfarm" — that phrasing already answered the question
+
+**Any ask about EARNING is the clipper side. Do not ask the disambiguating question — you have your
+answer.** These all mean *Agentic Clipper*, and they are the most common way a human opens this
+document:
+
+- *"help me earn on vidfarm marketplace.md"* · *"help me make money on vidfarm"*
+- *"I want to get paid to make videos"* · *"find me video gigs"* · *"any work today?"*
+- *"run in agentic clipper mode"* · *"start the clipper loop"*
+- *"check the vending machines"* · *"is there work I can claim?"*
+
+Load **`https://vidfarm.cc/agentic-clipper.md`** and run the loop there. Then do these four moves,
+in this order, and report back with what you found. Each one is spelled out in
+**Gigworker Instructions** below.
+
+| # | The move | The call | With the devcli | What it answers |
+|---|---|---|---|---|
+| 1 | **Read the feed's recent notifications** | `GET /feeds/$FEED/notifications?limit=50` | `vidfarm gigs feed` | *who is asking for videos RIGHT NOW.* The highest-signal thing in the network — a bell that just rang means an owner is sitting there reviewing |
+| 2 | **Check the gig behind each join link for money** | pull the `GIG_…` id out of the notification's `destination_url`, then `GET /gigs/$GIG` and read `available_funds` | `vidfarm gigs check <gig\|join-url>` | *can this machine actually pay me?* `available_funds: 0` = do not work it, whatever the brief says |
+| 3 | **Join the funded ones** — with your payout wallet set in the same call | `POST /gigs/$GIG/mailboxes` with `invite` + `wallet_address` | `vidfarm gigs join <url> --wallet 0x…` | you now have a mailbox on that machine and can be paid |
+| 4 | **Poll for tasks** | `GET /work/available?only_with_work=true` across every machine, then `POST /gigs/$GIG/queue/poll` to claim one | `vidfarm gigs work` → `vidfarm gigs claim` | *what can I build today* |
+
+> **All four in one command: `vidfarm gigs earn`.** It joins the feed if needed, reads every bell,
+> checks all of those machines for money in parallel, and prints them **best-payer-first** with the
+> join command on each row — then lists the work already waiting in machines you joined. Start
+> there, then use the table above when you want a move on its own.
+
+> **Then ask ONE question before you build anything: how much of the gigworker's attention does each
+> task get?** That is the **run mode**, and there are four — full interactive, quick interactive, full
+> auto with batch review, and full auto with auto-submit. They change which stages stop for the human
+> and nothing else. `vidfarm clipper-run mode` explains all four and saves the answer. The full
+> section is **The four run modes** under *Gigworker Instructions* below.
+
+**Move 1 before move 2, always.** The notifications feed is a recency stream: it tells you which of
+the hundreds of machines has a human paying attention this week. Working a quiet machine is how a
+clipper spends an afternoon on a video nobody reviews.
+
+**Move 2 before move 3, always.** Joining is free and reversible; an hour of editing is not. A gig is
+a vending machine, and a machine with an empty coin box cannot pay you — approval does not create
+money. Read `available_funds` **before** you commit, never after you deliver.
+
 **Cannot tell which side?** Ask one question: *"Do you want videos made for you, or do you want to
-get paid to make videos for other people?"* Do not guess — guessing wrong costs someone money.
+get paid to make videos for other people?"* Do not guess — guessing wrong costs someone money. But
+if they said *earn*, *get paid*, *make money*, or *find work*, they answered it already.
 
 **A note on formats.** Neither side invents a video format from scratch. Vidfarm publishes format
 harnesses — the written apparatus that reproduces one format well — and the live index is
@@ -35,6 +77,32 @@ identifies the format, and follows the harness that matches it. Details in each
 Every one of them also ships inside the CLI — `vidfarm harness list`, then `vidfarm harness show
 <name>` — so a clipper with no network still reads the full contract by name.
 
+**A note on WHICH MODEL is reading this, which matters more than most agents expect.** The format
+harnesses above are written to be *authored from* — 300 lines of prose to a rendered composition in
+one held-in-mind pass. That works on a frontier agent and reliably fails below one. Most gigworkers
+on this marketplace run **Google Antigravity**, which is a weak-tier model attached to a full media
+suite, so this is the common case, not the edge case.
+
+> **If you are Gemini Flash, DeepSeek, Kimi, GLM, MiniMax, Grok, Qwen, Llama, any "-mini" /
+> "-lite" / "-turbo" / distilled tier — or you cannot name your own model — read
+> `https://vidfarm.cc/flash-harness.md` before you build anything.** Unsure resolves to *weak*,
+> deliberately.
+>
+> It replaces authoring with **adapting**: fork an already-decomposed template off
+> `https://vidfarm.cc/discover`, derive its viral and visual DNA, procure every raw, and transplant
+> the client's story into it. Somebody already paid a frontier model to take that video apart —
+> take the parts. Output quality goes **up**, and overfitting to one template is the correct
+> outcome, because the variety a buyer sees comes from picking a different template next time.
+>
+> The flash harness does not replace the format harness. It **wraps** it: you still read the format
+> harness, but as a grading rubric rather than as build instructions.
+
+Also in that file, and worth answering once whichever tier you are: **does your own agent
+subscription already include image, TTS and STT generation?** Antigravity, Gemini CLI and OpenAI
+Codex do; Claude Code does not. If it does, that generation costs Vidfarm $0 and the provider $0
+extra, so it is **allowed inside `$0` cost-saving mode with no permission ask** — a clipper on
+Antigravity gets custom art and a custom voiceover while still honestly reporting $0.
+
 ## Get the key over REST (no copy-paste)
 
 **Read this first. It is the fastest way onto the marketplace, and it works on every plan.**
@@ -225,6 +293,34 @@ over its own specialty. Pick from the live index at `https://vidfarm.cc/experime
 base (`short-form`, `hooks`, `ugc-testimonial`, `explainer`, `product-demo`, `product-explainer`).
 Leave it out only when you genuinely do not care which format you get.
 
+**`reference_template_id` is the field that most changes the RELIABILITY of what comes back — and
+almost nobody sets it.** Most clippers run weak models (Antigravity, Gemini Flash, DeepSeek, GLM),
+and a weak model told to author a format from a written description produces something you will
+reject. The same model handed a *decomposed template to adapt* produces something you will keep. So
+find one yourself and name it:
+
+```bash
+vidfarm discover --query "<your product's problem, in your customers' words>" --limit 20 --json
+# keep the rows carrying `summary` + `keywords` + `promotions` — those are already decomposed
+```
+
+```jsonc
+{
+  "task": "60s product explainer for acme.com",
+  "format_harness": "https://vidfarm.cc/experimental/unique-product-explainers.md",
+  "reference_template_id": "template_019fd6b0…",   // ← adapt THIS, do not invent
+  "reference_note": "keep the beat count and the caption style; replace every word and every shot"
+}
+```
+
+A clipper's agent reads those out of the task payload the same way it reads `assets_link`. A weak
+model is then instructed to fork your reference, derive its viral and visual DNA, and transplant
+your product into it — the loop in `https://vidfarm.cc/flash-harness.md`. **Overfitting to your
+reference is the intended outcome, not a defect.** Your creative variety comes from naming a
+*different* reference on the next task, which is something you control; it does not come from a
+small model improvising, which is something nobody controls. Want seven different bets this week?
+Name seven different reference templates.
+
 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.
@@ -254,6 +350,26 @@ vidfarm gigs ring-bell --title "Acme wants 7 short-form ads this week" \
 
 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.
 
+**`add-task` has no flag for `format_harness` or `reference_template_id` — use `--body`.** Those two
+fields are the ones that decide what a weak-model clipper hands back, so do not drop them just
+because there is no flag:
+
+```bash
+cat > task-014.json <<'JSON'
+{
+  "task": "60s product explainer for acme.com",
+  "format_harness": "https://vidfarm.cc/experimental/unique-product-explainers.md",
+  "reference_template_id": "template_019fd6b0…",
+  "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_requirements": ["public MP4 url"]
+}
+JSON
+vidfarm gigs add-task --body task-014.json --price 0.50 --tags shortform,product_explainer
+```
+
 ### 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.
@@ -416,9 +532,215 @@ being paid, picks work it can actually deliver, hands each task to a **fresh sub
 proof itself, and keeps the earnings ledger on disk. The orchestrator never renders a video and a
 subagent never touches money. That separation is the harness.
 
-**Routing a task to a format.** Before building anything, the clipper decides what kind of video the
-task is, then follows the matching format harness from the live index at
-`https://vidfarm.cc/experimental`:
+**The gigworker reviews every video before it is submitted. Auto-submit is OFF by default.** A
+finished cut goes to the human who runs the loop, and it waits there until they approve it. A buyer
+who rejects a proof as `low_quality` scores that against the gigworker's wallet, and buyers read
+that score on the public profile before they pick whose pitch to take — so one weak video lowers
+every future payday, and a run of approved ones raises it. Turn auto-submit on **only when the
+gigworker explicitly asks for it**, keep it as narrow as they asked, and switch it back off after
+any rejection. Never enable it to save time. The full gate is step ⑥½ in
+`https://vidfarm.cc/agentic-clipper.md`.
+
+### The four run modes — ASK FOR ONE BEFORE THE FIRST TASK
+
+**A clipper loop is not one loop. It is four, and they differ in exactly one thing: which stages stop
+for the gigworker.** Everything else — the machines, the harnesses, the proofs, the payouts — is
+identical. Pick the mode with the human, out loud, before you claim anything, and write it down:
+
+```bash
+vidfarm clipper-run mode                      # explains all four, says which one is set
+vidfarm clipper-run mode quick-interactive    # save the answer into CLIPPER/run.json + MISSION.md
+```
+
+| Mode | Stops at | Who picks the template | Use it when |
+|---|---|---|---|
+| **full interactive** | shortlist · plan · raws · cut | the **gigworker**, off a shortlist | the model is weak and the buyer is new. Four cheap moments of human taste, and the output stops looking like a weak model made it |
+| **quick interactive** | shortlist · cut | the **gigworker**, off a shortlist | **the common one.** One decision before the work, one look after it, and nothing in between |
+| **full auto + batch review** | cut | the **agent** | **the other common one.** Run a batch overnight, review all of it in one sitting in the morning, submit what survives |
+| **full auto + auto-submit** | nothing | the **agent** | the gigworker explicitly asked for an unattended loop, in their own words, and accepts that every rejection lands on their public trust score |
+
+**Quick interactive and full auto + batch review are the two that get used.** Full interactive is the
+rescue mode for a weak model on an unfamiliar buyer; auto-submit is the narrow opt-in.
+
+**The template pick is the highest-leverage human moment in the whole loop, which is why three of the
+four modes put a stop there.** A weak model told to author a format from prose hands back something a
+buyer rejects; the same model handed a *decomposed template to adapt* hands back something they keep
+(that is the whole argument of `https://vidfarm.cc/flash-harness.md`). A gigworker can watch three
+candidate templates in ninety seconds and know which one fits the brief. Ninety seconds of a human
+beats an hour of a weak model guessing.
+
+#### Full interactive — the four stops, in order
+
+Use it when the model is weak, the buyer is new, or the last cut was rejected.
+
+```bash
+vidfarm clipper-run mode full-interactive
+vidfarm gigs claim $GIG                                     # keep the task id
+vidfarm clipper-run start $TASK --gig $GIG --price 0.50 \
+  --title "60s product explainer for acme.com" \
+  --harness https://vidfarm.cc/experimental/unique-product-explainers.md
+```
+
+1. **Shortlist, then STOP.** Find template ids that already do what this task is asking for, and say
+   why each one fits. Then hand them to the gigworker and wait.
+
+   ```bash
+   vidfarm discover --query "<the buyer's problem, in their customers' words>" --limit 20 --json
+   #   keep the rows carrying `summary` + `keywords` + `promotions` — those are already decomposed
+   vidfarm clipper-run shortlist $TASK \
+     --template template_019fd6b0… --why "same beat count, captions carry the whole story" \
+     --template template_019a41c2… --why "greenscreen react, matches their founder footage"
+   ```
+
+   Show the gigworker the videos, not just the ids — `https://vidfarm.cc/template/<template_id>`.
+   They answer with `vidfarm clipper-run pick $TASK <template_id>`, or "you pick".
+
+2. **Write the plan, then STOP.** Fork their choice, derive its DNA, and write the beats down before
+   you build anything.
+
+   ```bash
+   vidfarm fork <template_id> && vidfarm pull <forkId> --dir ./work
+   vidfarm harness derive <forkId> --out ./work/HARNESS.md    # viral DNA + visual DNA
+   #   …write ./work/STORYBOARD.md: the beats, the words, the shot per beat, the audio per beat
+   vidfarm clipper-run plan $TASK --file ./work/STORYBOARD.md
+   ```
+
+   The gigworker reads it and answers `approve`, or `changes --note "…"`. A plan is ten seconds to
+   read and an hour to un-render, so this stop is the cheapest one in the file.
+
+3. **Open the raws folder, then STOP.** Procure everything you can yourself first — the buyer's
+   shared folder → their website (`vidfarm capture`) → the free public raws catalog → free stock →
+   IconScout → your own subscription's generator → billed, last. Then offer the folder.
+
+   ```bash
+   vidfarm clipper-run raws $TASK        # prints (and creates) this task's local raws folder
+   #   → CLIPPER/tasks/<task-id>/raws
+   ```
+
+   Hand the gigworker that path. If they want to help, they drop clips into it and approve; a human
+   eye picks better footage than any keyword scan and it costs $0. If they say "go", approve it on
+   their word and source the rest yourself — helping is **optional**, and this stop is an offer, not
+   a demand.
+
+4. **Build, render, QA — then STOP for the review.**
+
+   ```bash
+   #   storyboard the scene with hyperframes when the shot is hard to picture; otherwise go
+   #   straight to the build. Both are correct — a storyboard is for when it earns its cost.
+   vidfarm lint && vidfarm render && vidfarm qa ./work --harness <the harness>
+   vidfarm clipper-run cut $TASK --file ./final-watermarked.mp4 --clean-master ./final-clean.mp4
+   ```
+
+   Then the review gate below, and only then the submit.
+
+#### Quick interactive — one decision in, one look out
+
+The gigworker approves **one template_id** off your shortlist and then leaves. You plan, procure,
+build, render and QA the whole task alone from that starting point, and you stop again only when the
+cut is finished.
+
+```bash
+vidfarm clipper-run mode quick-interactive
+# …start · shortlist · (gigworker picks) · plan · raws · cut — no stop at plan or raws
+vidfarm clipper-run next          # ← the one command that tells you what to do right now
+```
+
+Everything else is identical to full interactive; the `plan` and `raws` steps still happen and are
+still recorded, they just do not wait for anybody.
+
+#### Full auto + batch review — build the batch, review it in one sitting
+
+You pick the template too, and you run every task end to end. **You submit nothing.** Each finished
+cut parks in the review queue and the gigworker works through them together.
+
+```bash
+vidfarm clipper-run mode auto-batch
+#   …per task: start · shortlist · pick · plan · raws · cut
+vidfarm clipper-run review        # every cut waiting, with the file path to watch
+#   the gigworker answers, per task:
+vidfarm clipper-run approve $TASK
+vidfarm clipper-run changes $TASK --note "hook is dead, re-cut the first 3 seconds"
+vidfarm clipper-run drop    $TASK --reason "wrong buyer entirely"
+```
+
+Batching the review is the point: watching six cuts back to back takes a gigworker ten minutes, and
+they judge them better against each other than one at a time.
+
+#### Full auto + auto-submit — unattended, and narrow
+
+No stops anywhere: you pick, you build, you submit your own proofs. **Only the gigworker may choose
+this, in their own words** ("submit automatically", "you don't need to check with me"). Then:
+
+- record the date and their exact words next to `run_mode:` in `MISSION.md`;
+- keep it as narrow as they made it — one machine is not every machine, one task is not the mission;
+- state the trade once: faster, and every rejection lands on their public trust score with nobody in
+  between;
+- **revert to `auto-batch` on the first rejection**, on a new machine, or on a new format harness.
+
+You never turn this on yourself — not to hit a deadline, not because the queue is long, not because
+the last five cuts were approved.
+
+#### The state lives in files, because a weak model loses the thread
+
+A task is a dozen steps over hours. That does not survive a context reset, and the failure is always
+the same: the loop forgets which stage it was at, redoes a step, or submits a cut nobody watched. So
+the stage lives on disk under `CLIPPER/`, and **`vidfarm clipper-run` is the only thing that reads
+and writes it**:
+
+```bash
+vidfarm clipper-run init          # MISSION.md · MACHINES.md · LEDGER.jsonl · EARNINGS.md · REVIEW_QUEUE.md · tasks/
+vidfarm clipper-run next          # WHAT DO I DO RIGHT NOW — per open task, and what is waiting on the human
+vidfarm clipper-run status        # every task, its stage, who it is waiting on
+vidfarm clipper-run review        # the human's list (also written to CLIPPER/REVIEW_QUEUE.md)
+vidfarm clipper-run gate $TASK    # MAY I SUBMIT? exits non-zero while a human gate is open
+```
+
+**Open every cycle with `vidfarm clipper-run next`, and close every task with `gate` before you
+submit.** `gate` is the rail that makes the run mode real rather than advisory: write the submit as
+
+```bash
+vidfarm clipper-run gate $TASK && vidfarm gigs submit $GIG --task $TASK \
+  --proof https://…/final-watermarked.mp4 --clean-master ./final-clean.mp4 \
+  && vidfarm clipper-run submitted $TASK --proof $PROOF_ID
+```
+
+and an unreviewed cut cannot physically be sent — the gate exits non-zero and the chain stops.
+`submitted` closes the row and appends the `LEDGER.jsonl` line, including **who approved the cut and
+when**, which is how a gigworker audits the loop that ran while they slept.
+
+**The mode a task started under is the mode it finishes under.** Changing the mission mode mid-batch
+does not retroactively remove a stop from a task already in flight, and it must not: the gigworker
+agreed to review that one.
+
+**Before you route anything — which model are you?** This decides *how* you build, and it is a
+separate question from *what* you build. If you are **Gemini Flash, DeepSeek, Kimi, GLM, MiniMax,
+Grok, Qwen, Llama**, any distilled / "-mini" / "-lite" / "-turbo" tier, or you cannot name your own
+model, load **`https://vidfarm.cc/flash-harness.md`** and follow it. Unsure resolves to weak. Most
+clippers here run Antigravity, so this is the normal path, not the exception.
+
+The short version of that file, so you know what you are opting into:
+
+1. `vidfarm discover --query "<the client's problem, in their words>" --json` — shortlist three
+   templates. A row carrying `summary`, `keywords` and `promotions` is **already decomposed**.
+2. `vidfarm fork <template_id>` → `vidfarm pull <forkId> --dir ./work`. Not decomposed?
+   `vidfarm decompose <forkId>` on a paid plan, `vidfarm decompose <forkId> --local` on free.
+   Prefer a template that is already decomposed over one you have to decompose yourself.
+3. `vidfarm harness derive <forkId> --out ./work/HARNESS.md`, then read the **viral DNA** (hook /
+   retention / payoff) and the **visual DNA** (cut rhythm, typography, transitions).
+4. Plan the beats into `STORYBOARD.md`, then **procure every raw for every beat in one pass** —
+   the client's shared folder → the client's website (`vidfarm capture`) → public raws → free stock
+   → IconScout → your own subscription's generator → billed, last. Same ladder for the voiceover
+   and the music.
+5. Transplant: keep the beat count, the timings, the cut rhythm and the caption identity; replace
+   every word, every image, every voice line and the track. **Check that every audio `data-src` is
+   now yours** — shipping the source brand's voiceover under your client's captions is the failure
+   this format is most prone to, and it passes every automated check.
+6. `vidfarm qa`, render, read the contact sheet, then the review gate below.
+
+**Routing a task to a format.** Whichever tier you are, decide what kind of video the task is, then
+follow the matching format harness from the live index at `https://vidfarm.cc/experimental`. A weak
+model reads that harness as a **grading rubric** and reaches it by the six steps above; a frontier
+model authors from it directly:
 
 - a task asking to introduce a product, a feature, or a website → the product-explainer harness,
   `https://vidfarm.cc/experimental/unique-product-explainers.md`
@@ -441,14 +763,156 @@ have not seen is a format you cannot sell. **If the task payload names a `format
 over your own judgement.** The full routing table and the fall-through order are in
 `agentic-clipper.md`.
 
+**Grade the gigworker's hardware before you plan the work.** A clipper loop runs on whoever's laptop
+is in the room. On **capable** hardware (≥ 8 GB RAM, ≥ 4 cores) use the free local engines —
+`vidfarm tts --engine local` (Kokoro), `vidfarm stt --engine whisper`, local keying and local
+render. On **weak** hardware those models do not fail, they just take twenty minutes and lose the
+deadline: instead ask the AI agent subscription the gigworker already pays for to make the voice
+line, the audio or the image, and bring the file in with `vidfarm put-file`. Spend stays $0 either
+way — `minimize` still refuses billed steps. For the agent itself, recommend **Google Antigravity
+CLI** to a gigworker on a budget, and **OpenAI Codex** to one who can afford the more expensive
+subscription. The measurement commands and the full engine table are in
+`https://vidfarm.cc/agentic-clipper.md` § 3½.
+
+**Say the $0 rule out loud, because agents get it wrong in the cautious direction.** Antigravity,
+Gemini CLI and Codex all include image generation, TTS and STT inside the flat subscription the
+gigworker already pays for. Using them charges Vidfarm nothing and the provider nothing extra, so
+**they are permitted inside `$0` cost-saving mode with no `--yes` and no permission ask** — and
+they are *preferred* over a slow local engine on weak hardware, since both cost $0 and only one
+meets the deadline. **Default to the subscription.** Claude Code is the exception: Anthropic ships
+no image, voice or transcription model, so a Claude Code clipper has nothing to fall back on and
+must work the free stock / IconScout / interactive-handoff rungs instead. Check with
+`vidfarm agent-image --check`, and name in the proof which assets came from your own subscription.
+
 The REST APIs behind all of that:
 
 - 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
+- vidfarm.cc/flash-harness.md **if you are a weak model, or unsure which you are.** it is the same job by a different road: start from a decomposed template on vidfarm.cc/discover instead of authoring a format from prose. it also holds the two self-identification questions — strong vs weak, and whether your own subscription's image/tts/stt generation is available (it is $0, so it is legal in cost saving mode)
 - 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.
 
+### "help me earn on vidfarm" — the whole first session, copy-paste
+
+**When the gigworker asks to EARN, this block is the answer.** It is the four moves from the top of
+this document, as runnable commands. Everything below it is the manual for the calls it makes.
+
+```bash
+# 0 — your key. a free vidfarm.cc account hands it over; nothing is pasted anywhere.
+export DOLLARPLATOON_API_KEY=$(curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  https://vidfarm.cc/api/v1/user/me/marketplace | jq -r .dollarplatoon_api_key)
+
+FEED=FEED_01M0BCTVTKSDFZQVEY1RXA4NJK
+INVITE=MDFNMEJDVFZUWjVaUEFHNDlO
+
+# once — the vidfarm feed is invite-only. re-joining is a safe no-op.
+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\"}"
+
+# ── MOVE 1 ── who is asking for videos RIGHT NOW. note the key is `notifications`, not `items`.
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/feeds/$FEED/notifications?limit=50" \
+  | jq -r '.notifications[] | "\(.created_at)  \(.title)\n  \(.subtext)\n  → \(.destination_url)"'
+
+# ── MOVE 2 ── each destination_url is a JOIN LINK carrying the gig id and the invite token.
+#              pull both out, then read the gig's coin box BEFORE you join or build anything.
+GIG=$(echo   "$DEST_URL" | sed -n 's#.*/gig/\([^/]*\)/join.*#\1#p')
+INV=$(echo   "$DEST_URL" | sed -n 's#.*[?&]invite=\([^&]*\).*#\1#p')
+
+#   NOTE the `(.gig // .)`: this route has been seen returning the gig both nested under
+#   `gig` and flat at the top level. read it defensively and neither shape prints null.
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" "https://dollarplatoon.com/api/gigs/$GIG" \
+  | jq '(.gig // .) | {title, available_funds, reserved_funds, price, review_timeout, distribution}'
+#   available_funds == 0            → SKIP IT. approval does not create money.
+#   available_funds <  task price   → partial. the submit warns and still accepts. not a promise.
+#   available_funds >= 3x price     → healthy. work it.
+
+# ── MOVE 3 ── join the funded ones, WITH your Base L2 payout address in the same call.
+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\":\"$INV\",
+       \"wallet_address\":\"0xYOUR_BASE_L2_ADDRESS\",\"notes\":\"sticker-style short form, 9:16\"}"
+
+# ── MOVE 4 ── what can i build today, across EVERY machine i have joined. one call, not N.
+curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/work/available?only_with_work=true" \
+  | jq -r '.items[] | "\(.gig_title)\t\(.gig_id)\tprice \(.price)\tpoll=\(.poll_in_gig)"'
+
+# then, on a Custom Requests machine, claim ONE task off the shared fifo queue:
+curl -s -X POST "https://dollarplatoon.com/api/gigs/$GIG/queue/poll" \
+  -H "x-api-key: $DOLLARPLATOON_API_KEY" -H "Content-Type: application/json" -d '{"count":1}'
+```
+
+**with the devcli installed, all four moves are ONE command:**
+
+```bash
+npm i -g @officexapp/vidfarm-devcli
+export DOLLARPLATOON_API_KEY=…        # or just `vidfarm login` — every account holds a key
+
+vidfarm gigs earn
+```
+
+`gigs earn` joins the feed if you are not on it, reads every bell, digs the gig id out of each
+join link, checks all of them for money in parallel, and prints them **best-payer-first** with the
+exact join command on each row. Then it lists the work already waiting in machines you joined. It
+writes nothing except the feed join, so it is safe to run first and safe to run often.
+
+then, once, agree the **run mode** with the gigworker and save it — it decides which stages of every
+task stop for them:
+
+```bash
+vidfarm clipper-run mode                      # explains all four, says which one is set
+vidfarm clipper-run mode quick-interactive    # or full-interactive · auto-batch · auto-submit
+vidfarm clipper-run init                      # the CLIPPER/ mission files
+```
+
+the same four moves one at a time, when you want them separately:
+
+```bash
+vidfarm gigs feed --funded             # MOVE 1+2 — who is asking, AND who can pay
+vidfarm gigs check <gig-id|join-url>   # MOVE 2 — one machine. --price <usd> scores the TASK price
+vidfarm gigs join <invite-url> --wallet 0xYOUR_BASE_ADDRESS   # MOVE 3
+vidfarm gigs work                      # MOVE 4 — paged across every machine you joined
+vidfarm gigs claim <gig-id>            #          claim ONE off the FIFO queue — keep the task id
+```
+
+`gigs check` prints a verdict, not just a number, on the same thresholds this document uses:
+
+| Verdict | Means |
+|---|---|
+| `SKIP` | empty coin box. Approval does not create money |
+| `PARTIAL` | cannot cover one payout + the 10% fee. A submit still succeeds — that is not a promise |
+| `THIN` | one or two payouts left. Someone else may take it first |
+| `HEALTHY` | three or more payouts at this price |
+| `PRICE TBD` | funded, but the client names the amount at approval |
+
+Add `--json` to any of them for structured output.
+
+**four things that decide whether this session earns anything:**
+
+1. **read the notifications before the registry.** the registry lists every machine that exists; the
+   notifications list the ones whose owner is awake. a bell that rang today has a human sitting
+   there reviewing, and pitching into it beats pitching into a machine that has been quiet for a
+   month. the registry is for filling out the rest of your roster, not for picking today's work.
+2. **check `available_funds` before you join, and again before you build.** joining is free and
+   reversible; an hour of editing is not. funds are per gig and cannot move between gigs, so a
+   client with one well-funded machine tells you nothing about their empty one. budget the 10%
+   platform fee too: a gig holding $5.00 pays four $1.00 videos, not five.
+3. **set `wallet_address` on the FIRST join, not later.** a rollup pays the address that was
+   snapshotted when it was created, so an address added after you submit does not retroactively
+   redirect anything. your reputation survives a later change; a payout does not.
+4. **inbound offers needs no task and no claim.** on a `vidfarm_vm_inbound_offers` machine there is
+   nothing to poll — you make a video you think that buyer wants and submit it unprompted. nobody
+   can beat you to it, and a pass tagged `not_selected` costs you no reputation at all. that makes
+   it the right place to be prolific and the right place to try your specialty on a new client. see
+   **Step 4** below.
+
+**then write down what you found.** one row per machine in `CLIPPER/MACHINES.md`: the gig id, the
+client, the invite link, what it wants, its `available_funds`, and today's date. you will revisit
+these every loop, and re-deriving gig ids every session is wasted work.
+
 ### 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:
@@ -518,7 +982,15 @@ record the newest notification `id` you have seen and stop paging when you reach
 
 ### 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:
+**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. one command settles it, and it takes a gig id or a join link pasted straight out of a notification:
+
+```bash
+vidfarm gigs check "https://dollarplatoon.com/gig/GIG_01M…/join?invite=abc"
+vidfarm gigs check GIG_01M… --price 1.00      # score against the TASK price, not the gig default
+#   SKIP · PARTIAL · THIN · HEALTHY · PRICE TBD — the verdict, not just the number
+```
+
+the raw call it makes, and what each field means:
 
 ```bash
 curl -s -H "x-api-key: $DOLLARPLATOON_API_KEY" \
@@ -583,6 +1055,17 @@ vidfarm clients run two standing machines and they want different things from yo
 
 **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.
 
+**before you submit, the gigworker watches the cut and approves it.** this call is the point of no
+return: you cannot unsend a proof, and a `low_quality` rejection is scored on the wallet and shown to
+buyers as a trust score on the public profile. so an agent running a clipper loop builds, QAs and
+then **stops** — it presents the video to its gigworker and waits. only a gigworker who explicitly
+asked for auto-submit removes that stop, and only for as long and as narrowly as they asked.
+
+three of the four run modes stop here, and the fourth is the one the gigworker had to ask for by
+name. make the stop mechanical rather than remembered: `vidfarm clipper-run gate <task-id> && vidfarm
+gigs submit …` cannot send an unreviewed cut, because the gate exits non-zero while a human gate is
+open. see **The four run modes** above.
+
 **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
@@ -596,6 +1079,20 @@ put a **playable public MP4 url** in `proofs`. the buyer swipes these in a deck
 
 ### watermark the proof, hold the clean master
 
+**the devcli does this whole four-step dance in one call:**
+
+```bash
+vidfarm gigs submit $GIG --task $TASK \
+  --proof https://…/final-watermarked.mp4 \
+  --clean-master ./final-clean.mp4 \
+  --private-note "ProRes + project files in the drop box. 1080x1920, 27s, 30fps. Music licence: Epidemic #1234."
+```
+
+`--clean-master` presigns, uploads the file to dollarplatoon's own s3, and puts that url at the top
+of the private note. It then **verifies `private_note_locked` came back** and warns loudly if it did
+not — because you cannot patch a note onto a proof afterwards. `vidfarm gigs upload <file>` does the
+upload on its own if you want the url first. The manual version follows.
+
 **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.
@@ -679,23 +1176,56 @@ that `GET` returns the proof **flat** — read `.paid_out_at`, not `.proof.paid_
 
 ### 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:
+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 one command to start and eight to run:
 
 ```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 earn                      # START HERE — moves 1+2+4 in one call, ranked by who can pay
+
+vidfarm gigs feed --funded             # who is asking right now, annotated with their coin box
+vidfarm gigs feed --registry           # every machine listed in the feed, not just today's bells
+vidfarm gigs check <gig-id|join-url>   # CAN THIS ONE PAY ME? do it before you commit an hour
+vidfarm gigs join <invite-url> --wallet 0x…   # the url from the feed entry carries the token
+vidfarm gigs work                      # work waiting across every machine you joined (paged)
+vidfarm gigs claim <gig-id>            # claim ONE off the FIFO queue — keep the task id
+vidfarm gigs submit <gig-id> --task <task-id> \
+  --proof https://…/final-watermarked.mp4 --clean-master ./final-clean.mp4
+vidfarm gigs proof <gig-id> <proof-id> # did it save the note? have i been PAID?
+vidfarm gigs earnings                  # your rollups + totals
 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.
+`--json` on any of them gives your agent structured output.
+
+**the loop's own state is a second command, and it needs no key at all:**
+
+```bash
+vidfarm clipper-run mode <full-interactive|quick-interactive|auto-batch|auto-submit>
+vidfarm clipper-run next               # what do i do RIGHT NOW, per open task
+vidfarm clipper-run review             # what is waiting on the gigworker
+vidfarm clipper-run gate <task-id>     # may i submit? non-zero exit while a human gate is open
+```
+
+`vidfarm gigs` talks to the network; `vidfarm clipper-run` writes files under `CLIPPER/`. keep them
+straight: the first one is money, the second one is memory.
+
+**four rules the CLI now enforces or surfaces for you, and they still apply:**
+
+- `--task` is the **polled task's id**, never the subject line, and the proof must be a playable
+  public url.
+- `gigs claim` claims **one** task by default. Claiming takes a task off everybody else's queue and
+  the client is now waiting on you specifically; `unresponsive` is a 2× reputation hit. Pass
+  `--count N` only when you mean it.
+- `gigs join` prints the machine's funding verdict as it joins, and **warns when you gave no
+  `--wallet`**. Set it on the first join: a rollup pays the address that was snapshotted when it
+  was created, so adding one later does not redirect a payout already in flight.
+- `gigs submit --clean-master <file>` uploads that file to dollarplatoon's own s3 and seals the url
+  in the proof's `private_note`, then **checks `private_note_locked` came back in the response** and
+  says so loudly if it did not. You cannot patch a note onto a proof afterwards, so a silent miss
+  there means you handed over nothing. Submitting with no note at all gets a warning too — if the
+  url in `--proof` is your clean master, the buyer has it before paying.
 
 ### the task gave you a folder link — work it from the terminal