# Visual Bible — [PROJECT NAME]

> **Purpose:** Production-ready visual design document for storyboard and frame generation.
> Created during the Visual Design phase, after episodes are written, before storyboarding.
> Consumed by: `/storyboard` agent, `generate_from_storyboard.py`, Storyboard Editor

---

## Color Palette

| Name | HEX | Usage |
|------|-----|-------|
| [Primary] | #______ | [Where this color appears] |
| [Secondary] | #______ | [Where this color appears] |
| [Accent] | #______ | [Where this color appears] |
| [Alert/Warning] | #______ | [UI elements, danger signals] |
| [Environment Base] | #______ | [Dominant environment tone] |

### Per-Location Palettes

**[Location 1]:**
| Color | HEX | Element |
|-------|-----|---------|
| | #______ | Walls/surfaces |
| | #______ | Lighting |
| | #______ | Accent/detail |

---

## Characters

> **Header rule:** Use `### [Name]` exactly as it appears in characters.md (e.g., `### Jinx`, not `### Jinx — The Gambler`). The validator matches against characters.md names.

### [Character Name]

**Reference Sheet Status:** [ ] Not started / [ ] In progress / [ ] Locked

**Visual Summary:**
[One paragraph — the description that goes into every generation prompt for this character]

**Face/Body:**
- Age, build, distinguishing features
- Skin tone, hair (color, style, length)
- Identifying marks (scars, tattoos, implants, etc.)

**Wardrobe:**

| Arc Phase | Episodes | Description |
|-----------|----------|-------------|
| Default | 1-60 | [Primary outfit] |
| [Phase name] | [range] | [What changes and why] |

**Signature Props:**
| Prop | Description | Material/Color | When Visible |
|------|-------------|----------------|--------------|
| | | | |

**Reference Images:**
| Angle | File | Status |
|-------|------|--------|
| Front | [path] | [ ] Generated / [ ] Locked |
| Profile (left) | [path] | [ ] Generated / [ ] Locked |
| Three-quarter | [path] | [ ] Generated / [ ] Locked |
| Full body | [path] | [ ] Generated / [ ] Locked |
| Back | [path] | [ ] Generated / [ ] Locked |

**Flux 2 Reference Slot Assignment:** Slots 1-5 (character identity)

---

## Supporting Characters

> Minor/recurring characters that need visual notes but not full reference sheets.
> This is a separate h2 section — NOT under ## Characters — so the validator skips it.

**[Name]** (Ep N) — Brief visual description, distinguishing features, wardrobe notes.

---

## Props

### [Prop Name]

**Visual Summary:** [One sentence for prompt insertion]

**Details:**
- Dimensions (relative to hand/body)
- Materials and textures
- Colors (with HEX)
- Light behavior (does it glow? pulse? reflect?)
- State changes (does it look different when active vs. inactive?)

**Reference Images:**
| View | File | Status |
|------|------|--------|
| Default | [path] | [ ] Generated / [ ] Locked |
| Active state | [path] | [ ] Generated / [ ] Locked |

**Flux 2 Reference Slot Assignment:** Slot 5 (wardrobe/props)

---

## Locations

### [Location Name]

**Visual Summary:** [One paragraph for prompt context]

**Architecture:**
- Style (industrial brutalism, organic alien, Soviet concrete, etc.)
- Materials (concrete, metal, glass, biological, etc.)
- Scale (claustrophobic corridors, vast caverns, etc.)
- State of repair (pristine, weathered, decaying, destroyed)

**Lighting:**
- Primary light source
- Color temperature
- Shadow quality (hard/soft)
- Atmospheric effects (fog, dust, steam, sparks)

**Color Palette:**
| Element | HEX | Notes |
|---------|-----|-------|
| Walls/surfaces | #______ | |
| Primary light | #______ | |
| Accent light | #______ | |
| Shadow tone | #______ | |

**Sound/Atmosphere (for prompt context):**
- Ambient sounds that imply visual texture (dripping, humming, creaking)

**Reference Images:**
| View | File | Status |
|------|------|--------|
| Wide establishing | [path] | [ ] Generated / [ ] Locked |
| Detail/texture | [path] | [ ] Generated / [ ] Locked |

**Flux 2 Reference Slot Assignment:** Slots 6-7 (environment)

---

## VFX Elements

### [VFX Name]

**Type:** [ ] UI/HUD overlay / [ ] Practical effect / [ ] Post-production composite

**Visual Description:**
[What it looks like, for prompt engineering or compositor reference]

**Colors:**
| Element | HEX |
|---------|-----|
| | #______ |

**Behavior:**
- Static / animated / pulsing / scrolling
- Trigger conditions (when does it appear?)

**Production Notes:**
- [ ] Can be prompted in Flux 2
- [ ] Requires post-production compositing
- [ ] Needs motion graphics (After Effects / DaVinci)

---

## Lens Package

> **Purpose:** Codify the project's camera lens choices to maintain a consistent cinematic look across all generated frames.
> Most professional films limit lens choices to a small package. This section establishes those constraints.
> **Defaults from CONSTANTS.md:** Primary 50mm f/2.0, Close-Up 85mm f/1.4, Wide 24mm f/8
> Consumed by: `/storyboard` agent (populates `lens_package` in storyboard JSON), `generate_from_storyboard.py`

### Primary Lens (Standard Coverage)
- **Focal Length:** [e.g. 50mm]
- **Aperture:** [e.g. f/2.0]
- **Use For:** MS, MCU, dialogue scenes, general coverage
- **Look:** [Natural perspective, minimal distortion, moderate subject separation]

### Close-Up Lens (Emotional/Detail)
- **Focal Length:** [e.g. 85mm]
- **Aperture:** [e.g. f/1.4]
- **Use For:** ECU, CU, emotional beats, detail shots (hands, objects, faces)
- **Look:** [Strong background separation, soft bokeh, telephoto compression]

### Wide Lens (Environmental/Establishing)
- **Focal Length:** [e.g. 24mm]
- **Aperture:** [e.g. f/8]
- **Use For:** WIDE establishing shots, environmental reveals, action sequences
- **Look:** [Deep focus, dramatic perspective, spatial context]

### Specialty Lens (Optional)
- **Focal Length:** [e.g. 100mm macro, 14mm ultra-wide, tilt-shift]
- **Use For:** [Specific shots only — describe when this lens is used]
- **Look:** [Describe the distinctive visual effect]

### Film Stock Reference
- **Stock:** [e.g. Kodak Vision3 500T]
- **Look:** [Warm tones, visible grain, naturalistic color rendering]
- **Appended to all prompts** as: `"shot on [stock], [characteristics]"`

### Lens Assignment Rules

| Shot Type | Default Lens | Override When |
|-----------|-------------|---------------|
| ECU | Close-Up | — |
| CU | Close-Up | Wide spaces → Primary |
| MCU | Primary | Intimate moment → Close-Up |
| MS | Primary | — |
| LS | Wide | — |
| WIDE | Wide | — |
| POV | Primary | Match character's perspective |
| VFX | Varies | Match underlying shot type |

> **Rule:** Stick to the package. Only deviate for specialty shots where the visual effect is worth breaking consistency.
> **Reference:** `/appendix_e_flux2_protocols.md` → Cinematic Lexicon

---

## Lighting Guides

### [Scenario/Mood Name]

**Setup:** [Three-point, chiaroscuro, single source, volumetric, etc.]

**Prompt Language:**
```
[Exact lighting description to paste into generation prompts]
```

**Reference Image:**
| File | Status |
|------|--------|
| [path] | [ ] Found / [ ] Generated / [ ] Locked |

**Flux 2 Reference Slot Assignment:** Slot 8 (lighting reference)

---

## Production Notes

### Flux 2 Reference Slot Summary

| Slots | Assignment | Status |
|-------|------------|--------|
| 1-4 | [Character name] identity | [ ] Locked |
| 5 | [Prop/wardrobe item] | [ ] Locked |
| 6-7 | [Location name] environment | [ ] Locked |
| 8 | [Lighting setup] reference | [ ] Locked |
| 9-10 | Pose/layout guides | Reserved for per-shot use |

### LoRA Status

Registry: `[project]/visual/lora_registry.json` (managed by `tools/train_lora.py`)

| Character | Trigger | T2I Status | Video Status |
|-----------|---------|------------|--------------|
| [Name] | [TRIGGER] | [ ] Not trained / [ ] Training / [ ] Ready | [ ] Not trained / [ ] Training / [ ] Ready |

---

*Template version: 1.0*
*Source: `/templates/visual_bible_template.md`*
*Protocol: `/appendix_e_flux2_protocols.md`*