@officexapp/vidfarm-devcli 0.21.61 → 0.21.63

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

@@ -8,6 +8,10 @@
 // api key, read the feed to find clients, join a machine, claim a task, and
 // submit your proof.
 //
+// Those two sides are a VIDFARM distinction — paid plan versus none. Dollar
+// Platoon itself has no personas: one account, and per machine you are its
+// Owner or a Participant. Its web pages live under `/gigs*` only.
+//
 // Everything here talks to Dollar Platoon's own API. The key is resolved in
 // this order:
 //   1. --dp-key <key>
@@ -21,6 +25,7 @@ import { parseArgs } from "node:util";
 import { readFileSync } from "node:fs";
 import { readStoredAuth } from "./auth-store.js";
 import { verifyProof } from "./proof-verify.js";
+import { buildSealedDeliverable, sealDeliverable, describeSealedDeliverable } from "./delivery-seal.js";
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
 const GREEN = "\x1b[32m";
@@ -116,6 +121,17 @@ GIGWORKER — "help me earn on vidfarm" (free — bring your own key: export DOL
     --private-note "<text>"        Anything else that follows the master (ProRes, project
                                    files, music licence id). 8000 chars, and on a SUBMITTED
                                    proof it cannot be changed — withdraw it first, or draft it.
+    Delivering to a VIDFARM order (a vending-machine shop on vidfarm.cc/marketplace):
+    --project <url>                The composition folder — composition.html + composition.json
+                                   — so the buyer can FORK your build, not just download it.
+    --delivery-url <url>           The pack this settles: https://vidfarm.cc/delivery/del_…
+                                   Minted by the shop console when you fulfil the order.
+    --preview-note "<text>"        What the WATERMARKED cut is (aspect, length, fps). It
+                                   describes the half they can already see.
+    --sealed                       Force the vidfarm json note even with none of the above.
+                                   Any of the three flags turns it on by itself. The note is
+                                   then json WHOLE — your prose moves into --private-note,
+                                   which vidfarm renders as your message on the pack.
     --mailbox <id> --tags a,b --note "<text>"   (--note is the PUBLIC feedback field)
     --ask <usd>                    Quote your own price (machines with price offers on). An
                                    ask is a QUOTE — the buyer must approve at that number.
@@ -129,6 +145,8 @@ GIGWORKER — "help me earn on vidfarm" (free — bring your own key: export DOL
   gigs drafts <gig-id>             Your unsent drafts on that machine
   gigs edit-draft <gig-id> <proof-id> [--proof <url>…] [--private-note "<t>"] [--ask <usd>]
                                    Change an unsent draft. --private-note "" clears it.
+                                   Takes --clean-master and the vidfarm delivery flags too, so
+                                   a missing master or a lost delivery note is repaired here.
   gigs send <gig-id> <proof-id>    Send a draft. The price is snapshotted NOW, not when you
                                    saved it, and the review clock starts here.
   gigs withdraw <gig-id> <proof-id>   THE UNDO. Pulls a pending proof back to draft, stops the
@@ -139,6 +157,10 @@ GIGWORKER — "help me earn on vidfarm" (free — bring your own key: export DOL
                                    inside a rollup or already paid is final.
   gigs discard <gig-id> <proof-id>    Delete a draft and free its task. Drafts only — a
                                    submitted proof stays on the record. (alias: delete-draft)
+  gigs seal --clean-master-url <url> [--project <url>] [--delivery-url <url>]
+                                   Print the vidfarm delivery note as json and stop. No key
+                                   needed. Use it to check what submit would send, or to build
+                                   the note for a curl you write yourself. Never hand-roll it.
   gigs proof <gig-id> <proof-id>   Read your own proof back: paid_out_at + the private note
   gigs earnings                    Your rollups + totals. (aliases: rollups, paid)
   gigs mine                        Your mailboxes across every gig
@@ -191,7 +213,7 @@ async function resolveAuth(values) {
     throw new GigsAuthMissingError([
         "No Dollar Platoon key found.",
         "  Any plan:   run `vidfarm login` — every vidfarm account (free included) holds a key.",
-        "  Gigworker:  export DOLLARPLATOON_API_KEY=… from https://dollarplatoon.com/gigworker/settings",
+        "  Gigworker:  export DOLLARPLATOON_API_KEY=… from https://dollarplatoon.com/settings",
         "  Or pass it directly: --dp-key <key>"
     ].join("\n"));
 }
@@ -412,8 +434,10 @@ const MACHINE_ALIASES = {
 };
 /** Both machines, found by their stable `vidfarm_vm_<slug>` tag. */
 async function listMachines(auth) {
-    const body = await dp(auth, "/gigs/mine", { query: { tag: "vidfarm_vm_" } });
-    const gigs = body.gigs ?? body.items ?? body.data ?? [];
+    // Paged. `?tag=` is matched INSIDE a page, so a buyer with a few order gigs
+    // can have a machine sitting behind the cursor — and a machine we cannot see
+    // is one `resolveGigId` reports as missing.
+    const { rows: gigs } = await pageAll(auth, "/gigs/mine", (body) => body.gigs ?? body.items ?? body.data ?? [], { tag: "vidfarm_vm_" });
     return gigs.map((gig) => {
         const tag = (gig.tags ?? []).find((t) => typeof t === "string" && t.startsWith("vidfarm_vm_")) ?? "";
         return {
@@ -453,8 +477,11 @@ async function resolveInviteUrl(auth, gigId) {
             return `https://dollarplatoon.com/gig/${encodeURIComponent(gigId)}/join?invite=${encodeURIComponent(String(invite.token))}`;
         return "";
     };
-    const listed = await dp(auth, `/gigs/${gigId}/invites`).catch(() => ({}));
-    const invites = Array.isArray(listed.invites) ? listed.invites : [];
+    // Paged: not finding the durable `default` invite MINTS ANOTHER, so stopping
+    // at page one is how a machine collects dead links it will never redeem.
+    const invites = await pageAll(auth, `/gigs/${gigId}/invites`, (body) => body.invites ?? [])
+        .then((r) => r.rows)
+        .catch(() => []);
     const reusable = invites.filter((i) => !i.revoked && !i.exhausted && !i.email && (i.max_uses === null || i.max_uses === undefined));
     const chosen = reusable.find((i) => i.label === "default") ?? reusable[0];
     if (chosen && pick(chosen))
@@ -1314,6 +1341,64 @@ export async function cmdVerifyProof(values) {
     if (blocked)
         process.exitCode = 2;
 }
+// ── the vidfarm delivery note ────────────────────────────────────────────────
+/**
+ * Build the sealed note from submit's own flags — or return null, meaning this
+ * proof is a plain-text delivery on somebody else's gig and must stay one.
+ *
+ * The trigger is any VIDFARM-ONLY flag. A worker on a stranger's machine never
+ * passes one, so they never get a json blob where the buyer expected a sentence.
+ *
+ * ONE item, on purpose. A `gigs submit` call carries one task and one cut, and
+ * the multi-item deliveries are made in the shop console, which builds the same
+ * shape from its own form. A vendor who really is delivering a batch from the
+ * terminal builds it with `gigs seal` and passes the json through.
+ */
+function sealedFrom(values, proofs, masterUrl) {
+    const project = values.project ? String(values.project) : "";
+    const deliveryUrl = values["delivery-url"] ? String(values["delivery-url"]) : "";
+    const previewNote = values["preview-note"] ? String(values["preview-note"]) : "";
+    if (!values.sealed && !project && !deliveryUrl && !previewNote)
+        return null;
+    return buildSealedDeliverable({
+        deliveryUrl,
+        // In prose the private note is everything-after-the-master. In the sealed
+        // shape it is the VENDOR'S MESSAGE, which is where vidfarm renders it on the
+        // pack — so it moves here rather than being lost or duplicated per item.
+        vendorNote: values["private-note"] ? String(values["private-note"]) : "",
+        items: [{
+                masterUrls: masterUrl ? [masterUrl] : [],
+                previewUrls: proofs,
+                previewNote,
+                projectUrl: project,
+                notes: values["master-note"] ? String(values["master-note"]) : ""
+            }]
+    });
+}
+/**
+ * `vidfarm gigs seal` — print the note and stop. Needs NO key.
+ *
+ * The whole point of shipping this is that nobody hand-rolls `JSON.stringify`:
+ * a note with the right fields spelled slightly wrong parses fine, opens to
+ * nothing on the buyer's pack, and cannot be patched once the proof is sent.
+ */
+function cmdSeal(values) {
+    const proofs = [].concat(values.proof ?? []);
+    const masterUrl = values["clean-master-url"] ? String(values["clean-master-url"]) : "";
+    if (!masterUrl && !values.project) {
+        throw new Error("gigs seal needs at least --clean-master-url <url> (upload it first: vidfarm gigs upload ./final-clean.mp4) or --project <url>.");
+    }
+    // Forced on: `seal` IS the sealed format, so it never asks for --sealed too.
+    const sealed = sealedFrom({ ...values, sealed: true }, proofs, masterUrl);
+    if (values.json) {
+        console.log(sealDeliverable(sealed));
+        return;
+    }
+    for (const line of describeSealedDeliverable(sealed))
+        console.log(`${DIM}${line}${RESET}`);
+    console.log("");
+    console.log(sealDeliverable(sealed));
+}
 async function cmdSubmit(auth, values, positionals) {
     const gigId = positionals[0];
     if (!gigId)
@@ -1382,14 +1467,35 @@ async function cmdSubmit(auth, values, positionals) {
     // --clean-master uploads the file to DollarPlatoon's own s3 first, because the
     // note presigns that url at read time off a random key; a link you host is
     // reachable the moment anyone guesses it.
-    const noteParts = [];
-    if (values["clean-master"]) {
-        const url = await uploadToDollarPlatoon(auth, String(values["clean-master"]));
-        noteParts.push(`Clean master, no watermark: ${url}`);
+    const masterUrl = values["clean-master"]
+        ? await uploadToDollarPlatoon(auth, String(values["clean-master"]))
+        : (values["clean-master-url"] ? String(values["clean-master-url"]) : "");
+    // TWO NOTE FORMATS, and the difference is who reads it.
+    //
+    // A stranger's own vending machine reads the note as prose, so prose is the
+    // default and nothing about that changed. A VIDFARM order reads it as json —
+    // it is how the buyer's pack finds the master, the composition folder and
+    // your message — and json must be the WHOLE string, so the two cannot be
+    // mixed. Deciding by whether a vidfarm-only flag was passed means a worker on
+    // someone else's gig never accidentally sends a buyer a blob to read.
+    const sealedNote = sealedFrom(values, proofs, masterUrl);
+    let privateNote;
+    if (sealedNote) {
+        privateNote = sealDeliverable(sealedNote);
+        if (!values.json) {
+            console.log(`${DIM}Sealing a vidfarm delivery note:${RESET}`);
+            for (const line of describeSealedDeliverable(sealedNote))
+                console.log(`  ${DIM}${line}${RESET}`);
+        }
+    }
+    else {
+        const noteParts = [];
+        if (masterUrl)
+            noteParts.push(`Clean master, no watermark: ${masterUrl}`);
+        if (values["private-note"])
+            noteParts.push(String(values["private-note"]));
+        privateNote = noteParts.join("\n");
     }
-    if (values["private-note"])
-        noteParts.push(String(values["private-note"]));
-    const privateNote = noteParts.join("\n");
     const result = await dp(auth, `/gigs/${encodeURIComponent(gigId)}/proofs`, {
         method: "POST",
         body: {
@@ -1482,10 +1588,37 @@ async function cmdEditDraft(auth, values, positionals) {
     const body = {};
     if (proofs.length)
         body.proofs = proofs;
-    // An empty string is the documented way to CLEAR either field, so the test is
-    // "was the flag present", never "is the value truthy".
-    if (values["private-note"] !== undefined)
+    // Repair a VIDFARM delivery note the same way submit writes it. Without this
+    // the obvious repair — `edit-draft --private-note "…"` — would replace a
+    // sealed json note with prose, and the buyer's pack would open to nothing.
+    // The trigger is the same: any vidfarm-only flag.
+    // A missing master is the other half of the same repair, so --clean-master
+    // uploads here too rather than sending the vendor back to `gigs upload`.
+    const masterUrl = values["clean-master"]
+        ? await uploadToDollarPlatoon(auth, String(values["clean-master"]))
+        : (values["clean-master-url"] ? String(values["clean-master-url"]) : "");
+    const sealedNote = sealedFrom(values, proofs, masterUrl);
+    if (sealedNote) {
+        body.private_note = sealDeliverable(sealedNote);
+        if (!values.json) {
+            console.log(`${DIM}Resealing the vidfarm delivery note:${RESET}`);
+            for (const line of describeSealedDeliverable(sealedNote))
+                console.log(`  ${DIM}${line}${RESET}`);
+        }
+    }
+    else if (masterUrl) {
+        // Prose, in the same layout `gigs submit` writes, so a draft repaired here
+        // reads identically to one that never needed repairing.
+        const noteParts = [`Clean master, no watermark: ${masterUrl}`];
+        if (values["private-note"])
+            noteParts.push(String(values["private-note"]));
+        body.private_note = noteParts.join("\n");
+    }
+    else if (values["private-note"] !== undefined) {
+        // An empty string is the documented way to CLEAR either field, so the test
+        // is "was the flag present", never "is the value truthy".
         body.private_note = String(values["private-note"]) || null;
+    }
     if (values.ask !== undefined)
         body.asking_price = String(values.ask) === "" ? null : Number(values.ask);
     if (!Object.keys(body).length) {
@@ -1641,7 +1774,9 @@ function options() {
         tag: { type: "string" },
         title: { type: "string" },
         subtext: { type: "string" },
-        // Bid auction (request-bids / bids / award).
+        // Bid auction (request-bids / bids / award) — a PRIVATE bid thread. On
+        // `gigs submit` the same flag means the sealed vidfarm delivery note. They
+        // never meet: one is a buyer command, the other a worker command.
         sealed: { type: "boolean" },
         bell: { type: "boolean" },
         opening: { type: "string" },
@@ -1660,6 +1795,13 @@ function options() {
         "private-note": { type: "string" },
         "clean-master": { type: "string" },
         "clean-in-proof": { type: "boolean" },
+        // The vidfarm delivery note. Any ONE of project / delivery-url /
+        // preview-note switches the private note from prose to the sealed json.
+        project: { type: "string" },
+        "delivery-url": { type: "string" },
+        "preview-note": { type: "string" },
+        "master-note": { type: "string" },
+        "clean-master-url": { type: "string" },
         draft: { type: "boolean" },
         ask: { type: "string" },
         "skip-verify": { type: "boolean" },
@@ -1682,6 +1824,10 @@ export async function runGigsCommand(argv) {
     // share-link worker with no account can still check a proof before sending it.
     if (["verify-proof", "check-proof", "preflight", "verify"].includes(sub))
         return cmdVerifyProof(values);
+    // Same reason: `seal` only formats a string. A share-link worker with no
+    // account must be able to build the note they are about to paste into a curl.
+    if (["seal", "delivery-note"].includes(sub))
+        return cmdSeal(values);
     const auth = await resolveAuth(values);
     switch (sub) {
         case "machines":

package/marketplace.md

@@ -14,13 +14,44 @@ trying to fund machines it does not own. Decide once, out loud, before anything
 | Your human… | You are | Load this harness and follow it |
 |---|---|---|
 | wants videos **made for them** — they have a product, a budget, a brand | the **buyer** | **`https://vidfarm.cc/marketplace-buyer.md`** |
-| wants to **earn money** making videos for other people | an **Agentic Clipper** | **`https://vidfarm.cc/agentic-clipper.md`** |
+| wants to **earn money** making videos for other people | an **Agentic Clipper**, a.k.a. a **vendor** | **`https://vidfarm.cc/agentic-clipper.md`** |
+
+**"Clipper" and "vendor" are the same person, and both words are correct.** *Clipper* is the role —
+someone earning by making videos. *Vendor* is what that person is called once they open a **shop** on
+`https://vidfarm.cc/marketplace` and put **vending machines** on the shelf for buyers to order packs
+from. Nothing changes between the two: the same key, the same proofs, the same payouts. A vendor just
+has a storefront and therefore an extra way to deliver — see § *delivering to a vidfarm order*.
 
 **"Agentic Clipper" means one specific thing on vidfarm: the earning mode in
 `agentic-clipper.md`** — one orchestrator agent running a long-horizon mission to earn money from
 this marketplace, spawning one subagent per task. When a human says *"run in agentic clipper mode"*,
 that file is what they are asking for. It is not a synonym for "a person who edits clips."
 
+### three verbs, and the difference between them
+
+The shop half of this marketplace was a set of web pages until 2026-08-29 — an agent could read the
+shelf and touch nothing on it. It is now a REST surface under `/api/v1/marketplace/`, and the devcli
+wraps it. **Reach for the right verb first; they do not overlap.**
+
+| Verb | What it drives | Use it when |
+|---|---|---|
+| `vidfarm shop` | **your storefront** — pack cards, orders, deliveries, reviews, payouts | you are the vendor and a buyer ordered from *your shop* |
+| `vidfarm purchases` | **your orders as a buyer** — the shelf, buying, ruling on a pack, accepting | you are spending money to get videos made |
+| `vidfarm gigs` | **Dollar Platoon underneath** — mailboxes, task queues, proofs, rollups | you are working someone else's gig, with or without a shop |
+
+`gigs` knows nothing about shops or pack cards; `shop` and `purchases` know nothing about mailboxes.
+A clipper with no storefront lives entirely in `gigs` and that is a complete, paid way to work — a
+shop is how buyers come to *you* instead of you going to the queue.
+
+```bash
+vidfarm shop help          # the vendor surface, in full
+vidfarm purchases help     # the buyer surface, in full
+```
+
+Both take `--json` on every subcommand, and both authenticate on the ordinary vidfarm key
+(`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`.
+
 **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.
@@ -161,6 +192,82 @@ export DOLLARPLATOON_API_KEY=$(curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" \
 
 Then read `https://dollarplatoon.com/skill.md`. It is the accurate live index over tasks, proofs, payouts, wallets and feeds, and it stops an agent guessing field names.
 
+## How you get told — the bell, and the two emails
+
+Both sides of the marketplace share one inbox: **`https://vidfarm.cc/notifications`**. Buyer rows and
+vendor rows sit in the same list, because one person is a buyer on one order and a vendor on the next,
+and splitting the list would make them check two pages to learn one thing.
+
+The bell that opens it sits on `/marketplace`, `/marketplace/shop` and `/shop/:slug`, and 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
+
+This is the one thing to get right before acting on a row.
+
+| the row says | it actually means | what the deposit did |
+|---|---|---|
+| **vendor:** *Order rejected* | the BUYER asked for **changes** | nothing moved. still in escrow. **re-upload** |
+| **vendor:** *Order withdrawn* | the buyer refunded | returned to the buyer. the order is dead |
+| **buyer:** *Order rejected* | the VENDOR refunded and closed it | returned to you |
+
+The first one is the trap. `request-changes` never reaches Dollar Platoon — their verdict is final in
+both directions, so a wrong caption cannot be routed through their `reject` (see
+*an order ends three ways*). A vendor who reads "rejected" and stops working has abandoned a fully
+funded order.
+
+### the page
+
+Not paid-gated — a free account can fulfil work, so it can be owed a payout. Every control is a form
+post and works with JavaScript off.
+
+```
+GET  /notifications?q=<search>&filter=all|unseen&page=<n>     newest first, 25 a page
+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, so middle-click and cmd-click behave. Clicking the row itself does
+nothing, on purpose. There is a search box, an All / Unseen filter, *Mark all seen*, and paging.
+
+The unseen **count** is not in the page HTML — `/marketplace` is shared-cached for anonymous visitors,
+so a number baked in would be one buyer's badge served to whoever came through the cache next. It
+rides the session's own access probe, 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 }
+```
+
+### the two emails
+
+`marketplace@vidfarm.cc` sends exactly two things. Nothing else ever comes from that address, which is
+what makes a single on/off switch an honest offer.
+
+| to | when | the button |
+|---|---|---|
+| the **vendor** | a buyer placed an order in their shop | *Open the order →* |
+| the **buyer** | a vendor delivered — the pack is sealed and waiting | *Tear your pack →* |
+
+**Default ON**, and on by *absence* of a preference rather than by a backfill, so every existing
+account already gets them. 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`.
+**Do not suggest turning it off as a fix for anything.** Those two mails are how the other party
+learns money moved, and a vendor who never sees an order ages past their delivery estimate and earns
+a bad review for a shop that never knew.
+
+> **Notifications are for the HUMAN. They are not a work queue.** An agent still polls
+> `GET /work/available` and `POST /gigs/$GIG/queue/poll` — see *Gigworker Instructions*. The bell tells
+> a person something happened; it does not claim tasks, and nothing here changes the polling loop.
+
 ## Client Instructions
 
 > **The operating harness for this side is `https://vidfarm.cc/marketplace-buyer.md`.** It is the
@@ -1574,6 +1681,173 @@ that `GET` returns the proof **flat** — read `.paid_out_at`, not `.proof.paid_
 
 **never put the clean master in the task's `upload_link` folder.** that folder belongs to the buyer, so anything you upload there is handed over before payout. upload the watermarked cut and the working files there; the master goes in the note.
 
+### delivering to a vidfarm ORDER — the vending machine shops on /marketplace
+
+everything above is the general case: a proof on somebody's gig, and a note the buyer reads as
+prose. **a vidfarm order is different, and it is the one case where the note has a required shape.**
+
+**"clipper" and "vendor" are the same person.** a clipper who opens a **shop** on
+`https://vidfarm.cc/marketplace` is a vendor. the shop holds **vending machines** — a machine is one
+product on the shelf, with a lot size, a price per lot and its own examples — and a buyer buys a
+**pack** from a machine. underneath, every machine is a dollar platoon gig and **every order is a
+dollar platoon task**, which is why the order page and the task thread are the same conversation.
+
+| vidfarm | dollar platoon |
+|---|---|
+| vending machine (in your shop) | gig, distribution `inbound_order` |
+| a buyer orders a pack | task, funded on publish |
+| you deliver | proof — watermarked evidence + **sealed note** |
+| the buyer's pack | `https://vidfarm.cc/delivery/<id>` |
+
+#### 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
+buyer's own pack: private to their account, `noindex`, never shared-cached.
+
+**from the terminal — this is the path for an agent:**
+
+```bash
+vidfarm shop orders                          # your queue: who is waiting on you
+vidfarm shop order ord_…                     # the brief, their links, the thread
+
+vidfarm shop deliver ord_… \
+  --item "https://…/watermarked-1.mp4::https://…/clean-1.mp4::hook lands at 0:02" \
+  --item "https://…/watermarked-2.mp4::https://…/clean-2.mp4"
+# → Sent 2 items to the buyer.
+#   Pack: https://vidfarm.cc/delivery/del_…
+```
+
+one `--item` per video. the halves are `preview::master::note`, and either url half may be a
+`|`-separated list to make that item a **slideshow**. `vidfarm shop deliver` again to **revise** —
+what you send replaces the pack.
+
+the web form at `https://vidfarm.cc/marketplace/shop/orders` does exactly the same thing, one url per
+line. both go through one call, and vidfarm does three things in it:
+
+1. creates the delivery and returns `https://vidfarm.cc/delivery/del_…`
+2. attaches it to the order
+3. submits the dollar platoon proof for you, with the note already sealed
+
+**and it tells the buyer.** fulfilling puts an *Order fulfilled* row on their
+`https://vidfarm.cc/notifications` and mails them *"your pack is ready to tear"* from
+`marketplace@vidfarm.cc`. a revision does the same, worded as a revision. **so do not also chase them
+in the thread** — they have been told, twice, and the order page is where they rule on it. (the same
+machinery told YOU about the order in the first place; see *How you get told* above.)
+
+so **when you deliver through `vidfarm shop deliver` or the console there is nothing to hand-roll.**
+the flags below are for the third route only: a task where you want the sealed note built before you
+paste it into your own `curl`, or a clipper with no shop delivering straight to a gig.
+
+a delivery link is a **signpost**, not a page. whoever opens it is sent to their own side — the buyer
+to `/marketplace/orders/:orderId#delivery`, you to `/marketplace/shop/orders/:orderId`, anyone else
+to a 404 that does not confirm the id exists. so it is safe to put in the note, and it is the one
+link that survives being forwarded.
+
+**a clipper with no shop has no delivery url, and that is fine.** send `deliveryUrl: ""` — an empty
+string is the honest answer. inventing one gives the buyer's console a link that 404s.
+
+#### attach the proof to the TASK, not to the order
+
+`task_identifier` is the **dollar platoon task id on that order** — the same id the order thread
+hangs off. it is what claims the work to you and what joins your proof to the money. never send the
+order id, never send the subject line. subjects collide and cause duplicate `409`s.
+
+#### the note is JSON, and there is a supplied function — do not hand-roll it
+
+vidfarm parses the **whole** `private_note` as json. nothing may be written before or after it: one
+sentence of greeting around the blob and the buyer's pack opens to nothing, and **a submitted proof's
+note cannot be patched.** your prose goes *inside*, in `vendorNote`.
+
+**`vidfarm gigs seal` builds it.** it needs no api key, it prints the note in words before it prints
+the json, and it is the same builder the shop console uses — so the two can never drift:
+
+```bash
+vidfarm gigs upload ./final-clean.mp4        # → a durable dollarplatoon s3 url
+
+vidfarm gigs seal \
+  --clean-master-url "https://…/clean.mp4" \
+  --proof            "https://…/watermarked.mp4" \
+  --project          "https://vidfarm.cc/directory/preview/dsh_…/files/acme-01" \
+  --delivery-url     "https://vidfarm.cc/delivery/del_…" \
+  --preview-note     "watermarked, 1080x1920, 27s, 30fps" \
+  --private-note     "Second hook tested better. Fork the folder to swap the CTA." \
+  --master-note      "ProRes + 1:1 alt in the same folder. Music: Epidemic #1234."
+```
+
+`gigs submit` takes the same flags and seals the note itself. **any one of `--project`,
+`--delivery-url` or `--preview-note` switches it on**; with none of them the note stays prose, which
+is what a stranger's own vending machine wants:
+
+```bash
+vidfarm gigs submit $GIG --task $TASK \
+  --proof https://…/watermarked.mp4 \
+  --clean-master ./final-clean.mp4 \
+  --project https://vidfarm.cc/directory/preview/dsh_…/files/acme-01 \
+  --delivery-url https://vidfarm.cc/delivery/del_… \
+  --preview-note "watermarked, 1080x1920, 27s, 30fps" \
+  --private-note "Second hook tested better. Fork the folder to swap the CTA."
+```
+
+this is the shape it writes. it is versioned because the note is read back after the payout, weeks
+later, by code that has moved on — **v2 is additive, and every v1 note still opens**:
+
+```json
+{
+  "v": 2,
+  "deliveryUrl": "https://vidfarm.cc/delivery/del_…",
+  "vendorNote": "Second hook tested better. Fork the folder to swap the CTA.",
+  "items": [
+    {
+      "itemId":      "item_1",
+      "kind":        "video",
+      "urls":        ["https://…/clean.mp4"],
+      "previewUrls": ["https://…/watermarked.mp4"],
+      "previewNote": "watermarked, 1080x1920, 27s, 30fps",
+      "projectUrl":  "https://vidfarm.cc/directory/preview/dsh_…/files/acme-01",
+      "notes":       "ProRes + 1:1 alt in the same folder. Music: Epidemic #1234."
+    }
+  ]
+}
+```
+
+| field | what belongs in it |
+|---|---|
+| `deliveryUrl` | the pack this settles. `""` if you have no shop. |
+| `vendorNote` | **your own message about the delivery** — what you changed, what to look at first, what you would do next. this is where prose lives now. |
+| `itemId` | the join. a verdict is recorded against it, and it is what matches a preview to the master that replaces it. **never the array index** — that moves the moment you re-upload. |
+| `kind` | `video` or `slideshow`. derived from how many urls you gave, never declared, so it cannot disagree with the content. |
+| `urls` | the **clean master**. the sealed half. empty means nothing unseals when they pay. |
+| `previewUrls` | the **watermarked** cut they already saw. repeating it here is what tells the note which master replaces which card. |
+| `previewNote` | what the PREVIEW is — aspect, length, fps. it describes the half they are judging. |
+| `projectUrl` | the **composition folder** — `composition.html` + `composition.json`. |
+| `notes` | what follows the MASTER: ProRes, alternate aspects, fonts, the music licence id. |
+
+#### ship the composition folder, not just a file
+
+**`projectUrl` is the field vendors forget, and it is the one that gets you rebooked.** a buyer with
+an mp4 has to come back and pay again for "make the CTA green". a buyer with the composition folder
+**forks it** — `composition.html` plus `composition.json` open in the vidfarm editor, they change the
+line themselves, and they re-render. that is the difference between selling a file and selling
+something they can keep.
+
+put the folder in your own vidfarm file directory and share it. **do not put it in the task's
+`upload_link` folder** — that folder belongs to the buyer and everything in it is handed over
+*before* payout, which is exactly what the sealed note exists to prevent. the folder link goes in the
+note with the master, and it unseals with it.
+
+#### so the four things a vendor sends, and where each one goes
+
+| what | where |
+|---|---|
+| the **watermarked preview** | `proofs[]` — public, playable, what they rule on |
+| what that preview IS | `previewNote` |
+| the **clean unwatermarked HD master** | `urls` — sealed until `paid_out_at` |
+| the **composition.html / .json folder** to fork | `projectUrl` — sealed with it |
+| **your own notes** | `vendorNote` for the delivery, `notes` for one item |
+
+the release condition is unchanged and it is not yours to trigger: the note opens on `paid_out_at`,
+not on approval, and the platform does it.
+
 ### drafts, and the undo — a submitted proof is not one-way
 
 a proof has two halves, and for a long time this document only described the second one. the first