@officexapp/vidfarm-devcli 0.21.62 → 0.21.63

package/.agents/skills/dollarplatoon-skill/skill/web-pages.md

@@ -0,0 +1,586 @@
+# Web pages, deep links, and embeds
+
+Every page you can hand to somebody or frame inside your own product, and the URL params that
+control them.
+
+## Contents
+
+- What it is called, and what the URL calls it
+- Role belongs to the VENDING MACHINE, not to you
+- Autologin deep links
+- Universal URL params
+- Vending Machine pages — the list, one machine, the work inbox
+- Order pages — placing one, and watching one
+- The Task page — one task, on a page of its own
+- Notifications — the bell in the navbar
+- The Share Proof link — one proof, on its own review page
+- The Insert Task page — put work in without an account
+- The Submit page — hand in work without an account
+- Feed reader pages
+- Timeline pages
+- Iframe rules that actually matter
+- Page map
+- The older URLs — three generations, all of them live
+
+---
+
+## What it is called, and what the URL calls it
+
+The product word is **Vending Machine**. That is what the app says on screen, in the nav, and in
+every heading, and it is the word to use when you write to a user.
+
+The URL and the API say **gig**: the pages live under `/gigs`, the entity is a `Gig`, and you read
+one with `GET /gigs/:id`. That is deliberate. An identifier has to hold still while a product word
+is allowed to move, and this one has moved twice already. So:
+
+| | Word | Where |
+|---|---|---|
+| On screen | Vending Machine | Headings, nav, buttons, anything a person reads |
+| In the URL and the API | `gig` / `/gigs` | Paths, request bodies, responses, ids |
+
+Below, "machine" is used as the short form in prose. It means the same thing as "vending machine";
+the full phrase is spelled out where it is the name of something rather than a reference to it.
+
+**Do not build a link with the singular `/gig/:id`** unless you mean the *public* gig page — that
+path and `/gig/:id/join` are a different, unauthenticated family, and live invite links point at
+them. The signed-in pages are all plural.
+
+## Role belongs to the VENDING MACHINE, not to you
+
+**There is no persona toggle, and the URL never says which side you are on.** This is the single
+biggest thing to know before you build a link.
+
+The app used to have two halves — `/client/*` for someone who had work, `/gigworker/*` for
+someone who did it — and a switch between them. That was always a lie about one machine in
+particular: on an order machine (`inbound_order`) the **owner does the work** and an **outsider
+pays**, so "am I the client or the worker today" had no single answer. It was also a real dead
+end, because a vendor who never found the toggle could not fill a single order.
+
+So the personas are gone. There is one account, and for each machine you are either its **Owner**
+or a **Participant** in it. `/gigs/:id` is the only path to a machine, and it renders itself
+from two facts: whether you own it, and what mode it is in.
+
+| You | Machine | What `/gigs/:id` shows |
+|---|---|---|
+| Owner | outbound | The dashboard — tasks, proofs, mailboxes, payouts. |
+| Owner | `inbound_order` | The **shop** (price, escrow, invites, members) *and* your order inbox, on two tabs. A vending machine is the one machine whose owner is also its worker. |
+| Participant | outbound | Your work inbox, scoped to this machine. |
+| Participant | `inbound_order` | Place an order, and the orders you have already placed here. |
+
+Everything under `/client/*`, `/gigworker/*` and `/machine*` still redirects, in one hop, and the
+redirects are kept well past the 90-day life of any stored link. Nothing you already hold is
+broken — but a link you *build* today should use the paths below, or every visitor takes an extra
+hop. The full three-generation table is at the end of this page.
+
+## Autologin deep links
+
+Append `?api_key=` to **any** dollarplatoon.com URL to log in and land on that exact page in one
+step. This is how an agent, an email, or a partner site sends somebody straight to a machine.
+
+```
+https://dollarplatoon.com/gigs/GIG_01HX...?api_key=YOUR_API_KEY
+https://dollarplatoon.com/gigs/inbox?api_key=YOUR_API_KEY
+https://staging.dollarplatoon.com/gigs?api_key=YOUR_STAGING_KEY
+```
+
+- The key is validated, the session stored, and `api_key` is **immediately scrubbed** from the
+  address bar and browser history. Other query params survive.
+- Already logged in with the same key? The page loads directly, no redirect or flicker.
+- Logged in as somebody else? The URL's key wins and the session switches.
+- Invalid key? Any existing session is kept; otherwise you land on the page logged out.
+
+There is also `/auto-login?api_key=...&redirect=/path` (relative paths only), but the universal
+param above is simpler.
+
+> **A URL containing `api_key` grants full account access to anyone who sees it.** Send autologin
+> links over private channels only. Never post one publicly, never put one in a shared document,
+> and never bake one into a public page's HTML.
+
+## Universal URL params
+
+These work on any page and compose with `?api_key=`.
+
+| Param | Effect |
+|---|---|
+| `hide_navbar=true` | Removes the top navbar entirely (it occupies no space). Ideal for embeds. |
+| `hide_logo=true` | Removes every brand mark: navbar logo and wordmark, footer brand block, share-page header, and the "Powered by" line. For whitelabel embeds. |
+| `view_only_gigs=id1,id2` | On `/gigs/inbox`, restricts to mailboxes in those machines (unread counts and timelines scope too). A banner offers "Show all". |
+
+Both `hide_*` params persist for the browser tab across in-app navigation; pass `=false` to undo.
+The footer legal text and the Terms/Privacy links always stay.
+
+**`view_only_gigs` applies to the work inbox only.** It used to narrow the owner's gig list as
+well, on the old `/client/gigs`. The machines list at `/gigs` does **not** read it — a list
+that mixes machines you own with machines you take part in has no single thing to filter. Narrow
+the inbox, or link straight to `/gigs/:id`.
+
+```
+# A participant's work inbox for two machines, chrome-free
+https://dollarplatoon.com/gigs/inbox?api_key=KEY&view_only_gigs=GIG_01AAA,GIG_01BBB&hide_navbar=true
+
+# Fully whitelabel
+https://dollarplatoon.com/gigs/inbox?api_key=KEY&hide_navbar=true&hide_logo=true
+
+# A whitelabel public submit page (no key needed — the share token is the credential)
+https://dollarplatoon.com/submit/SHARE_TOKEN?hide_logo=true
+```
+
+## Vending Machine pages — the list, one machine, the work inbox
+
+| Page | What it is |
+|---|---|
+| `/gigs` | Every machine this account touches. Owned and participating in one list, told apart by a badge, never by a mode the session is in. |
+| `/gigs/new` | Deploy a vending machine. |
+| `/gigs/:id` | One machine. Renders by ownership **and** mode — see the table at the top. |
+| `/gigs/:id/inbox` | The owner's own order inbox on a vending machine. The other half of `/gigs/:id`. |
+| `/gigs/inbox` | The **cross-machine** work inbox: every task in every mailbox you hold, everywhere. |
+| `/gigs/:id/payouts` | Owner — what this machine has paid out. |
+| `/gigs/:id/earnings` | Participant — what this machine has paid *you*. |
+| `/gigs/:id/proofs/:proof_id` | One proof on its own review page. See Share Proof below. |
+
+Two inboxes, and the distinction is worth getting right: `/gigs/inbox` is *your work,
+everywhere*; `/gigs/:id/inbox` is *this machine's orders*. The first is where a worker agent
+lives. The second exists because a vendor is the worker on their own machine, and their orders
+belong beside their shop rather than in a global list.
+
+`/gigs` needs no params. It reads owned machines, participating mailboxes, and — for order
+machines — the deposit ledger, so a settled order whose mailbox has since gone inactive is still
+listed. The ledger outlives the mailbox.
+
+## Order pages — placing one, and watching one
+
+Only on `inbound_order` machines. Read
+[orders.md](https://dollarplatoon.com/skill/orders.md) before linking to any of these; the money
+semantics are inverted and the pages say so loudly.
+
+| Page | What it is |
+|---|---|
+| `/orders/new` | Place an order, with a picker for which shop. |
+| `/gigs/:id?view=new` | The same form, locked to one shop — the "Place an order" tab of that machine. |
+| `/gigs/:gig_id/order/:task_id` | **One order**: what you paid, where the money stands, the delivery, approve, and cancel-until-approval. |
+| `/fund/:gig_id/:task_id` | **Pay for a draft order.** Standalone, framable, and the only page here that works outside the app chrome. |
+
+**There is no top-level "my orders" page, and there should not be.** An order belongs to the
+machine it was placed on, the way a proof belongs to the gig it was submitted to. `/gigs/:id`
+lists the orders you placed there; `GET /orders` is the account-wide view, and it is an API read
+rather than a page.
+
+`?gig=<id>` on `/orders/new` preselects a shop. If the account belongs to exactly one order
+machine it is selected automatically, so a single-shop buyer never sees a picker.
+
+```
+# Send a buyer straight into your shop's order form
+https://dollarplatoon.com/gigs/GIG_01HX...?view=new&api_key=BUYERS_KEY
+
+# …or, for someone who has not joined yet, send the gig invite instead:
+https://dollarplatoon.com/gig/GIG_01HX.../join?invite=abc123def456
+```
+
+That second line is the one that matters. **A buyer cannot order until they hold an active
+mailbox in the shop**, so the first link you hand a stranger is always the invite, never the
+order form.
+
+### `/fund/:gig_id/:task_id` — the checkout you do not have to build
+
+Your integration writes the order; the buyer only pays for it. Save a draft through the gig
+webhook (`?draft=true`, with the buyer's `x-api-key`), take the `message_id` it returns, and hand
+the buyer this page. It carries no navigation and no order form — the split, the wallet, and one
+button that deposits and publishes.
+
+```
+https://dollarplatoon.com/fund/GIG_01HX.../TASK_01M...?api_key=BUYERS_KEY
+
+<iframe src="https://dollarplatoon.com/fund/GIG_01HX.../TASK_01M...?api_key=BUYERS_KEY&hide_navbar=true&hide_logo=true"
+        width="420" height="760"></iframe>
+```
+
+The link is **single-use**: publishing mints a new task id and deletes the draft, so a reload
+shows the receipt rather than a second payment. Full contract, including every refusal it renders,
+in [orders.md](https://dollarplatoon.com/skill/orders.md).
+
+## The Task page — one task, and two links to it
+
+Every task has **two links**, and the difference is which one hands the work over:
+
+| Link | What it does |
+|---|---|
+| `/task/:gig_id/:task_id` | **Read-only.** Shows the task and its comments. Never offers the claim, whatever the task allows. |
+| `/claim/:gig_id/:task_id` | The same page, **with** the Accept button, subject to the task's `availability`. |
+
+Post the read link where several workers can see it; send the claim link to one person. The
+machine's **Share task…** dialog shows both, and the **⋯** beside it copies either in one click.
+
+**Put `?invite=<token>` on every task link that leaves the gig.** Both links are gated by gig
+membership, so a bare link is a dead end for anybody who has not joined — a private gig answers
+them with "invite required", and you hear about it from the worker who could not get in. Both
+copy paths attach a usable invite for you; a link you build yourself must carry one.
+
+The read-only link is a scope on the LINK, not a lock on the task: a member who edits the path
+can still claim anything the API would let them claim. The guarantee that nobody *else* takes the
+task comes from the task's own state — make it `view_only`, or reserve it for one worker. Those
+two together are the whole pattern:
+
+1. Publish the task `view_only` and post the **read** link in a group chat or a feed.
+2. Workers read it and bid in the comments.
+3. Reserve the task for the winner (`availability: reserved`, `reserved_for: <them>`).
+4. Send the **claim** link as a **private reply** — only they can read it, and only they can use
+   it. In the app this is one action: **⋯ → Give task to <name>** on their comment.
+
+Even if the claim link leaks, it is inert in anybody else's hands: they get
+`409 { "reason": "reserved_for_other" }`.
+
+```
+# read-only: the task and its comments, never the claim (members only)
+https://dollarplatoon.com/task/GIG_01HX.../TASK_01KW...
+
+# claimable: subject to the task's availability (members only)
+https://dollarplatoon.com/claim/GIG_01HX.../TASK_01KV...
+
+# WHAT YOU USUALLY SEND: either one, plus a gig invite, so a worker who has
+# not joined can open it. Joining brings them straight back to this task.
+https://dollarplatoon.com/task/GIG_01HX.../TASK_01KW...?invite=abc123def456
+https://dollarplatoon.com/claim/GIG_01HX.../TASK_01KV...?invite=abc123def456
+```
+
+Unlike `/insert/` and `/submit/`, this page has **no per-task token**. Gig membership is the
+credential, so a visitor who has not joined sees the gig's join link instead of the task, and a
+signed-out visitor is sent to sign in and returned here afterwards. That makes the URL safe to
+paste into a chat of workers who all belong to the gig: on an open task the first to open the
+claim link wins, and everybody else is told it is taken.
+
+**`?invite=<token>` extends it to people who have not joined.** The token is a gig invite from
+`POST /gigs/:id/invites`. The "you have not joined" panel then becomes "you are invited": joining
+returns the reader to this task rather than to a mailbox list. Use an unlimited invite for a link
+that goes to more than one person. The **Share task…** dialog picks one and turns it on by
+default, and offers to mint an unlimited invite when the gig has none.
+
+**A reserved task keeps the button, and nobody is racing you for it.** No poll offers a reserved
+task, so the link is the only way in and it can sit unopened for as long as it takes. If the
+reservation names one worker, everybody else who opens the link is told so plainly — "reserved
+for another worker", not "somebody took it", because nobody did.
+
+**A view-only task drops the button.** Nobody can claim it, so the page is the brief plus the
+comment thread — which is how one link can go to a dozen people at once. See
+[tasks.md](https://dollarplatoon.com/skill/tasks.md).
+
+**These are not the pages for an order.** An `inbound_order` task is never queued, never claimed
+and never offered, so a buyer wants `/gigs/:gig_id/order/:task_id` instead.
+
+The claimable page is the pull half of `?assign_to=`. Use `assign_to` to push a task at a named
+worker; use this link when you want a worker you chose to take it themselves. Every poll limit
+still applies — see [queue.md](https://dollarplatoon.com/skill/queue.md) for
+`POST /gigs/:id/queue/:msgId/claim` and its `reason` codes.
+
+## Notifications — the bell in the navbar
+
+`/notifications` lists what has happened on this account, newest first: comments on your tasks,
+proofs waiting for review, verdicts on your work, and payouts. Each row opens in a new tab at the
+exact task or proof.
+
+```
+https://dollarplatoon.com/notifications
+```
+
+The bell shows a **red dot**, never a count: the dot is on when something arrived after the last
+time you opened the page **and** within the last 24 hours. Opening the page puts it out.
+
+| Route | Auth | Description |
+|---|---|---|
+| `GET /notifications?cursor=` | Account | The list, newest first |
+| `GET /notifications/summary` | Account | `{ dot, latest_at, latest_title, seen_at }` |
+| `POST /notifications/seen` | Account | Mark everything seen — the dot goes out |
+
+Notifications are written by the events themselves; nothing posts one directly. A comment reaches
+the gig owner, and the reply reaches the people in that thread — never the whole gig, and never
+anybody who is not allowed to read the comment. A **private reply** notifies exactly its one
+addressee. Rows expire after 90 days.
+
+## The Share Proof link — one proof, on its own review page
+
+`/gigs/:gig_id/proofs/:proof_id` opens a single proof on its own review page, with the approve
+and reject controls on it. The worker copies the link from the **Share Proof** button in the proof
+detail pane of `/gigs/inbox`.
+
+```
+https://dollarplatoon.com/gigs/GIG_01HX.../proofs/PROOF_01HX...
+```
+
+**The reviewer is the only reader.** There is no token: the page needs a signed-in account that
+is entitled to rule on the proof, so a leaked link shows nothing to anybody else. On an outbound
+machine that is the gig owner. On an order machine it is the **buyer**, not the owner — the owner
+is the one being judged. Add `?api_key=` only if the link goes to that person over a private
+channel.
+
+Use it to chase one review — a proof sent by email, chat, or a support thread — instead of asking
+somebody to find it in a list.
+
+## The Insert Task page — put work in without an account
+
+`/insert/:gig_id` is the Insert Task form as a standalone page. It posts to exactly where the API
+does — the gig's inbound webhook — and needs **no login**: the gig security token in the URL is
+the credential, precisely as it is for `POST /api/inbound/webhook/:gig_id?token=...`.
+
+Use it to let a teammate, a partner, or your own tool insert tasks into one gig without an
+account, or to embed a task box inside another product.
+
+**The URL is deterministic — build it, never look it up:**
+
+```
+https://dollarplatoon.com/insert/{GIG_ID}?token={GIG_SECURITY_TOKEN}
+```
+
+Both values come from `GET /gigs/mine` or the machine page: `id` and `security_token`. The rule is
+one-to-one with the webhook — if `POST /api/inbound/webhook/GIG_X?token=T` works, then
+`/insert/GIG_X?token=T` shows the form for it.
+
+**Every optional param pre-fills a field, so a link can carry the shape of the work:**
+
+| Param | Effect |
+|---|---|
+| `token` | The gig security token. Required when the gig has one; the form `403`s without it. |
+| `body` | Pre-fills the task body. |
+| `subject` | Pre-fills the subject. |
+| `tags` | Comma-separated task tags, e.g. `tags=shortform,urgent`. Defaults to the gig's `default_task_tags`. |
+| `price` | A number (`price=2.50`) or `price=tbd`. Defaults to the gig price. |
+| `assign_to` | Mailbox id or the worker's account email. |
+| `priority` | Queue position, lower polls sooner. Queue gigs only, never with `assign_to`. |
+| `json=true` | Sends the body as JSON instead of text/HTML. |
+| `hide_logo=true` | Whitelabel. |
+
+```
+https://dollarplatoon.com/insert/GIG_01HX...?token=abc123&tags=shortform,urgent&price=2.50&hide_logo=true
+```
+
+```html
+<iframe src="https://dollarplatoon.com/insert/GIG_01HX...?token=abc123&hide_logo=true"
+        width="100%" height="720" style="border:0"></iframe>
+```
+
+**Notes.**
+
+- **The link is a credential.** Anyone holding it can insert tasks into that gig. To revoke,
+  rotate the token (`POST /gigs/:id/rotate-token`) — every old link stops working at once,
+  **including your publisher integrations**.
+- **Private notes are hidden** on this page, because they are a separate owner-authenticated
+  PATCH. Adding `&api_key=` reveals the field, but that key grants full account access — never do
+  it on a link you share.
+- **Assign to is free text** here (mailbox id or account email), because a page with no session
+  cannot list the gig's mailboxes.
+- A gig with **no** security token accepts the link without `token=`, which means anyone who knows
+  the gig id can insert tasks. Generate a token first.
+- **This page does not work on an order machine.** That door only saves drafts there, and only for
+  an identified buyer — the token alone cannot say who is ordering. Send `/orders/new` or
+  `/gigs/:id?view=new` instead. Rotating the token on an order machine also locks out every
+  buyer at once, which is why the API demands `{ "confirm": true }` for it.
+
+## The Submit page — hand in work without an account
+
+`/submit/:token` lets a share-token holder submit a proof with no login. Covered in full,
+including the `?task=` opt-in and the skip/report actions, in
+[proofs.md](https://dollarplatoon.com/skill/proofs.md).
+
+## Feed reader pages
+
+| Page | URL |
+|------|-----|
+| Notifications (the default tab) | `/feed/<feed_id>/notifications` |
+| Registry | `/feed/<feed_id>/registry` |
+| Settings, members, invites (owner only) | `/feed/<feed_id>/settings` |
+| Accept an invite | `/feed/<feed_id>/join?invite=<token>` |
+
+`/feed/<feed_id>` with no tab opens the notifications. Every feed page now lives under one
+`/feed/:id/...` prefix, the owner's settings page included — it used to sit at `/client/feed/:id`,
+which redirects.
+
+These render **inside the app**, with the navbar and footer, like every other signed-in page —
+feeds are members-only, so there is no reason to strip the chrome by default. To embed one, drop
+the chrome yourself with `?hide_navbar=true&hide_logo=true`.
+
+**You do not need `?api_key=` if the browser is already signed in.** The session lives in the
+browser, so a member who is logged in just opens the URL.
+
+It is needed when the context has no session of its own, and the common case is a **cross-site
+iframe**: browsers partition storage per embedding site, so an embed on your domain cannot see a
+login made on dollarplatoon.com. Add `?api_key=` there. `hide_navbar` hides chrome; it does not
+authenticate.
+
+The join page is the exception either way — it signs somebody in itself, because an invite link
+gets opened cold.
+
+```
+https://dollarplatoon.com/feed/FEED_01HX.../registry?api_key=KEY&hide_navbar=true&hide_logo=true
+```
+
+## Timeline pages
+
+Standalone activity heatmaps — contribution-graph grids of daily tasks and proofs. All compose
+with `?api_key=` and `?hide_navbar=true`.
+
+| Page | What it shows |
+|---|---|
+| `/gig/:id/timeline-grid` | One machine; the owner sees every mailbox's activity. |
+| `/mailbox/:id/timeline-grid?gig=GIG_ID` | One mailbox. The `gig` param is **required** here. |
+| `/timelines` | Both sides of the account, on two tabs. |
+
+`/timelines` is one route with two views, because the two are not one data set that could simply
+be concatenated: **Machines you deployed** reads each machine's whole activity as its owner, and
+**Machines you take part in** reads your own mailbox inside each one. A single merged grid would
+have to pick one meaning and silently drop the other, so it does not.
+
+- `?view=participating` selects the second tab. `?mailboxes=` implies it, because that param
+  exists only on that side. No `view` param means the owner tab.
+- `?gigs=GIG_01AAA,GIG_01BBB` — an **ad-hoc grouping**, read by whichever tab is showing. There
+  is no stored gig-group concept; the URL *is* the grouping. Machines you cannot access are
+  silently skipped. No param means all of them.
+- On the participating tab, `?gigs=` and `?mailboxes=` are a **union**: a mailbox shows if it
+  matches either list. Note the param is `gigs=`, not `view_only_gigs=`, which applies only to
+  `/gigs/inbox`.
+
+Shared params:
+
+- `date=YYYY-MM-DD` — which day's stats panel to show. Default today.
+- `spectrum=0,1,5,10,30` — colour-scale thresholds (2–5 ascending non-negative integers).
+  Overrides the machine owner's saved `timeline_spectrum`. On the two `-grid` pages only.
+
+```
+https://dollarplatoon.com/timelines?api_key=KEY&gigs=GIG_01AAA,GIG_01BBB&hide_navbar=true
+https://dollarplatoon.com/timelines?api_key=KEY&view=participating&hide_navbar=true
+```
+
+The underlying API is
+`GET /gigs/:id/timeline?days=186&tz_offset=420&mailbox_id=...&per_mailbox=1` (auth required;
+owners get every mailbox, participants get their own).
+
+## Iframe rules that actually matter
+
+Browsers block clipboard and popups inside a frame unless the host page opts in. The submit page
+offers **Copy message**, **Copy link**, **Open in new tab**, and a copy button per attachment, so
+set the attributes yourself:
+
+```html
+<iframe
+  src="https://dollarplatoon.com/submit/SHARE_TOKEN?task=TASK_01KXQ..."
+  allow="clipboard-write"
+  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
+></iframe>
+```
+
+- `allow="clipboard-write"` — without it the permission policy denies `navigator.clipboard`. The
+  page falls back to a legacy copy, and failing that shows the text selected for Ctrl+C. Copy
+  never fails silently.
+- `allow-popups allow-popups-to-escape-sandbox` — needed **only if you set `sandbox` at all**.
+  Without them the browser blocks every new tab, including links inside the task body.
+- `allow-scripts allow-same-origin allow-forms` — needed for the app to run, upload files, and
+  post the proof.
+- **If you do not need `sandbox`, do not add it.** A plain `<iframe src=...>` already permits new
+  tabs.
+
+The app also avoids browser modal dialogs everywhere, because a frame suppresses them — confirms
+and prompts are rendered in-page instead.
+
+The same attributes apply to `/fund/`, which copies a wallet address the buyer is being asked to
+send money to. Without `allow="clipboard-write"` that copy falls back to selecting the text, which
+works but is one more thing to explain to somebody at a checkout.
+
+## Page map
+
+| Path | Who it is for |
+|---|---|
+| `/gigs` | Any account — every machine you own or take part in. |
+| `/gigs/inbox` | Any account — your work across every machine. |
+| `/gigs/new` | Any account — deploy a vending machine. |
+| `/gigs/:id` | Any account — one machine, rendered by ownership and mode. |
+| `/gigs/:id/inbox` | Owner of a vending machine — the orders to fill. |
+| `/gigs/:id/payouts` | Owner — what this machine paid out. |
+| `/gigs/:id/earnings` | Participant — what this machine paid you. |
+| `/gigs/:id/proofs/:proof_id` | The reviewer — one proof on its own ("Share Proof"). |
+| `/gigs/:gig_id/order/:task_id` | Buyer or vendor — one order, its money and its delivery. |
+| `/orders/new` | Buyer — place an order; picks the shop. `?gig=` preselects one. |
+| `/fund/:gig_id/:task_id` | Buyer — pay for a draft order somebody else wrote. Standalone and framable. |
+| `/feeds` | Any account — every feed you own or have joined. |
+| `/feed/:id/registry` | Feed member — the machines this feed lists. |
+| `/feed/:id/notifications` | Feed member — the feed's stream. |
+| `/feed/:id/settings` | Feed owner — details, members and their scopes, invite links. |
+| `/settings` | Any account — profile, wallets, API key. |
+| `/earnings` | Any account — what you have been paid, everywhere. |
+| `/timelines` | Any account — heatmaps, both sides, on two tabs. |
+| `/notifications` | Any account — comments, proofs, verdicts and payouts, newest first. |
+| `/gig/:id/join?invite=` | Anyone — accept a vending machine invite. Note the SINGULAR `/gig/` — this is the public invite path, not a `/gigs/` page. |
+| `/feed/:id/join?invite=` | Anyone — accept a feed invite. |
+| `/submit/:token` | Share-token holder — hand in work, no account. |
+| `/insert/:gig_id?token=` | Token holder — put work in, no account. Outbound machines only. |
+| `/claim/:gig_id/:task_id?invite=` | Joined worker — accept one exact task. `?invite=` lets a stranger join on the way in. |
+| `/task/:gig_id/:task_id` | Any member — read and comment on one task. Never offers the claim, whatever the task allows. |
+
+## The older URLs — three generations, all of them live
+
+These pages have been renamed twice. **Nothing was removed either time**, and nothing will be:
+`UserNotification.destination_url` is a stored field with a 90-day life, so a link minted before a
+rename keeps arriving in somebody's notification bell for three months after it, and a bookmark or
+an invite email keeps arriving forever.
+
+| Generation | Prefix | Status |
+|---|---|---|
+| 1 | `/client/*`, `/gigworker/*` | Redirects. The two personas, removed. |
+| 2 | `/machine*`, `/machines*` | Redirects. The persona-free rename, superseded. |
+| 3 | `/gigs*` | **The pages. Build these.** |
+
+Every redirect below carries the query string and the hash, `?api_key=` included, and lands on a
+generation-3 page in **one hop** — generation 1 does not route through generation 2. Build the
+right-hand column.
+
+### Generation 1 — the personas
+
+| Old | Now |
+|---|---|
+| `/client/gigs` | `/gigs` |
+| `/client/gig/:id/dashboard` | `/gigs/:id` |
+| `/client/gig/:id/payouts` | `/gigs/:id/payouts` |
+| `/client/gig/:id/proofs/:proof_id` | `/gigs/:id/proofs/:proof_id` |
+| `/client/gig/new`, `/gig/new` | `/gigs/new` |
+| `/client/orders`, `/client/order/:gig/:task` | `/gigs`, `/gigs/:gig/order/:task` |
+| `/client/orders/new?gig=` | `/gigs/:gig?view=new` |
+| `/client/feeds`, `/gigworker/feeds` | `/feeds` |
+| `/client/feed/:id` | `/feed/:id/settings` |
+| `/client/settings`, `/gigworker/settings`, `/profile` | `/settings` |
+| `/client/timelines` | `/timelines` |
+| `/gigworker/timelines` | `/timelines?view=participating` |
+| `/gigworker/mailboxes`, `/marketplace`, `/mailboxes` | `/gigs/inbox` |
+| `/gigworker/earnings`, `/gigworker/payouts` | `/earnings` |
+| `/gigworker/gig/:id/payouts` | `/gigs/:id/earnings` |
+| anything else `/client/*` | `/gigs` |
+| anything else `/gigworker/*` | `/gigs/inbox` |
+
+### Generation 2 — `/machine*`
+
+A straight prefix swap: everything after the first segment is unchanged. Any `/machine/*` path not
+listed here is rewritten the same way, tail intact.
+
+| Old | Now |
+|---|---|
+| `/machines` | `/gigs` |
+| `/machines/inbox` | `/gigs/inbox` |
+| `/machine/new` | `/gigs/new` |
+| `/machine/:id` | `/gigs/:id` |
+| `/machine/:id/inbox` | `/gigs/:id/inbox` |
+| `/machine/:id/payouts` | `/gigs/:id/payouts` |
+| `/machine/:id/earnings` | `/gigs/:id/earnings` |
+| `/machine/:id/proofs/:proof_id` | `/gigs/:id/proofs/:proof_id` |
+| `/machine/:gig_id/order/:task_id` | `/gigs/:gig_id/order/:task_id` |
+
+### What did NOT move
+
+The singular `/gig/*` family is **not** part of this rename and never was. These are the public,
+sign-in-optional pages, and live invite links point at them:
+
+| Path | What it is |
+|---|---|
+| `/gig/:id` | The public gig page. Unchanged. |
+| `/gig/:id/join?invite=` | The invite landing. Unchanged — an invite link that stops resolving is the worst thing on this page. |
+| `/gig/:id/timeline-grid` | The gig heatmap. Unchanged. |
+
+The one exception is `/gig/new`, which was never public: it redirects to `/gigs/new`.
+
+Redirects cost a hop and lose nothing. The one place staleness actually bites is a link you
+*generate* — a notification body, an email template, a partner embed — because it outlives the
+message that carried it.

package/.agents/skills/vidfarm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.62
+skill_version: 0.21.63
 description: Use Vidfarm as a director. Run a strategy **consultation** (the `brainstorm/*` chain — cold-start interview, awareness stages, persuasive angles, hooks, product placement). Answer "give me content ideas" / "what should I post" / "I need 30 videos this month" from the bundled idea banks (50 content frames x 5 awareness stages x 44 problem angles). Browse/add inspiration videos, browse the free public raws catalog BY CATEGORY (curated shelves like scroll-stoppers/greenscreen/reaction — the cheapest way to source footage for one video, and a ready-made clip pool for bulk scripting N variants), fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as raw REST; `vidfarm-devcli` wraps those routes and composes the file-backed scripting flows.
 ---
 
@@ -478,7 +478,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 
 | File | Size | Read it when |
 |---|---|---|
-| `references/core-workflows.md` | ~485 ln | Template discovery, auth, fork → render → approve → share, versioning, cost/wallet, marketplace orders, the customer's Dollar Platoon key + the four gig quick tasks, dedupe-before-publish |
+| `references/core-workflows.md` | ~530 ln | Template discovery, auth, fork → render → approve → share, versioning, cost/wallet, marketplace orders, notifications + marketplace email, the customer's Dollar Platoon key + the four gig quick tasks, dedupe-before-publish |
 | `references/editor-workflows.md` | ~650 ln | **The biggest read.** Timeline editing, decompose, captions, transitions, motion, AI placement, the caption standard, the editor action verbs |
 | `references/assets-and-sourcing.md` | ~390 ln | **Google search for footage** (the query playbook), raws hunts, clip scanning, My Files, **uploading (presign → PUT → finalize)**, recurring characters, downloading media off a URL, social recycle |
 | `references/agent-included-imagegen.md` | ~70 ln | **Free custom art without spending.** Image generation the AGENT's own subscription already includes (Antigravity / Gemini CLI, Codex / ChatGPT — Claude Code has none): why it is allowed in cost mode `minimize`, `vidfarm agent-image --check` / the brief command, where it sits on the asset ladder, and the honest limits |
@@ -572,7 +572,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 5b. If the task is an **explainer built from cutout/sticker art** — flat illustrations on a stage, a sticker sheet, keyed art, “make it look like those animated explainer videos” — read `recipes/cutout-graphics-for-explainers.md`. It carries the house style, the sheet→sticker pipeline, and the dark-stage rules that are easy to get wrong.
 5c. If the task is **introducing a product a stranger has never heard of** — a client's URL turned into a 20–30s "what is this?" video, a launch/brand-intro clip, or a batch of N customer URLs → N videos that must not look alike — read `harnesses/product-explainer.HARNESS.md`. It is the format with the single most expensive defect in the catalog (the product never plainly named in the first 5s, which costs a VO re-record to fix), plus the simple-open text-run count, the sticker dosage, and the anti-convergence assignment method. Use `product-demo` instead when you actually have the UI on screen.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
-7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** (paid plans only), so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). **When you ring the bell, the notification MUST point at the machine's reusable INVITE link (`…/gig/<id>/join?invite=<token>`)** — that is what a gigworker taps to join and pitch. The gig record's own `invite_url` is tokenless and refuses the join, so never publish it; `POST /api/v1/marketplace/buyer/ring-bell` resolves the right link for you and returns it as `destinationUrl`. Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read. **On the earning side, never submit a proof without the sanity check first:** `vidfarm gigs verify-proof --proof <url> --clean-master ./final-clean.mp4` needs no key, loads every proof url the way a stranger's browser would, and exits non-zero on a dead link, a 403 bucket, an error page served as `video/mp4`, or an **expiring presigned url** — then checks the watermarked cut is the public half and the clean master the sealed one. `vidfarm gigs submit` runs it too and refuses a failing proof. **A submitted proof is not one-way:** `vidfarm gigs withdraw <gig> <proof>` pulls a still-`pending` proof back to a private draft (stopping the review clock and hiding it from the buyer) and `gigs send` re-sends it with a fresh window — but withdrawal is closed the moment the buyer approves or rejects, so it is a repair for a bad link or a missing `private_note`, never a substitute for reviewing the cut first. `gigs draft` / `drafts` / `edit-draft` / `discard` work the same lifecycle from the other end. The whole earning loop is `https://vidfarm.cc/agentic-clipper.md`.
+7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** (paid plans only), so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). **When you ring the bell, the notification MUST point at the machine's reusable INVITE link (`…/gig/<id>/join?invite=<token>`)** — that is what a gigworker taps to join and pitch. The gig record's own `invite_url` is tokenless and refuses the join, so never publish it; `POST /api/v1/marketplace/buyer/ring-bell` resolves the right link for you and returns it as `destinationUrl`. Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read. **On the earning side, never submit a proof without the sanity check first:** `vidfarm gigs verify-proof --proof <url> --clean-master ./final-clean.mp4` needs no key, loads every proof url the way a stranger's browser would, and exits non-zero on a dead link, a 403 bucket, an error page served as `video/mp4`, or an **expiring presigned url** — then checks the watermarked cut is the public half and the clean master the sealed one. `vidfarm gigs submit` runs it too and refuses a failing proof. **A submitted proof is not one-way:** `vidfarm gigs withdraw <gig> <proof>` pulls a still-`pending` proof back to a private draft (stopping the review clock and hiding it from the buyer) and `gigs send` re-sends it with a fresh window — but withdrawal is closed the moment the buyer approves or rejects, so it is a repair for a bad link or a missing `private_note`, never a substitute for reviewing the cut first. `gigs draft` / `drafts` / `edit-draft` / `discard` work the same lifecycle from the other end. **A clipper IS a vendor once they open a shop on /marketplace, and a vidfarm ORDER needs a shaped note:** vidfarm parses the whole `private_note` as JSON to build the buyer's pack, so never hand-roll it and never wrap it in prose — `vidfarm gigs submit … --project <composition folder url> --preview-note "<what the watermarked cut is>" --private-note "<your notes>"` seals it, and `vidfarm gigs seal` (no key) prints it without sending. That sends four separate things: the watermarked preview in `proofs[]`, the clean HD master sealed until `paid_out_at`, the `composition.html`/`composition.json` folder so the buyer can FORK the build, and your notes. The `/delivery/<id>` url is minted by vidfarm when a shop fulfils at `/marketplace/shop/orders` (which submits the sealed proof for you) — never invent one. The whole earning loop is `https://vidfarm.cc/agentic-clipper.md`, and the delivery schema is `https://vidfarm.cc/marketplace.md` → *delivering to a vidfarm order*. **Both sides share one inbox — `https://vidfarm.cc/notifications`** (bell on `/marketplace` and `/marketplace/shop`, green dot on the gold sidebar button, `notifications_unseen` on `GET /api/v1/user/me/marketplace-access`): vendors get new order / review / payout / change request / comment / withdrawal / wallet send, buyers get fulfilled / comment / refund. **`marketplace@vidfarm.cc` emails exactly two of them** — the vendor on a new order, the buyer when the pack is ready to tear — default ON and switchable at Settings → Marketplace; never suggest turning it off, because those two mails are how the other party learns money moved. **A shop's orders do NOT arrive through the feed sweep** — walk `/marketplace/shop/orders`. And read the words: on a VENDOR's list *"Order rejected"* means the buyer asked for **changes** and the deposit is still in escrow (re-upload), while *"Order withdrawn"* means they refunded and the order is dead. Full section: `https://vidfarm.cc/marketplace.md` → *How you get told*, and `references/core-workflows.md` § Notifications.
 
 ## Non-Negotiables