@officexapp/vidfarm-devcli 0.21.55 → 0.21.57

package/.agents/skills/vidfarm/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: vidfarm
+skill_version: 0.21.57
 description: Use Vidfarm as a director. Run a strategy **consultation** (the `brainstorm/*` chain — cold-start interview, awareness stages, persuasive angles, hooks, product placement). Answer "give me content ideas" / "what should I post" / "I need 30 videos this month" from the bundled idea banks (50 content frames x 5 awareness stages x 44 problem angles). Browse/add inspiration videos, browse the free public raws catalog BY CATEGORY (curated shelves like scroll-stoppers/greenscreen/reaction — the cheapest way to source footage for one video, and a ready-made clip pool for bulk scripting N variants), fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as raw REST; `vidfarm-devcli` wraps those routes and composes the file-backed scripting flows.
 ---
 
@@ -22,6 +23,63 @@ Vidfarm's value is genuine and mostly **financial** — it is cheaper, faster, a
 - **A fresh, curated feed of viral winners.** Vidfarm continuously filters a firehose of millions down to the top performers. Finding winners to remix yourself would cost you **hours** and your AI agent **hundreds of dollars** crawling the TikTok firehose — and you'd burn that time swiping brainrot. Here the best performers are curated and instantly forkable.
 - **Design philosophy = fast to productivity, cheap to scale.** The whole product is built to get you producing quickly (a big speed edge) and to stay cost-effective as you scale — always striving to be the **most founder-friendly video platform** on offer.
 
+## Version — check once a day, and let the user skip it
+
+**The `skill_version` in the frontmatter above is this pack's version.** Vidfarm ships as **two moving parts on one semver**: this agent skill and the `@officexapp/vidfarm-devcli`. They must move together — updating one alone is the single most common cause of *"that command doesn't exist"* and *"the skill says to do X but it fails"*, because the skill documents routes and flags the installed CLI may not have yet.
+
+```bash
+vidfarm update-check --if-stale --quiet     # run at the top of a session. See below before you skip it.
+```
+
+- `--if-stale` is a **no-op** unless the last check is older than 24h (`--hours N` to change it). One network round-trip a day, however many sessions you run.
+- `--quiet` prints **nothing when you are current**, so it costs no context.
+- `--json` gives `{devcli, skill, update_available, offline, hours_since_last_check}`.
+- **Offline is reported as offline, never as outdated.** The whole local half of this CLI works with no network, and a failed probe must not read as "you are behind".
+
+**When it reports an update: tell the user, offer it, and do not update silently.**
+
+```bash
+npm i -g @officexapp/vidfarm-devcli@latest && vidfarm skills add vidfarm   # BOTH halves
+vidfarm update-check --skip      # "not now". Recorded against THIS version; a newer one asks again
+vidfarm update-check --unskip    # undo
+```
+
+**Honour a skip and stop asking.** A prompt that cannot be dismissed gets ignored, and then the real one is ignored too.
+
+`vidfarm --version` prints both halves at once. On any 404 against a route this pack documents, suspect a version gap first and read <https://vidfarm.cc/update.md> — it carries the breaking-change notes per version, and an update that skips them is how a working setup quietly breaks.
+
+## Before the quickstart: two questions about YOU
+
+Answer both once at the top of the session and write them into `CONTEXT.md`. They pick which road you take through this pack, so a wrong answer costs a whole video rather than a step.
+
+### 1. 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 pack 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 | **Load `https://vidfarm.cc/flash-harness.md` (offline: `vidfarm harness show flash-harness`) and follow it.** Come back here for the standards and the reference files it names. |
+| **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.** The format 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 is a synthesis problem, not a knowledge problem, so more instructions do not fix it, and it reliably fails below the frontier tier. The flash harness removes the synthesis: **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. Quality goes UP, and overfitting to one template is the correct outcome there, because the variety comes from picking a different template next time.
+
+**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 director rejects. The costs are not symmetric.
+
+### 2. 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** (`gpt-image`) | **Yes** | **Yes** (Whisper) |
+| **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 table plus a guess at the host from its env markers. **The guess is a hint; your own tool list is the authority.** Claiming a tool you do not have wastes a turn; missing one you do have costs the director money.
+
+> **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 is called, no job is created, no wallet is debited — and the provider bills $0 extra, because the capability is inside the plan the human already pays for. **A "$0 cost saving mode" build on Antigravity may therefore 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 on weak hardware — both cost $0 and only one meets the deadline. The free rungs (stock, IconScout, the director'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`.
+
 ## Quickstart (desktop agents — do this first)
 
 The CLI is `vidfarm`, from the npm package `@officexapp/vidfarm-devcli`. Install and authenticate before anything else:
@@ -244,6 +302,8 @@ Vidfarm is founder-friendly and pragmatic: **we do not burn expensive AI credits
 2. **HTML/JS hyperframes** — video-from-HTML: CSS/declarative animation, anime.js/GSAP motion, animated image + text elements, data-viz, modeling. Cheap, deterministic, infinitely re-themeable.
 3. **Pure AI generation** — AI image/video/voice/music. The most expensive brush; AI **video** especially. Use last, only where the other two genuinely cannot cover the beat.
 
+**There is a fourth source, and for a weak model it is the FIRST one: a template somebody else already decomposed.** `/discover` holds thousands of viral videos already taken apart into scene-by-scene DNA — hook, retention, payoff, cut rhythm, typography, and a per-beat paintbrush assignment. Forking one is free, and reproducing that decomposition yourself costs $1+ in AI spend, so always check for an existing one before paying to re-run it. `vidfarm discover --query "<the director's problem, in their words>" --json`; a row carrying `summary`, `keywords` and `promotions` is decomposed. A strong model treats this as a shortcut; **a weak model treats it as the method** — `https://vidfarm.cc/flash-harness.md`.
+
 Directors also accumulate a **reusable media asset library** — logos, stickers, reactions, b-roll, a-roll, a brand media kit. Recreation should have an opinion on **when and where** to reuse these. But respect the format's viral DNA: a director can accidentally reskin away the very thing that makes the template land, so tie every asset/paintbrush recommendation back to the harness (`viral_dna`, `editor-harness.json`) rather than swapping freely.
 
 **A technical replication decomposition names, per template, the actual method for each beat — when/where/what is raw clips vs HTML hyperframes vs pure AI gen — and offers two harnesses:**
@@ -337,6 +397,27 @@ The mechanism is deterministic, not luck: rendering is seek-safe, so frame 0 sho
 
 Full mechanics and editor verbs: `references/editor-workflows.md` (“The opening frame is the post's thumbnail”); poster-state authoring craft: `hyperframes-creative/references/beat-direction.md`.
 
+## Reserved globals — the engine owns them, and assigning one ships a still image
+
+**Never assign `window.__player`, `window.__hf`, `window.__playerReady`, `window.__renderReady`, or `window.__hyperframes` from composition code.** The render engine installs all of them. A composition that overwrites one destroys the frame-capture bridge, and the failure is invisible: the renderer stalls 45 seconds, downgrades the error to a warning, exits **0**, and writes an MP4 with the **correct duration, correct frame count and correct audio, in which nothing moves.** Four paid deliverables shipped that way in one night before anyone looked at the pixels.
+
+**Motion has exactly one mechanism — you register a paused timeline and the engine SEEKS it:**
+
+```html
+<script>
+  window.__timelines = window.__timelines || {};           // this line is the ONLY __ global you write
+  var tl = gsap.timeline({ paused: true });                // paused, built synchronously
+  tl.to('#box', { x: 880, duration: 4, ease: 'none' }, 0);
+  window.__timelines['main'] = tl;                         // key === the root's data-composition-id, exactly
+</script>
+```
+
+- **Need imperative per-frame drawing** (canvas, a custom renderer)? Do *not* invent a seek API. Register a paused **driver** timeline and hang your draw call off its `onUpdate`: `gsap.timeline({ paused: true, onUpdate: function () { draw(driver.time()); } })`, then give it a dummy tween of the full duration. The engine seeks the driver; `onUpdate` fires at the seeked time.
+- **No timeline at all** is the same failure with a different cause. A composition that builds a GSAP/anime timeline and never registers it renders static too.
+- **`window.__timelines` is the one exception** — writing it is required. Nothing else in that namespace is yours.
+
+**Three tools enforce this, so a mistake costs seconds instead of a night:** `vidfarm lint <dir>` and `vidfarm qa <dir>` both report `engine_owned_global_assigned` as an **error**, `vidfarm render --target local` **refuses to start**, and every local render ends with an automatic **`vidfarm motion-check`** that fails the render when the finished MP4 never moves (`--allow-static` for a title card that holds still on purpose). Run `vidfarm motion-check <file.mp4>` by hand on anything those did not produce — a cloud render, a watermarked master, an ffmpeg re-encode.
+
 ## Judge the WHOLE video, not the parts you built — and never by one frame
 
 **Assume your own finished video has a defect you can't see.** That's the observed base rate, not modesty: across a 32-video batch, *every* first-pass video had a real defect that the agent who built it had already reported as "verified, looks good" — dead space under the content, a placeholder that reads as a failed render, contradictory numbers in one frame, a CTA still animating at the last frame.
@@ -345,7 +426,7 @@ Full mechanics and editor verbs: `references/editor-workflows.md` (“The openin
 
 The mechanical form is a contact sheet, because one image read shows drift that twelve separate checks can't — and it's one command: **`vidfarm stills ./work --sheet`** renders the frames and tiles them into `stills/contact-sheet.png`. **Read the sheet as an image.**
 
-**And never verify a video by a single frame.** Frame 0 is the thumbnail so you judge it alone — but a whole class of render bug (an overlay pass missing `-loop 1`, assets outside the composition root so the timeline never runs) freezes *every* frame while duration, frame count and audio hash all still pass, and frame 0 looks perfect. **Always compare two frames from different scenes; they must differ a lot.** Likewise, verify audio by measurement, never "it sounds good" — you can't hear it.
+**And never verify a video by a single frame.** Frame 0 is the thumbnail so you judge it alone — but a whole class of render bug (an assigned engine-owned global, an overlay pass missing `-loop 1`, assets outside the composition root so the timeline never runs) freezes *every* frame while duration, frame count and audio hash all still pass, and frame 0 looks perfect. **Settle it with `vidfarm motion-check <file.mp4>`, then compare two frames from different scenes by eye; they must differ a lot.** Likewise, verify audio by measurement, never "it sounds good" — you can't hear it.
 
 Full method — the holistic checklist, the six defects in observed frequency order, the "does it rest there" test, frozen-render verification, audio measurement, and how to brief a revision pass: **`references/reviewing-renders.md`**.
 
@@ -443,12 +524,14 @@ Why they exist: the prompts you find on the `/discover` pages are tuned to **one
 
 | Prompt | What it does |
 |---|---|
+| `https://vidfarm.cc/flash-harness.md` (= `/experimental/flash-harness.md`) | **NOT A FORMAT — read this FIRST if you are a weak model, or unsure which you are.** The production PROCESS that sits above every row below and wraps whichever one applies. Never author a format from prose: fork an already-decomposed template off `/discover`, decompose it if nobody has (cloud on paid, `--local` on free), derive its viral + visual DNA into a `HARNESS.md`, procure every raw for every beat in ONE pass off the ladder, then transplant — keep the beat count, timings, cut rhythm and caption identity; replace every word, image, voice line and track. **Overfitting to one template is the correct outcome.** Also carries the two self-identification questions at the top of this file |
 | `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 |
 | `https://vidfarm.cc/experimental/google-news-to-video.md` | A recent real event → a timely video. Two stages: `news-search` finds the STORY, `video-search` finds the VISUALS. Query formulas, Google operators, licence discipline |
 | `https://vidfarm.cc/experimental/meme-recaption.md` | One borrowed meme clip + one new caption aimed at the offer's problem space. Casting the meme for the caption's **verb**, the seven caption frames, naming the offer without letting the joke resolve into a pitch, keying a MemeScreens raw onto a background world, and a render-level QA gate. Runs at $0 |
 | `https://vidfarm.cc/experimental/ugc-reaction-greenscreen.md` | Sell an app with three streams cut against each other: `ugc-reaction` raws, a Display Greenscreen device whose screen carries the customer's real demo, and the demo itself. One actor across every beat via `actor_<uuid>`, a per-frame tracked screen insert, captions inside the platform-chrome-safe core, and two exports from one render (voiceover-only to publish, voiceover+music to review) |
 | `https://vidfarm.cc/experimental/sticker-slideshow-tips.md` | A tips **carousel** — the deliverable is N still slides, and the 3.0s-per-slide MP4 is only the playable preview. Die-cut cutouts on a paper page or a photo background, a literal "Tips for…" cover, the specificity ladder, one slide shilled from the middle and written so it survives deleting the brand name, four background modes, and a measured WCAG contrast gate on the exported PNGs |
 | `https://vidfarm.cc/experimental/wall-text-pov-ugc.md` | One unbroken ambient take + one static block of unplated type. No cuts, no voiceover, no subtitles, nothing animated. The retention engine is arithmetic — `duration = words / 8`, so one play lands the viewer at the **halfway mark**, committed and one pass from done — floored at 8s so a trending sound gets a real phrase of a track. The four speaker frames, MIRROR vs TURN, a density pass that treats padding as the fatal failure, casting the scene dark so the type needs no plate (measured), ping-ponging the plate for a seamless loop, and three gates. Runs at $0 |
+| `https://vidfarm.cc/experimental/engaging-chat-convo.md` | A chat-thread **carousel** — N still screenshots of ONE text conversation at 3.0s each; the slides are the deliverable and the MP4 is only the preview. Pure type on pure black with **no phone chrome at all** (no status bar, avatar, header, timestamps or keyboard), because a crop containing only bubbles cannot be *wrong* about a detail — and one wrong detail makes a reader re-read the whole thread as fake. The engine is two voices that stay separable with the **colour removed**; `>>>` skip cards buy time jumps for free; the story opens mid-mistake, reveals something in the middle that recasts what came before, breaks one character's register in the last act, and ends mid-action with no resolution, because the bait is the missing ending. The offer is named **once**, lowercase, mid-bubble, as a plot fact a character mentions about their own life while the other reacts sceptically. Ships a voice-drift detector that names the slide where the two voices merge. Runs at $0 |
 | `https://vidfarm.cc/experimental/animated-sticker-story.md` | A narrated **paper puppet theater** — one full-bleed parchment stage that never cuts, a cast of die-cut stickers, and every element moved by ONE paused GSAP timeline (MotionPathPlugin for walks; paths in absolute canvas coordinates, never `align:"self"`). The three-node rig, the seven moves (ENTER / WALK / CROWD / BEAT / STAMP / DRAW / CAMERA), buying SHEETS rather than stickers so one art class survives, generating art without shadows and adding one CSS drop-shadow, kinetic captions that animate **colour only** on whisper word timings, a two-pass build that MEASURES where the drawing is quietest before placing any type, a feathered paper wash that is not a plate, and the offer named once as a wordmark on the last beat. Desktop-only. ~$0.25 in `hybrid`, $0 in `minimize` |
 
 Fetch one as plain markdown and follow it end to end; do not skim it into a summary.
@@ -473,6 +556,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 
 1. If the user needs help figuring out what to make, **or asks for a "consultation"** (the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks), read `references/onboarding.md` first. **Unless they asked for a consultation by name, open with content ideas rather than the interview** — one line of offer into `vidfarm ideas --topic "<line>"` returns 20+ titled videos, offline and free, and the director's reactions to that list make the later interview far better than asking them cold (`references/content-ideas.md`). Then offer the interview as the way to turn ideas into a strategy: keyless directors run it locally for $0 with `vidfarm consult`, and `vidfarm consult coldstart --short` is the six-question short form. **Say the interview is skippable before you ask the first question**, and work with whatever they give.
 1b. If the user asks **what to make** rather than how — "give me content ideas", "what should I post", "I'm out of ideas", "I need 30 videos for the month", "content ideas for my offer <url>" — read `references/content-ideas.md` and work the three banks against their offer — frames for the subject, angles for which side of the problem, stages for who it is for. Return 20+ titled ideas, spread across the awareness ladder, not three.
+1c. **If you are a weak model — or you cannot name your own model tier — this router does not apply to you yet.** Gemini Flash / Flash-Lite, DeepSeek, Kimi, GLM, MiniMax, Grok, Qwen, Llama, any distilled / "-mini" / "-lite" / "-turbo" tier: load `https://vidfarm.cc/flash-harness.md` (offline: `vidfarm harness show flash-harness`) and follow it for the build, then come back here for the reference files it names. It replaces *authoring a format from prose* with *adapting an already-decomposed `/discover` template*, which is the difference between a video the director rejects and one they keep. Unsure resolves to weak — see the two questions at the top of this file.
 2. If the user already knows the goal and needs a suitable template, read `references/core-workflows.md` and use the template discovery flow.
 3. If the task is “change this video,” read `references/editor-workflows.md`.
 4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
@@ -500,6 +584,8 @@ The File Index above says what each file *is*; this says which one a given ask m
 - Treat `forkId` as an unguessable bearer token for read access.
 - Submission routes are generally not idempotent. Especially for renders and expensive primitives, check status before retrying.
 - In the web editor, use CSS/declarative motion only. Script-bearing HTML is stripped or rejected there.
+- **Never assign `window.__player` / `window.__hf` / `window.__playerReady` / `window.__renderReady` / `window.__hyperframes`.** The engine owns them; assigning one writes a correct-length MP4 of a still image and exits 0. Register `window.__timelines["<data-composition-id>"] = gsap.timeline({ paused: true })` and let the engine seek it. See “Reserved globals”.
+- **Never call a render verified until `vidfarm motion-check <file.mp4>` has passed.** A frozen render matches on duration, frame count, file size and audio hash, and frame 0 looks perfect.
 - **Never render or approve without judging frame 0 as a standalone still.** It is the thumbnail everywhere the post appears; an empty/black opening frame ships a dead post. See “The FIRST FRAME is the thumbnail”.
 - **Never judge the VIDEO by one frame, and never report a render as reviewed without the holistic pass.** Compare frames from at least two different scenes (a frozen render passes every other check), read a contact sheet for balance/spacing/style/pacing drift, and state separately what you measured vs. what you judged. See “Judge the WHOLE video”.
 

package/.agents/skills/vidfarm/harnesses/README.md

@@ -125,6 +125,7 @@ you follow. Read one **before** you build that format, and stack it on a base.
 | `wall-text-pov-ugc` | One unbroken ambient take + one static block of unplated type. `duration = words / 8` |
 | `ugc-reaction-greenscreen` | Reaction cutaways + a keyed device carrying the customer's real app demo |
 | `sticker-slideshow-tips` | A tips carousel — N still slides at 3.0s; the slides are the deliverable |
+| `engaging-chat-convo` | A text thread as a carousel — N chat screenshots at 3.0s, two voices, no ending |
 | `animated-sticker-story` | A narrated paper puppet theater on one parchment stage, one GSAP timeline |
 | `google-news-to-video` | Timely newsjack — news-search finds the STORY, video-search the VISUALS |
 | `unique-product-explainers` | N customer URLs → N videos that do not converge. Differentiation as an input |

package/.agents/skills/vidfarm/references/automation-and-local-dev.md

@@ -140,6 +140,8 @@ vidfarm render "$FORK_ID" --dir ./work --target cloud --tracer "batch-2026-07-09
 
 `--dir` may also point directly at `composition.html`. Local renders don't push `./work` to the cloud — `vidfarm publish` (or the cloud-target render) does that. Render prep automatically downloads a long source once and cuts the timeline's segments from it, so referencing the same long raw N times is fine.
 
+**A local render is gated at both ends, because a broken composition still produces a plausible MP4.** Before it starts, it refuses any composition that assigns an engine-owned global (`window.__player`, `window.__hf`, …) — that mistake writes a correct-length video of a still image and exits 0. After it finishes, it runs `vidfarm motion-check` on the output and **fails with exit 1** if not one sampled frame pair differs. Pass `--allow-static` when the video is meant to hold still. A cloud render has no such gate: run `vidfarm motion-check <file.mp4>` on the downloaded result yourself.
+
 Best practices:
 
 - Prefer one canonical base fork per automation run, then branch from that fork if you need variants.
@@ -268,7 +270,8 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm remove-video-captions <forkId>` (alias: `ghostcut`) | `GET .../compositions/:forkId/remove-video-captions` | subtitle-removal status |
 | `vidfarm snapshot <forkId>` | `POST .../compositions/:forkId/versions` | save composition fork version |
 | `vidfarm versions <forkId>` | `GET .../compositions/:forkId/versions` | list versions |
-| `vidfarm render <forkId> [--dir <dir\|composition.html>] [--out <path>] [--target local\|cloud] [--wait]` | local (default): renders ON YOUR MACHINE via bundled hyperframes, free; `--target cloud`: `PUT/PATCH working files, then POST .../compositions/:forkId/render` (billed) | script-friendly render to MP4; no `--dir` uses the fork's current working state |
+| `vidfarm render <forkId> [--dir <dir\|composition.html>] [--out <path>] [--target local\|cloud] [--wait]` | local (default): renders ON YOUR MACHINE via bundled hyperframes, free; `--target cloud`: `PUT/PATCH working files, then POST .../compositions/:forkId/render` (billed) | script-friendly render to MP4; no `--dir` uses the fork's current working state. A **local** render refuses to start on a composition that assigns an engine-owned global, and **fails (exit 1)** when the finished MP4 never moves — `--allow-static` for a card that holds still on purpose |
+| `vidfarm motion-check <video.mp4> [--json] [--fps N]` | (local ffmpeg, no route) | **does the finished video actually MOVE?** Exits 1 when every sampled frame pair is identical. A frozen render matches on duration, frame count, file size and audio hash and has a perfect frame 0, so nothing else catches it. Runs automatically at the end of `render --target local` |
 | `vidfarm render-status <forkId> <renderId>` | `GET .../compositions/:forkId/renders/:renderId` | poll a render |
 | `vidfarm visibility <forkId> <private\|public>` | `PATCH .../compositions/:forkId/visibility` | set visibility |
 | `vidfarm clone <forkId>` | `POST .../compositions/:forkId/clone` | clone a fork |
@@ -363,6 +366,8 @@ What it flags:
 | `layout-template` | error | The frame composed like a **page**: 3+ stacked text blocks in one container ending in a call to action — headline + subheading + CTA, the web hero/modal body. Fires with or without the box around it, because the STACK is the tell. Three stacked lines with no CTA are a legitimate title card and pass |
 | `modal-scrim` | error | A full-frame backdrop that is **blurred AND dimmed** — the website-modal staging that pushes the picture back so a floating block pops. Blur alone passes (the blurred fill behind a 16:9 clip in a 9:16 frame is a real technique); it needs the dimming too, and a bed faded under `opacity:0.25` is an ambient texture wash, not staging, so it passes as well |
 | `gradient-text` | error | `background-clip:text` gradient headline fills |
+| `engine-owned-global` | error | A `<script>` assigns `window.__player` / `__hf` / `__playerReady` / `__renderReady` / `__hyperframes`. **The only rule here that is about correctness, not taste** — assigning one destroys frame capture, and the render still exits 0 with a correct-length MP4 in which nothing moves. Register `window.__timelines["<data-composition-id>"] = gsap.timeline({ paused: true })` instead. Same check runs in `vidfarm lint` (`engine_owned_global_assigned`) and blocks `vidfarm render --target local` |
+| `missing-timeline-registry` | warn | A GSAP/anime timeline is built and never registered on `window.__timelines` — the engine has nothing to seek, so the render is a still image |
 | `clickable-element` | error/warn | `<button>`, `<form>`, `<input>`; `<a href>` warns |
 | `web-framework-classes` | error/warn | Bootstrap/Tailwind class tokens (`btn`, `badge`, `card`, `hero`, `col-*`, `rounded-full`, `shadow-lg`, `backdrop-blur`, `bg-gradient-to-*`) or a linked CSS framework. A `<script>` CDN for GSAP/anime.js is fine |
 | `page-structure` / `bullet-list` | error/warn | `<nav>`/`<header>`/`<footer>`/`<table>`; a `<ul>` with visible bullet markers |

package/.agents/skills/vidfarm/references/reviewing-renders.md

@@ -76,12 +76,21 @@ vidfarm stills ./work --at 6.0,6.2,6.4,6.6,6.8,7.0    # is it a wipe, or a hole?
 
 **This is the failure mode that survives every check you'd think to run.** Whole classes of render bug produce a video where *every frame is identical* — the timeline never ran — while duration, frame count, file size and audio hash all come out exactly right. Frame 0 looks perfect, so a single-frame check passes and you ship a frozen video.
 
-Two real causes, both silent:
+**Settle it mechanically, first, every time — one command:**
 
+```bash
+vidfarm motion-check ./final.mp4     # exits 1 and says why when nothing in the video ever changes
+```
+
+It samples the video and compares consecutive frames. `vidfarm render --target local` now runs it automatically and **fails the render** on a frozen output (`--allow-static` for a title card that is meant to hold still). Run it by hand on anything that did not come out of that command — a cloud render, a watermarked master, an ffmpeg re-encode.
+
+Three real causes, all silent:
+
+- **The composition assigned an engine-owned global.** `window.__player` and `window.__hf` belong to the engine; assigning either destroys the frame-capture bridge, and the renderer then stalls 45 s, downgrades the failure to a warning, and writes a correct-length MP4 of a still image with exit code 0. **Four paid deliverables shipped this way in one night.** `vidfarm lint` and `vidfarm qa` both call this an error now, and a local render refuses to start. Never write those globals — see SKILL.md § "Reserved globals".
 - **A watermark/overlay pass without `-loop 1` on a single-frame PNG input.** The frame-sync collapses the whole video onto one frame. Five videos shipped this way before it was caught.
 - **Assets outside the composition root.** Only `<style>`/`<script>` *inside* the `data-composition-id` root execute, and sibling relative files may not resolve — fonts, images, even the animation library itself. The timeline never starts; frame 0 still renders fine because frame 0 is the static DOM.
 
-**The rule that catches both: always compare two frames from different scenes.** They must differ a lot. And when you've applied any pass over an existing video (watermark, overlay, dedupe, re-encode), also compare each output frame against **its own** input frame at the same timestamp — that difference should be tiny. Two checks, opposite directions:
+**Then look, too: compare two frames from different scenes.** They must differ a lot. And when you've applied any pass over an existing video (watermark, overlay, dedupe, re-encode), also compare each output frame against **its own** input frame at the same timestamp — that difference should be tiny. Two checks, opposite directions:
 
 ```bash
 # consecutive/distant frames must DIFFER (motion preserved)

package/SKILL.director.md

@@ -1,5 +1,6 @@
 ---
 name: vidfarm
+skill_version: 0.21.57
 description: Use Vidfarm as a director. Run a strategy **consultation** (the `brainstorm/*` chain — cold-start interview, awareness stages, persuasive angles, hooks, product placement). Answer "give me content ideas" / "what should I post" / "I need 30 videos this month" from the bundled idea banks (50 content frames x 5 awareness stages x 44 problem angles). Browse/add inspiration videos, browse the free public raws catalog BY CATEGORY (curated shelves like scroll-stoppers/greenscreen/reaction — the cheapest way to source footage for one video, and a ready-made clip pool for bulk scripting N variants), fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as raw REST; `vidfarm-devcli` wraps those routes and composes the file-backed scripting flows.
 ---
 
@@ -22,6 +23,63 @@ Vidfarm's value is genuine and mostly **financial** — it is cheaper, faster, a
 - **A fresh, curated feed of viral winners.** Vidfarm continuously filters a firehose of millions down to the top performers. Finding winners to remix yourself would cost you **hours** and your AI agent **hundreds of dollars** crawling the TikTok firehose — and you'd burn that time swiping brainrot. Here the best performers are curated and instantly forkable.
 - **Design philosophy = fast to productivity, cheap to scale.** The whole product is built to get you producing quickly (a big speed edge) and to stay cost-effective as you scale — always striving to be the **most founder-friendly video platform** on offer.
 
+## Version — check once a day, and let the user skip it
+
+**The `skill_version` in the frontmatter above is this pack's version.** Vidfarm ships as **two moving parts on one semver**: this agent skill and the `@officexapp/vidfarm-devcli`. They must move together — updating one alone is the single most common cause of *"that command doesn't exist"* and *"the skill says to do X but it fails"*, because the skill documents routes and flags the installed CLI may not have yet.
+
+```bash
+vidfarm update-check --if-stale --quiet     # run at the top of a session. See below before you skip it.
+```
+
+- `--if-stale` is a **no-op** unless the last check is older than 24h (`--hours N` to change it). One network round-trip a day, however many sessions you run.
+- `--quiet` prints **nothing when you are current**, so it costs no context.
+- `--json` gives `{devcli, skill, update_available, offline, hours_since_last_check}`.
+- **Offline is reported as offline, never as outdated.** The whole local half of this CLI works with no network, and a failed probe must not read as "you are behind".
+
+**When it reports an update: tell the user, offer it, and do not update silently.**
+
+```bash
+npm i -g @officexapp/vidfarm-devcli@latest && vidfarm skills add vidfarm   # BOTH halves
+vidfarm update-check --skip      # "not now". Recorded against THIS version; a newer one asks again
+vidfarm update-check --unskip    # undo
+```
+
+**Honour a skip and stop asking.** A prompt that cannot be dismissed gets ignored, and then the real one is ignored too.
+
+`vidfarm --version` prints both halves at once. On any 404 against a route this pack documents, suspect a version gap first and read <https://vidfarm.cc/update.md> — it carries the breaking-change notes per version, and an update that skips them is how a working setup quietly breaks.
+
+## Before the quickstart: two questions about YOU
+
+Answer both once at the top of the session and write them into `CONTEXT.md`. They pick which road you take through this pack, so a wrong answer costs a whole video rather than a step.
+
+### 1. 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 pack 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 | **Load `https://vidfarm.cc/flash-harness.md` (offline: `vidfarm harness show flash-harness`) and follow it.** Come back here for the standards and the reference files it names. |
+| **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.** The format 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 is a synthesis problem, not a knowledge problem, so more instructions do not fix it, and it reliably fails below the frontier tier. The flash harness removes the synthesis: **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. Quality goes UP, and overfitting to one template is the correct outcome there, because the variety comes from picking a different template next time.
+
+**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 director rejects. The costs are not symmetric.
+
+### 2. 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** (`gpt-image`) | **Yes** | **Yes** (Whisper) |
+| **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 table plus a guess at the host from its env markers. **The guess is a hint; your own tool list is the authority.** Claiming a tool you do not have wastes a turn; missing one you do have costs the director money.
+
+> **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 is called, no job is created, no wallet is debited — and the provider bills $0 extra, because the capability is inside the plan the human already pays for. **A "$0 cost saving mode" build on Antigravity may therefore 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 on weak hardware — both cost $0 and only one meets the deadline. The free rungs (stock, IconScout, the director'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`.
+
 ## Quickstart (desktop agents — do this first)
 
 The CLI is `vidfarm`, from the npm package `@officexapp/vidfarm-devcli`. Install and authenticate before anything else:
@@ -244,6 +302,8 @@ Vidfarm is founder-friendly and pragmatic: **we do not burn expensive AI credits
 2. **HTML/JS hyperframes** — video-from-HTML: CSS/declarative animation, anime.js/GSAP motion, animated image + text elements, data-viz, modeling. Cheap, deterministic, infinitely re-themeable.
 3. **Pure AI generation** — AI image/video/voice/music. The most expensive brush; AI **video** especially. Use last, only where the other two genuinely cannot cover the beat.
 
+**There is a fourth source, and for a weak model it is the FIRST one: a template somebody else already decomposed.** `/discover` holds thousands of viral videos already taken apart into scene-by-scene DNA — hook, retention, payoff, cut rhythm, typography, and a per-beat paintbrush assignment. Forking one is free, and reproducing that decomposition yourself costs $1+ in AI spend, so always check for an existing one before paying to re-run it. `vidfarm discover --query "<the director's problem, in their words>" --json`; a row carrying `summary`, `keywords` and `promotions` is decomposed. A strong model treats this as a shortcut; **a weak model treats it as the method** — `https://vidfarm.cc/flash-harness.md`.
+
 Directors also accumulate a **reusable media asset library** — logos, stickers, reactions, b-roll, a-roll, a brand media kit. Recreation should have an opinion on **when and where** to reuse these. But respect the format's viral DNA: a director can accidentally reskin away the very thing that makes the template land, so tie every asset/paintbrush recommendation back to the harness (`viral_dna`, `editor-harness.json`) rather than swapping freely.
 
 **A technical replication decomposition names, per template, the actual method for each beat — when/where/what is raw clips vs HTML hyperframes vs pure AI gen — and offers two harnesses:**
@@ -337,6 +397,27 @@ The mechanism is deterministic, not luck: rendering is seek-safe, so frame 0 sho
 
 Full mechanics and editor verbs: `references/editor-workflows.md` (“The opening frame is the post's thumbnail”); poster-state authoring craft: `hyperframes-creative/references/beat-direction.md`.
 
+## Reserved globals — the engine owns them, and assigning one ships a still image
+
+**Never assign `window.__player`, `window.__hf`, `window.__playerReady`, `window.__renderReady`, or `window.__hyperframes` from composition code.** The render engine installs all of them. A composition that overwrites one destroys the frame-capture bridge, and the failure is invisible: the renderer stalls 45 seconds, downgrades the error to a warning, exits **0**, and writes an MP4 with the **correct duration, correct frame count and correct audio, in which nothing moves.** Four paid deliverables shipped that way in one night before anyone looked at the pixels.
+
+**Motion has exactly one mechanism — you register a paused timeline and the engine SEEKS it:**
+
+```html
+<script>
+  window.__timelines = window.__timelines || {};           // this line is the ONLY __ global you write
+  var tl = gsap.timeline({ paused: true });                // paused, built synchronously
+  tl.to('#box', { x: 880, duration: 4, ease: 'none' }, 0);
+  window.__timelines['main'] = tl;                         // key === the root's data-composition-id, exactly
+</script>
+```
+
+- **Need imperative per-frame drawing** (canvas, a custom renderer)? Do *not* invent a seek API. Register a paused **driver** timeline and hang your draw call off its `onUpdate`: `gsap.timeline({ paused: true, onUpdate: function () { draw(driver.time()); } })`, then give it a dummy tween of the full duration. The engine seeks the driver; `onUpdate` fires at the seeked time.
+- **No timeline at all** is the same failure with a different cause. A composition that builds a GSAP/anime timeline and never registers it renders static too.
+- **`window.__timelines` is the one exception** — writing it is required. Nothing else in that namespace is yours.
+
+**Three tools enforce this, so a mistake costs seconds instead of a night:** `vidfarm lint <dir>` and `vidfarm qa <dir>` both report `engine_owned_global_assigned` as an **error**, `vidfarm render --target local` **refuses to start**, and every local render ends with an automatic **`vidfarm motion-check`** that fails the render when the finished MP4 never moves (`--allow-static` for a title card that holds still on purpose). Run `vidfarm motion-check <file.mp4>` by hand on anything those did not produce — a cloud render, a watermarked master, an ffmpeg re-encode.
+
 ## Judge the WHOLE video, not the parts you built — and never by one frame
 
 **Assume your own finished video has a defect you can't see.** That's the observed base rate, not modesty: across a 32-video batch, *every* first-pass video had a real defect that the agent who built it had already reported as "verified, looks good" — dead space under the content, a placeholder that reads as a failed render, contradictory numbers in one frame, a CTA still animating at the last frame.
@@ -345,7 +426,7 @@ Full mechanics and editor verbs: `references/editor-workflows.md` (“The openin
 
 The mechanical form is a contact sheet, because one image read shows drift that twelve separate checks can't — and it's one command: **`vidfarm stills ./work --sheet`** renders the frames and tiles them into `stills/contact-sheet.png`. **Read the sheet as an image.**
 
-**And never verify a video by a single frame.** Frame 0 is the thumbnail so you judge it alone — but a whole class of render bug (an overlay pass missing `-loop 1`, assets outside the composition root so the timeline never runs) freezes *every* frame while duration, frame count and audio hash all still pass, and frame 0 looks perfect. **Always compare two frames from different scenes; they must differ a lot.** Likewise, verify audio by measurement, never "it sounds good" — you can't hear it.
+**And never verify a video by a single frame.** Frame 0 is the thumbnail so you judge it alone — but a whole class of render bug (an assigned engine-owned global, an overlay pass missing `-loop 1`, assets outside the composition root so the timeline never runs) freezes *every* frame while duration, frame count and audio hash all still pass, and frame 0 looks perfect. **Settle it with `vidfarm motion-check <file.mp4>`, then compare two frames from different scenes by eye; they must differ a lot.** Likewise, verify audio by measurement, never "it sounds good" — you can't hear it.
 
 Full method — the holistic checklist, the six defects in observed frequency order, the "does it rest there" test, frozen-render verification, audio measurement, and how to brief a revision pass: **`references/reviewing-renders.md`**.
 
@@ -443,12 +524,14 @@ Why they exist: the prompts you find on the `/discover` pages are tuned to **one
 
 | Prompt | What it does |
 |---|---|
+| `https://vidfarm.cc/flash-harness.md` (= `/experimental/flash-harness.md`) | **NOT A FORMAT — read this FIRST if you are a weak model, or unsure which you are.** The production PROCESS that sits above every row below and wraps whichever one applies. Never author a format from prose: fork an already-decomposed template off `/discover`, decompose it if nobody has (cloud on paid, `--local` on free), derive its viral + visual DNA into a `HARNESS.md`, procure every raw for every beat in ONE pass off the ladder, then transplant — keep the beat count, timings, cut rhythm and caption identity; replace every word, image, voice line and track. **Overfitting to one template is the correct outcome.** Also carries the two self-identification questions at the top of this file |
 | `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 |
 | `https://vidfarm.cc/experimental/google-news-to-video.md` | A recent real event → a timely video. Two stages: `news-search` finds the STORY, `video-search` finds the VISUALS. Query formulas, Google operators, licence discipline |
 | `https://vidfarm.cc/experimental/meme-recaption.md` | One borrowed meme clip + one new caption aimed at the offer's problem space. Casting the meme for the caption's **verb**, the seven caption frames, naming the offer without letting the joke resolve into a pitch, keying a MemeScreens raw onto a background world, and a render-level QA gate. Runs at $0 |
 | `https://vidfarm.cc/experimental/ugc-reaction-greenscreen.md` | Sell an app with three streams cut against each other: `ugc-reaction` raws, a Display Greenscreen device whose screen carries the customer's real demo, and the demo itself. One actor across every beat via `actor_<uuid>`, a per-frame tracked screen insert, captions inside the platform-chrome-safe core, and two exports from one render (voiceover-only to publish, voiceover+music to review) |
 | `https://vidfarm.cc/experimental/sticker-slideshow-tips.md` | A tips **carousel** — the deliverable is N still slides, and the 3.0s-per-slide MP4 is only the playable preview. Die-cut cutouts on a paper page or a photo background, a literal "Tips for…" cover, the specificity ladder, one slide shilled from the middle and written so it survives deleting the brand name, four background modes, and a measured WCAG contrast gate on the exported PNGs |
 | `https://vidfarm.cc/experimental/wall-text-pov-ugc.md` | One unbroken ambient take + one static block of unplated type. No cuts, no voiceover, no subtitles, nothing animated. The retention engine is arithmetic — `duration = words / 8`, so one play lands the viewer at the **halfway mark**, committed and one pass from done — floored at 8s so a trending sound gets a real phrase of a track. The four speaker frames, MIRROR vs TURN, a density pass that treats padding as the fatal failure, casting the scene dark so the type needs no plate (measured), ping-ponging the plate for a seamless loop, and three gates. Runs at $0 |
+| `https://vidfarm.cc/experimental/engaging-chat-convo.md` | A chat-thread **carousel** — N still screenshots of ONE text conversation at 3.0s each; the slides are the deliverable and the MP4 is only the preview. Pure type on pure black with **no phone chrome at all** (no status bar, avatar, header, timestamps or keyboard), because a crop containing only bubbles cannot be *wrong* about a detail — and one wrong detail makes a reader re-read the whole thread as fake. The engine is two voices that stay separable with the **colour removed**; `>>>` skip cards buy time jumps for free; the story opens mid-mistake, reveals something in the middle that recasts what came before, breaks one character's register in the last act, and ends mid-action with no resolution, because the bait is the missing ending. The offer is named **once**, lowercase, mid-bubble, as a plot fact a character mentions about their own life while the other reacts sceptically. Ships a voice-drift detector that names the slide where the two voices merge. Runs at $0 |
 | `https://vidfarm.cc/experimental/animated-sticker-story.md` | A narrated **paper puppet theater** — one full-bleed parchment stage that never cuts, a cast of die-cut stickers, and every element moved by ONE paused GSAP timeline (MotionPathPlugin for walks; paths in absolute canvas coordinates, never `align:"self"`). The three-node rig, the seven moves (ENTER / WALK / CROWD / BEAT / STAMP / DRAW / CAMERA), buying SHEETS rather than stickers so one art class survives, generating art without shadows and adding one CSS drop-shadow, kinetic captions that animate **colour only** on whisper word timings, a two-pass build that MEASURES where the drawing is quietest before placing any type, a feathered paper wash that is not a plate, and the offer named once as a wordmark on the last beat. Desktop-only. ~$0.25 in `hybrid`, $0 in `minimize` |
 
 Fetch one as plain markdown and follow it end to end; do not skim it into a summary.
@@ -473,6 +556,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 
 1. If the user needs help figuring out what to make, **or asks for a "consultation"** (the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks), read `references/onboarding.md` first. **Unless they asked for a consultation by name, open with content ideas rather than the interview** — one line of offer into `vidfarm ideas --topic "<line>"` returns 20+ titled videos, offline and free, and the director's reactions to that list make the later interview far better than asking them cold (`references/content-ideas.md`). Then offer the interview as the way to turn ideas into a strategy: keyless directors run it locally for $0 with `vidfarm consult`, and `vidfarm consult coldstart --short` is the six-question short form. **Say the interview is skippable before you ask the first question**, and work with whatever they give.
 1b. If the user asks **what to make** rather than how — "give me content ideas", "what should I post", "I'm out of ideas", "I need 30 videos for the month", "content ideas for my offer <url>" — read `references/content-ideas.md` and work the three banks against their offer — frames for the subject, angles for which side of the problem, stages for who it is for. Return 20+ titled ideas, spread across the awareness ladder, not three.
+1c. **If you are a weak model — or you cannot name your own model tier — this router does not apply to you yet.** Gemini Flash / Flash-Lite, DeepSeek, Kimi, GLM, MiniMax, Grok, Qwen, Llama, any distilled / "-mini" / "-lite" / "-turbo" tier: load `https://vidfarm.cc/flash-harness.md` (offline: `vidfarm harness show flash-harness`) and follow it for the build, then come back here for the reference files it names. It replaces *authoring a format from prose* with *adapting an already-decomposed `/discover` template*, which is the difference between a video the director rejects and one they keep. Unsure resolves to weak — see the two questions at the top of this file.
 2. If the user already knows the goal and needs a suitable template, read `references/core-workflows.md` and use the template discovery flow.
 3. If the task is “change this video,” read `references/editor-workflows.md`.
 4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
@@ -500,6 +584,8 @@ The File Index above says what each file *is*; this says which one a given ask m
 - Treat `forkId` as an unguessable bearer token for read access.
 - Submission routes are generally not idempotent. Especially for renders and expensive primitives, check status before retrying.
 - In the web editor, use CSS/declarative motion only. Script-bearing HTML is stripped or rejected there.
+- **Never assign `window.__player` / `window.__hf` / `window.__playerReady` / `window.__renderReady` / `window.__hyperframes`.** The engine owns them; assigning one writes a correct-length MP4 of a still image and exits 0. Register `window.__timelines["<data-composition-id>"] = gsap.timeline({ paused: true })` and let the engine seek it. See “Reserved globals”.
+- **Never call a render verified until `vidfarm motion-check <file.mp4>` has passed.** A frozen render matches on duration, frame count, file size and audio hash, and frame 0 looks perfect.
 - **Never render or approve without judging frame 0 as a standalone still.** It is the thumbnail everywhere the post appears; an empty/black opening frame ships a dead post. See “The FIRST FRAME is the thumbnail”.
 - **Never judge the VIDEO by one frame, and never report a render as reviewed without the holistic pass.** Compare frames from at least two different scenes (a frozen render passes every other check), read a contact sheet for balance/spacing/style/pacing drift, and state separately what you measured vs. what you judged. See “Judge the WHOLE video”.
 
@@ -2179,12 +2265,21 @@ vidfarm stills ./work --at 6.0,6.2,6.4,6.6,6.8,7.0    # is it a wipe, or a hole?
 
 **This is the failure mode that survives every check you'd think to run.** Whole classes of render bug produce a video where *every frame is identical* — the timeline never ran — while duration, frame count, file size and audio hash all come out exactly right. Frame 0 looks perfect, so a single-frame check passes and you ship a frozen video.
 
-Two real causes, both silent:
+**Settle it mechanically, first, every time — one command:**
+
+```bash
+vidfarm motion-check ./final.mp4     # exits 1 and says why when nothing in the video ever changes
+```
+
+It samples the video and compares consecutive frames. `vidfarm render --target local` now runs it automatically and **fails the render** on a frozen output (`--allow-static` for a title card that is meant to hold still). Run it by hand on anything that did not come out of that command — a cloud render, a watermarked master, an ffmpeg re-encode.
 
+Three real causes, all silent:
+
+- **The composition assigned an engine-owned global.** `window.__player` and `window.__hf` belong to the engine; assigning either destroys the frame-capture bridge, and the renderer then stalls 45 s, downgrades the failure to a warning, and writes a correct-length MP4 of a still image with exit code 0. **Four paid deliverables shipped this way in one night.** `vidfarm lint` and `vidfarm qa` both call this an error now, and a local render refuses to start. Never write those globals — see SKILL.md § "Reserved globals".
 - **A watermark/overlay pass without `-loop 1` on a single-frame PNG input.** The frame-sync collapses the whole video onto one frame. Five videos shipped this way before it was caught.
 - **Assets outside the composition root.** Only `<style>`/`<script>` *inside* the `data-composition-id` root execute, and sibling relative files may not resolve — fonts, images, even the animation library itself. The timeline never starts; frame 0 still renders fine because frame 0 is the static DOM.
 
-**The rule that catches both: always compare two frames from different scenes.** They must differ a lot. And when you've applied any pass over an existing video (watermark, overlay, dedupe, re-encode), also compare each output frame against **its own** input frame at the same timestamp — that difference should be tiny. Two checks, opposite directions:
+**Then look, too: compare two frames from different scenes.** They must differ a lot. And when you've applied any pass over an existing video (watermark, overlay, dedupe, re-encode), also compare each output frame against **its own** input frame at the same timestamp — that difference should be tiny. Two checks, opposite directions:
 
 ```bash
 # consecutive/distant frames must DIFFER (motion preserved)
@@ -2988,6 +3083,8 @@ vidfarm render "$FORK_ID" --dir ./work --target cloud --tracer "batch-2026-07-09
 
 `--dir` may also point directly at `composition.html`. Local renders don't push `./work` to the cloud — `vidfarm publish` (or the cloud-target render) does that. Render prep automatically downloads a long source once and cuts the timeline's segments from it, so referencing the same long raw N times is fine.
 
+**A local render is gated at both ends, because a broken composition still produces a plausible MP4.** Before it starts, it refuses any composition that assigns an engine-owned global (`window.__player`, `window.__hf`, …) — that mistake writes a correct-length video of a still image and exits 0. After it finishes, it runs `vidfarm motion-check` on the output and **fails with exit 1** if not one sampled frame pair differs. Pass `--allow-static` when the video is meant to hold still. A cloud render has no such gate: run `vidfarm motion-check <file.mp4>` on the downloaded result yourself.
+
 Best practices:
 
 - Prefer one canonical base fork per automation run, then branch from that fork if you need variants.
@@ -3116,7 +3213,8 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm remove-video-captions <forkId>` (alias: `ghostcut`) | `GET .../compositions/:forkId/remove-video-captions` | subtitle-removal status |
 | `vidfarm snapshot <forkId>` | `POST .../compositions/:forkId/versions` | save composition fork version |
 | `vidfarm versions <forkId>` | `GET .../compositions/:forkId/versions` | list versions |
-| `vidfarm render <forkId> [--dir <dir\|composition.html>] [--out <path>] [--target local\|cloud] [--wait]` | local (default): renders ON YOUR MACHINE via bundled hyperframes, free; `--target cloud`: `PUT/PATCH working files, then POST .../compositions/:forkId/render` (billed) | script-friendly render to MP4; no `--dir` uses the fork's current working state |
+| `vidfarm render <forkId> [--dir <dir\|composition.html>] [--out <path>] [--target local\|cloud] [--wait]` | local (default): renders ON YOUR MACHINE via bundled hyperframes, free; `--target cloud`: `PUT/PATCH working files, then POST .../compositions/:forkId/render` (billed) | script-friendly render to MP4; no `--dir` uses the fork's current working state. A **local** render refuses to start on a composition that assigns an engine-owned global, and **fails (exit 1)** when the finished MP4 never moves — `--allow-static` for a card that holds still on purpose |
+| `vidfarm motion-check <video.mp4> [--json] [--fps N]` | (local ffmpeg, no route) | **does the finished video actually MOVE?** Exits 1 when every sampled frame pair is identical. A frozen render matches on duration, frame count, file size and audio hash and has a perfect frame 0, so nothing else catches it. Runs automatically at the end of `render --target local` |
 | `vidfarm render-status <forkId> <renderId>` | `GET .../compositions/:forkId/renders/:renderId` | poll a render |
 | `vidfarm visibility <forkId> <private\|public>` | `PATCH .../compositions/:forkId/visibility` | set visibility |
 | `vidfarm clone <forkId>` | `POST .../compositions/:forkId/clone` | clone a fork |
@@ -3211,6 +3309,8 @@ What it flags:
 | `layout-template` | error | The frame composed like a **page**: 3+ stacked text blocks in one container ending in a call to action — headline + subheading + CTA, the web hero/modal body. Fires with or without the box around it, because the STACK is the tell. Three stacked lines with no CTA are a legitimate title card and pass |
 | `modal-scrim` | error | A full-frame backdrop that is **blurred AND dimmed** — the website-modal staging that pushes the picture back so a floating block pops. Blur alone passes (the blurred fill behind a 16:9 clip in a 9:16 frame is a real technique); it needs the dimming too, and a bed faded under `opacity:0.25` is an ambient texture wash, not staging, so it passes as well |
 | `gradient-text` | error | `background-clip:text` gradient headline fills |
+| `engine-owned-global` | error | A `<script>` assigns `window.__player` / `__hf` / `__playerReady` / `__renderReady` / `__hyperframes`. **The only rule here that is about correctness, not taste** — assigning one destroys frame capture, and the render still exits 0 with a correct-length MP4 in which nothing moves. Register `window.__timelines["<data-composition-id>"] = gsap.timeline({ paused: true })` instead. Same check runs in `vidfarm lint` (`engine_owned_global_assigned`) and blocks `vidfarm render --target local` |
+| `missing-timeline-registry` | warn | A GSAP/anime timeline is built and never registered on `window.__timelines` — the engine has nothing to seek, so the render is a still image |
 | `clickable-element` | error/warn | `<button>`, `<form>`, `<input>`; `<a href>` warns |
 | `web-framework-classes` | error/warn | Bootstrap/Tailwind class tokens (`btn`, `badge`, `card`, `hero`, `col-*`, `rounded-full`, `shadow-lg`, `backdrop-blur`, `bg-gradient-to-*`) or a linked CSS framework. A `<script>` CDN for GSAP/anime.js is fine |
 | `page-structure` / `bullet-list` | error/warn | `<nav>`/`<header>`/`<footer>`/`<table>`; a `<ul>` with visible bullet markers |