videoclaw 3.0.0-alpha.1

package/docs/STORY_BIBLE.md

@@ -0,0 +1,288 @@
+# Story bible
+
+`videoclaw` treats the **story bible** as the single machine-readable
+continuity reference for a project — one artifact that names the cast,
+settings, props, and the full scene timeline, with per-scene continuity
+notes, so every downstream generation stage stays consistent across scenes
+and across regenerations.
+
+> **Lock continuity once, read it everywhere.**
+> The story bible is *derived*, not authored: it is rebuilt deterministically
+> from the brief, the storyboard, and the character profiles whenever the
+> storyboard changes. It spends no credits and calls no providers.
+
+It lives next to the other canonical artifacts at
+`projects/<slug>/artifacts/story-bible.json` and is validated by the doctor
+layer like any other canonical artifact.
+
+<p align="center"><img src="./assets/diagram-story-bible.jpg" alt="Story bible generation — Brief, Storyboard, and Character profiles converge into the deterministic story-bible.ts builder, which writes story-bible.json, consumed by doctor validation and downstream continuity" width="100%" /></p>
+
+---
+
+## Why the story bible exists
+
+Long-form and multi-scene video drift in predictable ways once a project has
+more than a couple of scenes:
+
+- **Cast drift** — a character described one way in scene 0 is described
+  differently in scene 5, so the provider renders a different person.
+- **Scattered continuity intent** — "keep the same jacket / same kitchen /
+  same lighting" lives only in the operator's head and is re-typed (or
+  forgotten) per scene.
+- **No single timeline** — "when does each scene start and end, and how long
+  is the whole thing?" is recomputable but never written down.
+- **Regeneration amnesia** — re-running the storyboard loses any continuity
+  context that wasn't baked into each scene's prompt.
+
+The story bible fixes this by collapsing brief + storyboard + character
+profiles into **one deterministic continuity document** that downstream
+stages and operators can both read. Because it is a pure derivation, it is
+always regenerated to match the current storyboard — there is no stale
+hand-maintained copy to keep in sync.
+
+---
+
+## What it is — a deterministic derivation
+
+`buildStoryBibleArtifact` (in [`src/video/story-bible.ts`](../src/video/story-bible.ts))
+is pure: given a brief, a storyboard, and the project's character profiles it
+returns a `StoryBibleArtifact`. `writeStoryBibleForProject` is the thin
+on-disk wrapper — it reads `artifacts/brief.json`, `artifacts/storyboard.json`,
+and `characters/characters.json` for the project, builds the artifact, and
+writes it via the artifact store. Both are re-exported from
+[`src/index.ts`](../src/index.ts) for library callers.
+
+The derivation rules are entirely mechanical:
+
+- **Title / intent / production mode** come straight from the brief.
+- **Style, genre, mood, music, aspect ratio** are pulled from the brief's
+  `metadata` (each is optional — omitted when absent).
+- **Cast** is the union of character names referenced across storyboard
+  scenes, names in brief metadata, and registered character profiles, sorted
+  alphabetically. Each character's `description` / `voice` are filled from the
+  matching profile (preferred) or brief metadata, and `referenceAssets` come
+  from the profile.
+- **Settings and props** are read from brief `metadata.storyBible.settings` /
+  `metadata.storyBible.props` (and the top-level `metadata.settings` /
+  `metadata.props` fallbacks), keeping only entries with both a `name` and a
+  `description`.
+- **Scenes** are the storyboard scenes sorted by `sceneIndex`. Each scene's
+  duration comes from the storyboard (falling back to a default derived from
+  `metadata.clipDurationSeconds`, or `targetRuntimeSeconds / sceneCount`).
+  `start`/`end` seconds are accumulated in order to form a contiguous
+  timeline. `narration` is the scene's dialogue (or its description), and
+  `visualPrompt` / `motionPrompt` / `diegeticAudio` are lifted from the
+  scene's prompt block when present.
+- **Continuity notes** are synthesized per scene: keep the present characters
+  consistent with the bible, continue cleanly from the previous scene, and
+  maintain the project visual style.
+- **Timeline** is the rolled-up `totalDurationSeconds` plus a compact
+  `{ sceneIndex, startSeconds, endSeconds }` list.
+
+Because every field is computed from the same three inputs, two runs over the
+same brief + storyboard produce a byte-identical artifact (modulo
+`generatedAt`).
+
+---
+
+## When it is generated
+
+The story bible is written automatically at **storyboard-write time** by every
+command that produces or rewrites a storyboard — operators never invoke it
+directly:
+
+- `vclaw video create`
+- `vclaw video storyboard`
+- `vclaw video clone-execute`
+- `vclaw video storyboard-from-clone`
+- `vclaw video storyboard-review`
+- `vclaw video director-preflight --apply-content-fixes`
+
+When `director-preflight --apply-content-fixes` rewrites the storyboard, the
+story bible is **regenerated afterwards** so it reflects the post-fix
+storyboard rather than the pre-fix one.
+
+The story bible is also **regenerated mid-run** by `vclaw video execute` /
+`produce` when it applies a director content auto-fix — gated on env
+`DIRECTOR_AUTO_FIX_CONTENT=1` in director mode — mirroring the
+`director-preflight --apply-content-fixes` behaviour above.
+
+Each of these commands, after writing the artifact, records it in three
+places:
+
+1. The **storyboard checkpoint**, under `artifacts['story-bible']`.
+2. The **`artifact.storyboard.written` event** payload, as `storyBiblePath`.
+3. The **command's JSON output**, surfaced as `storyBiblePath`.
+
+So an operator (or a downstream script) can find the bible either by its fixed
+path or by reading the `storyBiblePath` field off the command result.
+
+---
+
+## Where it lands on disk
+
+```
+projects/<slug>/
+  artifacts/
+    brief.json            # input
+    storyboard.json       # input
+    story-bible.json      # <- derived continuity bible
+  characters/
+    characters.json       # input (character profiles, optional)
+```
+
+The artifact is written through the standard artifact store, so it also gets
+the usual append-only `artifacts/history/` snapshot on each write.
+
+---
+
+## Artifact shape
+
+Canonical schema:
+[`schemas/video/artifacts/story-bible.schema.json`](../schemas/video/artifacts/story-bible.schema.json)
+(`schemaVersion: 1`). Full skeleton:
+
+```json
+{
+  "schemaVersion": 1,
+  "projectSlug": "demo",
+  "generatedAt": "2026-05-31T10:00:00.000Z",
+  "title": "Demo",
+  "intent": "A 15s product tease",
+  "productionMode": "director",
+  "style": "warm cinematic, shallow depth of field",
+  "genre": "product",
+  "mood": "upbeat",
+  "music": "light electronic bed",
+  "aspectRatio": "16:9",
+  "defaultSceneDurationSeconds": 5,
+  "characters": [
+    {
+      "name": "Nova",
+      "description": "30s engineer, short dark hair, charcoal jacket",
+      "voice": "warm, measured",
+      "referenceAssets": ["characters/nova/sheet.png"]
+    }
+  ],
+  "settings": [
+    { "name": "Loft kitchen", "description": "sunlit open-plan kitchen, oak counters" }
+  ],
+  "props": [
+    { "name": "Hero mug", "description": "matte black ceramic mug with brand logo" }
+  ],
+  "scenes": [
+    {
+      "sceneIndex": 0,
+      "startSeconds": 0,
+      "endSeconds": 5,
+      "durationSeconds": 5,
+      "description": "open on product on the counter",
+      "narration": "Meet the mug that wakes you up.",
+      "charactersPresent": ["Nova"],
+      "visualPrompt": "close on matte black mug, morning light",
+      "motionPrompt": "slow push-in",
+      "diegeticAudio": "kettle hiss, distant street",
+      "continuityNotes": [
+        "Keep Nova visually consistent with the character bible.",
+        "Maintain the project visual style: warm cinematic, shallow depth of field."
+      ]
+    }
+  ],
+  "timeline": {
+    "totalDurationSeconds": 5,
+    "scenes": [
+      { "sceneIndex": 0, "startSeconds": 0, "endSeconds": 5 }
+    ]
+  }
+}
+```
+
+Field notes:
+
+- **Required everywhere:** `schemaVersion`, `projectSlug`, `generatedAt`,
+  `title`, `intent`, `productionMode`, `characters`, `settings`, `props`,
+  `scenes`, `timeline`.
+- **`productionMode`** is `storyboard` or `director`.
+- **Optional top-level:** `style`, `genre`, `mood`, `music`, `aspectRatio`,
+  `defaultSceneDurationSeconds` — each emitted only when derivable from the
+  brief.
+- **`characters[]`** require `name` + `referenceAssets` (possibly empty);
+  `description` and `voice` are optional.
+- **`settings[]` / `props[]`** are `{ name, description }` pairs — both fields
+  required, so partially-specified entries are dropped during derivation.
+- **`scenes[]`** require `sceneIndex`, `startSeconds`, `endSeconds`,
+  `durationSeconds`, `description`, `narration`, `charactersPresent`, and
+  `continuityNotes`; `visualPrompt`, `motionPrompt`, and `diegeticAudio` are
+  optional.
+- **`timeline`** carries `totalDurationSeconds` and a per-scene
+  `{ sceneIndex, startSeconds, endSeconds }` list mirroring `scenes[]`.
+
+The schema is `additionalProperties: false` at every level, so the artifact is
+a tight contract — no stray fields survive validation.
+
+---
+
+## How the doctor validates it
+
+`validateStoryBibleArtifact` is registered in the doctor's artifact-validation
+switch, and `story-bible` is part of the **canonical-artifacts** list that
+`doctor-project` walks. The doctor performs two checks against
+`projects/<slug>/artifacts/story-bible.json` when it exists:
+
+1. **Schema validation** — each issue is surfaced as
+   `story-bible: <message>`.
+2. **Malformed-JSON guard** — if the file exists but does not parse, the
+   doctor raises `story-bible: malformed JSON artifact (...)` rather than
+   crashing.
+
+A project that has never produced a storyboard simply has no
+`story-bible.json`, and the doctor treats that as a non-issue.
+
+---
+
+## Smoke test
+
+```bash
+npm run smoke:story-bible-image
+```
+
+This runs [`scripts/smoke-story-bible-image-only.mjs`](../scripts/smoke-story-bible-image-only.mjs)
+end to end on the image-only path: it creates a project, drives the storyboard
+so the continuity bible is generated, and exercises the content-fix
+propagation path so the regenerated bible reflects the post-fix storyboard.
+Like the other smokes it runs `npm run build` first.
+
+---
+
+## How downstream stages benefit
+
+The story bible is a **read surface**, not a runtime gate — it never blocks a
+stage. Its value is that everything past the storyboard has one consistent
+place to consult for continuity:
+
+- **Cast consistency** — the `characters[]` block gives every scene the same
+  canonical name → description / voice / reference-asset mapping, so prompts
+  describe the same person each time.
+- **Set and prop continuity** — `settings[]` / `props[]` keep the same
+  environment and objects described identically across scenes.
+- **Timeline awareness** — the rolled-up `timeline` and per-scene
+  `start`/`end`/`duration` seconds give assemble, narration-fit, and review
+  surfaces an authoritative scene-by-scene clock.
+- **Per-scene continuity notes** — the synthesized notes ("keep X consistent",
+  "continue cleanly from scene N", "maintain the visual style") are ready to
+  fold into generation prompts.
+- **Regeneration safety** — because the bible is rebuilt every time the
+  storyboard is written (including after director content-fixes), the
+  continuity reference can never silently fall out of sync with the scenes it
+  describes.
+
+---
+
+## Where to read next
+
+- [`docs/CLI_REFERENCE.md`](./CLI_REFERENCE.md) — the storyboard-producing commands that emit the bible.
+- [`docs/ARCHITECTURE.md`](./ARCHITECTURE.md) — where the story bible sits in the layered flow.
+- [`docs/REFERENCE_SHEETS.md`](./REFERENCE_SHEETS.md) — the input-layer character reference subsystem the bible's `referenceAssets` point at.
+- [`docs/SCENE_CANDIDATES.md`](./SCENE_CANDIDATES.md) — the output-layer per-scene take registry, indexed by the same `sceneIndex`.
+- [`src/video/story-bible.ts`](../src/video/story-bible.ts) — the pure derivation plus the project writer.
+- [`schemas/video/artifacts/story-bible.schema.json`](../schemas/video/artifacts/story-bible.schema.json) — the canonical artifact contract.

package/docs/STUDIO.md

@@ -0,0 +1,96 @@
+# Studio
+
+`vclaw studio` is the human-friendly planning front door for VideoClaw.
+
+It does not replace the low-level CLI. It builds a production plan from a goal,
+then shows the exact commands and artifacts that will be used.
+
+## Start With A Dry Run
+
+```bash
+vclaw studio --dry-run --goal create-video --project demo --intent "Create a 30 second product ad"
+```
+
+The Phase 1 Studio command is plan-only. It does not call providers, run FFmpeg,
+or spend credits.
+
+## Goals
+
+| Goal | Use When |
+|---|---|
+| `create-video` | Original video from a brief |
+| `copy-reference` | Adapt a reference video or ad |
+| `presenter-video` | Bunty, Nex, Davendra, or generic presenter episode |
+| `music-video` | Multi-shot cinematic or music video planning |
+| `character-video` | Identity-locked character ad or episode (locked Go Bananas / Flow character) |
+| `ugc-campaign` | Belief-driven UGC campaign |
+| `brand-campaign` | Brand DNA from a website URL → seed the brief → plan an on-brand campaign |
+| `existing-project` | Continue a project and get next actions |
+| `review-regenerate` | Review, reroll, or approve scenes |
+| `publish-deliver` | Build and publish a portal |
+
+`brand-campaign` (aliases: `brand`, `website`) takes the site URL via `--input`; its
+plan chains `brand-extract` → `brief --from-brand-dna` → `storyboard` → `readiness`.
+
+<p align="center"><img src="./assets/diagram-studio-goals.jpg" alt="Studio goals to commands — the ten vclaw studio goals route through the studio planner (recipes.ts) into a recipe of the underlying vclaw video commands: init, brief, storyboard, assets, readiness, plan, produce/execute, assemble, portal, publish-preview" width="100%" /></p>
+
+## Examples
+
+```bash
+vclaw studio --dry-run --goal presenter-video --project demo --input deck.pdf --client "Acme"
+vclaw studio --dry-run --goal music-video --project dhuaan --duration 60
+vclaw studio --dry-run --goal existing-project --project demo
+vclaw studio --dry-run --goal publish-deliver --project demo --client "Acme"
+vclaw studio --dry-run --goal brand-campaign --project demo --input https://acme.com
+```
+
+Use `--write-session` to persist the planned handoff under the project:
+
+```bash
+vclaw studio --dry-run --goal presenter-video --project demo --input deck.pdf --write-session
+```
+
+This writes `projects/<slug>/artifacts/studio-session.json`.
+
+## Execution (`--execute`)
+
+By default Studio is plan-only — it prints the commands but runs nothing. Add
+`--execute` to **run the emitted plan** step-by-step. Studio does not re-implement
+any orchestration; it shells out to the same `vclaw video …` commands the plan
+already lists, so the plan stays the source of truth.
+
+```bash
+vclaw studio --execute --goal existing-project --project demo
+```
+
+### Three modes (you choose at run time)
+
+| Command | What runs | Credits |
+|---|---|---|
+| `--execute` | **Dry.** Free steps + spend steps with `--dry-run`. Pauses at the real director storyboard gate (surfaced as a `blocked` step). | none |
+| `--execute --confirm-spend` | **Real render, human-gated.** Promotes the dry spend steps to real (strips `--dry-run`). The render still needs the storyboard approved out-of-band — the runner does not auto-approve. | spends on approval |
+| `--execute --confirm-spend --auto-approve-storyboard` | **Unattended render.** Also sets `VIDEOCLAW_APPROVE_STORYBOARD`, so a single command runs the whole pipeline through the real render with no human checkpoint. | spends unattended |
+
+Credit-safety guarantees:
+
+- The default `--execute` is **provably dry** — a spend subcommand
+  (`execute`/`produce`/`seedance-register-assets`/`batch-submit`/`publish-preview`/`publish-portal-index`)
+  lacking `--dry-run` is **refused** (`blocked-spend`), and the dry steps keep `--dry-run`.
+- Real spend requires the **explicit** `--confirm-spend`; unattended real spend
+  requires **both** `--confirm-spend` and `--auto-approve-storyboard` (never accidental).
+- Without `--auto-approve-storyboard` the runner strips `VIDEOCLAW_APPROVE_STORYBOARD`
+  from the child env, so the director gate keeps blocking a real render.
+- Fails fast — a blocked or failed step stops the run with no partial spend.
+- `--from-step <id>` resumes after you have approved the storyboard out-of-band.
+
+The result is reported under an `execution` block in the JSON output: the `mode`
+(`dry` / `confirm-spend` / `auto-render`), per-step `status` (`ran` /
+`blocked-spend` / `blocked` / `failed` / `skipped-before-resume`), the
+`stopReason`, a `hint` (in dry mode) on how to render for real, and any surfaced
+storyboard `markdownPath`.
+
+## Agent Contract
+
+When stdout is piped, Studio outputs JSON. Progress and warnings stay out of
+stdout. The plan-only default performs no provider work; `--execute` runs only
+dry-run/free steps and pauses at approval/spend points (see above).

package/docs/TEMPLATES.md

@@ -0,0 +1,143 @@
+# Templates
+
+## Purpose
+
+Templates are the reusable bridge between:
+
+1. reference analysis
+2. new project intent
+3. seeded clone plans
+4. storyboard generation
+
+## Workflow
+
+0. Inspect bundled provider playbooks:
+
+```bash
+vclaw video playbook-list
+vclaw video playbook-show --name seedance-ugc
+vclaw video prompt-lib-list
+vclaw video prompt-lib-show --name veo-prompting-guide
+```
+
+## Built-in storyboard templates
+
+Built-in storyboard templates are available for quick scene scaffolds:
+
+```bash
+vclaw video storyboard-template-list
+vclaw video storyboard-template-show --name product-commercial-4
+vclaw video storyboard --project new-project --template product-commercial-4 --environment "bright kitchen counter" --character-a "Maya"
+```
+
+Guide-inspired storyboard templates include:
+
+1. `product-commercial-4` — short problem, reveal, proof, payoff ad
+2. `food-tutorial-6` — ingredients, prep, cooking, plate, taste
+3. `dance-social-6` — hook pose, choreography, loopable finish
+4. `dramatic-short-6` — reveal, choice, confrontation, aftermath
+5. `action-short-6` — threat, obstacle, impact, near miss, release
+
+## Reference-derived templates
+
+1. Analyze a reference:
+
+```bash
+vclaw video analyze --project ref-project --source <url-or-path> --title "Reference"
+```
+
+2. Save a template:
+
+```bash
+vclaw video template-save --project ref-project --name launch-template
+```
+
+3. List and inspect templates:
+
+```bash
+vclaw video template-list
+vclaw video template-show --name launch-template
+```
+
+4. Generate a clone plan:
+
+```bash
+vclaw video clone-plan --template launch-template --project new-project --intent "Make a launch teaser for a smart bottle."
+```
+
+5. Initialize a new project from the template:
+
+```bash
+vclaw video clone-init --template launch-template --project new-project --intent "Make a launch teaser for a smart bottle."
+```
+
+6. Generate a first-pass storyboard from that clone plan:
+
+```bash
+vclaw video storyboard-from-clone --project new-project
+```
+
+## Stored data
+
+Templates currently capture:
+
+1. pacing
+2. beat structure
+3. motion classification
+4. keep list
+5. change list
+6. reusable variables
+7. style layers
+8. beat-compression guidance
+9. technical notes
+10. dialogue notes
+11. workflow checklist
+
+Playbooks currently capture:
+
+1. use-when guidance
+2. prompt formula steps
+3. constraints
+4. adaptation checklist
+
+Prompt-library references now capture:
+
+1. provider prompting guides
+2. style template schema notes
+3. stage-director guidance
+4. checkpoint protocol guidance
+5. generation telemetry guidance
+6. dialogue-duration preflight guidance
+7. character reference-sheet guidance
+8. clone-ad template workflow guidance
+
+## Clone-plan enrichment
+
+`analyze --auto` asks Gemini for the optional fields above. Manual analyze
+commands can still provide the legacy beat/keep/change/variable data; when a
+template is saved, V-Claw fills conservative defaults for missing style layers
+and beat-compression guidance.
+
+Clone plans preserve the template's style layers and compression rules. They do
+not copy claims or brand-specific language; the checklist pushes operators to
+replace product, audience, offer, proof, objection, and CTA variables for the
+new intent.
+
+## Current gap
+
+Templates do not yet drive runtime execution directly. They currently seed:
+
+1. clone plan
+2. brief metadata
+3. storyboard scaffold
+
+## Character continuity note
+
+If a cloned storyboard needs consistent characters, add them explicitly during
+storyboard authoring and register matching profiles:
+
+```bash
+vclaw video storyboard --project new-project --scene "Hook shot" --scene-character 0:Nova
+vclaw video character-add --project new-project --name Nova --ref refs/nova-sheet.png
+vclaw video character-consistency --project new-project
+```