videoclaw 3.0.0-alpha.11 → 3.0.0-alpha.13

package/CLAUDE.md

@@ -2,13 +2,13 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Quick orientation (read this first, then `MERGE_PLAN.md`)
+## Quick orientation (read this first)
 
-- **Entrypoint:** `src/cli/vclaw.ts` — a thin ~530-line dispatch shell; all command logic lives in `src/cli/handlers/*.ts` (25 modules).
+- **Entrypoint:** `src/cli/vclaw.ts` — a thin ~640-line dispatch shell; all command logic lives in `src/cli/handlers/*.ts` (38 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.
+- **Also load:** the sibling `.claude/CLAUDE.md` for the `graphify`, `improvement-run`, and `concierge`/`videoclaw` 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`
@@ -17,9 +17,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 > copied from `vclaw-video-core`; presenter skills synced from
 > `video-creation-projects/video-replicator-veo-cli/.claude/skills/`; Runway
 > transport ported from `videoclaw/src/video/providers/runway-useapi.ts`.
-> The full merge plan, decisions, and remaining phases are in `MERGE_PLAN.md` —
-> **read it before starting any non-trivial work.** It is the source of truth for
-> the architecture and what's coming.
+> `MERGE_PLAN.md` holds the merge's architecture rationale and phase history
+> (all phases but source retirement are done). Current status lives in
+> `docs/RELEASE_READINESS.md` and `CHANGELOG.md`; the shipped architecture in
+> `docs/ARCHITECTURE.md`.
 
 ## Repository purpose
 
@@ -28,13 +29,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Concierge front door (user-facing requests)
 
 `skills/concierge/SKILL.md` is the user-facing front door, and it speaks as
-**Clawbot** — VideoClaw's mascot (`clawbot` is a persona alias of the skill).
+**VideoClaw** — the product itself (`videoclaw` is a persona alias of the skill).
+The on-screen mascot is VideoClaw too: Go Bananas character 291, renamed from
+its earlier name on 2026-09-09; the artwork is unchanged.
 When the user asks to make a video, gives an ambiguous creative request, types
-`/concierge` or `/clawbot`, asks for Clawbot, or seems new to the system, read
-that skill and follow it before doing anything else: greet them as Clawbot,
+`/concierge` or `/videoclaw`, asks for VideoClaw, or seems new to the system, read
+that skill and follow it before doing anything else: greet them as VideoClaw,
 present the menu, route their choice through its lane table, and keep the
-plan → preview → spend order (never spend without explicit go-ahead). If their
-first message is just a greeting with no task, offer the concierge menu.
+plan → preview → spend order (never spend without explicit go-ahead).
 Engineering and maintenance requests on this codebase itself are NOT concierge
 territory — handle those normally.
 
@@ -179,8 +181,17 @@ 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 acceptance:live -- --route <id> [--veo-model free] [--approve]  # ONE quoted provider job per route → an audit row (dry without --approve; the repeatable form of docs/audits/*-live-acceptance.md); --kind narrate|soundtrack|image-upscale [--backend <id>] certifies an audio / Magnific backend the same way
+npm run lint                             # eslint src --max-warnings=0 (eqeqeq, no-var, prefer-const, no-eval family)
+npm run check:module-size                # fails on any src/**/*.ts over 1,000 lines; legacy giants are frozen at per-file ceilings in scripts/check-module-size.mjs — lower them, never raise them
+npm run check:seedance-engine            # in-tree free Seedance engine present + wired + offline stub self-test (no browser, no spend)
+npm run check:build-fresh                # dist/ is not stale relative to src/
+npm run frontdoors:check                 # .claude/CLAUDE.md skill front-door blocks match scripts/skill-frontdoors.json (regenerate: npm run frontdoors:install)
+npm run test:coverage                    # build, then compiled tests under coverage
+npm run demo                             # zero-key creator-demo quickstart in a temp workspace (providerCalls: 0)
 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/)
+npm run shared-queue:status              # `vclaw video lane status` against the shared coordinator; shared-queue:setup / :verify / :dashboard / :self-test manage services/shared-lane-coordinator
 ```
 
 `npm run check:release-readiness-lite` is the preferred local pre-flight before non-trivial changes land.
@@ -189,8 +200,8 @@ 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 (~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).
+1. `src/cli/vclaw.ts` — the single user-facing entrypoint, now a thin dispatch shell (~640 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/` (38 modules — the original 25: `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`; plus the later families `cinema`, `cinema-archive`, `cinema-candidate`, `cinema-delivery`, `cinema-execution`, `cinema-history`, `cinema-migration`, `creator-demo`, `creator-ui`, `lane`, `mograph`, `publish-platform`, `stock`), 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 five built-in adapter routes (`seedance-direct`, `veo-useapi`, `runway-useapi`, `dreamina-useapi`, `magnific-rest`; 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`; since Phase 3a the lighting/grade, hook, realism and dynamic tables live in `lighting-grade-register.ts` / `hook-register.ts` / `realism-register.ts` / `dynamic-register.ts` and are re-exported from it, so import from `cinematography.js` as before), `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.
 5. `schemas/video/` — canonical JSON Schema contracts for artifacts and pipeline manifests. Treat these as the source of truth for artifact shapes.
@@ -221,7 +232,7 @@ Canonical stage order: **init → brief → storyboard → assets → review →
 
 ### Two production modes
 
-Every command accepts `--mode storyboard|director`. Pipeline manifests under `src/video/pipeline-manifests/` define the stage contract per mode. `director` mode adds a storyboard-approval gate: `produce`/`execute` export `storyboard.md` and block before provider submission unless `VIDEOCLAW_APPROVE_STORYBOARD=1` is set. `storyboard-review` (no-execution) can perform preflight + transition the project into `awaiting-approval` without starting a run.
+Every command accepts `--mode storyboard|director`. Pipeline manifests under `src/video/pipeline-manifests/` define the stage contract per mode. `director` mode adds a storyboard-approval gate: `produce`/`execute` export `storyboard.md` and block before provider submission unless `VIDEOCLAW_APPROVE_STORYBOARD=1` is set or the run is `produce --approve` (the command the blocked report prints; `approve` is a deprecated spelling of it). Plain `produce` has no `--confirm-spend` gate and refuses that flag (and `--execute`) rather than ignoring it; every direct front door reaches the provider through `executeProject` (ADR 0008 amendment). `storyboard-review` (no-execution) can perform preflight + transition the project into `awaiting-approval` without starting a run.
 
 ### Studio front door (planning layer)
 
@@ -239,7 +250,7 @@ The ops layer tracks a normalized `storyboardReviewState` of `missing | current
 
 ### Review & delivery portal (`src/video/preview-portal/`)
 
-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`.
+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 — since Phase 3d `render.ts` keeps the surface router and imports `render-primitives.ts` (escaping, aspect, dates), `render-scene-contract.ts` (the exact-submit contract), `render-run.ts` (the run dashboard) and `render-brand.ts` (brand theming)), 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`)
 
@@ -247,7 +258,7 @@ The portal generates the standardized HTML surfaces that used to be hand-written
 
 ### 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) 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/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 `hook-register.ts`, re-exported by `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.
 
@@ -286,6 +297,25 @@ The repeatable cartoon-SHOW production system (from the Jack-Vs-AI workflow). `v
 
 `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").
 
+### Cinema production queue + render lanes (the durable execution layer)
+
+ADR 0008 converges every generated-work front door (`produce --auto-chain`, `pool`, `batch-submit`, `mograph-render --enqueue` (its `--emit-batch` still writes the legacy batch manifest), fallback rendering) onto ONE durable, dependency-aware production queue owned by the `src/video/cinema-*` store family (~60 small modules: `cinema-production-queue.ts`, `cinema-production-contract-*`, `cinema-provider-*`, `cinema-evidence*`, `cinema-review-*`, `cinema-preflight*`, `cinema-retry-policy.ts`, `cinema-file-lock.ts`, …). The queued path is `compile → exact quote → authorise → cinema-work → reconcile → review → delivery`, driven by the `vclaw video cinema-*` verbs (handlers `cinema*.ts`: `cinema-create`/`-compile`/`-preflight`/`-quote`/`-authorize`/`-work`/`-work-quote`/`-ingest`/`-review`/`-promote`/`-deliver`/`-status`/`-console`/`-console-live`/`-archive`/`-restore`/`-migrate`/`-history-import`). Workers act on SAVED state (the quote, the immutable request, and the provider job id must survive interruption); an ambiguous submission is resolved before any replacement work is authorised, never re-submitted blindly. ADR 0009 makes the Cinema console (`cinema-console` / `cinema-console-live`, `cinema-project-console*.ts`, `cinema-live-console.ts`) the one authoritative live review surface that review-ui, the preview portal and monitor detail pages converge on. Cinema route ids are a separate id space from the core `ProviderRouteId`s (ADR 0001 + 0007: unlimited Higgsfield, paid xskill API and the official Higgsfield CLI — `cinema-higgsfield-cli-*.ts` — are distinct routes and never silently swap).
+
+**Render lanes** (`src/video/lane-queue.ts`, `lane-coordinator.ts`; `vclaw video lane <acquire|await|heartbeat|release|status>` in `handlers/lane.ts`) are the cross-process slot leases every driver — in any language — must take before submitting. The lane key is `route:account` (provider limits are per ACCOUNT), one lane per transport so different engines run in parallel. The local queue is the external `sqlite3` CLI (not `node:sqlite`); the shared multi-computer authority is a Cloudflare Durable Object per lane deployed from `services/shared-lane-coordinator/` (`docs/SHARED_QUEUE.md`). It is a lease, not a task queue: the agent still runs its own render, it only waits its turn. Two drivers on one lane look exactly like moderation failures and have the opposite fix (serialise vs redraw) — check `lane status` before diagnosing rejections.
+
+### Free Seedance engine, vendored in-tree (`engines/seedance-direct/`)
+
+ADR 0006 (supersedes 0005): the free, unlimited Higgsfield Seedance engine is a ~600-line Python adapter (`adapter.py`, `run.sh`, `bootstrap.sh`, `test_adapter.py`) living OUTSIDE `src/` — it does not touch `tsc`, `node:test` or the npm tarball. It speaks the same stdin/stdout SUBMIT/POLL/CANCEL JSON contract as every `..._ADAPTER`. `resolveAdapterCommand` prefers it for `seedance-direct` only when the engine is fully bootstrapped; the readiness verdict is `describeFreeInTreeSeedanceEngine` in `src/video/execution-adapter.ts`, which requires the `.vclaw-engine-ready.json` marker (`FREE_SEEDANCE_ENGINE_MARKER`) that ONLY a successful signed-in cookie import writes inside the browser-session directory — an existing venv + an empty profile directory is NOT ready and falls through to the PAID `native-seedance.ts` transport (`SUTUI_API_KEY`), per ADR 0001. The venv and the `.cloak-profile` browser session are local, secret and git-ignored; `engines/seedance-direct/bootstrap.sh` creates them. Before any `--confirm-spend` on `seedance-direct`, read `activeTransport` in `vclaw video providers` output — `in-tree-engine` is free, anything else is paid. `VCLAW_SEEDANCE_DIRECT_NATIVE=1` forces the paid path.
+
+### Smaller newer families (each self-contained under `src/video/`)
+
+- `creator-ui/` (`vclaw video creator-ui`, `creator-demo`; `docs/CREATOR_DEMO.md`) — the zero-key product-shell: `capabilities.ts` probes which stock/TTS/music/generative routes this machine can actually use, `read-model.ts` + `server.ts` serve a local creator surface, and `creator-demo` (also `vclaw studio --goal creator-demo`, `npm run demo`) builds a full project + preview with `providerCalls: 0`, `networkCalls: 0`, never marking it publish-ready.
+- `stock-platform/` (`vclaw video stock-search` / `stock-import`) — stock footage providers (`providers/pexels.ts`) behind a registry; `rights.ts` records licence/provenance (sha256 + source) per imported asset and `store.ts` keeps imports inside the project.
+- `publish-platform/` (`vclaw video publish-metadata` / `publish-package`) — versioned, source-cited platform profiles (`profiles.ts`: YouTube Shorts etc. with max duration, aspect, codec, title/description limits, synthetic-media disclosure) and `validate.ts` checks a final cut + metadata against the chosen profile before packaging. Distinct from `publish-preview` / `publish-portal-index` (the preview portal) and from `docs/PUBLISHING.md` (releasing the npm package itself).
+- `reframe/` — the shot-plan engine behind `make-vertical`: `--write-plan-template` detects cuts and writes UNVERIFIED subject-anchor suggestions; `--strict` refuses to render until every anchor is verified (or `--quick-center-crop` is explicit); `captions.ts` renders portrait-native captions and `qc.ts` audits the crop.
+- `run-state/` — `readProjectRunState` normalises candidates + storyboard + execution report into one derived run view (stale `pending` candidates are treated as abandoned); the read model that monitor/console surfaces share.
+- `magnific/` + `providers/` — the Magnific REST route (`magnific-rest`, one of the five built-in adapter routes) and the thin useapi/xskill/Flow transport clients the native routes call.
+
 ### Director Blueprint (director layer)
 
 `src/video/project-blueprint.ts` + `blueprint-prompt.ts` + `director-defaults.ts` (`vclaw video director-blueprint --project <slug> (--from-json <path> [--write] | --show)`) persist a project-level **visual bible** (`artifacts/project-blueprint.json`): color system, lighting grammar, per-character camera language, forbidden moves, "the one rule". It is distinct from the story bible (continuity); the blueprint locks **visual direction** above the execution layer. Authoring is creative and lives in the `ai-director` skill (`skills/ai-director/SKILL.md`); the CLI half is deterministic (validate/normalize/persist). `filmmaking-prompts` auto-appends a prose DIRECTOR block and flags forbidden-move violations when a blueprint exists; no blueprint → byte-identical legacy output. See `docs/DIRECTOR_BLUEPRINT.md`.
@@ -304,7 +334,7 @@ The repeatable cartoon-SHOW production system (from the Jack-Vs-AI workflow). `v
 
 ### 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.
+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`) — since Phase 3c the stitch constants/filter register, the concat/prep argv builders and the multi-layer audio mix live in `assemble/stitch-filters.ts` / `stitch-concat.ts` / `stitch-audio-mix.ts` and are re-exported from `stitch.ts`, so import from `stitch.js` as before — 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
 
@@ -315,6 +345,12 @@ Two handler families cover the finishing lane. `handlers/media-production.ts`: `
 - `execution-plan` ↔ `plan`
 - `execute` ↔ `produce`
 
+These two are supported spellings: the product itself emits `vclaw video execute` (`create.ts`, `execute.ts`, `storyboard-markdown.ts`, the studio recipes), so they never print a notice.
+
+### Declared aliases on their way out (notice-only, dispatch preserved until removal)
+
+`template-create` → `template-save`, `clone-ad` → `clone-execute`, `analyze-template` → `analyze`, `preflight` → `director-preflight`, `library find` → `find-library` — all marked `deprecatedAliases` since 3.0.0-alpha.13, as are the one-shot and historical-only commands listed in `docs/DEPRECATION.md` "Marked as of 3.0.0-alpha.13". Each alias is an `aliases` entry on the canonical `CommandSpec` in `src/video/cli-schema.ts` (one schema entry, one handler); marking one deprecated is `deprecatedAliases: [{ name, since }]` on that entry, which makes `main` print one stderr line and run the command unchanged. Lifecycle: `docs/DEPRECATION.md` "Command lifecycle". `src/tests/cli-dispatch-table.test.ts` fails on a dispatch key that shares a handler but is declared nowhere. The command `approve` is marked `deprecated` (not an alias: its own dispatch key) as a spelling of `produce --approve`; its handler forwards to the produce handler.
+
 (The old `omx` wrapper binary has been removed entirely — don't reintroduce it.)
 
 ## Conventions that are not obvious
@@ -327,9 +363,10 @@ Two handler families cover the finishing lane. `handlers/media-production.ts`: `
 - Tests use `node:test` with `assert/strict`. Prefer `mkdtemp`/`tmpdir` for temp-directory isolation. Put CLI end-to-end tests under `src/tests/cli-*.test.ts` and module-contract tests under `src/tests/*.test.ts`.
 - When adding a new CLI subcommand: add the handler in the appropriate `src/cli/handlers/*.ts` module (or a new one following the verbatim-move pattern) and register the dispatch-table entry (plus any alias) in `src/cli/vclaw.ts`; update the relevant `src/video/*` module(s), a schema under `schemas/video/` if it introduces or changes an artifact, register the command in the `COMMANDS` array of `src/video/cli-schema.ts` (bump the hardcoded command-count assertion in `cli-schema.test.ts` to match), add a `cli-*.test.ts`, and update `README.md` + `docs/CLI_REFERENCE.md`. The `check:cleanroom-docs` guardrail watches docs drift.
 - Project slugs are validated by `isProjectSlug` (`src/video/projects.ts`); both `parseProjectSlug` and `handleVideoInit` (`validateInitSlug`) enforce it so flag-looking values (e.g. `--project`) cannot be silently accepted as slugs. Preserve this guard when adding new slug-accepting commands.
-- Architecture diagrams under `docs/assets/*.jpg` are generated from Mermaid sources in `docs/DIAGRAMS_SOURCE.md`. Edit the Mermaid blocks there and regenerate the images via the Go Bananas Pro model — never hand-edit the JPGs.
+- Architecture diagrams under `docs/assets/*.jpg` are generated from the Mermaid sources in `docs/DIAGRAMS_SOURCE.md`. Edit the Mermaid block there, then `npm run diagrams:mirror && npm run diagrams:render` (mermaid-cli with the brand config — the deterministic render the existing JPGs came from; `npm run diagrams:lint` fails when a mirror drifts). Never hand-edit the JPGs.
 - `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).
+- Do not commit secrets, `.env.local`, provider cookies, `engines/*/.cloak-profile/`, or `.omx/` state (already gitignored).
+- `.cursor/rules/codegraph.mdc` (alwaysApply) is the CodeGraph MCP usage guide: prefer `codegraph_context` / `codegraph_trace` / `codegraph_impact` for structural questions (callers, callees, blast radius) and grep only for literal text. Skills that touch many modules (the cinema store, provider routes) are where this pays off most.
 
 ## Start in your own worktree
 
@@ -358,9 +395,9 @@ Proceed by default on obvious next steps. Keep work scoped to this repository an
 
 ## 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/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`.
+`docs/AGENT_QUICKSTART.md` (install → first free render; `vclaw schema --json` + `skills/catalog.json` are the live command/skill indexes) → `docs/ARCHITECTURE.md` → `docs/PROJECT_LAYOUT.md` → `docs/CLI_REFERENCE.md` → `docs/STUDIO.md` → `docs/SHARED_QUEUE.md` → `docs/CREATOR_DEMO.md` → `docs/PUBLISHING.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.
+Architecture decision records live in `docs/adr/` — 0001 no-silent-fallback across routes, 0002 on-disk project as source of truth, 0003 Seedance identity via Asset Library, 0004 director-mode approval gate, 0005→0006 free Higgsfield Seedance engine vendored in-tree, 0007 unlimited / paid-API / official-CLI Higgsfield are separate routes, 0008 one durable production queue, 0009 one HTML5 production review console. Consult them before relitigating those decisions.
 
 ## Agent skills
 

package/README.md

@@ -6,9 +6,9 @@
 
 **Turn a one-line idea into a finished AI video — step by step, in the open, with a human approval before anything expensive runs and automated QC before anything ships.**
 
-A command-line tool (`vclaw`) that takes a plain-English idea like *"a 15-second ad for my coffee brand"* and walks it all the way to a reviewed, published video — using AI video services like **Veo, Seedance, and Runway**. Every step is saved to a file you can read, so nothing is hidden and you can stop, inspect, or replay any stage. It also **checks its own output** — a vision pass that catches the motion defects a still-frame glance misses (breath vapour, morphing, vanishing props, character drift) before a clip is called done.
+A command-line tool (`vclaw`) that takes a plain-English idea like *"a 15-second ad for my coffee brand"* and walks it all the way to a reviewed, published video — using AI video services like **Veo, Seedance, and Runway**. Every step is saved to a file you can read, so nothing is hidden and you can stop, inspect, or replay any stage. Optional vision QC can inspect motion defects such as breath vapour, morphing, vanishing props and character drift. It requires a configured vision backend; final playback review remains separate.
 
-[![Tests](https://img.shields.io/badge/tests-2800%2B%20passing-brightgreen)](https://github.com/davendra/videoclaw-v3/blob/main/.github/workflows/ci.yml)
+[![CI](https://github.com/davendra/videoclaw-v3/actions/workflows/ci.yml/badge.svg)](https://github.com/davendra/videoclaw-v3/actions/workflows/ci.yml)
 [![Node](https://img.shields.io/badge/node-20%2B-brightgreen)](./package.json)
 [![TypeScript](https://img.shields.io/badge/typescript-strict%20%7C%20NodeNext%20ESM-3178c6)](./tsconfig.json)
 [![Status](https://img.shields.io/badge/status-active%20development-orange)](https://videoclaw-docs.vercel.app/reference/MASTER_PLAN_ALIGNMENT)
@@ -22,8 +22,8 @@ The complete, idiot-proof **and** agent-ready docs: an [interactive guide](https
 
 > **New here?** The easiest path is to **[drive it by talking to Claude Code](https://videoclaw-docs.vercel.app/guide/with-claude-code)** (or any agent host); there's a dedicated [how-it-works page for agents](https://videoclaw-docs.vercel.app/for-agents/) too.
 >
-> **Agents working in this repo:** read [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) (or [`llms.txt`](llms.txt)) — a one-read capability manifest: what videoclaw can produce, the provider routes, the spend-safety model, and the full command index. Run `vclaw schema --json` for exact flags.
-> Once you're in Claude Code in this repo, just type **`/concierge`** (or **`/clawbot`**) — or say *"make me a video"* — and **Clawbot**, VideoClaw's mascot and concierge, walks you from idea to finished film, with a preview and your approval before anything costs money.
+> **Agents working in this repo:** read [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) (or [`llms.txt`](llms.txt)) — a one-read capability manifest: what videoclaw can produce, the provider routes, the spend-safety model, and a command map that names every registered command (exact flags: `vclaw schema --json` and `docs/CLI_REFERENCE.md`). Run `vclaw schema --json` for exact flags.
+> Once you're in Claude Code in this repo, just type **`/concierge`** (or **`/videoclaw`**) — or say *"make me a video"* — and **VideoClaw**, speaking as its own concierge, walks you from idea to finished film, with a preview and your approval before anything costs money.
 
 <a href="https://videoclaw-docs.vercel.app/"><img src="./docs/assets/docsite-preview.png" alt="videoclaw documentation site — make AI videos by just talking" width="100%" /></a>
 
@@ -86,12 +86,12 @@ Three things make it different from the usual *"type a prompt, get a video"* too
 
 - **Go from idea → finished video** without leaving the terminal.
 - **Use several AI video engines** (Veo, Seedance, Runway) through one consistent set of commands — no need to learn each provider's quirks.
-- **Keep characters consistent** — the same person, outfit, set, and props look the same in every scene (via character profiles, reference sheets, and the *story bible*).
-- **Approve in your browser** before any expensive render runs — open the Review UI, look at the stills, click approve or regenerate.
+- **Manage character consistency** — character profiles, reference sheets and the *story bible* carry identity and continuity between scenes; inspect generated results for drift.
+- **Review storyboard stills in your browser** — use the Review UI to inspect and select them. Director approval and exact queued spend authorisation are distinct gates; plain `produce` is live by default.
 - **Add the finishing touches** — narration, background music, subtitles, thumbnails, and vertical / square / looping variants for different platforms.
 - **Run many projects at once** and see them all on a dashboard: what's blocked, what's stale, what needs review, what's ready to publish.
-- **Trust the result** — a project is only "ready" when its review report literally says `pass`. No guessing.
-- **Rehearse for free** — almost every command has a `--dry-run` that plans the whole thing without spending a credit.
+- **Record delivery evidence** — publish readiness requires a passing review report and `metrics.publishReady: true`; planned or previously film-reviewed projects also need current passing film-edit evidence.
+- **Preview the intended operation** — use each command’s documented planning or `--dry-run` path. There is no universal dry-run flag; queue compilation and direct rendering have different contracts.
 
 ---
 
@@ -108,9 +108,11 @@ Here is the whole assembly line in plain words. Each step is a command, and each
 | 5 | `plan` | Pick the AI provider and prepare the exact request to send. |
 | 6 | `produce` | Actually generate the clips. (Add `--dry-run` to rehearse for free.) |
 | 7 | `assemble` | Stitch clips + narration + music into one MP4, then quality-check it. |
-| 8 | `review` | A human (or the Review UI) approves the result. |
+| 8 | `review` | Record final review; explicit film plans require current full-playback evidence bound to the actual edit. Storyboard approval in the Review UI is a separate gate. |
 | 9 | `publish` | Mark it done and hand it off. |
 
+For new agent-led films, add a [structured film plan](./docs/SHARED_FILMMAKING_WORKFLOW.md) at storyboard time. It records format, purpose, shot action and performance; compiled prompts and final edit reviews detect relevant changes before reuse. The host agent manages phases and progress.
+
 You don't always run these by hand — `vclaw video create` can do the whole front of the line in one shot — but this is the path everything follows underneath.
 
 ---
@@ -132,7 +134,7 @@ videoclaw is made of a few moving pieces. Here's each one in everyday terms:
 | **Obsidian workspace** | The same project data, rendered as browsable notes you can read in Obsidian instead of the terminal. |
 | **Skills** | Pre-built, ready-to-run workflows for common jobs (make a presenter video, clone an ad, build a character) that an AI agent can invoke. |
 
-That's the whole picture. Everything below is **reference detail** for power users, operators, and AI agents — you can stop here and still use the tool.
+That's the whole picture. Everything below is **reference detail** for power users, people running vclaw day to day, and AI agents — you can stop here and still use the tool.
 
 ---
 
@@ -196,7 +198,7 @@ node dist/cli/vclaw.js video status   --project demo
 
 > **Discovery and authoring need no provider keys.** Planning/direct dry-run can report blocked readiness when assets or a locally configured route are missing; that is diagnostic output, not a successful render. Keep `--dry-run` on plain `produce` while exploring, read the blockers, and configure only the route you intend to use. A zero-call queue compiler and a direct execution preview have different prerequisites.
 
-Add `--auto-chain` to `produce`/`execute` to compile the whole storyboard as a continuity chain into the durable Cinema queue — zero provider calls: the first pending scene is `awaiting-quote`, every later scene stays `blocked` behind its predecessor's selected video, and each link enters exact quotation only when that source exists. `--enqueue` is the explicit spelling of the same thing; `--execute`, `--dry-run` and `--confirm-spend` are refused. Each queued task is then quoted, authorized and run one at a time with `vclaw video cinema-work --task <id>` — for `veo-useapi` the shipped `dist/cli/flow-quote-adapter.js` quotes from the account's own Flow price table, so the 0-credit free model authorizes at `--maximum-spend 0`; only `runway-useapi` explore submits provider-free with `--confirm-provider-call`. See "Draining a queued Flow task" in `docs/CLI_REFERENCE.md`.
+Add `--auto-chain` to `produce`/`execute` to compile the whole storyboard as a continuity chain into the durable Cinema queue — zero provider calls: the first pending scene is `awaiting-quote`, every later scene stays `blocked` behind its predecessor's selected video, and each link enters exact quotation only when that source exists. `--enqueue` can be added alongside `--auto-chain` (it does not replace it); `--execute`, `--dry-run` and `--confirm-spend` are refused. Each queued task is then quoted, authorized and run one at a time with `vclaw video cinema-work --task <id>` — for `veo-useapi` the shipped `dist/cli/flow-quote-adapter.js` quotes from the account's own Flow price table, so the 0-credit free model authorizes at `--maximum-spend 0`; only `runway-useapi` explore submits provider-free with `--confirm-provider-call`. See "Draining a queued Flow task" in `docs/CLI_REFERENCE.md`.
 
 `vclaw video pool --project <slug> [--max-concurrent <N>] [--scenes <csv>]` compiles pending scenes as independent tasks into the durable Cinema queue. The concurrency cap is recorded on the queue lane; compilation itself submits nothing. `--dry-run` previews without writing. `--execute` is retired and `--confirm-spend` is rejected for enqueueing. Quote, authorise and run the returned tasks through `cinema-work`, then review their candidates. Plain `produce` without `--auto-chain` retains its direct live execution path: use `--dry-run` to preview that path, and do not assume its director approval gate is the same as an exact Cinema spend authorisation.
 
@@ -231,7 +233,7 @@ approval for already-reviewed projects; for director storyboard-image handoffs,
 use `review-ui` or `review-autopilot` so `publishReady` is derived from locked
 scene candidates, artifact-backed 4K stills, and final assembly approvals.
 
-Full operator guide: [`docs/PRODUCTION_WORKFLOW.md`](https://videoclaw-docs.vercel.app/reference/PRODUCTION_WORKFLOW).
+Full guide: [`docs/PRODUCTION_WORKFLOW.md`](https://videoclaw-docs.vercel.app/reference/PRODUCTION_WORKFLOW).
 Handoff checklist: [`docs/OPERATOR_HANDOFF.md`](https://videoclaw-docs.vercel.app/reference/OPERATOR_HANDOFF).
 
 ---
@@ -269,7 +271,7 @@ See [`docs/AGENT_INTEGRATION_RESEARCH.md`](https://videoclaw-docs.vercel.app/ref
 
 The system is layered: a thin command-line front, a domain core that does the real work, and an adapter tier that talks to the AI providers. Each stage writes to the artifact/checkpoint/event ledger on disk.
 
-<p align="center"><img src="./docs/assets/diagram-architecture.jpg" alt="videoclaw architecture layers — operator/agent at the top, CLI dispatching into domain modules, artifacts/checkpoints/events fanning out, execution runtime feeding the adapter layer, adapter layer branching into native transport, command shim, and custom adapter" width="100%" /></p>
+<p align="center"><img src="./docs/assets/diagram-architecture.jpg" alt="videoclaw architecture layers — you or an agent at the top, CLI dispatching into domain modules, artifacts/checkpoints/events fanning out, execution runtime feeding the adapter layer, adapter layer branching into native transport, command shim, and custom adapter" width="100%" /></p>
 
 <details>
 <summary>Show diagram source (Mermaid)</summary>
@@ -302,7 +304,7 @@ flowchart TB
 
 - **CLI layer** — argparse + dispatch only; no business logic.
 - **Domain layer** (`src/video/*`) — small, single-purpose modules. Each file owns one concept (artifacts, checkpoints, readiness, execution-plan, execution-runtime, doctor, metrics, next-actions, project-index, obsidian-export, etc.).
-- **Provider platform** — route descriptors for `veo-useapi`, `seedance-direct`, `runway-useapi`, `dreamina-useapi`, `magnific-rest`.
+- **Provider platform** — route descriptors for `veo-useapi`, `seedance-direct`, `runway-useapi`, `dreamina-useapi` (registered, not pursued since 2026-09-09), `magnific-rest`.
 - **Adapter layer** — three resolution strategies (custom binary → built-in adapter with command shim → native in-process transport). Explicit fall-through, never silent.
 - **Schemas** — JSON Schema contracts under `schemas/video/` are the source of truth for every artifact shape.
 
@@ -332,7 +334,7 @@ flowchart LR
     ingest --> assets([assets])
     assets --> review([review])
     review --> publish([publish])
-    execStatus -. operator .-> cancel([execute-cancel])
+    execStatus -. you .-> cancel([execute-cancel])
 ```
 
 </details>
@@ -396,11 +398,11 @@ flowchart TD
     Start[["route ∈ { veo-useapi · seedance-direct · runway-useapi ·<br/>dreamina-useapi · magnific-rest }"]]
     Start --> Q1{"VCLAW_*_ADAPTER set?"}
     Q1 -->|yes| Custom[["Custom adapter binary<br/>stdin → JSON, stdout → JSON"]]
-    Q1 -->|no| Q2{"Built-in adapter supports route?<br/>(seedance-direct · veo-useapi · runway-useapi)"}
+    Q1 -->|no| Q2{"Built-in adapter supports route?<br/>(all five routes ship one)"}
     Q2 -->|no| Fail([["❌ hard fail<br/>no silent fallback"]])
     Q2 -->|yes| Q3{"_SUBMIT_CMD / _POLL_CMD set?"}
     Q3 -->|yes| Shim[["Command shim<br/>through built-in adapter"]]
-    Q3 -->|no| Q4{"Native creds available?<br/>SUTUI_API_KEY (seedance) · local vclaw-cli (veo) · USEAPI_API_TOKEN (runway)"}
+    Q3 -->|no| Q4{"Native creds available?<br/>SUTUI_API_KEY or the free Higgsfield engine (seedance) · local vclaw-cli (veo) · USEAPI_API_TOKEN (runway, dreamina) · MAGNIFIC_API_KEY (magnific)"}
     Q4 -->|yes| Native[["✅ Native in-process transport"]]
     Q4 -->|no| Fail
 ```
@@ -441,7 +443,7 @@ useapi.net's Google Flow v1 API (blog 260609) accepts **inline `@`-mention marke
 
 Markers are **case-insensitive** and **opt-in** (a slot without a marker is fine; a marker without a matching body slot makes the API 400). The grammar is reserved through videoclaw's prompt pipeline (`@Name` tag resolution preserves the tokens verbatim, like `@imageN`) and is **veo-useapi-route-only** — on any other route the tokens are stripped from the scene prompt with a warning. V2V deliberately has **no** marker (`referenceVideo_1` stays flag-only via `--ref-video`). Helper module: `src/video/flow-markers.ts`; full details in [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE).
 
-**Auto-injection:** on veo-useapi, when a scene's prompt tags a character that has a registered Flow ref (`flow-characters.json`), `buildExecutionPayload` rewrites the `@Name` tag into its canonical `@character_N` marker automatically. Slot order = scene cast order first, then tag-only characters (capped at 7, overflow warned); hand-authored markers pass through untouched. Cast-name matching stays **exact-case** (the legacy lookup, verbatim) — which is exactly why a tagless prompt produces a byte-identical payload; only `@Name` **tag** matching is case-insensitive (`@clawbot` resolves to a registered `Clawbot`). Note that a ref-registered character's tag no longer also attaches its loose portrait image — the saved Flow character bundles its identity images. Characters without a Flow ref keep the normal descriptor substitution (including portrait collection).
+**Auto-injection:** on veo-useapi, when a scene's prompt tags a character that has a registered Flow ref (`flow-characters.json`), `buildExecutionPayload` rewrites the `@Name` tag into its canonical `@character_N` marker automatically. Slot order = scene cast order first, then tag-only characters (capped at 7, overflow warned); hand-authored markers pass through untouched. Cast-name matching stays **exact-case** (the legacy lookup, verbatim) — which is exactly why a tagless prompt produces a byte-identical payload; only `@Name` **tag** matching is case-insensitive (`@mascot` resolves to a registered `Mascot`). Note that a ref-registered character's tag no longer also attaches its loose portrait image — the saved Flow character bundles its identity images. Characters without a Flow ref keep the normal descriptor substitution (including portrait collection).
 
 ---
 
@@ -483,10 +485,10 @@ regenerated automatically on every `produce`/`execute` and `execute-status` poll
 (`VCLAW_NO_RUN_SURFACE=1` opts out).
 
 ### Templates · cloning · storyboard templates
-`analyze` · `analyze-template` · `template-create` · `template-save` · `template-list` · `template-show` · `template-validate` · `clone-plan` · `clone-init` · `clone-ad` · `clone-execute` · `storyboard-from-clone` · `storyboard-template-list` · `storyboard-template-show`
+`analyze` (`analyze-template` is a deprecated spelling) · `template-save` (`template-create` is a deprecated spelling) · `template-list` · `template-show` · `template-validate` · `clone-plan` · `clone-init` · `clone-execute` (`clone-ad` is a deprecated spelling) · `storyboard-from-clone` · `storyboard-template-list` · `storyboard-template-show`
 
 ### Character subsystem
-`character-add` · `character-list` · `character-show` · `character-consistency` · `consistency-audit` · `motion-qc` · `clip-qc` · `keyframe-qc` · `character-auto-create` · `environment-auto-create` · `character-import-library` · `find-library` · `library find` · `library clean` · `list-library` · `seedance-register-assets` · `flow-register-characters` · `flow-register-voices` · `flow-r2v` · `voice-clone` · `show-bible` · `show-preflight`
+`character-add` · `character-list` · `character-show` · `character-consistency` · `consistency-audit` · `motion-qc` · `clip-qc` · `keyframe-qc` · `character-auto-create` · `environment-auto-create` · `character-import-library` · `find-library` · `library find` (deprecated spelling of `find-library`) · `library clean` · `list-library` · `seedance-register-assets` · `flow-register-characters` · `flow-register-voices` · `flow-r2v` · `voice-clone` · `show-bible` · `show-preflight`
 
 `consistency-audit` is the **automated character identity/costume vision audit**: for each rendered scene it extracts a representative mid-frame and asks an (injectable, Gemini-backed) vision client whether each registered scene character still matches its locked reference face/hair AND costume/colours, plus a deterministic dark-border check and an extra-figure flag — catching wardrobe/identity drift (a dhoti rendering crimson in one scene and tan in another) BEFORE a render is presented as done. It writes `consistency-audit.json` and also runs advisory/non-fatal at the end of a real `produce`/`execute` run when a Gemini key is configured.
 
@@ -501,10 +503,10 @@ regenerated automatically on every `produce`/`execute` and `execute-status` poll
 
 ### Mission Control
 - `vclaw video monitor` — Mission Control: a live localhost cockpit across every project and provider.
-- `vclaw video migrate-home [--confirm] [--root <home>]` — consolidate scattered projects (`~/.videoclaw-*` roots) into the one canonical workspace home (`~/videoclaw`) via `mv` + a symlink left at the old path. Dry-run by default; `--confirm` performs the moves. Collision-safe and idempotent.
+- `vclaw video migrate-home [--confirm] [--root <home>]` — (deprecated since 3.0.0-alpha.13, one-shot) consolidate scattered projects (`~/.videoclaw-*` roots) into the one canonical workspace home (`~/videoclaw`) via `mv` + a symlink left at the old path. Dry-run by default; `--confirm` performs the moves. Collision-safe and idempotent.
 
 ### Metadata
-`set-meta` · `set-execution-profile` · `import-legacy`
+`set-meta` · `set-execution-profile` · `import-legacy` (deprecated, historical v2 import)
 
 ### Post-production
 `remix-narrated` · `verify-final` · `qc` · `make-vertical` · `make-square` · `make-loop` · `thumbnail` · `archive-project` · `motion-overlay` · subtitle burn-in
@@ -540,16 +542,16 @@ Two recent additions are worth calling out because they fix the two things that
 - **Diegetic stills** (`vclaw video gen-image`) — generate an in-world **prop**, on-screen **screen** (UI/dashboard), or **overlay** graphic (e.g. a "SYSTEM COMPROMISED" alert) into `assets/props/`. Three backends via `--backend`: **gobananas** (default, `GO_BANANAS_API_KEY`, no OpenAI key), **openai** (gpt-image), and **flow** — Google Flow via useapi.net (`USEAPI_API_TOKEN` + `USEAPI_ACCOUNT_EMAIL`): `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro` auto-selected by reference count (the retired `imagen-4` and `nano-banana` ids still map to the current models), repeated `--ref` (`reference_1..10`, local paths upload first) + `--character` (`character_1..7`, names resolve via `flow-characters.json`) slots, `--count`/`--seed`, and inline `@reference_N`/`@character_N` prompt markers validated **before any upload or spend**. Per-kind render directives (screens/overlays keep text, props suppress it); `--dry-run` prints the composed request with no spend. Composite it onto footage with the assemble overlay builders. Full guide: [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE).
 - **Motion-graphics overlays** (`vclaw video overlay`) — composite a graphic onto a clip (time-gated, faded, positioned — pairs with `gen-image` to drop a generated screen/alert onto footage, **font-free + real-render validated**), or burn a pulsing `--alert` / boxed `--lower-third` caption (FFmpeg `drawtext`, needs a libfreetype build). `--dry-run` prints the planned ffmpeg command. Full guide: [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE).
 - **Motion-overlay reels** (`vclaw video motion-overlay`) — turn an existing **talking-head video** into a reel with **motion-graphics overlays synced to the speech** via Google Flow's **Omni Flash V2V** (kinetic typography / icons / metaphors painted on the footage, original voice preserved). Plan/dry by default — ingest → Gemini STT (or `--transcript`) → sentence-boundary slice into ≤10s takes → per-take overlay-prompt composition → work folder + manifest + `--preview` review surface, **no spend**. `--execute --confirm-spend` renders each take (V2V → audio-restore → clip-stitch). Four layouts (`split` / `overlay` / `motion-only` / `avatar-host`); the `avatar-host` layout fills the frame with an **identity-locked character host** (go-bananas `generate_with_character` → Veo I2V) and needs `--gb-character <Name:ID>`. Full guide: [`docs/MOTION_OVERLAY.md`](https://videoclaw-docs.vercel.app/reference/MOTION_OVERLAY).
-- **Style-locked motion graphics** (`vclaw video mograph-sheet` / `mograph-pack` / `mograph-render` / `mograph-logos`) — generate **fleets of explainer B-roll clips that share one look with a shared visual reference**. A **motion sheet** (master style-board image + ≤120-word style lock, persisted as `artifacts/motion-sheet.json`) locks the visual system ONCE; a **motion pack** turns the VO into time-coded, **action-only** blocks tagged P1/P2/P3, gated by an anti-drift lint (style words and hex codes are banned from choreography). `mograph-render` is plan-only — it assembles `style lock + SHOT + AUDIO + AVOID` per block and compiles a **batch-queue manifest** for `batch-submit`/`batch-monitor` (free explore lane by default); v2v modes route to omni-flash. Clips carry **sound design only** (never music/VO — they sit under your own narration). Full guide: [`docs/MOGRAPH.md`](https://videoclaw-docs.vercel.app/reference/MOGRAPH).
+- **Style-locked motion graphics** (`vclaw video mograph-sheet` / `mograph-pack` / `mograph-render` / `mograph-logos`) — generate **fleets of explainer B-roll clips that share one look with a shared visual reference**. A **motion sheet** (master style-board image + ≤120-word style lock, persisted as `artifacts/motion-sheet.json`) locks the visual system ONCE; a **motion pack** turns the VO into time-coded, **action-only** blocks tagged P1/P2/P3, gated by an anti-drift lint (style words and hex codes are banned from choreography). `mograph-render` is plan-only — it assembles `style lock + SHOT + AUDIO + AVOID` per block and compiles a **batch-queue manifest** for `batch-submit`/`batch-monitor` (the free Runway explore route by default); v2v modes route to omni-flash. Clips carry **sound design only** (never music/VO — they sit under your own narration). Full guide: [`docs/MOGRAPH.md`](https://videoclaw-docs.vercel.app/reference/MOGRAPH).
 
 - **Music videos** (`vclaw video music-video`) — the **vocal-synced, beat-exact assembler**. From a hand-authored config (song + clip registry + B-roll pools + an explicit vocal map *or* a transcript it auto-classifies into rap / hook / instrumental / outro by **word density**), it pins each performer to **their own vocal** time-aligned across B-roll cutaways (lips stay locked to the muxed song), cuts every segment **frame-exact** (`-frames:v`, never `-t`, so there is **zero cumulative drift**), then concats + applies one grade pass + muxes the song. **Fully local — ffmpeg only, no provider, no spend.** Plan/dry by default; `--execute` renders and asserts the built master matches the plan within one frame. Full guide: [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE).
 
 - **Music-video titles** (`vclaw video title-card`) — burn the **titles you see in music videos** (a faded **lower-third** + a centred **end card** that holds to EOF) onto a finished cut. Text is rasterized via **Pillow + RAQM**, so it works on **any ffmpeg build** (no libfreetype) and **any script** — including **Devanagari/Arabic** (vowel marks shape + stack correctly). Each card is a looped PNG input so delayed alpha fades animate. Fully local, no spend; `--dry-run` plans, omit to render. Full guide: [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE).
 
-- **HD finish / upscale** (`vclaw video finish`) — upscale a rendered cut to a clean HD master via **Topaz** (hosted Proteus/Gaia/Starlight through the apiz/xskill aggregator, or a local Topaz CLI), **Magnific Video Upscaler Precision** (`--backend magnific-precision`, direct Magnific REST, `--target-resolution 1k|2k|4k`), or **free Runway Topaz 4K** (`--backend runway-topaz-free`, useapi `exploreMode` — $0 on a Runway Unlimited plan; chunks the source at the 40 s cap and re-muxes the original audio). Magnific accepts MP4/MOV/AVI/WebM/MKV and ffprobe-preflights every input against its limits (≤15 s / ≤450 frames / ≤150 MB / ≤4K), failing fast unless `--normalize` re-encodes to fit. The **anti-plastic** "detail-not-sharp" recipe (denoise + halo off, film grain kept + clamped to the real 0.1 cap, detail recovery high) avoids waxy skin. Hosted backends are **paid** → refuses without `--confirm-spend` (`--dry-run` plans free); `topaz-local` is free. Hosted needs `APIZ_API_KEY`/`XSKILL_API_KEY` (Topaz) or `MAGNIFIC_API_KEY` (Magnific). Full guide: [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE).
+- **HD finish / upscale** (`vclaw video finish`) — upscale a rendered cut to a clean HD master via **Topaz** (hosted Proteus/Gaia/Starlight through the apiz/xskill service, or a local Topaz CLI), **Magnific Video Upscaler Precision** (`--backend magnific-precision`, direct Magnific REST, `--target-resolution 1k|2k|4k`), or **free Runway Topaz 4K** (`--backend runway-topaz-free`, useapi `exploreMode` — $0 on a Runway Unlimited plan; chunks the source at the 40 s cap and re-muxes the original audio). Magnific accepts MP4/MOV/AVI/WebM/MKV and ffprobe-preflights every input against its limits (≤15 s / ≤450 frames / ≤150 MB / ≤4K), failing fast unless `--normalize` re-encodes to fit. The **anti-plastic** "detail-not-sharp" recipe (denoise + halo off, film grain kept + clamped to the real 0.1 cap, detail recovery high) avoids waxy skin. Hosted backends are **paid** → refuses without `--confirm-spend` (`--dry-run` plans free); `topaz-local` is free. Hosted needs `APIZ_API_KEY`/`XSKILL_API_KEY` (Topaz) or `MAGNIFIC_API_KEY` (Magnific). Full guide: [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE).
 - **Image upscale** (`vclaw video image-ops --op upscale`) — still-image upscaling 2×–16× via **Magnific's image upscaler** (`image-upscaler-precision-v2`, live-verified). Local image is base64-encoded inline; an `http(s)` URL is passed through. `--logo-safe` keeps flat graphics/text crisp without hallucinated texture. **Paid** → `--confirm-spend` (`--dry-run` plans free); needs `MAGNIFIC_API_KEY`.
 
-- **Audio-driven lip-sync** (`vclaw video lipsync`) — a **still/keyframe + a vocal track** → a **lip-synced talking-head clip** via **OmniHuman v1.5** (apiz/xskill). Uploads image+audio → submits → awaits → downloads → **normalizes** to CFR fps + even dims (OmniHuman's 25fps/odd dims otherwise break frame-accurate seeking). Drives an **external** vocal (a rapper's verse, a singer's hook) — the lane's way to put a performer's real vocal on their face. Audio cap enforced up front (1080p≤30s, 720p≤60s). **Paid** → refuses without `--confirm-spend` (`--dry-run` plans free); needs `APIZ_API_KEY`/`XSKILL_API_KEY`. Full guide: [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE).
+- **Audio-driven lip-sync** (`vclaw video lipsync`) — a **still/keyframe + a vocal track** → a **lip-synced talking-head clip** via **OmniHuman v1.5** (apiz/xskill). Uploads image+audio → submits → awaits → downloads → **normalizes** to CFR fps + even dims (OmniHuman's 25fps/odd dims otherwise break frame-accurate seeking). Drives an **external** vocal (a rapper's verse, a singer's hook) — the way to put a performer's real vocal on their face. Audio cap enforced up front (1080p≤30s, 720p≤60s). **Paid** → refuses without `--confirm-spend` (`--dry-run` plans free); needs `APIZ_API_KEY`/`XSKILL_API_KEY`. Full guide: [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE).
 
 ---
 
@@ -565,15 +567,15 @@ sane.
 |---|---|---|
 | **Canonical entry** | `video-framework`, `brand-presenter` | Generic / unspecified video request — the entry skill routes into a specialist. |
 | **Specialist** | `video-storyboard`, `video-clone-ad`, `movie-director`, `video-post`, ... | The mode is clearly known up front. |
-| **Compatibility alias** | `davendra-presenter`, `nex-presenter`, `bunty` | Personal/brand presets that delegate into `brand-presenter`. |
-| **Workflow** | `doctor`, `pipeline`, `worker`, `studio-mode`, ... | Orchestration, debugging, ops — independent of any one production mode. |
+| **Compatibility alias** | `davendra-presenter`, `david-sales-presenter`, `nex-presenter`, `bunty` | Personal/brand presets that delegate into `brand-presenter`. |
+| **Workflow** | `concierge`, `improvement-run`, `deepsearch`, `graphify`, ... | Orchestration, repo ops, search — independent of any one production mode. |
 
 **Rule of thumb:** start at a canonical entry, specialize only when the mode is clearly known.
 
 ### Quick skill map
 
 <details>
-<summary><strong>🎬 Video skills</strong> (15 — click to expand)</summary>
+<summary><strong>🎬 Video skills</strong> (a curated 15 of 40 — click to expand; the <a href="https://videoclaw-docs.vercel.app/skills/video">docs site lists all 40</a>)</summary>
 
 | Skill | Role | One-liner |
 |---|---|---|
@@ -594,23 +596,21 @@ sane.
 | [`ugc`](./skills/ugc) | imported | Belief-driven UGC campaign generator (E5 method). |
 
 **Compatibility aliases** (all delegate into `brand-presenter`):
-[`davendra-presenter`](./skills/davendra-presenter) · [`nex-presenter`](./skills/nex-presenter) · [`bunty`](./skills/bunty)
+[`davendra-presenter`](./skills/davendra-presenter) · [`david-sales-presenter`](./skills/david-sales-presenter) · [`nex-presenter`](./skills/nex-presenter) · [`bunty`](./skills/bunty)
 
 </details>
 
 <details>
-<summary><strong>⚙️ Workflow skills</strong> (13 — click to expand)</summary>
+<summary><strong>⚙️ Workflow skills</strong> (9 — click to expand)</summary>
 
 | Group | Skills |
 |---|---|
-| **Multi-agent orchestration** | [`worker`](./skills/worker) · [`pipeline`](./skills/pipeline) · [`studio-mode`](./skills/studio-mode) |
-| **Diagnostics & exploration** | [`doctor`](./skills/doctor) · [`build-fix`](./skills/build-fix) · [`deepsearch`](./skills/deepsearch) · [`deep-interview`](./skills/deep-interview) |
-| **Review & governance** | [`review`](./skills/review) |
-| **Operational utilities** | [`ai-slop-cleaner`](./skills/ai-slop-cleaner) · [`configure-notifications`](./skills/configure-notifications) · [`skill`](./skills/skill) · [`note`](./skills/note) · [`help`](./skills/help) · [`web-clone`](./skills/web-clone) |
+| **Front door & orchestration** | [`concierge`](./skills/concierge) (speaks as VideoClaw; alias [`videoclaw`](./skills/videoclaw)) · [`improvement-run`](./skills/improvement-run) |
+| **Search & knowledge** | [`deepsearch`](./skills/deepsearch) · [`graphify`](./skills/graphify) · [`web-clone`](./skills/web-clone) |
+| **Review & governance** | [`ai-slop-cleaner`](./skills/ai-slop-cleaner) · [`skills-auditor`](./skills/skills-auditor) |
+| **Design utilities** | [`ui-ux-pro-max`](./skills/ui-ux-pro-max) |
 
-Generic orchestration skills (`autopilot`, `ralph`/`ralph-init`/`ralplan`, `team`, `cancel`,
-`trace`, `hud`, `git-master`, `code-review`, `security-review`, `omx-setup`) were culled —
-they duplicated the operator's global plugin set with zero repo-specific content.
+Generic orchestration skills that duplicated the global plugin set were culled from the repo; use the global versions.
 
 </details>
 
@@ -619,7 +619,7 @@ they duplicated the operator's global plugin set with zero repo-specific content
 
 ---
 
-## 🗂️ Obsidian operator workspace
+## 🗂️ Obsidian workspace
 
 The repo writes a **vault of machine-generated notes** that mirrors canonical project state — dashboards,
 queues, metrics, health, timelines, dependencies, and per-project notes — all regenerated from one command.
@@ -627,7 +627,7 @@ queues, metrics, health, timelines, dependencies, and per-project notes — all
 > **Obsidian is a view, not the source of truth.** The repo state on disk is canonical; the vault is a
 > regenerable rendering of it.
 
-<p align="center"><img src="./docs/assets/diagram-obsidian-loop.jpg" alt="Daily operator loop — five-step circular workflow: make changes via vclaw, sync vault, read Dashboard, triage queue, update metadata, then back to making changes" width="100%" /></p>
+<p align="center"><img src="./docs/assets/diagram-obsidian-loop.jpg" alt="Daily loop — five-step circular workflow: make changes via vclaw, sync vault, read Dashboard, triage queue, update metadata, then back to making changes" width="100%" /></p>
 
 ### What you get
 
@@ -645,7 +645,7 @@ vclaw video export-obsidian --project my-project --output-dir ./ops/obsidian/Pro
 vclaw video sync-obsidian --root . --output-dir ./ops/obsidian        # full regenerate (the common case)
 ```
 
-📖 **Full operator guide** — vault layout, every dashboard note explained, frontmatter schema, daily loop,
+📖 **Full guide** — vault layout, every dashboard note explained, frontmatter schema, daily loop,
 common workflows: **[`docs/OBSIDIAN.md`](https://videoclaw-docs.vercel.app/reference/OBSIDIAN)**
 
 ---
@@ -763,16 +763,16 @@ Current status: **`npm test` green · `check:release-readiness-lite` passing.**
 
 | # | Doc | What it gives you |
 |---|---|---|
-| 1 | [Production workflow](https://videoclaw-docs.vercel.app/reference/PRODUCTION_WORKFLOW) | Operator-first workflow: make, review/fix, and manage video projects |
+| 1 | [Production workflow](https://videoclaw-docs.vercel.app/reference/PRODUCTION_WORKFLOW) | A workflow built around you: make, review and fix, and manage video projects |
 | 2 | [Architecture](https://videoclaw-docs.vercel.app/reference/ARCHITECTURE) | Layer map + canonical flow |
 | 3 | [CLI reference](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE) | Full command reference |
 | 4 | [Skills](https://videoclaw-docs.vercel.app/skills/) | **Comprehensive per-skill reference with features and when-to-reach-for guidance** |
 | 5 | [Story bible](https://videoclaw-docs.vercel.app/reference/STORY_BIBLE) | **Story bible reference — the deterministic continuity artifact, when it's generated, its shape, and how downstream stages use it** |
-| 6 | [Assemble](https://videoclaw-docs.vercel.app/reference/ASSEMBLE) | **`vclaw video assemble` operator guide — pipeline stages, media QC, narration fit, API keys, dry-run vs real render, validation status** |
-| 7 | [Obsidian](https://videoclaw-docs.vercel.app/reference/OBSIDIAN) | **Obsidian operator workspace deep guide — vault layout, dashboard notes, frontmatter schema, daily loop** |
-| 8 | [Reference sheets](https://videoclaw-docs.vercel.app/reference/REFERENCE_SHEETS) | **Reference sheets operator guide — 5 sheet types, role vocabularies, CLI commands, readiness/preflight semantics, GB integration** |
-| 9 | [Scene candidates](https://videoclaw-docs.vercel.app/reference/SCENE_CANDIDATES) | **Scene candidates operator guide — append-only candidates + mutable selection, 9 CLI commands, partial reruns, chain-from-prev, migration** |
-| 10 | [Prompt quality](https://videoclaw-docs.vercel.app/reference/PROMPT_QUALITY) | **Prompt-quality preflight operator guide — Seedance-handbook anti-pattern checks, thresholds, strict-mode blocking** |
+| 6 | [Assemble](https://videoclaw-docs.vercel.app/reference/ASSEMBLE) | **`vclaw video assemble` guide — pipeline stages, media QC, narration fit, API keys, dry-run vs real render, validation status** |
+| 7 | [Obsidian](https://videoclaw-docs.vercel.app/reference/OBSIDIAN) | **Obsidian workspace deep guide — vault layout, dashboard notes, frontmatter schema, daily loop** |
+| 8 | [Reference sheets](https://videoclaw-docs.vercel.app/reference/REFERENCE_SHEETS) | **Reference sheets guide — 5 sheet types, role vocabularies, CLI commands, readiness/preflight semantics, GB integration** |
+| 9 | [Scene candidates](https://videoclaw-docs.vercel.app/reference/SCENE_CANDIDATES) | **Scene candidates guide — append-only candidates + mutable selection, 9 CLI commands, partial reruns, chain-from-prev, migration** |
+| 10 | [Prompt quality](https://videoclaw-docs.vercel.app/reference/PROMPT_QUALITY) | **Prompt-quality preflight guide — Seedance-handbook anti-pattern checks, thresholds, strict-mode blocking** |
 | 11 | [Generation telemetry](https://videoclaw-docs.vercel.app/reference/GENERATION_TELEMETRY) | Generation event ledger + cost-estimate telemetry behavior |
 | 12 | [Operations](https://videoclaw-docs.vercel.app/reference/OPERATIONS) | Day-to-day maintenance loop |
 | 13 | [Templates](https://videoclaw-docs.vercel.app/reference/TEMPLATES) | Template store + clone bridge |
@@ -780,6 +780,7 @@ Current status: **`npm test` green · `check:release-readiness-lite` passing.**
 | 15 | [Deprecation](https://videoclaw-docs.vercel.app/reference/DEPRECATION) | Alias + deprecation status |
 | 16 | [Release readiness](https://videoclaw-docs.vercel.app/reference/RELEASE_READINESS) | Release checklist |
 | 17 | [Master plan alignment](https://videoclaw-docs.vercel.app/reference/MASTER_PLAN_ALIGNMENT) | What's shipped + remaining gaps |
+| 18 | [Shared filmmaking workflow](https://videoclaw-docs.vercel.app/reference/SHARED_FILMMAKING_WORKFLOW) | Structured film plans, contextual acting, reference freshness and full-playback edit evidence |
 
 Skill deep-dives (also indexed in [`docs/SKILLS.md`](https://videoclaw-docs.vercel.app/skills/)):
 
@@ -787,6 +788,21 @@ Skill deep-dives (also indexed in [`docs/SKILLS.md`](https://videoclaw-docs.verc
 - [`skills/video-storyboard/SKILL.md`](./skills/video-storyboard/SKILL.md) · [`skills/video-clone-ad/SKILL.md`](./skills/video-clone-ad/SKILL.md) · [`skills/video-analyze-template/SKILL.md`](./skills/video-analyze-template/SKILL.md) — clean-room native specialists
 - Full catalog in [`skills/README.md`](./skills/README.md) · machine-readable in [`skills/catalog.json`](./skills/catalog.json)
 
+### Working notes & prompts (internal)
+
+Not published to the site; kept in `docs/` for the sessions that use them:
+[`AI_FILMMAKING_PROMPTS`](./docs/AI_FILMMAKING_PROMPTS.md) ·
+[`CODEBASE_REVIEW_PROMPT`](./docs/CODEBASE_REVIEW_PROMPT.md) ·
+[`CONCIERGE_PROMPT`](./docs/CONCIERGE_PROMPT.md) ·
+[`CONCIERGE_COVERAGE_PROMPT`](./docs/CONCIERGE_COVERAGE_PROMPT.md) ·
+[`IMPROVE_PROMPT`](./docs/IMPROVE_PROMPT.md) ·
+[`INFOGRAPHICS_PROMPT`](./docs/INFOGRAPHICS_PROMPT.md) ·
+[`SKILL_COHESION_PROMPT`](./docs/SKILL_COHESION_PROMPT.md) ·
+[`UPDATE_DOCS_PROMPT`](./docs/UPDATE_DOCS_PROMPT.md) ·
+[`ENGINE_ESCAPE_AUDIT`](./docs/ENGINE_ESCAPE_AUDIT.md) ·
+[`SEEDANCE_HARVEST`](./docs/SEEDANCE_HARVEST.md) ·
+[`HIGGSFIELD_MCP_CREATIVE_AGENCY`](./docs/HIGGSFIELD_MCP_CREATIVE_AGENCY.md)
+
 ---
 
 ## 🧬 Where it came from