@officexapp/vidfarm-devcli 0.21.49 → 0.21.50

package/SKILL.director.md

@@ -481,7 +481,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). 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.
+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** on EVERY plan, free included — a free account can fulfil work on the network even though buying is paid-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). 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.
 
 ## Non-Negotiables
 
@@ -770,7 +770,9 @@ devcli: `vidfarm marketplace` (browse links), `vidfarm marketplace orders`, `vid
 
 ## 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.
+**Every** vidfarm account owns a Dollar Platoon account — free plans included — and **one route hands the agent that credential**, so an agent holding only a `vidfarm-api-key` can drive the gig side without the human copying anything out of Settings.
+
+A free account gets the key and can **fulfil** work on the network (join a gig, claim a task, submit proofs, get paid in USDC). Buying — the two vending machines, orders, payouts — is the paid half.
 
 ```bash
 curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "accept: application/json" \
@@ -784,6 +786,9 @@ curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "accept: application/json" \
   "dollarplatoon_api_url": "https://dollarplatoon.com/api",
   "dollarplatoon_skill_url": "https://dollarplatoon.com/skill.md",
   "dollarplatoon_auth_header": "x-api-key",
+  "plan": "paid",                                    // "paid" | "free"
+  "can_buy": true,                                   // paid only: orders, machines, payouts
+  "can_fulfil": true,                                // every plan: claim tasks, submit proofs
   "feed_id": "FEED_01M0BCTVTKSDFZQVEY1RXA4NJK",
   "feed": { "notifications_url": "…", "notifications_result_key": "notifications",
             "registry_url": "…",      "registry_result_key": "items" },
@@ -798,8 +803,9 @@ curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "accept: application/json" \
 }
 ```
 
-- **Paid plans only** — a free account gets `402` with an `upgrade_url`. An account with no key connected yet gets `409 { setup_required: true, settings_url }`.
-- The two vending machines are **ensured on read**: a first call creates a missing one, so this route is also the setup step.
+- **Every plan answers here.** A free account gets the key with `"plan": "free"`, `can_buy: false`, an `upgrade_url`, and `machines: []` — it has no vending machines, only the key. Branch on `can_buy`, never on the presence of the key.
+- The key is **provisioned on read**: an account that never had one gets one now. `409 { setup_required: true, settings_url }` means the integration is unreachable, not that the human forgot a step.
+- On a paid plan the two vending machines are **ensured on read** too: a first call creates a missing one, so this route is also the setup step.
 - Keep the key in the environment. Do not print it into a transcript, a composition, or a report.
 
 **Dollar Platoon reads `x-api-key` and NOTHING else.** A Bearer-only request is refused with `401 {"error":"Missing x-api-key header"}` *before* the key is read — that message names the header, not the key. A key that is truly wrong says `Invalid API key` instead. (Vidfarm is the mirror image: `vidfarm-api-key` only, never Bearer.)

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

@@ -108,7 +108,7 @@ async function resolveAuth(values) {
     }
     throw new GigsAuthMissingError([
         "No Dollar Platoon key found.",
-        "  Client:     run `vidfarm login` (paid plan) — the key comes from your account.",
+        "  Any plan:   run `vidfarm login` — every vidfarm account (free included) holds a key.",
         "  Gigworker:  export DOLLARPLATOON_API_KEY=… from https://dollarplatoon.com/gigworker/settings",
         "  Or pass it directly: --dp-key <key>"
     ].join("\n"));

package/marketplace.md

@@ -6,13 +6,76 @@ Please redirect user based on whether they are a client or a gigworker, instruct
 > Served at `https://vidfarm.cc/marketplace.md`. The older `https://vidfarm.cc/crowdsourcing.md`
 > redirects here — same document, one canonical name.
 
+## Get the key over REST (no copy-paste)
+
+**Read this first. It is the fastest way onto the marketplace, and it works on every plan.**
+
+Everything on this page runs on a `DOLLARPLATOON_API_KEY`. **Every vidfarm.cc account already has one** — free plans included — and an agent holding a `VIDFARM_API_KEY` can read it in one call. No human opens a settings page, and no key is pasted into a chat.
+
+```bash
+# 1. the human makes a vidfarm.cc account (free is fine) and gives the agent a
+#    vidfarm api key from https://vidfarm.cc/settings/developer
+export VIDFARM_API_KEY="vf_live_…"
+
+# 2. the agent reads its own dollarplatoon credential
+curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" -H "accept: application/json" \
+  "https://vidfarm.cc/api/v1/user/me/marketplace"
+```
+
+```jsonc
+{
+  "ok": true,
+  "dollarplatoon_api_key": "dp_live_…",       // ← the account's OWN key
+  "dollarplatoon_api_url": "https://dollarplatoon.com/api",
+  "dollarplatoon_skill_url": "https://dollarplatoon.com/skill.md",
+  "dollarplatoon_auth_header": "x-api-key",
+  "plan": "free",                              // "free" | "paid"
+  "can_buy": false,                            // paid only: orders, machines, payouts
+  "can_fulfil": true,                          // every plan: claim tasks, submit proofs
+  "upgrade_url": "https://vidfarm.cc/pricing", // present on free only
+  "feed_id": "FEED_01M0BCTVTKSDFZQVEY1RXA4NJK",
+  "feed": { "notifications_url": "…", "notifications_result_key": "notifications",
+            "registry_url": "…",      "registry_result_key": "items" },
+  "machines": []                               // free: []. paid: the two vending machines
+}
+```
+
+One line, straight into the environment:
+
+```bash
+export DOLLARPLATOON_API_KEY=$(curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  https://vidfarm.cc/api/v1/user/me/marketplace | jq -r .dollarplatoon_api_key)
+```
+
+**Rules an agent must follow here.**
+
+- **Branch on `can_buy`, never on the presence of the key.** Every plan returns a key. `can_buy: false` means: do not try to place orders, add tasks, or run payouts — go work the gigworker flow instead.
+- The key is **provisioned on read**. An account that never had one gets one on this call, so there is no "connect it first" step to walk a human through.
+- **Two hosts, two headers.** `vidfarm.cc/api` reads `vidfarm-api-key` only. `dollarplatoon.com/api` reads `x-api-key` only. A Bearer token is refused by both. Dollar Platoon answers a Bearer-only request with `401 {"error":"Missing x-api-key header"}` *before* it reads the key — that message names the header, not the key.
+- `409 { setup_required: true }` means the integration is unreachable, not that the human missed a step. Retry, then tell the human.
+- Keep the key in the environment. Never print it into a transcript, a composition, a memory file, or a report.
+- The same key is shown to the human at `https://vidfarm.cc/settings/marketplace`, which is **not** paid-gated — it is settings.
+
+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.
+
 ## Client Instructions
 
 Please help setup agentic clipper loops for a client so they can get crowdsourced viral videos for their app.
 
 ### Start at vidfarm.cc/marketplace — you already have two vending machines
 
-You do not have to create a gig to start. Every **paid** vidfarm.cc account is provisioned with a dollarplatoon.com account **and two standing vending machines**. `https://vidfarm.cc/marketplace` opens straight onto them, and the Marketplace link appears in the sidebar. If your account predates this, just visit the page — it re-creates anything missing on load. The marketplace is a paid-plan feature: a free account sees the upgrade wall, and its machines are only created when it upgrades.
+You do not have to create a gig to start. **Every** vidfarm.cc account — free plans included — is provisioned with a dollarplatoon.com account, and every **paid** account also gets **two standing vending machines**. `https://vidfarm.cc/marketplace` opens straight onto them, and the Marketplace link appears in the sidebar. If your account predates this, just visit the page — it re-creates anything missing on load.
+
+**Which half of the network does your plan open?**
+
+| | Free plan | Paid plan |
+|---|---|---|
+| dollarplatoon.com account + api key | ✅ | ✅ |
+| `vidfarm.cc/settings/marketplace` (see your key) | ✅ | ✅ |
+| **Fulfil** work — join gigs, claim tasks, submit proofs, get paid | ✅ | ✅ |
+| **Buy** work — two vending machines, orders, invites, payouts | ❌ | ✅ |
+
+So a free account is not locked out of the marketplace, it is on the other side of it: it earns rather than spends. If you are on the free plan, jump to **Gigworker Instructions** below.
 
 | Machine | slug | dollarplatoon distribution | What it is |
 |---|---|---|---|
@@ -29,6 +92,8 @@ Both machines are ordinary dollarplatoon gigs underneath — same proofs, same a
 
 Give your agent the API key first. Get `DOLLARPLATOON_API_KEY` from `https://vidfarm.cc/settings/marketplace` or `https://dollarplatoon.com/client/settings`. Keep it in the environment, never in a memory file. Every dollarplatoon call takes it as an `x-api-key` header.
 
+**Better: let the agent fetch the key itself.** Nobody has to copy anything if the agent already holds a `VIDFARM_API_KEY` — see [Get the key over REST](#get-the-key-over-rest-no-copy-paste) below. That route works on the free plan too.
+
 **Find your two gig ids.** They carry a `vidfarm_vm_<slug>` tag, so one call gets both:
 
 ```bash
@@ -557,7 +622,16 @@ if the link answers "this share link is unavailable", the client disabled it —
 
 ### Your API key
 
-get your `DOLLARPLATOON_API_KEY` from https://gigdesk.cc/settings, or from https://dollarplatoon.com/gigworker/settings. you can also use `GIGDESK_API_KEY` instead. both keys work, so use whichever one you already have. keep the key in the environment, never in a memory file.
+**fastest path — a free vidfarm.cc account hands your agent the key over REST.** make the account (free is fine), take a vidfarm api key from https://vidfarm.cc/settings/developer, and one call gets you a dollarplatoon key with nothing pasted anywhere:
+
+```bash
+export DOLLARPLATOON_API_KEY=$(curl -s -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  https://vidfarm.cc/api/v1/user/me/marketplace | jq -r .dollarplatoon_api_key)
+```
+
+the free plan answers `"can_buy": false` — that is correct and expected. you are here to **fulfil** work, not to buy it, and every route in this section works on a free plan. full details in [Get the key over REST](#get-the-key-over-rest-no-copy-paste) at the top. the human can also read the same key at https://vidfarm.cc/settings/marketplace, which is not paid-gated.
+
+otherwise get your `DOLLARPLATOON_API_KEY` from https://gigdesk.cc/settings, or from https://dollarplatoon.com/gigworker/settings. you can also use `GIGDESK_API_KEY` instead. both keys work, so use whichever one you already have. keep the key in the environment, never in a memory file.
 
 - `GIGDESK_API_KEY` (`gd_live_…`) talks to `https://gigdesk.cc/api`
 - `DOLLARPLATOON_API_KEY` talks to `https://dollarplatoon.com/api`

package/package.json

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