# Director Blueprint (AI Animation Director)

The **Project Blueprint** is VideoClaw's *director layer* — a project-level visual
bible that locks the film language **above** the existing execution layer
(`cinematography.ts`, `filmmaking-prompts.ts`). It is distinct from the
[Story Bible](STORY_BIBLE.md): the story bible tracks **continuity** (cast,
settings, props, scene timeline); the blueprint tracks **visual direction** (color
system, lighting grammar, per-character camera language, environment atmosphere,
the project camera bible).

> Design principle (from the source "AI Animation Director" system): the blueprint
> is *"a director layer ABOVE your existing camera reference, not a replacement for
> it."* It does not change how prompts are composed — it locks the decisions they
> express.

## Generate it (the `ai-director` skill)

Authoring a blueprint is a creative task, so it lives in the **`ai-director`
skill** (`skills/ai-director/SKILL.md`), which runs the staged director
master-prompt (intake → 8 sections) and emits a `project-blueprint.json`. The CLI
is the deterministic half: it validates, normalizes, and persists that JSON, then
the prompt composer consumes it.

The eight locked sections:

1. **Visual identity** — aesthetic, influences (what's borrowed), texture, scale, time-of-day, one-line thesis.
2. **Master color system** — 4–6 named colors (where + emotional function), Kelvin range, warm/cool shift meaning, contrast, saturation, optional `gradeId`.
3. **Lighting grammar** — key direction, quality, shadow strategy, practicals, and three signature setups (intimate / tension / hero).
4. **Character blueprint** — per character: silhouette identity, signature detail, 3-color palette, costume, what the design communicates, a voice profile, and **power / vulnerability / signature camera framing**.
5. **Environment blueprint** — per location: emotional function, visual anchors, scale, light/color, and the **5 sensory words** (1 smell + 1 texture + 1 sound + 2 feelings).
6. **Project camera bible** — camera relationship, when it moves vs. locks, 3 dominant shots, rare shots, primary angles/movements, **forbidden movements**, focal feel, depth strategy, and **the one rule the camera must never break**.
7. **Performance rules** — acting style, dialogue energy, silence usage, intensity scale, casting pattern, what to avoid.
8. **Output notes** — runtime, aspect ratio, motion style, editing rhythm, 8–12 vibe keywords.

## CLI

```bash
# Validate + persist a skill-authored blueprint JSON (writes artifacts/project-blueprint.json):
vclaw video director-blueprint --project <slug> --from-json <path> --write

# Print the persisted blueprint:
vclaw video director-blueprint --project <slug> --show
```

`director-blueprint` only validates and stores — generation is the skill's job.
Validation is lenient on sub-fields (missing strings → empty) but strict on the
eight required sections, throwing a single `invalid_flag_value` error listing all
missing sections. The artifact is managed + history-tracked
(`artifacts/project-blueprint.json`, schema
`schemas/video/artifacts/project-blueprint.schema.json`).

## How it's consumed

`vclaw video filmmaking-prompts` **auto-reads** `artifacts/project-blueprint.json`
(graceful — absent → byte-identical legacy output) and enriches **every** scene
packet:

- A compact, prose-only addendum is appended **after** the canonical 10-block
  Seedance body (so the block-order contract is preserved) and uses no Kelvin/hue
  numerals (so the `prompt-lint` prose-register check passes):

  ```
  DIRECTOR — Palette: <master colors>. Look: <contrast/saturation + vibe keywords>.
  Lighting: <scene's signature setup>. Subject: <present character — silhouette,
  signature detail; signature framing>. Atmosphere: <5 sensory words>.
  Rule: <the one rule>.
  ```

- The scene's signature lighting setup is selected from its text (tension words →
  `tension`, reveal/hero words → `hero`, else `intimate`).
- The camera bible's **forbidden movements** are validated against each scene's
  prompt; a `forbidden-camera-movement` issue is raised per hit.
- When the bible forbids `handheld`, the `storyboard-grid-reference` packet also
  drops its default "Handheld camera moments may be used to boost realism"
  boilerplate — so the prompt never instructs a forbidden move (and the checker
  never flags its own boilerplate). No blueprint / handheld allowed → the clause
  stays, byte-identical to legacy.

The underlying camera/lighting vocabulary lives in `src/video/shot-grammar.ts`
(shot-size emotional taxonomy, movement grammar with Seedance syntax, the
sensory-words rule, the two-temperature technique helper in `cinematography.ts`).
See `references/video/camera-bible.md` and
`references/video/ai-director-blueprint.md`.

## Modules

| File | Role |
|---|---|
| `skills/ai-director/SKILL.md` | The staged director master-prompt (generation) |
| `src/video/project-blueprint.ts` | Artifact type + validate/write/read |
| `src/video/blueprint-prompt.ts` | Render the DIRECTOR addendum + forbidden-move detection |
| `src/video/shot-grammar.ts` | Camera-bible shot/angle/movement taxonomy + sensory-words rule |
| `src/video/filmmaking-prompts.ts` | Consumes the blueprint into every scene packet |
| `schemas/video/artifacts/project-blueprint.schema.json` | Canonical artifact schema |