@officexapp/vidfarm-devcli 0.21.38 → 0.21.42

package/SKILL.md

@@ -103,7 +103,7 @@ Otherwise, pull it over the network and load only the reference you need:
   - `references/rest-api.md` — complete REST map (load only for direct HTTP integration)
   - `recipes/` — `find-and-fork-template.md` · `retheme-template.md` · `local-edit-render-approve.md` · `onboard-a-new-director.md` · `bulk-scripting-with-a-harness.md` (volume/N-variant work) · `cutout-graphics-for-explainers.md` (sticker-art explainers)
   - `harnesses/` — `README.md` (**start here for anything harness-shaped**: the three director phrasings, the format, the DNA strands) plus the bundled bases `short-form` · `hooks` · `ugc-testimonial` · `explainer` · `product-demo`, each as `<name>.HARNESS.md`
-- **Running ad experiments (finding the winning ad):** `https://vidfarm.cc/experiment.md` — **fetch this whenever the ask is about performance rather than one video**: "which ad should I run", "test these angles", "what's working", "we post daily on N channels", or any campaign that runs for weeks. It primes you as a short-form ad scientist: the KPI interview (default north star = **comments**), channel count → testing capacity, **epochs** and **rounds**, **Creative Mode** (N free-form videos, the default, ideal for gigworkers) vs **Structured Mode** (one variable, everything else pinned by a harness, your own agents only), the composition params, and the standalone `EXPERIMENTS_DIARY.md` ledger. Plan → user approval → one static handoff document per video.
+- **Running ad experiments (finding the winning ad):** `https://vidfarm.cc/experiments.md` — **fetch this whenever the ask is about performance rather than one video**: "which ad should I run", "test these angles", "what's working", "we post daily on N channels", or any campaign that runs for weeks. It primes you as a short-form ad scientist: the KPI interview (default north star = **comments**), channel count → testing capacity, **epochs** and **rounds**, **Creative Mode** (N free-form videos, the default, ideal for gigworkers) vs **Structured Mode** (one variable, everything else pinned by a harness, your own agents only), the composition params, and the standalone `EXPERIMENTS_DIARY.md` ledger. Plan → user approval → one static handoff document per video.
 - **Crowdsourcing the editing:** `https://vidfarm.cc/crowdsourcing.md` — the client-vs-gigworker router for agentic clipper loops (a Dollar Platoon vending machine, recruiting editors, claiming tasks, proofs and payouts). This is how a Creative Mode batch gets produced in bulk.
 - **Updating Vidfarm:** `https://vidfarm.cc/update.md` — **fetch this file whenever the user asks to update/upgrade Vidfarm**, says their skill or devcli is out of date, or hits a command/route that "used to work". It's the clean uninstall→reinstall runbook for BOTH halves (the `vidfarm` skill pack and `@officexapp/vidfarm-devcli`), and it carries the current breaking-change notes — read it live rather than improvising an `npm i -g`, because the notes are exactly what a blind reinstall misses.
 - **Skill pack index (what else is installable):** `https://vidfarm.cc/skill-pack/index.json`
@@ -125,7 +125,7 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 5. "Script / batch / render loop" → `references/automation-and-local-dev.md`
 5b. **"Explainer with cutout/sticker art"** (flat illustrations on a stage, sticker sheets, "like those animated explainer videos") → `recipes/cutout-graphics-for-explainers.md`
 6. "I need TTS / music / captions / background removal" → `references/primitives.md`
-6b. **"Which ad wins?" / "test these angles" / "we post every day and want results"** → fetch <https://vidfarm.cc/experiment.md> and run the experimentation method (capacity → epochs/rounds → creative vs structured → `EXPERIMENTS_DIARY.md`). Do not improvise a testing plan; a round with two variables teaches nothing. To produce a bulk batch with gigworkers, pair it with <https://vidfarm.cc/crowdsourcing.md>.
+6b. **"Which ad wins?" / "test these angles" / "we post every day and want results"** → fetch <https://vidfarm.cc/experiments.md> and run the experimentation method (capacity → epochs/rounds → creative vs structured → `EXPERIMENTS_DIARY.md`). Do not improvise a testing plan; a round with two variables teaches nothing. To produce a bulk batch with gigworkers, pair it with <https://vidfarm.cc/crowdsourcing.md>.
 7. **"Update / upgrade vidfarm"** (or anything that smells like a stale install — a missing command, a 404 on a documented route, a version mismatch) → fetch <https://vidfarm.cc/update.md> and follow it. Update the skill pack and the devcli **together**; updating one alone is the usual cause of "the skill says to do X but it fails."
 
 ## Non-negotiables
@@ -138,7 +138,7 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 - **Structure before polish — the four charges, written before the timeline.** 🪝 **Hook**: the first line is a complete clause naming a *situation*, not a label; on screen at `start:0` (chunk 1 is read before any audio). 🔄 **Loop**: one open question by 0:10, stated on screen, **closing inside this video**, with an answer the viewer can't guess. 😍 **Payoff**: shown, not summarized, before the final beat. 🎣 **Bait**: one ask, final beat + post caption. Banned openers: throat-clearing, a logo, a title card, a fade from black. Full harness: `references/hooks-and-virality.md`; checkable form: `vidfarm harness show hooks`.
 - **Then cut ruthlessly — every second is precious.** First assembly is ~30–50% too long. **Deletion test** on every beat (delete it; if the video survives, it stays deleted); what's left must serve a charge. Cut intros, the wind-up before the claim, restatement, >0.35s silences, real-time process, establishing shots, and any tail after the last word — then **ripple the hole closed** or fluff becomes dead air. Not speed: keep the comedic beat, the payoff, and readable cue time. Length is an output. `vidfarm qa` flags `dead-air` / `dead-tail` / `slow-scene`.
 - **The first frame is the thumbnail.** Frame 0 is one frame of ~30 in the first second, but it's the poster every feed and share link freezes on — so it's seen by more people than the video is. Never open on black, an empty frame, or a fade-up: a real visual at `start:0`, the hook words already up, and no *entrance* transition on the first clip (junction transitions between later clips are fine). Check it with `vidfarm stills <dir> --at 0`.
-- **On devcli, `vidfarm qa <dir>` before every render.** Free, instant, local-only blocklist for the slop above + the first frame + the font regime. Feedback, not a gate (exits 0, never automatic). No REST/web equivalent.
+- **On devcli, `vidfarm qa <dir>` before every render.** Free, instant, local-only blocklist for the slop above + the first frame + the font regime. Feedback, not a gate (exits 0, never automatic). No REST/web equivalent. **It stops after 2 revisions of the same composition** — at the limit it withholds the finding list and tells you to ship or ask the human, because qa→fix→qa has no natural base case and some findings are deliberate style you will never "clear". Re-running qa without editing costs nothing; `--max-revisions <n>` (0 disables) and `--reset-revisions` are the escape hatches.
 - **Review the finished video as a WHOLE, and never by one frame.** Agents build scene by scene, so every scene passes alone while the video drifts as a sequence — shifting margins, three type sizes, a wandering accent colour, N identically-long beats, a jarring join, a dead band under top-anchored content. Tile ~12 stills into one contact sheet — one command, `vidfarm stills <dir> --sheet` — and **read it as an image**: balance, spacing, one type scale, one palette, deliberate pacing, clean joins — then fix the *system*, not the one odd scene. Compare frames from two different scenes (a frozen render passes duration, frame-count and audio-hash checks), verify audio by measurement (~12–15 dB speech-over-bed, peak <0 dBFS) rather than "sounds fine", and report what you measured separately from what you judged. Your own "verified, looks good" is the least reliable signal here — it was wrong on every video of a 32-video batch. Method: `references/reviewing-renders.md`.
 - **Ask about deduplication before you publish or bulk-produce.** "Is this going out more than once — several accounts, another platform, a re-post later? How many copies?" Ask *before* the render or the batch, not after: dedupe is a post-render ffmpeg pass, so answering early keeps it at **render once → dedupe N** instead of paying for a second render per slot. Then post each variant to a **different** account — two accounts posting the same variant defeats the point.
 - **Ask one-time vs bulk before you build.** Volume = **scripting mode**: a pinned base fork, a loop varying ONE thing, and a **`HARNESS.md`** — the director's own written standard, because a fifty-video loop has no human watching every frame. `vidfarm harness init short-form --out ./work/HARNESS.md` (bases: `short-form`, `hooks`, `ugc-testimonial`, `explainer`, `product-demo`), then `vidfarm qa ./work --harness <name|path>` — stackable, any user file valid, auto-discovered from the work dir. Its `checks:` are machine-settled; its `- [ ]` items come back for **you** to answer honestly.

package/crowdsourcing.md

@@ -50,7 +50,55 @@ https://www.youtube.com/watch?v=sR0C0V-WiRc
 Please run agentic clipper loops for a gigworker using these REST APIs:
 
 - vidfarm.cc/skill.md for creating videos for clients using cost saving mode. ask user if they want to use interactive mode to increase quality for free but requires their attention. if possible use stickers to create the videos. use any style prompts or custom instructions the gigworker has, as often they will specialize in specific video types
-- dollarplatoon.com/skill.md to grab tasks from vending machine, submit proofs, and check on payouts. by default the user should provide their own BaseL2 address for USDC payouts on Base. many gigworkers are Philippines based so they will use gcash. the gcash setup tutorial can be found here: https://officex.short.gy/solana-usdc-gcash and your DOLLARPLATOON_API_KEY can be found in https://dollarplatoon.com/gigworker/settings
+- dollarplatoon.com/skill.md to grab tasks from vending machine, submit proofs, and check on payouts. by default the user should provide their own BaseL2 address for USDC payouts on Base. many gigworkers are Philippines based so they will use gcash. the gcash setup tutorial can be found here: https://officex.short.gy/solana-usdc-gcash
+
+### 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.
+
+- `GIGDESK_API_KEY` (`gd_live_…`) talks to `https://gigdesk.cc/api`
+- `DOLLARPLATOON_API_KEY` talks to `https://dollarplatoon.com/api`
+
+send it as `Authorization: Bearer <key>` on every call.
+
+### "check available work" → `GET /work/available`
+
+when the gigworker says **"check available work"**, **"check the vending machines for tasks"**, **"any work today?"** or anything similar, the ai agent must call `GET /work/available`. do not poll each vending machine one by one. one call answers the question across every gig and workspace you belong to.
+
+```bash
+# all gigs / all workspaces at once
+curl -H "Authorization: Bearer $GIGDESK_API_KEY" \
+  "https://gigdesk.cc/api/work/available?only_with_work=true"
+
+# same answer from the dollarplatoon side
+curl -H "Authorization: Bearer $DOLLARPLATOON_API_KEY" \
+  "https://dollarplatoon.com/api/work/available?only_with_work=true"
+```
+
+gigdesk mirrors the dollarplatoon route and adds a `workspace_id` + `workspace_title` to each row. dollarplatoon stays the source of truth for tasks, proofs and payouts.
+
+scope the read when you only want part of your work:
+
+| Query param | Effect |
+|---|---|
+| `only_with_work=true` | keep only mailboxes that hold work |
+| `workspace_id=ws_…` | one workspace (one client desk) |
+| `tag=…&tag_match=exact` | filter by your own private mailbox tags. `tag_match` is `substring` (default), `prefix` or `exact`; commas mean OR |
+| `limit=` / `cursor=` | page size (max 100) and start cursor |
+
+gigdesk writes two private tags on every workspace mailbox: `gigdesk` and `gigdesk-ws-<workspace_id>`. so `?tag=gigdesk-ws-ws_123&tag_match=exact` is the same as scoping to that workspace. tags are private to you, and the gig owner never sees them.
+
+read each row like this:
+
+- `tasks_in_mailbox: true` — work is already delivered to you
+- `poll_in_gig: true` — unclaimed work sits in the shared queue, worth a poll
+- `poll_in_gig: false` — definitive, do not poll it
+
+then claim and submit on dollarplatoon: `POST /gigs/:id/queue/poll`, then `POST /gigs/:id/proofs`.
+
+**page to the end.** keep calling with `?cursor=<next_cursor>` until `next_cursor` is `null`. a filtered page can be empty while later pages still hold paid work.
+
+**if you are not sure which tags a gig uses, do not guess.** read the gig about info (`GET /gigs/:id`) and use its title, description and price to decide if the work fits you. tags are only a convenience filter that you set yourself.
 
 in order to join client projects, you need to get an invite link from them. those can be found by scrolling through these communities: