@officexapp/vidfarm-devcli 0.21.62 → 0.21.64

package/.agents/skills/vidfarm/references/core-workflows.md

@@ -256,9 +256,74 @@ devcli: `vidfarm channels` lists destinations, `vidfarm schedule <postId> --at <
 
 Deeper FlockPoster work (connecting accounts, channel management, direct posting/analytics outside vidfarm's schedule wrapper) is FlockPoster's own API, not vidfarm's — grab its skill first: `npx skills add https://github.com/OfficeXApp/flockposter-skill` (mirrored as `vidfarm skills add flockposter`).
 
-## Marketplace — order videos from specialist agents
-
-The marketplace is a **paid, web-only surface**. NEVER render or reimplement it locally (not in the terminal, not on a serve box) — send the human to **https://vidfarm.cc/marketplace** (featured agents), `/marketplace/browse` (portfolios by category tag), `/marketplace/manage` (their orders). `vidfarm marketplace` prints exactly those links.
+## Pack marketplace — buy a pack, or sell one
+
+**There are two marketplaces and they are not the same product.** This one is the **shelf**: a vendor
+puts **pack cards** on `https://vidfarm.cc/marketplace` — one card is one offer, "7 videos, $35, 3-5
+days" — and a buyer orders a **pack** from it. No brief bank, no bell, no swipe deck. The older gig
+marketplace (briefs broadcast to a crowd) is the section after this one.
+
+It was web-only until 2026-08-29. It is now REST, under `/api/v1/marketplace/`, and the devcli wraps
+every route. Auth is the ordinary `vidfarm-api-key` header or a session; the whole surface is
+paid-only and answers **402** to a free key.
+
+```
+GET    /api/v1/marketplace/shelf                       PUBLIC — what is for sale
+GET    /api/v1/marketplace/shelf/:shop/:machine         one card + examples + reviews
+GET    /api/v1/marketplace/shop                         your shop, cards, limits
+POST   /api/v1/marketplace/shop/profile                 create/edit the shop
+POST   /api/v1/marketplace/shop/machines                create/edit a pack card
+POST   /api/v1/marketplace/shop/machines/:id/visibility  on/off for buyers
+GET    /api/v1/marketplace/shop/orders                  the vendor queue
+POST   /api/v1/marketplace/shop/orders/:id/fulfil       DELIVER — { items: [...] }
+POST   /api/v1/marketplace/purchases                    place an order
+GET    /api/v1/marketplace/purchases/:id                one order + thread + files + `can`
+POST   /api/v1/marketplace/purchases/:id/accept         pays, and is FINAL
+POST   /api/v1/marketplace/purchases/:id/request-changes  free; nothing moves
+GET    /api/v1/marketplace/free-order-status/:shopSlug  is MY first order here free?
+```
+
+devcli — **two verbs, and they do not overlap**: `vidfarm shop` is the vendor
+(`shop orders`, `shop deliver <id> --item "<preview>::<master>::<note>"`, `shop earnings`,
+`shop withdraw`), `vidfarm purchases` is the buyer (`purchases shelf`, `vidfarm buy
+<shop>/<card> -y`, `purchases accept <id> -y`, `purchases changes <id> "<fix>"`). Full lists:
+`vidfarm shop help`, `vidfarm purchases help`. Everything takes `--json`.
+
+**An order ends three ways, and only one is reversible.** `accept` approves and settles in full and
+is FINAL in both directions. `request-changes` is FREE and reaches nothing on chain — the deposit
+stays in escrow and the vendor re-delivers. `refund` returns the escrow; whoever signs pays the gas.
+Never route a fixable note through Dollar Platoon's reject — theirs is final and would kill a funded
+order. **Clean masters are withheld until the payout is stamped**; everything before that is
+watermarked, and the rule is applied server-side.
+
+### First order free — the NEW SHOP flag
+
+The platform can mark a shop so that **every buyer's FIRST order there is free** — one pack, $0,
+one per SHOP rather than one per card. It is superagency-only
+(`POST /api/v1/admin/shops/new-status`); a vendor can neither grant nor revoke it.
+
+It changes three rules, and an agent that misses them will mislead its human:
+
+- **No deposit and no escrow.** There is nothing to refund. A "refund" on a free order is a
+  **cancel** — it closes the order and returns nothing.
+- **The buyer's approval is FINAL and releases the files by itself.** On the paid rail the PAYOUT
+  unlocks the masters; on the free rail the APPROVAL does, because there is no payout after it. So
+  accepting is the entire transaction and there is no undo behind it.
+- **A spent free order does not come back.** Cancelling one does not restore the entitlement.
+
+**Read `is_free` on the order — NEVER `total_usd === 0`.** A zero total reached any other way still
+has escrow semantics, and treating it as free skips the payout. Underneath, a free order runs on a
+**separate Dollar Platoon gig** (`dp_free_gig_id`): their API locks a gig's price mode at creation,
+so one gig cannot sell both.
+
+`GET …/shelf` is shared-cached and therefore only ever carries the **offer** (`shop.new_shop`).
+Whether *this* buyer still has theirs is per-account and lives on its own `no-store` route. It is
+**advisory**: price at the paid number and lower it on a yes, never the other way round.
+`vidfarm purchases pack <shop>/<card>` does exactly that and prints the terms.
+
+## Older gig marketplace — broadcast a brief to a crowd
+
+Web-only. NEVER render or reimplement it locally (not in the terminal, not on a serve box) — send the human to **https://vidfarm.cc/marketplace** (featured agents), `/marketplace/browse` (portfolios by category tag), `/marketplace/manage` (their orders). `vidfarm marketplace` prints exactly those links.
 
 An **order IS a Dollar Platoon gig** (tagged `vidfarm_order_<uuidv7>` plus category tags). Vidfarm exposes a deliberately thin REST wrapper — auth via session or the `vidfarm-api-key` header:
 
@@ -279,6 +344,45 @@ POST /api/v1/marketplace/orders/:gigId/invite   { "slug": "<agent portfolio slug
 
 devcli: `vidfarm marketplace` (browse links), `vidfarm marketplace orders`, `vidfarm marketplace order --title <t> --brief <b> [--count <n>] [--price <usd>] [--rate-limit-per-day <n>] [--tags a,b] [--folder <path>]` (defaults: 10 videos, $0.50, 2/day per worker), `vidfarm marketplace invite <gigId> --portfolio <slug>`.
 
+## Notifications — one list for both sides of the marketplace
+
+Everything that happens on an order lands on **https://vidfarm.cc/notifications**, buyer side and vendor side in the same list. The bell that opens it sits on `/marketplace`, `/marketplace/shop` and `/shop/:slug`; the gold **Marketplace** / **Vendor** button in the sidebar wears a green dot while anything is unseen.
+
+| you are | you are told about |
+|---|---|
+| **vendor** | a new order · a new review · a payout · the buyer asked for changes · a new comment · the buyer withdrew · a wallet withdrawal |
+| **buyer** | your order was fulfilled · a new comment · the vendor refunded and closed it |
+
+**Three words that look alike and are not.** On the vendor's list *"Order rejected"* means the BUYER asked for **changes** — nothing reached Dollar Platoon and the deposit is still in escrow, so the right move is to re-upload, not to argue. *"Order withdrawn"* means the buyer refunded and the order is dead. On the BUYER's list *"Order rejected"* means the **vendor** refunded and closed it. See `https://vidfarm.cc/marketplace.md`.
+
+Web-only, and **not paid-gated** — a free account can fulfil work, so it can be owed a payout. Everything on the page is a form post and works with JavaScript off:
+
+```
+GET  /notifications?q=<search>&filter=all|unseen&page=<n>     the list, newest first
+POST /notifications/:notificationId/seen                      form: seen=1|0, q, filter, page
+POST /notifications/mark-all-seen                             form: q, filter
+```
+
+A row carries **two separate controls**: *Mark seen / Mark unseen*, and *Open ↗* — a plain link that opens the order in a new tab. Clicking the row itself does nothing, on purpose.
+
+The unseen count is **not** in the page HTML — `/marketplace` is shared-cached for anonymous visitors, so a count baked in would be one buyer's badge served to a stranger. It rides the session's own access probe instead, which an agent can read directly:
+
+```bash
+curl -s -b cookies.txt "https://vidfarm.cc/api/v1/user/me/marketplace-access"
+# { "ok": true, "marketplace": true, "vendor": true, "shop_slug": "acme", "notifications_unseen": 3 }
+```
+
+### Marketplace email — two messages, one switch
+
+`marketplace@vidfarm.cc` sends exactly two things, and nothing else ever comes from that address:
+
+| to | when |
+|---|---|
+| the **vendor** | a buyer placed an order in their shop |
+| the **buyer** | a vendor delivered the pack — it is ready to tear |
+
+**Default ON**, by absence of a preference rather than by a backfill. The switch is **Settings → Marketplace → Marketplace email** (`POST /settings/marketplace/email-prefs`). Turning it off changes nothing about how orders work; the same events are still on `/notifications`. Never tell a user to disable it as a fix for something else — those two mails are how the other party learns money moved.
+
 ## Your Dollar Platoon key, from the vidfarm REST API
 
 Every paid vidfarm account owns a Dollar Platoon account, and **one route hands the agent that credential** — so an agent holding only a `vidfarm-api-key` can drive the whole gig side without the human copying anything out of Settings.

package/SKILL.director.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.62
+skill_version: 0.21.64
 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
 
@@ -854,9 +854,74 @@ devcli: `vidfarm channels` lists destinations, `vidfarm schedule <postId> --at <
 
 Deeper FlockPoster work (connecting accounts, channel management, direct posting/analytics outside vidfarm's schedule wrapper) is FlockPoster's own API, not vidfarm's — grab its skill first: `npx skills add https://github.com/OfficeXApp/flockposter-skill` (mirrored as `vidfarm skills add flockposter`).
 
-## Marketplace — order videos from specialist agents
+## Pack marketplace — buy a pack, or sell one
 
-The marketplace is a **paid, web-only surface**. NEVER render or reimplement it locally (not in the terminal, not on a serve box) — send the human to **https://vidfarm.cc/marketplace** (featured agents), `/marketplace/browse` (portfolios by category tag), `/marketplace/manage` (their orders). `vidfarm marketplace` prints exactly those links.
+**There are two marketplaces and they are not the same product.** This one is the **shelf**: a vendor
+puts **pack cards** on `https://vidfarm.cc/marketplace` — one card is one offer, "7 videos, $35, 3-5
+days" — and a buyer orders a **pack** from it. No brief bank, no bell, no swipe deck. The older gig
+marketplace (briefs broadcast to a crowd) is the section after this one.
+
+It was web-only until 2026-08-29. It is now REST, under `/api/v1/marketplace/`, and the devcli wraps
+every route. Auth is the ordinary `vidfarm-api-key` header or a session; the whole surface is
+paid-only and answers **402** to a free key.
+
+```
+GET    /api/v1/marketplace/shelf                       PUBLIC — what is for sale
+GET    /api/v1/marketplace/shelf/:shop/:machine         one card + examples + reviews
+GET    /api/v1/marketplace/shop                         your shop, cards, limits
+POST   /api/v1/marketplace/shop/profile                 create/edit the shop
+POST   /api/v1/marketplace/shop/machines                create/edit a pack card
+POST   /api/v1/marketplace/shop/machines/:id/visibility  on/off for buyers
+GET    /api/v1/marketplace/shop/orders                  the vendor queue
+POST   /api/v1/marketplace/shop/orders/:id/fulfil       DELIVER — { items: [...] }
+POST   /api/v1/marketplace/purchases                    place an order
+GET    /api/v1/marketplace/purchases/:id                one order + thread + files + `can`
+POST   /api/v1/marketplace/purchases/:id/accept         pays, and is FINAL
+POST   /api/v1/marketplace/purchases/:id/request-changes  free; nothing moves
+GET    /api/v1/marketplace/free-order-status/:shopSlug  is MY first order here free?
+```
+
+devcli — **two verbs, and they do not overlap**: `vidfarm shop` is the vendor
+(`shop orders`, `shop deliver <id> --item "<preview>::<master>::<note>"`, `shop earnings`,
+`shop withdraw`), `vidfarm purchases` is the buyer (`purchases shelf`, `vidfarm buy
+<shop>/<card> -y`, `purchases accept <id> -y`, `purchases changes <id> "<fix>"`). Full lists:
+`vidfarm shop help`, `vidfarm purchases help`. Everything takes `--json`.
+
+**An order ends three ways, and only one is reversible.** `accept` approves and settles in full and
+is FINAL in both directions. `request-changes` is FREE and reaches nothing on chain — the deposit
+stays in escrow and the vendor re-delivers. `refund` returns the escrow; whoever signs pays the gas.
+Never route a fixable note through Dollar Platoon's reject — theirs is final and would kill a funded
+order. **Clean masters are withheld until the payout is stamped**; everything before that is
+watermarked, and the rule is applied server-side.
+
+### First order free — the NEW SHOP flag
+
+The platform can mark a shop so that **every buyer's FIRST order there is free** — one pack, $0,
+one per SHOP rather than one per card. It is superagency-only
+(`POST /api/v1/admin/shops/new-status`); a vendor can neither grant nor revoke it.
+
+It changes three rules, and an agent that misses them will mislead its human:
+
+- **No deposit and no escrow.** There is nothing to refund. A "refund" on a free order is a
+  **cancel** — it closes the order and returns nothing.
+- **The buyer's approval is FINAL and releases the files by itself.** On the paid rail the PAYOUT
+  unlocks the masters; on the free rail the APPROVAL does, because there is no payout after it. So
+  accepting is the entire transaction and there is no undo behind it.
+- **A spent free order does not come back.** Cancelling one does not restore the entitlement.
+
+**Read `is_free` on the order — NEVER `total_usd === 0`.** A zero total reached any other way still
+has escrow semantics, and treating it as free skips the payout. Underneath, a free order runs on a
+**separate Dollar Platoon gig** (`dp_free_gig_id`): their API locks a gig's price mode at creation,
+so one gig cannot sell both.
+
+`GET …/shelf` is shared-cached and therefore only ever carries the **offer** (`shop.new_shop`).
+Whether *this* buyer still has theirs is per-account and lives on its own `no-store` route. It is
+**advisory**: price at the paid number and lower it on a yes, never the other way round.
+`vidfarm purchases pack <shop>/<card>` does exactly that and prints the terms.
+
+## Older gig marketplace — broadcast a brief to a crowd
+
+Web-only. NEVER render or reimplement it locally (not in the terminal, not on a serve box) — send the human to **https://vidfarm.cc/marketplace** (featured agents), `/marketplace/browse` (portfolios by category tag), `/marketplace/manage` (their orders). `vidfarm marketplace` prints exactly those links.
 
 An **order IS a Dollar Platoon gig** (tagged `vidfarm_order_<uuidv7>` plus category tags). Vidfarm exposes a deliberately thin REST wrapper — auth via session or the `vidfarm-api-key` header:
 
@@ -877,6 +942,45 @@ POST /api/v1/marketplace/orders/:gigId/invite   { "slug": "<agent portfolio slug
 
 devcli: `vidfarm marketplace` (browse links), `vidfarm marketplace orders`, `vidfarm marketplace order --title <t> --brief <b> [--count <n>] [--price <usd>] [--rate-limit-per-day <n>] [--tags a,b] [--folder <path>]` (defaults: 10 videos, $0.50, 2/day per worker), `vidfarm marketplace invite <gigId> --portfolio <slug>`.
 
+## Notifications — one list for both sides of the marketplace
+
+Everything that happens on an order lands on **https://vidfarm.cc/notifications**, buyer side and vendor side in the same list. The bell that opens it sits on `/marketplace`, `/marketplace/shop` and `/shop/:slug`; the gold **Marketplace** / **Vendor** button in the sidebar wears a green dot while anything is unseen.
+
+| you are | you are told about |
+|---|---|
+| **vendor** | a new order · a new review · a payout · the buyer asked for changes · a new comment · the buyer withdrew · a wallet withdrawal |
+| **buyer** | your order was fulfilled · a new comment · the vendor refunded and closed it |
+
+**Three words that look alike and are not.** On the vendor's list *"Order rejected"* means the BUYER asked for **changes** — nothing reached Dollar Platoon and the deposit is still in escrow, so the right move is to re-upload, not to argue. *"Order withdrawn"* means the buyer refunded and the order is dead. On the BUYER's list *"Order rejected"* means the **vendor** refunded and closed it. See `https://vidfarm.cc/marketplace.md`.
+
+Web-only, and **not paid-gated** — a free account can fulfil work, so it can be owed a payout. Everything on the page is a form post and works with JavaScript off:
+
+```
+GET  /notifications?q=<search>&filter=all|unseen&page=<n>     the list, newest first
+POST /notifications/:notificationId/seen                      form: seen=1|0, q, filter, page
+POST /notifications/mark-all-seen                             form: q, filter
+```
+
+A row carries **two separate controls**: *Mark seen / Mark unseen*, and *Open ↗* — a plain link that opens the order in a new tab. Clicking the row itself does nothing, on purpose.
+
+The unseen count is **not** in the page HTML — `/marketplace` is shared-cached for anonymous visitors, so a count baked in would be one buyer's badge served to a stranger. It rides the session's own access probe instead, which an agent can read directly:
+
+```bash
+curl -s -b cookies.txt "https://vidfarm.cc/api/v1/user/me/marketplace-access"
+# { "ok": true, "marketplace": true, "vendor": true, "shop_slug": "acme", "notifications_unseen": 3 }
+```
+
+### Marketplace email — two messages, one switch
+
+`marketplace@vidfarm.cc` sends exactly two things, and nothing else ever comes from that address:
+
+| to | when |
+|---|---|
+| the **vendor** | a buyer placed an order in their shop |
+| the **buyer** | a vendor delivered the pack — it is ready to tear |
+
+**Default ON**, by absence of a preference rather than by a backfill. The switch is **Settings → Marketplace → Marketplace email** (`POST /settings/marketplace/email-prefs`). Turning it off changes nothing about how orders work; the same events are still on `/notifications`. Never tell a user to disable it as a fix for something else — those two mails are how the other party learns money moved.
+
 ## Your Dollar Platoon key, from the vidfarm REST API
 
 Every paid vidfarm account owns a Dollar Platoon account, and **one route hands the agent that credential** — so an agent holding only a `vidfarm-api-key` can drive the whole gig side without the human copying anything out of Settings.

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.62
+skill_version: 0.21.64
 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.
 ---
 
@@ -278,6 +278,8 @@ Also served at `vidfarm.cc`: `/flash-harness.md` (**the weak-model process harne
 
 **Then ask the gigworker one more question: the RUN MODE.** It decides which stages of every task stop for them — `full-interactive` (shortlist · plan · raws · cut), `quick-interactive` (shortlist · cut), `auto-batch` (cut only — build the batch unattended, review it in one sitting), `auto-submit` (nothing; opt-in, in their own words). The middle two are the common ones. `vidfarm clipper-run mode` explains all four and saves the answer, `vidfarm clipper-run next` says what to do right now, and `vidfarm clipper-run gate <task>` exits non-zero while a human gate is open — so `gate && gigs submit …` cannot send an unreviewed cut. Full section: `/marketplace.md` → *The four run modes*.
 
+**Both sides share one inbox: `https://vidfarm.cc/notifications`.** Buyer rows and vendor rows in one list, because one person is a buyer on one order and a vendor on the next. The bell is on `/marketplace` and `/marketplace/shop`; the gold sidebar button wears a green dot while anything is unseen; `GET /api/v1/user/me/marketplace-access` returns `notifications_unseen` for an agent that wants the number. Vendors are told about a new order, a review, a payout, a change request, a comment, a withdrawal and a wallet send; buyers about a fulfilment, a comment and a refund. **`marketplace@vidfarm.cc` emails exactly two of those** — the vendor when an order is placed, the buyer when the pack is ready to tear — default ON, switchable at **Settings → Marketplace**, and never a thing to suggest turning off. **One trap: on a VENDOR's list "Order rejected" means the buyer asked for CHANGES — the deposit is still in escrow and the fix is to re-upload.** "Order withdrawn" is the dead one. Full section: `/marketplace.md` → *How you get told*.
+
 **Then offer the CLIPPER DASHBOARD — `vidfarm dashboard` — and expect a yes.** Three of the four run modes stop to make a human *watch a video*, and a terminal cannot play one; without the dashboard the gigworker reads a path out of `REVIEW_QUEUE.md`, opens the file by hand, and types a verb, once per task. `vidfarm dashboard` is that queue as one localhost page over the same `CLIPPER/` folder — no key, no network, no account: the cut plays and seeks, the buyer's brief sits beside it, the checks are tickable and the unticked ones pre-fill the rejection note, the shortlist candidates play side by side (`1`/`2`/`3` to pick), and `A`/`C`/`D`/`U` answer the gate. Every button calls the same `clipper-run` transition the CLI calls, so the page and the terminal can never disagree. Ask once, record it in `MISSION.md` as `dashboard: yes | no`, and never depend on it — a gigworker who declines keeps `REVIEW_QUEUE.md`, `clipper-run review` and the `gate` rail exactly as they were. Full section: `/agentic-clipper.md` § 3⅘.
 
 **Before ANY proof is submitted, run the sanity check — every time, on every side of the loop.** `vidfarm gigs verify-proof --proof <url> --clean-master ./final-clean.mp4` needs no api key. It loads each proof url the way a stranger's browser would (no key, no cookie) and exits non-zero on a 403 bucket, a 404, an s3 AccessDenied body served as `video/mp4`, an **expiring presigned url** (read access dies before the buyer swipes), a `localhost`/Drive/Dropbox link, or a 0-byte file. It then checks the delivery is split the right way: the **watermarked** cut public in `proofs[]`, the **clean master** sealed in `private_note` (`--clean-master`) — recommended, not required, so putting the unwatermarked final in the proof itself only warns, and `--clean-in-proof` says you meant it. `vidfarm gigs submit` runs the same check and refuses a failing proof. The two gates are different questions: `clipper-run gate` = *did a human watch it*, `gigs verify-proof` = *can the buyer open it*. Full section: `/marketplace.md` → *the sanity check before you send*.

package/clipper.md

@@ -395,6 +395,26 @@ await submitProof(gigId, {
 });
 ```
 
+**If the gig is a vidfarm ORDER, one more field, and it has a required shape.** A vendor —
+"clipper" and "vendor" are the same person here — who runs a **vending machine shop** on
+`https://vidfarm.cc/marketplace` sells packs, and the buyer opens the delivery as a pack on
+vidfarm. That pack is built from `private_note`, which vidfarm parses as **JSON, whole**. Do not
+write it by hand and do not wrap it in a sentence — build it:
+
+```bash
+vidfarm gigs submit $GIG --task $TASK \
+  --proof "$SHARE_URL" --clean-master ./videos/<task-id>-clean.mp4 \
+  --project "https://vidfarm.cc/directory/preview/dsh_…/files/<slug>" \
+  --preview-note "watermarked, 1080x1920, 27s" \
+  --private-note "What I changed, and what I would try next."
+```
+
+That sends four separate things: the **watermarked** cut in `proofs` for them to judge, the
+**clean HD master** sealed until the payout, the **`composition.html` / `composition.json` folder**
+so they can fork and re-edit it themselves, and **your notes**. `vidfarm gigs seal` prints the note
+without sending it. The full shape is in `https://vidfarm.cc/marketplace.md` → *delivering to a
+vidfarm order*.
+
 Check the response:
 
 - **`warning: "available funds are less than the task price"`** — the proof was accepted but

package/dist/src/cli.js

@@ -1136,7 +1136,28 @@ Files (multi-step flows the devcli handles for you):
     --job <jobId>           Price ONE render/video (sums its charges → "this video cost $X")
     --tracer <tracer>       Price everything tagged with a tracer; --limit <n> recent events
 
-Marketplace (paid, cloud-only — the bazaar never renders locally):
+The pack marketplace (paid, cloud-only) — SHOPS, PACK CARDS AND ORDERS:
+  A vendor puts PACK CARDS on the shelf ("7 videos, $35, 3-5 days"). A buyer
+  orders a pack, the USDC sits in escrow, the vendor delivers, the buyer rules
+  on it. Accepting is what pays. One person is usually both, so there are two
+  verbs and one key.
+
+  shop                      Your storefront: cards, orders, deliveries, money
+    shop open --name "…"      Create/edit the shop  ·  shop cards  ·  shop orders
+    shop new-card --title "…" --lot-size 7 --price 35 --live
+    shop deliver <orderId> --item "<preview>::<master>::<note>"   ← hand the pack over
+    shop refund <orderId>  ·  shop reviews  ·  shop earnings  ·  shop withdraw
+    (full list: vidfarm shop help)
+  purchases                 What you bought, and every move left on it
+    purchases shelf           What is for sale  ·  purchases pack <shop>/<cardId>
+    buy <shop>/<cardId> --packs 1 --answer <id>=<url> -y      ← place the order
+    purchases open <orderId>  ·  purchases rate <orderId> <itemId> keep|pass
+    purchases accept <orderId> -y   pays in full, FINAL
+    purchases changes <orderId> "<what to fix>"   free — nothing moves
+    purchases refund <orderId> [--ask]  ·  purchases review <orderId> …
+    (full list: vidfarm purchases help)
+
+The older gig marketplace (Dollar Platoon briefs, not pack cards):
   marketplace               Browse = the web. Prints vidfarm.cc/marketplace (paid customers)
   marketplace orders        List YOUR orders (each is a Dollar Platoon gig) → GET  /api/v1/marketplace/orders
   marketplace order         Place an order (thin wrapper around a DP gig)  → POST /api/v1/marketplace/orders
@@ -1145,7 +1166,7 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
                              --rate-limit-per-day <n> per-gigworker daily cap (default 2, 0 = none);
                              --tags <a,b> category tags; --folder <path> share a My Files folder
   marketplace invite <gig>  Email-invite an agent portfolio to an order    → POST /api/v1/marketplace/orders/:id/invite
-    --portfolio <slug>       The agent portfolio slug (from /marketplace/browse)
+    --portfolio <slug>       The agent portfolio slug (from /marketplace-old/browse)
                             Gig inbox / proofs / payouts are Dollar Platoon's own API —
                             grab the skill: npx skills add https://github.com/OfficeXApp/dollarplatoon-skill
   files                     List My Files assets + folders               → GET /api/v1/user/me/attachments
@@ -1703,6 +1724,25 @@ async function main() {
         case "market":
             await runMarketplaceCommand(rest);
             return;
+        // THE PACK MARKETPLACE — shops, pack cards and orders on vidfarm.cc.
+        // `marketplace` above is the OLDER gig surface and stays where it is; these
+        // two are the storefront that replaced it, one verb per side.
+        case "shop":
+        case "vendor":
+        case "storefront": {
+            const { runShopCommand } = await import("./devcli/marketplace-console.js");
+            await runShopCommand(rest);
+            return;
+        }
+        case "purchases":
+        case "purchase":
+        case "buy": {
+            const { runPurchasesCommand } = await import("./devcli/marketplace-console.js");
+            // `vidfarm buy <shop>/<card>` is the whole point of the buyer side, so it
+            // works as a top-level verb without the reader learning a subcommand.
+            await runPurchasesCommand(command === "buy" ? ["buy", ...rest] : rest);
+            return;
+        }
         // Both sides of the vending machines: a paid client posting tasks and
         // reviewing proofs, and a FREE gigworker with their own dollarplatoon key.
         case "gigs":
@@ -10981,8 +11021,8 @@ async function runMarketplaceCommand(argv) {
         // Paid web surface — send the human there instead of rendering locally.
         console.log(`${BOLD}The marketplace is a web surface for paying customers — browse it here:${RESET}`);
         console.log(`  ${FRONTEND}${ctx.host}/marketplace${RESET}          featured agents`);
-        console.log(`  ${FRONTEND}${ctx.host}/marketplace/browse${RESET}   portfolios by category tag`);
-        console.log(`  ${FRONTEND}${ctx.host}/marketplace/manage${RESET}   your orders (gig inboxes)`);
+        console.log(`  ${FRONTEND}${ctx.host}/marketplace-old/browse${RESET}   portfolios by category tag`);
+        console.log(`  ${FRONTEND}${ctx.host}/marketplace-old/manage${RESET}   your orders (gig inboxes)`);
         console.log("");
         console.log(`${DIM}Place orders from here: vidfarm marketplace order --title <t> --brief <b> [--tags a,b] [--folder <path>]${RESET}`);
         console.log(`${DIM}${DOLLARPLATOON_SKILL_HINT}${RESET}`);
@@ -11048,7 +11088,7 @@ async function runMarketplaceCommand(argv) {
         const order = (result.json ?? {}).order ?? {};
         emitResult(result, ctx.json, [
             ["Manage Inbox", order.inboxUrl],
-            ["Manage Orders", `${ctx.host}/marketplace/manage`]
+            ["Manage Orders", `${ctx.host}/marketplace-old/manage`]
         ]);
         if (!ctx.json)
             console.log(`\n${DIM}${DOLLARPLATOON_SKILL_HINT}${RESET}`);
@@ -13589,7 +13629,11 @@ void main().catch(async (error) => {
         // clipper-run / panel conditions: a wrong task id, an id already taken, a
         // gate that has to be answered first. All of these are the CLI talking to a
         // human, and a stack trace reads as "vidfarm is broken".
-        || (error instanceof Error && error.name === "ClipperUserError")) {
+        || (error instanceof Error && error.name === "ClipperUserError")
+        // `shop` / `purchases`: a refused refund, a card that needs a title, a
+        // missing --answer. Every one of these is the marketplace answering a
+        // person, and the answer is already a sentence.
+        || (error instanceof Error && error.name === "MarketplaceError")) {
         console.error(error.message);
         process.exit(1);
     }

package/dist/src/devcli/delivery-seal.js

@@ -0,0 +1,119 @@
+// The vidfarm deliverable, as it travels inside a Dollar Platoon `private_note`.
+//
+// Dollar Platoon gives the vendor exactly one protection: the note on a proof
+// opens only when `paid_out_at` is stamped — not when the buyer approves. So the
+// watermarked preview goes in `proofs[]` where the buyer can rule on it, and
+// everything they are paying FOR goes in the note, sealed until the money moves.
+//
+// Their field is a plain string. That is why this exists: without an agreed
+// shape, one vendor writes "master: <url>", the next writes "here u go", and
+// vidfarm cannot render either as a pack. The string is therefore JSON, WHOLE —
+// vidfarm parses the entire note, so nothing may be appended before or after it.
+// A vendor's prose belongs in `vendorNote`, not around the blob.
+//
+// VERSIONED, because the note is written once and read back after the payout,
+// possibly weeks later, by code that has moved on. An unversioned blob is
+// unreadable the first time the shape changes.
+//
+//   v1  deliveryUrl + items[{itemId, kind, urls, notes}]
+//   v2  adds previewUrls / previewNote (the watermarked half, described),
+//       projectUrl (the composition folder the buyer forks), and vendorNote.
+//
+// v2 is PURELY ADDITIVE: every v1 note still opens, and a v1 reader still finds
+// everything it knew about in a v2 note. Never renumber a field; add one.
+//
+// Backend-free (no imports at all) so it ships in the public cloud-only CLI and
+// is the single definition both `vidfarm gigs` and the server fulfil route use.
+/** Drop empty strings and blanks — a url list is never partly blank. */
+function urls(value) {
+    return (value ?? []).map((url) => String(url).trim()).filter(Boolean);
+}
+/** Omit rather than send "" — an absent field reads as absent, not as empty. */
+function text(value) {
+    const trimmed = String(value ?? "").trim();
+    return trimmed ? trimmed : undefined;
+}
+/**
+ * Build the deliverable from loose input, so no caller hand-rolls the shape.
+ *
+ * `kind` is DERIVED, never declared: several preview urls are the frames of a
+ * slideshow and one is a video. A vendor who cannot state the type cannot state
+ * it wrongly, and the declared kind can never disagree with the content.
+ */
+export function buildSealedDeliverable(input) {
+    const items = input.items.map((item, index) => {
+        const previewUrls = urls(item.previewUrls);
+        const masterUrls = urls(item.masterUrls);
+        return {
+            itemId: text(item.itemId) ?? `item_${index + 1}`,
+            kind: item.kind
+                ?? ((previewUrls.length > 1 || masterUrls.length > 1) ? "slideshow" : "video"),
+            urls: masterUrls,
+            ...(previewUrls.length ? { previewUrls } : {}),
+            ...(text(item.previewNote) ? { previewNote: text(item.previewNote) } : {}),
+            ...(text(item.projectUrl) ? { projectUrl: text(item.projectUrl) } : {}),
+            notes: text(item.notes) ?? ""
+        };
+    });
+    return {
+        v: 2,
+        deliveryUrl: text(input.deliveryUrl) ?? "",
+        ...(text(input.vendorNote) ? { vendorNote: text(input.vendorNote) } : {}),
+        items
+    };
+}
+/** The note, ready to send. The WHOLE string — never append to it. */
+export function sealDeliverable(input) {
+    return JSON.stringify(input);
+}
+/**
+ * Read a note back. Returns null on anything we do not recognise, which is the
+ * correct answer for a plain-text note written by a worker who never used this
+ * shape — that note is still a valid delivery, it is just not a vidfarm pack.
+ */
+export function openSealedDeliverable(note) {
+    if (!note)
+        return null;
+    try {
+        const parsed = JSON.parse(note);
+        if (!parsed || !Array.isArray(parsed.items))
+            return null;
+        // Accept every version we have ever written. A note from a newer vendor CLI
+        // than this reader is the one case worth rejecting: its items may mean
+        // something else, and half-reading them is worse than showing the raw note.
+        return parsed.v === 1 || parsed.v === 2 ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One human-readable line per item, for a CLI to print before it sends.
+ *
+ * A vendor cannot proof-read a minified json blob, and the two mistakes that
+ * cost the payout — the halves swapped, or no master at all — are both obvious
+ * the moment the note is written out in words.
+ */
+export function describeSealedDeliverable(sealed) {
+    const lines = [];
+    lines.push(sealed.deliveryUrl
+        ? `pack        ${sealed.deliveryUrl}`
+        : "pack        (none — this proof settles no vidfarm order)");
+    if (sealed.vendorNote)
+        lines.push(`your note   ${sealed.vendorNote}`);
+    for (const item of sealed.items) {
+        lines.push(`${item.itemId}  ${item.kind}`);
+        lines.push(`  master    ${item.urls.length
+            ? item.urls.join(", ")
+            : "(none — nothing unseals when they pay)"}`);
+        if (item.previewUrls?.length)
+            lines.push(`  preview   ${item.previewUrls.join(", ")}`);
+        if (item.previewNote)
+            lines.push(`  about     ${item.previewNote}`);
+        lines.push(`  project   ${item.projectUrl ?? "(none — the buyer cannot fork this)"}`);
+        if (item.notes)
+            lines.push(`  notes     ${item.notes}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=delivery-seal.js.map