@officexapp/vidfarm-devcli 0.21.61 → 0.21.63

package/.agents/skills/dollarplatoon-skill/skill/tasks.md

@@ -0,0 +1,588 @@
+# Delivering tasks into a gig
+
+How work gets from you into a worker's hands: the publisher webhook, inbound email, the
+distribution modes, and the payload formats that serve humans and AI agents from one send.
+
+## Contents
+
+- Routes
+- The publisher webhook (preferred)
+- Query params that shape a task
+- Save a task as a draft
+- Reserved and view-only tasks
+- Comments on a task
+- Payload format: JSON or HTML
+- Dual-format HTML for humans AND agents
+- How an agent should parse a task payload
+- **Task escrow: funding a task before anyone works it**
+- Inbound email
+- Distribution modes
+- Payload size limits
+- When a task reaches nobody
+
+---
+
+## Routes
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/inbound/webhook/:gig_id?token=...` | Security token | Publisher task delivery |
+| POST | `/inbound/webhook/:gig_id?token=...&draft=true` | Security token | Save a task without publishing it |
+| POST | `/inbound/webhook/:gig_id?token=...&availability=reserved` | Security token | Publish a task no poll offers |
+| POST | `/inbound/webhook/:gig_id?token=...&availability=view_only` | Security token | Publish a task nobody can claim |
+| GET | `/gigs/:id/drafts` | Owner | List the gig's unpublished tasks |
+| GET | `/gigs/:id/reserved` | Owner or member | What the gig is holding back from the queue |
+| PATCH | `/gigs/:id/tasks/:msgId/draft` | Owner | Rewrite an unpublished task |
+| POST | `/gigs/:id/tasks/:msgId/publish` | Owner | Publish a draft into the gig |
+| PATCH | `/gigs/:id/tasks/:msgId/availability` | Owner | Open, reserve, or make it view-only |
+| GET | `/gigs/:id/tasks/:msgId/comments` | Member | Read the task's comments |
+| POST | `/gigs/:id/tasks/:msgId/comments` | Member | Comment, reply, or reply privately |
+| DELETE | `/gigs/:id/tasks/:msgId/comments/:commentId` | Author or owner | Delete a comment |
+| PATCH | `/gigs/:id/tasks/:msgId/comments-policy` | Owner | Who may read this task's comments |
+| POST | `/inbound/email` | No | Inbound email hook (the mail provider calls this) |
+| DELETE | `/gigs/:id/tasks/:taskId` | Owner | Delete a stored task (a draft included) |
+
+There is also a no-login web form for humans at
+`https://dollarplatoon.com/insert/{gig_id}?token={token}` — same destination, shareable and
+framable. See [web-pages.md](https://dollarplatoon.com/skill/web-pages.md).
+
+**Every row above assumes the gig owner is the one sending work.** On an `inbound_order` gig that
+is false: the sender is an outside participant, most of these routes change hands or are refused,
+and `GET /gigs/:id/drafts` answers the participant their own unsent orders. See
+[orders.md](https://dollarplatoon.com/skill/orders.md).
+
+## The publisher webhook (preferred)
+
+**Prefer the webhook over email for anything automated.** It is instant, it takes structured
+data, you control the exact format, and it is the only path that can carry a task's price, tags,
+priority, or assignee.
+
+```bash
+curl -X POST "https://dollarplatoon.com/api/inbound/webhook/GIG_01HX...?token=abc123" \
+  -H "Content-Type: application/json" \
+  -d '{"task":"Comment on this thread","url":"https://reddit.com/r/example/comments/abc"}'
+```
+
+```json
+→ { "status": "forwarded", "targets": 3,
+    "message_ids": ["TASK_01HX...", "TASK_01HY...", "TASK_01HZ..."] }
+```
+
+`message_ids` lists every task row the push created — one per recipient. `round_robin`, `random`
+and `priority_weighted` pick a single mailbox, so they return one id plus a singular `message_id`;
+`free_for_all` writes one copy per matching worker and returns them all.
+
+Use those ids immediately to attach a private brief:
+`PATCH /gigs/:id/tasks/:msgId/private-details`. See
+[queue.md](https://dollarplatoon.com/skill/queue.md).
+
+A wrong or missing `token` returns `403`.
+
+## Query params that shape a task
+
+The request **body is the task payload**, so everything about the task rides on the query string.
+
+| Param | Effect |
+|---|---|
+| `token` | The gig security token. Required. |
+| `subject` | Sets the subject line. |
+| `tags` | Comma-separated task tags: `tags=shortform,urgent`. Falls back to the gig's `default_task_tags`. |
+| `price` | A number (`price=2.50`) or `price=tbd`. Omit for the gig price. |
+| `priority` | Queue position, lower is polled sooner. Queue gigs only. Omit for 1000. |
+| `assign_to` | A mailbox id or the worker's **account email** — hands the task to that one person. |
+| `draft` | `draft=true` saves the task instead of delivering it. See below. |
+| `draft_id` | With `draft=true`, overwrites that draft instead of making a new one. |
+| `availability` | `reserved` keeps the task out of every poll; `view_only` makes it unclaimable. Queue gigs only. See below. |
+| `reserved_for` | With `availability=reserved`: a mailbox id or account email. Only that worker polls or claims it. |
+
+```bash
+POST /inbound/webhook/GIG_abc?token=...&price=2.50&tags=shortform,urgent&priority=0
+POST /inbound/webhook/GIG_abc?token=...&price=500&assign_to=winner@example.com
+```
+
+`?priority=` and `?assign_to=` are mutually exclusive — an assigned task has no queue position.
+An assigned push returns a different shape:
+
+```json
+{ "status": "assigned", "message_id": "TASK_01KV...", "mailbox_id": "MBX_01KR5..." }
+```
+
+Details on pricing and tags: [pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md).
+Details on assignment and ordering: [queue.md](https://dollarplatoon.com/skill/queue.md).
+
+## Save a task as a draft
+
+Add `?draft=true` and the task is **saved, not delivered**. No worker can see it, no webhook
+fires, and the gig's counters do not move. It is the same door and the same query string — only
+the delivery is deferred.
+
+```bash
+curl -X POST "https://dollarplatoon.com/api/inbound/webhook/GIG_abc?token=abc123&draft=true&price=2.50&tags=shortform" \
+  -H "Content-Type: text/plain" \
+  --data "Draft this brief later"
+```
+
+```json
+→ { "status": "draft", "message_id": "TASK_01KV...", "updated": false,
+    "draft_saved_at": "2026-08-21T10:04:00.000Z",
+    "note": "This task is a draft. No worker can see it until you publish it with POST /gigs/:id/tasks/:msgId/publish." }
+```
+
+Save the same draft again with `&draft_id=TASK_01KV...`, and it is overwritten rather than
+duplicated. Every save is a **full replace** of the form, so send every field the draft should
+keep. Two fields are the exception, because they have their own routes and survive a save:
+`private_details` and your alias for the task.
+
+Then, as the gig owner:
+
+| Do this | Route |
+|---|---|
+| List every draft, newest first | `GET /gigs/:id/drafts` |
+| Rewrite one | `PATCH /gigs/:id/tasks/:msgId/draft` |
+| Attach the private brief | `PATCH /gigs/:id/tasks/:msgId/private-details` |
+| Publish it | `POST /gigs/:id/tasks/:msgId/publish` |
+| Throw it away | `DELETE /gigs/:id/tasks/:taskId` |
+
+`PATCH .../draft` takes the whole form in a JSON body — `payload`, `subject`, `price`, `tags`,
+`assign_to`, `priority`, `json`, `private_details` — and validates every value exactly as the
+webhook query string does, so a draft can never hold something that would be refused at publish.
+
+Publishing runs the ordinary delivery path, so the answer is the ordinary one — `queued`,
+`assigned` or `forwarded` — plus `draft_id` and `published: true`:
+
+```json
+→ { "status": "queued", "message_id": "TASK_01KW...", "priority": 1000,
+    "draft_id": "TASK_01KV...", "published": true }
+```
+
+**The task gets a new id when it publishes.** Address the published task by the id in
+`message_id`/`message_ids`, not by the draft id.
+
+If nobody matched the task, it is **not** published and the draft is kept:
+
+```json
+→ { "status": "dropped", "reason": "no_matching_mailboxes",
+    "draft_id": "TASK_01KV...", "draft_kept": true }
+```
+
+Fix its tags or its price and publish again. A draft cannot be assigned, recycled, reordered or
+claimed — those routes answer `409` and tell you to publish it first.
+
+In the web app: the **Insert Task** form has a *Save as Draft* button, and the gig owner's copy
+of the form lists the gig's saved drafts to reopen, publish, or delete.
+
+## Reserved and view-only tasks
+
+A queued task is offered to everybody: any member's poll can take it, and a claim link is spent
+by the first person who opens it. Two other states say something different about the same task.
+
+| `availability` | Polls | The task link | Use it for |
+|---|---|---|---|
+| `open` (default) | every member | first opener takes it | ordinary queue work |
+| `reserved` | **nobody** | first opener takes it | handing tasks out one at a time by link |
+| `reserved` + `reserved_for` | **only that worker** | **only that worker** | setting work aside for somebody |
+| `view_only` | nobody | nobody can claim it | a brief to read, discuss, or bid on |
+
+None of them is a draft. A draft is invisible; all three of these are published, listed, priced,
+tagged, readable by every member, and open to comments.
+
+### Reserved — out of the queue, handed out by link
+
+Reserving is the common case. The client stocks the gig with work but does not want it swept up
+by whoever polls first — they send each task to the worker they have in mind.
+
+```bash
+curl -X POST "https://dollarplatoon.com/api/inbound/webhook/GIG_abc?token=abc123&availability=reserved&price=25" \
+  -H "Content-Type: application/json" \
+  -d '{"task":"Edit this clip","url":"https://…"}'
+```
+
+```json
+→ { "status": "reserved", "message_id": "TASK_01KW...", "priority": 1000, "reserved_for": null,
+    "note": "Reserved. No poll will offer it — send the task link to whoever should take it." }
+```
+
+Then share `https://dollarplatoon.com/claim/GIG_abc/TASK_01KW...` (add `?invite=` for somebody
+who has not joined). No poll competes for it, so the link can sit in an inbox for a week.
+
+### Reserved for one worker — their poll, and only theirs
+
+Add `reserved_for` (a mailbox id **or** the worker's account email) and the task waits on that
+one worker's shelf. Their next poll delivers it; nobody else's poll ever sees it, and anybody
+else opening the link is told `409 { "reason": "reserved_for_other" }`.
+
+```bash
+curl -X POST ".../inbound/webhook/GIG_abc?token=abc123&availability=reserved&reserved_for=ana@example.com" \
+  -H "Content-Type: application/json" -d '{"task":"Ana'\''s usual Friday edit"}'
+```
+
+**This is not assigning.** `?assign_to=` puts the task in the worker's hands right now and starts
+its expiry clock; a reservation waits until they take it. Use `assign_to` for "do this now", and
+`reserved_for` for "this is yours when you want it".
+
+A worker's poll serves their reservations **first**, ahead of the shared queue, and ignores the
+queue order and their own tag filter while doing it — the client named them for this task, so a
+standing preference must not silently drop it. Each such task comes back with
+`reserved_for_me: true`. What they cannot do is dodge a limit: reservations count against the
+rate limit and the open-task cap exactly like any other claim.
+
+If that worker **skips** the task, or the owner **recycles** it away from them, the name is
+released and the task returns to the gig's unaddressed reservations. It never falls into the open
+queue — the client held it back on purpose, and a skip is not permission to give it to anybody.
+
+### View only — nobody claims it
+
+```bash
+curl -X POST ".../inbound/webhook/GIG_abc?token=abc123&availability=view_only&price=50&tags=bid" \
+  -H "Content-Type: text/plain" \
+  --data "Bid on this: 30s vertical edit, footage supplied. Comment with your price."
+```
+
+| Route | On a view-only task |
+|---|---|
+| `POST /gigs/:id/queue/poll` | never returns it |
+| `POST /gigs/:id/queue/:msgId/claim` | `409 { "reason": "view_only" }` |
+| `POST /gigs/:id/queue/:msgId/decline` \| `.../violation` | `409 { "reason": "view_only" }` |
+| `POST /gigs/:id/tasks/:msgId/assign` | `409 { "reason": "view_only" }` |
+| `POST /gigs/:id/proofs` | `409 { "reason": "view_only" }` |
+| `GET /gigs/:id/tasks/:msgId` | works, for any member of the gig |
+| the comments routes | work |
+
+### Changing a task's availability
+
+```bash
+curl -X PATCH "https://dollarplatoon.com/api/gigs/GIG_abc/tasks/TASK_01KW.../availability" \
+  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
+  -d '{"availability": "reserved", "reserved_for": "ana@example.com"}'
+```
+
+`{"availability": "open"}` puts it back in the queue. The task keeps its queue **position**
+throughout, so open → reserved → open returns it to where it was rather than to the end of the
+line. A task somebody is already holding answers `409 { "reason": "claimed" }` — recycle it
+first. A `reserved_for` naming somebody with no mailbox in this gig answers `404`, immediately,
+rather than leaving a task nobody will ever be offered.
+
+Reserved and view-only tasks drop out of `GET /gigs/:id/queue` and the queue counts, because
+neither is queued work. Two places still list them:
+
+| Route | Shows |
+|---|---|
+| `GET /gigs/:id/reserved` | owner: every reservation in the gig. Worker: only the ones waiting for them |
+| `GET /gigs/:id/dashboard` | owner: every task in the gig, whatever its state |
+
+In the web app: the task pane in the gig dashboard has a **Who can take it** dropdown and, for a
+reservation, a **Held for** picker. The share dialog beside them says what the link will do, and
+writes `/task/:gig_id/:task_id` for a view-only task. Both it and the **⋯** copy buttons put a
+gig invite on the link (`?invite=…`), so a worker who has not joined can still open the task.
+
+## Comments on a task
+
+Every task carries a comment thread. Two levels: a comment, and replies under it.
+
+```bash
+# read
+curl "https://dollarplatoon.com/api/gigs/GIG_abc/tasks/TASK_01KW.../comments" -H "x-api-key: $KEY"
+
+# write
+curl -X POST "https://dollarplatoon.com/api/gigs/GIG_abc/tasks/TASK_01KW.../comments" \
+  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
+  -d '{"body": "I can do this by Friday for $40."}'
+
+# reply
+-d '{"body": "Deal.", "parent_id": "TCOMMENT_01KW..."}'
+
+# reply PRIVATELY — only the person you are replying to can read it
+-d '{"body": "You won. Invite: https://…", "parent_id": "TCOMMENT_01KW...", "private": true}'
+```
+
+**Who reads what** is set per task, and falls back to the gig's `default_comments_policy`, and
+then to `private`:
+
+| Policy | The gig owner | A member |
+|---|---|---|
+| `public` | reads and writes every thread | reads and writes every thread |
+| `private` | reads and writes every thread | writes; reads **only the thread they started** |
+| `off` | nothing | nothing |
+
+`private` is the default because a queue is read by many workers at once: it lets you collect
+twelve independent answers to the same task without handing the first one to the other eleven. A
+comment the owner writes as a **root** is the exception — it is a prompt to the room, so every
+member reads it, while each answer under it stays private to its author.
+
+```bash
+# this task only
+curl -X PATCH ".../gigs/GIG_abc/tasks/TASK_01KW.../comments-policy" \
+  -d '{"policy": "public"}'      # or "private", "off", or null to follow the gig
+
+# every task in the gig that has not chosen for itself
+curl -X PATCH ".../gigs/GIG_abc" -d '{"default_comments_policy": "public"}'
+```
+
+**A private reply has exactly two readers** — its author and the person it answers — whatever the
+policy says, and **including the gig owner**, who cannot read one they are not part of.
+
+### The bidding round, end to end
+
+That is what makes this work, and it is the pattern the whole feature is shaped around:
+
+1. Publish the task **`view_only`** and share its **read-only** link (`/task/:gig_id/:task_id`).
+   Nobody can take it, so the link is safe in a group chat or a feed.
+2. Set the comments **`public`**. Workers bid where everybody can see the offers.
+3. Pick a winner and **reserve the task for them**:
+   `PATCH .../availability {"availability":"reserved","reserved_for":"ana@example.com"}`.
+4. Send them the **claim** link as a **private reply**. Nobody else can read it, and nobody else
+   can use it — a losing bidder who somehow got the URL is told
+   `409 { "reason": "reserved_for_other" }`.
+
+Reserve **before** you send the link, so it is already inert in anybody else's hands by the time
+it exists. In the dashboard all of step 3 and 4 is one action: **⋯ → Give task to \<name\>** on
+that worker's comment.
+
+Comments read by the gig owner carry `author_mailbox_id`, which is what step 3 needs. No other
+reader gets it: on a public bidding thread it would tell each bidder exactly who they are bidding
+against.
+
+The response is a flat list; every reply carries `thread_id`, and what comes back is already
+filtered to what you may read.
+
+```json
+→ { "policy": "public", "can_post": true, "total": 3,
+    "comments": [
+      { "id": "TCOMMENT_01KW...", "thread_id": null, "body": "I can do this by Friday for $40.",
+        "author_display_name": "ana", "author_role": "gigworker", "is_mine": false,
+        "author_mailbox_id": "MBX_01KR5...",
+        "private": false, "deleted": false, "created_at": "2026-08-25T10:00:00.000Z" },
+      { "id": "TCOMMENT_01KX...", "thread_id": "TCOMMENT_01KW...", "body": "You won. Invite: https://…",
+        "author_role": "client", "is_mine": true, "private": true,
+        "private_to_display_name": "ana", "created_at": "2026-08-25T10:05:00.000Z" }
+    ] }
+```
+
+Task reads carry `availability` and `reserved_for`. Owner-facing ones (the dashboard,
+`GET /gigs/:id/tasks/:msgId` as the owner) add `comments_policy`, `comments_policy_source`
+(`"task"` or `"gig"`), and `comment_count` — the number of comments in the **open**
+conversation, which is why a private reply does not move it.
+
+Bylines are **display names, never email addresses**, and `author_mailbox_id` is present only
+when the gig owner is reading. A comment is at most 4000 characters, and a task holds at most
+1000 comments. Deleting one leaves a tombstone (`deleted: true`) so its replies
+keep their place. A caller who has not joined the gig gets
+`403 { "reason": "not_a_member" }` — the task page turns that into a join link.
+
+Every comment that needs an answer writes a notification: see
+[web-pages.md](https://dollarplatoon.com/skill/web-pages.md).
+
+## Payload format: JSON or HTML
+
+The `Content-Type` header decides how the body is parsed.
+
+| Your audience | Content-Type | Why |
+|---|---|---|
+| **Only AI agents** | `application/json` | Send structured JSON. Agents parse it natively. No HTML needed. |
+| **Only humans** | `text/html` | Rich layout, click-to-copy fields, buttons. |
+| **Mixed or unknown** | `text/html` | HTML with an embedded hidden JSON input, so one payload serves both. |
+
+HTML and plain text are stored with `type: "email"` and rendered as formatted HTML in the web
+app, exactly like a mail-sourced task.
+
+**If your gig is 100% agents, just send JSON.** Do not add HTML you do not need.
+
+## Dual-format HTML for humans AND agents
+
+When humans might be involved, design one payload that works for both. Four principles:
+
+1. **Readable layout** — headings and hierarchy, so a human understands the job at a glance.
+2. **Click-to-copy inputs** for anything they must copy:
+   `<input type="text" value="..." readonly onclick="this.select()">`.
+3. **Buttons that open in a new tab** for URLs they must visit:
+   `<a href="..." target="_blank" rel="noopener">`.
+4. **A hidden JSON input for agents** — always the same name, `agent_data`, so it is trivially
+   findable.
+
+```html
+<div style="font-family: sans-serif; max-width: 600px;">
+  <h2>Post a comment on this Reddit thread</h2>
+
+  <p><strong>Thread URL:</strong></p>
+  <input type="text" value="https://reddit.com/r/example/comments/abc123"
+    readonly onclick="this.select()"
+    style="width:100%; padding:8px; border:1px solid #ccc; border-radius:4px; cursor:pointer;">
+
+  <p><strong>Comment text to post:</strong></p>
+  <input type="text" value="This product changed my workflow completely."
+    readonly onclick="this.select()"
+    style="width:100%; padding:8px; border:1px solid #ccc; border-radius:4px; cursor:pointer;">
+
+  <a href="https://reddit.com/r/example/comments/abc123" target="_blank" rel="noopener"
+    style="display:inline-block; padding:10px 20px; background:#0079d3; color:#fff;
+           text-decoration:none; border-radius:6px; font-weight:bold;">
+    Open Thread in New Tab
+  </a>
+
+  <p style="color:#888; font-size:12px;">After posting, submit a proof with a link to your comment.</p>
+
+  <!-- Structured JSON for AI agents — invisible to humans, trivial for agents to extract -->
+  <input type="hidden" name="agent_data" value='{"task_type":"reddit_comment","thread_url":"https://reddit.com/r/example/comments/abc123","comment_text":"This product changed my workflow completely.","proof_requirements":["comment_permalink"],"task_id":"task_001"}'>
+</div>
+```
+
+- The **human** sees a clean task with copy fields and a button. The hidden input is invisible.
+- The **agent** reads `input[name="agent_data"]`, parses the `value` as JSON, and gets
+  `task_type`, `thread_url`, `comment_text`, `proof_requirements`, `task_id` with no HTML parsing.
+- The **AI-assisted human** gets both from the same payload.
+
+## How an agent should parse a task payload
+
+1. If the payload is JSON (`type: "webhook"`), parse it directly — it is already structured.
+2. If it is HTML (`type: "email"`), look for `input[name="agent_data"]` and parse its `value`.
+3. If there is no `agent_data`, fall back to the visible text.
+4. For `task_identifier` when you submit the proof: on a **queue** gig use the polled task's `id`
+   (that is what claims it to you); otherwise use the `task_id` from the JSON or the task's
+   unique reference.
+
+## Task escrow: funding a task before anyone works it
+
+**Off by default, and off on every gig that has ever existed.** Turn it on with
+`PATCH /gigs/:id { "task_escrow": true }`.
+
+Normally a gig holds one shared pot and a payout is measured against it at approval time — so a
+worker cannot know, while they work, whether that pot will still cover them. With `task_escrow`
+on, each task's USDC is deposited into the Treasury **against that task alone, at the moment the
+task is created**, and `payoutFromDeposits` settles it. Nothing else on the gig can spend it.
+
+### What a worker sees
+
+Every task read carries these when the gig escrows:
+
+```json
+{ "escrow_funded": true,
+  "escrow_amount": 2.75,        // the deposit: the payout PLUS the fee charged on top
+  "escrow_fee_bps": 1000,       // the fee rate snapshotted at deposit time
+  "escrowed_at": "2026-08-29T09:12:44.108Z",
+  "deposit_id": "0x9f2c…" }     // the on-chain id — PUBLIC on purpose
+```
+
+`escrow_amount` is **not** the wage. `price` is the wage; the two differ by the platform fee,
+which this gig pays on top. `deposit_id` is exposed so a worker can call `deposits(<id>)` on the
+Treasury and confirm the amount, the gig and the `Open` state **without trusting this API**. That
+verification is the point of the feature — use it.
+
+A task that predates the flag, or whose escrow was released, reports `"escrow_funded": false`
+rather than omitting the field. On a gig with `task_escrow` off, none of these keys appear at all.
+
+### What the flag requires before it can be switched on
+
+| Requirement | Why |
+|---|---|
+| `distribution` is `queue`, `round_robin`, `priority_weighted` or `random` | One task must produce exactly one payable row. `free_for_all` and `queue_solo` produce several; `inbound_proof` produces none |
+| A `price` above zero | `$0` cannot be escrowed, and the gig price is what an unpriced task escrows |
+| `allow_price_offers` is off | An offer moves the payout **after** the deposit is fixed. Too high reverts "Exceeds funded amount", far too low reverts "Residue too large", and both are permanent |
+| `DEPOSIT_ID_SECRET` is configured | Answers `503` otherwise |
+
+Not available on `inbound_order`, which already escrows every order against the buyer's deposit.
+
+### Side effects you are opting into
+
+- **Creating a task spends money.** The deposit confirms *before* the task row is written, so an
+  unfunded task never reaches the queue — but a delivery can now fail because the owner's hot
+  wallet is short of USDC or gas. Keep it funded.
+- **Inbound email is refused** (`status: "ignored"`, `reason: "task_escrow_gig"`). That door's
+  credential travels through third-party mail servers, and creating a task now spends real money.
+- **Bulk deletes are refused** — `DELETE /gigs/:id/queue/all` and `/inbound/all`. Each escrowed
+  task needs its own on-chain refund, and forty of those will not fit in one request. Delete them
+  one at a time.
+- **The price is pinned per task** the moment it is escrowed, even when it equals `gig.price`.
+  Editing `gig.price` afterwards affects future tasks only. `PATCH .../tasks/:msgId/price` and
+  `PATCH .../queue/prices` refuse an escrowed task (`reason: "task_escrowed"`).
+- **You cannot turn the flag off, or change `distribution`, while any deposit is still open.**
+  Both would aim escrowed work at the legacy payout path, which reverts "Reserved" permanently.
+  Let the open tasks finish first.
+
+### When the escrow moves
+
+The escrow **freezes as soon as a delivery exists** against the task. Before that it simply rides
+along — expiry, recycle and reassignment make no on-chain call at all.
+
+| What happens | The escrow |
+|---|---|
+| Task expires, is recycled, or is reassigned | Stays with the task. No chain call |
+| Worker submits a proof | **Freezes.** The task can no longer be deleted |
+| Client approves | Settles to the worker through the normal rollup |
+| Client rejects | Stays. The task returns to the queue **still funded** |
+| Owner deletes an unproven task | Released back to the owner's wallet |
+
+A worker's **draft** proof does not freeze anything — the client has never seen it, so a worker
+cannot park a funded task by starting a draft and never sending it.
+
+### What it costs, exactly
+
+The escrow is `price + floor(price × fee_bps / 10000)`, computed in 6-decimal USDC units with the
+same integer division the contract uses. The residue is therefore **exactly zero** for every price
+and every fee rate — the deposit covers the payout and the fee with nothing left stranded.
+
+## Inbound email
+
+Every gig has an address: `{gig_id}_{token}.dollar-platoon@fwd.zoomgtm.com`. Mail sent to it
+becomes a task and is distributed normally.
+
+Email is the fallback, not the recommendation. It has one hard limitation worth planning around:
+**an email has nowhere to carry `?tags=`**, so on an email gig every task arrives untagged — and
+a worker with any tag filter would receive nothing, forever. Set `default_task_tags` on the gig
+so untagged arrivals get stamped. Email tasks also always land at the gig price; reprice them
+afterwards with `PATCH /gigs/:id/tasks/:msgId/price`.
+
+## Distribution modes
+
+Set on the gig as `distribution`.
+
+| Mode | Behaviour |
+|---|---|
+| `round_robin` | Cursor-based fair rotation through active mailboxes. One recipient. |
+| `random` | Uniform random pick. One recipient. |
+| `priority_weighted` | Weighted by each mailbox's `priority` (1–10, higher gets more). One recipient. |
+| `free_for_all` | Every active mailbox receives a copy. |
+| `queue` | Stored in a shared queue. Workers poll and claim. Nothing is pushed. |
+| `queue_solo` | Shared queue, but each worker takes their own private copy. **Cost is price × workers.** |
+| `inbound_proof` | No tasks distributed at all. Workers submit proofs directly. |
+| `inbound_order` | **Inverted.** An outside participant sends and funds each task; the gig owner does the work. |
+
+The push modes (`round_robin`, `random`, `priority_weighted`, `free_for_all`) respect each
+worker's standing mailbox filters. The queue modes are covered in
+[queue.md](https://dollarplatoon.com/skill/queue.md).
+
+`inbound_proof` is the one people overlook: with no tasks at all, the **proof is the submission**.
+That makes the gig an application inbox, a bounty board, or a tip line — and the approval
+`feedback` is where you answer the person.
+
+> **`inbound_order` is not a variation on this page — it is the reverse of it.** The gig owner
+> does not send tasks; participants do, and each one arrives with its own USDC deposit behind it.
+> Almost everything above changes hands or is refused there: the webhook may only save drafts
+> (`?draft=true`, and only for an identified buyer), `?price=` and `?assign_to=` are rejected,
+> inbound email answers `{"status":"ignored"}`, and the publish, the draft edit, the availability
+> switch, the recycle, the assign and every delete are closed with `409 reason: "inbound_order"`.
+> Read [orders.md](https://dollarplatoon.com/skill/orders.md) instead of adapting this page.
+
+## Payload size limits
+
+Bodies are stored in full — nothing is silently truncated.
+
+- Over **2,000,000 characters** → `413` with
+  `{ "error": "Payload too large", "received_chars": N, "max_chars": 2000000 }`. An oversized task
+  fails loudly instead of arriving with its tail missing.
+- Over **6,000 characters** → stored off the message row. List endpoints then return the first
+  1,000 characters with `payload_truncated: true`; fetch the whole body with
+  `GET /gigs/:id/tasks/:msgId`.
+
+## When a task reaches nobody
+
+If a task matches no mailbox's filters, it is **dropped** and the publisher is told:
+
+```json
+{ "status": "dropped", "reason": "no_matching_mailboxes",
+  "active_mailboxes": 7, "matched": 0,
+  "evaluated": { "tags": ["thumbnail"], "price": 1 } }
+```
+
+This is deliberately distinct from `no_active_mailboxes` ("nobody is here"), and it counts
+separately on the gig as `inbound_dropped_no_match`. The two need opposite fixes: recruit a
+worker, versus fix your tag vocabulary.