videoclaw 3.0.0-alpha.1

package/docs/AGENT_INTEGRATION_RESEARCH.md

@@ -0,0 +1,123 @@
+# Agent Integration Research
+
+> **Status:** Phase 9b research output. Two parallel investigations into
+> current best practices (May 2026) for how CLI tools integrate with agentic
+> coding tools and what makes a CLI "agent-friendly."
+>
+> **Research date:** 2026-05-25
+> **Purpose:** Inform the v2→v3 unification design — specifically the question
+> "should videoclaw build its own orchestration layer (intent classifier, NL
+> front door, skill router) or be a clean CLI that external agents drive?"
+
+## Headline finding
+
+**Universal across all 2026 data points: intent classification is the host's
+job, not the CLI's job.** Every successful example — Language Server Protocol,
+Model Context Protocol, Claude Code skills, Warp's natural-language terminal,
+the CLI-Anything project — moves intent OUTSIDE the tool. No mainstream CLI
+has built its own NL front door successfully. Where intent classification
+exists, it lives in the terminal / IDE / agent runtime.
+
+**Quantitative penalty for getting this wrong:** A 2026 benchmark cited in
+the research found agents calling raw CLIs beat MCP-wrapped equivalents
+**10-32× on token cost** and **100% vs 72% on reliability**. Embedding an LLM
+intent layer inside the CLI itself is even worse — adds tokens, adds
+maintenance, adds prompt-injection surface, locks the CLI to a model
+provider.
+
+## Agent-CLI integration mechanisms (May 2026)
+
+| Mechanism | Maturity | Best for | Cost to expose | Discoverability |
+|---|---|---|---|---|
+| **Claude Code skill** | Production-ready | Procedural knowledge, workflows, repeatable tasks | ~15 min (markdown file) | Auto-triggered by description match; manual `/skill-name`; descriptions loaded in context |
+| **MCP server** | Production-ready (standardized) | External state access, live APIs, databases | 2-4 hours (Python/TS SDK) | Explicit tool listing in client UI; ~55K tokens for 5 servers pre-discovery (Tool Search reduces ~85%) |
+| **Raw CLI shell-out** | Universal | Quick integration, stateless operations | ~5 min (just call it) | Manual command chaining; no built-in discoverability |
+| **OpenAI Codex plugins** | New 2026 | Bundle skills + MCP + apps into reusable workflows | Varies by component | Plugin marketplace; skill names + MCP servers self-describe |
+| **Google Antigravity 2.0** | New at I/O May 2026 | Multi-agent orchestration, desktop/CLI/SDK integrations | 1-2 hours (SDK-based) | CLI auto-discovery; agent orchestration UI; voice support |
+
+## CLI extensibility prior art (2026)
+
+| Pattern | Tool example | Discoverability | Install model | Lessons |
+|---|---|---|---|---|
+| **Owner-prefixed binaries on $PATH** | GitHub CLI extensions (`gh-*`) | Topic tag + `gh extension browse` | `gh extension install owner/repo` | Cheap; relies on social/star-driven discovery. Works because `gh` already won the user base. |
+| **Curated index + per-plugin manifest** | kubectl + Krew | Central plugin index repo (~200 plugins) | YAML manifest, checksum-verified | Strong UX but maintenance cost real; two-tier ecosystem (indexed vs ad-hoc) creates friction. |
+| **Signed registry + protocol** | Terraform providers | `registry.terraform.io` | GPG-signed, semver, declarative `required_providers` | Heavyweight. Justified by infra supply-chain risk. Overkill for video CLI. |
+| **First-class extension API + marketplace** | VSCode, JetBrains | Centralized marketplace | One-click install; sandboxed runtime | Gold standard ONLY because IDE provides rich UI APIs. CLI has no UI surface — copying this is a category error. |
+| **`bin` field in package manifest** | Any npm CLI | None (npm search / GitHub / blog) | `npm i -g pkg` registers shims | Already how videoclaw ships. Keep the bin surface small. |
+| **Protocol, not plugin model** | LSP, MCP | Clients discover servers via config | Servers run as separate processes | **The winning pattern of the last decade.** 150+ language servers because the host doesn't dictate runtime/lang. **This is the analogue for an agent-driven CLI: be the "server," let agents/IDEs be the "client."** |
+
+## "Did anyone successfully build intent-in-CLI?" — No, with caveats
+
+- **Warp** embeds an intent classifier in the **terminal**, not in any individual CLI. The terminal routes NL to commands; the CLIs it drives stay narrow.
+- **Claude Code Agent Skills** move the "intent layer" OUT of CLIs. Each skill is a `SKILL.md` with name+description; the agent host loads them via progressive disclosure. CLIs are invoked from skills, they don't host skills.
+- **HKUDS/CLI-Anything** explicitly recommends: "agent reasoning happens *outside* the CLI; the interface stays focused on direct, composable operations."
+- **MCP servers** wrap intent at a layer ABOVE the CLI, not inside it.
+
+The consistent pattern: **intent classification is the host's job. The CLI's job is to be a deterministic, introspectable target.**
+
+## What "agent-friendly CLI" means in 2026
+
+1. **Noun-verb command structure** — agents traverse a deterministic tree (`vclaw scene generate`, not `vclaw generate-scene`).
+2. **Structured output by default when stdout isn't a TTY.** `--json` or `--output json` everywhere; NDJSON for streams. Human output goes to stderr or behind TTY detection.
+3. **Self-describing surface.** `--help` is necessary but not sufficient. Ship a `schema` / `commands` dump that emits the full command tree + flags + artifact shapes as JSON. videoclaw already does this via `schemas/video/` — just expose it through a `vclaw schema` subcommand.
+4. **Meaningful exit codes.** Not 0/1. Distinguish transient (retry) from permanent (give up). Pair with stable string error codes in JSON output (`{"code": "image_not_found"}`, not freeform messages).
+5. **Idempotency + checkpointable state on disk.** videoclaw's `projects/<slug>/` checkpoint model is exactly the modern best practice — agents can crash/resume.
+6. **No silent fallback across materially different routes** (videoclaw already enforces this). Agents need explicit failure to choose recovery, not magic.
+7. **Token-frugal output.** Field masks, summary-vs-detail flags. A single chatty response can blow a context window.
+
+## Advantage table — orchestration options for videoclaw
+
+| Approach | Build cost | Token cost per agent run | Discoverability | Vendor lock-in | Future-proof |
+|---|---|---|---|---|---|
+| **Build own orchestration in videoclaw** (intent classifier, NL front door, skill router inside CLI) | 4-8 weeks initial + ongoing tuning | **10-32× more** than raw CLI | None — users have to know your DSL | None | ❌ Every agent host re-invents this layer; yours competes |
+| **Ship as clean noun-verb CLI only** | 1-2 weeks (mostly cleanup) | Baseline (1×) | Agents introspect via `--help` + `vclaw schema --json` | None | ✅ Works with every current + future agent host |
+| **Add MCP server on top** | +3-4 hours | Adds ~10-20K tokens per active server | Auto-listed in MCP-aware clients | MCP standard (multi-vendor) | ✅ Works in every MCP client |
+| **Ship as Claude Code skills + Codex plugin** | +2-4 hours per platform | Skills ~30-50 tokens until invoked | Auto-trigger via description match | None — each platform's own format | ✅ Community-maintained |
+
+## Reframing the four original pain points
+
+| Original pain | Original framing | Reframed answer |
+|---|---|---|
+| Too many entrypoints | "Build single front door `vclaw make ...`" | Consolidate to one `vclaw` binary (F2a fold Python). No NL front door. |
+| Skill discovery | "Build a skill picker" | Already solved by Claude Code's skill description-matching. We ship skills, host orchestrates. |
+| Provider routing complexity | "Build smart auto-router" | Keep the existing router. Expose route choice + reasoning as JSON so agents pick. |
+| Manual 6-stage pipeline | "Collapse into one command" | Agents walk the pipeline. Job: make each step crisp, idempotent, agent-friendly. |
+
+## Recommendation locked in for Phase B design
+
+**Do not build a custom orchestration layer.** Spend the saved 4-8 weeks on making videoclaw the best possible target for external orchestrators.
+
+Concrete agenda for v3:
+
+1. **Stay narrow.** No LLM, no intent classification, no NL front door inside the CLI.
+2. **Agent-friendly polish** (1-2 weeks):
+   - `vclaw schema --json` — dumps full command tree + flags + artifact schemas
+   - `--json` default when stdout isn't a TTY
+   - Stable string error codes
+   - Exit-code taxonomy (0/1/2 minimum: success / user error / system error)
+   - Noun-verb consistency audit
+3. **Fold Python into TS (F2a)** — 3-4 weeks. Not for elegance, but: a single `npm install` is what makes videoclaw trivially driveable by every agent host.
+4. **Optional MCP server** (+3-4 hours) — read-only queries (`list_projects`, `get_status`) for live introspection.
+5. **Publish "videoclaw skills" pack** as separate plugin/repo (1 week) — `.claude/skills/videoclaw-*.md` for Claude Code; same approach for Codex when its plugin marketplace matures. **Lives outside the binary.**
+
+## Sources
+
+Both research investigations cited their sources. Key references:
+
+- [Claude Code skills documentation](https://code.claude.com/docs/en/skills)
+- [MCP protocol and server building](https://modelcontextprotocol.io/docs/develop/build-server)
+- [OpenAI Codex plugins and CLI](https://developers.openai.com/codex/cli)
+- [Google Antigravity 2.0 announcement](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/)
+- [Rewrite Your CLI for Agents — The Undercurrent](https://www.theundercurrent.dev/p/rewrite-your-cli-for-agents-or-get) (10-32× token benchmark)
+- [CLI-Anything: making software agent-native](https://github.com/HKUDS/CLI-Anything)
+- [Writing CLI Tools That AI Agents Want to Use — dev.to](https://dev.to/uenyioha/writing-cli-tools-that-ai-agents-actually-want-to-use-39no)
+- [Anthropic Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
+- [GitHub CLI extensions docs](https://docs.github.com/en/github-cli/github-cli/using-github-cli-extensions)
+- [Krew (kubectl plugins)](https://krew.sigs.k8s.io/)
+- [LSP Wikipedia](https://en.wikipedia.org/wiki/Language_Server_Protocol)
+
+## Next step
+
+Phase B unification design spec at
+`docs/superpowers/specs/2026-05-25-videoclaw-v3-unification-design.md`.
+This research feeds in directly and resolves the orchestration question.

package/docs/AI_FILMMAKING_PROMPTS.md

@@ -0,0 +1,195 @@
+# AI Filmmaking prompts
+
+Two prompts derived from the **AI Filmmaking Visual Guide** (`~/Documents/AI Prompting/AI_Filmmaking_Visual_Guide.pdf`), authored with the `prompting-fable-5` skill.
+
+The guide chains three templates — an 8-shot **Character Sheet** (identity lock), a 9-panel **Cinematic Storyboard Grid** (CAM/MOVE/MOOD strips), and **Seedance 2.0 video prompts** (three reference variants) — under a discipline of character-lock-verbatim, lean screenwriter prose, `@image` numbering hygiene, neutral char-sheet lighting, 15s/no-music defaults, and fenced-block delivery.
+
+1. **Creative / usage prompt** — paste-ready; turns a creative brief into the three templates.
+2. **Engineering / integration prompt** — drives a coding agent to close the six gaps where videoclaw does not yet fully embody the guide, and to add the missing unified front-door skill.
+
+A read-only survey of videoclaw-v3 found all three templates already implemented at core fidelity (8-shot sheet, 3×3 grid with CAM/MOVE/MOOD→VOICE/STYLE substitution, grid-as-reference split-screen guard, all three Seedance variants, unique `@imageN` numbering, character-lock, visual-descriptors-not-names, fenced delivery). The engineering prompt targets only the genuine gaps, not a rebuild.
+
+---
+
+## 1. Creative / usage prompt
+
+```text
+You are a production prompt engineer for AI filmmaking. Given a creative brief, you write
+paste-ready prompts across three chained templates — a Character Sheet that locks
+identity, a 9-panel Cinematic Storyboard Grid that designs one continuous scene, and
+Seedance 2.0 video prompts that render each shot. The templates are genre-agnostic; genre
+is a swappable parameter (photorealistic, Pixar 3D, anime, noir, music video, influencer
+vlog, commercial), never a hardcoded assumption.
+
+How to work a brief:
+1. Identify the gaps in the creative spec. To write concrete copy you need: genre/visual
+   style; lead character(s) — a sentence each on age range, build, wardrobe, key prop;
+   setting/location; the scene's emotional beat or story turn in one sentence; aspect
+   ratio (default 16:9 cinema, 9:16 vertical/social); and exclusions (anything that must
+   NOT appear).
+2. Ask 2-3 sharp questions ONLY if the brief is genuinely vague about something
+   load-bearing. If they already wrote a paragraph of detail, just start generating.
+3. Deliver only the templates the user actually needs — don't ship a character sheet if
+   they already have character images; don't ship all three when they asked for one.
+4. Fill every bracket with concrete, evocative copy. Never ship [BRACKETED] placeholders.
+5. Deliver each prompt in its own fenced code block, paste-ready. All commentary, options,
+   and questions live OUTSIDE the block — a prompt block contains only the prompt.
+
+Non-negotiable disciplines:
+- CHARACTER LOCK is the single most important rule. Reuse the same character description
+  VERBATIM in every template that features that character — don't paraphrase between
+  templates, don't trust the model to "remember." The text description is the identity
+  anchor. If reference images exist, reference them AND keep the text as a belt-and-braces
+  backup.
+- Keep prompts LEAN — short, evocative, declarative; screenwriter not novelist. "Viper
+  lunges, palm strike to sternum," not a sentence with three subordinate clauses. Word
+  clutter dilutes the signal. Character Sheet description-only mode targets 30-60 words and
+  must not exceed 100. When a reference image is attached, add NO prose description — state
+  the rendering style only; the image IS the description.
+- STYLE CONSISTENCY — the same palette, grain, lighting language, lens descriptors, and
+  aspect ratio appear in every shot of a sequence, stated on every shot, not just the
+  first. Keep char-sheet lighting NEUTRAL (clean even studio light, simple non-distracting
+  background); scene lighting belongs in the shot prompts, never the sheet.
+
+Template 1 — Character Sheet: an 8-shot grid (top row four full-body views: front, side,
+three-quarter, back, fully visible head-to-toe no cropping; bottom row four matching
+close-ups). Mode A when a reference image is attached (specify style + 1:1 similarity, no
+prose). Mode B description-only (tight comma-separated identity traits — age, build, skin,
+hair, eyes, wardrobe-in-brief, key prop — no scene effects, no narrative damage). Swap the
+style descriptor by genre; avoid descriptors that imply scene lighting.
+
+Template 2 — Cinematic Storyboard Grid: one image, 3x3 = 9 sequential panels of ONE
+continuous scene (one location, one unbroken flow of time), characters identical across
+all panels, no text/captions/panel-numbers inside panels. Under each panel a thin
+annotation strip of three uppercase screenplay slug lines, 2-6 words each:
+CAM: [framing + movement]
+MOVE: [what the subject does]
+MOOD: [emotional/atmospheric beat]
+Substitute the third line by genre — VOICE for vlog/dialogue (carries the spoken line),
+STYLE for action/martial-arts (carries the stance/technique). Move the camera like a
+director: vary framing wide -> medium -> close-up -> over-the-shoulder across panels and
+build to a climactic beat in panels 7-9. Request a clean high-contrast sans-serif
+annotation font legible at grid size.
+
+Template 3 — Seedance 2.0 video prompts, three variants — pick by what references exist:
+- Variant A (text-driven, optional char-sheet refs): FORMAT line (15 seconds / N cuts /
+  genre + tone / audio), SUBJECT(s), ENVIRONMENT, AUDIO/MOOD, then a TIMELINE covering the
+  full 0:00-0:15 in shot rows.
+- Variant B (storyboard grid as the main reference): instruct Seedance to read the grid
+  panels as sequential shots — not one image — following panel order, camera logic, motion
+  arrows and framing; plus a short storyline through-line.
+- Variant C (character sheets + grid): highest fidelity — sheets lock identity, grid locks
+  motion and framing.
+@image numbering: every reference gets a UNIQUE number — Character A's sheet @image1,
+Character B's sheet @image2, the grid the next free number (@image3 with two sheets,
+@image1 when the grid is the only reference). Never collapse two references into one number
+— they fuse in the output. Renumber consistently when sheets are dropped or added.
+Duration: default the full 15 seconds (Seedance 2.0's cap); only go shorter when the user
+explicitly asks (teaser, loop, TikTok intro). Audio: NO MUSIC by default — default the
+AUDIO line to ambient/diegetic or "NO MUSIC"; only bake music in when the user asks or
+names a track. Dialogue: bake spoken lines into the TIMELINE in quoted brackets with the
+speaker's emotion; for a second character's response start with "She replies:" / "He
+replies:" — the word "reply" signals consecutive-order speech and stops speakers from
+collapsing into each other. Multi-shot without a storyboard: one Variant A prompt, keeping
+SUBJECT/ENVIRONMENT/AUDIO constant and varying only TIMELINE and framing shot-to-shot.
+
+Avoid the common pitfalls: shipping bracket placeholders; bloating character descriptions
+in the storyboard (one tight sentence per character there); re-narrating a character when a
+reference image is attached; baking scene effects (blood, sparks, damp hair, rim-light)
+into the character sheet; narrating panel beats instead of directing them; writing
+annotation strips as full sentences; using MOOD when the scene needs VOICE or STYLE;
+collapsing references onto one @image number; using Variant A when a storyboard grid
+exists; forgetting aspect ratio on later shots; adding music the user didn't ask for;
+defaulting Seedance under 15 seconds; and editorializing inside the code block.
+```
+
+---
+
+## 2. Engineering / integration prompt
+
+Run at **xhigh** effort. Default shape is discover → plan-gate → implement end-to-end (it pauses once for plan approval). Swap the checkpoint paragraph for a hard stop after findings if you want audit-only.
+
+```text
+You're working on videoclaw-v3 (the `vclaw` CLI). I want videoclaw to fully embody the
+discipline in docs/IMPORTED/AI_Filmmaking_Visual_Guide.pdf (also at
+~/Documents/AI Prompting/AI_Filmmaking_Visual_Guide.pdf) — a production-prompting
+methodology that chains an 8-shot Character Sheet, a 9-panel Cinematic Storyboard Grid
+with CAM/MOVE/MOOD annotation strips, and Seedance 2.0 video prompts in three reference
+variants. This is the tool I use to ship real client film work, so the goal is parity with
+the guide's discipline, not novelty.
+
+Important: videoclaw already implements ~80% of this guide at full fidelity. A prior
+read-only survey confirmed these are HAVE (do NOT rebuild them): the 8-shot character
+sheet with Mode A/Mode B and neutral lighting and genre-swappable style
+(src/video/filmmaking-prompts.ts), the 3x3 storyboard grid with CAM/MOVE/MOOD and the
+VOICE/STYLE third-line substitution and character-lock and the grid-as-reference
+split-screen guard (src/video/storyboard-grid.ts, src/video/seedance-blocks.ts), all three
+Seedance variants A/B/C with unique @imageN numbering and renumbering
+(src/video/filmmaking-prompts.ts), and the cross-cutting rules — character-lock-verbatim,
+visual-descriptors-not-proper-names, 15s default, no-music default, fenced delivery
+(src/video/prompt-rules.ts, references/video/multi-shot-framework.md). Read those files and
+the PDF first so your changes fit what exists; read CLAUDE.md, docs/CLI_REFERENCE.md, and
+the ADRs in docs/adr/ for the conventions and the decisions you must not undo (no silent
+fallback across routes; on-disk project as source of truth; the CLI registration
+checklist).
+
+Then close the six gaps where videoclaw does NOT yet fully embody the guide. Confirm each
+against the current code before changing it — the line numbers below are from an earlier
+read and may have drifted:
+1. Character Sheet Mode B has no hard length guard — a >100-word description only warns. The
+   guide treats over-100 as a failure. Make it a hard validation error (keep the existing
+   warning for the 60-100 band). src/video/filmmaking-prompts.ts.
+2. The 9-panel grid does not enforce framing progression. The guide wants camera framing to
+   vary wide -> medium -> close and build to a climax in panels 7-9. Add this as guidance
+   the grid builder emits and a lint/advisory check, not a silent rewrite of operator
+   panels. src/video/storyboard-grid.ts panel builder + src/video/prompt-lint.ts.
+3. Dialogue notation ("She replies:" / "He replies:") exists in multi-shot-prompt.ts
+   (withDialogue) but is not wired into the Seedance grid-reference and
+   character-sheets-plus-storyboard-grid variants — it must be inserted by hand today. Wire
+   it through so dialogue flows into those variants' TIMELINE.
+4. There is no single front-door that chains character-sheet -> storyboard-grid -> seedance
+   packets. Add a unified `ai-filmmaking` skill (skills/ai-filmmaking/SKILL.md) that
+   orchestrates the existing commands in order over a brief — modeled on the guide's
+   workflow and pitfalls, and on how skills/character-ad and skills/brand-agency are
+   structured. Register it in skills/catalog.json and keep the catalog parity test and
+   check:skill-frontdoor green. Do not duplicate logic the CLI already owns — the skill
+   drives existing commands.
+5. The anti-bloat prose discipline is documented but not enforced. Extend prompt-lint to
+   flag character-description budget overruns and full-sentence annotation strips
+   (annotations should be 2-6 word uppercase slug lines), as advisories. src/video/prompt-lint.ts.
+6. Aspect ratio is stated on the grid header but not repeated per panel/shot; the guide
+   says state it on every shot. Thread it where shots are emitted. Low priority — do it only
+   if it's clean and non-breaking.
+
+This is parity work, not churn. Don't refactor the HAVE paths, don't add abstractions for
+hypothetical needs, don't reformat files you aren't otherwise touching. Match the
+conventions exactly: kebab-case filenames, .js import extensions on relative imports,
+2-space indent, machine-readable JSON output, node:test with assert/strict. For any new CLI
+command or artifact, follow the full registration checklist in CLAUDE.md (handler +
+dispatch + schema + cli-schema COMMANDS array + the count assertion in cli-schema.test.ts +
+test + README + docs/CLI_REFERENCE.md). Copy the PDF into the repo at
+docs/IMPORTED/AI_Filmmaking_Visual_Guide.pdf so the source is tracked.
+
+Checkpoint before you commit to a direction: confirm the six gaps against the current code,
+present a short ranked plan (impact over effort), and pause for me there — that scope call
+is mine. After I approve, proceed end-to-end without pausing for reversible steps; stop
+again only for genuinely destructive/irreversible actions or a real change of scope. Use
+parallel subagents to confirm the gaps concurrently and keep working while they run.
+
+Hold the quality bar and verify against it. Every change ships with a node:test that would
+have caught the gap. Build with `npm run build`, run `npm test`, and run the relevant
+guardrails as your pre-flight before declaring a batch done: smoke:reference-sheets,
+check:cleanroom-docs, check:skill-frontdoor, the skills/catalog.json parity test, and
+check:release-readiness-lite. Verify with fresh-context verifier subagents against the
+guide and the existing tests — don't self-approve in the same pass. Note that
+check:release-readiness-lite has historically exited 0 even on a failing test, so read the
+actual test output, don't trust the exit code alone.
+
+Before reporting progress, audit each claim against an actual tool result from this
+session: if a test fails, show the output; if a guardrail was skipped, say so; state only
+what you can point to evidence for. Don't claim a smoke passed unless you ran it.
+
+When you finish, lead with the outcome — which of the six gaps are closed and how you
+proved each — then the detail. Write the summary for someone who didn't watch you work:
+plain sentences, each file/command/test its own clause, no working shorthand.
+```

package/docs/ARCHITECTURE.md

@@ -0,0 +1,257 @@
+# Architecture
+
+`videoclaw` (npm package: `videoclaw`) is a multi-provider video CLI
+that grew out of two predecessor codebases:
+
+- the original `videoclaw` package (v0.11.x) which had an orchestration
+  layer (ralph / ralplan / team / MCP servers) on top of a video pipeline
+- the clean-room `vclaw-video-core` rebuild which kept only the video
+  pipeline with strict on-disk artifacts + approval gates
+
+v2 takes `vclaw-video-core` as the foundation, drops the orchestration
+layer (Claude Code / Codex now cover those concerns natively), and ports
+forward selected pieces from `videoclaw`: the `vclaw-cli` Bun package
+(formerly `veo-cli`), the Runway transport, a curated Python pipeline,
+and the Google Flow v1 + Omni Flash backend additions.
+
+## What's intentionally NOT here
+
+The following subsystems from the original `videoclaw` v0.11.x are
+deliberately dropped. See `MERGE_PLAN.md` §3 for the rationale:
+
+- `src/team/` (tmux team coordination)
+- `src/ralph/`, `src/ralplan/` (persistent loops + consensus planning)
+- `src/mcp/` (state / memory / code-intel / team / trace MCP servers)
+- `src/hooks/`, `src/autoresearch/`, `src/hud/`, `src/visual/`,
+  `src/openclaw/`, `src/sparkshell/`, `src/runtime/`, `src/subagents/`,
+  `src/notifications/`, `src/verification/`
+- `crates/` (would have been Rust performance components if they had
+  ever been checked in — they were referenced in CLAUDE.md but never
+  existed in source)
+
+Equivalents exist in Claude Code (native subagents), the OMC plugin
+(ralph / team / autopilot skills), and similar host CLI tooling.
+
+## Sidecars
+
+The main repo is pure TypeScript Node 20+, but two opt-in sidecars
+extend it:
+
+- **`vclaw-cli/`** — Bun package (formerly `veo-cli`). Multi-provider
+  video automation: Google Labs Flow (Veo 3.x direct + Omni Flash) via
+  Puppeteer scraping, UseAPI (Veo / Seedance / Runway), local
+  SQLite job tracking. The main repo's `native-veo.ts` invokes this
+  package for the `veo-useapi` transport.
+- **`skills/video-replicator/scripts/`** — Python 3.10+ pipeline. 122
+  modules covering the Seedance Prompt Director (compose / chain /
+  critique / reference-validator / hooks), the bunty cricket pipeline,
+  character sheet generation, presenter helpers, video assembly, and
+  audio utilities. Documented at `docs/PYTHON_PIPELINE.md`.
+
+## Current layers
+
+1. `src/cli/`
+   - user-facing command entrypoints
+2. `src/video/provider-platform/`
+   - provider route descriptors
+3. `src/video/provider-status.ts`
+   - environment, dependency, and route health reporting
+4. `src/video/pipeline-manifests/`
+   - built-in stage definitions for `storyboard` and `director`
+5. `schemas/video/`
+   - canonical machine-readable contracts
+6. `src/video/*`
+   - portfolio management, reporting, templates, readiness, character consistency, execution planning, adapter-backed execution runtime, and Obsidian export
+   - `story-bible.ts` — deterministic continuity bible (`buildStoryBibleArtifact`, `writeStoryBibleForProject`) derived from `brief.json` + `storyboard.json` + character profiles. Pure apart from reading project files; spends no credits and calls no providers. Auto-generated at storyboard-write time by every storyboard-producing command (`video create|storyboard|clone-execute|storyboard-from-clone|storyboard-review` and `director-preflight --apply-content-fixes`, regenerated after content-fixes apply) and written to `artifacts/story-bible.json` (contract: `schemas/video/artifacts/story-bible.schema.json`). It captures cast, settings, props, and a scene timeline with continuity notes so downstream generation stays consistent across scenes/regenerations; recorded in the storyboard checkpoint, the `artifact.storyboard.written` event payload, and the command JSON output as `storyBiblePath`, and validated by the doctor layer.
+   - `assemble/` — the FFmpeg assemble/stitch layer. `assemble/media-qc.ts` (`runAssembleMediaQc`) runs after stitch on non-dry-run renders, ffprobing each clip + the master via `probeMedia` (issue codes `probe-failed`, `missing-audio`, `nonstandard-audio-codec`, `nonstandard-audio-sample-rate`, `nonstandard-video-codec`, `duration-drift`); the report is attached to `AssembleResult.qc` and the `assemble-report` artifact under `qc`, with issues surfaced as `qc.<code>[<scope>]` assemble warnings. `assemble/narration-fit.ts` (`planNarrationFit`) is a pure planner (adapted from Google's story-generator timing rule) that either speeds up narration within a tempo threshold or keeps speech natural and loops the visual bed.
+   - native in-process transports: `native-veo.ts` (→ `vclaw-cli`/Bun), `native-seedance.ts` (SUTUI_API_KEY), `native-runway.ts` (UseAPI Bearer, pure-Node fetch), `native-dreamina.ts` (Seedance 2.0 / Dreamina via useapi.net — reuses `USEAPI_API_TOKEN` + `VCLAW_DREAMINA_ACCOUNT`, pure-Node fetch)
+   - `review-ui.ts` — HTTP server (port 4317) that drives the browser-based storyboard review station at `tmp/review-station/index.html`. See `docs/REVIEW_UI_STORYBOARD_WORKFLOW.md`.
+   - `prompt-quality.ts` — six Seedance-handbook anti-pattern checks (adjective soup, multiple actions, multiple camera moves, style-word overload, literary emotion language, overlong prompts) wired into `director-preflight`, warnings by default and promotable to blocking errors via `DIRECTOR_STRICT_PROMPT_QUALITY=1`; also houses `runMultiShotChecks`, the validator for the multi-shot prompt framework
+   - `multi-shot-prompt.ts` — multi-shot cinematic prompt authoring utility: provider-aware presets (`cinematic-15s`, `seedance-10s`, `veo-8s`, `runway-10s`), `buildShotPlan` (deterministic timecode scaffold, non-repeating camera grid), parsed `shots[]`, and `generateMultiShotPromptText` (Gemini-backed or stub). `video multi-shot --from-storyboard` hydrates prompts from project storyboard scenes and persists source metadata.
+   - `dialogue-fit.ts` — short-clip dialogue duration checks wired into `director-preflight`, warnings by default and promotable to blocking errors via `DIRECTOR_STRICT_DIALOGUE_FIT=1`
+   - `generation-telemetry.ts` — route/task/config/cost/timing/output telemetry recorded into project event ledgers and used by cost estimates when completed Seedance USD samples exist
+7. `src/video/providers/`
+   - per-provider HTTP adapter code (`runway-useapi.ts` and `dreamina-useapi.ts`). Each adapter exports submit/poll/cancel functions that accept an optional `fetchImpl` for test injection. Wrapped by `src/video/native-*.ts` for production use.
+
+## Principles
+
+1. No silent fallback across materially different provider paths
+2. Every stage should eventually have a canonical artifact
+3. CLI output should be machine-readable by default
+4. Architecture remains small until the contracts are stable
+
+## Near-term roadmap
+
+1. Add more review/publish automation around generated outputs
+2. Keep tightening the transport contracts without widening orchestration complexity
+3. Expand higher-level operator ergonomics on top of the current runtime
+4. Keep docs/help output aligned with the actual product surface
+5. Add selective provider-specific polish only where real runs justify it
+
+## Current implemented flow
+
+1. `video init`
+   - creates canonical project workspace
+2. `video brief`
+   - writes `brief.json`
+   - marks `brief` checkpoint complete
+3. `video storyboard`
+   - writes `storyboard.json`
+   - marks `storyboard` checkpoint complete
+4. `video assets`
+   - writes `asset-manifest.json`
+   - marks `assets` checkpoint complete
+5. `video review`, `video review-ui`, or `video review-autopilot`
+   - writes `review-report.json`
+   - marks `review` checkpoint to completed, retry-required, or failed
+   - allows publish handoff only when the saved report has `verdict: "pass"` and `metrics.publishReady: true`
+6. `video publish`
+   - writes `publish-report.json`
+   - marks `publish` checkpoint complete or failed
+7. `video status`
+   - resolves next stage from manifest + checkpoints
+8. `video doctor-project`
+   - validates checkpoint/artifact consistency
+9. `video doctor-portfolio`
+   - validates the whole portfolio
+10. `video metrics|workload|next-actions|dependencies`
+   - portfolio management views
+11. `video report|report-snapshot|report-history|report-diff|trends|export-csv`
+   - reporting and snapshot history
+12. `video export-obsidian|sync-obsidian|scaffold-obsidian-vault`
+   - Obsidian operations layer
+13. `video playbook-list|playbook-show`
+   - bundled prompt/playbook registry
+14. `video prompt-lib-list|prompt-lib-show`
+   - imported prompt/reference library
+15. `video template-save|template-list|template-show|clone-plan|clone-init|storyboard-from-clone`
+   - reusable template / clone bridge
+16. `video clone-execute`
+   - template -> storyboard -> execution-seed -> runtime in one flow
+17. `video readiness`
+   - artifact, character-consistency, image-input, scene-selection, and director identity-sheet readiness before runtime execution
+18. `video plan|produce|execute-status`
+   - route selection, payload generation, dry-run validation, built-in or external adapter execution, polling, output ingestion, native Seedance direct transport, native Veo direct transport, and prompt-guided execution context
+19. `video character-add|character-list|character-show|character-consistency`
+   - character profile subsystem and continuity enforcement
+20. `video reference-sheet-add|list|show|bind|validate`
+21. `video candidates-list|candidates-show|select-candidate|reject-candidate|reroll-scene|chain-from|unchain|candidates-migrate-from-assets`
+    - per-scene candidate registry + operator selection state + chain-from-prev
+    - partial rerun via `produce --scene <n>`
+    - role-tagged reference sheets with closed-vocabulary validation and per-scene binding
+22. `video cost-estimate`
+    - static default estimate with optional historical Seedance USD telemetry override
+23. `video multi-shot`
+    - cinematic prompt-authoring utility with standalone and project-storyboard entry paths
+    - `--plan` generates a deterministic timecode scaffold + non-repeating camera grid
+    - `--validate` (--file or stdin) checks prompt quality via `runMultiShotChecks`; nonzero exit on errors
+    - `--auto --image <path>` calls Gemini to author prose from a reference image (offline-stubbable via `VCLAW_MULTISHOT_AUTO_STUB`)
+    - `--from-storyboard --project <slug> --scene <sceneIndex>` derives action, characters, and default location from the project artifacts
+    - `--provider` / `--route` resolve provider-shaped presets when `--preset` is omitted
+    - `--project <slug>` persists the result as a `multi-shot-prompt` artifact; status/readiness summarize the latest artifact for review
+
+Compatibility aliases:
+
+1. `video execution-plan` -> `video plan`
+2. `video execute` -> `video produce`
+
+## Commercial track + quantified prompt-craft (landed)
+
+The prompt-craft layer is category-driven and quantified. It generalises beyond
+"cinematic character video" to cover commercial / product work, and locks
+Seedance identity through the official Asset Library. The pieces below are all
+implemented and on `main`.
+
+### Category Descriptor registry
+
+`src/video/category-registry.ts` defines nine categories (`CATEGORY_IDS`), each
+a `CategoryDescriptor` carrying a `subjectType` of `character` or `product`, a
+`beatTemplate` (`three-act` / `ad-hook-feature-cta` / `turntable` / `lookbook`),
+a `cameraVocab`, a `genre`, an `audioProfile` (`diegetic` / `ad-mix`), and
+`hookSeconds`. `resolveCategory(id?)` defaults to the `cinematic` character
+descriptor. The `subjectType` selects which branch `filmmaking-prompts` takes:
+
+- **character path** — character sheets + storyboard-grid character lock
+  (the existing cinematic path, unchanged).
+- **product path** — no character sheets, no grid lock; each product in
+  `artifacts/product-references.json` becomes a text-driven Seedance packet
+  whose timeline follows the descriptor's beat template, with orbit grammar
+  woven in for orbit/turntable vocabularies. `src/video/product-references.ts`
+  reads the product references and degrades gracefully (description-only hero
+  from the brief) when the artifact is absent.
+
+`referenceBuildOrder()` fixes the identity-reference build sequence
+(`base-ref → sheet → scene-plate`) so scene lighting can't contaminate the
+identity anchor.
+
+### Quantified cinematography + standing prompt rules
+
+`src/video/cinematography.ts` holds pure, deterministic prompt-fragment emitters
+whose density scales with a `DetailLevel` of `terse | standard | rich`:
+`cameraSpec` (shot/lens-mm/angle/movement, velocity in ft/s at `rich`),
+`lightingSpec` (Kelvin / key angle / ratio), `gradeSpec` (shadow/highlight
+hue+sat splits), and `audioMix` (a dB hierarchy at `rich`). It also defines five
+cinema modes (`CINEMA_MODE_IDS`: `narrative`, `studio`, `action`, `performance`,
+`atmospheric`) resolved by `cinemaMode` and stacked for multi-world intercuts by
+`stackModes` (adjacent modes are never merged), `resolveCameraVocab`, per-genre
+look defaults (`genreDefaults`), beat-template layout (`beats()`), and precise
+orbit grammar (`orbitGrammar`, three `ORBIT_KINDS`).
+
+A library of six named 2-second opening hooks (`HOOK_PATTERN_IDS`:
+`black-to-light`, `silence-to-sound`, `reverse-motion`, `beat-drop`,
+`match-cut-in`, `whip-reveal`) is resolved by `resolveHookPattern` / `hookBeat`,
+which **throw** on an unknown id (hooks must be explicit).
+
+`src/video/prompt-rules.ts` holds the standing prompt rules as pure scrubbers:
+`stripProperNames` (swap cast names for stable visual descriptors),
+`brandNeutralize` (strip brand tokens), `noFaceMorphTag` (forbid identity
+drift), and `diegeticAudioLine` (diegetic audio only).
+
+### Filmmaking-prompts two-phase gate
+
+`vclaw video filmmaking-prompts` (`src/video/filmmaking-prompts.ts`) takes a
+`--phase storyboard|video` gate: `storyboard` returns the storyboard /
+camera-language portion only (`seedancePackets` gated to `[]`); `video` and the
+default (omitted) return the full video-generation packets. The same command
+takes `--category <id>`, `--genre`, `--detail terse|standard|rich` (appends a
+quantified cinematography suffix at `rich`), `--panels 9|12|15|20`,
+`--aspect-ratio`, `--no-faces`, and `--storyboard-grid <path>`.
+
+### Multi-shot output formats
+
+`vclaw video multi-shot --plan` (`src/video/multi-shot-prompt.ts`) renders a
+deterministic shot plan in several formats:
+
+- `--format default|seedance-paragraph|per-shot` — `composeSeedanceParagraph`
+  (Seedance native single-paragraph), `composePerShotFormat` (per-shot
+  `SHOT N` blocks), or the default layout.
+- `--lang en|zh|en+zh` — `composeBilingual` wraps the rendered prompt in fenced
+  blocks (single, translated, or EN + 中文); numeric/technical spec tokens pass
+  through unchanged.
+- `--dialogue "<speaker>: <line> [|| <speaker>: <line>]"` — `parseDialogueLine`
+  + `withDialogue` attach one- or two-speaker spoken dialogue.
+- `--hook <patternId>` — prepends a resolved opening-hook directive.
+- `--category <id>` — resolves a `CategoryDescriptor` to shape the prompt.
+
+### Seedance Asset Library end-to-end flow
+
+Seedance character/product consistency on the official `ark/seedance-2.0`
+endpoint goes through managed Asset Library avatars (`Asset://` URIs), not raw
+photoreal URLs (which trip the "real person" content filter and don't lock
+identity). The end-to-end flow:
+
+1. `vclaw video seedance-register-assets` (`src/video/seedance-asset-library.ts`)
+   registers each `--character <name>:<imageUrl>` as an Image asset under a
+   group, polls until it reaches the international Ark profile
+   (`sync_status: active`), and writes `artifacts/seedance-assets.json`
+   (contract: `schemas/video/artifacts/seedance-assets.schema.json`). Requires
+   `SUTUI_API_KEY`.
+2. At runtime, `src/video/execution-runtime.ts` reads
+   `seedance-assets.json` (only when `recommendedRouteId === 'seedance-direct'`)
+   and auto-resolves each scene's cast names to their `Asset://` URIs, which
+   become that scene's reference set.
+3. `src/video/native-seedance.ts` routes `Asset://` references into the Seedance
+   `reference_images` param and enforces the per-generation reference budget via
+   `assertReferenceBudget` (≤9 image, ≤3 video, ≤3 audio) — validated for every
+   task before any network call, so an over-budget task can't cause a partial
+   submit.