@officexapp/vidfarm-devcli 0.21.55 → 0.21.57

package/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: vidfarm
+skill_version: 0.21.57
 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.
 ---
 
@@ -9,6 +10,65 @@ Vidfarm builds video from HTML. You fork a published template, edit it on a time
 
 This page is the router. It holds the setup, one worked example, the standards, and the file index. It does **not** hold the workflows — fetch those from the index at the bottom when a task needs them.
 
+## 0a. Version — check it once a day, and it is skippable
+
+**The `skill_version` in the frontmatter above is this document's version** — machine-readable, and the number to compare against. Vidfarm ships as **two moving parts on one semver**: the `vidfarm` agent skill and the `@officexapp/vidfarm-devcli`. Updating one without the other is the single most common cause of *"that command doesn't exist"* and *"the skill says to do X but it fails"* — the skill documents routes and flags the installed CLI may not have yet.
+
+**Check at the top of a session, at most once every 24 hours, in one command:**
+
+```bash
+vidfarm update-check --if-stale --quiet
+```
+
+- `--if-stale` makes it a **no-op** unless the last check is older than 24h (`--hours N` to change it), so an agent can run it every session for one network round-trip a day.
+- `--quiet` prints **nothing at all when you are current**. It costs no context to leave in.
+- `--json` gives `{devcli, skill, update_available, offline, hours_since_last_check}`.
+- Offline, or the registry unreachable? It says so and **does not** claim you are out of date. Everything local keeps working.
+
+**If it reports an update, tell the user and offer it — do not update silently, and do not nag.**
+
+```bash
+npm i -g @officexapp/vidfarm-devcli@latest && vidfarm skills add vidfarm   # BOTH halves, together
+vidfarm update-check --skip      # "not now" — this version stays quiet, a NEWER one asks again
+vidfarm update-check --unskip    # undo that
+```
+
+**Honour a skip.** A prompt the user cannot dismiss gets ignored, and then the real one is ignored too. `--skip` is recorded against the version number, so you are not silencing the next release.
+
+`vidfarm --version` prints both halves. Read the breaking-change notes at <https://vidfarm.cc/update.md> **before** assuming an old workflow still applies — especially on a major bump. Any 404 on a route this page documents means you are out of date; check there first rather than working around it.
+
+## 0b. Two questions about YOU, before anything else
+
+Answer both once, at the top of the session, and write them into `CONTEXT.md`. They change which road you take through this document, so getting them wrong costs a whole video.
+
+### Am I a strong model or a weak one?
+
+| Tier | You are | Then |
+|---|---|---|
+| **strong** | Claude Opus / Sonnet (4.5+), GPT-5 class, Gemini Pro (3+ thinking), Fable | Use this page as written. The `vidfarm.cc/experimental/*` format harnesses are build instructions for you. |
+| **weak** | **Gemini Flash / Flash-Lite, DeepSeek, Kimi, GLM, MiniMax, Grok, Qwen, Llama**, any "-mini" / "-lite" / "-turbo" / distilled tier | **Go to `https://vidfarm.cc/flash-harness.md` and follow it.** Come back here for the standards in §6. |
+| **unsure** | you cannot name your own model, or you are a router that may swap tiers mid-task | **Treat yourself as weak.** |
+
+**Why the split is real, and not a slight.** The `experimental/*` harnesses ask an agent to author a format from its written description — 300 lines of prose to a rendered composition in one held-in-mind pass. That works on frontier agents and reliably fails below them. It is a synthesis problem, not a knowledge problem, so more instructions do not fix it. The flash harness removes the synthesis instead: **fork an already-decomposed template off `/discover` and transplant the client's story into it.** Somebody already paid a frontier model to take that video apart — take the parts. Output quality goes UP, not down, and overfitting to one template is the correct outcome there.
+
+**Unsure resolves to weak, deliberately.** A strong model following the flash harness loses a little freedom and still ships a good video. A weak model skipping it ships something the client rejects.
+
+### Does my own subscription already include media generation?
+
+| Host agent | Image | Voice / TTS | Transcribe / STT |
+|---|---|---|---|
+| **Google Antigravity** (Gemini) | **Yes** | **Yes** | **Yes** |
+| **Gemini CLI** | **Yes** | **Yes** | **Yes** |
+| **OpenAI Codex / ChatGPT** | **Yes** | **Yes** | **Yes** |
+| **Claude Code** | No — Anthropic ships no image, voice or transcription model | No | No |
+| OpenCode / Cursor / anything else | depends on the configured model — read your own tool list | | |
+
+`vidfarm agent-image --check` prints this plus a guess at the host from its env markers. **The guess is a hint; your own tool list is the authority.**
+
+> **Generation already inside a flat subscription is FREE, so it is allowed in cost mode `minimize`, with no `--yes` and no permission ask.** Vidfarm bills $0 — no primitive, no job, no wallet debit — and the provider bills $0 extra, because the capability is inside the plan the human already pays for. **So "$0 cost saving mode" on Antigravity may still generate its own images and its own voiceover, and you report it honestly as $0.**
+
+**Default to using the subscription.** Prefer it over a free local engine that takes twenty minutes, and long before anything billed. The free rungs (stock, IconScout, the client's own site) still come first on quality grounds — *free* does not mean *first*. Name in your report which assets came from your own subscription; that sentence is the proof `minimize` really cost $0. Full page: `references/agent-included-imagegen.md`.
+
 ## 1. Setup
 
 ```bash
@@ -19,6 +79,7 @@ vidfarm doctor                        # verifies vidfarm + ffmpeg + hyperframes
 vidfarm skills add vidfarm            # install the full director skill on disk — do this
 vidfarm serve                         # free local editor + render loop at localhost:3000
 vidfarm browser setup                 # optional: drive the user's own Chrome — FREE footage sourcing
+vidfarm update-check --if-stale --quiet   # §0a — silent when current, no-op if checked in the last 24h
 ```
 
 **Image generation you already pay for is free — check before you spend or go without.** If the agent driving this terminal includes image generation in its own subscription (Google Antigravity / Gemini CLI, OpenAI Codex / ChatGPT — **Claude Code does not**, Anthropic ships no image model), generating a graphic bills Vidfarm $0 and the provider $0 extra. That makes it legal in cost mode `minimize`, with no `--yes`. `vidfarm agent-image --check` answers "do I have it here?"; `vidfarm agent-image "<subject>" --items "a,b,c"` prints the prompt, the key-plate rules and the cut + import commands. Free stock and IconScout still come first. Full page: `references/agent-included-imagegen.md`.
@@ -60,12 +121,14 @@ Every visual on the timeline comes from one of three sources. Try them in this o
 
 A capable agent can replicate a template entirely on brush 1 and 2, on the free tier, with no wallet.
 
+**There is a fourth source, and for a weak model it is the FIRST one: a template somebody already decomposed.** `/discover` holds thousands of viral videos that have been taken apart into their scene-by-scene DNA — hook, retention, payoff, cut rhythm, typography, per-beat paintbrush assignments — and forking one is free. That decomposition costs $1+ in AI spend to reproduce yourself, so always check for an existing one before paying to re-run it. `vidfarm discover --query "<the client's problem, in their words>" --json`; a row carrying `summary`, `keywords` and `promotions` is decomposed. **Weak models: this is not an optimisation, it is the method** — see `vidfarm.cc/flash-harness.md`.
+
 ## 3. Worked example — one video, end to end
 
 ```bash
 vidfarm ideas --topic "cold email tool for agencies"     # free, offline → content-ideas.md
 vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"   # plan first — free to redo
-vidfarm templates search "ugc testimonial"               # find a published template
+vidfarm discover --query "ugc testimonial" --json        # find a published template
 vidfarm fork <templateId>                                # → forkId
 vidfarm pull <forkId> --dir ./work                       # composition.html + .harness/ to disk
 vidfarm public-raws --category greenscreen --limit 20    # source footage, $0
@@ -86,6 +149,7 @@ vidfarm publish <forkId>                                 # push edits back to th
 
 | The user asks for | Do | Read |
 |---|---|---|
+| **Anything at all, and §0b said you are a weak model** | do not author a format from prose. Fork a **decomposed** template off `/discover`, derive its DNA, procure every raw, transplant the client's story into it | `vidfarm.cc/flash-harness.md` |
 | "Help me figure out what to make" | `vidfarm ideas --grid --topic "<offer>" --count 30` first — the list beats an interview | `references/onboarding.md` |
 | "Give me a consultation" | the `brainstorm/*` chain: cold-start → awareness stages → angles → hooks. No AI key: `vidfarm consult` prints the prompt for **you** to answer, $0 | `references/onboarding.md` |
 | "Find a template and start" | `vidfarm templates search` → `fork` → `pull` | `references/core-workflows.md`, `recipes/find-and-fork-template.md` |
@@ -98,6 +162,7 @@ vidfarm publish <forkId>                                 # push edits back to th
 | "A UGC ad for my app" / "someone reacting, then the app" / a client's app demo you have to make watchable | three streams cut against each other: `ugc-reaction` raws (ONE actor, via `actor_<uuid>`), a Display Greenscreen device carrying their real demo on its screen, and the demo. Ships a voiceover-only cut to publish + a voiceover+music cut to review | `vidfarm.cc/experimental/ugc-reaction-greenscreen.md` |
 | "A tips slideshow / carousel" / "5 tips for X" / a listicle post | N still slides at exactly 3.0s, die-cut cutouts on a page or a photo, a literal "Tips for…" cover, ONE slide shilled from the middle. **The slides are the deliverable; the MP4 is the preview.** $0–$0.15 | `vidfarm.cc/experimental/sticker-slideshow-tips.md` |
 | "A confession / truth bomb over a POV or ambient scene" / "just text on a video" / a text-story post | ONE unbroken take + ONE static block of unplated type. Nothing animates, nothing is cut. `duration = words / 8` (min 8s) so one play reaches the HALFWAY mark and they loop to finish. Cast the scene DARK so the type needs no plate. $0 | `vidfarm.cc/experimental/wall-text-pov-ugc.md` |
+| "A fake text conversation" / "a chat story" / "a screenshot thread" / funny-or-dramatic DMs | N still chat screenshots at exactly 3.0s, pure type on pure black, **no phone chrome at all**. Two voices that stay separable with the colour removed, `>>>` cards for time jumps, the offer named ONCE mid-thread as a plot fact, and NO ending — it stops mid-action. **The slides are the deliverable; the MP4 is the preview.** $0 | `vidfarm.cc/experimental/engaging-chat-convo.md` |
 | "An animated explainer / a little story that animates" / "like those Vox map animations" / "cutout paper animation" | ONE full-bleed parchment stage, no cuts, a cast of die-cut paper stickers moved by ONE paused GSAP timeline. Narrated, subtitles stay small and kinetic in colour only, the offer named once as a wordmark on the LAST beat. Buy SHEETS, not stickers. Desktop-only (the web editor strips scripts). ~$0.25 hybrid, $0 minimize | `vidfarm.cc/experimental/animated-sticker-story.md` |
 | "Make N videos for N customers / clients" / a batch that must not read as N runs of one template | differentiation is an INPUT, not a hope: assign each variant its own frame before you build any of them, then review frame by frame. $0 | `vidfarm.cc/experimental/unique-product-explainers.md` |
 | "Download this video from `<url>`" | `vidfarm download-video <url>` (paid). Free plan gets a 402 — `vidfarm browse page "<url>"` and save it from their Chrome yourself, else have them download it, then `vidfarm put-file`. Never answer "I can't." | `references/browser-harness.md` |
@@ -119,7 +184,7 @@ Ask both once, early, then persist them. They are independent axes.
 
 | Mode | Per video | Method |
 |---|---|---|
-| `minimize` | $0 | free local compute + free stock media only |
+| `minimize` | $0 | free local compute + free stock media + **any generation your own subscription already includes** (§0b) |
 | `hybrid` *(default)* | ~$0.01–$1 | free where free, pay AI only where it clearly wins |
 | `rich-ai` | $1+ | generate reusable greenscreen assets, key them, animate in HTML, save to the library for later reuse |
 | `pure-videogen` | $5+ | script → storyboard stills → scene-by-scene generation. No reuse |
@@ -131,7 +196,7 @@ AI charges go to the user's own provider keys (`vidfarm add-provider-key`), not
 - `interactive` — at checkpoints you hand over a copy-paste brief and they hand a file back: an image prompt they run in a free web generator, or a keyword list for footage. Mint them with `vidfarm handoff image` / `vidfarm handoff raws`. Costs minutes, usually beats what an API budget buys.
 - `autonomous` — you finish end to end with zero steps from them.
 
-Two consequences worth stating out loud: `minimize + interactive` still gets custom art, for $0. `minimize + autonomous` gets none. Voice samples (`vidfarm voices --sample`, `--free --sample`) are free on both tiers — offer them either way.
+Two consequences worth stating out loud: `minimize + interactive` still gets custom art, for $0. `minimize + autonomous` gets none — **unless §0b said your own subscription includes generation, in which case `minimize + autonomous` gets custom art AND a custom voiceover, still at $0.** That is the normal case on Antigravity, which is what most gigworkers run. Voice samples (`vidfarm voices --sample`, `--free --sample`) are free on both tiers — offer them either way.
 
 ## 5b. Production has phases — plan, collect, build
 
@@ -157,6 +222,7 @@ The standards themselves are not optional. `vidfarm qa <dir>` is — it is a fre
 - **The first frame is the thumbnail.** A real visual and the hook words at `start:0`. No fade-up, no entrance transition on the first clip. Check with `vidfarm stills <dir> --at 0`.
 - **Cut ruthlessly.** First assembly is 30–50% too long. Delete every beat that the video survives without, then ripple the hole closed. Length is an output, not a target.
 - **Review the whole video, never one frame.** Tile ~12 stills with `vidfarm stills <dir> --sheet` and read it as an image — one type scale, one palette, deliberate pacing, clean joins. Verify audio by measurement (~12–15 dB speech-over-bed, peak <0 dBFS). Report what you measured separately from what you judged. Your own "looks good" is the least reliable signal here.
+- **Prove the render MOVES before you call it done: `vidfarm motion-check <file.mp4>`.** A frozen render has the right duration, frame count, file size and audio, and a perfect frame 0 — every other check you would run passes. `vidfarm render --target local` runs this itself and fails on a still output (`--allow-static` when that is the point).
 - **Use the real trending song.** The render is a review artifact; the user re-attaches the same track from the platform's in-app music library at post time, where it is licensed. Pull it with `vidfarm download-audio <post-url>`, keep it on its own `<audio>` layer at its own `data-volume`, and name the track in your report. Exception: a paid ad placement is not covered — say so once and offer `vidfarm music "<same vibe, same BPM>"`.
 - **Ask about deduplication before the render, not after.** "Is this going out more than once?" Answering early keeps it at render once → dedupe N.
 
@@ -167,6 +233,7 @@ The standards themselves are not optional. `vidfarm qa <dir>` is — it is a fre
 - Render only through `POST /api/v1/compositions/:forkId/render`. Never call the renderer directly.
 - Submissions are **not** idempotent. Every render and primitive POST charges again — check status before retrying.
 - In the web editor, CSS/declarative motion only; JS animation adapters are stripped on save. Locally via `vidfarm serve`, the full adapters work.
+- **`window.__player`, `window.__hf`, `window.__playerReady`, `window.__renderReady` and `window.__hyperframes` belong to the engine — never assign them.** Assigning one destroys frame capture: the render exits 0 and writes a correct-length MP4 in which nothing moves. Motion has one mechanism — register a paused timeline and let the engine seek it: `window.__timelines = window.__timelines || {}; window.__timelines["<data-composition-id>"] = gsap.timeline({ paused: true });` (that key must equal the root's `data-composition-id` exactly). For per-frame drawing, hang your draw call off a paused driver timeline's `onUpdate` instead of inventing a seek API. `vidfarm lint` and `vidfarm qa` both error on this, and a local render refuses to start.
 - Treat `forkId` as an unguessable bearer token. Never put provider secrets in composition HTML or JSON.
 
 ## 8. Deeper knowledge — fetch on demand
@@ -197,8 +264,13 @@ Otherwise fetch `https://vidfarm.cc/skill-pack/vidfarm/files/<path>`. Load one f
 | `references/rest-api.md` | direct HTTP integration only |
 | `recipes/*.md` | `find-and-fork-template` · `retheme-template` · `local-edit-render-approve` · `onboard-a-new-director` · `bulk-scripting-with-a-harness` · `cutout-graphics-for-explainers` |
 | `harnesses/README.md` | anything harness-shaped — start here. Bases: `short-form` · `hooks` · `ugc-testimonial` · `explainer` · `product-demo` · `product-explainer` |
-| `vidfarm harness list` | both shelves: the bases above, **plus every format harness from `vidfarm.cc/experimental`** — `meme-recaption` · `wall-text-pov-ugc` · `ugc-reaction-greenscreen` · `sticker-slideshow-tips` · `animated-sticker-story` · `google-news-to-video` · `unique-product-explainers`. They ship in the package, so `vidfarm harness show <name>` reads one in full with no fetch, and `vidfarm qa ./work --harness <name>` grades against it. The name is the URL slug |
+| `vidfarm.cc/flash-harness.md` | **you are a weak model (§0a), or you are unsure.** The process harness that sits above every format harness: match a decomposed `/discover` template → decompose if nobody has → derive the viral + visual DNA → procure every raw in one pass → transplant. Also at `vidfarm harness show flash-harness`, offline |
+| `vidfarm harness list` | both shelves: the bases above, **plus every format harness from `vidfarm.cc/experimental`** — `flash-harness` (the weak-model process, not a format) · `meme-recaption` · `wall-text-pov-ugc` · `ugc-reaction-greenscreen` · `sticker-slideshow-tips` · `engaging-chat-convo` · `animated-sticker-story` · `google-news-to-video` · `unique-product-explainers`. They ship in the package, so `vidfarm harness show <name>` reads one in full with no fetch, and `vidfarm qa ./work --harness <name>` grades against it. The name is the URL slug |
 
-Also served at `vidfarm.cc`: `/experiments.md` (ad testing), `/marketplace.md` (the marketplace manual — routes you to one of the two side harnesses below), `/marketplace-buyer.md` (**buyer side**: commission videos from the crowd), `/agentic-clipper.md` (**worker side**: "Agentic Clipper" mode — one orchestrator on a long-horizon earning mission, one subagent per task), `/update.md` (upgrade runbook), `/experimental` (format harnesses under live testing — the index a clipper routes tasks against), `/skill/vidfarm-platform` (architecture), `/skill/hyperframes` (composition-authoring craft — route broad "make me a video" asks here first).
+Also served at `vidfarm.cc`: `/flash-harness.md` (**the weak-model process harness — read it first if §0a called you weak or unsure**), `/experiments.md` (ad testing), `/marketplace.md` (the marketplace manual — routes you to one of the two side harnesses below), `/marketplace-buyer.md` (**buyer side**: commission videos from the crowd), `/agentic-clipper.md` (**worker side**: "Agentic Clipper" mode — one orchestrator on a long-horizon earning mission, one subagent per task), `/update.md` (upgrade runbook), `/experimental` (format harnesses under live testing — the index a clipper routes tasks against), `/skill/vidfarm-platform` (architecture), `/skill/hyperframes` (composition-authoring craft — route broad "make me a video" asks here first).
 
 **The two marketplace harnesses never mix.** A buyer's agent must never load the clipper loop and a clipper must never load the buyer loop. If the user's side is unclear, ask: *"Do you want videos made for you, or do you want to get paid to make videos for other people?"*
+
+**But an ask about EARNING has already answered it — do not ask.** *"help me earn on vidfarm marketplace"*, *"help me make money on vidfarm"*, *"find me video gigs"*, *"any work today?"*, *"check the vending machines"*, *"run in agentic clipper mode"* all mean the **clipper** side: load `/agentic-clipper.md`, then run the four moves — read the feed's recent notifications for who is asking right now, pull the `GIG_…` id out of each notification's join link and check `available_funds` before committing, join the funded ones with a Base L2 `wallet_address` in the same call, then `GET /work/available` and poll a queue for a task. The copy-paste version is in `/marketplace.md` → *"help me earn on vidfarm" — the whole first session*.
+
+**Then ask the gigworker one more question: the RUN MODE.** It decides which stages of every task stop for them — `full-interactive` (shortlist · plan · raws · cut), `quick-interactive` (shortlist · cut), `auto-batch` (cut only — build the batch unattended, review it in one sitting), `auto-submit` (nothing; opt-in, in their own words). The middle two are the common ones. `vidfarm clipper-run mode` explains all four and saves the answer, `vidfarm clipper-run next` says what to do right now, and `vidfarm clipper-run gate <task>` exits non-zero while a human gate is open — so `gate && gigs submit …` cannot send an unreviewed cut. Full section: `/marketplace.md` → *The four run modes*.

package/clipper.md

@@ -80,6 +80,22 @@ Ask these, in one message, with the defaults stated:
 5. **How often — default every 30 minutes** while their computer is on. Respect the gig's rate
    limit above anything they ask for.
 6. **Where to keep the project — default `~/clipper/<gig-id>/`.**
+7. **Auto-submit — default OFF, and say why.** You build the video, then they watch it and approve
+   it before it goes to the client. Explain the reason in one line: rejections score against their
+   wallet and clients read that as a trust score on their public profile, so one bad submit lowers
+   future earnings. Turn it on only if they ask for it in their own words, and record those words.
+8. **Their hardware — measure it, don't ask.** Read cores, RAM and free disk
+   (`sysctl -n hw.ncpu hw.memsize` on macOS, `nproc` + `free -g` on Linux,
+   `Get-CimInstance Win32_ComputerSystem` on Windows), then time the first render. **Capable**
+   (≥ 8 GB RAM, ≥ 4 cores) uses the free local engines: `vidfarm tts --engine local` (Kokoro),
+   `vidfarm stt --engine whisper`, local keying. **Weak** hardware never starts those — they do not
+   fail, they just take twenty minutes and lose the deadline. There, ask the AI agent subscription
+   they already pay for to make the voice line, the audio or the image, and bring the file in with
+   `vidfarm put-file`. Spend stays $0 on either tier. Write the tier into `config.json`.
+9. **Which AI agent runs the loop — recommend Google Antigravity CLI on a budget**, and **OpenAI
+   Codex** if they can afford the more expensive subscription. Either runs this whole file. Do not
+   make a subscription the price of entry — start on Antigravity, get the first proof paid, and let
+   them upgrade out of earnings.
 
 Write their answers into `config.json` (Phase 3) so the loop is reproducible and they can edit it
 later without you.
@@ -334,10 +350,23 @@ vidfarm put-file ./sheet.png
 vidfarm mask ./sheet.png --crop x,y,w,h --flat "#00FF00" --out prop-a.png   # once per element
 ```
 
-**Watch the finished video before you submit it.** Check `vidfarm stills` frames or open the MP4.
-Ask yourself whether it actually satisfies `terms`. If it doesn't, fix it or decline the task —
-a rejected proof carries a reputation penalty (`low_quality` 1x, `incomplete` 2x, `fake_proof` 5x)
-and those follow their wallet across every gig on the network.
+**The gigworker watches the finished video and approves it before you submit. Auto-submit is OFF by
+default.** Show them the file — `vidfarm serve` plays it, `vidfarm stills` gives frames — say what
+you want checked (brief satisfied, hook alive in 3 seconds, captions readable and in the safe zone,
+audio clean, brand right), and **wait**. No answer is not a yes. If they say fix it, fix it and come
+back. If they say drop it, do not submit.
+
+**This is a money rail, not politeness.** A rejected proof carries a reputation penalty
+(`low_quality` 1x, `incomplete` 2x, `fake_proof` 5x), it follows their wallet across every gig on
+the network, and **clients read it as a trust score on their public profile** before choosing whose
+pitch to take. One weak video lowers every future payday; a run of approved ones raises the score
+and wins better-funded machines at higher prices. Holding a cut back costs one task. Submitting it
+costs earnings they will never see arrive.
+
+**Only submit unattended when the gigworker explicitly asks for it** — "auto-submit", "you don't
+need to check with me". Write the exact words and the date into `config.json`, keep the permission
+as narrow as they gave it (one machine is not all machines), and turn it back off after any
+rejection. Never enable it yourself to hit a deadline or clear a queue.
 
 ---
 
@@ -407,6 +436,9 @@ what they earned (or are owed, for off-chain), and what it cost — AI spend sho
 
 These exist because the loop touches real customers, real reputation, and real money.
 
+- **Never submit a video the gigworker hasn't approved**, unless they explicitly asked for
+  auto-submit. Build, QA and queue unattended all you like; the last step waits for a human.
+  Rejections are permanent, wallet-anchored, and visible to clients as a public trust score.
 - **Never fake a proof.** Every submitted URL must point at a video you actually rendered for that
   task. `fake_proof` is a 5x reputation penalty and it is permanent and wallet-anchored.
 - **Never promise earnings.** Pay is per approved proof and demand-driven — quiet days pay nothing.

package/dist/src/cli.js

@@ -868,6 +868,10 @@ Fine timeline control (trackpad-level verbs on a pulled/served composition — l
                             --target cloud: billed Lambda render (~$0.01-$0.10)
                             → POST .../compositions/:forkId/render (--wait to
                             poll; --dir pushes composition.html + .json first)
+                            A local render REFUSES compositions that assign the
+                            engine-owned globals (window.__player / window.__hf)
+                            and FAILS if the finished MP4 never moves — pass
+                            --allow-static for a deliberately still card
   render-status <forkId> <renderId>   Poll one render job               → GET  .../compositions/:forkId/renders/:renderId
   template run <template_id> <operation_name>
                             Run one template operation via REST          → POST /api/v1/templates/:templateId/operations/:operationName
@@ -934,6 +938,7 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
                                       meme-recaption, wall-text-pov-ugc,
                                       ugc-reaction-greenscreen,
                                       sticker-slideshow-tips,
+                                      engaging-chat-convo,
                                       animated-sticker-story,
                                       google-news-to-video,
                                       unique-product-explainers
@@ -961,6 +966,13 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
                               sheet shows it
     --sheet-out <file>        Sheet path (default <out>/contact-sheet.png)
     --sheet-width <px>        Per-tile width in the sheet (default 320)
+  motion-check <video.mp4>  DOES IT MOVE? Proves a finished video is not    (local ffmpeg)
+                            a still image. A frozen render has the right
+                            duration, frame count, audio and frame 0, so
+                            every other check you would run passes. Exits 1
+                            when nothing in the video ever changes. Runs
+                            automatically after vidfarm render --target local
+                            [--json] [--fps <n>]
   doctor                    Health-check the local toolchain: node,       (local)
                             ffmpeg, hyperframes engines, Chrome, API key
                             (whoami), provider keys, agent CLI, poisoned
@@ -969,6 +981,20 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
     --kill-orphans           Reap orphaned local serve/preview servers
                             (running from a deleted package path) so their
                             squatted ports are reclaimed
+  --version (-v)            This devcli's version + the installed skill's   (local)
+  update-check              IS THIS INSTALL CURRENT? The skill and the      (npm registry + vidfarm.cc)
+                            devcli are ONE semver and must move together —
+                            updating one alone is the usual cause of "that
+                            command doesn't exist". Agents: run the --if-stale
+                            form at the top of a session; it is a no-op unless
+                            the last check is over 24h old, and --quiet prints
+                            NOTHING when you are already current.
+    --if-stale [--hours 24]  Only actually check if the last one is older
+    --quiet                  One line, silent when current
+    --skip / --unskip        Record "not now" for this version / undo it
+    --json                   {devcli, skill, update_available, offline, …}
+                            Offline is reported as offline, never as outdated.
+                            Breaking-change notes: https://vidfarm.cc/update.md
   skills <list|add <names…>|update>   Install/refresh agent skills into   → GET /skill-pack/* (or the
                             <root>/.agents/skills/<name> + a relative      copies bundled in this repo)
                             .claude/skills symlink; skills-lock.json is
@@ -1168,10 +1194,35 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
     (alias: dir · save-url|from-url|import-url — CLI twin of the "Save to Files" picker)
   gigs <sub>                Your vending machines, BOTH sides (client + gigworker)
     machines · tasks · add-task · proofs · approve · reject · ring-bell      (client, paid)
-    work · feed · join-feed · join · claim · submit · mine                   (gigworker, free — bring DOLLARPLATOON_API_KEY)
-    e.g. vidfarm gigs add-task --task "60s explainer for acme.com" --price 0.50 --upload-link <share url>
+    earn · feed · check · join · work · claim · submit · proof · earnings    (gigworker, free — bring DOLLARPLATOON_API_KEY)
+      upload · mine · join-feed
+    "HELP ME EARN ON VIDFARM" IS ONE COMMAND: vidfarm gigs earn. It joins the
+    feed, reads who is asking for videos right now, checks every one of those
+    machines for MONEY, and ranks them best-payer-first with the join command.
+    'gigs check <gig|join-url>' is the funds check on its own — run it BEFORE you
+    spend an hour, because approval does not create money. 'gigs submit
+    --clean-master <file>' seals the unwatermarked cut in the proof's private
+    note, which the buyer cannot open until a rollup has actually paid you.
+    e.g. vidfarm gigs earn
+         vidfarm gigs add-task --task "60s explainer for acme.com" --price 0.50 --upload-link <share url>
          vidfarm gigs proofs --status pending   ·   vidfarm gigs approve PRF_01H…
-    (see: vidfarm gigs help)
+    (see: vidfarm gigs help · the loop: vidfarm.cc/agentic-clipper.md)
+  clipper-run <sub>         HOW the clipper loop runs, and WHERE each task is up to
+    mode · init · start · shortlist · pick · plan · raws · cut · gate · submitted
+    approve · changes · drop        (the gigworker's answers)
+    next · status · review          (where am I / what is waiting on the human)
+    Four run modes, differing only in which stages STOP for the gigworker:
+      full-interactive   shortlist · plan · raws · cut   (best quality on a weak model)
+      quick-interactive  shortlist · cut                 (approve ONE template, then watch the cut)
+      auto-batch         cut                             (build everything, submit nothing until reviewed)
+      auto-submit        nothing                         (unattended; opt-in, in the gigworker's own words)
+    The stage lives in files under ./CLIPPER, not in the context — that is what
+    lets a weak model run a long task without forgetting where it was. 'gate'
+    exits non-zero while a human gate is open, so a loop written as
+    'clipper-run gate <task> && gigs submit …' cannot send an unreviewed cut.
+    e.g. vidfarm clipper-run mode quick-interactive
+         vidfarm clipper-run next
+    (see: vidfarm clipper-run help)
   shared <sub> <link>       USE a link someone shared with you — NO account, NO API key
     info · ls --tree · search · grab · note · mkdir · put · get
     grab is the one to reach for: it finds footage by MEANING and downloads it in one step.
@@ -1311,6 +1362,19 @@ async function main() {
         process.stdout.write(HELP);
         return;
     }
+    // `vidfarm --version` is the first line of the update runbook and of every
+    // "what are you running?" support exchange, and it used to error out with
+    // "Unknown option before command". Handled before dispatch so no subcommand
+    // can shadow it.
+    if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
+        const { installedDevcliVersion, installedSkillPath, readSkillVersion } = await import("./devcli/update-check.js");
+        const skillPath = installedSkillPath();
+        const skillVersion = skillPath ? readSkillVersion(readFileSync(skillPath, "utf8")) : null;
+        console.log(installedDevcliVersion() ?? "unknown");
+        console.log(`skill ${skillVersion ?? "not installed"}${skillPath ? ` (${skillPath})` : ""}`);
+        console.log("check for updates: vidfarm update-check");
+        return;
+    }
     const command = argv[0];
     // Opt-out crash telemetry (also covers the long-lived `serve` runtime, whose
     // in-process job/render captures share this client). Guarded + no-op by default.
@@ -1630,6 +1694,16 @@ async function main() {
             await runGigsCommand(rest);
             return;
         }
+        // The RUN MODE of an agentic clipper loop — how much of the gigworker's
+        // attention each task costs — plus the per-task stage that survives a
+        // context reset. Local files only; no key, no network.
+        case "clipper-run":
+        case "clipper-mode":
+        case "run-mode": {
+            const { runClipperRunCommand } = await import("./devcli/clipper-run.js");
+            await runClipperRunCommand(rest);
+            return;
+        }
         case "get-file":
             await runGetFileCommand(rest);
             return;
@@ -1755,6 +1829,13 @@ async function main() {
         case "stills":
             await runStillsCommand(rest);
             return;
+        // "does this finished video actually move?" — the check that catches a
+        // frozen render, which passes every other verification.
+        case "motion-check":
+        case "motioncheck":
+        case "frozen-check":
+            await runMotionCheckCommand(rest);
+            return;
         case "doctor":
             await runDoctorCommand(rest);
             return;
@@ -1770,6 +1851,13 @@ async function main() {
         case "hf":
             await runHyperframesPassthroughCommand(rest);
             return;
+        case "update-check":
+        case "check-update":
+        case "outdated": {
+            const { runUpdateCheckCommand } = await import("./devcli/update-check.js");
+            await runUpdateCheckCommand(rest);
+            return;
+        }
         default:
             if (!command.startsWith("-")) {
                 // Positional template id → default to booting the local editor.
@@ -4119,6 +4207,10 @@ async function runRenderCommand(argv) {
             out: { type: "string" },
             quality: { type: "string" },
             "keep-project": { type: "boolean", default: false },
+            // A deliberately static render (a title card, a still loop) is a real
+            // output — this is how you say so. Everything else that never moves is a
+            // bug, so the default is to fail loudly.
+            "allow-static": { type: "boolean", default: false },
             wait: { type: "boolean", default: false }
         }
     });
@@ -4177,8 +4269,20 @@ async function runRenderCommand(argv) {
             keepProjectDir: Boolean(parsed.values["keep-project"])
         });
         const prepCuts = result.prepNotes.filter((note) => note.action !== "skipped");
+        // A frozen render is a FAILED render wearing a successful render's exit
+        // code. Treat it as a failure unless the director said the video is static
+        // on purpose.
+        const frozen = Boolean(result.motion?.frozen) && !parsed.values["allow-static"];
         if (ctx.json) {
-            printJson({ ok: true, render_target: "local", output_path: result.outputPath, duration_ms: result.durationMs, media_prep: result.prepNotes });
+            printJson({
+                ok: !frozen,
+                render_target: "local",
+                output_path: result.outputPath,
+                duration_ms: result.durationMs,
+                media_prep: result.prepNotes,
+                motion: result.motion ?? null,
+                ...(frozen ? { error: "frozen_render", message: result.motion?.reason } : {})
+            });
         }
         else {
             if (prepCuts.length > 0) {
@@ -4186,10 +4290,22 @@ async function runRenderCommand(argv) {
             }
             console.log(`${GREEN}Rendered locally in ${(result.durationMs / 1000).toFixed(1)}s → ${result.outputPath}${RESET}`);
             console.log(`${DIM}$0.00 — local Vidfarm render, no cloud charge.${RESET}`);
+            if (frozen && result.motion) {
+                const { formatFrozenRenderFailure } = await import("./lib/frozen-render.js");
+                console.log(formatFrozenRenderFailure(result.motion, { red: RED, bold: BOLD, dim: DIM, reset: RESET }));
+            }
+            else if (result.motion?.skipped) {
+                console.log(`${DIM}Motion not verified (${result.motion.reason}) — check it by eye before publishing.${RESET}`);
+            }
+            else if (result.motion) {
+                console.log(`${DIM}Motion verified: ${result.motion.moving_pairs}/${result.motion.compared_pairs} sampled frame pairs differ — the video moves.${RESET}`);
+            }
             // Nudge, not a gate: QA never runs automatically, but every production
             // should get a look before it's published.
             console.log(`${DIM}Recommended: ${RESET}vidfarm qa ${sourceDir ?? "<dir>"}${DIM} — social-native QA (HTML slop + font regime). Feedback only, free, instant.${RESET}`);
         }
+        if (frozen)
+            process.exitCode = 1;
         return;
     }
     if (sourceDir) {
@@ -12715,6 +12831,54 @@ async function runStillsCommand(argv) {
         console.log(`${DIM}READ the contact sheet as ONE image — that is how you catch what per-scene checks miss: uneven margins, a wandering type scale or accent colour, N identically-long beats, a jarring join, dead space under top-anchored content. Fix drift by defining the system, not by patching the one odd scene.${RESET}`);
     }
 }
+// `vidfarm motion-check <video.mp4>` — prove a finished video actually MOVES.
+//
+// The one check that catches a whole class of silent render failure: a frozen
+// render has the right duration, the right frame count, clean audio, and a
+// perfect frame 0, so every other verification an agent would think to run
+// passes. This one samples the video and compares consecutive frames. Runs on
+// any MP4, not just a vidfarm render — including the output of a watermark or
+// overlay pass, which is where the other known cause lives.
+async function runMotionCheckCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean", default: false },
+            fps: { type: "string" }
+        }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("motion-check requires a video path: `vidfarm motion-check <video.mp4> [--json]`.");
+    const videoPath = path.resolve(process.cwd(), target);
+    if (!existsSync(videoPath))
+        throw new Error(`No such file: ${videoPath}`);
+    const fpsRaw = parsed.values.fps;
+    const fpsGrid = fpsRaw !== undefined ? Number(fpsRaw) : undefined;
+    if (fpsRaw !== undefined && (!Number.isFinite(fpsGrid) || fpsGrid <= 0)) {
+        throw new Error(`--fps must be a positive number, got "${fpsRaw}".`);
+    }
+    const { checkRenderMotion, formatFrozenRenderFailure } = await import("./lib/frozen-render.js");
+    const result = await checkRenderMotion(videoPath, fpsGrid ? { fpsGrid } : {});
+    if (parsed.values.json) {
+        printJson(result);
+        if (result.frozen)
+            process.exitCode = 1;
+        return;
+    }
+    if (result.frozen) {
+        console.log(formatFrozenRenderFailure(result, { red: RED, bold: BOLD, dim: DIM, reset: RESET }));
+        process.exitCode = 1;
+        return;
+    }
+    if (result.skipped) {
+        console.log(`${YELLOW}? Motion not verified${RESET} ${DIM}— ${result.reason}${RESET}`);
+        return;
+    }
+    console.log(`${GREEN}✓ The video moves${RESET} ${DIM}— ${result.moving_pairs}/${result.compared_pairs} sampled frame pairs differ (max change ${result.motion_score.toFixed(1)}%).${RESET}`);
+    console.log(`${DIM}This proves motion exists, not that the video is good. Still watch it: vidfarm stills <dir> --sheet.${RESET}`);
+}
 // ── Agent skill ───────────────────────────────────────────────────────────────
 // Install the latest director skill onto disk as a Claude Code / agent skill so
 // the user's AI agent can read SKILL.director.md and act. We pull the freshest