videoclaw 3.0.0-alpha.1

package/docs/UNIFICATION_AUDIT.md

@@ -0,0 +1,321 @@
+# videoclaw-v2 Unification Audit
+
+> **Status:** Phase A discovery output. Findings here feed into the Phase B
+> unification design and Phase C implementation. No code changes yet.
+>
+> **Audit date:** 2026-05-25
+> **Audit scope:** entrypoints · skills · provider routes · pipeline stages
+
+## Executive summary
+
+videoclaw-v2 today is **four loosely-coupled subsystems sharing a name**:
+
+1. The TS core (`src/video/*` + `vclaw` CLI) operating on `projects/<slug>/` JSON
+   artifacts.
+2. A separate Bun package (`vclaw-cli/`) with its own CLI surface and SQLite
+   job DB, kept alive because Node can't host the Puppeteer/CDP path to Google
+   Flow.
+3. A Python pipeline under `skills/video-replicator/scripts/` (~14 user-facing
+   entrypoints) that produces stitched MP4s end-to-end **with zero code or
+   artifact-format overlap** with the TS pipeline.
+4. 52 skills, of which ~18 are user-facing video verbs and the rest are OMX
+   harness plumbing not in scope for unification.
+
+The four pain points the user named map cleanly to four findings:
+
+| User pain | Root cause from audit |
+|---|---|
+| Too many entrypoints | 3 TS bins + 1 Bun CLI + ~14 Python entrypoints; ~40 env vars; no manifest. |
+| Skill discovery | 6+ confirmed skill-merge candidates; no single "what should I run for X" registry. |
+| Provider routing complexity | Only 3 of 5 routes are production-ready; router exists but ignores half the available signals; `veo-direct` is a phantom (production-marked, no transport). |
+| Manual pipeline | 6 approval/decision gates in director mode; 3 already auto-able via flags; `vclaw video auto` already exists in dispatch but isn't surfaced. |
+
+**The unification has a head start most users don't see**: there is already a
+`vclaw video auto` primitive, a scoring router, route descriptors, and the
+canonical `projects/<slug>/` layout. The gap is **not** "build a new
+orchestrator" — it's "wire what exists into a single front door, retire what
+duplicates it, and decide whether the Python pipeline gets folded in or stays
+separate behind a stable contract."
+
+---
+
+## A. Entrypoints inventory
+
+### A.1 TypeScript CLI binaries
+
+| Binary | Source | Purpose | Status |
+|---|---|---|---|
+| `vclaw` | `src/cli/vclaw.ts` | Primary user-facing CLI. Hand-rolled argparser dispatching `video init/brief/storyboard/assets/review/publish/produce/execute/...`, readiness, plan, doctor, portfolio, review-ui, Obsidian, character/library, template/clone. | **Primary** |
+| `omx` | `src/cli/omx.ts` | One-line legacy alias. Delegates to `vclaw.main()`, prints deprecation notice. Kept alive only by `check:omx-alias`. | **Dead weight** — 1-commit removal |
+| `vclaw-provider-adapter` | `src/cli/provider-adapter.ts` | Built-in adapter binary spawned by `execution-runtime`. Reads JSON on stdin, dispatches to `..._SUBMIT_CMD`/`..._POLL_CMD`/`..._CANCEL_CMD` shims, returns JSON on stdout. | **Internal** (not a real "front door"; could become an internal module via `import()`) |
+
+### A.2 Bun-based CLI (`vclaw-cli/`)
+
+A separate `private: true` Bun package (`vclaw-cli@1.2.0`, engine `bun >=1.3.5`) driving Google Labs Flow via Puppeteer browser automation — a runtime the main Node package can't host (real-browser CDP, headful login, reCAPTCHA execution, FileChooser uploads). Single entry is `vclaw-cli/flow.ts`, invoked as `bun run flow.ts`.
+
+It exposes **its own duplicate subcommand surface**: `status | list | history | resume | reset | cancel | help` (SQLite-backed batch tracking) + `useapi:accounts | captcha | health | image | image:upscale | gif | upscale` + `sync` (Convex migration). Backend selection via `--backend direct|useapi`.
+
+`native-veo.ts` already bridges the two by spawning the Bun CLI as a subprocess. The 7+ standalone subcommands in `flow.ts` (status/list/history/resume/reset/cancel + useapi:*) duplicate functionality available through `vclaw` and could collapse into a single `vclaw veo:*` subtree.
+
+### A.3 Python user-facing entrypoints (14)
+
+All but two live under `skills/video-replicator/scripts/`. They are referenced from `bunty`, `davendra-presenter`, `nex-presenter` SKILL.mds **without a manifest** — discoverability is via grep.
+
+| Script | Skill(s) | Purpose |
+|---|---|---|
+| `bunty_match_to_deck.py` | bunty | Match Bunty narration → slide pages |
+| `bunty_narration_check.py` | bunty, presenters | Narration QA / linter |
+| `bunty_image_filter_check.py` | bunty, presenters | Image-filter QA pass |
+| `bunty_regen.py` | bunty | Regen intro/outro segments by location |
+| `parallel_video_gen.py` | bunty, presenters | **Parallel video-gen runner** (the Bunty/Nex pipeline core) |
+| `generate_tts.py` | bunty, presenters | Text-to-speech |
+| `generate_music.py` | bunty, presenters | Background music |
+| `generate_title_card.py` | bunty, nex-presenter | Title-card image |
+| `stitch_bunty.py` | bunty | **Final stitch**: narration + slides + b-roll → MP4 |
+| `bunty_animate_slides.py` | bunty, presenters | Animate static slides → motion clips |
+| `extract_pdf_slides.py` | bunty, presenters | Extract slides from PDF deck |
+| `nex_assemble.py` | nex-presenter, davendra-presenter | **Final assembly** for Nex/Davendra episodes |
+| `brand_episode.py` | nex-presenter | One-shot brand-episode orchestrator |
+| `search.py` | ui-ux-pro-max | Design-system reference search |
+
+### A.4 Provider adapter env-var contract
+
+Resolved in `execution-runtime.ts:19-32` and `provider-status.ts:49-59`. `..._ADAPTER` wins if set; otherwise built-in `vclaw-provider-adapter --route <id>` is spawned for the 3 routes that have a fallback.
+
+| Env var | What it expects |
+|---|---|
+| `VCLAW_VEO_DIRECT_ADAPTER` | **Required** for `veo-direct` (no built-in fallback exists) |
+| `VCLAW_VEO_USEAPI_ADAPTER` | Override; built-in fallback available |
+| `VCLAW_SEEDANCE_DIRECT_ADAPTER` | Override; built-in fallback available |
+| `VCLAW_RUNWAY_USEAPI_ADAPTER` | Override; built-in fallback available |
+| `VCLAW_KLING_USEAPI_ADAPTER` | **Required** — no built-in (scaffold route) |
+| `VCLAW_<ROUTE>_{SUBMIT,POLL,CANCEL}_CMD` (×3 routes) | Shell commands the built-in adapter pipes JSON in/out of |
+| `VCLAW_VEO_BUN_BIN` | Path to local Bun binary for native-veo |
+
+### A.5 Cross-cutting observations
+
+- **Two parallel video-gen pipelines.** `vclaw video execute` (TS) and the Python Bunty/Nex chain (`parallel_video_gen.py` + `stitch_bunty.py` + `nex_assemble.py`) both produce stitched MP4s. **Zero shared code, zero shared artifact format.** Strongest unification candidate.
+- **Two runtimes.** Node + Bun, kept apart only because Puppeteer/CDP needs Bun's faster startup + real-browser support. `native-veo.ts` already bridges. Bun CLI's standalone subcommands are duplication.
+- **Three storage runtimes.** `projects/<slug>/` JSON (canonical), Bun SQLite `veo-cli.db` (job tracking), optional Convex (migration target). Pick one.
+- **`omx` is dead weight.** 1-commit removal.
+- **No skills entrypoint manifest.** 14 Python scripts, no `__entrypoints__.json`. A `scripts/cli.py` dispatcher (`python -m videoreplicator <verb>`) would collapse this to one addressable surface.
+
+---
+
+## B. Skills catalog audit (52 skills)
+
+### B.1 Status breakdown (from `skills/catalog.json`)
+
+- **18 user-facing video skills** (presenters, movie-director, creative-brief, ugc, character-creator, video-replicator, video-thumbnail-lab, video-post, studio-mode, video-framework, etc.)
+- **20 orchestration-internal** (video-storyboard, video-clone-ad, video-analyze-template, video-portfolio-ops, ralph, autopilot, team, worker, pipeline, cancel — OMX harness plumbing, **out of scope for unification**)
+- **9 utility/library** (trace, hud, doctor, skill, configure-notifications, git-master, omx-setup, skills-auditor — also out of scope)
+- **5 redundant/alias** (bunty / davendra-presenter / nex-presenter → brand-presenter; movie-director vs director-video; video-replicator vs video-framework)
+- **1 orphan**: `video-replicator-workspace/` on disk, **not** in catalog.json — vestigial, safe to delete
+
+### B.2 High-value consolidations (ordered by ROI)
+
+| # | Consolidation | Effort | Rationale |
+|---|---|---|---|
+| 1 | **Presenter family → parametric `brand-presenter`** | ~1 day | Catalog already declares 3 children as `alias`. Each child SKILL.md duplicates ~500 lines of workflow with only `character_id` + brand strings changing. Make `brand-presenter` parametric on `brand-profile.json`; reduce children to 20-line profile stubs. |
+| 2 | **`video-framework` as sole front door; demote `video-replicator`** | ~half day | Both currently claim "front door" role; `video-replicator` self-describes as legacy 7-mode reference and says "use video-framework as front door". Keep video-framework, move video-replicator content to references. |
+| 3 | **Fold `creative-brief` into `video-framework`** | ~half day | creative-brief is a 7-question intake; video-framework needs exactly that. Merge as the intake mode. |
+| 4 | **Merge `movie-director` ← `director-video`** | ~half day | Same Director-mode pipeline, near-identical triggers. movie-director is richer (12 genres, interview/auto/hybrid). Fold director-video, alias it. |
+| 5 | **Delete `video-replicator-workspace/` orphan** | 1 commit | Not in catalog.json. |
+| 6 | **Merge `seedance-prompts` + `seedance-music-video-prompts`** | ~quarter day | Music-video is strict subset. Keep one with `--music-video` subsection. |
+| 7 | **`character-creator` + `character-library` → `characters`** | ~quarter day | Clean halves. Consider merging into one skill with `create|list|audit|patch|delete` sub-actions, or keep split if intentional. |
+
+### B.3 User-facing entry verbs (what unification front door should expose)
+
+- "make me a video" → **video-framework** (intake + routing)
+- "make a presenter / Bunty / Davendra / Nex video" → **brand-presenter** (parametric)
+- "make me a short film / movie / cinematic ad" → **movie-director**
+- "make me a UGC ad campaign" → **ugc**
+- "clone / analyze this ad" → **video-clone-ad**, **video-analyze-template**
+- "make a thumbnail / post-process / package" → **video-thumbnail-lab**, **video-post**
+- "manage my characters" → **character-creator** (+ library)
+- "studio mode (interview-driven)" → **studio-mode**
+- "download from youtube" → **youtube-audio**
+
+~10 verbs. Everything else is plumbing.
+
+### B.4 Vestigial / drop
+
+- `video-replicator-workspace/` (orphan)
+- `video-replicator` SKILL (superseded; keep only if external docs name it)
+- `bunty`, `davendra-presenter`, `nex-presenter` SKILL.md (collapse to brand-profile stubs after #1)
+- `director-video` (superseded by movie-director)
+- `creative-brief` (folded into video-framework)
+- `seedance-music-video-prompts` (folded)
+
+---
+
+## C. Provider routes inventory
+
+### C.1 Route status
+
+| Provider | Route ID | Native? | Built-in adapter? | Tests/smoke? | Status |
+|---|---|---|---|---|---|
+| Veo | `veo-direct` | No | No | Routing tests only | ⚠️ **Phantom**: marked `production` but `execution-runtime.ts:34-40` excludes from builtin dispatch — throws unless `VCLAW_VEO_DIRECT_ADAPTER` set |
+| Veo | `veo-useapi` | ✅ `native-veo.ts` (spawns Bun + `vclaw-cli/flow.ts`) | ✅ | `native-veo.test.ts`, `smoke:native-veo` | **Production-ready** (depends on Bun + Google Flow cookies) |
+| Seedance | `seedance-direct` | ✅ `native-seedance.ts` (pure Node fetch) | ✅ | `native-seedance.test.ts`, `smoke:execution-cancel` | **Production-ready** |
+| Runway | `runway-useapi` | ✅ `native-runway.ts` (pure Node fetch) | ✅ | `native-runway.test.ts`, `runway-useapi.test.ts` | **Production-ready** ⚠️ no real cancel — local state only |
+| Kling | `kling-useapi` | No | No | Asserts `degraded` only | **Scaffold** |
+
+**Only 3 of 5 routes are usable today**: `veo-useapi`, `seedance-direct`, `runway-useapi`.
+
+### C.2 Env vars per route
+
+| Route | Required | Optional |
+|---|---|---|
+| `veo-direct` | (none registered, but unusable without `_ADAPTER` shim) | — |
+| `veo-useapi` | `USEAPI_API_TOKEN`, `USEAPI_ACCOUNT_EMAIL` | `VCLAW_VEO_CLI_ROOT`, `_OUTPUT_DIR`, `_BUN_BIN`, `_COMMAND_TIMEOUT_MS`, Flow cookies |
+| `seedance-direct` | `SUTUI_API_KEY` | `VCLAW_SEEDANCE_BASE_URL` |
+| `runway-useapi` | `USEAPI_API_TOKEN` | `VCLAW_RUNWAY_MODEL`, `VCLAW_RUNWAY_MODE` |
+| `kling-useapi` | (declared but no transport reads them) | — |
+
+Universal: `GEMINI_API_KEYS` / `GOOGLE_API_KEYS` / `GOOGLE_API_KEY` for analyze; not tied to a transport.
+
+### C.3 Auto-routing potential
+
+`router.ts` already scores routes by:
+- Operation kind (T2V / I2V / F2V / I2gV / V2V / add-audio / extend / edit)
+- Aspect ratio (`veo-useapi` +25 for portrait I2V/F2V — only auto-unlock today)
+- Workflow tag (product-demo-spokesperson, ad-creative-variants, generic)
+- Cost / latency preference
+- Required controls (audio, lip-sync, multi-shot)
+- Route health (offline/deprecated/degraded filter)
+
+**Not yet used**: duration (Runway 5/8/10/15, Seedance ≤15s), input MIME (derived in execution-runtime but not surfaced to router), resolution, `generateAudio` flag. Wiring these would let the router auto-pick for ~all common cases.
+
+### C.4 Merge candidates
+
+- **`veo-direct` + `veo-useapi` → single `veo` provider**, transport auto-picked. Today `veo-direct` is unusable without an external shim — a smart `veo` provider would transparently fall through to `useapi` when no direct adapter exists.
+- **Shared `useapi-client.ts`** for the 3 UseAPI routes (token + base URL + asset upload). Removes duplication in `native-runway.ts:140-161` + `providers/runway-useapi.ts`.
+- **Extract `native-shared.ts`** before adding a 4th native transport — `native-seedance.ts` and `native-runway.ts` already share `readDotEnvLike`, `loadWorkspaceEnv`, `jobStateDir`, `classifyReferences`, `downloadToFile`.
+
+### C.5 Open questions
+
+- Downgrade `veo-direct` to `scaffold` until `vclaw-cli/flow.ts --backend google-flow` is wired in `native-veo.ts`?
+- Surface `cancelSemantics: 'local-only' | 'server-side'` on the registry so operators don't expect a real cancel for Runway?
+- `kling-useapi` declares `USEAPI_ACCOUNT_EMAIL` required but no code reads it — stale from Joey-Flags era? Drop?
+- Only `smoke:native-veo` exercises a live transport. Add `smoke:native-seedance` + `smoke:native-runway` (gated on env vars) to catch transport regressions before release?
+
+---
+
+## D. Pipeline stages, artifacts, env vars
+
+### D.1 Canonical stage order
+
+Two modes (`storyboard`, `director`) share the order; director adds the `storyboard.md` gate.
+
+| Stage | User invokes | Produces | Auto-advance? |
+|---|---|---|---|
+| init | `vclaw video init <slug> [--mode]` | `project.json` + dirs | ✅ Yes (pure scaffold) |
+| brief | `vclaw video brief --project ... --title --intent ...` | `brief.json` + checkpoint | ✅ Yes if title+intent supplied |
+| storyboard | `vclaw video storyboard --project ... --scene ... \| --template ...` | `storyboard.json` + checkpoint (director: also `storyboard.md`) | ✅ Yes if template+characters resolve |
+| **director gate** | `vclaw video storyboard-review` → human edits `storyboard.md` → `vclaw video approve` | rewrites checkpoint status → `approved` | ❌ unless `VIDEOCLAW_APPROVE_STORYBOARD=1` |
+| assets | `vclaw video assets --project --asset kind:path...` | `asset-manifest.json` | ✅ already `humanApprovalDefault: false` |
+| readiness | `vclaw video readiness --project` | `readiness.json` | ✅ diagnostic only |
+| plan | `vclaw video plan` (alias `execution-plan`) | `execution-plan.json` | ✅ derived from manifest |
+| execute | `vclaw video execute --project [--dry-run]` (alias `produce`) | `execution-report.json` + events | ⚠️ Conditional — director blocks on stale review |
+| execute-status | `vclaw video execute-status --project` | refresh `execution-report.json` | ✅ pure poll |
+| review | `vclaw video review --verdict pass\|retry\|fail` (or `review-autopilot`) | `review-report.json` + checkpoint | 🟡 `review-autopilot` exists |
+| publish | `vclaw video publish --status ready\|published\|blocked` | `publish-report.json` + checkpoint | 🟡 needs thin auto wrapper |
+
+### D.2 Artifacts and schemas
+
+All under `projects/<slug>/artifacts/`; schemas in `schemas/video/artifacts/`. Side files: `project.json`, `storyboard.md`, `checkpoints/<stage>.json` (×5), `events/events.jsonl`, `state/`, `characters/characters.json`.
+
+13 artifact JSONs: brief, storyboard (+ scene-candidates, scene-selection, reference-sheets in director), asset-manifest, readiness (no schema), execution-plan, execution-report, review-report, publish-report, analyze-output, clone-plan, character-consistency.
+
+### D.3 Approval gates — implication for creator mode
+
+**6 decision points in director mode, 3 in storyboard mode.**
+
+- 3 of 6 already auto-able via flags (brief, storyboard, assets).
+- 1 has env-var bypass (director storyboard.md → `VIDEOCLAW_APPROVE_STORYBOARD=1`).
+- 2 need thin auto wrappers (review-autopilot exists; publish needs `ready` vs `blocked` heuristic from review verdict + final-media presence).
+
+**`vclaw video auto` already exists in dispatch** (`vclaw.ts:3090`) alongside `create`, `iterate`, `run-pipeline`. These are the existing primitives a unified creator-mode entrypoint should wrap.
+
+### D.4 Env-var burden
+
+**~40+ env vars** with no committed `.env.example`. Grouped:
+- Director toggles (`DIRECTOR_PREFLIGHT`, `_STRICT_PROMPT_QUALITY`, `_STRICT_DIALOGUE_FIT`, `_AUTO_FIX_CONTENT`, `_GENRE_DEFAULTS`, `_INFERENCE_RULES`)
+- Approval bypass (`VIDEOCLAW_APPROVE_STORYBOARD`)
+- Provider keys (`USEAPI_*`, `SUTUI_API_KEY`, `GEMINI_*`, `GOOGLE_*`, `GO_BANANAS_*`)
+- Veo transport (`VCLAW_VEO_*` × ~8 vars)
+- Runway transport (`VCLAW_RUNWAY_*` × ~6 vars)
+- Seedance transport (`VCLAW_SEEDANCE_*` × ~5 vars + `SEEDANCE_*`)
+- Workspace (`VIDEOCLAW_ROOT`, `VCLAW_DEMO_PAUSE_MS`)
+
+A committed `.env.example` + a `vclaw doctor env` subcommand listing what's set / missing per provider would meaningfully reduce setup friction.
+
+---
+
+## Cross-cutting findings → unification design inputs
+
+The four audits converge on five concrete unification opportunities, ordered by ROI:
+
+### F1. Single front door: `vclaw make "<intent>"`
+
+**Foundation already exists**: `vclaw video auto`, `vclaw video create`, scoring router, pipeline manifests, project-state layout. Wire them behind one user-friendly command that:
+
+1. Takes a natural-language intent.
+2. Picks the right skill (video-framework / brand-presenter / movie-director / ugc) by intent classification.
+3. Picks the right provider route via the existing router (after C.3 enhancements).
+4. Walks the pipeline with all gates auto-cleared (`VIDEOCLAW_APPROVE_STORYBOARD=1` + `review-autopilot` + auto-publish).
+5. Falls back to interactive prompts at any gate the user wants to inspect.
+
+**Estimated effort**: 1-2 weeks.
+
+### F2. Collapse the two video-gen pipelines (TS vs Python)
+
+**The biggest seam in the system.** Two options:
+
+- **F2a — Fold Python into TS**: rewrite the Bunty/Nex Python pipeline as TS modules calling the same providers via the existing router. ~3-4 weeks. Removes a whole runtime.
+- **F2b — Stable contract**: keep Python as a peer pipeline behind a documented JSON-in/JSON-out contract, register it as a provider/skill, surface it through F1. ~1 week. Less ambitious but preserves working code.
+
+Recommendation pending — **needs a decision call** in Phase B.
+
+### F3. Collapse `vclaw-cli` Bun standalone surface into `vclaw veo:*`
+
+Bun stays as a runtime (Puppeteer requirement) but its standalone subcommands (`status | list | history | resume | reset | cancel | useapi:*`) move under `vclaw veo:*` in the main TS CLI, which shells out to Bun as needed.
+
+**Estimated effort**: ~1 week.
+
+### F4. Skill consolidation (B.2 items 1-7)
+
+Independent of the other lanes; can ship incrementally.
+
+**Estimated effort**: ~3 days total across all 7 items.
+
+### F5. Operator polish
+
+- Delete `omx` alias (1 commit).
+- Delete `video-replicator-workspace/` orphan (1 commit).
+- Commit `.env.example`.
+- Add `vclaw doctor env`.
+- Downgrade `veo-direct` to scaffold or wire its native transport via `vclaw-cli/flow.ts --backend google-flow`.
+- Add `smoke:native-seedance` and `smoke:native-runway`.
+
+**Estimated effort**: ~2 days.
+
+---
+
+## Open questions for Phase B
+
+1. **F2 decision: fold Python (F2a) or keep as peer (F2b)?** This shapes the whole unification.
+2. **Front door command name**: `vclaw make`? `vclaw create`? Something else? Should the operator-mode `vclaw video *` flow stay or get hidden behind a `--operator` flag?
+3. **Storage**: collapse to one (drop Bun SQLite + Convex) or three with a clear ownership boundary?
+4. **`kling-useapi`**: invest in a real transport or drop the route entirely?
+5. **Coverage tooling**: still nothing. Add c8 + per-module thresholds, or punt?
+
+---
+
+## Phase A complete. Next step: Phase B design.
+
+This document is read-only output of Phase A. Phase B should:
+- Resolve the 5 open questions above
+- Write `docs/superpowers/specs/2026-05-25-videoclaw-v2-unification-design.md`
+- Sequence F1–F5 into shippable slices

package/docs/UPDATE_DOCS_PROMPT.md

@@ -0,0 +1,78 @@
+# Update-all-docs prompt (Opus 4.8)
+
+A prompt to bring every videoclaw doc back in sync with the current code after a period of
+heavy change. Authored with the `prompting-opus-4-8` skill — tuned for Opus 4.8's literal
+scope-following (the doc set is enumerated, not sampled), its low default subagent count
+(explicit fan-out), and its preference for reasoning over tools (explicit verify-against-code).
+
+Run at **xhigh** effort, and set a large max output budget (start ~64k) so the parallel
+subagents have room.
+
+```text
+You're working on videoclaw-v3 (the `vclaw` CLI). The codebase has changed a lot recently
+and the documentation has drifted. Bring EVERY doc back into sync with the current code.
+Documentation accuracy is the goal: every command, flag, artifact, schema, and workflow a
+doc describes must match what the code actually does today.
+
+Ground truth is the code, not your memory or the existing prose. The authoritative sources
+for what exists are: the COMMANDS array in src/video/cli-schema.ts (and its count assertion
+in src/tests/cli-schema.test.ts), `vclaw --help` and per-command `--help` output, the
+handlers in src/cli/handlers/, the JSON Schemas in schemas/video/, and the skills in
+skills/ with skills/catalog.json. When a doc disagrees with these, the doc is wrong — fix
+the doc to match the code (do not change code to match docs).
+
+Scope is ALL of these, not a sample. Update every one that has drifted:
+- README.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/BRAND_AGENCY.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/adr/* (architecture decision records — keep decisions intact; only fix factual drift)
+- docs/agents/* (issue-tracker, triage-labels, domain)
+- every skills/<name>/SKILL.md and skills/catalog.json (descriptions must match what each
+  skill/command now does)
+- the CLAUDE.md command/architecture descriptions if they have gone stale
+- the VitePress site under docs-site/ (its pages mirror the docs above — sync them too)
+Treat this list as exhaustive: review each entry, don't generalize from the first few.
+
+Spawn parallel subagents to do this — Opus does not fan out on its own. Dispatch one
+subagent per doc cluster (e.g. CLI reference, architecture, studio/workflow, audio/assemble,
+skills, docs-site) to audit its docs against the code concurrently, and keep working while
+they run. Each subagent reports a drift list (doc location -> what's stale -> the correct
+current behavior with the file/command that proves it).
+
+Work in two passes:
+1. AUDIT (parallel): produce a single consolidated drift inventory across all docs. Then
+   show me that inventory and a short plan, and pause once for me there. If a doc is already
+   accurate, say so and leave it untouched — don't churn correct prose.
+2. UPDATE (after I approve): fix every confirmed drift. New/renamed/removed commands and
+   flags, changed artifact shapes, new skills, the current command count, moved file paths,
+   and dead references all get corrected. Add docs for genuinely undocumented commands or
+   skills that now exist. Keep each doc's existing structure, voice, and depth — you're
+   correcting facts, not rewriting style.
+
+Conventions and guardrails:
+- Match house style exactly: machine-readable examples, exact command syntax, kebab-case
+  filenames, the .js import extensions when you reference source. Don't reformat a doc you
+  aren't otherwise changing.
+- Do NOT hand-edit the architecture diagram JPGs under docs/assets/ — those are generated
+  from the Mermaid sources in docs/DIAGRAMS_SOURCE.md. If a diagram is stale, update the
+  Mermaid block and note that the image needs regeneration; don't touch the JPG.
+- The repo has doc guardrails: run `npm run check:cleanroom-docs` and
+  `npm run check:skill-frontdoor` and keep them green; if you change skills/catalog.json keep
+  its parity test passing; if the command count changed, update the assertion in
+  cli-schema.test.ts. Run `npm run build` and `npm test` before declaring done.
+
+Verify before you claim done. Before reporting a doc as fixed, confirm the corrected
+statement against the actual code/--help output you read this session — quote the source.
+If you couldn't verify something, flag it rather than guessing. Report faithfully: list
+which docs you changed, which you confirmed already-correct, and anything you couldn't
+verify.
+
+When you finish, lead with the outcome — how many docs were stale, how many you corrected,
+and that the guardrails and build pass — then the per-doc detail. Plain sentences, each doc
+and command its own clause.
+```

package/docs/assets/demo-quickstart.cast

@@ -0,0 +1,13 @@
+{"version":3,"term":{"cols":100,"rows":28,"type":"xterm-256color"},"timestamp":1776896128,"idle_time_limit":2.0,"command":"node scripts/demo-quickstart.mjs","env":{"SHELL":"/bin/zsh"}}
+[0.100, "o", "vclaw-video-core · 60-second tour\r\nexplicit artifacts · multi-provider · no silent fallbacks\r\n\r\n"]
+[0.600, "o", "▶ vclaw video init demo-ad\r\n  ✓ project ready · next stage: brief\r\n\r\n"]
+[0.900, "o", "▶ vclaw video brief --project demo-ad --title \"Launch tease\" --intent \"15s reveal\"\r\n  ✓ brief.json written · shorts · 9:16 · 1080p · 2 outputs\r\n\r\n"]
+[0.900, "o", "▶ vclaw video storyboard --project demo-ad --scene hook --scene reveal --scene cta\r\n  ✓ 3 scenes written · storyboard.json\r\n\r\n"]
+[0.900, "o", "▶ vclaw video assets --project demo-ad --asset image:logo.png:0:seedance\r\n  ✓ 1 asset pinned · ready to plan\r\n\r\n"]
+[0.900, "o", "▶ vclaw video plan --project demo-ad\r\n  ✓ route: seedance-direct · dry-run safe\r\n\r\n"]
+[0.900, "o", "▶ vclaw video produce --project demo-ad --dry-run\r\n  ✓ dry-run passed · no provider submission\r\n\r\n"]
+[0.900, "o", "▶ vclaw video status --project demo-ad\r\n  ✓ next: assets · review state: missing\r\n\r\n"]
+[0.900, "o", "▶ vclaw video report\r\n  ✓ portfolio · 1 project(s) · machine-readable JSON\r\n\r\n"]
+[0.900, "o", "▶ vclaw video export-obsidian --project demo-ad\r\n  ✓ Obsidian note exported · .../vault/Projects/demo-ad.md\r\n\r\n"]
+[0.400, "o", "done · your campaign is JSON on disk.\r\ngithub.com/davendra/vclaw-video-core\r\n"]
+[0.005, "x", "0"]

package/docs/preview-portal-audit.md

@@ -0,0 +1,151 @@
+# Preview Portal Audit
+
+The review and delivery portal standardizes the separate HTML files that were
+previously generated by project-specific scripts.
+
+| Example | Surface | Controls | Lightbox | Downloads | Notes |
+|---|---|---:|---:|---:|---|
+| `guardians-of-the-dawn/review.html` | editor review | yes | yes | partial | Source for editor approve/regenerate controls and copyable agent handoff. |
+| `guardians-of-the-dawn/client-review.html` | client review | simplified | yes | partial | Source for client approve/decline/comment mode. |
+| `mirchi-mode/preview.html` | final preview | no | no | yes | Source for final showcase and download behavior. |
+| `dhuaan-music-video/preview.html` | project preview | no | no | no | Should migrate to generated `music-video` preview. |
+
+## Standard Surfaces
+
+The portal generates **two** surfaces per project: a tabbed **Review** (the
+feedback loop) and a clean **Preview** (the deliverable). Review and Preview are
+opposite jobs — Review exists to *change* the output (feedback → regenerate, via
+the copy→paste-back-to-Claude protocol); Preview exists to *show* the finished
+output for upload/delivery. The former `edit` / `client-review` / `compare`
+pages are consolidated **into Review** (a Decide/Compare tab set + an
+editor↔client mode toggle); they remain valid `--surface` aliases for
+back-compat but are no longer generated by default.
+
+| File | Audience | Purpose |
+|---|---|---|
+| `review.html` | operator ↔ Claude (+ client mode) | The single feedback surface. **Decide** tab: approve/regenerate per unit → `VIDEOCLAW_REVIEW_DECISIONS` copy. **Compare** tab: run/version comparison. A low-key **client mode** toggle swaps controls to approve/decline/comment → `VIDEOCLAW_CLIENT_FEEDBACK` copy. Absorbs the old edit/client-review/compare surfaces. |
+| `preview.html` | final viewer | Polished, **controls-free** deliverable: click-to-fullscreen lightbox on every production image, a soundtrack `<audio controls preload="none">` player (when a soundtrack is discovered), aspect-aware sizing, and asset downloads. The upload artifact. |
+| `projects/index.html` | operator | Portfolio index across generated projects (links to each project's Review + Preview). |
+| `projects/clients/<client>/index.html` | client/operator | Client-filtered index across that client's projects. |
+
+> Aliases: `--surface edit` and `--surface review` both render `review.html`
+> (editor mode default); `--surface client-review` renders it with client mode
+> default; `--surface compare` renders the standalone compare page. Default
+> generation is `['review','preview']`.
+
+## Template Registry
+
+The renderer keeps the HTML structure consistent while adapting section labels
+and ordering for `music-video`, `story-film`, `documentary`, `product-ad`,
+`sports-recap`, and `generic-video`. Projects can set `template` or
+`previewTemplate` in `project.json`; unknown values fall back to
+`generic-video`.
+
+The portal also reads `artifacts/asset-manifest.json` for image assets used by
+generation routes. Local project-scoped image inputs are rendered in a dedicated
+generation-input section; for Seedance-backed assets this appears as
+`Seedance Input Frames` in the music-video template. This makes the exact
+start-frame/upscaled image being sent into Seedance visible beside the resulting
+clip, instead of relying only on the generic `images/` folder.
+
+When `artifacts/filmmaking-prompts.json` exists, the portal exposes it under the
+prompt-packet section, labelled `Seedance Prompt Packets` for music-video
+projects. That gives reviewers one place to inspect the generated `@image`
+reference map, character-sheet prompts, 9-panel storyboard-grid prompt, and
+Seedance packet text before or after video generation.
+
+## Per-Scene Submit Contract
+
+Each storyboard scene card renders the exact contract that will be submitted for
+that scene, expanded inline (no click-to-reveal), so an operator can confirm
+"exactly what you're going to get" before any render spend:
+
+- **Submit prompt — what the model receives.** The resolved provider submit text
+  is the `seedancePackets[].promptText` (the 10-block master prompt) from
+  `artifacts/filmmaking-prompts.json`, matched to the scene by `sceneIndex`. The
+  lighter storyboard `scenePrompt` fields (`imagePrompt`, `animationPrompt`,
+  `styleFooter`) are shown alongside it. This is the convergence point where the
+  multi-shot plan, the cinematography registers, and the story-bible continuity
+  all land in one packet.
+- **References — identity lock.** Each `seedancePackets[].references` slot is
+  rendered with its role, a `ready`/`pending` badge, and the binding. For
+  character-sheet slots the binding is the `Asset://` URI resolved from
+  `artifacts/seedance-assets.json` by character name (preferring `intlAssetUri`);
+  an unregistered character renders as `<name> · unregistered`. Discovered
+  character reference thumbnails are shown beneath the slots. This lets a reviewer
+  confirm which avatar locks which scene, and that every required reference is
+  ready, before submitting.
+
+The data is sourced entirely from on-disk artifacts (`storyboard.json`,
+`filmmaking-prompts.json`, `seedance-assets.json`); the card falls back
+gracefully (omitting the missing block) when an artifact is absent.
+
+## Soundtrack Player
+
+The `preview` showcase discovers a project soundtrack and, when one exists,
+renders a `<audio controls preload="none">` player in the header strip.
+Discovery prefers an explicit `soundtrack` or `audio` field in `project.json`
+that resolves to an existing project-local audio file, then falls back to the
+first discovered audio asset (`.mp3`/`.m4a`/`.wav`/`.aac`). When no soundtrack
+is found, no `<audio>` element is emitted (no broken/empty player). The player
+is preview-only; the editor/review/client-review decision surfaces are
+unchanged.
+
+## Lightbox on Production Images
+
+Every production image rendered by the showcase carries
+`data-lightbox-group` (and `data-lb-caption` where a caption exists) so the
+shared `initLightbox` makes each image click-to-fullscreen with caption and
+Escape-to-close, with no per-project hand-wiring.
+
+## Empty-preview guardrail
+
+When a project has no renderable media, `generatePreviewPortalSurfaces` returns
+a non-empty `warnings` array (echoed to stderr by the `vclaw video portal`
+handler) instead of a silently empty page. The usual cause is that the finished
+cut was staged at the workspace root rather than under
+`projects/<slug>/final/{videos,images,audio}` — the only location the portal
+scans. The pure, exported `previewPortalMediaWarnings()` computes the list;
+`warnings` is always present (empty when media exists) and the stdout JSON stays
+machine-readable.
+
+## Publish Contract
+
+`vclaw video publish-preview` builds a deterministic R2 upload plan from the
+HTML file and its local `src`/`href` references. `vclaw video
+publish-portal-index` uploads a client or global index whose links point into
+the published run folders.
+
+```bash
+vclaw video publish-preview \
+  --project <slug> \
+  --client <name> \
+  --bucket <bucket> \
+  [--run <id>] \
+  [--surface edit|review|client-review|preview|compare|index] \
+  [--public-base-url <url>] \
+  [--wrangler-bin <path>] \
+  [--dry-run]
+```
+
+`--project`, `--client`, and `--bucket` are all **required** — the handler
+throws if any is missing. `--surface` defaults to `preview`. The `client`,
+`project`, and `run` path segments are slugified before forming the R2 key, so
+the upload prefix is `clients/<slugified-client>/<slugified-project>/runs/<slugified-run>/`.
+
+Each plan item includes:
+
+- local file path
+- remote R2 key under `clients/<client>/<project>/runs/<run>/`
+- content type
+- SHA-256 hash
+- public URL when `--public-base-url` is provided
+
+Use `--dry-run` first to inspect the plan. Running without `--dry-run` executes
+`wrangler r2 object put` for each item and appends a `surface.published` event
+to `project-audit.jsonl`. Use `--wrangler-bin <path>` to pin a specific
+Wrangler executable in CI or agent automation.
+
+Published project pages live under
+`clients/<client>/<project>/runs/<run>/`. Published client indexes live at
+`clients/<client>/index.html` and link to those project/run pages.