@officexapp/vidfarm-devcli 0.21.62 → 0.21.63

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

@@ -0,0 +1,404 @@
+# Queues — polling, ordering, and assigning work
+
+Two queue distributions share every endpoint here. They differ in one thing: whether workers
+compete for the same task.
+
+## Contents
+
+- `queue` versus `queue_solo`
+- Queue order
+- Routes
+- Polling for tasks
+- Claiming one named task (share link)
+- Declining a task
+- Setting priority
+- Direct assignment to one worker
+- Private task details
+- Returning an assigned task
+- Hiring for a high-value task
+
+---
+
+## `queue` versus `queue_solo`
+
+| | `queue` (shared) | `queue_solo` (single player) |
+|---|---|---|
+| Who can claim a task | The first worker to poll it | Every worker, independently |
+| Effect on other workers | Claiming removes it from their queue | None — nothing you do is visible to them |
+| What you receive | The task itself | Your own private copy |
+| Proofs per task | One, gig-wide | One per worker |
+| Cost per task | price × 1 | price × number of workers who take it |
+| Task leaves the queue when | Someone claims it | It hits `max_claims_per_task` (never, if unlimited) |
+
+**The `queue_solo` cost warning.** Ten queued tasks in a solo gig with five workers is fifty
+payouts, not ten. `max_claims_per_task` bounds it — and it is also the *only* thing that ever
+drains a solo queue, because claiming does not consume the task.
+
+## Queue order
+
+Set `queue_order` on the gig.
+
+- **`fifo`** (default) — oldest first.
+- **`lifo`** — newest first.
+- **`priority`** — you set the order. Each task carries a `priority` number; lower goes first, and
+  tasks sharing a number are served oldest-first. So 0, 1, 2, 5, 7, 23, 4689, 99999 are polled in
+  exactly that order.
+- **`random`** — each poll draws at random from the tasks still queued. There is no position, so
+  `priority` numbers are ignored while this mode is on. A poll samples up to the first 1000 queued
+  tasks.
+
+New tasks default to priority **1000**, leaving room to insert above and below without renumbering
+anything. Priorities are non-negative whole numbers up to 9999999999.
+
+Think of priority as a **virtual arrival time**: a task at 0 behaves as though it arrived before
+everything else. That is why `fifo` honours priorities (oldest virtual arrival first) and `lifo`
+reverses them. Setting `queue_order: "priority"` declares the queue is meant to be hand-ordered —
+it turns on the priority column in the dashboard — but reordering works in any mode.
+
+## Routes
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/gigs/:id/queue/poll` | Worker | Claim tasks |
+| POST | `/gigs/:id/queue/:msgId/claim` | Worker | Claim ONE named task |
+| POST | `/gigs/:id/queue/:msgId/decline` | Worker | Skip a task, for you only |
+| GET | `/gigs/:id/queue` | Member | List queued tasks with `tags`, `price`, `priority`, `declined_count` |
+| GET | `/gigs/:id/reserved` | Owner or member | Tasks held back from the queue. Owner sees all; a worker sees their own |
+| GET | `/gigs/:id/tasks/:msgId` | Owner, holder, or member | One task with its full body |
+| PATCH | `/gigs/:id/tasks/:msgId/availability` | Owner | `open`, `reserved` (with `reserved_for`), or `view_only` |
+| PATCH | `/gigs/:id/tasks/:msgId/priority` | Owner | Move one queued task |
+| PATCH | `/gigs/:id/queue/priorities` | Owner | Reorder up to 100 tasks in one call |
+| PATCH | `/gigs/:id/tasks/:msgId/price` | Owner | Set what one task pays |
+| PATCH | `/gigs/:id/queue/prices` | Owner | Price up to 100 tasks in one call |
+| PATCH | `/gigs/:id/tasks/:msgId/tags` | Owner | Retag one task |
+| PATCH | `/gigs/:id/queue/tags` | Owner | Retag up to 100 tasks in one call |
+| POST | `/gigs/:id/tasks/:msgId/assign` | Owner | Give a task to one named worker |
+| PATCH | `/gigs/:id/tasks/:msgId/private-details` | Owner | The brief only the holder sees |
+| PATCH | `/gigs/:id/tasks/:msgId/alias` | Owner, holder, member | Your own private title for a task |
+| DELETE | `/gigs/:id/tasks/:taskId` | Owner | Delete a task |
+
+`GET /gigs/:id/queue` accepts `?tag=`, `?tag_match=`, and `?tag_mode=`. It is the owner's way to
+confirm that `?tags=` and `?price=` landed — **do not use `/queue/poll` to check**, because it is
+worker-only and it claims what it returns.
+
+## Polling for tasks
+
+```json
+POST /gigs/:id/queue/poll   { "count": 2 }   // default 2, max 20
+```
+
+```json
+{
+  "tasks": [
+    { "id": "TASK_01HX...", "type": "webhook", "subject": "...", "payload": "...",
+      "forwarded_at": "...", "claimed_at": "...",
+      "price": 2.50, "price_tbd": false,
+      "tags": ["shortform"],
+      "reserved_for_me": false,
+      "source_task_id": null }
+  ],
+  "count": 1,
+  "scan_exhausted": false,
+  "filter_applied": false,
+  "rate_limit": { "count": 5, "minutes": 60, "source": "gig", "used": 3, "remaining": 2, "retry_at": null },
+  "open_tasks": { "max_open_tasks": 3, "source": "gig", "open": 1, "remaining": 2 }
+}
+```
+
+Returns tasks in the configured order, skipping anything you have already taken, proven, or
+declined. Tasks are never pushed to a mailbox in a queue gig — you must poll.
+
+**Read `price` and `tags` per task, not per gig.** The gig price is only a default.
+
+**Your own reservations come first.** A task the client reserved for you is served ahead of the
+shared queue, and comes back with `reserved_for_me: true`. It ignores the queue order and your
+own tag filter — the client named you for that task, so a standing preference does not drop it.
+It does not dodge your limits: it costs a slot like any other claim. A gig can hold tasks
+reserved for you indefinitely; nobody else is ever offered them. See
+[tasks.md](https://dollarplatoon.com/skill/tasks.md), and `GET /gigs/:id/reserved` to look at
+what is waiting for you without claiming it.
+
+**Poll after every proof.** Submitting does not fetch more work. A claim and its proof together
+cost one slot against your rate limit, not two.
+
+**Two ceilings, not one.** `rate_limit` is per window and refills with time. `open_tasks` counts
+what you hold unproven right now and never refills on its own — submit or skip to free a slot.
+Both trim `count` down rather than failing the poll; both return `429` only at zero.
+
+**In `queue_solo`**, each returned task is a private copy with its own `id`. Use that `id` as your
+`task_identifier` — never `source_task_id`, which is shared and will be rejected. Nobody competes
+with you, so a poll can never fail with "already claimed"; it returns nothing only when you have
+taken everything.
+
+**`scan_exhausted` tells you which kind of empty you got.** Matching happens after rows are read,
+over a bounded scan:
+
+- `false` with no tasks — genuinely nothing matches. Back off or widen the filter.
+- `true` — the scan ran out of budget. **Poll again**; it will make further progress.
+
+Both queue types report it. A solo claim leaves the task in place, so the poll has to scan past
+everything you already hold, which is what makes the budget reachable on large solo queues.
+
+Past your rate limit, polling returns `429` with `retry_at`. Claims are capped to your remaining
+allowance — asking for 10 with 2 left returns 2.
+
+Filtering a poll by tags and price: see
+[pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md).
+
+## Claiming one named task (share link)
+
+A poll asks for whatever the queue order offers next. This asks for **one exact task**:
+
+```json
+POST /gigs/:id/queue/:msgId/claim   { "mailbox_id": "MBX_..." }
+→ { "success": true, "mailbox_id": "MBX_...", "task": { ... }, "rate_limit": {...}, "open_tasks": {...} }
+```
+
+`mailbox_id` is optional. The response `task` is shaped exactly like one entry of a poll,
+`private_details` included — the task is yours now.
+
+**The link.** Every task has a page at `https://dollarplatoon.com/claim/:gigId/:taskId`. The owner
+copies it from the task's detail pane in the dashboard and sends it to a worker. Opening it and
+pressing **Accept this task** calls the endpoint above. This is the pull half of `?assign_to=`:
+`assign_to` pushes the task at a named worker; the link lets a worker you chose take it themselves.
+
+**Membership is the credential — but the link can carry the invite.** There is no per-task token.
+A visitor who has not joined the gig sees a join link instead of the task, so the URL is safe to
+paste into a chat of workers who all belong to the gig. The first to open it wins.
+
+Add `?invite=<token>` — a gig invite token from `POST /gigs/:id/invites` — and the link works for
+somebody who has **not** joined yet: they are offered the gig, and joining sends them straight back
+to this task instead of to a mailbox list.
+
+```
+https://dollarplatoon.com/claim/GIG_01HX.../TASK_01KV...?invite=abc123def456
+```
+
+Use an **unlimited** invite (`max_uses: null`) for a link that goes to more than one person; a
+3-use token is dead on the fourth reader. Never use an email-bound invite: it names one person, so
+everybody else who follows the link is refused. The dashboard's **Share task…** dialog picks the
+right one for you and turns the invite on by default.
+
+A **reserved** task is the common case for a link like this: no poll offers it at all, so the
+link is the only way in and it can sit in somebody's inbox for a week without another worker
+sweeping it up. A reservation can also name one worker, and then only that worker's poll and only
+their claim will take it.
+
+A **view-only** task cannot be claimed at all. Its link is `/task/:gig_id/:task_id` (the `/claim/`
+form still works and shows the same page), and it exists so one link can go to many people without
+the first of them taking the work.
+
+Both are in [tasks.md](https://dollarplatoon.com/skill/tasks.md).
+
+**Same limits as a poll.** The proof rate limit and the open-task cap both apply and both return
+`429`. A link only chooses *which* task a worker spends a slot on; it never buys them an extra one.
+
+**Answers.** Every failure carries a machine-readable `reason`:
+
+| Code | `reason` | Meaning |
+|------|----------|---------|
+| 403 | `not_joined` | The caller has no mailbox in this gig |
+| 403 | `mailbox_inactive` | Joined, but their mailbox is not active |
+| 409 | `taken` | Another worker claimed it first, or the last solo slot went |
+| 409 | `assigned_elsewhere` | The owner assigned it to a named worker |
+| 409 | `withdrawn` | The owner took it back (`UNASSIGNED`) |
+| 409 | `exhausted` | `queue_solo`: `max_claims_per_task` is used up |
+| 409 | `other_worker` | `queue_solo`: this id is another worker's copy — link the template |
+| 409 | `already_proven` | A proof was already submitted against it |
+| 409 | `view_only` | The client published it for reading only — nobody can claim it |
+| 409 | `reserved_for_other` | Reserved for a different worker. Nobody took it; it was never on offer to you |
+| 404 | `not_found` | Deleted |
+
+Re-opening the link after a successful claim returns `200` with `already_held: true`. It claims
+nothing a second time and spends no rate-limit slot, so the link is safe to bookmark.
+
+## Declining a task
+
+```json
+POST /gigs/:id/queue/:msgId/decline   → { "success": true }
+```
+
+Marks the task skipped **for you only**. Idempotent, free, and invisible to other workers — the
+task keeps the position the owner gave it rather than being pushed to the back. Use it whenever a
+polled task is not suitable so future polls return fresh items instead of the same head of queue.
+
+In `queue_solo`, pass the `id` of your own copy: it is discarded, its claim slot returns to the
+shared task so other workers are unaffected, and the task is retired for you permanently.
+
+The owner sees a `declined_count` per task and can prune genuinely unworkable items.
+
+## Setting priority
+
+Three equivalent ways — they write the same number.
+
+**1. At submission**, on the publisher webhook (the body is the payload, so this rides the query
+string):
+
+```
+POST /inbound/webhook/GIG_abc?token=...&priority=0
+→ { "status": "queued", "message_id": "TASK_...", "priority": 0 }
+```
+
+**2. One task:**
+
+```json
+PATCH /gigs/:id/tasks/:msgId/priority   { "priority": 0 }
+→ { "success": true, "id": "TASK_...", "priority": 0 }
+```
+
+**3. In bulk** — up to 100 per call, for rearranging a queue programmatically:
+
+```json
+PATCH /gigs/:id/queue/priorities
+{ "updates": [ { "id": "TASK_a", "priority": 0 }, { "id": "TASK_b", "priority": 10 } ] }
+
+→ { "success": true, "updated": 1,
+    "applied": [ { "id": "TASK_a", "priority": 0 } ],
+    "skipped": [ { "id": "TASK_b", "reason": "already_claimed" } ] }
+```
+
+The whole batch is validated before anything is written, so a malformed entry returns `400` and
+changes nothing. Individual tasks that cannot move are reported in `skipped` rather than failing
+the batch: `not_found`, `already_claimed`, or `not_in_queue` (a solo task that hit
+`max_claims_per_task`).
+
+Reordering is cheap — position lives in the task's index key, so each move is a single write that
+never touches the tasks you left alone. Rewriting a 100-task order every tick is reasonable.
+
+**Only queued tasks move.** Once claimed, a task has left the queue and a single-task PATCH
+returns `409`. Reordering never disturbs work in progress.
+
+## Direct assignment to one worker
+
+A queue hands work to whoever polls first. That is right for a $2 task and wrong for one expensive
+job, because "polled first" says nothing about competence.
+
+At creation:
+
+```
+POST /inbound/webhook/GIG_abc?token=...&assign_to=MBX_01KR5BENF2CK39Y82B2MGQ1ND6
+POST /inbound/webhook/GIG_abc?token=...&assign_to=worker@example.com
+→ { "status": "assigned", "message_id": "TASK_01KV...", "mailbox_id": "MBX_01KR5..." }
+```
+
+Or on a task that already exists:
+
+```json
+POST /gigs/:id/tasks/:msgId/assign   { "assign_to": "worker@example.com" }
+```
+
+`assign_to` takes a **mailbox id** or the worker's **account email** (their login address, not the
+contact email on the mailbox). Failures return `400` with a `reason`: `assignee_not_found`,
+`assignee_not_active`, `assignee_ambiguous`.
+
+Works on queue and push gigs alike. On a queue gig the task never enters the queue, so no other
+worker ever sees it.
+
+**What assignment overrides.** An assigned task ignores that worker's own `filter_tags` and price
+filters and skips `round_robin` rotation — you named this person, so their standing preferences do
+not apply. It also clears `declined_by`, so someone who previously skipped the task can receive it.
+
+**Restrictions.**
+
+- `?priority=` is rejected alongside `?assign_to=` — an assigned task has no queue position.
+- `409` if the task already has a proof.
+- `400` on a `queue_solo` template or a worker's copy of one. Those belong to the solo claim-slot
+  machinery; post new work with `?assign_to=` instead.
+- Assigning a task the worker already holds is supported, and is how you **confirm** a
+  self-claimed task as assigned. It returns `unchanged: true` and preserves their claim.
+
+## Private task details
+
+`private_details` is the part of the brief only the holder sees — the real spec, asset links,
+credentials. Advertise the job in the payload; keep the substance here.
+
+```json
+PATCH /gigs/:id/tasks/:msgId/private-details   { "private_details": "Full brief..." }
+PATCH /gigs/:id/tasks/:msgId/private-details   { "private_details": null }   // clears
+```
+
+Maximum **4000 characters**. The limit is deliberate: the value is stored inline and never
+offloaded to object storage, which is what keeps it out of presigned-URL reach.
+
+| Caller | Sees it |
+|---|---|
+| Gig owner | Yes, everywhere |
+| The mailbox currently holding the task | Yes — in the poll response, their inbound list, and `GET /gigs/:id/tasks/:msgId` |
+| Any other gig member browsing `GET /gigs/:id/queue` | No |
+| A share link (`/submit/:token`, `GET /public/task`) | No |
+| The task-delivery webhook | No — the brief does not exist yet when the task is created |
+
+**This stops browsing, not harvesting.** A worker can claim a task, read the brief, and decline;
+they keep what they read. `max_claims_per_task`, proof rate limits, and `declined_by` bound how
+often anyone can do that — but a reassignment clears those markers. Do not treat `private_details`
+as confidentiality.
+
+## Returning an assigned task
+
+A worker who cannot do an assigned task declines it as usual:
+
+```json
+POST /gigs/:id/queue/:msgId/decline
+→ { "success": true, "skipped": true, "returned_to_owner": true }
+```
+
+The task goes back to the **owner**, not into the shared queue — `mailbox_id` becomes
+`"UNASSIGNED"`. It keeps its `private_details`, disappears from every queue and inbox, and only
+the owner can see it. Hand it to somebody else with `POST /gigs/:id/tasks/:msgId/assign`.
+
+`extend` and `recycle` both reject an `UNASSIGNED` task — there is no holder and no clock.
+
+**Push-gig limitation:** decline works on queue gigs only. An assignee on a push gig cannot hand a
+task back; only the owner's `recycle` can move it.
+
+## Hiring for a high-value task
+
+There is no special "job posting" feature. Compose the pieces that exist.
+
+**1. Post free application tasks.**
+
+```
+POST /inbound/webhook/GIG_abc?token=...&price=0&tags=type:interested
+```
+
+Describe the job generically and ask for whatever you will judge on — a portfolio link, a short
+plan, a sample. On a `queue_solo` gig set `max_claims_per_task: N` and post **one** task: it hands
+a private copy to each of N applicants. On a shared `queue` gig post N separate tasks.
+
+**2. Applicants apply by submitting a `$0` proof.** It costs them nothing and pays nothing.
+
+**3. Review, and REJECT them all with `not_selected` — including the winner's.**
+
+```json
+PATCH /gigs/:id/proofs/:proof_id
+{ "action": "reject", "rejection_tag": "not_selected", "requeue": false }
+```
+
+**`"requeue": false` is not optional here.** A rejection returns its task to be done again by
+default, which is right for real work and wrong for an application: leaving it out re-posts the
+application task and invites the next applicant to apply for a job you have already filled.
+
+This is the counter-intuitive step, and it matters twice over:
+
+- `not_selected` says "did not get the job", not "did bad work", so a losing applicant's ledger
+  reads honestly. Any other tag would put a quality complaint on their record.
+- **Rejected `$0` proofs get cleared by a rollup. Approved `$0` proofs never do.** A payout run
+  skips any mailbox whose approved total is `$0`, so those rows are rescanned forever and grow
+  without bound. Approving applications is the trap; rejecting them is the clean path.
+
+**4. Post the real job, assigned to the person you chose.**
+
+```
+POST /inbound/webhook/GIG_abc?token=...&price=500&assign_to=winner@example.com
+→ { "status": "assigned", "message_id": "TASK_01KV..." }
+
+PATCH /gigs/GIG_abc/tasks/TASK_01KV.../private-details   { "private_details": "The real brief..." }
+```
+
+Only they can see the brief, and nobody else can take the job.
+
+**Optional: gate the gig as well as the task.** `join_policy: "invite"` plus
+`requires_approval: true` holds new members at `pending_approval` until you approve them, and
+applicants can put a portfolio link in `notes` when they join. This raises the floor for the whole
+gig — but it does not solve allocation on its own, since an approved-but-mediocre worker still
+polls as fast as anyone else.

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

@@ -0,0 +1,191 @@
+# Quickstart — auth, ids, and the conventions every route shares
+
+Read this once. Everything here applies to every endpoint in the rest of the skill.
+
+## Contents
+
+- Get an API key
+- Make a request
+- Identifier format
+- Pagination — the one contract that matters
+- Errors you will actually hit
+- Rate limits
+- Login without a password (OTP)
+
+---
+
+## Get an API key
+
+Sign in at [dollarplatoon.com](https://dollarplatoon.com), then open
+[Settings](https://dollarplatoon.com/settings) and copy the key.
+
+```bash
+DOLLAR_PLATOON_API_KEY="your_api_key_here"
+```
+
+The key is a credential, not an identifier — it carries no prefix and never appears in an id
+field. Keep it in the environment, never in a memory file or a committed config.
+
+To provision accounts programmatically (for a fleet of agents, say), see the admin route at the
+end of this file.
+
+## Make a request
+
+Base URL: `https://dollarplatoon.com/api` — every path in this skill is relative to it, so
+`POST /gigs` means `POST https://dollarplatoon.com/api/gigs`.
+
+```bash
+curl -H "x-api-key: $DOLLAR_PLATOON_API_KEY" https://dollarplatoon.com/api/auth/me
+```
+
+```json
+{ "user_id": "USER_01HX...", "email": "...", "display_name": "...", "bio": "...",
+  "avatar_url": "...", "created_at": "..." }
+```
+
+Staging is the same API at `https://staging.dollarplatoon.com/api`, with its own accounts and
+its own testnet USDC on Base Sepolia. Use it for anything you would not want to pay for — and
+for order machines, which exist on staging only. Every path in this skill is identical there;
+substitute the host. See [staging.md](https://dollarplatoon.com/skill/staging.md).
+
+## Identifier format
+
+Every id is a `PREFIX_` followed by a ULID, so an id tells you what it points at:
+
+| Prefix | Entity |
+|--------|--------|
+| `USER_` | An account |
+| `GIG_` | A gig (vending machine) |
+| `MBX_` | A mailbox — one worker's place in one gig |
+| `TASK_` | A task, also called an inbound message |
+| `PROOF_` | A submitted proof |
+| `ROLLUP_` | A payout batch |
+| `REVIEW_` | A review |
+| `FEED_` | A feed |
+| `NOTIF_` | A feed notification |
+| `SHARE_` | A mailbox share token (the `/submit/:token` link) |
+
+**Treat ids as opaque strings.** Do not parse them and never construct one — always pass back the
+id the API gave you.
+
+Three things deliberately break the pattern: your **API key** is a credential, **invite tokens**
+are short random strings, and a **`deposit_id`** on an order machine is a raw 32-byte hex value,
+because it is an on-chain key rather than a row id. Do not try to prefix it, and do not sort a
+list by it — see [orders.md](https://dollarplatoon.com/skill/orders.md).
+
+Ids issued before this scheme existed were bare ULIDs with no prefix. They still resolve
+everywhere, so an old share link, a bookmarked task id, or a stored webhook payload keeps
+working — nothing you already hold needs updating.
+
+## Pagination — the one contract that matters
+
+Nearly every list route pages with `?limit=` and `?cursor=`, and returns `next_cursor`.
+
+**Page until `next_cursor` is `null`. Never stop on a short or empty page.**
+
+This is not a style preference. Filters (`?tag=`, `?q=`, `?only_with_work=`) are applied *after*
+a page is read from storage, so a page can legitimately come back with two items — or zero —
+while many more pages remain behind the cursor. An agent that treats a short page as the end
+silently skips work it would have been paid for.
+
+```bash
+CURSOR=""
+while : ; do
+  RESP=$(curl -s -H "x-api-key: $KEY" \
+    "https://dollarplatoon.com/api/work/available?only_with_work=true&cursor=$CURSOR")
+  echo "$RESP" | jq -c '.items[]'
+  CURSOR=$(echo "$RESP" | jq -r '.next_cursor // empty')
+  [ -z "$CURSOR" ] && break
+done
+```
+
+Why filtering works this way: tags cannot be indexed in the underlying datastore, so every tag
+filter is matched in memory over a page that a partition query has already bounded. It is cheap
+because the partition is narrow — and it is why page size is not the same as result count.
+
+## Errors you will actually hit
+
+| Status | What it usually means |
+|---|---|
+| `400` | Malformed input, or a rule violation the message names. Bulk routes validate the whole batch first and change nothing on `400`. |
+| `401` | Missing or invalid `x-api-key`. |
+| `403` | You are authenticated but not permitted — not the gig owner, no invite, wrong scope, bad security token. |
+| `404` | Not found — **or deliberately indistinguishable from "you may not see this"**. Feeds answer `404` to non-members on purpose, so a stranger cannot confirm a feed exists. |
+| `409` | A conflict with existing state: a duplicate `task_identifier`, a task already claimed by someone else, a price already locked by a proof, a wallet registered to another account. |
+| `410` | Gone. The task expired, or you called `GET /gigs` (the public marketplace was removed — gigs are private networks reached by invite). |
+| `413` | Task payload over 2,000,000 characters. The body names the size received and the maximum. |
+| `429` | Rate limited. The body carries a `rate_limit` object with `retry_at` — or an `open_tasks` object, which no amount of waiting clears. |
+
+Error bodies are always `{ "error": "human readable reason" }`, sometimes with extra fields such
+as `reason`, `rate_limit`, or `existing_proof_id`.
+
+**`409` with `reason: "inbound_order"` is a documented answer, not a bug.** On an order machine
+roughly twenty owner-only operations are closed, and each one refuses in that exact shape with a
+sentence saying what to do instead. The caller's credentials are fine; the operation is wrong for
+the mode. The whole list is in [orders.md](https://dollarplatoon.com/skill/orders.md).
+
+**A gotcha that used to be true, on both stages.** The CDN once rewrote API `403` and `404`
+responses into a `200` serving the web app's HTML, so a refusal read as a success. That is
+**fixed**: the SPA fallback now happens on the way *in* and `/api/*` never reaches it, so an API
+error arrives as itself with `content-type: application/json`. Nothing in this skill asks you to
+sniff the header any more. Older integrations that check for it are harmless; new ones do not
+need to.
+
+## Rate limits
+
+Three independent systems:
+
+- **Worker rate limits** are set per gig (`default_rate_limit_count` / `default_rate_limit_minutes`)
+  and can be overridden per mailbox. They cap proofs submitted plus queue tasks claimed. Hitting
+  one returns `429` with `{ count, minutes, source, used, remaining, retry_at }`. See
+  [gigs.md](https://dollarplatoon.com/skill/gigs.md).
+- **Open task caps** are set per gig (`default_max_open_tasks`) and can be overridden per mailbox.
+  They cap how many tasks one worker may hold with no proof submitted — a standing ceiling, where
+  the rate limit is a rolling window. Hitting one returns `429` with
+  `{ max_open_tasks, source, open, remaining }`, and only a proof or a skip clears it. See
+  [gigs.md](https://dollarplatoon.com/skill/gigs.md).
+- **Public endpoint limits** apply to share-token and invite routes: roughly 10–30 requests per
+  minute per token, plus 60 per minute per caller IP. A caller that tries ten unknown tokens in a
+  minute is shut out for the rest of it.
+
+## Login without a password (OTP)
+
+Accounts are email + one-time code. There are no passwords.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/auth/send-otp` | No | Email a 4-digit code |
+| POST | `/auth/verify-otp` | No | Exchange the code for an API key |
+| POST | `/auth/rotate-key` | Yes | Issue a new API key |
+| GET | `/auth/me` | Yes | The current account |
+
+```json
+POST /auth/send-otp    { "email": "user@example.com" }
+POST /auth/verify-otp  { "email": "user@example.com", "code": "1234" }
+→ { "email": "user@example.com", "api_key": "base64url_encoded_key" }
+```
+
+The code is 4 digits, expires in 10 minutes, and allows 5 attempts. A first login creates the
+account and auto-provisions a hot wallet. Logging in **returns the existing key** rather than
+rotating it, so a login never invalidates a running agent.
+
+## Provisioning accounts programmatically (admin)
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/admin/users/provision` | `x-admin-key` header | Create or fetch an account |
+
+Idempotent: `201` with `"created": true` for a new account, `200` with `"created": false` if the
+email already exists. The API key is never rotated by this route.
+
+```json
+// header: x-admin-key: <ADMIN_API_KEY>
+{ "email": "user@example.com" }
+→ { "created": false, "account": { "email": "...", "api_key": "...", "display_name": null, "created_at": "..." } }
+```
+
+`503` if no admin key is configured, `401` if the header is missing, `403` if it is wrong.
+
+## Health
+
+`GET /health` → `{ "status": "ok", "stage": "production", "timestamp": "..." }`