videoclaw 3.0.0-alpha.1 → 3.0.0-alpha.11

package/AGENTS.md

@@ -3,15 +3,21 @@
 ## Agent integration contract (v3)
 
 videoclaw v3 is designed as a target for external agents (Claude Code,
-Codex, Antigravity, Cursor, Warp), not as an orchestrator itself. The
-contract:
+Codex, Antigravity, Cursor, Warp), not as an orchestrator itself.
+
+`docs/AGENT_QUICKSTART.md` is the install-and-first-render path for an agent on
+a new machine. `vclaw schema --json` is the command index and
+`skills/catalog.json` the lane index — read both before improvising.
+
+The contract:
 
 1. **Stdout is JSON when piped.** Pretty-printed when TTY. Progress goes to stderr.
 2. **Exit codes follow a 0/1/2/3 taxonomy** — see `docs/CLI_REFERENCE.md` § Agent-friendly surface.
 3. **Errors carry stable string codes** in their JSON envelope. The catalog: `schemas/video/errors.json`.
 4. **One-call discovery: `vclaw schema --json`** dumps the full contract — commands, flags, artifact schemas, exit codes, error codes.
 5. **Veo (Google Flow) access requires Bun.** `vclaw veo *` subcommands bridge to `bun run vclaw-cli/flow.ts` as a subprocess. Bun must be on PATH (`bun --version` to verify).
-6. **MCP option.** `vclaw mcp serve` exposes read-only project introspection (list_projects, get_project_status, get_artifacts, get_event_log, list_provider_routes) over stdio MCP. Writes still go through the CLI.
+6. **Durable production queue.** `produce --auto-chain`, `pool` and `batch-submit` compile tasks without provider submission. New queued work goes through `cinema-work-quote`, `cinema-authorize`, and `cinema-work`; plain `produce` retains a direct live path. Discover exact flags before invoking either; there is no universal dry-run or spend flag.
+7. **MCP option.** `vclaw mcp serve` exposes read-only project introspection (list_projects, get_project_status, get_artifacts, get_event_log, list_provider_routes) over stdio MCP. Writes still go through the CLI.
 
 If you are an agent author wiring videoclaw into your tool: call
 `vclaw schema --json` once, then drive the CLI deterministically.
@@ -47,13 +53,18 @@ Don't try to do natural-language intent classification inside videoclaw
 - `src/video/` holds the core video workflow modules: artifacts, checkpoints, provider status, workspace helpers, and built-in pipeline manifests.
 - `src/tests/` contains Node test files; compiled tests run from `dist/tests/` after build.
 - `schemas/video/` stores JSON Schema contracts for artifacts and pipeline manifests.
+- `src/video/cinema-*` owns durable production tasks, quotes, authorisations, evidence and reconciliation; `lane-queue.ts` / `lane-coordinator.ts` coordinate provider-account slots.
+- `vclaw-cli/` is the optional Bun Flow sidecar; Python workflow helpers live under `skills/`. `services/shared-lane-coordinator/` is a separately deployed Cloudflare service for shared account slots.
+- `docs/` is canonical for mirrored reference pages; run `npm run docs:sync` after edits. Independently authored `docs-site/guide/` pages need separate updates.
 - `docs/ARCHITECTURE.md` explains the clean-room, video-first design. Treat `dist/` as generated output; edit `src/` instead.
 
 ## Build, Test, and Development Commands
-- `npm install` — install the Node 20+ toolchain.
+- Use Node >=20.10. `npm ci` installs the locked Node dependencies; it does not install Node itself.
+- Contributor verification needs Python 3.12+ in an activated virtual environment, `python -m pip install -r requirements-test.txt`, and FFmpeg/ffprobe. Run `npm run check:test-python` before the suite.
+- Optional Flow commands require Bun >=1.3.5 plus `bun install --cwd vclaw-cli --frozen-lockfile`; local lane coordination requires the `sqlite3` CLI. Package users should follow the optional runtime setup in `docs-site/guide/install.md`.
 - `npm run build` — compile TypeScript to `dist/` and make `dist/cli/vclaw.js` executable.
 - `npm run dev` — run `tsc --watch` for local iteration.
-- `npm test` — full verification: rebuild, then run the Node test suite.
+- `npm test` — lint, module-size check, rebuild, then the Node test suite. This does not run the separate Bun sidecar suite or prove live provider readiness.
 - `npm run test:node` — rerun compiled tests only when `dist/` is already current.
 - Example CLI smoke check: `node dist/cli/vclaw.js video providers`.
 
@@ -71,7 +82,7 @@ Don't try to do natural-language intent classification inside videoclaw
 - Prefer temp-directory-based tests (`mkdtemp`, `tmpdir`) so runs stay isolated and repeatable.
 
 ## Commit & Pull Request Guidelines
-- This repository has no published git history yet; use imperative, scope-aware commits that follow the repo Lore protocol.
+- Use imperative, scope-aware commits that follow the repo Lore protocol and preserve the existing published history.
 - Start with why, then add trailers when useful, such as `Constraint:`, `Confidence:`, `Scope-risk:`, `Tested:`, and `Not-tested:`.
 - PRs should summarize user-visible changes, list verification commands run, link related issues, and include sample CLI output when command behavior changes.
 

package/CLAUDE.md

@@ -2,7 +2,15 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-> **Repository status (2026-05-25):** This is `videoclaw-v3`, the current repo —
+## Quick orientation (read this first, then `MERGE_PLAN.md`)
+
+- **Entrypoint:** `src/cli/vclaw.ts` — a thin ~530-line dispatch shell; all command logic lives in `src/cli/handlers/*.ts` (25 modules).
+- **Domain core:** `src/video/*` — small single-purpose modules (projects, execution, assemble, audio-platform, studio, preview-portal, motion-overlay, provider-platform, …).
+- **Contracts & state:** `schemas/video/*` JSON Schemas are the source of truth for artifact *shapes*; the on-disk `projects/<slug>/` tree is the source of truth for project *state*.
+- **Tests:** `node:test` files in `src/tests/*.test.ts`, run from compiled `dist/tests/` (`npm test`).
+- **Also load:** the sibling `.claude/CLAUDE.md` for the `graphify`, `improvement-run`, and `concierge`/`clawbot` skill triggers.
+
+> **Repository status (2026-07-02):** This is `videoclaw-v3`, the current repo —
 > unified from `videoclaw-v2`, itself the merged successor of the older `videoclaw`
 > package and the clean-room `vclaw-video-core` rebuild. (The
 > npm package is `videoclaw`; "videoclaw-v3" is just the repo name.) Foundation
@@ -30,6 +38,101 @@ first message is just a greeting with no task, offer the concierge menu.
 Engineering and maintenance requests on this codebase itself are NOT concierge
 territory — handle those normally.
 
+## Working discipline — ground in what already exists before you build (READ THIS FIRST)
+
+This project keeps getting bitten by the same failure: **improvising a fresh
+(worse) approach instead of reusing the proven artifact that already exists**, and
+silently dropping load-bearing pieces between turns.
+
+**The honest root cause is a default to fast *visible* output** — a clip, an HTML,
+a keyframe, a render — **over a provably-correct setup.** A fast wrong render is
+slower than a slow right one: it burns spend, trust, and rework. The rules below
+are forcing functions against that default; the friction IS the point. The
+highest-leverage rules are **0, 1, and 4** — do them even when it feels slower.
+
+Before authoring or changing **any** skill, procedure, function, prompt, render
+setup, or review surface — and before creating a new command — work through this:
+
+0. **Read the spec in full, once, up front — and write the contract down.** When
+   the user points to an authoritative method file (a doc, `WORKFLOW.md`, a
+   compliance sheet, a working harness script, a `--validate`d prompt), read the
+   WHOLE thing first and extract its requirements into a written checklist/contract
+   (a file or notepad) BEFORE building. Do NOT skim it on demand and discover the
+   pieces one correction at a time — that is exactly what makes the operator repeat
+   himself. For any multi-step build/production, keep that contract on disk and
+   **re-read it each turn**; requirements held only in working memory erode over a
+   long session. The on-disk contract, not your memory, is what you build against.
+1. **Inventory before you build (the #1 rule).** Search first. Grep/read the
+   relevant `src/video/*`, `src/cli/handlers/*`, `skills/*`, `docs/*`, the
+   project's on-disk `artifacts/*` (e.g. `show-bible.json`, `voice-clones.json`,
+   `story-bible`, `flow-characters.json`, `seedance-assets.json`), and any
+   `references/` assets, proven harness scripts, or already-`--validate`d prompts.
+   If a working artifact exists, **use it** — never regenerate an ad-hoc
+   substitute. Most "why did this break again" pain is re-deriving something that
+   was already solved and written down.
+2. **Artifacts/registries are the source of truth, not memory.** Drive work from
+   the on-disk artifacts (the `show-bible` registry, voice clones, reference
+   sheets, validated prompt files) — not from paths or prompts re-typed from
+   memory. If you catch yourself re-typing a file path or re-authoring a prompt
+   that already exists, stop and load it from the artifact.
+3. **Prompting is per-model — never reuse one prompt style across routes.**
+   Seedance/Runway/Dreamina lock identity from **references + a rich per-subject
+   visual descriptor** (never a generic "the man") + the multi-shot framework, and
+   take character-sheet + location + per-speaker voice refs. Flow (`veo-useapi`)
+   locks identity on a **registered Flow Character** and tolerates generic
+   prompts. Image models (GB, `openai-gpt-image-2`) differ again. Check the
+   route's ruleset (and any model-specific prompting skill/doc) before authoring a
+   prompt or choosing references.
+4. **Encode the method so the TOOL enforces it — don't rely on remembering.**
+   When a procedure has required inputs/steps, add a fail-fast preflight/readiness
+   gate that ERRORS (non-zero, clear blocker) when a required piece is missing, and
+   prefer **registry-driven auto-attach** over manual setup. The target shape: an
+   operator just prompts; the tool attaches the right inputs and refuses to render
+   wrong (see `show-preflight` + show-bible auto-attach).
+5. **Review-first, one-at-a-time for any spend.** Before any paid or slow
+   generation, emit the exact **contract** — the prompt + the references + the JSON
+   that will actually be submitted — for review (the review portal IS the
+   contract; show the EXACT submit payload, not a paraphrase). Then render ONE
+   unit, verify it (extract a frame + whisper the audio / QC), get approval, and
+   only then the next. Never batch-spend on an unreviewed setup. **Immediately
+   before submitting, dry-run `buildExecutionPayload` and confirm the resolved
+   refs/prompt/route match the approved contract** — the actual submission has
+   silently diverged before (an `@tag` hijacked the references and dropped the
+   approved sheets/location). If it doesn't match the contract, do not submit.
+6. **New command/skill = conventions below + steps 1 & 4.** Still do the full
+   registration (handler + `vclaw.ts` dispatch + `cli-schema.ts` `COMMANDS` entry +
+   bump the `cli-schema.test.ts` count + a `cli-*.test.ts` + README/CLI_REFERENCE +
+   a schema for any new artifact), but **inventory first** (step 1) and add a
+   **preflight gate** (step 4) if it has required inputs.
+7. **Verify OUTCOMES, not that a command ran — and never report unverified
+   progress.** "Launched a driver" / "submitted" is NOT "it's working." After any
+   submit or render, confirm the real provider-side state before claiming it: a
+   live job exists (`execute-status` → `live-submitted` + a candidate + a
+   `.vclaw-jobs/*.json` file), and then the actual output downloaded + QC'd (frame
+   + whisper). If you tell the user something is happening, prove it (a job id /
+   status / a frame) — do not assert progress you have not checked.
+
+   **QC the whole clip, not one frame.** A single mid-frame grab is not
+   verification: it passed 8 clips whose defect (extra figures walking in from the
+   frame edges) only began around the four-second mark, and the operator found it
+   on screen after delivery. Use `vclaw video clip-qc`, or a filmstrip —
+   `ffmpeg -i clip.mp4 -vf "fps=1,scale=200:-1,tile=8x1" strip.jpg` renders every
+   second in one pass. `consistency-audit` (one mid-frame, identity) and
+   `motion-qc` (nine frames, morph/vanish) are advisory and never block, so read
+   their findings rather than treating silence as clean.
+
+   **Re-render corollary — deleting the clip does NOT force a re-render.** The
+   resumable drivers resume from the **scene-selection artifact**, never from
+   disk, so a changed prompt plus a deleted `outputs/scene-N.mp4` yields
+   `skipped, attempts=0` and no provider call at all. Clear the selection with
+   `vclaw video reroll-scene --project <slug> --scene <i> --void` (it voids all
+   four stores atomically). After any re-render read the **per-scene statuses**,
+   not the file count — a silent no-op looks exactly like success from the
+   outside.
+
+When in doubt, the on-disk project and its artifacts win over anything you
+remember.
+
 ## Build, test, and smoke commands
 
 ```bash
@@ -37,15 +140,22 @@ npm install                              # Node 20+
 npm run build                            # clean dist/, tsc, chmod +x the CLI bins
 npm run dev                              # tsc --watch
 npm test                                 # rebuild, then node --test dist/tests/*.test.js
-npm run test:node                        # rerun compiled tests without rebuilding (serial: --test-concurrency=1)
+npm run test:node                        # rerun compiled tests without rebuilding (serial by default; VCLAW_TEST_CONCURRENCY=4 saturates a 4-core box — CI additionally splits it with `--shard i/4` across four runners, see .github/workflows/ci.yml)
 ```
 
-Run a single test file after `npm run build` (or `npm run dev`):
+Run a subset after `npm run build` (or `npm run dev`) — the arg is a filename
+substring:
 
 ```bash
-node --test dist/tests/cli-full-flow.test.js
+npm run test:node -- cli-full-flow
 ```
 
+Prefer this over a bare `node --test dist/tests/...`. The runner points `python3`
+at the interpreter `check:test-python` pins; invoking `node --test` directly runs
+the suite's ~114 Python call sites on whatever `python3` PATH happens to give,
+which is how a drifted Pillow once passed the gate and silently changed
+title-card rendering.
+
 End-to-end smokes (each runs `npm run build` first) and local guardrails:
 
 ```bash
@@ -60,6 +170,7 @@ npm run smoke:story-bible-image          # story-bible image-only path
 npm run smoke:assemble                   # FFmpeg assemble/stitch layer (dry)
 npm run smoke:assemble-render            # real FFmpeg render validation
 npm run smoke:multi-shot                 # multi-shot prompt plan→validate round-trip
+npm run smoke:rap-dryrun                 # rap lane: a solo and a duet film built from nothing reach qc (no renders, no spend; needs ffmpeg-full, macOS say)
 npm run e2e:image-storyboard             # image-storyboard workflow (runs --verify-server)
 npm run e2e:image-storyboard:examples    # image-storyboard e2e against the bundled examples
 npm run check:movie-director-wrappers    # bundled Director helper scripts
@@ -68,6 +179,7 @@ npm run check:skill-frontdoor            # repo-local skill front door
 npm run check:artifact-schema-coverage   # writers vs schemas drift (advisory)
 npm run check:artifact-schema-coverage:strict  # same, but fails the build on drift (--strict)
 npm run check:release-readiness-lite     # one-shot: build + tests + main smokes + guardrails
+npm run docs:sync                        # regenerate docs-site/reference/ from docs/ — run after ANY docs/*.md edit (CI: check:docs-site)
 npm run graph:full                       # rebuild the graphify knowledge graph (graphify-out/)
 ```
 
@@ -77,7 +189,7 @@ npm run graph:full                       # rebuild the graphify knowledge graph
 
 ### Layers (read top-down)
 
-1. `src/cli/vclaw.ts` — the single user-facing entrypoint, now a thin dispatch shell (~480 lines: imports, `printHelp`, the `NOUN_VERB_ALIASES` map, `resolveSubcommand`, the `VIDEO_DISPATCH` table, and `main`). The decomposition is COMPLETE (PRs #89–#120): pure arg/slug/spend helpers live in `src/cli/args.ts`, and ALL command handlers live in `src/cli/handlers/` (22 modules — `analysis`, `audio`, `batch`, `candidates`, `character`, `clone`, `create`, `execution`, `library`, `media-ops`, `media-production`, `motion-overlay`, `multi-shot`, `project-ops`, `prompt-craft`, `provider-registration`, `reference-sheets`, `reporting`, `review-portal`, `stages`, `studio`, `templates`), each a verbatim extraction with module-private helpers and only dispatch-facing handlers exported. ⚠️ When moving handler code, watch for position-sensitive path math (`import.meta.url` etc.) — the compiled location changes (see the documented adaptations in `handlers/studio.ts` and `handlers/motion-overlay.ts`). `src/cli/provider-adapter.ts` is the built-in adapter binary for `seedance-direct`.
+1. `src/cli/vclaw.ts` — the single user-facing entrypoint, now a thin dispatch shell (~530 lines: imports, `printHelp`, the `NOUN_VERB_ALIASES` map, `resolveSubcommand`, the `VIDEO_DISPATCH` table, and `main`). The decomposition is COMPLETE (PRs #89–#120): pure arg/slug/spend helpers live in `src/cli/args.ts`, and ALL command handlers live in `src/cli/handlers/` (25 modules — `analysis`, `audio`, `batch`, `candidates`, `character`, `clone`, `create`, `execution`, `library`, `media-ops`, `media-production`, `migrate-home`, `monitor`, `motion-overlay`, `multi-shot`, `project-ops`, `prompt-craft`, `provider-registration`, `reference-sheets`, `reporting`, `review-portal`, `show`, `stages`, `studio`, `templates`), each a verbatim extraction with module-private helpers and only dispatch-facing handlers exported. ⚠️ When moving handler code, watch for position-sensitive path math (`import.meta.url` etc.) — the compiled location changes (see the documented adaptations in `handlers/studio.ts` and `handlers/motion-overlay.ts`). `src/cli/provider-adapter.ts` is the built-in adapter binary for the four `..._ADAPTER` routes (see Provider routes below). Besides `video`/`studio`, `main` also dispatches two smaller families: `vclaw mcp serve` (`src/mcp/` — a read-only stdio MCP server exposing `list_projects`, `get_project_status`, `get_artifacts`, `get_event_log`, `list_provider_routes`; writes stay CLI-only by design) and `vclaw veo <verb>` (`src/video/veo-subprocess.ts` — spawn-forwarding to the Bun-based `vclaw-cli/flow.ts`, required for Puppeteer/Google Flow verbs like `status`, `resume`, `cancel`, `useapi:*`).
 2. `src/video/` — the core domain. Each file is small and single-purpose, e.g. `artifacts.ts`, `artifact-store.ts`, `checkpoints.ts`, `workspace.ts`, `projects.ts`, `status.ts`, `doctor.ts`, `doctor-portfolio.ts`, `readiness.ts`, `execution-plan.ts`, `execute.ts`, `execution-runtime.ts`, `execution-status.ts`, `execution-cancel.ts`, `director-preflight.ts`, `report.ts`, `csv-export.ts`, `obsidian-export.ts`, `project-index.ts`, `metrics.ts`, `next-actions.ts`, `template-store.ts`, `provider-status.ts`, `native-seedance.ts`, `native-veo.ts`, `multi-shot-prompt.ts`, `storyboard-grid.ts`, `cinematography.ts` (detail-leveled quantified camera/lighting/grade/audio emitters — `--detail terse|standard|rich`), `prompt-rules.ts` (standing prompt rules: visual-descriptor-not-names, brand-neutral, no-face-morph, diegetic audio), `seedance-asset-library.ts` (Asset Library character/product consistency), `story-bible.ts` (deterministic continuity bible — cast/settings/props/scene-timeline from brief + storyboard + characters), `brand-definition.ts` (locked brand system — palette/voice/typography/theme map; `filmmaking-prompts` appends a prose BRAND line when present), `assemble/media-qc.ts` (post-stitch ffprobe QC of clips + master), `assemble/narration-fit.ts` (TTS-vs-video timing planner: atempo / loop-video fit). `src/video/studio/` is the planning front door and `src/video/preview-portal/` is the review/delivery portal (both described below).
 3. `src/video/provider-platform/` — route descriptors (Veo / Seedance / Runway direct and useapi flavors).
 4. `src/video/pipeline-manifests/` — built-in stage definitions for the two production modes.
@@ -87,7 +199,7 @@ npm run graph:full                       # rebuild the graphify knowledge graph
 
 ### Project lifecycle (per project, on disk)
 
-After `vclaw video init <slug>`, a project lives at `projects/<slug>/` under the workspace root and is the unit of everything else:
+After `vclaw video init <slug>`, a project lives at `projects/<slug>/` under the workspace root and is the unit of everything else. **The workspace root is the ONE canonical home `~/videoclaw`** (`CANONICAL_WORKSPACE_ROOT` in `src/video/workspace-root.ts`), resolved as `--root` flag → `VCLAW_WORKSPACE` → `VIDEOCLAW_WORKSPACE` → `~/videoclaw` — this replaced the old per-invocation `process.cwd()` default that scattered projects wherever `vclaw` happened to run. `vclaw video migrate-home` consolidates scattered projects into the home (dry-run plan by default; `--confirm` moves each project and leaves a symlink at the old path so old absolute paths still resolve).
 
 ```
 projects/<slug>/
@@ -103,7 +215,9 @@ projects/<slug>/
 
 Canonical stage order: **init → brief → storyboard → assets → review → publish**. `readiness`, `plan`/`execution-plan`, `produce`/`execute`, `execute-status`, `execute-cancel` are the runtime-execution layer that sits between assets and review.
 
-`produce`/`execute --auto-chain` (`src/video/execute-autochain.ts`, `runAutoChain`) is the whole-storyboard driver over the existing dormant chain-from-prev engine: it renders scenes sequentially, auto-selects each produced candidate (from `report.candidatesByScene`), sets `chainFromPrev` for every scene after the first, and bundles `continuityFeedback` — so each scene seeds from the previous scene's output video with zero manual `reroll-scene`. The engine itself (seed resolution, `referenceRole='keyframe'`, reference budget) is unchanged; the one supporting change is that a seedance scene now keeps BOTH its character `Asset://` identity refs AND the keyframe video, via the pure `resolveSceneReferencePaths` in `execution-runtime.ts` (formerly an either/or that dropped the chain seed when characters were locked). It is resumable (skips already-selected scenes) and fail-fast (`stoppedAt` on the first barren scene). Default-off → byte-identical to today. Because `executeProject` on async routes (e.g. `seedance-direct`) is SUBMIT-ONLY, the default per-scene runner calls `waitForSceneVideo` (loops `refreshExecutionStatus` until the scene's candidate gains a video output) BEFORE selecting + chaining — otherwise the next scene's chain seed resolves to a still-rendering, video-less candidate and `chain-from-prev-source-missing` fires. Injected test runners simulate completed renders and skip the poll.
+`produce`/`execute --auto-chain` and `vclaw video pool` are **durable-queue compilers, not renderers** (since the cinema queue landed, PRs #360/#364). `--auto-chain` compiles the storyboard into `artifacts/cinema/production-queue.json` as a dependency chain (each scene's task seeds from its predecessor's *selected* candidate; `cinema-chain-fallback.ts` carries the image-only fallback policy per link), `pool` enqueues the pending scenes as independent tasks, and both return `{ enqueued, pendingScenes, providerCalls: 0, spendAuthorized: false }` without touching a provider. `--execute`, `--dry-run` and `--confirm-spend` are refused on both (`--execute` is retired). The queue drains one task at a time through `vclaw video cinema-work --task <id>` (`src/cli/handlers/cinema-execution.ts`): a task compiled for any paid route — which includes `veo-useapi` even when the model is the 0-credit `veo-3.1-lite-low-priority` — is `authorizationRequirement: 'exact-quote'` and needs a bound authorization + repeated quote hash + `--confirm-spend` + a fresh quote-adapter observation; only `runway-useapi` explore mode is a provider-free submission (`--confirm-provider-call`). The chain-from-prev engine underneath is unchanged: `resolveSceneReferencePaths` (`execution-runtime.ts`) keeps BOTH a seedance scene's character `Asset://` refs AND the keyframe video, and `execute-autochain.ts` keeps `waitForSceneVideo` / `resolveInFlightScene` for the submit-only async routes (a chain seed must be a candidate that already HAS a video, or `chain-from-prev-source-missing` fires). Continuation advisories (`continuation-handoff.ts`, `analyzeChainContinuity`) still flag chain-depth drift.
+
+`vclaw video render-scenes` (`execute-render-scenes.ts`, `runRenderScenes`) is the one scene driver that still renders **directly** (a PURE scheduler + an injectable per-scene runner, offline-testable): sequential, walking a per-scene **fallback route ladder** — try route A, escalate to B then C on provider rejection, first success wins — and spend-gated by `--confirm-spend`. Plain `produce` (no `--auto-chain`) also still submits directly and re-submits a scene whose clip was deleted; the "resumes from the scene-selection artifact, so deleting the clip is a silent no-op" trap in the working-discipline rules applies to the queue-driven paths, where `reroll-scene --void` is what clears a selection.
 
 ### Two production modes
 
@@ -127,14 +241,20 @@ The ops layer tracks a normalized `storyboardReviewState` of `missing | current
 
 The portal generates the standardized HTML surfaces that used to be hand-written per project: `edit.html`/`review.html` (editor/operator human-in-the-loop, with approve/regenerate controls and `VIDEOCLAW_REVIEW_DECISIONS` copy output), `client-review.html` (lightweight client approve/decline/comment, `VIDEOCLAW_CLIENT_FEEDBACK` copy output), and `preview.html` (polished final showcase: every production image is lightbox-enabled for click-to-fullscreen, a soundtrack `<audio controls preload="none">` player renders when a soundtrack is discovered, plus downloads). The module is split into `discovery.ts` (find project assets), `generate.ts` + `templates.ts` + `shared-assets.ts` (render the surfaces), `render.ts`/`publish.ts` (emit/ship), and `audit.ts` (drift checks); `src/video/review-ui.ts` (`vclaw video review-ui`) serves the editor surface interactively. The decisions/feedback flow back through env-var copy blocks rather than a server round-trip, keeping the on-disk project the source of truth. See `docs/preview-portal-audit.md`.
 
+### Mission Control (`vclaw video monitor`)
+
+`src/video/monitor/` serves a read-only localhost cockpit (default port 8765): `monitor/discovery.ts` discovers every project across workspace roots (`--root` adds extra roots to scan) and the server renders a live overview from the on-disk artifacts. Never calls a provider, never spends.
+
 ### Storyboard grid & multi-shot prompt handoff
 
-`src/video/multi-shot-prompt.ts` builds project-ready, provider-tuned multi-shot prompt packets (presets via `vclaw video multi-shot --presets`; see `references/video/multi-shot-framework.md`, especially its Anti-patterns section). `multi-shot --plan` can render through alternate composers via `--format default|seedance-paragraph|per-shot` (default = the original `{ preset, shots[] }` JSON, unchanged) and wrap the rendered text bilingually via `--lang en|zh|en+zh` (offline identity translator — the flag surfaces the two-block `en+zh` structure, not live translation); `--category <id>` drives the composed prose. On a non-`default` `--format`, `--hook <patternId>` (named `HOOK_PATTERNS` opening directive from `cinematography.ts`) prepends an `Opening hook — ...` line and `--dialogue "<speaker>: <line> [|| <speaker>: <line>]"` appends spoken dialogue to the opening via `withDialogue` — both are post-render text transforms (composers stay pure), default off / unchanged output. `--dialogue` parses a trailing `[emotion]` per speaker, and `--emotion-cues` rewrites those named emotions into physical-cue descriptors (`rewriteEmotionAsPhysical`/`EMOTION_PHYSICAL_CUE_MAP` in `emotion-cues.ts`) — advisory/additive, extremes left named, default off / byte-identical. `filmmaking-prompts --phase storyboard|video` gates the heavy video `seedancePackets` to `[]` in the `storyboard` phase (lock-the-grid step) while keeping the storyboard/camera-language portion. Joey cinematic-adaptation opt-in flags (all additive — omit = byte-identical legacy output) route through these same commands: `filmmaking-prompts` takes `--sheet 8-shot|6-panel` (`characterSheetSixPanelPrompt`), `--realism`/`--wet`/`--haze thin|light|heavy` (the `captureRealismBlock` keystone + `volumetricHaze`, at `--detail rich`), `--background mid-gray|white|black` (`backgroundPlate`), and `--lighting <id>`/`--grade <id>` (rich cinematography-suffix registers, e.g. `night-fire`/`bleach-bypass`); `multi-shot` takes `--genre <id>` (`resolveStyleLine`, Nolan fallback). Operator trigger-word map: mid-gray → `backgroundPlate`; haze → `volumetricHaze`; anti-plastic → `captureRealismBlock`; wet → moisture clause; bleach-bypass/lifted-blacks → lift/gamma grade; no-on-screen-text → Last Frame suppression. See `docs/CLI_REFERENCE.md` ("Joey cinematic opt-in flags") and the framework Anti-patterns.
+`src/video/multi-shot-prompt.ts` builds project-ready, provider-tuned multi-shot prompt packets (presets via `vclaw video multi-shot --presets`; see `references/video/multi-shot-framework.md`, especially its Anti-patterns section). `multi-shot --plan` can render through alternate composers via `--format default|seedance-paragraph|per-shot` (default = the original `{ preset, shots[] }` JSON, unchanged) and wrap the rendered text bilingually via `--lang en|zh|en+zh` (offline identity translator — the flag surfaces the two-block `en+zh` structure, not live translation); `--category <id>` drives the composed prose. On a non-`default` `--format`, `--hook <patternId>` (named `HOOK_PATTERNS` opening directive from `cinematography.ts`) prepends an `Opening hook — ...` line and `--dialogue "<speaker>: <line> [|| <speaker>: <line>]"` appends spoken dialogue to the opening via `withDialogue` — both are post-render text transforms (composers stay pure), default off / unchanged output. `--dialogue` parses a trailing `[emotion]` per speaker, and `--emotion-cues` rewrites those named emotions into physical-cue descriptors (`rewriteEmotionAsPhysical`/`EMOTION_PHYSICAL_CUE_MAP` in `emotion-cues.ts`) — advisory/additive, extremes left named, default off / byte-identical. `filmmaking-prompts --phase storyboard|video` gates the heavy video `seedancePackets` to `[]` in the `storyboard` phase (lock-the-grid step) while keeping the storyboard/camera-language portion. Joey cinematic-adaptation opt-in flags (all additive — omit = byte-identical legacy output) route through these same commands: `filmmaking-prompts` takes `--sheet 8-shot|6-panel` (`characterSheetSixPanelPrompt`), `--realism`/`--wet`/`--haze thin|light|heavy` (the `captureRealismBlock` keystone + `volumetricHaze`, at `--detail rich`), `--background mid-gray|white|black` (`backgroundPlate`), and `--lighting <id>`/`--grade <id>` (rich cinematography-suffix registers, e.g. `night-fire`/`bleach-bypass`); `multi-shot` takes `--genre <id>` (`resolveStyleLine`, Nolan fallback) and `--vfx <id>` (physical-VFX effects register, `src/video/vfx-register.ts`). Operator trigger-word map: mid-gray → `backgroundPlate`; haze → `volumetricHaze`; anti-plastic → `captureRealismBlock`; wet → moisture clause; bleach-bypass/lifted-blacks → lift/gamma grade; no-on-screen-text → `noOnScreenTextBlock`, the FIRST directive block (it moved out of Last Frame: overlay text is decided early in the frame, so the instruction has to sit early in the prompt). See `docs/CLI_REFERENCE.md` ("Joey cinematic opt-in flags") and the framework Anti-patterns.
 
 `src/video/storyboard-grid.ts` (`vclaw video storyboard-grid`, `renderStoryboardGrid`) renders a **deterministic shot-spec sheet** — a 3×3 SVG→PNG of CAM/MOVE/MOOD annotation panels — **not** a cinematic storyboard with character imagery. It is the *layout/intent contract*, not the finished reference image. The intended two-step is: (1) `storyboard-grid` to lock panel order + camera language, then (2) generate the real cinematic 3×3 grid via an image model (always `openai-gpt-image-2` for multi-panel composites) and re-attach it with `vclaw video filmmaking-prompts --storyboard-grid <path>`, which feeds it into the Seedance/Veo/Runway prompt packets.
 
 Two production-learned gotchas baked into the generated packets (see the framework Anti-patterns): (a) grids passed as provider `reference_images` get **reproduced as a moving 9-panel split-screen** unless the prompt explicitly forces single-full-frame output — the packets now embed that guard; (b) real-person content filters (xskill/ARK Seedance) reject photoreal faces as `reference_images`, so use `filmmaking-prompts --no-faces` to render the grid prompt in a silhouette / no-face register.
 
+`vclaw video prompt-lint` (`src/video/prompt-lint.ts`, pure/deterministic — the handler does the I/O) lints a filmmaking-prompts artifact BEFORE spend: Seedance 13-block order, the 280–1000-words-per-packet window, brand/proper-name scrub leaks, the single-full-frame grid guard whenever a storyboard-grid reference is attached, NO ON-SCREEN TEXT / CAPTURE CADENCE / SUBJECT LOCK / CAPTURE REALISM / CAMERA CAPTURE presence on video packets, grid-panel annotation style (advisory), the character-identity word budget (30–60 words target, >100 hard failure), and two newer advisories: the reference-transfer contract and allocation-model over-allocation. `--checklist` prints the route checklist. `vclaw video cinema-profile` persists per-project cinematography defaults onto the project manifest (`updateProjectManifestCinemaProfile` in `workspace.ts`) so the prompt/packet layer picks them up without re-typing flags. `vclaw video diagnose` (`src/video/output-diagnosis.ts`) is the companion for AFTER a render: an output-quality troubleshoot tree — `--symptom <text>` matches an observed defect to causes + fixes, `--retry-pattern` prints the conservative retry pattern.
+
 ### Provider routes and adapters
 
 Live execution calls route-specific adapters. A custom adapter is set via one of:
@@ -148,12 +268,20 @@ VCLAW_DREAMINA_USEAPI_ADAPTER
 
 Adapters receive JSON on stdin and must return JSON on stdout (`externalJobId` for submit, `pending|completed|failed` for poll).
 
+**One declaration per route.** What a route NEEDS — required env vars, runtime dependencies, maturity, its `..._ADAPTER` and `..._SUBMIT_CMD` env var names, and declared membership of the specialist lanes (`batch-queue.ts`'s batch routes, `execution-runtime.ts`'s `VOICE_REF_ROUTES`) — lives once in `src/video/provider-platform/route-prerequisites.ts`; `provider-status.ts` reads it instead of keeping five parallel tables, and the lane consumers derive their subsets from the declared flags. `src/video/capability-contract.ts` composes it with `ROUTE_CAPABILITIES`, the Cinema route registry, the audio backend registries and `FINISH_BACKEND_IDS` into one pure `CapabilityManifest`. Adding a route means editing the id tuple plus `route-prerequisites.ts` — `src/tests/capability-contract.test.ts` FAILS when any consumer, the MCP `list_provider_routes` description, or a fenced table in `docs/CAPABILITIES.md` / `docs/PROVIDER_PLATFORM.md` drifts from it. Do not merge the core and Cinema route id spaces (ADR 0001).
+
 For `seedance-direct`, `veo-useapi`, `runway-useapi`, and `dreamina-useapi`, `vclaw` ships a built-in adapter binary (`dist/cli/provider-adapter.js`) used automatically unless the full `..._ADAPTER` override is set. The built-in adapters read route-specific `..._SUBMIT_CMD` / `..._POLL_CMD` / `..._CANCEL_CMD` command shims. Routes also have native in-process transports: `native-seedance.ts` (uses `SUTUI_API_KEY`), `native-veo.ts` (drives the local `vclaw-cli` Bun package), `native-runway.ts` (pure Node fetch + fs, UseAPI bearer auth), `native-dreamina.ts` (pure Node fetch + fs, UseAPI bearer auth).
 
-**`dreamina-useapi` = Seedance 2.0 / Dreamina via useapi.net.** Dreamina (CapCut/ByteDance Seed) exposes `seedance-2.0` / `seedance-2.0-fast` (and Sora 2) through useapi.net; CA-region accounts unlock 1080p Seedance 2.0. `native-dreamina.ts` reuses the **same `USEAPI_API_TOKEN`** as runway-useapi (no new token) and reads the account from `VCLAW_DREAMINA_ACCOUNT` (e.g. `CA:ai@example.com`), region from `VCLAW_DREAMINA_REGION` (default `CA`), and model from `VCLAW_DREAMINA_MODEL` (default `seedance-2.0`); the route adapter override is `VCLAW_DREAMINA_USEAPI_ADAPTER`. The account is registered server-side out-of-band (`POST /accounts` with `{email,password,region,maxJobs}`), so submit only needs the account id + token. For image-to-video, the first image reference is uploaded via `POST /dreamina/assets/<account>` to obtain an `assetRef`, which is passed as `firstFrameRef` on `POST /dreamina/videos` (first_frame mode auto-detects aspect ratio from the image); poll uses `GET /dreamina/videos/<jobid>` (`status: created → completed|failed`) and downloads `response.videoUrl`. Like runway-useapi, real human faces are rejected by Seedance moderation — describe stylized characters by visual descriptor.
+**`dreamina-useapi` = Seedance 2.0 / Dreamina via useapi.net.** Dreamina (CapCut/ByteDance Seed) exposes the Seedance family (`seedance-2.0` default, `-2.0-fast`, `-2.0-mini`, `-1.5-pro`, `-1.0-pro`, `-1.0-mini`, `-1.0-fast`) and `sora2` through useapi.net; CA-region accounts unlock 1080p Seedance 2.0 (and 4k on `seedance-2.0` as of 2026-06-26 — opted into route-locally via `VCLAW_DREAMINA_RESOLUTION=4k`, since the shared execution profile only expresses 720p/1080p; the transport clamps 4k→1080p on non-seedance-2.0 models and →720p on the 720p-only ones). `-2.0-fast`/`-2.0-mini`/`sora2` are 720p-only. `native-dreamina.ts` reuses the **same `USEAPI_API_TOKEN`** as runway-useapi (no new token) and reads the account from `VCLAW_DREAMINA_ACCOUNT` (e.g. `CA:ai@example.com`), region from `VCLAW_DREAMINA_REGION` (default `CA`), and model from `VCLAW_DREAMINA_MODEL` (default `seedance-2.0`); the route adapter override is `VCLAW_DREAMINA_USEAPI_ADAPTER`. The account is registered server-side out-of-band (`POST /accounts` with `{email,password,region,maxJobs}`), so submit only needs the account id + token. For image-to-video, the first image reference is uploaded via `POST /dreamina/assets/<account>` to obtain an `assetRef`, which is passed as `firstFrameRef` on `POST /dreamina/videos` (first_frame mode auto-detects aspect ratio from the image); a scene's `endKeyframePath` (the same field the runway route uses) uploads a second frame passed as `endFrameRef` alongside `firstFrameRef` → **end_frame mode**, where the clip animates first→end (two stills → one continuous shot); poll uses `GET /dreamina/videos/<jobid>` (`status: created → completed|failed`) and downloads `response.videoUrl`. Like runway-useapi, real human faces are rejected by Seedance moderation — describe stylized characters by visual descriptor.
 
 **Seedance character consistency = the Asset Library, not raw URLs.** `ark/seedance-2.0` (the official Volcengine Ark Seedance 2.0, Standard = 1080p) locks character identity via managed **Asset Library avatars** (`Asset://` URIs), NOT raw photoreal image URLs (those trip the "real person" content filter and don't lock identity). `src/video/seedance-asset-library.ts` (`vclaw video seedance-register-assets`) registers character images as Assets, waits for international-profile sync, and writes `artifacts/seedance-assets.json` (canonical schema `schemas/video/artifacts/seedance-assets.schema.json`; shape `{ schemaVersion, projectSlug, groupName, generatedAt, assets:[{name, assetId, assetUri, intlAssetUri}] }`); `readSeedanceAssets(workspaceRoot, slug)` reads it back into a name→`Asset://`-URI map (graceful when absent). On the `seedance-direct` route only, `buildExecutionPayload` (`execution-runtime.ts`) auto-resolves each scene's `referencePaths` from that artifact by matching `scene.characters` names → their `Asset://` URIs (a project without the artifact behaves as before); `native-seedance.ts`'s `seedanceReferenceParams` then routes `Asset://` references into `reference_images`. References are capped at ≤9 image / ≤3 video / ≤3 audio per submission via `assertReferenceBudget`, preflighted across the whole payload in `submitSeedanceDirectNative` before any submit (fail-fast, no partial submission). Describe characters by visual descriptor (not proper names) in prompts — names don't survive across generations. (Validated 2026-05-29 against the same Ark endpoint the user's production project uses.) `@Name` tags in scene prompts (`resolveAssetTags` in `prompt-rules.ts`, lookup via `asset-tag-lookup.ts` `buildAssetTagLookup`) resolve at `buildExecutionPayload` time to the character's visual descriptor (text) + its saved reference (`Asset://`/image), merged through `resolveSceneReferencePaths`; unresolved tags strip the `@` and warn (never fatal), `@imageN` positional bindings are reserved, and it runs before `stripProperNames`. `@location` tags resolve via locked environment plates: `vclaw video environment-auto-create` (`src/video/environment-auto-create.ts`, mirrors `character-auto-create`) generates seamless no-people location plates and writes `artifacts/environment-assets.json` (own schema, like seedance-assets); `readEnvironmentAssets` (`environment-assets.ts`) feeds `buildAssetTagLookup`'s `environmentsByName` so `@tokyo-alley` resolves to the plate descriptor + ref (absent → graceful no-op).
 
+**Flow identity is registered, not referenced.** The Flow-side counterpart of `seedance-register-assets`: `vclaw video flow-register-characters` / `flow-register-voices` (`src/video/flow-character-library.ts`, handlers in `provider-registration.ts`) register reusable Google Flow Characters/Voices via useapi and write `artifacts/flow-characters.json` / `flow-voices.json` (needs `USEAPI_API_TOKEN` + `USEAPI_ACCOUNT_EMAIL`). `vclaw video flow-r2v` (`src/video/native-flow-r2v.ts`) then submits reference-to-video against those registrations, running `applyR2vPromptHygiene` over the prompt first. This is what working-discipline rule 3 means by "locks identity on a registered Flow Character".
+
+### Cartoon-show layer (show-bible → show-preflight → voice clones)
+
+The repeatable cartoon-SHOW production system (from the Jack-Vs-AI workflow). `vclaw video show-bible` (`src/cli/handlers/show.ts`) is the show's asset-library index: it ties the project's characters + locations (environment plates) + voice clones into one reusable world and tracks the episode list — plan/derive by default, deterministic, no provider calls. `vclaw video show-preflight` (`src/video/show-preflight.ts`, `buildShowPreflight`) is the fail-fast, **route-aware** readiness gate that working-discipline rule 4 points at: given the show-bible + storyboard, it verifies every cast/speaking subject in every scene has what the CHOSEN route actually needs — Seedance-family routes (`seedance-direct`/`runway-useapi`/`dreamina-useapi`) require a resolvable character sheet per cast member (on `seedance-direct` it must additionally be a registered Asset Library avatar — a raw portrait trips the real-person filter), a location plate per scene, and a bound, resolvable voice clip per speaking character, with subjects described by full visual descriptor (never a bare generic noun); Flow (`veo-useapi`) requires a registered Flow Character per cast member (registration is out-of-band via `flow-characters.json`, so the gate enforces — it never fabricates). `vclaw video voice-clone` (`src/video/voice-clone.ts`) implements the production-learned voice lock: a raw MP3/WAV voice reference DRIFTS to a generic accent, but the same audio as the track of a **black-frame video** locks it — the command builds that black-frame+audio MP4 (shared `runFfmpeg`) and persists reusable voice-clone assets in `artifacts/voice-clones.json` (mirroring the seedance-assets/environment-assets pattern), bindable to characters.
+
 ### Overnight batch queue
 
 `src/video/batch-queue.ts` + the `vclaw video batch-submit` / `batch-monitor` / `batch-status` commands queue many independent video jobs to run unattended overnight. The default route is the **free** `runway-useapi` explore mode (low-res, slow — backfill drafts); target `dreamina-useapi` (or `seedance-direct`) for paid hi-res. An operator-authored manifest (`schemas/video/artifacts/batch-queue-manifest.schema.json` — an input-only artifact, allowlisted in `check-artifact-schema-coverage.mjs`) compiles via the pure `buildBatchPayload()` into a single `VideoExecutionPayload` with N tasks, so it reuses the existing native route transports (`native-runway`/`native-dreamina`/`native-seedance`) and their job-state — no duplicate submit/poll logic. `batch-submit` persists `<dir>/batch-queue.json`; `batch-monitor` polls once (the transport downloads to `<dir>/scene-<i>.mp4`), copies each completed scene to `<dir>/clips/<jobId>.mp4`, and writes `<dir>/batch-status.json`. It is **resumable/idempotent**: re-running only advances pending→done/failed and never re-downloads completed clips, so `batch-monitor --out <dir> --once` is safe to schedule via launchd (one pass per tick). Opt-in wedge handling: `--stall-minutes <n>` (0=off) flags scenes the provider has left `submitted` past the stall window as **wedged** (`detectWedgedScenes`/`applyWedgeHandling` in `batch-queue.ts`), and `--fail-wedged` marks them `failed` so the queue reaches terminal and the monitor exits instead of polling a stuck job to the deadline. The monitor also backs off automatically when the explore queue is throttled (`isExploreThrottled`/`nextBackoffMs`), and the opt-in `--auto-resubmit` (with `--stall-minutes <n>`, bounded by `--max-resubmits <n>`, default 2) re-submits wedged scenes as fresh single-scene jobs (`planResubmits`/`runResubmitPass`) — **only on the free `runway-useapi` route** (refused on paid routes up front, and the resubmit path self-guards, so it never spends credits). See `docs/CLI_REFERENCE.md` ("Overnight batch video queue").
@@ -166,10 +294,18 @@ For `seedance-direct`, `veo-useapi`, `runway-useapi`, and `dreamina-useapi`, `vc
 
 `vclaw video motion-overlay --input <video>` turns an existing talking-head video into a reel with speech-synced motion-graphics overlays. Pipeline: ingest → transcribe (Gemini STT) → slice into ≤10s takes → compose overlay prompts (retention principles + concept→animation metaphor map live as deterministic code, not markdown) → render via one of four layouts (`split|overlay|motion-only|avatar-host`). Render transports: Omni Flash V2V (moderation-prone on person footage), **local** per-frame render (`render-local.ts`/`animate*.ts` — word reveal, count-up, gauge fill), and `avatar-host` (locked go-bananas character via `--gb-character <Name:ID>`, pin+chain identity). Plan/dry by default; spend requires `--execute --confirm-spend`; retry/resume self-heals probabilistic Flow moderation. See `docs/MOTION_OVERLAY.md`.
 
+### Mograph — style-locked motion graphics (`src/video/mograph/`)
+
+`vclaw video mograph-sheet` / `mograph-pack` / `mograph-render` / `mograph-logos` generate fleets of motion-graphics clips that share ONE look: a **motion sheet** (`artifacts/motion-sheet.json` — master style-board image + ≤120-word style lock carrying the do-NOT-copy-the-sheet-layout guard + a negative ending in the five audio bans) locks the style once, and a **motion pack** (`artifacts/motion-pack.json` — coverage map + action-only `B###` blocks, P1/P2/P3, `t2v|ref2v|v2v-*` modes) carries pure choreography. `mograph-pack --check` is the anti-drift gate (style words/hex codes banned from actions, quoted on-screen text ≤4 words, SFX-never-music, coverage integrity); `mograph-render` is PLAN-ONLY — it assembles `style lock + SHOT + AUDIO + AVOID` per block and `--emit-batch` compiles a batch-queue manifest for the existing `batch-submit`/`batch-monitor` machinery (refs ride in `characterRefs`, the REFERENCE slot; v2v blocks are set aside for omni-flash or prompt-only, never dropped silently). Creative authoring lives in `skills/mograph/SKILL.md`; contract in `docs/MOGRAPH.md`; design spec in `docs/design/specs/2026-07-13-mograph-native-port.md`. Native port of a licensed external skill's concepts — original wording only, the purchased pack is never committed.
+
 ### Audio platform (`src/video/audio-platform/`)
 
 `narrate`, `dialogue`, `sfx`, and `soundtrack` are backend-pluggable audio commands over a backend registry (`registry.ts`): TTS via `gemini-tts`/`elevenlabs-tts`, SFX via ElevenLabs, music via `lyria` (Vertex), `lyria3` (Gemini API, key-based), `flowmusic` (Lyria 3 Pro vocals via useapi.net), and Suno. All spend-gated: without `--confirm-spend` they exit 3 with `spend_confirmation_required` (`--dry-run` to plan). `assemble` consumes their outputs via the mix-plan (dialogue + SFX mixed at stitch; `assemble/narration-fit.ts` handles TTS-vs-video timing).
 
+### Media production & local post-production
+
+Two handler families cover the finishing lane. `handlers/media-production.ts`: `assemble` (FFmpeg stitch, incl. `--from-clips`), `gen-image` (diegetic prop/screen/overlay stills; Flow image models via `gen-image-flow.ts`), `overlay` (graphic/alert/lower-third motion graphics with a drawtext preflight), `music-video` (vocal-synced beat-exact assembler, plan/dry by default), `title-card` (Pillow+RAQM title overlays), `stitch-ad`, `animation-styles` (shared `animation-styles.json` registry), `finish` (`src/video/finish.ts` — upscale a rendered cut to an HD/QHD master via hosted Topaz (spend-gated) or local Real-ESRGAN/Topaz CLI; the anti-plastic recipe is baked in: photoreal model, denoise/sharpen DISABLED, film grain kept, and Topaz `grain` clamps to 0.1 because the published schema overstates the range), and `lipsync` (OmniHuman, spend-gated). `assemble`'s stitch layer also supports opt-in **reading-holds** (`assemble/stitch.ts`, `readingHold`) — readable pre-roll holds on dense motion-comic segments. `handlers/media-ops.ts` is local-FFmpeg-only post-production on a finished cut — `make-vertical`/`make-square`/`make-loop`, `thumbnail`, `burn-subtitles`, `verify-final`, and `qc` (recursively scans `projects/<slug>/final/` + `outputs/` for clips and runs the assemble media-QC probe: missing-audio, nonstandard codec, duration drift; graceful `status: 'skipped'` when no clips) — real file I/O but NO provider calls and NO spend. Two adjacent quality/finishing tools: `vclaw video image-ops` (`src/video/image-ops.ts` + `native-magnific.ts`) is still-image post-processing, currently the Magnific precision-v2 image upscaler (pure planning core + injectable runner; `--dry-run` plans without spending; the IMAGE endpoint is live-verified, a different service from the video upscaler), and `vclaw video consistency-audit` (`src/video/consistency-audit.ts`) is an automated character-consistency VISION audit across rendered scenes/keyframes — the engine-side forcing function that catches wardrobe/face drift on recurring characters BEFORE a render is presented as done.
+
 ### Gemini key pool
 
 `src/video/gemini-key-pool.ts` provides round-robin selection with per-key cooldown across `GEMINI_API_KEYS`, `GOOGLE_API_KEYS`, `GOOGLE_API_KEY`. `analyze-template --auto` and `analyze --auto` use it via `src/video/gemini-analyze.ts`. `VCLAW_GEMINI_API_ENDPOINT` overrides the endpoint.
@@ -195,13 +331,34 @@ For `seedance-direct`, `veo-useapi`, `runway-useapi`, and `dreamina-useapi`, `vc
 - `check:skill-frontdoor` deliberately ignores `skills/seedance-prompts/SKILL.md` and the three presenter skills (`bunty`, `davendra-presenter`, `nex-presenter`) because their docs legitimately reference the legacy Python pipeline scripts. Don't "fix" the ignore list — it's load-bearing.
 - Do not commit secrets, `.env.local`, provider cookies, or `.omx/` state (already gitignored).
 
+## Start in your own worktree
+
+Sessions share this repo's `.git`. Two in the MAIN checkout also share its
+working tree, index, HEAD and `dist/` — which on 2026-08-01 absorbed one
+session's uncommitted work into another's commit, wiped `dist/` mid-test-run
+(322 phantom failures), and switched the branch under an in-flight commit. A
+worktree gives a session its own copy of all four.
+
+Run `scripts/new-session.sh <name> [branch]` before doing anything else. It
+builds `.claude/worktrees/<name>` off a freshly fetched `origin/main`, links
+`node_modules`, proves the link resolves, and prints the `cd`. Stage explicit
+paths when committing, so a commit holds only what you touched.
+
+Working in the main checkout is fine when you are certain you are the only
+session. When you are not certain, you are not.
+
+`scripts/hooks/install.sh` activates a `pre-commit` guard: it blocks a commit
+made directly on `main`, and warns when you commit from the main checkout while
+another worktree holds uncommitted work. Both are advisory-on-error and skippable
+with `VCLAW_SKIP_GUARD=1` — a guard that wrongly blocks just gets deleted.
+
 ## Autonomy directive (from AGENTS.md)
 
 Proceed by default on obvious next steps. Keep work scoped to this repository and its generated `projects/<slug>/` folders. If a blocker is local and solvable, solve it; if it's external, note it and continue with the next meaningful lane rather than pausing for confirmation.
 
 ## Recommended reading order
 
-`docs/ARCHITECTURE.md` → `docs/CLI_REFERENCE.md` → `docs/STUDIO.md` → `docs/ASSEMBLE.md` → `docs/PRODUCTION_WORKFLOW.md` → `docs/REVIEW_UI_STORYBOARD_WORKFLOW.md` → `docs/preview-portal-audit.md` → `docs/STORY_BIBLE.md` → `docs/DIRECTOR_BLUEPRINT.md` → `docs/MOTION_OVERLAY.md` → `docs/REFERENCE_SHEETS.md` → `docs/SCENE_CANDIDATES.md` → `docs/OPERATIONS.md` → `docs/GENERATION_TELEMETRY.md` → `docs/OBSIDIAN.md` → `docs/TEMPLATES.md` → `docs/MIGRATION.md` → `docs/DEPRECATION.md` → `docs/RELEASE_READINESS.md` → `docs/MASTER_PLAN_ALIGNMENT.md` → `docs/DIAGRAMS_SOURCE.md`.
+`docs/ARCHITECTURE.md` → `docs/CLI_REFERENCE.md` → `docs/STUDIO.md` → `docs/ASSEMBLE.md` → `docs/PRODUCTION_WORKFLOW.md` → `docs/REVIEW_UI_STORYBOARD_WORKFLOW.md` → `docs/preview-portal-audit.md` → `docs/STORY_BIBLE.md` → `docs/DIRECTOR_BLUEPRINT.md` → `docs/MOTION_OVERLAY.md` → `docs/MOGRAPH.md` → `docs/REFERENCE_SHEETS.md` → `docs/SCENE_CANDIDATES.md` → `docs/OPERATIONS.md` → `docs/GENERATION_TELEMETRY.md` → `docs/OBSIDIAN.md` → `docs/TEMPLATES.md` → `docs/MIGRATION.md` → `docs/DEPRECATION.md` → `docs/RELEASE_READINESS.md` → `docs/MASTER_PLAN_ALIGNMENT.md` → `docs/DIAGRAMS_SOURCE.md`.
 
 Architecture decision records live in `docs/adr/` (no-silent-fallback across routes, on-disk project as source of truth, Seedance identity via Asset Library, director-mode approval gate) — consult them before relitigating those decisions.