@officexapp/vidfarm-devcli 0.21.39 → 0.21.43

package/SKILL.md

@@ -7,8 +7,9 @@ description: Thin entry point for agentic video editing with Vidfarm. An AI agen
 
 **You are an AI agent that was pointed at `https://vidfarm.cc/SKILL.md` to get your human started with agentic video editing.** This page is deliberately thin. It tells you what Vidfarm is, how to get hands-on in the next two minutes, and exactly which deeper files to fetch. Read this, then pull the full director skill — don't improvise Vidfarm's workflows from this page alone.
 
-**Do these two things first, before anything else:**
+**Do these three things first, before anything else:**
 
+0. **Agree on a working folder.** Ask the user to keep **one folder for all their Vidfarm work**, named after their offer or brand (`./acme-skincare/`; if they have no preference, propose `~/vidfarm/<brand>/` and create it). Run every `vidfarm` command from it, or pass `--dir`. Everything lands there — the strategy documents (`OFFER.md`, `CONTEXT.md`, `ad-hooks.md`, `content-ideas.md`), `STORYBOARD.md`, `brand-assets/`, `raws/`, `renders/` — so a later session, in a new terminal weeks from now, reads the whole history back instead of asking the same questions again. If the folder already exists, **read `CONTEXT.md` and `OFFER.md` before you ask anything.**
 1. **Install the `vidfarm` devcli** — `npm i -g @officexapp/vidfarm-devcli`. It wraps every REST route, runs a free local editor + render loop, and is by far the smoothest way to drive Vidfarm.
 2. **Log in** — `vidfarm login <email>` (one-time email code), or if you already hold a key: `vidfarm login --api-key <key>` / set `VIDFARM_API_KEY` and run `vidfarm login`. This persists the credential so every later command and `vidfarm serve` just work.
 
@@ -106,6 +107,8 @@ Otherwise, pull it over the network and load only the reference you need:
 - **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.
+- **Experimental prompts (index):** `https://vidfarm.cc/experimental` — methods under live testing. They are **not** part of the router and nothing above depends on them: read one only when the user asks for experimental prompts, or names one. Current list:
+  - **Unique Product Explainer Videos** — `https://vidfarm.cc/experimental/unique-product-explainers.md` — N customer URLs → N product-introduction videos that do not look like each other. Differentiation as an input, frame-level review, measured verification.
 - **Skill pack index (what else is installable):** `https://vidfarm.cc/skill-pack/index.json`
 - **Platform architecture (how it all fits together):** `https://vidfarm.cc/skill/vidfarm-platform`
 
@@ -113,7 +116,7 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 
 ## Router — where to go from the user's ask
 
-1. "Help me figure out what to make" **or "give me a consultation"** → `references/onboarding.md`. A consultation *is* the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks. Run the primitives; don't improvise the strategy in chat.
+1. "Help me figure out what to make" **or "give me a consultation"** → `references/onboarding.md`. **Lead with content ideas, not the interview**, unless they said "consultation": ask for their offer in one line, run `vidfarm ideas --topic "<line>"`, and hand back 20+ titled videos saved as `content-ideas.md` — offline, free, keyless, about a minute. It is the easiest first win, and what they say about the list is better interview material than an interview. A consultation *is* the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks. Run the primitives; don't improvise the strategy in chat. **On devcli with no AI key or no credits, run it keyless: `vidfarm consult` prints the same prompt for YOU to answer, for $0** — never tell a keyless director the consultation is unavailable. Offer `vidfarm consult coldstart --short` (six fixed questions) to anyone who just wants a video today, tell them any question is skippable before you ask the first one, and keep every answer in `CONTEXT.md` in their working folder so the next session starts warm.
 2. "Find a template and start" → `references/core-workflows.md`
 3. "Change / re-theme this video" → `references/editor-workflows.md`
 4. "Find footage / use our assets" → `references/assets-and-sourcing.md`
@@ -138,7 +141,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: