@officexapp/vidfarm-devcli 0.21.63 → 0.21.64

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

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

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:
 

package/SKILL.director.md

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

package/SKILL.md

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

package/dist/src/devcli/marketplace-console.js

@@ -121,6 +121,17 @@ function money(value) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? `$${parsed.toFixed(2)}` : "$—";
 }
+/**
+ * What an order cost, in words.
+ *
+ * "$0.00" on a free order reads as a bug, and worse, it reads as a PAID order
+ * that went wrong — which is the one thing it must never look like, because
+ * the two rails have opposite undo rules. Never derive this from the number:
+ * a zero total reached any other way still has escrow behind it.
+ */
+export function orderPrice(order) {
+    return order.is_free ? "FREE" : money(order.total_usd);
+}
 function shortDate(value) {
     const raw = String(value ?? "");
     return raw ? raw.slice(0, 10) : "—";
@@ -135,16 +146,22 @@ function shortDate(value) {
  */
 export function orderStage(order) {
     if (order.refunded_at)
-        return { label: "refunded", colour: DIM };
+        return { label: order.is_free ? "cancelled" : "refunded", colour: DIM };
+    // A FREE order is never "paid out" — nobody was paid. It closed, and the
+    // buyer's files were released by the approval itself.
     if (order.settled_at)
-        return { label: "paid out", colour: GREEN };
-    if (order.refund_requested_at)
-        return { label: "refund asked", colour: YELLOW };
+        return { label: order.is_free ? "closed" : "paid out", colour: GREEN };
+    if (order.refund_requested_at) {
+        return { label: order.is_free ? "cancel asked" : "refund asked", colour: YELLOW };
+    }
     if (order.changes_requested_at)
         return { label: "changes asked", colour: YELLOW };
     if (order.delivery_id)
         return { label: "delivered", colour: CYAN };
-    if (!order.funded)
+    // "UNFUNDED" is the vendor's do-not-work signal, and it is meaningless on the
+    // free rail: a free order carries no deposit BY DESIGN and is still real work
+    // the vendor agreed to. Flagging it red would train vendors to abandon it.
+    if (!order.funded && !order.is_free)
         return { label: "UNFUNDED", colour: RED };
     return { label: "waiting on vendor", colour: YELLOW };
 }
@@ -154,9 +171,10 @@ function printOrderRow(order, opts = {}) {
         ? ` · ${String(order.buyer_name || order.buyer_email)}`
         : "";
     console.log(`  ${BOLD}${order.order_id}${RESET}  ${order.machine_title}`
-        + `  ${DIM}${order.packs}× pack · ${order.video_count} videos · ${money(order.total_usd)}`
+        + `  ${DIM}${order.packs}× pack · ${order.video_count} videos · ${orderPrice(order)}`
         + `${who} · ${shortDate(order.created_at)}${RESET}`
-        + `  ${stage.colour}${stage.label}${RESET}`);
+        + `  ${stage.colour}${stage.label}${RESET}`
+        + (order.is_free ? `  ${CYAN}free first order${RESET}` : ""));
 }
 function printCardRow(card) {
     const shelf = card.listed
@@ -317,6 +335,11 @@ export const SHOP_HELP = `vidfarm shop — your storefront on the vidfarm market
   a buyer orders a pack from it. Every card waits for a manual review before it
   reaches the public shelf; \`shop\` tells you which state each one is in.
 
+  NEW SHOP. The platform can mark a shop so that every buyer's FIRST order there
+  is free — one pack, $0. You cannot set it or clear it; \`shop\` reports it, and
+  an operator grants it. Those orders are REAL WORK with no deposit behind them,
+  they never pay out, and the buyer's approval is final. Work them normally.
+
   Earning WITHOUT a shop? You do not need one — read vidfarm.cc/agentic-clipper.md
   and use \`vidfarm gigs\`. A shop is how buyers come to you instead.
 
@@ -374,6 +397,15 @@ async function cmdShopShow(ctx) {
     if (shop.headline)
         console.log(`  ${shop.headline}`);
     console.log(`  ${CYAN}${shop.shop_url}${RESET}`);
+    if (shop.new_shop) {
+        // The vendor cannot set this and cannot clear it — it is a promise the
+        // PLATFORM makes to buyers, so the console reports it rather than offering
+        // it. Reported at all because it changes what the vendor is agreeing to:
+        // real work, no deposit behind it.
+        console.log(`  ${GREEN}NEW SHOP${RESET} — every buyer's first order here is free, one pack at $0.`);
+        console.log(`  ${DIM}Those orders carry no deposit and the buyer's approval is final.`
+            + ` Work them like any other order. Granted by the platform; ask an operator to change it.${RESET}`);
+    }
     if (!result.body.dollarplatoon_connected) {
         console.log(`  ${YELLOW}No Dollar Platoon key on this account — your cards cannot take a paid order.${RESET}`);
         console.log(`  ${DIM}Connect it at ${ctx.host}/settings/marketplace${RESET}`);
@@ -539,6 +571,13 @@ async function cmdOrderDetail(ctx, orderId) {
         return;
     const { order, buyer, delivery, thread, review } = result.body;
     printOrderRow({ ...order, buyer_name: buyer?.name, buyer_email: buyer?.email }, { showBuyer: true });
+    if (order.is_free) {
+        // A vendor reading "$0" needs to know it is the promotion and not a broken
+        // order — and needs to know the undo rules are inverted before they ask a
+        // buyer to "just approve it".
+        console.log(`  ${CYAN}This is the buyer's free first order.${RESET}`
+            + ` ${DIM}No deposit, no payout, and their approval closes it for good.${RESET}`);
+    }
     if (order.notes)
         console.log(`\n${BOLD}Their brief${RESET}\n  ${order.notes.replace(/\n/g, "\n  ")}`);
     if (order.answers?.length) {
@@ -660,6 +699,11 @@ async function cmdEarnings(ctx, values) {
     console.log(`  In escrow  ${YELLOW}${money(totals.pendingUsd)}${RESET} ${DIM}${totals.pending ?? 0} order(s)${RESET}`);
     console.log(`  Refunded   ${DIM}${money(totals.refundedUsd)} · ${totals.refunded ?? 0} order(s)${RESET}`);
     console.log(`  Ordered    ${money(totals.ordersUsd)} ${DIM}${totals.orders ?? 0} order(s)${RESET}`);
+    if (result.body.shop_slug && totals.orders && !totals.ordersUsd) {
+        // Real orders totalling nothing is what a New Shop's early history looks
+        // like. Without this line it reads as a broken rollup.
+        console.log(`  ${DIM}Orders at $0 are free first orders — they close without a payout.${RESET}`);
+    }
     for (const machine of result.body.machines ?? []) {
         console.log(`    ${machine.label || machine.machineId} ${DIM}${money(machine.totals?.payoutsUsd)} paid out${RESET}`);
     }
@@ -821,10 +865,20 @@ export const PURCHASES_HELP = `vidfarm purchases — buy packs of videos on the
     accept    approve and pay. FINAL, in both directions.
     changes   free. Nothing moves — the vendor re-delivers and you rule again.
     refund    the escrow comes back to you. Whoever signs it pays the gas.
+              On a FREE order this is a cancel: it closes the order and returns
+              nothing, because nothing was taken.
+
+  FIRST ORDER FREE — some shops are marked NEW SHOP by the platform, and your
+  first order there is one pack at $0. \`purchases shelf\` flags the offer;
+  \`purchases pack\` says whether YOU still have yours. It is one per shop, not
+  one per card, and it changes the rules: no deposit, nothing to refund, and
+  YOUR APPROVAL IS FINAL — it releases the files at once, with no payout step
+  after it to hold anything back. Cancelling does not give the free order back.
 
   THE SHELF
   purchases shelf [--shop <slug>]        What is for sale        → GET  ${API}/shelf
-  purchases pack <shop>/<machineId>      One card, its examples and reviews
+  purchases pack <shop>/<machineId>      One card, its examples, reviews, and
+                                         whether your free first order is still there
 
   BUYING
   purchases buy <shop>/<machineId> [--packs <n>] [--notes "<brief>"]
@@ -863,6 +917,29 @@ export function splitPackRef(ref, values) {
         return { shop: explicitShop, machine: raw };
     throw new MarketplaceError("Name the pack as <shopSlug>/<machineId> — `vidfarm purchases shelf` lists both.");
 }
+/**
+ * Does THIS account still have its free first order at this shop?
+ *
+ * A separate call on purpose. The shelf is shared-cached and can only say that
+ * the OFFER exists (`shop.new_shop`); the entitlement is per-account, so it has
+ * its own no-store route.
+ *
+ * Fails CLOSED — an unreachable answer is `false`, which prices the order at
+ * the paid number. Showing $0 and then charging is the one direction that is
+ * unforgivable, so this only ever LOWERS a price it already showed.
+ */
+async function freeOrderAvailable(ctx, shopSlug) {
+    const result = await call(ctx, "GET", `${API}/free-order-status/${encodeURIComponent(shopSlug)}`)
+        .catch(() => null);
+    return result?.ok === true && result.body?.free_available === true;
+}
+/** The three sentences a buyer must read BEFORE they consent to a free order. */
+const FREE_ORDER_TERMS = [
+    "It is ONE pack, at $0, and you get one per shop — not one per card.",
+    "Nothing is deposited, so there is no escrow and nothing to refund.",
+    "YOUR APPROVAL IS FINAL and releases the files at once. There is no payout to hold back,"
+        + " so accepting is the whole transaction."
+];
 async function cmdShelf(ctx, values) {
     const result = await call(ctx, "GET", `${API}/shelf`, {
         query: { shop: optionalText(values.shop), limit: optionalText(values.limit) }
@@ -877,7 +954,10 @@ async function cmdShelf(ctx, values) {
     }
     console.log(`${BOLD}${packs.length} pack${packs.length === 1 ? "" : "s"} for sale${RESET}`);
     for (const pack of packs) {
-        console.log(`\n  ${BOLD}${pack.title}${RESET} ${DIM}by ${pack.shop.display_name}${RESET}`);
+        console.log(`\n  ${BOLD}${pack.title}${RESET} ${DIM}by ${pack.shop.display_name}${RESET}`
+            // The OFFER, which is the same for everybody and safe on a cached list.
+            // Whether YOU still have yours is answered by `purchases pack`.
+            + (pack.shop.new_shop ? `  ${GREEN}FIRST ORDER FREE${RESET}` : ""));
         console.log(`    ${money(pack.price_per_lot_usd)} for ${pack.lot_size} videos`
             + `${pack.delivery_estimate ? ` ${DIM}· ${pack.delivery_estimate}${RESET}` : ""}`);
         if (pack.note)
@@ -897,6 +977,19 @@ async function cmdPack(ctx, values, ref) {
         + `${pack.delivery_estimate ? ` · ${pack.delivery_estimate}` : ""}`);
     if (pack.note)
         console.log(`  ${pack.note}`);
+    // The card above is a cached, public answer. THIS is the per-account one, and
+    // it is the only place that can say the word "you".
+    if (result.body.shop.new_shop) {
+        if (await freeOrderAvailable(ctx, result.body.shop.shop_slug)) {
+            console.log(`\n  ${GREEN}Your first order at this shop is FREE — one pack, $0.${RESET}`);
+            for (const term of FREE_ORDER_TERMS)
+                console.log(`  ${DIM}· ${term}${RESET}`);
+        }
+        else {
+            console.log(`\n  ${DIM}This shop offers a free first order, but you have already used yours.`
+                + ` This one is ${money(pack.price_per_lot_usd)}.${RESET}`);
+        }
+    }
     if (pack.before_you_buy_note) {
         console.log(`\n  ${YELLOW}Before you buy${RESET}\n  ${pack.before_you_buy_note}`);
     }
@@ -938,9 +1031,37 @@ async function cmdBuy(ctx, values, ref) {
         ].join("\n"));
     }
     const total = Math.round(packs * Number(pack.price_per_lot_usd) * 100) / 100;
+    // ── is this one free? ──
+    //
+    // ADVISORY, and only ever downward. The order route claims the free pack
+    // again with a conditional write, so a stale yes here cannot mint a free
+    // order — it can only produce a confirmation that was too generous, and the
+    // server then charges the real price. Which is why this is read BEFORE the
+    // confirmation and never after: quoting $0 and then charging is the one
+    // direction a buyer cannot forgive.
+    const free = card.body.shop.new_shop === true
+        && await freeOrderAvailable(ctx, card.body.shop.shop_slug);
+    // A free order is ONE pack whatever was asked for — the free rail prices a
+    // whole order at $0 and cannot discount part of one. Say so before they
+    // consent, rather than silently delivering a third of what they typed.
+    if (free && packs > 1 && !ctx.json) {
+        console.error(`${YELLOW}Your free first order is ONE pack. `
+            + `Ordering ${packs} would be charged in full — drop --packs to take the free one.${RESET}`);
+    }
     if (!values.yes && !ctx.json) {
         console.log(`${BOLD}${packs} × ${pack.title}${RESET} from ${card.body.shop.display_name}`);
-        console.log(`  ${packs * pack.lot_size} videos · ${BOLD}${money(total)}${RESET} into escrow now`);
+        if (free && packs === 1) {
+            console.log(`  ${pack.lot_size} videos · ${GREEN}${BOLD}FREE${RESET}`
+                + ` ${DIM}— your first order at this shop${RESET}`);
+            // THE CONSENT POINT. "Free" is the part a buyer reads; the part they must
+            // read is that free costs them the undo. On this rail there is no escrow
+            // to hold back and approval ends the order outright.
+            for (const term of FREE_ORDER_TERMS)
+                console.log(`  ${YELLOW}· ${term}${RESET}`);
+        }
+        else {
+            console.log(`  ${packs * pack.lot_size} videos · ${BOLD}${money(total)}${RESET} into escrow now`);
+        }
         if (pack.before_you_buy_note)
             console.log(`  ${YELLOW}${pack.before_you_buy_note}${RESET}`);
         console.log(`\n  ${DIM}Add -y to place it.${RESET}`);
@@ -975,8 +1096,21 @@ async function cmdBuy(ctx, values, ref) {
         return;
     console.log(`${GREEN}${result.body.replay ? "Already ordered." : "Ordered."}${RESET}`
         + ` ${BOLD}${result.body.order_id}${RESET}`);
-    console.log(`  ${result.body.video_count} videos · ${money(result.body.total_usd)}`
-        + ` · ${result.body.funded ? `${GREEN}funded${RESET}` : `${YELLOW}NOT funded — no deposit was taken${RESET}`}`);
+    // THE SERVER DECIDED, not the check above. The claim is a conditional write
+    // and this is its answer, so a race that lost prints the price it was charged.
+    console.log(`  ${result.body.video_count} videos · `
+        + (result.body.free ? `${GREEN}FREE — your first order at this shop${RESET}` : money(result.body.total_usd))
+        + ` · ${result.body.funded
+            ? (result.body.free ? `${GREEN}live${RESET}` : `${GREEN}funded${RESET}`)
+            // On the free rail there is nothing to fund, so an unfunded free order
+            // means it never reached Dollar Platoon at all — a different fault, and
+            // it needs a different sentence.
+            : (result.body.free
+                ? `${YELLOW}NOT live — it did not reach Dollar Platoon${RESET}`
+                : `${YELLOW}NOT funded — no deposit was taken${RESET}`)}`);
+    if (result.body.free) {
+        console.log(`  ${YELLOW}Your approval on this order is FINAL and releases the files at once.${RESET}`);
+    }
     console.log(`  ${CYAN}${ctx.host}${result.body.order_url}${RESET}`);
 }
 async function cmdPurchasesList(ctx) {
@@ -991,7 +1125,7 @@ async function cmdPurchasesList(ctx) {
     }
     for (const row of rows) {
         console.log(`  ${BOLD}${row.order_id ?? row.delivery_id}${RESET}  ${row.machine_title}`
-            + ` ${DIM}from ${row.shop_name} · ${money(row.total_usd)} · ${shortDate(row.created_at)}${RESET}`
+            + ` ${DIM}from ${row.shop_name} · ${orderPrice(row)} · ${shortDate(row.created_at)}${RESET}`
             + `  ${row.opened_at ? `${DIM}opened${RESET}` : `${CYAN}sealed${RESET}`}  ${row.status}`);
     }
 }
@@ -1013,7 +1147,12 @@ async function cmdPurchaseDetail(ctx, orderId) {
         console.log(`\n${BOLD}The pack${RESET} ${DIM}${delivery.items.length} item(s)`
             + `${delivery.opened_at ? "" : " · still sealed"}${RESET}`);
         if (!delivery.masters_released) {
-            console.log(`  ${YELLOW}Masters are locked until you accept and the payout lands.${RESET}`);
+            // Two rails, two release rules, and the difference matters to a buyer
+            // deciding whether to accept: on a paid order the payout unlocks the
+            // masters, on a free one the approval does it by itself.
+            console.log(order.is_free
+                ? `  ${YELLOW}Masters are locked until you accept. On a free order accepting IS the end — there is no payout after it.${RESET}`
+                : `  ${YELLOW}Masters are locked until you accept and the payout lands.${RESET}`);
         }
         for (const item of delivery.items) {
             const verdict = item.verdict === "approved"
@@ -1042,9 +1181,13 @@ async function cmdPurchaseDetail(ctx, orderId) {
     if (review)
         console.log(`\n${BOLD}Your review${RESET} ${review.overall}/5`);
     const moves = [
-        can?.accept ? `accept (pays ${money(order.total_usd)}, FINAL)` : null,
+        can?.accept
+            ? (order.is_free ? "accept (FINAL, nothing charged)" : `accept (pays ${money(order.total_usd)}, FINAL)`)
+            : null,
         can?.request_changes ? "changes (free)" : null,
-        can?.refund ? "refund" : null,
+        // "refund" on an order that cost nothing reads as a bug. Same route either
+        // way — it closes the order — but the word has to match what happened.
+        can?.refund ? (order.is_free ? "cancel" : "refund") : null,
         can?.review ? "review" : null
     ].filter(Boolean);
     if (moves.length)
@@ -1112,14 +1255,24 @@ async function cmdRate(ctx, values, orderId, itemId, verdictWord) {
 }
 async function cmdAccept(ctx, values, orderId) {
     const body = await fetchOrder(ctx, orderId);
+    const free = body.order.is_free === true;
     if (!values.yes && !ctx.json) {
-        // The one command in this file that spends money irreversibly. It gets a
-        // confirmation for the same reason the web card has a dialog.
-        console.log(`${BOLD}Accepting pays ${money(body.order.total_usd)} to ${body.order.shop_name}, in full.${RESET}`);
-        console.log(`  Dollar Platoon's verdict is FINAL — there is no undo, and no partial payment.`);
+        // The one command in this file that cannot be undone. It gets a
+        // confirmation for the same reason the web card has a dialog — and a FREE
+        // order needs it MORE, not less: nothing is charged, so the only thing the
+        // buyer is spending is their right to send the pack back.
+        console.log(free
+            ? `${BOLD}Accepting closes this order for good. Nothing is charged — it is your free first order.${RESET}`
+            : `${BOLD}Accepting pays ${money(body.order.total_usd)} to ${body.order.shop_name}, in full.${RESET}`);
+        console.log(free
+            ? `  Your verdict is FINAL and releases the files at once. There is no payout to hold back,`
+                + ` so this IS the end of the order — you cannot ask for changes afterwards.`
+            : `  Dollar Platoon's verdict is FINAL — there is no undo, and no partial payment.`);
         const rejected = (body.delivery?.items ?? []).filter((item) => item.verdict === "rejected").length;
         if (rejected) {
-            console.log(`  ${YELLOW}You marked ${rejected} video(s) wrong. Accepting pays for them anyway.${RESET}`);
+            console.log(free
+                ? `  ${YELLOW}You marked ${rejected} video(s) wrong. Accepting takes the pack as it is.${RESET}`
+                : `  ${YELLOW}You marked ${rejected} video(s) wrong. Accepting pays for them anyway.${RESET}`);
             console.log(`  ${YELLOW}Free alternative: vidfarm purchases changes ${orderId} "<what to fix>"${RESET}`);
         }
         console.log(`\n  ${DIM}Add -y to accept.${RESET}`);
@@ -1130,9 +1283,11 @@ async function cmdAccept(ctx, values, orderId) {
     if (emit(ctx, result.body))
         return;
     console.log(`${GREEN}${result.body.message}${RESET}`);
-    if (!result.body.settled) {
-        // Approved-but-unsettled is real and recoverable. Never tell this buyer to
-        // accept again — there is nothing left to approve.
+    // Approved-but-unsettled is real and recoverable, and it is a PAID-rail
+    // state only: on the free rail the approval is the whole transaction, so
+    // there is no second call left to fail.
+    if (!result.body.settled && !free) {
+        // Never tell this buyer to accept again — there is nothing left to approve.
         console.log(`${YELLOW}The verdict landed but the payout did not. Do NOT accept again — retry the payout shortly.${RESET}`);
     }
 }
@@ -1154,9 +1309,19 @@ async function cmdBuyerRefund(ctx, values, orderId) {
     assertOk(result, "purchases refund");
     if (emit(ctx, result.body))
         return;
+    // The server's own sentence already knows which rail it was on — a free
+    // order gets "cancelled", a paid one "refunded" — so it is printed as-is
+    // rather than reworded here.
     console.log(`${GREEN}${result.body.message}${RESET}`);
     if (result.body.tx_hash)
         console.log(`  ${DIM}tx ${result.body.tx_hash}${RESET}`);
+    // A spent free order does NOT come back. Said here because this is the one
+    // command that spends it, and a buyer cancelling to "re-order properly"
+    // would otherwise find out by being charged.
+    if (result.body.free_spent) {
+        console.log(`  ${YELLOW}Your free first order at this shop stays used. `
+            + `A new order here will be charged.${RESET}`);
+    }
 }
 async function cmdReview(ctx, values, orderId) {
     const axes = ["value", "speed", "quality", "support"];

package/marketplace.md

@@ -52,6 +52,12 @@ Both take `--json` on every subcommand, and both authenticate on the ordinary vi
 (`vidfarm login`, `VIDFARM_API_KEY`, or `--api-key`). The marketplace is paid-only, so a free key
 reaches the routes and is refused with `402`.
 
+**One shop-level rule cuts across both verbs: NEW SHOP.** The platform can mark a shop so every
+buyer's *first* order there is free — one pack, $0, one per shop. Those orders carry no deposit and
+never pay out, and **the buyer's approval is final and releases the files by itself** rather than
+waiting for a payout. Buyers: § *first order free* in `marketplace-buyer.md`. Vendors: § *a NEW SHOP
+order pays nothing* below. Either way, read `is_free` on the order — never `total_usd == 0`.
+
 **This document is the shared reference underneath both harnesses** — the keys, the REST surface,
 the machines, the proof rules, the payout rules. The harness tells you *what loop to run*; this file
 tells you *what each call does*. Read the harness for your side first, then use this as the manual.
@@ -1699,6 +1705,24 @@ dollar platoon task**, which is why the order page and the task thread are the s
 | you deliver | proof — watermarked evidence + **sealed note** |
 | the buyer's pack | `https://vidfarm.cc/delivery/<id>` |
 
+#### a NEW SHOP order pays nothing, and it is still real work
+
+if your shop is marked **new shop**, every buyer's **first order** at it is free — one pack, $0. the
+platform grants that, not you; `vidfarm shop` reports it and an operator changes it. what matters
+while you are working one:
+
+- **it carries no deposit and it never pays out.** `vidfarm shop orders` shows it as `FREE`, not as
+  `UNFUNDED` — those are different things, and the red one means *do not work this*. a free order is
+  an order the vendor agreed to take. work it normally.
+- **the buyer's approval is final and releases your files at once.** on a paid order the payout
+  unlocks the clean masters; here the approval does it alone, because there is no payout afterwards.
+  so there is no window in which to renegotiate — deliver what you would deliver for money.
+- **your earnings chart will show orders totalling $0.** that is the promotion, not a broken rollup.
+
+underneath it is a **separate dollar platoon gig** (`dpFreeGigId`) with `list_price: 0`. their API
+locks a gig's price mode at creation, so one gig cannot sell both free and paid — which is why a
+machine that does both owns two. you never choose which: the order lands in the right one.
+
 #### the delivery url — vidfarm mints it, you never invent it
 
 **you do not construct a `/delivery/` url.** it is minted when you fulfil the order, and it is the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.63",
+  "version": "0.21.64",
   "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": {