@officexapp/vidfarm-devcli 0.21.64 → 0.21.65

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

@@ -35,7 +35,7 @@ production's identical copy, so read siblings from the host you started on if th
 - **Auth:** an `x-api-key` header on every authenticated call. Get a key at
   [dollarplatoon.com/settings](https://dollarplatoon.com/settings).
 - **Staging:** `https://staging.dollarplatoon.com/api` — same code, Base Sepolia, its own
-  accounts, and the only stage where order machines exist. **Build here first:**
+  accounts, and test money you cannot lose. **Build here first:**
   [skill/staging.md](https://dollarplatoon.com/skill/staging.md).
 
 ---
@@ -65,6 +65,13 @@ approve it. Every "the client sends work and pays for it" sentence in this skill
 It is documented on its own page — [skill/orders.md](https://dollarplatoon.com/skill/orders.md) —
 and the pages it contradicts say so where it matters.
 
+**An order machine can also be free.** `list_price: 0` opens a shop that takes orders and touches
+no contract at all: no deposit, no Treasury, no gas, and the buyer needs no wallet. It is a
+different machine rather than a cheaper one — approval, not a payout, is what releases the
+vendor's withheld deliverable, and approval is final. Paid shops still have a $0.02 floor, and
+anything between the two is refused. See
+[skill/orders.md](https://dollarplatoon.com/skill/orders.md).
+
 **Your role is a property of the MACHINE, not of your session.** There is no client/worker toggle
 and no persona in any URL: for each machine you are its Owner or a Participant in it. One account,
 one set of pages. See [skill/web-pages.md](https://dollarplatoon.com/skill/web-pages.md).
@@ -135,7 +142,9 @@ deposited — there is no withdrawal.
 > **On an order machine every one of these five changes.** The task price comes from the buyer's
 > deposit rather than the gig; the fee comes **out of** that deposit rather than on top, so a
 > $0.50 order pays the vendor $0.45; and the deposit can be undone by either party right up until
-> approval. Check `gig.distribution` before applying rules 3 and 5, and read
+> approval. On a **free** order machine (`list_price: 0`) there is no deposit, no fee and no
+> payout at all — the buyer's approval settles the order and releases the deliverable. Check
+> `gig.distribution` and `gig.list_price` before applying rules 3 and 5, and read
 > [skill/orders.md](https://dollarplatoon.com/skill/orders.md).
 
 ---
@@ -151,14 +160,14 @@ Each file below is self-contained and linked directly from here. Open what you n
 | [skill/quickstart.md](https://dollarplatoon.com/skill/quickstart.md) | API key, base URL, the `PREFIX_ULID` id format, pagination and error conventions, rate limits. Read once. |
 | [skill/clients.md](https://dollarplatoon.com/skill/clients.md) | The client playbook end to end: create a gig, fund it, invite workers, send tasks, review proofs, pay out. Includes a runnable walkthrough. |
 | [skill/gigworkers.md](https://dollarplatoon.com/skill/gigworkers.md) | The gigworker playbook end to end, including the agent loop for working many machines at once without wasting polls. |
-| [skill/orders.md](https://dollarplatoon.com/skill/orders.md) | **Order machines (`inbound_order`)** — the inverted mode, both sides of it: the shopfront price, the fee-inclusive deposit, publish-with-deposit, the undo either party may press until approval, why the deliverable belongs in `private_note`, and the whole list of what the mode refuses. |
+| [skill/orders.md](https://dollarplatoon.com/skill/orders.md) | **Order machines (`inbound_order`)** — the inverted mode, both sides of it: the shopfront price, the fee-inclusive deposit, publish-with-deposit, **free shops (`list_price: 0`, no chain at all)**, the undo either party may press until approval, why the deliverable belongs in `private_note`, and the whole list of what the mode refuses. |
 | [skill/staging.md](https://dollarplatoon.com/skill/staging.md) | Building against staging: base URLs, Base Sepolia and MockUSDC, getting an account and test money, and an honest list of what is not production-ready. |
 
 ### API reference, by domain
 
 | File | What is in it |
 |---|---|
-| [skill/gigs.md](https://dollarplatoon.com/skill/gigs.md) | Gigs, invite links, mailboxes (joining and leaving), worker rate limits, task expiry, funding, the dashboard. |
+| [skill/gigs.md](https://dollarplatoon.com/skill/gigs.md) | Gigs, invite links, mailboxes (joining and leaving), worker rate limits, task expiry, funding, the dashboard, and **every webhook event — where to register a URL, which way each event flows, and how to verify the signature**. |
 | [skill/tasks.md](https://dollarplatoon.com/skill/tasks.md) | Getting tasks INTO a gig: the publisher webhook, drafts a client can save before publishing, reserved tasks that no poll offers (optionally held for one named worker), view-only tasks nobody can claim, the comment thread on a task and who can read it, running a bidding round and giving the task to the winner privately, inbound email, **task escrow — funding one task on chain before anyone works it**, distribution modes, and the payload formats that serve humans and agents at once. |
 | [skill/queue.md](https://dollarplatoon.com/skill/queue.md) | Queue and single-player queue: polling, claiming, declining, hand-ordering, assigning a task to one named worker, task links that carry a gig invite, private briefs, hiring for a high-value job. |
 | [skill/pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md) | Per-task pricing including TBD, task tags, and every filter — how one gig carries several shapes of work. |
@@ -214,3 +223,16 @@ Participant (buys)                            Vendor (owns the machine, does the
   └─ USDC pays out on Base ─────────────────────▶ │ paid_out_at is stamped
                                                   └─ private_note is released to the buyer
 ```
+
+On a **free** machine (`list_price: 0`) the same picture stops three lines early. There is no
+deposit to send and none to undo — cancelling simply closes the order — and no rollup and no
+payout. The buyer's approval is the last step, and it is what releases `private_note`. Because
+nothing follows it to close the verdict, that approval is **final**:
+
+```
+  ├─ publishes it with NO deposit ──────────────▶ │ receives it, does the work
+  │◀──────────────────────────────────────────────┤ delivers a proof, deliverable withheld
+  ├─ may CANCEL, and so may the vendor, until here
+  └─ approves (or the review timeout does)  ◀── the point of no return
+                                                  └─ private_note is released to the buyer
+```

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

@@ -1,6 +1,32 @@
 # Provenance of this vendored skill
 
-**Synced from `https://staging.dollarplatoon.com` on 2026-08-29.**
+**Synced on 2026-08-29 from the WORKING TREE at
+`ZoomGTM/dollar-platoon/publish-officex/repos/dollarplatoon-skill`, not from a
+host.**
+
+## Read this before "correcting" the source
+
+The webhook generation is not deployed anywhere yet. Dollar Platoon commit
+`800bdec` ("Send signed webhook events") added the whole *Webhooks and events*
+chapter to `gigs.md` and the order-webhook section to `orders.md`, and neither
+host serves it. Measured the same day:
+
+| Source | `gigs.md` | Webhook chapter |
+|---|---|---|
+| working tree `publish-officex/repos/dollarplatoon-skill` | 542 lines | **yes** |
+| `staging.dollarplatoon.com` | 397 lines | no |
+| `dollarplatoon.com` | one generation behind that | no |
+
+**Re-running the curl loop below TODAY silently deletes that chapter**, and with
+it the only description of `order_webhook_url`, `events_webhook_url` and
+`order.auto_approved` — the event that names the state
+`orderClosedAt` in `src/services/dollarplatoon-orders.ts` was written to catch.
+Check `grep -c events_webhook_url skill/gigs.md` before and after any re-sync; if
+it drops to zero, the host is still behind and the sync must come from the
+working tree instead.
+
+Everything below describes the previous generation and still applies to host
+choice once the hosts catch up.
 
 ## Read this before "correcting" the source host
 

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

@@ -169,7 +169,19 @@ PATCH /gigs/:id/proofs/:proof_id
   `"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.
+  validator or agent:
+
+```bash
+curl -X PATCH "https://dollarplatoon.com/api/gigs/$GIG_ID" \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{ "proof_webhook_url": "https://my-validator.example.com/proofs" }'
+→ { "success": true, "webhook_secret": "whsec_..." }   // returned when the gig had none
+```
+
+  Each submission POSTs `{ gig_id, proof_id, task_identifier, locked_price, private_note_locked }`,
+  signed with `X-DollarPlatoon-Signature`. Verify it before acting — the snippet, the header
+  format and every other event are in [gigs.md](https://dollarplatoon.com/skill/gigs.md). Read
+  the secret back at any time with `GET /gigs/:id`, which shows it to the owner only.
 
 ## Step 6 — pay out
 

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

@@ -8,6 +8,8 @@ worker's place inside it.
 - Gig routes
 - Create a gig
 - Read and update a gig
+- Webhooks and events
+- Verifying a signature
 - Invite links
 - Security token
 - Worker rate limits
@@ -84,14 +86,21 @@ POST /gigs
     "webhook": "https://dollarplatoon.com/api/inbound/webhook/GIG_01HX...?token=abc123",
     "invite_url": "https://dollarplatoon.com/gig/GIG_01HX.../join?invite=a1b2c3d4e5f6",
     "join_policy": "invite", "price": 0.50, "status": "active"
-  }
+  },
+  "webhook_secret": "whsec_..."
 }
 ```
 
+`webhook_secret` signs every delivery to `proof_webhook_url` and `join_webhook_url`. Store it —
+you can read it back later on `GET /gigs/:id`, but only as the owner. See **Webhooks and
+events** below.
+
 Creation runs a compliance check that blocks illegal content and warns on borderline content.
 
 **`distribution: "inbound_order"` takes a different body.** Omit `price` — it is pinned to 0 —
-and send `list_price` instead (minimum $0.02). `review_timeout` must be a positive number of at
+and send `list_price` instead: either `0` for a **free shop**, which sends no deposit and needs no
+Treasury, or at least `$0.02` for a paid one. Anything strictly between the two is refused, and a
+shop cannot cross that line later. `review_timeout` must be a positive number of at
 least 3600 seconds; `-1` is refused. `price_tbd`, `allow_price_offers`, a non-null `task_timeout`
 and a non-zero `min_payout` are all rejected at the door rather than quietly ignored. The response
 adds `vendor_mailbox_id` — your own mailbox in your own shop, because there you are the worker
@@ -126,6 +135,141 @@ there means "not synced", not "zero". On PATCH, `list_price` moves and `price` a
 along with `distribution`, `contract_address`, `min_payout`, `task_timeout` and a `review_timeout`
 of `-1`.
 
+## Webhooks and events
+
+Every event on this platform is delivered to **the party it is news for**, and who that is
+depends on which way the gig points. On a normal gig the owner is the client who pays and the
+mailbox holder is the worker. On an `inbound_order` shop those roles invert: the owner is the
+**vendor** who does the work, and the buyer is a **participant** who funded one order.
+
+### Where you register a URL
+
+| Field | Lives on | Set by | Receives |
+|---|---|---|---|
+| `proof_webhook_url` | the gig | owner | `proof.submitted` |
+| `join_webhook_url` | the gig | owner | `mailbox.joined` |
+| `webhook` | a mailbox | that member | `task.assigned`, `task.pushed` |
+| `events_webhook_url` | a mailbox | that member | `proof.approved`, `proof.rejected`, `payout.paid`, `order.withdrawn` |
+| `order_webhook_url` | one order | the buyer who funded it | `order.delivered`, `order.auto_approved`, `order.paid_out`, `order.withdrawn` |
+
+`webhook` and `events_webhook_url` are **two streams on purpose**. The first carries tasks and
+has since the first release, so an agent parsing it as a task keeps working; the second carries
+everything that happens to work you already did. Set either, both, or neither.
+
+### Which way each event flows
+
+| Event | On a normal gig it reaches | On an order machine it reaches |
+|---|---|---|
+| `task.assigned` / `task.pushed` | the worker given the task | **the vendor** — this is the new-order notice |
+| `proof.submitted` | the client (gig owner) | the vendor's own endpoint, which is rarely useful |
+| `order.delivered` | — | **the buyer**, when the vendor delivers |
+| `proof.approved` / `proof.rejected` | the worker | the vendor, ruled on by the buyer |
+| `order.auto_approved` | — | the buyer, when their review window ran out |
+| `payout.paid` | the worker | the vendor |
+| `order.paid_out` | — | the buyer; a withheld deliverable is now readable |
+| `order.withdrawn` | — | **both**, with `withdrawn_by` naming who pressed it |
+
+Delivery is **best effort**: two attempts, a 3-second timeout each, no durable queue and no
+replay. Treat a webhook as a nudge to go and read the row, never as the only record.
+
+### Set a gig's webhooks
+
+```bash
+curl -X PATCH "https://dollarplatoon.com/api/gigs/GIG_01HX..." \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{ "proof_webhook_url": "https://my-agent.example.com/proofs",
+        "join_webhook_url":  "https://my-agent.example.com/joins" }'
+→ { "success": true, "webhook_secret": "whsec_..." }   // only on a gig that had none
+```
+
+Every gig created from now on is born with a `webhook_secret`. An older gig is given one on the
+first PATCH that touches either URL. Read it back at any time with `GET /gigs/:id` — **owner
+only**, and the one webhook field that route returns.
+
+### Set a mailbox's webhooks
+
+Member-only. The gig owner can neither set nor read these.
+
+```bash
+curl -X PATCH "https://dollarplatoon.com/api/gigs/GIG_01HX.../mailboxes/MBX_01HX..." \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{ "webhook": "https://my-agent.example.com/tasks",
+        "events_webhook_url": "https://my-agent.example.com/events" }'
+→ { "success": true, "webhook": "...", "events_webhook_url": "...", "webhook_secret": "whsec_..." }
+```
+
+`null` clears either field. Clearing **both** drops the secret, so setting one again mints a new
+key — that is how you rotate. You can also read your own secret back on `GET /mailboxes/mine`.
+
+**Vendors: this is the call that turns your shop on.** Opening an order machine creates your
+mailbox for you with no webhook, so PATCH it once and every order that arrives POSTs to you.
+
+### The payloads
+
+`task.assigned` — a task was handed to your mailbox. On an order machine this is a new order.
+
+```json
+{ "gig_id": "GIG_01HX...", "mailbox_id": "MBX_01HX...", "message_id": "MSG_01HX...",
+  "gig_title": "Video edits", "distribution_mode": "assigned",
+  "forwarded_at": "2026-08-29T10:00:00.000Z", "payload": { "your": "task body" } }
+```
+
+`proof.approved` / `proof.rejected` — a verdict on work you submitted.
+
+```json
+{ "event": "proof.approved", "sent_at": "...", "gig_id": "GIG_01HX...",
+  "gig_title": "Video edits", "mailbox_id": "MBX_01HX...", "proof_id": "PRF_01HX...",
+  "task_identifier": "MSG_01HX...", "amount": 2.5, "feedback": "nice work",
+  "revised": false, "auto": false }
+```
+
+`amount` is `null` when the client approved without naming one. `revised: true` means this
+overwrites an earlier verdict — always trust the latest. `auto: true` means a clock approved it,
+not a person, and only that kind can still be reported.
+
+`payout.paid` — the money moved. Approval is not payment; this is.
+
+```json
+{ "event": "payout.paid", "sent_at": "...", "gig_id": "GIG_01HX...", "mailbox_id": "MBX_01HX...",
+  "rollup_id": "RLP_01HX...", "gross_amount": 5.0, "net_amount": 4.5,
+  "wallet_address": "0x...", "tx_hash": "0x...", "proof_ids": ["PRF_01HX..."] }
+```
+
+`tx_hash` is `null` on an off-chain settlement. That is still a payout — do not read a missing
+hash as a failure.
+
+The `order.*` payloads are in [orders.md](https://dollarplatoon.com/skill/orders.md).
+
+## Verifying a signature
+
+Every delivery carries three headers:
+
+```
+X-DollarPlatoon-Event: proof.approved
+X-DollarPlatoon-Delivery: 6f2a...          # unique per attempt
+X-DollarPlatoon-Signature: t=1756468800,v1=9c1f...
+```
+
+`v1` is an HMAC-SHA256 over the exact string `` `${t}.${raw_request_body}` `` keyed with your
+secret. Sign the **raw body**, before any JSON parse — a re-serialised body will not match.
+
+```js
+const crypto = require("crypto");
+
+function verify(rawBody, header, secret) {
+  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
+  const expected = crypto.createHmac("sha256", secret)
+    .update(`${parts.t}.${rawBody}`).digest("hex");
+  const a = Buffer.from(expected), b = Buffer.from(parts.v1 || "");
+  // Reject anything older than five minutes, or the signature can be replayed.
+  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+```
+
+A delivery arrives **unsigned** when the destination has no secret — every gig and mailbox
+registered before signing existed. Set the URL again to mint one.
+
 ## Invite links
 
 Invite links gate who joins the private network. Two fields give you every mode:
@@ -304,11 +448,13 @@ POST /gigs/:id/mailboxes
   "email": "john@example.com",          // contact address for forwarded tasks
   "invite": "a1b2c3d4e5f6",             // required when join_policy is "invite"
   "wallet_address": "0x...",            // optional — hot wallet auto-provisioned if omitted
-  "webhook": "https://...",             // optional — pushed tasks POST here
+  "webhook": "https://...",             // optional — tasks POST here
+  "events_webhook_url": "https://...",  // optional — verdicts and payouts POST here
   "notes": "I have experience with Reddit marketing",
   "tags": ["urgent", "linkedin-batch"]  // private to the worker
 }
-→ { "mailbox": { "id": "MBX_01HX...", "status": "active" } }   // or "pending_approval"
+→ { "mailbox": { "id": "MBX_01HX...", "status": "active" },
+    "webhook_secret": "whsec_..." }    // only when you registered a URL. Keep it.
 ```
 
 The invite is the gate. An invite gig rejects a join without a valid token (`403`); an
@@ -332,8 +478,9 @@ Useful for auto-provisioning a workspace or syncing a roster the moment somebody
 pending mailbox, `"inactive"` disables it), and the rate-limit override.
 
 **The worker** sets `tags`, the standing `filter_*` preferences (see
-[pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md)), and
-`wallet_address`.
+[pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md)),
+`wallet_address`, and both webhook URLs. The owner cannot set or read the URLs, and never sees
+`webhook_secret` at all.
 
 Worker `tags` are **never returned to the gig owner**. They are for organising your own inbox.
 

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

@@ -52,12 +52,18 @@ POST /gigs/:id/mailboxes
 {
   "name": "my-agent",
   "invite": "a1b2c3d4e5f6",
-  "webhook": "https://my-agent.example.com/tasks",   // optional — pushed tasks POST here
+  "webhook": "https://my-agent.example.com/tasks",   // optional — tasks POST here
+  "events_webhook_url": "https://my-agent.example.com/events",  // optional — verdicts, payouts
   "tags": ["video", "urgent"]                        // optional — YOUR private labels
 }
-→ { "mailbox": { "id": "MBX_01HX...", "gig_id": "GIG_01HX...", "status": "active" } }
+→ { "mailbox": { "id": "MBX_01HX...", "gig_id": "GIG_01HX...", "status": "active" },
+    "webhook_secret": "whsec_..." }                  // save it — it signs your deliveries
 ```
 
+Both URLs are yours alone: the gig owner can neither set nor read them, and never sees the
+secret. You can add or change them later with
+`PATCH /gigs/:id/mailboxes/:mbx_id`, and `null` clears either one.
+
 - `status: "pending_approval"` means the gig requires the owner to let you in. You will receive
   nothing until they do.
 - Omit `wallet_address` and a hot wallet is created for you. Supply one to be paid at your own
@@ -248,6 +254,27 @@ licence key, the password, the download link. The client sees only `private_note
 until `paid_out_at` is stamped on that proof; approving it is not enough. You can always read
 your own note back. See [proofs.md](https://dollarplatoon.com/skill/proofs.md).
 
+**Or be told, instead of polling.** Set `events_webhook_url` on your mailbox and the platform
+POSTs you `proof.approved`, `proof.rejected` and `payout.paid` as they happen:
+
+```bash
+curl -X PATCH "https://dollarplatoon.com/api/gigs/$GIG_ID/mailboxes/$MBX_ID" \
+  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
+  -d '{ "events_webhook_url": "https://my-agent.example.com/events" }'
+→ { "success": true, "events_webhook_url": "...", "webhook_secret": "whsec_..." }
+```
+
+```json
+{ "event": "payout.paid", "sent_at": "...", "gig_id": "GIG_01HX...",
+  "mailbox_id": "MBX_01HX...", "rollup_id": "RLP_01HX...", "gross_amount": 5.0,
+  "net_amount": 4.5, "wallet_address": "0x...", "tx_hash": "0x...",
+  "proof_ids": ["PRF_01HX..."] }
+```
+
+Verify the `X-DollarPlatoon-Signature` header before you trust one, and still reconcile against
+the API — delivery is best effort, with no durable retry. The verification snippet and every
+payload are in [gigs.md](https://dollarplatoon.com/skill/gigs.md).
+
 ---
 
 ## Running as an autonomous agent

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

@@ -11,6 +11,8 @@ here in both halves.
 - Routes
 - Open a shop — the vendor's side
 - `list_price`, and why `gig.price` is pinned to 0
+- Free shops (`list_price: 0`)
+- Closing a PAID order machine
 - Fee-INCLUSIVE pricing: what the deposit actually buys
 - The order lifecycle
 - Place an order — the participant's side, end to end
@@ -19,6 +21,7 @@ here in both halves.
 - `private_note` is the vendor's only protection
 - Approve, then settle, then reveal
 - Report and comments both work in both directions
+- Webhooks: run the shop without polling
 - What this mode refuses, and why a `409` is an answer
 - Fields you will see on an order
 - What is still missing
@@ -137,9 +140,91 @@ settled on chain, `paid_out_at` is never stamped, the withheld deliverable is ne
 and the undo is already closed by the approval. The buyer pays, the vendor works, and the escrow
 is stranded with no exit. $0.02 is the smallest deposit that leaves the vendor $0.01.
 
+**`list_price: 0` is the one value below that floor which is allowed, and it is a different shop
+rather than a cheaper one.** See [Free shops](#free-shops-list_price-0). Anything strictly between
+`0` and `$0.02` is refused.
+
 `PATCH /gigs/:id` moves `list_price` and refuses `price` (`409`, `reason: "inbound_order"`).
 Repricing the shop **does not touch orders already funded** — their amounts were fixed by the
-money that was actually sent, and are bounded on chain by it.
+money that was actually sent, and are bounded on chain by it. A PATCH that would cross the
+free/paid line in either direction is refused with `409 list_price_mode_change`.
+
+## Free shops (`list_price: 0`)
+
+A free order machine takes orders and **touches no contract at all**. No deposit, no Treasury, no
+`DEPOSIT_ID_SECRET`, no gas, and the buyer needs no wallet.
+
+That is the point of it rather than a side effect: a paid shop needs a Treasury carrying the
+escrow surface, and a deployment whose Treasury has been drained cannot run one. A free shop runs
+anywhere.
+
+Everything the trap above describes is a property of escrow. A free order has no deposit, so
+there is no escrow to strand, no rollup to settle, no `paid_out_at` to lose and no undo to close.
+
+**Open one** exactly as above, with `list_price: 0`.
+
+**Place an order** with the same two calls as a paid one — draft through the webhook, then
+`POST /gigs/:id/tasks/:msgId/publish` — with **no body**. An `amount` other than `0` is refused
+(`409`, `reason: "free_order"`), never silently dropped, so a buyer is never told they tipped when
+they did not. The response carries `free: true`, `price: 0`, and no `deposit_id` or `tx_hash`.
+
+What changes downstream:
+
+| | Paid shop | Free shop |
+|---|---|---|
+| Marker on the sent order | `deposit_id` | `order_free: true` |
+| Ledger row `state` | `pending` → `open` → `settled` | `free` (terminal) |
+| Releases the withheld `private_note` | `paid_out_at`, after the payout | the buyer's **approval** |
+| Rollups | one per settled order | none, ever (`409 free_order`) |
+| Approval | revisable until a rollup carries it | **final** (`409 free_order_approved`) |
+| Undo | returns the deposit on chain | closes the order, returns nothing |
+| Closing the shop | allowed once nothing is unsettled | always allowed |
+
+The approval being final is the one asymmetry worth reading twice. On a paid order the payout
+stamp is what closes the verdict; a free order never gets one, and approval is what *releases the
+deliverable* — so if approval stayed revisable, a buyer could read a withheld licence key and then
+withdraw the verdict that unlocked it, repeatedly. Rejections stay revisable in both modes,
+because a rejection releases nothing.
+
+A free cancel writes **no reputation event**. Those are keyed on the depositor's wallet address,
+and a free order has no depositor.
+
+**A free shop can always be closed** — `PATCH /gigs/:id {"status":"closed"}`, or `DELETE /gigs/:id`,
+which writes the same field. It has no deposits and no sweep.
+
+Closing stops **new** orders only (`409`, "This shop is not open"). Orders already in flight run to
+their end: auto-approval is a query over proof rows and never reads a gig, and delivery, the
+verdict and the undo have no gig-status check either. Reopen with `{"status":"active"}`.
+
+## Closing a PAID order machine
+
+Allowed too, but only while no order is unsettled. Closing takes a gig out of `scanActiveGigs()`,
+and two cron sweeps read that scan: `processApprovedProofs` (the payout backstop for a buyer who
+approved and never pressed the button) and `reconcilePendingDeposits`. So the refusal asks about
+the money, not about the mode:
+
+| Deposit state | Blocks the close? | Why |
+|---|---|---|
+| `pending` | **yes** | money may be on chain with nothing recorded; only the reconciler resolves it |
+| `open` | **yes** | in escrow, and the review timeout can still auto-approve it into a payout |
+| `settled` | no | the chain already moved it |
+| `withdrawn` | no | the buyer has it back |
+| `free` | no | there never was any |
+
+An **abandoned** row never blocks, whatever its state — the id was given up on and the salt
+stepped. A ledger read that fails refuses the close (`409 ledger_unreadable`): "we could not tell"
+is not "there is nothing there".
+
+The refusal names the offending deposits so you know what to chase:
+
+```json
+{ "error": "This shop cannot be closed while 2 orders are unsettled. …",
+  "reason": "unsettled_orders", "unsettled": 2,
+  "deposits": [ { "deposit_id": "0x…", "state": "open", "amount": 0.5, "task_id": "TASK_…" } ] }
+```
+
+An `open` deposit clears by the buyer approving the delivery (or undoing the order); a `pending`
+one clears when the reconciler catches up on the next cron run.
 
 ## Fee-INCLUSIVE pricing: what the deposit actually buys
 
@@ -252,7 +337,9 @@ outright (`403`) and refuse everybody once the draft is funded (`409`): at that
 
 ```json
 POST /gigs/:id/tasks/:msgId/publish
-{ "amount": 0.50, "wallet_alias_id": "..." }
+{ "amount": 0.50, "wallet_alias_id": "...",
+  "order_webhook_url": "https://my-app.example.com/callback",  // optional, per order
+  "order_webhook_secret": "a-key-i-chose" }                    // optional, signs it
 
 → { "status": "assigned", "message_id": "TASK_01KX...", "published": true,
     "deposit_id": "0x…", "tx_hash": "0x…",
@@ -497,6 +584,99 @@ work the same way. Read the role note at the top of this page before you render
 buyer's comments are stored `client` and the vendor's are stored `gigworker`, which is the
 inverse of what "owns the gig" would tell you.
 
+## Webhooks: run the shop without polling
+
+Both sides of an order machine can be driven by events. Full field-by-field reference, including
+the signature scheme, is in [gigs.md](https://dollarplatoon.com/skill/gigs.md); this section is
+the order-specific half.
+
+**The direction rule.** `proof_webhook_url` on the gig belongs to the **gig owner**, who here is
+the vendor. It is the wrong channel for a buyer, and pointing it at one would tell a seller about
+their own delivery. The buyer's channel is on the **order**, and the vendor's is on their
+**mailbox**.
+
+### Vendor: be told when an order arrives
+
+Opening a shop creates your own mailbox (`vendor_mailbox_id` in the create response) with no
+webhook on it. One PATCH turns the shop on:
+
+```bash
+curl -X PATCH "https://dollarplatoon.com/api/gigs/$GIG_ID/mailboxes/$VENDOR_MAILBOX_ID" \
+  -H "x-api-key: $VENDOR_KEY" -H "Content-Type: application/json" \
+  -d '{ "webhook": "https://my-shop.example.com/orders",
+        "events_webhook_url": "https://my-shop.example.com/order-events" }'
+→ { "success": true, "webhook_secret": "whsec_..." }
+```
+
+Every funded order now POSTs to `/orders` as `task.assigned`, carrying `message_id` — the order
+you deliver a proof against. Verdicts (`proof.approved`, `proof.rejected`), payouts
+(`payout.paid`) and cancellations (`order.withdrawn`) arrive on `/order-events`.
+
+### Buyer: be told what happens to your order
+
+Name a callback in the **publish** call — the one that funds the order. It is per order, because
+you may hold more than one mailbox in a shop and "your webhook" would otherwise be ambiguous.
+
+```bash
+curl -X POST "https://dollarplatoon.com/api/gigs/$GIG_ID/tasks/$DRAFT_ID/publish" \
+  -H "x-api-key: $BUYER_KEY" -H "Content-Type: application/json" \
+  -d '{ "amount": 5.00,
+        "order_webhook_url": "https://my-app.example.com/orders/callback",
+        "order_webhook_secret": "a-key-i-chose" }'
+```
+
+`order_webhook_secret` is **yours to pick**, unlike every other secret on the platform, and it
+signs every `order.*` event for this order. Omit it and the deliveries go out unsigned. Both
+fields work identically on a free shop.
+
+### The `order.*` payloads
+
+`order.delivered` — the vendor submitted work. Review it, or let the clock do it for you.
+
+```json
+{ "event": "order.delivered", "sent_at": "...", "gig_id": "GIG_01HX...",
+  "gig_title": "Thumbnail shop", "task_id": "MSG_01HX...", "proof_id": "PRF_01HX...",
+  "price": 4.54, "deliverable_locked": true, "resubmitted": false }
+```
+
+`deliverable_locked: true` means the vendor withheld the file itself in `private_note`.
+Approving does **not** open it on a paid shop — payment does. Wait for `order.paid_out`.
+
+`order.auto_approved` — your review window ran out and the clock ruled for the vendor.
+
+```json
+{ "event": "order.auto_approved", "sent_at": "...", "gig_id": "GIG_01HX...",
+  "task_id": "MSG_01HX...", "proof_id": "PRF_01HX...", "price": 4.54, "reportable": true }
+```
+
+`reportable: true` is your remedy, and it is the only event that carries it: `POST
+/gigs/:id/proofs/:proof_id/report` takes the delivery out of the payable set — but only until a
+rollup carries it.
+
+`order.paid_out` — the vendor was paid, and a withheld deliverable is now readable.
+
+```json
+{ "event": "order.paid_out", "sent_at": "...", "gig_id": "GIG_01HX...",
+  "task_id": "MSG_01HX...", "proof_id": "PRF_01HX...", "paid_to_vendor": 4.54,
+  "tx_hash": "0x...", "deliverable_unlocked": true }
+```
+
+On `deliverable_unlocked: true`, fetch `GET /gigs/:id/proofs/:proof_id` to read the note. A free
+shop never sends this event — nothing settles, and approval is what releases the note there.
+
+`order.withdrawn` — the order was cancelled and the money went back. **The one event both sides
+receive.** Read `withdrawn_by` before you react, or you will handle your own cancellation as if
+the other party had sent it.
+
+```json
+{ "event": "order.withdrawn", "sent_at": "...", "gig_id": "GIG_01HX...",
+  "task_id": "MSG_01HX...", "withdrawn_by": "participant", "withdrawn_at": "..." }
+```
+
+`withdrawn_by` is `"participant"` (the buyer cancelled), `"vendor"` (the shop declined the job),
+or `"reconciler"` (a publish that never completed, cleaned up by the cron). The vendor's copy
+also carries `mailbox_id`.
+
 ## What this mode refuses, and why a `409` is an answer
 
 Roughly twenty owner-only levers are closed on an order machine. Every one of them answers
@@ -543,6 +723,10 @@ order's value is not readable by everyone who joined.
 | `accepted_at` | When the vendor took delivery. There is no claim step in this mode. |
 | `order_withdrawn_at` | Set on an undone order. Absent everywhere else. |
 
+`order_webhook_url` and `order_webhook_secret` are **write-only**. They are stored on the order
+and no route ever reads them back — not to the vendor, and not to the buyer who set them. Keep
+your own record of what you registered.
+
 On `GET /orders`, `state` is one of `pending | open | settled | withdrawn`, `vendor_payout` is
 derived from the deposit's own `fee_bps`, and `tip_estimate` is explicitly nullable and
 best-effort — it is measured against the shop's price **today**. The exact figure is on the task
@@ -557,9 +741,11 @@ lands somewhere unrelated.
 
 Honest gaps, so you do not design around something that is not there.
 
-- **No production shops.** `inbound_order` runs on **staging only**. Production has not had its
-  Treasury migration and its `DEPOSIT_ID_SECRET` is unset, so a publish there would `500` by
-  design. See [staging.md](https://dollarplatoon.com/skill/staging.md).
+- **On production, only gigs created since 2026-08-29 can be shops.** `inbound_order` shipped to
+  production that day on a new Treasury. Gigs older than that are on the retired contract, which
+  has no escrow in its bytecode, and a publish-with-deposit there is refused `contract_no_escrow`.
+  This cannot be configured away and escrow cannot be moved between contracts — create a new gig.
+  See [staging.md](https://dollarplatoon.com/skill/staging.md).
 - **No route lists a gig's deposits.** A vendor cannot enumerate who owes what; they see the
   aggregate `escrowed_funds` and their own order inbox.
 - **No vendor display name on the gig read.** `GET /gigs/:id` gives `owner_wallet_alias` only, so

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

@@ -44,9 +44,9 @@ curl -H "x-api-key: $DOLLAR_PLATOON_API_KEY" https://dollarplatoon.com/api/auth/
 ```
 
 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).
+its own testnet USDC on Base Sepolia. Use it for anything you would not want to pay for. Every
+path in this skill is identical there; substitute the host.
+See [staging.md](https://dollarplatoon.com/skill/staging.md).
 
 ## Identifier format
 

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

@@ -25,14 +25,16 @@ be wrong with.
 | API | `https://staging.dollarplatoon.com/api` | `https://dollarplatoon.com/api` |
 | Chain | **Base Sepolia** (chain id `84532`) | Base mainnet (chain id `8453`) |
 | USDC | **MockUSDC** `0xE4E5…c6a8` — worthless by design | Real USDC `0x8335…2913` |
-| Treasury | `0x932B9D4CA0e11D7859C43F7e58492F2C6206D485` | `0xE4E5…c6a8` |
+| Treasury | `0x932B9D4CA0e11D7859C43F7e58492F2C6206D485` | `0x42118E4F0c0E326c5c09d2aC5d764957025214A9` |
 | Accounts | Entirely separate. Your production key does **not** work here. | |
-| `inbound_order` | **Available** | Not deployed — see below |
+| `inbound_order` | **Available** | **Available** |
 | Inbound email | `…@fwd.zoomgtm.com`, with a `staging.` infix in the address | same domain, no infix |
 
-The two Treasury addresses are not a copy-paste error, and neither is production's Treasury
-matching staging's MockUSDC: they are the same deployer account at the same nonce on two
-different chains. Nothing is shared between them.
+Staging's MockUSDC address is `0xE4E5…c6a8`, which was also production's Treasury address until
+2026-08-29. That was never a copy-paste error: it is the same deployer account at the same nonce
+on two different chains. Nothing is shared between them. Production has since moved to
+`0x42118E4F…14A9`, and `0xE4E5…c6a8` is retired there — so if you see that address in an older
+document, check which chain and which role is meant.
 
 Everything in the rest of this skill is written with production URLs. To read it as a staging
 integrator, substitute the host — every path is identical. `POST /gigs` means
@@ -109,29 +111,35 @@ history. Compose it with `?hide_navbar=true&hide_logo=true` for an embed. See
 
 ## What staging has that production does not
 
-**`inbound_order` — the order machine mode — runs on staging only.** A full order has been taken
-end to end there on Base Sepolia: deposit, deliver, approve, settle, reveal. Production has none
-of it, and would refuse: its Treasury migration has not run and its deposit-id secret is unset,
-so a publish-with-deposit would `500` by design rather than take money it could not settle.
+**Money that costs nothing to be wrong with.** That is now the main difference. `inbound_order`
+shipped to production on 2026-08-29, so both stages carry it.
 
-If you are building against `inbound_order`, staging is not a rehearsal — it is the only place it
-exists. See [orders.md](https://dollarplatoon.com/skill/orders.md).
+One thing to know if you read older notes: production runs **two Treasuries at once**. Gigs
+created before 2026-08-29 live on the retired `0xE4E5…c6a8` and can never do escrow — that
+contract predates the feature, and an order against one of those gigs is refused
+`contract_no_escrow`. Gigs created since then are on `0x42118E4F…14A9` and have the full set. A
+gig keeps the Treasury it was born on for life, so this is a property of the GIG, not of the
+stage. `GET /gigs/:id` tells you which one you are on.
+
+See [orders.md](https://dollarplatoon.com/skill/orders.md).
 
 ## What is NOT production-ready — read before you ship
 
 Stated plainly, because the difference between the stages is not only "one has fake money".
 
-- **The wallet encryption key rotation has not run — on either stage.** Hot wallet private keys
-  are encrypted with a key that is the published development default. On production that is 782
-  real wallets. The dual-key read path that makes rotation possible is deployed to staging only.
+- **The wallet encryption key rotation has not run on production.** Hot wallet private keys there
+  are encrypted with a key that is the published development default — 782 real wallets. The
+  dual-key read path that makes rotation possible is now deployed to both stages, but the rotation
+  itself has not been done on production. Staging has been rotated.
   **Do not treat a Dollar Platoon hot wallet as cold storage on either stage.** Withdraw earnings
   to a wallet you control (`POST /wallets/:alias_id/transfer`).
-- **The production Treasury migration has not happened.** Production still runs the old contract,
-  which has no per-task deposits, no undo, and no reserved-balance guard. Every `inbound_order`
-  feature depends on the new one.
-- **The maintenance flag does not exist.** There is no way to quiesce the money routes on either
-  stage, so a platform migration cannot cleanly stop the world. This is the platform's problem,
-  not yours, but it means a production cutover is not a background event.
+- **Gigs created before 2026-08-29 cannot do escrow, on production.** They live on the retired
+  Treasury, which has no per-task deposits, no undo and no reserved-balance guard. This is
+  permanent for those gigs — escrow cannot be migrated between contracts. Create a new gig.
+- **Those older production gigs settle by hand, not on chain.** Their Treasury was drained on
+  2026-08-29, so they mint no payouts and refuse deposits; approved work there is paid directly to
+  worker wallets. `POST /gigs/:id/rollups` on one answers `409 settled_offchain`. New gigs are
+  unaffected and settle on chain as normal.
 - **`GET /public/read-url` signs any S3 key for any share-token holder.** Unfixed on both stages.
   Anything offloaded to S3 — a large task body, an uploaded file — should be treated as readable
   by anyone holding any share token on the platform. Keep secrets in `private_details` and

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

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.64
+skill_version: 0.21.65
 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.
 ---
 

package/SKILL.director.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.64
+skill_version: 0.21.65
 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.
 ---
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.64
+skill_version: 0.21.65
 description: Entry point for making, editing, and rendering short-form video with Vidfarm. Use when the task is to create a video, ad, explainer, or social clip; to edit or re-theme an existing composition; to source footage or audio; or to run a batch of video variants. Routes to the full director skill and the `vidfarm` CLI.
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.64",
+  "version": "0.21.65",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {
@@ -161,6 +161,8 @@
     "test:order-decision": "node --import tsx --test test/order-decision.test.ts",
     "test:reviews": "node --import tsx --test test/shop-reviews.test.ts",
     "test:marketplace-api": "node --import tsx --test test/marketplace-api.test.ts",
+    "test:marketplace-regressions": "node --import tsx --test test/marketplace-prod-regressions.test.ts",
+    "test:new-shop-free-order": "node --import tsx --test test/new-shop-free-order.test.ts",
     "test:notifications": "node --import tsx --test test/marketplace-notifications.test.ts",
     "test:delivery": "node --import tsx --test test/delivery-items.test.ts",
     "test:dporders": "node --import tsx --test test/dp-order-fee.test.ts",