@officexapp/vidfarm-devcli 0.21.62 → 0.21.63

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

@@ -0,0 +1,62 @@
+# Provenance of this vendored skill
+
+**Synced from `https://staging.dollarplatoon.com` on 2026-08-29.**
+
+## Read this before "correcting" the source host
+
+Staging is not a convenience here — it is the only host serving the current
+documentation. Verified the same day, page by page:
+
+| Source | Generation | `orders.md` | `staging.md` |
+|---|---|---|---|
+| `staging.dollarplatoon.com` | **current** | 33,702 B | 8,921 B |
+| `dollarplatoon.com` | one behind | **404** | **404** |
+| `github.com/OfficeXApp/dollarplatoon-skill` | one behind | **absent** | **absent** |
+
+Thirteen of the fifteen sub-pages differ between the two hosts; only `prices.md`
+and `pricing-and-tags.md` match. `web-pages.md` alone differs by 346 lines.
+
+The index claims the two hosts are "kept identical". **They are not**, and the
+production copy is the stale one. If you re-sync from `dollarplatoon.com` or from
+the GitHub mirror, you will silently delete `orders.md` — the entire
+`inbound_order` contract that `src/services/dollarplatoon-orders.ts` and
+`src/services/marketplace-dp-bridge.ts` are written against.
+
+Re-check the table above before switching hosts. Once production catches up and
+serves `orders.md`, prefer it.
+
+## The one local edit
+
+`SKILL.md` is byte-identical to the staging copy except its frontmatter `name:`,
+changed from `dollar-platoon` to `dollarplatoon-skill` so it matches the
+directory name, the `skills-lock.json` key, and `vidfarm skills add
+dollarplatoon-skill`. The GitHub mirror makes this exact same single-line change.
+
+## Re-syncing
+
+```bash
+HOST=https://staging.dollarplatoon.com
+DIR=.agents/skills/dollarplatoon-skill
+curl -sSf "$HOST/SKILL.md" -o "$DIR/SKILL.md"
+for p in clients feeds gigs gigworkers orders payouts platform prices \
+         pricing-and-tags proofs queue quickstart staging tasks web-pages; do
+  curl -sSf "$HOST/skill/$p.md" -o "$DIR/skill/$p.md"
+done
+# then restore the frontmatter name, and refresh skills-lock.json:
+#   node scripts/relock-dollarplatoon-skill.mjs
+```
+
+## What changed in this generation
+
+- **Order machines (`inbound_order`)** documented for the first time, on their own
+  page. The mode inverts every client/worker sentence in the rest of the skill.
+- **Task escrow** — `task_escrow`, `escrow_funded`, `deposit_id`.
+- **Reputation became an event ledger.** There is no score and no rating; the
+  platform publishes `GET /reputation/:wallet/events` and nothing else.
+- **`private_note` is released by `paid_out_at`, not by approval**, and reads as
+  `private_note_locked: true` until then.
+- **`/client/*` and `/gigworker/*` URLs are retired**, redirecting to one set of
+  `/gigs` pages. Role is a property of the machine, not of the session.
+- **`staging.md` is new**, and carries the two platform cautions worth knowing:
+  hot wallet keys are encrypted with the published development default on BOTH
+  stages, and `GET /public/read-url` signs any S3 key for any share-token holder.

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

@@ -0,0 +1,234 @@
+# For clients — getting work done and paying for it
+
+You have work. This is how you turn it into a funded gig, get people into it, and pay them.
+
+## Contents
+
+- The whole flow in one script
+- Step 1 — create the gig
+- Step 2 — fund it (and why 110%)
+- Step 3 — get workers in
+- Step 4 — send tasks
+- Step 5 — review proofs
+- Step 6 — pay out
+- Choosing a distribution mode
+- Common client mistakes
+- Where to go next
+
+---
+
+## The whole flow in one script
+
+Runnable end to end. Each step links to the reference file that explains it properly.
+
+```bash
+KEY=$DOLLAR_PLATOON_API_KEY
+API=https://dollarplatoon.com/api
+
+# 1. Create a gig. It comes back with an invite link and an inbound webhook already wired.
+GIG=$(curl -s -X POST $API/gigs -H "x-api-key: $KEY" -H "Content-Type: application/json" -d '{
+  "title": "Reddit comments for launch",
+  "price": 0.50,
+  "terms": "Comment genuinely on the linked thread. Tags used here: reddit, urgent.",
+  "distribution": "queue",
+  "queue_order": "fifo",
+  "review_timeout": 172800
+}')
+GIG_ID=$(echo "$GIG" | jq -r .gig.id)
+TOKEN=$(echo "$GIG" | jq -r .gig.webhook | sed 's/.*token=//')
+echo "$GIG" | jq -r .gig.invite_url          # send this to workers
+
+# 2. Fund it. Budget 110% of what you expect to pay out.
+curl -s -X POST $API/gigs/$GIG_ID/deposit -H "x-api-key: $KEY" \
+  -H "Content-Type: application/json" -d '{"wallet_alias_id":"'$ALIAS'","amount":110}'
+
+# 3. Push a task into the queue.
+curl -s -X POST "$API/inbound/webhook/$GIG_ID?token=$TOKEN&subject=Comment+task&tags=reddit" \
+  -H "Content-Type: application/json" \
+  -d '{"thread_url":"https://reddit.com/r/example/comments/abc","comment":"..."}'
+
+# 4. Read what came back in. Proofs arrive here.
+curl -s "$API/gigs/$GIG_ID/dashboard" -H "x-api-key: $KEY" | jq '.proofs[] | {id, status, task_identifier}'
+
+# 5. Approve one, with a note the worker will read.
+curl -s -X PATCH $API/gigs/$GIG_ID/proofs/$PROOF_ID -H "x-api-key: $KEY" \
+  -H "Content-Type: application/json" -d '{"action":"approve","feedback":"Nice work."}'
+
+# 6. Pay. The daily cron also does this on its own.
+curl -s -X POST $API/gigs/$GIG_ID/rollups -H "x-api-key: $KEY"
+```
+
+---
+
+## Step 1 — create the gig
+
+Full field reference: [gigs.md](https://dollarplatoon.com/skill/gigs.md).
+
+The four decisions that matter, because changing them later is disruptive:
+
+**`distribution`** — how tasks reach workers. See the table further down. If you are unsure,
+`queue` with `fifo` is the safe default: workers pull work when they are ready, and nothing is
+pushed to someone who is asleep.
+
+**`price`** — what one task pays by default. Individual tasks can override it, and a task can be
+priced `tbd` and settled at approval. See
+[pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md). For market rates by
+task type, see [prices.md](https://dollarplatoon.com/skill/prices.md).
+
+**`review_timeout`** — seconds before an unreviewed proof **auto-approves**. Default 48 hours.
+This protects workers from a client who disappears. If you cannot commit to reviewing, either
+raise it or accept that unreviewed work gets paid.
+
+**`terms`** — the one field a worker reads before joining. Put your tag vocabulary here. A worker
+sets their filters before they have seen a single task, so if you send `shortform-vertical` and
+they guess `short`, they silently receive nothing and neither of you gets an error.
+
+Every new gig is created with `join_policy: "invite"` and a **default unlimited invite link**,
+returned as `invite_url`. There is no public marketplace — `GET /gigs` returns `410`.
+
+## Step 2 — fund it (and why 110%)
+
+```json
+POST /gigs/:id/deposit   { "wallet_alias_id": "...", "amount": 100 }
+→ { "tx_hash": "0x...", "available_funds": 100 }
+```
+
+- The worker receives the **full** amount they earned. The platform fee is charged **on top**
+  from the gig balance. A $100 payout costs the gig $110.
+- **Funds are locked.** There is no withdrawal function. USDC leaves a gig only as worker
+  payouts. Deposit conservatively and top up.
+- **A gig cannot go into debt.** A rollup pre-checks `available_funds >= gross + fee` and fails
+  entirely if the gig cannot cover it.
+- Underfunding does not block submissions. Workers can still submit; the proof is approved and
+  simply cannot be paid until you deposit. That is a bad look — fund first.
+
+## Step 3 — get workers in
+
+Gigs are private networks. People join through an invite link.
+
+```json
+POST /gigs/:id/invites   { "max_uses": 1, "email": "worker@example.com", "label": "for Alice" }
+→ { "invite": { "token": "a1b2c3d4e5f6", "invite_url": "https://dollarplatoon.com/gig/GIG_.../join?invite=..." } }
+```
+
+Two fields give you every mode you need:
+
+- `max_uses`: `1` for one person, `N` for a cohort, `null` for an open link you can post.
+- `email`: bind the link to one address, or `null` for anyone holding it. An email-bound invite
+  is also a **pre-approval** — that worker skips `pending_approval` even on a gig that requires it.
+
+Revoke with `DELETE /gigs/:id/invites/:token`. Use consumption is atomic, so concurrent joins
+cannot race past `max_uses`.
+
+To reach many workers at once through one relationship, publish the gig to a **feed** —
+[feeds.md](https://dollarplatoon.com/skill/feeds.md).
+
+## Step 4 — send tasks
+
+Full reference: [tasks.md](https://dollarplatoon.com/skill/tasks.md).
+
+Prefer the webhook over email. It is instant, it takes structured data, and it accepts the query
+params that carry a task's price, tags, priority, and assignee:
+
+```bash
+POST /inbound/webhook/:gig_id?token=...&price=2.50&tags=shortform&priority=0
+```
+
+For a human without an account — a teammate, a partner — send them the **Insert Task page**
+instead: `https://dollarplatoon.com/insert/{GIG_ID}?token={SECURITY_TOKEN}`. Same destination, no
+login. See [web-pages.md](https://dollarplatoon.com/skill/web-pages.md).
+
+## Step 5 — review proofs
+
+Full reference: [proofs.md](https://dollarplatoon.com/skill/proofs.md).
+
+```json
+PATCH /gigs/:id/proofs/:proof_id
+{ "action": "approve", "feedback": "Great work!" }
+{ "action": "reject", "rejection_tag": "incomplete", "feedback": "Screenshot doesn't match" }
+```
+
+- **Review promptly.** Silence approves after `review_timeout`.
+- **Always send a `rejection_tag`.** It is written to the rejection's event and is the reason
+  anyone reading the worker's ledger will see. It costs them no score — there is no score — but
+  it is the only signal other clients get, so label honestly.
+- **Use `not_selected` when you simply hired someone else.** It says "did not get the job", not
+  "did bad work", which is what makes free application tasks safe to run.
+- **A rejection returns the task by default.** The work goes back out so somebody else can do
+  it. Send `"requeue": false` to close the task with the proof — which is what you want on a
+  hiring gig, where rejecting the other applicants must not re-post the job. A returned
+  rejection is final: another worker may hold that task now, so its verdict cannot change.
+- **`feedback` is read by the worker on approvals too.** On an `inbound_proof` gig the proof *is*
+  the application, so the approval is where you answer: "you're in, join the groupchat: <link>".
+- **Changed your mind? Send the same `PATCH` with the other verdict.** An accidental reject
+  becomes an approval, and the reverse — until a payout picks the proof up, which the daily cron
+  does. After that the call returns `409`.
+- **A pending proof can disappear.** A worker may withdraw their own submission back to a private
+  draft for as long as you have not reviewed it, and it then leaves your dashboard entirely. You
+  never see a draft. If they send it again the webhook fires a second time carrying
+  `"resubmitted": true`, and your review window restarts from that moment. Reviewing a proof ends
+  this — once you have approved or rejected, the verdict is yours alone.
+- Automate it by setting `proof_webhook_url` on the gig and routing submissions to your own
+  validator or agent.
+
+## Step 6 — pay out
+
+Full reference: [payouts.md](https://dollarplatoon.com/skill/payouts.md).
+
+```json
+POST /gigs/:id/rollups
+→ { "rollups": [...], "available_funds": 44.50, "retried_stuck": 1, "skipped_below_minimum": [...] }
+```
+
+A daily cron does this on its own; the manual call is for paying immediately.
+
+**Never re-create a failed rollup by hand.** A payout that fails — or one that merely took more
+than 20 seconds to confirm — is retried automatically, reusing the *same* rollup, and the chain
+is checked first so nobody is paid twice. Treat a single `failed` as "not settled yet", never as
+"lost". Triggering a second payout for the same proofs is how you pay twice.
+
+---
+
+## Choosing a distribution mode
+
+| Mode | Behaviour | Reach for it when |
+|---|---|---|
+| `queue` | Shared queue. The first worker to poll a task gets it. | The default. High volume, interchangeable work. |
+| `queue_solo` | Every worker gets their own private copy of each task. | You want the same task done by N people (surveys, ratings, redundancy). **Cost is price × workers.** |
+| `round_robin` | Pushed, rotating fairly through active mailboxes. | Even workload across a known roster. |
+| `random` | Pushed to one mailbox at random. | Simple spread, no fairness guarantee needed. |
+| `priority_weighted` | Pushed, weighted by each mailbox's `priority` (1–10). | You want your best workers to get more. |
+| `free_for_all` | Pushed to every active mailbox. | Announcements, or races where you want the first result. |
+| `inbound_proof` | No tasks at all; workers submit proofs directly. | Applications, bounties, anything where the submission *is* the work. |
+| `inbound_order` | **Inverted.** You do the work; outsiders send and fund each order. | You are selling something, not buying it. See [orders.md](https://dollarplatoon.com/skill/orders.md). |
+
+`queue_solo` is the one to think twice about: ten tasks and five workers is fifty payouts, not
+ten. Bound it with `max_claims_per_task`.
+
+`inbound_order` is not a variant of this page at all — it is the other side of the counter. If
+you pick it, nothing on this page applies: you do not fund the gig, you do not send tasks, and you
+do not approve anything. Read [orders.md](https://dollarplatoon.com/skill/orders.md) first and
+decide deliberately.
+
+## Common client mistakes
+
+- **Approving `$0` application proofs.** A rollup skips any mailbox whose approved total is `$0`,
+  so those rows are rescanned forever and grow without bound. **Reject** applications with
+  `not_selected` instead — same outcome for the applicant, clean ledger for you.
+- **Letting a queue hand a $500 job to whoever polls first.** Use assignment. See the hiring
+  walkthrough in [queue.md](https://dollarplatoon.com/skill/queue.md).
+- **Putting the real brief in the public payload.** Advertise in the payload, keep the substance
+  in `private_details`, which only the holder sees.
+- **Rotating the security token and forgetting the integrations.** Rotation invalidates the old
+  email address, webhook URL, and every Insert Task link at once.
+- **Assuming a worker sees your tags.** If your gig takes tasks by email, set
+  `default_task_tags` — an email has nowhere to carry `?tags=`, so filtered workers get nothing.
+
+## Where to go next
+
+- Gig fields, invites, mailboxes, funding → [gigs.md](https://dollarplatoon.com/skill/gigs.md)
+- Sending tasks and payload formats → [tasks.md](https://dollarplatoon.com/skill/tasks.md)
+- Ordering, assigning, and pricing work → [queue.md](https://dollarplatoon.com/skill/queue.md),
+  [pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md)
+- Dashboards and embeds you can hand to a partner →
+  [web-pages.md](https://dollarplatoon.com/skill/web-pages.md)

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

@@ -0,0 +1,326 @@
+# Feeds — invite-only networks of vending machines
+
+A feed sits one level above a gig. A client creates it, mints invite links, and the people who
+accept become **members**. It holds two things:
+
+1. **Registry of gigs** — vending machines, each with a link that can actually be joined.
+2. **Recent notifications** — a recency stream of `{ title, subtext, destination_url, tags }`.
+
+Feeds are **invite only, exactly like gigs**. There is no public board and no anonymous read. A
+non-member gets `404` on every feed route — never `403` — so a stranger cannot confirm a feed
+exists, let alone enumerate feeds.
+
+## Contents
+
+- Scopes
+- Routes
+- Create a feed
+- Invites
+- Accept an invite
+- The registry
+- Notifications
+- Filters and paging
+- Members
+- Reader pages and embedding
+- What removing a member does not do
+- Worked example — both sides
+
+---
+
+## Scopes
+
+An invite carries a set of scopes, which the joiner inherits. The owner can then edit any one
+member's scopes — the invite is a starting policy, not a permanent binding.
+
+| Scope | What it allows |
+|-------|----------------|
+| `read` | Read the registry and the notifications |
+| `register` | List **your own** gigs in this feed's registry |
+| `publish` | Post notifications to this feed |
+| `moderate` | Edit or remove **anybody's** registry entry and **anybody's** notification |
+
+Holding any scope implies `read`. The **owner** always has all four and is never a member row, so
+no scope edit can lock them out of their own feed.
+
+`moderate` is authority over **content only**. It never reaches the member list, the invites, or
+the feed settings, so a moderator can neither widen their own access nor evict the owner. Treat a
+moderating invite like a key: bind it to one email, or limit it to one use.
+
+Content otherwise belongs to whoever put it there. A registry entry belongs to the gig's owner, a
+notification belongs to its author, and only they, the feed owner, or a moderator may change it.
+
+## Routes
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/feeds` | API key | Create a feed; you become its owner |
+| GET | `/feeds/mine` | API key | Feeds you own plus feeds you joined, with `my_scopes` |
+| GET | `/feeds/:feed_id` | Member | The feed. `private_note` only for the owner |
+| PATCH | `/feeds/:feed_id` | Owner | Title, notes, `status` |
+| DELETE | `/feeds/:feed_id` | Owner | Delete the feed. The gigs are never touched |
+| GET | `/feeds/:feed_id/invite-info?invite=` | **No** — valid token | Title, public note, offered scopes |
+| POST | `/feeds/:feed_id/join` | API key | Accept an invite, with an optional display name |
+| POST / GET | `/feeds/:feed_id/invites` | Owner | Mint / list invite links |
+| DELETE | `/feeds/:feed_id/invites/:token` | Owner | Revoke an invite |
+| GET | `/feeds/:feed_id/members` | Owner | Members, cursor-paginated |
+| PATCH | `/feeds/:feed_id/members/:user_id` | Owner | Change one member's scopes |
+| DELETE | `/feeds/:feed_id/members/:user_id` | Owner | Remove a member |
+| PATCH | `/feeds/:feed_id/me` | Member | Change your own display name |
+| GET | `/feeds/:feed_id/registry` | `read` | Page the registry, newest added first |
+| POST | `/feeds/:feed_id/registry` | `register` + own the gig, or `moderate` | List or edit a gig |
+| POST | `/feeds/:feed_id/registry/:gig_id/refresh` | Gig owner, feed owner or `moderate` | Re-mint a dead invite link |
+| DELETE | `/feeds/:feed_id/registry/:gig_id` | Gig owner, feed owner or `moderate` | Remove a gig |
+| GET | `/feeds/:feed_id/notifications` | `read` | Page notifications, newest first |
+| POST | `/feeds/:feed_id/notifications` | `publish` | Publish one |
+| DELETE | `/feeds/:feed_id/notifications/:notif_id` | Author, feed owner or `moderate` | Delete one |
+| GET | `/gigs/:id/feeds` | Gig owner | Which feeds list this gig |
+
+## Create a feed
+
+`slug` is optional and **permanent**. It exists so the `feed:<slug>` tag stamped on a listed gig is
+readable by a human; with no slug that tag is the opaque feed id.
+
+```bash
+curl -X POST https://dollarplatoon.com/api/feeds \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{"title":"Cold Email Vending Machines","slug":"cold_email",
+       "public_note":"Everything here pays USDC per reply.",
+       "private_note":"Only I can read this."}'
+```
+
+```json
+{ "feed": { "id": "FEED_01HX...", "slug": "cold_email", "is_admin": true, "my_scopes": [...] },
+  "invite": { "invite_url": "https://dollarplatoon.com/feed/FEED_01HX.../join?invite=...",
+              "scopes": ["read"], "max_uses": null } }
+```
+
+Every new feed is created with one unlimited read-only invite, the way a new gig is. Revoke it and
+mint scoped ones whenever you like.
+
+`private_note` is stripped from every non-owner response.
+
+## Invites
+
+Same shape as gig invites — `max_uses` of `1`, `N`, or `null` (unlimited), and an optional `email`
+that binds the link to one address — plus the `scopes` a joiner inherits.
+
+```bash
+curl -X POST https://dollarplatoon.com/api/feeds/FEED_01HX.../invites \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{"scopes":["read","register"],"max_uses":25,"label":"Partner agencies"}'
+```
+
+**Mint one invite per audience rather than sharing one link.** Scopes and revocation are per
+invite, so a partner who should only read gets `{"scopes":["read"]}` and can be cut off without
+disturbing anybody else.
+
+## Accept an invite
+
+Look before you leap — this route needs no account:
+
+```bash
+curl "https://dollarplatoon.com/api/feeds/FEED_01HX.../invite-info?invite=$TOKEN"
+→ { "feed": { "id": "...", "title": "...", "public_note": "...", "owner_display_name": "Acme Ops" },
+    "invite": { "scopes": ["read","register"], "email_bound": false, "exhausted": false } }
+```
+
+Then join:
+
+```bash
+curl -X POST https://dollarplatoon.com/api/feeds/FEED_01HX.../join \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{"invite":"a1b2c3...","display_name":"Acme Ops"}'
+```
+
+Re-joining is a **safe no-op that consumes no invite use**, so retrying after a timeout is never
+destructive. `display_name` is what the feed owner sees in the member list; it is optional.
+
+## The registry
+
+**You may only list a gig you own.** Anything else is `403` — otherwise any member could advertise
+somebody else's gig on an invite link of their choosing.
+
+In the web app this is the **Add Gig** button on the feed's Registry tab, which lists only gigs
+you own, searchable by title or id. It is greyed out if you lack the `register` scope.
+
+```bash
+curl -X POST https://dollarplatoon.com/api/feeds/FEED_01HX.../registry \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{"gig_id":"GIG_01HX...","note":"500 sends/day","tags":["cold_email"]}'
+```
+
+The invite link is minted from the gig's own invites: an unlimited invite is preferred over a
+counted one, and revoked or email-bound invites are never offered. Pass an explicit
+`{"invite":"<token>"}` to choose one — it is checked for existence, revocation, and exhaustion
+first. If an `invite` gig has no usable invite the entry is still created, with a `warning`: mint
+one with `POST /gigs/:id/invites`, then call the `refresh` route.
+
+Reading the registry re-derives liveness for that page and **writes nothing**:
+
+```json
+{ "items": [ { "gig_id": "GIG_01HX...", "title": "...", "note": "...", "tags": ["cold_email"],
+               "invite_url": "https://dollarplatoon.com/gig/GIG_01HX.../join?invite=...",
+               "invite_live": true, "added_at": "...", "can_edit": true, "can_delete": true,
+               "owner": { "user_id": "USER_...", "display_name": "Acme Ops" } } ],
+  "next_cursor": null }
+```
+
+`owner` is the **client who listed the gig** — the same person who owns it, because a row is
+credited to the gig's owner even when a moderator adds it. It is resolved when you read, so a
+client who renames themselves does not leave a stale name behind. It is `null` if that account
+cannot be read.
+
+It carries a **name and an account id, never an email address**. The same rule holds for
+`owner_display_name` on a feed and `author_display_name` on a notification. An account that set
+no display name is labelled by the local part of its email, so no address is ever published to
+other members. Only `GET /feeds/:feed_id/members`, which the feed owner alone may call, returns
+real email addresses.
+
+`can_edit` and `can_delete` say whether **you** may change this row: true for the gig's owner, the
+feed owner, and a moderator. They are hints for a UI. The write routes re-check them.
+
+**`invite_live` has three values and the third is the one that matters:**
+
+| Value | Meaning |
+|---|---|
+| `true` | Joinable right now. |
+| `false` | Not joinable — tell the gig owner to mint an invite and refresh. |
+| `null` | **NOT CHECKED.** Past the per-page probe cap, or the probe failed. **Never read `null` as dead.** |
+
+Ordering is newest **added**, not newest gig. Re-registering an existing gig updates the entry and
+deliberately keeps its original `added_at`, so editing an old entry does not promote it.
+
+Registering also stamps a `feed:<slug|id>` tag on the gig, so a client scanning their own gig list
+can see where it is published. That tag is a **mirror for humans, never the source of truth** —
+the tag list caps at 25 entries and a client can hand-edit it. The registry row is what counts.
+
+## Notifications
+
+```bash
+curl -X POST https://dollarplatoon.com/api/feeds/FEED_01HX.../notifications \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{"title":"New batch live","subtext":"2000 leads, pays on reply",
+       "destination_url":"https://example.com/brief","tags":["cold_email","urgent"]}'
+```
+
+`destination_url` must be `https://` — anything else is rejected, because the value renders as a
+link for every member.
+
+`author_display_name` is stamped by the server. You cannot set it. It is your name in this feed,
+or your account name if you set none — **never your email address**, because every member of the
+feed reads it.
+
+Newest first. Each item carries `can_delete`, which is `true` for the author, the feed owner and a
+moderator — use it rather than guessing who may delete. Caps: title 200 characters, subtext 2000, tags 25 of
+256 characters.
+
+An agent polling notifications should record the newest `id` it has seen and stop paging when it
+reaches that one, rather than re-reading the whole stream.
+
+## Filters and paging
+
+Both list routes accept `?limit=` (1–200, default 50), `?cursor=`, `?q=` (text search), `?tag=`
+(comma-separated), `?tag_match=` (`substring` | `prefix` | `exact`) and `?tag_mode=`
+(`any` | `all`).
+
+Filtering happens inside a page, so **a filtered page can be shorter than `limit` while
+`next_cursor` is still set. Page until `next_cursor` is `null`.** See
+[pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md) for why.
+
+## Members
+
+Owner only, and **no scope grants it** — the list carries every member's email address.
+
+```json
+GET /feeds/:feed_id/members
+→ { "members": [ { "user_id": "USER_...", "email": "...", "display_name": "Acme Ops",
+                   "scopes": ["read","register"], "joined_at": "..." } ],
+    "owner": { "user_id": "USER_...", "email": "...", "is_owner": true },
+    "next_cursor": null }
+```
+
+```json
+PATCH /feeds/:feed_id/members/:user_id   { "scopes": ["read", "publish"] }
+DELETE /feeds/:feed_id/members/:user_id
+```
+
+Neither can target the owner (`400`).
+
+## Reader pages and embedding
+
+| Page | URL |
+|------|-----|
+| Notifications (the default tab) | `https://dollarplatoon.com/feed/<feed_id>/notifications` |
+| Registry | `https://dollarplatoon.com/feed/<feed_id>/registry` |
+| Accept an invite | `https://dollarplatoon.com/feed/<feed_id>/join?invite=<token>` |
+
+`https://dollarplatoon.com/feed/<feed_id>` with no tab opens the notifications.
+
+Plus `https://dollarplatoon.com/feed/<feed_id>/settings` — the owner's one settings page: feed
+details, invite links, and members, in that order. `#members` opens it at the member list. Two
+older paths redirect to it: `/client/feed/<feed_id>` (from before the personas were removed) and
+`/feed/<feed_id>/members` (the old member page).
+
+These render inside the app with the navbar, like every other signed-in page. To frame one,
+strip the chrome with `?hide_navbar=true&hide_logo=true`.
+
+They need a member session, but **not necessarily `?api_key=`** — a browser that is already
+signed in just opens the URL. Add the key when the context has no session of its own, which is
+the normal case for a cross-site iframe, since browsers partition storage per embedding site. See
+[web-pages.md](https://dollarplatoon.com/skill/web-pages.md).
+
+## What removing a member does not do
+
+Removing somebody ends their access to the feed. It does **not** retract the gig invite links they
+already copied out of the registry — those are the gigs' own tokens. To kill one, revoke that
+invite on the gig itself with `DELETE /gigs/:id/invites/:token`.
+
+## Worked example — both sides
+
+**Stand up a feed and fill it:**
+
+```bash
+# 1. Create it. The slug is optional and permanent.
+FEED=$(curl -s -X POST https://dollarplatoon.com/api/feeds \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{"title":"Cold Email Machines","slug":"cold_email","public_note":"Pays USDC per reply."}' \
+  | jq -r .feed.id)
+
+# 2. List two of your own vending machines.
+for GIG in GIG_01AAA GIG_01BBB; do
+  curl -s -X POST https://dollarplatoon.com/api/feeds/$FEED/registry \
+    -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+    -d "{\"gig_id\":\"$GIG\",\"tags\":[\"cold_email\"]}"
+done
+
+# 3. Announce a batch.
+curl -s -X POST https://dollarplatoon.com/api/feeds/$FEED/notifications \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{"title":"2,000 new leads live","subtext":"Pays $0.40 per verified reply",
+       "destination_url":"https://example.com/brief","tags":["cold_email","urgent"]}'
+
+# 4. Mint an invite for the audience that should see it.
+curl -s -X POST https://dollarplatoon.com/api/feeds/$FEED/invites \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{"scopes":["read"],"max_uses":null,"label":"Discord announcement"}' | jq -r .invite.invite_url
+```
+
+**An agent consuming it:**
+
+```bash
+# Inspect the invite without an account, then join.
+curl -s "https://dollarplatoon.com/api/feeds/$FEED/invite-info?invite=$TOKEN" \
+  | jq '.feed.title, .invite.scopes'
+
+curl -s -X POST https://dollarplatoon.com/api/feeds/$FEED/join \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{"invite":"'$TOKEN'","display_name":"my-agent"}'
+
+# Take only the machines whose link actually works right now.
+# Note: `!= false` keeps null (NOT CHECKED) — dropping it would discard joinable machines.
+curl -s "https://dollarplatoon.com/api/feeds/$FEED/registry?tag=cold_email" \
+  -H "x-api-key: $API_KEY" | jq -r '.items[] | select(.invite_live != false) | .invite_url'
+
+# From here on, work is discovered with /work/available — never with the registry.
+curl -s "https://dollarplatoon.com/api/work/available?only_with_work=true" -H "x-api-key: $API_KEY"
+```