# Microdrama Production Pipeline -- Full Workflow

> **STALENESS WARNING (2026-04-25):** This document predates the June 1 refactor and describes the pre-CP-1/CP-2 architecture. The ASCII pipeline diagram, Phase 6 "router-pipeline" description, "Phase Mapping" table (Guide Phase 6 = Starsend visual production), Section 6.5 dual-engine description, and Section 11.5 "Dual-Engine Architecture & Cross-Repo Bridge" are inaccurate as of 2026-04-25. The visual pipeline now lives in `recoil/pipeline/` (single engine, not sibling repos), uses scene-level coverage passes (Formats A/B/C) via ProductionLoop + PassStore, and entry point is `/generate-video` → `recoil/pipeline/cli/generate.py`. Do not rely on this file for current pipeline behavior. Cross-reference: `audit-2026-04-25/pipeline-map.md` for current data flow, `recoil/pipeline/docs/coverage-pass-strategy.md` for the coverage pass spec. Scheduled rewrite: post-CP-2 verification (~2026-06-08).

**From concept to audience delivery**

| Phase | Name | Status |
|-------|------|--------|
| 1 | Development | ACTIVE -- fully built |
| 2 | Scripting | ACTIVE -- fully built, 7+ series complete |
| 2.5 | Script Doctor (Series-Level Revision) | ACTIVE -- pipeline built |
| 3 | Script Breakdown | ACTIVE -- Starsend Global Bible (Stage 1) + Opus Enrichment |
| 4 | Visual Design | ACTIVE -- Starsend casting pipeline (character angles, expressions, locations, props) |
| 5 | Storyboard | ACTIVE -- Starsend Plan Pass (Stage 2) + Previz pipeline |
| 6 | Visual Production | ACTIVE -- Flash 3.1 previz, NBP keyframes, Kling/SeedDance/Veo video, router-pipeline |
| 7 | Post-Production | PLANNED |
| 8 | Distribution | PLANNED |

> **Phase Mapping:** This guide uses 8 user-facing phases. The authoritative specification
> (`/WORKFLOW_SPEC.md`) uses 10 phases with explicit validation gates:
> Guide Phase 1 = Spec Phases 1-3 (Development → Validation → Promotion)
> Guide Phase 2 = Spec Phases 4-7 (Treatment → Validation → Generation → Validation)
> Guide Phase 3 = Spec Phase 8 (Script Breakdown)
> Guide Phase 4 = Spec Phase 9 (Visual Design)
> Guide Phase 5 = Spec Phase 10 (Storyboard)
> Guide Phase 6 = Starsend visual production (previz → keyframes → video → review)
> Guide Phases 7-8 extend beyond WORKFLOW_SPEC scope.

---

## 1. Pipeline Overview

```
                    THE RECOIL MICRODRAMA PIPELINE

  DEVELOPMENT         SCRIPTING          SCRIPT DOCTOR        SCRIPT BREAKDOWN     VISUAL DESIGN
  ============        ============       ==============       ================     =============
  Concept/Premise     Promoted Project   60 eps + bible       60 revised eps       Starsend Casting:
       |                   |                  |                    |               hero images, angles,
       v                   v                  v                    v               expressions, locations
  34-point checklist   Treatment +        Gemini reads ALL     Starsend Global         |
  Character DNA        Orchestrated       60 episodes at       Bible (Stage 1)         v
  Thematic spine       generation         once → finds         + Opus Enrichment   Character refs,
  Pressure testing     Validation gates   systemic issues      → characters,       expression matrix,
       |                   |              → annotations           locations,       location moodboards,
       v                   v              → /revise batch         props, motifs    prop refs
  Promoted project     60 validated       → deep fix P1s            |                    |
  (series bible,       episodes per       → verify             global_bible.json        v
  characters,          series                  |                    |              Locked ref images
  episode arc)              |                  |                    |              + visual_bible.md
       |                    |                  |                    |                    |
       |                    |          [PRODUCTION CONSOLE]  [PRODUCTION CONSOLE]  [PRODUCTION CONSOLE]
       |                    |           Revision + Grammar    Breakdown tab         Casting tab
       |                    +--------+---------+---------+---------+---------+--------+
       +--------+-----------+                                                |
                |                                                            v
                v                                  STORYBOARD          VISUAL PRODUCTION
        STARSEND PIPELINE     POST-PROD           ============         ================
        =================     ==========          Plan Pass            Previz (Flash 3.1)
        Camera Test +          Raw clips           (Stage 2) →              |
        Global Bible +              |              ep_NNN_plan.json         v
        Plan Pass                   v              + shot routing      Keyframes (NBP)
             |                Upscaling,      [PRODUCTION CONSOLE]          |
             v                lip sync,        Storyboard tab               v
        plans/ep_NNN_plan     compositing,            |              Video generation
        (5 consumer groups)   color grade              v              (Kling/SeedDance/Veo)
             |                sound design       Previz → Review           |
             v                     |                                       v
        Previz → Keyframes         v          DISTRIBUTION          [PRODUCTION CONSOLE]
        → Video generation    Final episode   ============           Previz + Dailies tabs
  [PRODUCTION CONSOLE]       video           Platform, metadata,
   Previz + Dailies tabs                     analytics → Revenue
```

**Total pipeline:** Concept enters Phase 1. Revenue exits Phase 8. Phases 1-3 are fully automated via the narrative engine. Phases 4-8 involve progressively more human-in-the-loop work, though automation is planned for each.

---

## 2. Phase 1: Development

**Status: ACTIVE -- Fully Built**

### Input
- Concept or premise (a one-sentence idea)

### Process

The development phase uses a **34-point character-first checklist** organized into 7 sections:

| Section | Items | What It Produces |
|---------|-------|------------------|
| Characters First | 10 | Protagonist, antagonist, and emotional anchor with behavioral DNA, voice patterns, humor types, need layers |
| Pressure Test | 2 | Non-canonical collision sequences that discover (not design) thematic tension |
| Thematic Spine | 5 | Theme, thematic question, protagonist/antagonist stances, mythological DNA |
| Concept & Hook | 5 | Surprising conceit, logline, genre blend, demographic hook, archetype-worldview |
| Emotional Architecture | 4 | Anchor type, primary ache, relationship milestones |
| World | 3 | Setting, rules/constraints, factions/power structure |
| Structure | 5 | Three-act breakdown, eight-sequence skeleton, key plot points, emotional beat schedule |

**Key principle:** Characters are developed BEFORE theme. Theme is discovered through character collision, not designed upfront. This produces characters that feel like people rather than thesis statements.

### Tools

| Command | Purpose |
|---------|---------|
| `/develop [project]` | Interactive development through the 34-point checklist |
| `/showrunner [project]` | Agent-driven development with specialist sub-agents (character agent, plot agent, world agent) |
| `/validate [project]` | Comprehensive pre-promotion validation |
| `/promote [project]` | Transforms development project into production-ready scripting folder |

### Validation Gates (Hard)

1. **Behavioral DNA Gate** -- validates filmable on-screen behaviors (not backstory), stress behaviors, signature lines, orthogonal traits, contradictions
2. **Arc Validation Gate** -- validates 60-episode structure, cliffhanger distribution, emotional beat schedule, thread coverage
3. **Comprehensive Validation** -- all 34 checklist items, all required documents, thematic question clarity, primary ache intensity
4. **Promotion Gate** -- pre-treatment structural check

All gates must pass before promotion. There is no manual override.

### Output
- `/[project]/bible/series_bible.md` -- world, theme, constraints
- `/[project]/bible/characters.md` -- full behavioral DNA, voice patterns, arcs
- `/[project]/bible/episode_arc.md` -- 60 episodes with one-line summaries, cliffhanger types, intensity scores
- `/[project]/state/current_state.json` -- initialized generation state
- `/[project]/ORCHESTRATION.md` -- project-specific generation rules

### Gate
34/34 checklist items complete. All validation scripts pass (exit code 0).

---

## 3. Phase 2: Scripting

**Status: ACTIVE -- Fully Built. 7+ series with 60 episodes each have been generated.**

### Input
- Promoted project folder from Phase 1

### Process

Scripting proceeds through two major sub-phases:

**Treatment Creation:**
The treatment is a 3,000-4,000 word prose document that serves as the master generation input. Each of the 60 episodes gets a prose paragraph containing:
- Metadata (sequence, beat type, hook type, cliffhanger type)
- Thread markers (PLANT, ADVANCE, PAYOFF)
- THE MOMENT -- the single most important image or line in the episode
- VOICE SEED (Episode 1 only) -- establishes character speech patterns
- Prose paragraph describing the episode
- Cliffhanger image -- exact visual or line that ends the episode

Treatment metadata uses **subtype codes** (e.g., S-VP, M-PT, M-CF) for hook and cliffhanger types, not just main categories (SILENT, MID-ACTION). Both formats are accepted for backward compatibility.

**Treatment Close Read (Mandatory Two-Pass):**
After treatment validation passes, a close read runs automatically. First pass catches obvious gaps (cliff→hook logic, spatial continuity, thread integrity, character motivation, filmability). Fixes are applied. Second pass re-reads the entire treatment to catch fix-introduced issues, obscured problems, and reverse-direction gaps (hook→cliff within episodes). The close read is not done until two consecutive passes find zero issues, or all remaining issues are acknowledged as intentional.

**Orchestrated Episode Generation:**
The recommended generation mode (`/generate-orchestrated`) uses a two-tier architecture:

```
ORCHESTRATOR AGENT (lightweight, maintains global state)
  |
  |-- Tracks: threads, emotional beats, pattern variety, voice drift
  |
  +-- Spawns BATCH SUB-AGENTS (fresh context per batch of 5 episodes)
      |
      |-- Batch 1: Episodes 1-5    (pristine context)
      |-- Batch 2: Episodes 6-10   (pristine context)
      |-- ...
      |-- Batch 12: Episodes 56-60 (pristine context)
```

Each batch sub-agent:
1. Reads the treatment for its 5 episodes
2. Reads character behavioral DNA and voice patterns
3. Generates episodes in the Kill Box format (90 seconds, 450-500 words per CONSTANTS.md)
4. Validates each episode via Python script before proceeding
5. Runs checkpoint validation for the batch
6. Reports results to orchestrator

**Per-Episode Validation (Mandatory):**
After every episode is written, `episode_metrics.py` validates:
- Total word count (450-500 per CONSTANTS.md, hard fail)
- Dialogue percentage (max 40% per CONSTANTS.md, hard fail)
- Exchange count (max 8, hard fail)
- Format compliance

If validation fails, the episode is iteratively edited and re-validated (max 3 attempts).

**Per-Batch Checkpoint Validation:**
After every 5-episode batch, `save_checkpoint.py` runs a three-gate check:
- Gate 1 (Mechanical): word count, dialogue %, exchanges, format, meta-reference detection
- Gate 2 (Quality): pattern variety, emotional beats, continuity
- Gate 3 (Dramatic QC): voice consistency, behavioral DNA expression, relationship earning

### Tools

| Command | Purpose |
|---------|---------|
| `/treatment [project]` | Generate prose treatment from episode arc |
| `/generate-script-orchestrated [project]` | Production-grade generation with fresh sub-agents and cross-series verification |
| `/generate-script [project]` | Manual generation with user-controlled compaction |
| `/autogenerate-scripts [project]` | Fully autonomous generation (never stops) |
| `/assess [project] --lens [lens]` | Post-generation quality assessment through specific lenses |
| `/rewrite [project] ep [N] "[issue]"` | Targeted rewrite of specific episodes |
| `/thread [project] "[name]" --episodes [N,N,N]` | Retrofit narrative threads across episodes |
| `/compile [project]` | Merge episodes into Fountain screenplay format |
| `/dramatic-qc [project]` | Evaluate dramatic quality (voice, texture, earning) |
| `/script-doctor [project]` | Full-series diagnostic via Gemini — 6 dimensions, annotation-ready output |
| `/revise [project] [annotations.json]` | Batch-apply annotations from script doctor or revision editor |

### Episode Format: The Kill Box

Every episode follows a 90-second, 5-section structure:

| Section | Timestamp | Duration | Typical Words |
|---------|-----------|----------|---------------|
| HOOK | [00:00-00:05] | 5 sec | ~25 words |
| SETUP | [00:05-00:15] | 10 sec | ~50 words |
| ESCALATION | [00:15-00:40] | 25 sec | ~100 words |
| TURN | [00:40-00:70] | 30 sec | ~100 words |
| CLIFFHANGER | [00:70-00:90] | 20 sec | ~50 words |

Pattern distribution rules enforce variety:
- 70-85% silent hooks / 15-30% dialogue hooks (per CONSTANTS.md)
- 70-85% mid-action cliffhangers / 15-30% aftermath cliffhangers (per CONSTANTS.md)
- Maximum 3 consecutive episodes of the same **subtype** (4+ is a hard violation). Different subtypes within the same main category (e.g., M-CF then M-PT then M-CT) do NOT count as consecutive. Main-category runs are informational soft flags only.

### Output
- 60 validated episode scripts per series (450-500 words each, per CONSTANTS.md)
- State tracking (checkpoint history, cliffhanger/hook patterns, voice baselines)
- Batch summaries with thread tracking and emotional beat verification

### Gate
All 60 episodes pass `episode_metrics.py`. All 12 batch checkpoints pass. Pattern variety validated. Emotional beat schedule complete (11/11 beats hit).

### Production Record

| Series | Episodes | Status |
|--------|----------|--------|
| Leviathan | 5 (in progress, 3rd generation) | Active generation |
| Olympus | 60 | Complete |
| ASI-Bridge | 60 | Complete |
| Borders | 66 | Complete |
| The Eye | 60 | Complete |
| The Hike | 60 | Complete |
| Singularity | 60 | Complete |
| Eye | 60 | Complete |
| Time Enough for Love | 60 | Complete |

Total episodes generated: **431+** across 9 series.

---

## 3.5 Phase 2.5: Script Doctor (Series-Level Revision)

**Status: ACTIVE -- Pipeline built**

### Purpose

After all 60 episodes are generated, the Script Doctor reads the **entire series in a single context window** via Google Gemini's 1M-token API. This catches systemic issues that are invisible at the batch level — voice drift that accumulates across 12 batches, catchphrases that appear 3x per batch but 36x across the series, arcs that skip intermediate beats, threads that are planted but never pay off.

**Key architectural principle:** The script doctor is a *permanent* pipeline layer, not a temporary fix. System-level changes to characters.md or ORCHESTRATION.md risk flattening texture because Claude's batch generation can't make intelligent placement decisions across 60 episodes. The per-instance revision pass IS the solution.

### Input
- Completed episode scripts (60 validated episodes from Phase 2)
- Character bible (`bible/characters.md`)
- Treatment (`treatment.md`)
- Orchestration rules (`ORCHESTRATION.md`)

### Multi-Pass Architecture

The script doctor runs in multiple internal passes, producing a single combined brief:

**Pass 1: Structural (Transitions — Inter + Intra)** — Checks transitions at TWO levels in a single Gemini call using the THEREFORE/BUT vs AND THEN rule:

- **Inter-episode** (59 boundaries): Every cliffhanger→hook boundary. Also checks spatial continuity, character positioning, emotional carry-over, off-screen resolution. Findings use T-prefixed IDs (T001, T002...).
- **Intra-episode** (240 boundaries): Every Kill Box section boundary within each episode (HOOK→SETUP→ESCALATION→TURN→CLIFFHANGER). Flags convenience — obstacles, locations, or characters that appear without setup. Findings use I-prefixed IDs (I001, I002...).

| Connector | Meaning | Quality |
|-----------|---------|---------|
| **THEREFORE** | Previous beat causes/necessitates the next | Good |
| **BUT** | Next beat complicates/subverts expectations | Good |
| **AND THEN** | Next beat merely follows chronologically, no causal link | **Failure** |

**Pass 2: Series-Level (6 Dimensions)** — Evaluates across 6 series-level dimensions:

| # | Dimension | What It Catches |
|---|-----------|-----------------|
| 1 | **voice** | Drift, convergence, calcification, "never say" violations across full series |
| 2 | **pattern_fatigue** | Catchphrase overuse, physical tic repetition, idiom loops, structural rhythm monotony |
| 3 | **arc_earning** | Character transformations + relationships: missing beats, unearned shifts, skipped milestones |
| 4 | **continuity** | Thread integrity, planted-but-unresolved, knowledge consistency, world logic, batch-boundary artifacts |
| 5 | **texture_tone_vitality** | Register variety, Kill Box fatigue, breathing room, surprise distribution, humor, play, fun — does this feel alive or like a formula? |
| 6 | **exposition_load** | Dialogue-as-narration, "as you know" patterns, missed visual storytelling opportunities |

These dimensions are a **reporting vocabulary**, not a search directive. The diagnostic prompt says: "Read this entire series and tell me everything that's wrong. When you report findings, classify them using these categories — but if you find something that doesn't fit, report it under 'uncategorized'." This gives Gemini freedom to find surprises AND a structured vocabulary for filing what it finds.

**Why transitions run first:** Transition fixes ADD text (bridge lines, modified hooks/cliffhangers). That new text needs downstream evaluation for voice consistency, arc earning, etc. Structural analysis first, refinement second.

### The Prompts

| Prompt | Purpose | API Calls | Output |
|--------|---------|-----------|--------|
| **Structural** | Transition analysis (Pass 1) | 1 | Transition findings with T-prefixed IDs |
| **A: Diagnostic** | Full-series analysis (Pass 2) | 1 | Series-level findings with F-prefixed IDs |
| **Focused** | Per-dimension deep dive (Pass 3) | 0-6 | Findings for gap dimensions |
| **B: Deep Fix** | Structural P1 fix (Pass 4) | 1 per P1 FLAG | Bridge scenes, rewrite guidance |
| **C: Verification** | Post-revision check | 1 | Resolved/unresolved status + new issues |

All single-shot. No back-and-forth. Typical `--full` run: 1 structural + 1 broad + 2-3 focused + 7 close-read batches + 0-2 deep fixes = 11-14 calls total.

**Close Read (Mandatory Two-Pass):** The close read (7 batches, scene-level) uses the same two-pass protocol as the treatment close read. First pass catches obvious gaps across 5 categories (spatial logic, motivation grounding, scene-to-scene transitions, physical consistency, filmability gate). Fixes applied. Second pass re-reads the entire corpus and also checks Kill Box segment transitions, dialogue consistency, and intra-scene spatial tracking. Not done until two consecutive passes find zero issues, or all remaining issues are acknowledged as intentional.

### Process

```
60 Validated Episodes + Bible + Treatment
        |
        v
script_doctor.py --diagnose              ← Prompt A: full-series diagnostic via Gemini
        |
        v
script_doctor_brief.json (v2)            ← Findings with inline annotations
        |
        v
script_doctor.py --to-annotations        ← Flatten annotations for /revise
        |
        v
script_doctor_annotations.json           ← /revise-ready annotation file
        |
        +---> /revise [project] annotations.json    ← Batch-apply REWRITE/DELETE
        |
        +---> script_doctor.py --deep-fix F002      ← Prompt B: structural P1 fixes
        |           |
        |           v
        |     deep_fix_F002.json          ← Bridge scenes, rewrite guidance
        |           |
        |           v
        |     /rewrite [project] ep [N]   ← Apply structural fixes per-episode
        |
        v
script_doctor.py --verify                ← Prompt C: confirm fixes landed
        |
        v
script_doctor_verify.json                ← PASS or NEEDS_WORK (loop if needed)
```

**Step-by-step:**

1. **Diagnostic** (`--diagnose`): Bundles the complete corpus into a 4-tier payload (engine constraints → intended story → audience context → episodes) and sends to Gemini. The prompt opens with a vitality frame ("these scripts need to feel ALIVE"), asks the open diagnostic question ("tell me everything that's wrong"), and provides the 6 dimensions as filing vocabulary. Output is a structured brief where each finding contains an `annotations` array with exact episode quotes and action types.

2. **Extract Annotations** (`--to-annotations`): Flattens the brief's nested annotation structure into a flat `/revise`-ready JSON file. For v2 briefs this is trivial (no quote matching). For legacy v1 briefs, falls back to the old fuzzy-match conversion.

3. **Batch Apply** (`/revise`): The revision agent processes REWRITE and DELETE annotations in batch. FLAG annotations are displayed for discussion but not automatically applied.

4. **Deep Fix** (`--deep-fix F002`): For structural P1 findings (unearned arcs, missing beats, pacing restructuring) that need creative content, not just text substitution. Sends the specific finding + character data + affected episodes to Gemini. Output includes bridge scene drafts (150-200 words each), rewrite guidance, continuity impact notes, and Behavioral DNA alignment checks. Applied via `/rewrite` per-episode.

5. **Verification** (`--verify`): Re-bundles the revised corpus and sends to Gemini with the original brief. For each finding: RESOLVED / PARTIALLY_RESOLVED / UNRESOLVED. Also checks for NEW issues introduced by revisions. If unresolved, loop.

### Manual Gemini Workflow

For testing or when you want to inspect the prompts before committing API calls, the script doctor supports a manual copy-paste workflow via Google AI Studio:

```bash
# 1. Generate the payload (no API call)
python3 script_doctor.py leviathan --diagnose --dry-run
# → Saves to leviathan/state/script_doctor_diagnostic_payload.txt

# 2. Open Google AI Studio (https://aistudio.google.com)
#    Paste the payload content, run with Gemini 3 Pro
#    Copy the response, save to a .txt file

# 3. Feed the response back for parsing
python3 script_doctor.py leviathan --parse-response response.txt
# → Parses JSON, saves brief, prints summary

# Also works for verification and deep fix:
python3 script_doctor.py leviathan --verify --dry-run
python3 script_doctor.py leviathan --parse-response verify_response.txt --parse-type verify

python3 script_doctor.py leviathan --deep-fix F002 --dry-run
python3 script_doctor.py leviathan --parse-response deepfix_response.txt --parse-type deep-fix
```

This lets you use the free tier in AI Studio (your data may be used for training) or your subscription credits without needing the `google-generativeai` Python package or API key configured locally.

### Severity Levels

| Level | Definition | Action |
|-------|-----------|--------|
| **P1** | Must fix. Actively damages the series — unearned arcs that break audience trust, repetition so heavy it becomes a meme, voice collapse that makes characters interchangeable. | Address before moving to Phase 3. |
| **P2** | Should fix. Noticeable quality issue that a careful viewer catches — moderate repetition, pacing drag, exposition that slows momentum. | Address if revision budget allows. |
| **P3** | Consider. Polish-level — minor variety improvements, subtle exposition reduction, small voice refinements. | Nice to have. |

### Annotation-Ready Output (v2)

The v2 brief format eliminates the brittle quote-matching conversion layer from v1. Each finding now contains an `annotations` array directly:

```json
{
  "version": "2.0",
  "findings": [
    {
      "id": "F001",
      "dimension": "pattern_fatigue",
      "severity": "P1",
      "title": "Jinx 'sixty-forty' overuse",
      "description": "Catchphrase appears in 28 of 60 episodes...",
      "episodes": [1, 4, 7, 14, 20, 24, 25, 29],
      "annotations": [
        {
          "episode": 4,
          "line": 0,
          "action": "REWRITE",
          "selected_text": "Sixty-forty we make it through this.",
          "note": "[F001/P1] Catchphrase overuse. Replace with gambler alternative."
        }
      ]
    }
  ]
}
```

Annotations use `selected_text` (exact quotes from episodes) rather than line numbers — the `/revise` agent finds the text by searching the episode file. This is robust against minor episode edits that would shift line numbers.

### Tools

| Tool | Purpose | Status |
|------|---------|--------|
| `script_doctor.py` | Corpus bundling, Gemini API interaction, brief management, annotation extraction | Built |
| `/script-doctor [project]` | Skill interface for the diagnostic workflow | Built |
| `/revise [project] [annotations.json]` | Batch-apply annotations from script doctor output | Built |
| `/rewrite [project] ep [N] "[issue]"` | Per-episode structural fixes (for deep fix output) | Built |
| `revision_editor.html` | Visual annotation editor — load Fountain scripts, view/edit revision annotations, export | Built |

### API & Cost

| Model | Input / 1M tokens | Output / 1M tokens | Typical diagnostic call (~100K in, ~30K out) |
|-------|-------------------|---------------------|----------------------------------------------|
| Gemini 3 Pro Preview (default) | $2.00 | $12.00 | ~$0.56 |
| Gemini 2.5 Pro (fallback) | $1.25 | $10.00 | ~$0.43 |

With Google AI Ultra ($249.99/mo) providing $100/month in Google Cloud credits, a full revision pass (4-5 API calls) costs under $5. The free tier in Google AI Studio also works for testing via the manual workflow.

### Output
- `[project]/state/script_doctor_brief.json` — structured diagnostic with inline annotations
- `[project]/state/script_doctor_annotations.json` — flat annotation file for `/revise`
- `[project]/state/deep_fix_F00N.json` — bridge scenes and rewrite guidance per structural finding
- `[project]/state/script_doctor_verify.json` — verification report

### Gate
- All P1 findings addressed (resolved or consciously accepted)
- Verification pass returns PASS or acceptable NEEDS_WORK
- No new P1 issues introduced by revisions

---

## 4. Phase 3: Script Breakdown

**Status: ACTIVE -- Pipeline built**

### Input
- Completed episode scripts (from Phase 2)
- characters.md with Visual Design sections (from Phase 1 promotion)

### Purpose

Extract every visual production asset from the episode scripts into a structured JSON database. This produces the "asset inventory" that informs Visual Design decisions and feeds directly into the storyboard pipeline.

**Why before Visual Design?** You need to know what locations, props, wardrobe phases, VFX elements, and SFX exist across all 60 episodes before designing the visual look. The breakdown extracts this systematically so nothing is missed.

### Process

```
Episode Scripts (60 episodes)
        ↓
script_breakdown.py                 ← Python extraction (deterministic checklist)
        ↓
Gemini structural synthesis         ← All episodes → global_bible.json (Pass 1)
        ↓
Python validation                   ← Compare regex checklist vs Gemini output
        ↓
Opus prose enrichment               ← Dense descriptions, wardrobe prose (Pass 2)
        ↓
Derive breakdown.json               ← Schema translation from global_bible.json
        ↓
validate_breakdown.py               ← Three-tier validation (hard gate)
        ↓
visual/breakdown.json               ← Structured asset database
```

**Two-Pass Architecture:**

1. **Python Extraction** (`script_breakdown.py`): Scans all episodes + characters.md. Produces a deterministic asset checklist — characters, locations, props, SFX, VFX.

2. **Gemini Structural Synthesis** (Pass 1): Reads all episodes at once via Gemini 3.1 Pro's 1M+ token context window. Synthesizes character phases with exact episode boundaries, lighting profiles, lighting motifs, location consolidation with habitat zones. Outputs `global_bible.json` with `[OPUS_ENRICHMENT]` placeholders for prose fields.

3. **Python Validation**: Compares regex checklist against Gemini output — any missing assets?

4. **Opus Prose Enrichment** (Pass 2): Takes Gemini's structural output, writes dense evocative descriptions, wardrobe prose, reference prompts. Fills `[OPUS_ENRICHMENT]` placeholders.

5. **Schema Translation**: `breakdown.json` is derived from `global_bible.json` — pure Python mapping, no LLM needed.

6. **Validation** (`validate_breakdown.py`): Three-tier check:
   - **Tier 1 (Hard Errors, exit 1):** All episodes processed, all characters present, visual descriptions exist, wardrobe covers all episodes
   - **Tier 2 (Warnings, exit 2):** State change continuity, prop ownership, location consistency
   - **Tier 3 (Info):** Prompts populated, reference paths valid, VFX methods assigned

### Starsend Intake

After breakdown, the project is ready for Starsend's 3-stage extraction pipeline:

```
/breakdown [project]                → visual/breakdown.json + global_bible.json
        ↓
Stage 0: Camera Test               → state/visual/camera_tested/ep_NNN.json
  /camera-test [project] ep 1-3       (one paragraph = one camera shot)
        ↓
Stage 1: Global Bible               → state/visual/global_bible.json
  Gemini structural synthesis          + Opus prose enrichment
        ↓
Stage 2: Plan Pass (Storyboard)     → plans/ep_NNN_plan.json
  Shot plans with 5 consumer groups    (routing, prompt, spatial, asset, audio)
```

The plan pass output contains compiled prompts for every target model (previz Flash, keyframe NBP, Kling I2V/T2V, SeedDance, Veo) plus pipeline routing decisions (still → I2V vs direct T2V vs multi-shot).

### Tools

| Tool | Purpose | Status |
|------|---------|--------|
| `/breakdown [project]` | Full extraction + enrichment + validation | Built |
| `/breakdown [project] --prompts ref` | Generate rich photorealistic reference prompts for all assets | Built |
| `script_breakdown.py` | Python extraction engine | Built |
| `validate_breakdown.py` | Three-tier validation (includes prompt quality checks) | Built |
| `batch_generate_refs.py` | Batch image generation via Gemini API (with validation + auto-retry) | Built |
| `visual_qc.py` | Audit breakdown.json for visual production readiness | Built |
| `breakdown_editor.html` | Visual asset management tool | Built |
| `references_editor.html` | Edit prompts, browse/replace generated refs, auto-save to disk, lock variants | Built |
| `breakdown_schema.json` | Canonical data contract | Built |
| `appendix_f_midjourney_v7_protocols.md` | MJ V7 parameter reference (legacy — reference prompts are now engine-agnostic) | Built |

### Output
- `visual/breakdown.json` — structured asset database for the entire series
- `visual/refs/` directories — reference image slots (populated in Visual Design)

### Gate
- `validate_breakdown.py` passes with exit code 0 (no tier 1 errors)
- All episodes processed
- All characters have visual descriptions
- Wardrobe phases cover all episodes

---

## 5. Phase 4: Visual Design

**Status: ACTIVE -- Starsend casting pipeline, expression library, location/prop refs**

### Input
- Script breakdown (from Phase 3: `visual/breakdown.json`)
- Completed episode scripts (from Phase 2)
- Series bible, characters.md (from Phase 1 promotion)

### Purpose

Lock down the visual look of the series before storyboarding. This phase produces the production design documents and reference images that ensure visual consistency across all generated frames and video.

**Why after episode generation?** You need the scripts to know what locations, props, and wardrobe exist. You wouldn't know to design "the Forgotten's dwellings" or a specific prop unless it appears in an episode.

### Process

1. **Create Visual Bible** from template (`/templates/visual_bible_template.md`):
   - Color palette with HEX codes per location tier
   - Character designs: face/body details, wardrobe per arc phase
   - Props: dimensions, materials, colors, light behavior
   - Locations: architecture, materials, lighting, atmosphere
   - VFX elements: UI overlays, practical effects, composites
   - Lighting guides with exact prompt language

2. **Character Casting** via Starsend Production Console:
   - Generate concept grids (multiple looks per character)
   - Select hero image (white-bg, pristine — the identity anchor)
   - Generate turnaround shots (front, profile, three-quarter, full body)
   - `wash_mj_heroes.py` — clean MidJourney artifacts from hero images
   - `prep_character_angles.py` — generate angle shots from hero
   - Lock character design in Production Console Casting tab

3. **Expression Library Generation** (`prep_expressions.py`):
   - 27 universal refs per character: 9 emotions × 3 intensities
   - Emotions: joy, anger, sadness, fear, surprise, disgust, contempt, exhaustion, resolve
   - Intensities: subtle, moderate, intense
   - Fed as inline refs during generation (recency-bias ordering)

4. **Location Reference Generation**:
   - `prep_location_refs.py` — generate moodboard refs for key locations
   - `generate_location_refs.py` — batch generation from global bible location data
   - Habitat zones consolidate 60-70+ locations into 4-6 production habitats

5. **Prop Reference Generation** (`prep_prop_refs.py`):
   - Product-style shots of key props from global bible
   - Materials, dimensions, light behavior captured

6. **Design Lock Writeback** (`visual_sync.py`):
   - Vision-based bible text extraction from approved images
   - Updates global_bible.json with locked visual descriptions

### Tools

| Tool | Purpose |
|------|---------|
| `prep_character_angles.py` | Generate angle shots from hero image |
| `prep_expressions.py` | Generate 27-expression matrix per character |
| `prep_location_refs.py` | Generate location moodboard refs |
| `generate_location_refs.py` | Batch location ref generation from global bible |
| `prep_prop_refs.py` | Generate prop reference shots |
| `wash_mj_heroes.py` | Clean MidJourney artifacts from hero images |
| `visual_sync.py` | Design lock writeback (vision-based text extraction) |
| Production Console (Casting tab) | Visual casting workflow — grids, hero selection, turnarounds |
| `/templates/visual_bible_template.md` | Visual Bible template |
| `/tools/visual_qc.py` | Audit breakdown.json for visual production readiness |
| Gemini API (NBP / Flash 3.1) | Character/location/prop reference image generation |

### Lens Package & Film Stock

The **lens package** is a per-project creative constraint mimicking professional film production. Most films limit lens choices to maintain a consistent visual language.

| Lens | Default | Use For |
|------|---------|---------|
| Primary | 50mm f/2.0 | MS, MCU, dialogue, general coverage (per CONSTANTS.md) |
| Close-Up | 85mm f/1.4 | ECU, CU, emotional beats, detail shots (per CONSTANTS.md) |
| Wide | 24mm f/8 | Establishing shots, environmental, action (per CONSTANTS.md) |
| Specialty | Varies | Project-specific (macro, tilt-shift, etc.) |

**Film stock** (e.g., "Kodak Vision3 500T") is a per-project creative choice codified in `visual_bible.md`. It is consumed by the prompt engine when building generation prompts — included as natural language descriptors in the prompt body.

**Lens and film stock in reference prompts:** Include focal length and film stock descriptors in the prompt body text (e.g., "shot on 85mm lens", "Kodak Vision3 500T color science") for photorealistic detail. Reference prompts are engine-agnostic.

### Output
- `visual_bible.md` — production design document (lens package, HEX palettes, film stock, lighting guides)
- `visual/refs/characters/` — per-wardrobe-variant reference images (hero + 4 angles each)
- `visual/refs/characters/[CHAR]/expressions/` — 27-expression matrix per character
- `visual/refs/locations/` — moodboard refs per location / habitat zone
- `visual/refs/props/` — product shot per prop
- `visual/refs/lighting/` — mood/scenario reference images

### Habitat Zones (Location Consolidation)

**Status: BUILT -- Leviathan zones defined, breakdown.json updated with zone assignments**

The habitat zone concept consolidates 60-70+ script locations into 4-6 production habitats per project. Each zone gets one **hero key art image** that establishes materials, color temperature, lighting logic, and scale. All sub-locations within a zone derive from that hero's visual DNA -- same materials, same lighting, different framing and details.

**Leviathan zones:** 5 zones covering 72 locations with 6 hero images (Zone 5 splits into bay + surface).

| Zone | Locations | Hero Images |
|------|-----------|-------------|
| Lower Decks (Salvage Territory) | 13 | 1 |
| Mid-Ship Infrastructure | 25 | 1 |
| The Root (Organic Growth) | 16 | 1 |
| Crown Level (Command) | 6 | 1 |
| Shuttle Bay & Planet Surface | 12 | 2 |

Hero key art prompts defined in `/[project]/visual/habitat_zones.md`. This pattern scales to any project.

### Identity Strategy (Current: Frontier Model References)

Character identity is maintained via inline reference images sent to frontier models
(NBP supports up to 11 refs per generation). No training required — identity comes
from reference quality and recency-bias ordering.

**Reference set per character:**
- Hero image (white-bg, pristine — never altered)
- 4+ angle shots (front, profile, three-quarter, full body)
- Universal expression matrix (27 refs: 9 emotions × 3 intensities)
- Wardrobe phase variants (per-episode costume changes)

**Recency bias ordering:** Scene → Pose → Expression → Identity → Prompt

> **LoRA Option:** If we return to open-source models (Flux, WAN, etc.), the full LoRA
> training pipeline is preserved in `docs/archive/lora_training_best_practices.md` and
> `docs/archive/candidate_generation_engines.md`. The `train_lora.py`, `batch_threepass.py`,
> and `lora_picker.html` tools remain in the codebase.

### Coverage Model (Setup-Based Generation)

**Status: DESIGNED -- specification complete, not yet integrated into storyboard schema**

Generate **setups** (unique camera positions), not individual shots. A 20-shot conversation scene with 4 setups requires 4 keyframe generations instead of 20 -- a ~54% cost reduction while improving background consistency.

Full specification: `/[project]/visual/COVERAGE_MODEL.md`

### Gate
- All main characters have locked hero + angle refs
- Expression matrix generated (27 refs per character)
- Key locations have moodboard refs
- Color palette has HEX codes
- Lens package and film stock defined
- Visual bible reviewed and approved by human

---

## 6. Phase 5: Storyboard

**Status: ACTIVE -- Starsend Plan Pass (Stage 2), router-pipeline shot routing**

### Input
- Episode scripts (from Phase 2)
- Script breakdown (from Phase 3: `global_bible.json`)
- Visual bible + reference images (from Phase 4)
- Character refs + expression matrix (from Phase 4)

### Process

The storyboard phase converts each episode script into a structured JSON shot plan with generation-ready prompts and pipeline routing decisions.

```
Episode Script (ep_NNN.md)
        ↓
Starsend Plan Pass (Stage 2)        ← Shot plans with 5 consumer groups
        ↓                              (routing, prompt, spatial, asset, audio)
plans/ep_NNN_plan.json              ← Structured shot breakdown per episode
        ↓
Storyboard Editor (HTML tool)       ← Human edits visually
        ↓
plans/ep_NNN_plan.json              ← Updated with edits + director notes
        ↓
Previz Generation (Flash 3.1)      ← Quick visual gut-check (~$0.039/frame)
        ↓
Production Console → Previz tab    ← Approve/reject/regenerate
        ↓
4-Gate Validation Framework         ← Ref consistency → artifacts → semantics → identity drift
        ↓
Approved Plans → Keyframe + Video Generation (Phase 6)
```

### Storyboard Schema v3

The v3 schema (updated 2026-02-06) adds five fields per shot:

| Field | Type | Description |
|-------|------|-------------|
| `generation_approach` | enum | `triptych_split_flf`, `standard_flf`, `held_frame_push`, `held_frame_static` |
| `hero_frame` | string/null | E-style ~150-180 word decisive moment prose (triptych shots only) |
| `triptych_prompt` | string/null | Full 3-panel strip prompt (triptych shots only) |
| `asset_name` | string | Naming convention base (e.g., `LEV_EP001_S10_T01_JINX`) |
| `characters_in_shot` | array | Explicit character list |

**Generation Approach Classification:**

Each shot is classified by its visual generation strategy:

| Approach | When to Use | Keyframes | Video |
|----------|-------------|-----------|-------|
| `triptych_split_flf` | Climactic action, reveals, high-impact moments | 3 (anticipation/peak/aftermath from strip) | 2-segment FLF (f1→f2, f2→f3) |
| `standard_flf` | Normal motion — dialogue, movement, transitions | 2 (first + last) | 1 standard FLF |
| `held_frame_push` | Minimal motion — expressions, reveals, subtle shifts | 1 (first only) | Ken Burns push |
| `held_frame_static` | No motion — VFX composites, final images, data overlays | 1 (first only) | None (static frame) |

**EP001 Classification (21 shots):**
- Triptych (6): boots_hit_catwalk, cryo_pod_reveal, seal_crack, gas_venting_corridor, eyes_snap_open, hand_on_throat
- Standard FLF (9): corridor_rust_drift, hook_scrapes_metal, jinx_works_panel, shaft_revealed, fingers_counting_odds, jinx_sixty_forty, jinx_touches_release, boots_off_grating, kian_identify_sector
- Held Frame Push (4): debt_counter_pulse, jinx_rebreather_face, pov_abyss, pod_glass_detail
- Held Frame Static (2): data_streams_scan, counter_between_fingers

### Asset Naming Convention

All generated assets follow a standardized naming convention for traceability:

```
{PRJ}_EP{NNN}_S{NN}_T{NN}_{CHAR}[_{suffix}].{ext}
```

| Component | Description | Example |
|-----------|-------------|---------|
| `{PRJ}` | Asset code from ORCHESTRATION.md | `LEV` |
| `EP{NNN}` | 3-digit episode | `EP001` |
| `S{NN}` | 2-digit shot | `S10` |
| `T{NN}` | 2-digit take | `T01`, `T02` (retake) |
| `{CHAR}` | Primary character(s), alphabetical | `JINX`, `JINX-KIAN`, `ENV` |

**Suffixes:** `_f1` (first keyframe), `_f2` (mid/hero), `_f3` (last), `_strip` (triptych strip), `_f1_up` (upscaled), `_seg1.mp4` / `_seg2.mp4` (split FLF segments), `_flf.mp4` (standard FLF), `_push.mp4` (Ken Burns), `_full.mp4` (joined final).

**Utility:** `tools/asset_naming.py` — `build_asset_name()`, `asset_path()`, `next_take_number()`, `parse_asset_name()`. Reads project code from `## Asset Code` section in ORCHESTRATION.md.

### E-Style Hero Prompts & Triptych Strips

Triptych shots get two additional prompt types:

**Hero Frame (E-style prose):** ~150-180 word decisive moment description using active verbs, Arri Alexa Mini LF, Kodak Vision3 500T film stock. These are cinematic prose — the visual director's intent for the peak action moment.

**Triptych Prompt:** Full 3-panel strip prompt:
```
"A horizontal triptych of three vertical panels showing a continuous action sequence...
Left panel - ANTICIPATION: [setup verbs]
Center panel - PEAK ACTION: [decisive moment verbs]
Right panel - AFTERMATH: [result verbs]
All three panels: [shared camera/film/lighting DNA]"
```

Generated as a single 1536x912 image, then auto-split into 3 individual keyframes (512px each, with border crop).

### Motion Prompt Upgrades

All motion prompts (for video generation) use active-verb timing cues:
- Before: `"Rust particles drift slowly downward through still air."`
- After: `"Rust particles cascade downward 0-1s. Headlamp beam sweeps left-to-right 1-2s, catching particles in cone of light."`

**Per-episode shot breakdown:**
- 18-24 shots per 90-second episode (per CONSTANTS.md)
- Each shot mapped to a Kill Box beat (Hook, Setup, Escalation, Turn, Cliffhanger)
- Target ~5-6 seconds per shot (anything over 6s feels static in AI video)
- Shot types: ECU, CU, MCU, MS, LS, WIDE, POV, VFX
- Full first_frame and last_frame prompts with character visuals + lighting + cinematic modifiers
- Motion prompts with timing cues (for Kling/SeedDance/Veo video generation)
- Free-form description field for human directors (Claude fills structured fields via --edit)

### Tools

| Tool | Purpose | Status |
|------|---------|--------|
| Starsend Plan Pass (Stage 2) | Shot plans with 5 consumer groups from camera-tested episodes + Global Bible | Built |
| `generate_previs.py` | Previz generation via Flash 3.1 ($0.039/frame) | Built |
| `scene_planner.py route_shot` | Router-pipeline shot routing (Still/I2V/T2V/Multi-Shot) | Built |
| `preflight.py` | Pre-generation validation (ref sets, prompt format, model availability) | Built |
| `validate_storyboard.py` | Beat coverage, script coverage, hallucination detection | Built |
| `asset_naming.py` | Asset naming convention utility (build/parse/next-take) | Built |
| `generate_storyboard_keyframes.py` | Legacy keyframe generation (triptych + standard + held) — still in codebase | Built |
| Production Console (Storyboard tab) | Storyboard editing + shot review | Built |
| `storyboard_schema.json` | Canonical data contract (v3) | Built |

### Output
- `storyboard_ep_NNN.json` per episode (v3 schema with generation approach, asset names, triptych prompts)
- Validated shot breakdown with generation-ready prompts
- `storyboards/assets/ep_NNN/` — flat directory of named assets (keyframes, strips, upscaled, video)

### 4-Gate Validation Framework

After frames are generated, the Starsend validation framework runs 4 sequential gates:

**Gate 0 — Ref Set Consistency:**
Validates that all required reference images exist and are consistent before generation begins.
- Character hero + angle shots present
- Expression matrix complete (27 refs)
- Location refs exist for scene locations
- Ref images pass basic quality checks (resolution, aspect ratio, not blank)

**Gate 1 — Mechanical Artifact Detection (Image + Video):**
Checks each generated frame/clip for technical defects. Five dimensions scored 1-10:

| Dimension | What It Detects |
|-----------|-----------------|
| `face_quality` | Blur, distortion, asymmetry, uncanny valley, melted features |
| `hand_quality` | Wrong finger count, deformation, fused fingers |
| `body_proportion` | Wrong limb lengths, oversized head, anatomical errors |
| `artifacts` | Text/watermark, seam lines, tiling, color banding |
| `generation_quality` | Partial objects, impossible geometry, style transitions |

**Pass threshold:** ALL scores >= 6. Any score < 6 = hard reject → queue for regeneration.

**Gate 2 — Semantic Keyframe Check (Identity/Wardrobe/Composition):**
Sends the generated frame + character reference images to Gemini. Compares against shot plan and generation prompt. Six dimensions scored 1-10:

| Dimension | What It Evaluates |
|-----------|-------------------|
| `identity_match` | Does the character match the reference images? |
| `wardrobe_match` | Correct clothing, accessories, props? |
| `lighting_match` | Correct light source, color temperature, mood? |
| `emotion_match` | Expression/body language conveys intended emotion? |
| `composition_match` | Framing correct for shot type and camera angle? |
| `element_completeness` | All described elements present? |

**Thresholds:**
- ALL >= 8 → `auto_pass` (skip human review)
- ANY < 5 → `auto_reject` (queue for regeneration)
- Mixed 5-7 → `edge_case` (route to human review in Production Console)

**Gate 3 — Video Identity Drift Spot-Check:**
For video clips, samples 3-5 frames across the clip duration and checks for:
- Character identity drift (face/body changes mid-clip)
- Wardrobe teleportation (costume changes within shot)
- Background consistency (environment shifts)
- Motion coherence (physics violations, teleportation)

Hard reject if identity drift detected → re-route shot to different video engine or split into shorter segments.

### Gate
- Plan pass output valid (all required consumer groups populated)
- All 5 Kill Box beats covered
- Every script line assigned to at least one shot
- No hallucinated content in shot excerpts
- Shot distribution reasonable per beat duration
- 4-gate validation passes (0 unresolved auto_reject, edge cases reviewed by human)

---

## 6.5 Visual Editors & Editor Hub

**Status: ACTIVE -- Built**

The visual editors and the Editor Hub server provide browser-based tools for reviewing and editing production data across Phases 2.5-6.

### Production Console

The **Production Console** (`production_console.html`) is the unified visual pipeline interface, replacing `index.html` as the primary entry point. It combines all pipeline editors into a single tabbed app with shared state, cross-tab navigation, and Visual Grammar Bible integration.

```
serve.py on 127.0.0.1:8420
        ↓
production_console.html — tabbed workspace
        ↓
7 tabs: Revision | Grammar | Visual Bible | Breakdown | Storyboard | Shotlist | Dailies
        ↓
Select project → select episode → all tabs sync
```

**URL:** `http://127.0.0.1:8420/production_console.html`

**Tabs:**

| Tab | Phase | Purpose |
|-----|-------|---------|
| **Revision** | 2.5 | Script doctor annotations and revision workflow (embeds `revision_editor.html`) |
| **Grammar** | All | Visual Grammar Bible corpus targets, shot type distribution bars, Two-Peak timeline, deviation warnings when storyboard exists |
| **Visual Bible** | 4 | Visual design bible editor — camera/film stock, lens package, color palettes with pickers, characters, locations, lighting guides, quality guard. Saves directly to `visual_bible.md` and `project_config.json` via API. Project-level (no episode dependency). |
| **Breakdown** | 3 | Script breakdown assets — characters, locations, props, VFX (embeds `breakdown_editor.html`) |
| **Storyboard** | 4.5 | Shot-by-shot direction with edit/review toggle (embeds `storyboard_editor.html` + `storyboard_review.html`) |
| **Shotlist** | 5 | Shootable shotlist — shot cards with generation metadata + prompt preview (embeds `shotlist_editor.html`) |
| **Dailies** | 5-6 | Generated frame/video review — approve/retake per take (embeds `dailies_editor.html`) |

**Shared State:** Project selector, episode sidebar with pipeline status icons, cross-tab episode/shot selection, keyboard shortcuts (Cmd+1-7 for tabs, Up/Down for episodes).

**Architecture:** `modules/app.js` (state + events), `modules/api.js` (fetch wrappers), `modules/score.js` (Visual Grammar Bible visualization), `modules/visual_bible.js` (visual bible editor), `styles/console.css` (shared dark theme). Each tab module is in `modules/<tab>.js`.

### Editor Hub (Legacy)

The original `index.html` project card grid remains for simple editor linking. The Production Console supersedes it as the primary workflow tool.

### Server API

A local Python dev server (`serve.py`) on `127.0.0.1:8420` that serves all editors, the Production Console, and project data APIs.

| Route | Returns |
|-------|---------|
| `GET /` | Editor Hub landing page (index.html) |
| `GET /<file>.html` | Any editor from `editors/` |
| `GET /api/projects` | JSON manifest of all projects + available data |
| `GET /api/project/<name>/breakdown` | `visual/breakdown.json` for the project |
| `GET /api/project/<name>/storyboard/<file>` | Storyboard JSON from `storyboards/` |
| `GET /api/project/<name>/review/<file>` | Review JSON from `storyboards/reviews/` |
| `GET /api/project/<name>/dailies/<episode>` | Asset file manifest from `storyboards/assets/ep_NNN/` |
| `GET /api/project/<name>/corpus-summary` | Aggregated Visual Grammar Bible corpus stats as JSON (33 scenes, 1,955 shots) |
| `GET /api/project/<name>/score/<episode>` | Storyboard vs corpus grammar comparison with deviation report |
| `GET /api/project/<name>/pipeline-status` | Per-episode breakdown/storyboard/dailies/shot status |
| `GET /api/project/<name>/visual-bible` | `visual_bible.md` markdown + `project_config.json` as structured JSON |
| `POST /api/project/<name>/visual-bible` | Save visual bible markdown and project config updates |
| `GET /api/project/<name>/fountain/<file>` | Fountain file (URL-decoded, handles spaces/colons) |
| `GET /api/project/<name>/file/<path>` | Any file within the project directory (images, manifests, etc.) |
| `POST /api/project/<name>/review/<file>` | Save review JSON to `storyboards/reviews/` |
| `POST /api/project/<name>/preview-prompt` | Compile and preview a shot's resolved prompt (body: `{shot_id, episode, model, frame_type}`) — returns full prompt, layer breakdown, negative prompt, warnings, prompt hash |
| `POST /api/project/<name>/run-gate/<episode>` | Run `visual_gate.py batch` and return gate results JSON |

**Auto-load:** Each editor includes an IIFE snippet that reads `?project=` (and optionally `?file=`) from the URL query string. When served via the hub, editors auto-load project data on open — no manual file selection needed.

### Standalone Editors (Backward Compatible)

All standalone editors still work at their original URLs for direct access:

| Editor | Phase | Purpose |
|--------|-------|---------|
| `breakdown_editor.html` | 3 | Visual asset management |
| `references_editor.html` | 3-4 | Reference image management |
| `storyboard_editor.html` | 4.5 | Storyboard annotation |
| `storyboard_review.html` | 5-6 | Gate-aware frame review |
| `shotlist_editor.html` | 5 | Shotlist editor |
| `dailies_editor.html` | 5-6 | Asset review with takes |
| `revision_editor.html` | 2.5 | Script revision annotations |
| `lora_picker.html` | 3-4 | LoRA training candidate curation |
| `voice_casting.html` | 6+ | Voice casting editor with TTS preview (ElevenLabs) |

### Tools

| Tool | Purpose | Status |
|------|---------|--------|
| `serve.py` | Python stdlib HTTP server (127.0.0.1:8420) with project scanning and data APIs | Built |
| `production_console.html` | Unified tabbed pipeline interface (7 tabs, shared state, Visual Grammar Bible) | Built |
| `index.html` | Legacy Editor Hub landing page — project card grid | Built |
| `launch.sh` | Start server if not running, open Chrome (falls back to default browser) | Built |
| `voice_casting_server.py` | Voice casting backend — ElevenLabs API integration for TTS preview | Built |
| `fountain_reader.py` | Fountain script parser + TTS pipeline — ElevenLabs or Qwen3 TTS (ICL voice cloning, voice-direct analysis). Engines: elevenlabs, qwen3, qwen3_clone | Built |
| `/editors` skill | Launch the Editor Hub from Claude Code CLI | Built |

### Usage

```bash
# From CLI
bash editors/launch.sh

# From Claude Code
/editors              # Start server + open Chrome
/editors --stop       # Kill server on port 8420

# Direct URL — Production Console (recommended)
open http://127.0.0.1:8420/production_console.html

# Direct URL — Legacy hub
open http://127.0.0.1:8420
```

---

## 7. Phase 6: Visual Production

**Status: ACTIVE -- Starsend frontier model pipeline, Production Console review workflow**

> **Production findings:** See `docs/visual_production_findings.md` for the living document of all testing discoveries, confirmed decisions, bug fixes, and open production challenges. Read at the start of every visual production session.

### Input
- Plan pass output (from Phase 5: `plans/ep_NNN_plan.json`)
- Character/location/expression refs (from Phase 4)
- Model roles configuration (`recoil/pipeline/config/model_roles.json`)
- Asset naming convention (from `asset_naming.py` + ORCHESTRATION.md asset code)

### Sub-Phases

**a. Previz Generation**
- Engine: Flash 3.1 ($0.039/frame)
- Quick visual gut-check before committing to expensive keyframe generation
- One frame per shot, native 9:16 aspect ratio
- Output: `[project]/output/previz/ep_NNN/`

**b. Previz Review**
- Production Console → Previz tab
- Approve / reject / regenerate per frame
- Rejected shots get notes for prompt adjustment before keyframe generation
- Gate: All shots approved or flagged with specific issues before proceeding

**c. Keyframe Generation**
- Engine: NBP / Gemini 3 Pro Image ($0.134/frame)
- Production-quality frames with inline character refs (up to 11 per generation)
- Identity maintained via reference image ordering (recency bias: Scene → Pose → Expression → Identity → Prompt)
- 4K grid planning for native 9:16 output
- Output: `[project]/output/keyframes/ep_NNN/`

**d. Dailies Review**
- Production Console → Dailies tab
- Approve / reject / reroute / override per shot
- Reroute sends shot to different video engine
- Override allows manual replacement image
- Gate: All keyframes approved before video generation

**e. Video Generation (Router-Pipeline Architecture)**

The `scene_planner.py` router assigns each shot to the optimal video sub-pipeline based on shot characteristics:

| Sub-Pipeline | Engine | Use Case | Cost |
|-------------|--------|----------|------|
| Still | NBP (Gemini 3 Pro) | Keyframes, inserts, ENV shots | $0.134/img |
| I2V | Kling 3.0 | Start+end frame precision edits | $0.10/sec |
| T2V | SeedDance 2.0 / Kling 3.0 / Veo 3.1 | Character motion, dialogue | $0.013-0.10/sec |
| Multi-Shot | SeedDance 2.0 | Scene batching (3-8 shots) | $0.013/sec |

**Routing logic:**
- Static/held frames → Still (no video needed)
- Precision motion with specific start/end poses → I2V (Kling 3.0)
- Character dialogue and general motion → T2V (SeedDance 2.0 for cost, Kling 3.0 for quality)
- Complex camera moves, environment establishing → T2V (Veo 3.1)
- Multi-character conversation scenes → Multi-Shot (SeedDance 2.0 batch)

**f. Final Review + Export**
- Production Console → Board tab for season overview
- Per-episode assembly review
- Export to post-production pipeline

### Starsend Infrastructure

**Architecture:**

| Component | Purpose |
|-----------|---------|
| `recoil/pipeline/pipeline.py` | Main orchestrator — coordinates all generation stages |
| `recoil/pipeline/scene_planner.py` | Router-pipeline — assigns shots to optimal sub-pipeline |
| `recoil/pipeline/prompt_engine.py` | Prompt compilation with model-specific builders |
| `recoil/pipeline/config/model_roles.json` | **Centralized model registry** — all model IDs in one file. Update here when models expire. |
| `review_server.py` | Production Console backend (port 8430) |
| `production-console.html` | 3-tab review UI: Previz, Board, Dailies |

**API Services:**

| Service | Purpose | Cost | Status |
|---------|---------|------|--------|
| Google Gemini API (NBP) | Keyframe generation | $0.134/img | **ACTIVE** |
| Google Gemini API (Flash 3.1) | Previz generation | $0.039/img | **ACTIVE** |
| Kling 3.0 API | I2V video generation | $0.10/sec | **ACTIVE** |
| SeedDance 2.0 API | T2V + multi-shot video | $0.013/sec | **ACTIVE** |
| Veo 3.1 API | Complex camera + ENV video | $0.05/sec | **ACTIVE** |
| Google Gemini API | Script doctor + visual QC | Included | **ACTIVE** |

> **Centralized model registry:** All model IDs are centralized in `recoil/pipeline/config/model_roles.json`. When a model expires or is replaced, update one file — all pipeline components read from it.

### Tools

| Tool | Role | Status |
|------|------|--------|
| Gemini 3 Pro Image (NBP) | Keyframe generation ($0.134/img) | **ACTIVE** |
| Gemini Flash 3.1 Image | Previz + exploration ($0.039/img) | **ACTIVE** |
| Kling 3.0 | I2V video, precision edits ($0.10/sec) | **ACTIVE** |
| SeedDance 2.0 | Multi-shot + dialogue video ($0.013/sec) | **ACTIVE** |
| Veo 3.1 | Complex camera, ENV video ($0.05/sec) | **ACTIVE** |
| `recoil/pipeline/pipeline.py` | Orchestration, routing, QC | **Built** |
| `recoil/pipeline/scene_planner.py` | Shot routing (Still/I2V/T2V/Multi-Shot) | **Built** |
| Production Console (port 8430) | Review UI (Previz, Board, Dailies tabs) | **Built** |
| `prompt_engine.py` | Model-specific prompt compilation | **Built** |
| `asset_naming.py` | Naming convention utility | **Built** |
| `cost_tracker.py` | Project cost tracking | **Built** |

### Output
- `[project]/output/previz/ep_NNN/` — previz frames (Flash 3.1)
- `[project]/output/keyframes/ep_NNN/` — production keyframes (NBP)
- `[project]/output/video/ep_NNN/` — generated video clips
- Asset naming: `{PRJ}_EP{NNN}_S{NN}_T{NN}_{CHAR}[_{suffix}].{ext}`

### Gate
- 4-gate validation framework passes (see Phase 5)
- All keyframes approved in Production Console Dailies tab
- Video clips pass Gate 3 identity drift check
- Per-episode assembly reviewed in Board tab
- Regeneration pass complete for all flagged shots

---

## 8. Phase 7: Post-Production

**Status: PLANNED**

### Input
- Raw video clips from Phase 6 (~18 per episode)

### Process

**a. Upscaling**
- RealESRGAN (local) for resolution enhancement
- All final frames upscaled to delivery resolution

**b. Lip Sync / Dialogue Shots**
- **WAN 2.2 Animate Replace (PRIMARY):** Capture actor performing dialogue → Animate swaps with AI character, preserving lip sync natively. Identity from inline hero frame reference (no LoRA).
- **LivePortrait / MuseTalk (FALLBACK):** Audio-driven lip sync for non-captured shots
- Applied only to shots with character dialogue
- Input: video capture + hero frame reference (Animate) or still/video + audio track (LivePortrait)
- Output: Character mouth movements matched to spoken dialogue

**c. Compositing**
- AR/HUD overlay elements (the scripts specify `.AR OVERLAY` callouts for data displays, debt counters, health bars)
- Text overlays (planned for post compositing — frontier models cannot reliably render precise text)
- Eye effects (targeting reticles, glowing circuits -- per character visual language)
- Environmental VFX where needed

**d. Color Grading**
- Consistent visual palette per series
- Match lighting across shots within each episode
- Establish mood per Kill Box section (warm for setup, cold for escalation, etc.)

**e. Sound Design**
- Dialogue recording or AI voice generation
- Sound effects matched to action beats
- Music composition or licensing
- Ambient sound design per location

**f. Final Assembly**
- Import all clips into editing software
- Cut to Kill Box timing (90-second episodes)
- Sync audio
- Export final episode video

### Tools
- DaVinci Resolve or Final Cut Pro (human editor)
- RealESRGAN (local upscaling)
- WAN 2.2 Animate Replace (dialogue character swap — fal.ai or local)
- LivePortrait / MuseTalk (lip sync fallback)
- AI voice tools (TBD)

### Output
- Final episode video (90 seconds, vertical format 9:16)

### Gate (Planned)
- Timing matches Kill Box structure
- Character consistency maintained across all shots
- Audio synced
- No visible artifacts or compositing seams

---

## 9. Phase 8: Distribution

**Status: PLANNED**

### Input
- Final episode videos

### Process
- Platform upload (ReelShort, DramaBox, or proprietary platform)
- Metadata optimization (titles, thumbnails, descriptions)
- Episode scheduling (release cadence)
- Audience analytics monitoring
- Revenue tracking and optimization

### Output
- Revenue per episode / per series
- Audience retention data (where do viewers drop off?)
- Engagement metrics (what cliffhangers drive the highest unlock rates?)
- Data feedback to inform future series development

### Gate
- Episode 10 paywall conversion rate (the first 10 episodes are free; episode 10 must have maximum urgency cliffhanger)
- Series completion rate
- Revenue per viewer

---

## 10. IP Asset Inventory

| Asset | Description | Status | Investor Value |
|-------|-------------|--------|----------------|
| Narrative Engine | Custom AI orchestration system: 36 skills, 13 hooks, 72 Python tools, 21 agent protocols, 7 assessment lenses, format specification, constants management | Built and Active | Core differentiator. Not replicable by competitors without equivalent engineering investment. Handles story quality at scale -- the hardest problem in AI content. |
| Episode Scripts | 431+ validated episodes across 9 series, production-spec quality (450-500 words per CONSTANTS.md, validated dialogue %, pattern variety) | Built (7 complete series, 2 in progress) | Content library. Each script is a production-ready blueprint. At 60 episodes per series, this represents 7+ complete series ready for visual production. |
| Series Bibles | Character behavioral DNA, thematic spines, world-building documents, 60-episode arc structures with cliffhanger types and intensity scores | Built (per series) | Foundation IP. Defines creative universes. Transferable to other media (games, merchandise, licensing). |
| Character Reference Libraries | Hero images, angle shots, 27-expression matrices per character. Portable across any frontier model supporting inline refs. | Built | Owned IP. Each ref library generates unlimited consistent content across any model. Marginal cost near zero after initial $5-15/character. LoRA fallback preserved in archive. |
| Storyboard Pipeline | Script-to-visual conversion: Starsend Plan Pass (Stage 2), JSON schema, Production Console, `validate_storyboard.py`, router-pipeline | Built | Bridge IP. Connects narrative quality (hard) to visual production (fast). No competitor has a structured interface between AI narrative and AI visual production. |
| Visual Design System | Starsend casting pipeline, expression library, location/prop refs, visual_sync.py design lock | Built | Production design IP. Ensures visual consistency without per-frame human oversight. Systematic approach to identity persistence across 1000+ frames. |
| Production Pipeline | End-to-end automation from script to video (Starsend router-pipeline, 4-gate validation, Production Console) | Active | Process IP. Reduces per-episode production cost from thousands of dollars to tens of dollars. The efficiency moat. |
| Golden Record System | Reproducible generation parameter database -- every successful generation saved with exact prompt, seed, model, strength, steps | Built | Quality control IP. Ensures any winning generation can be exactly reproduced. Enables team scaling without quality loss. |
| Quality Gates | 13 automated Python validation hooks + 28 Python tools running at every stage (per-episode, per-batch, per-phase) | Built | Quality assurance at scale. Catches errors that manual review misses. Runs automatically -- no human reviewer needed for structural/mechanical compliance. |
| Claude Code Orchestration | CLAUDE.md system instructions, 25-skill architecture, 13-hook system, agent protocols, context management | Built | The "brain" that makes autonomous production possible. Skills, hooks, and agents coordinate to maintain quality across thousands of episodes without human supervision. Trade secret. |
| Starsend Engine | Project-agnostic visual production engine: pipeline orchestration, prompt compilation, shot routing, 4-gate QC, Production Console | Built | Portable production infrastructure. API-based — runs anywhere. Not locked to any single model provider. |
| Completed Videos | Final rendered episodes ready for distribution | Planned | Revenue-generating content. |
| Distribution Platform | Direct-to-audience delivery system | Planned | Audience ownership. Reduces dependence on third-party platform algorithms and revenue splits. |

---

## 11. Technology Stack

### Narrative Engine (Phases 1-2)

| Tool | Role | Status | Cost | License |
|------|------|--------|------|---------|
| Claude Code (Opus 4.6) | AI orchestration, episode generation, development | Active | Subscription | Anthropic |
| Python 3 | Validation scripts, metrics, state management | Active | Free | Open source |
| Markdown | Episode format, documentation, project files | Active | Free | N/A |
| Google Gemini 3 Pro | Series-level script doctor diagnostic (1M context) | Active | $100/mo credits (Ultra) | Commercial API |
| Fountain (via compile) | Screenplay export format | Active | Free | Open source |

### Script Breakdown (Phase 3)

| Tool | Role | Status | Cost | License |
|------|------|--------|------|---------|
| `/breakdown` skill | Full extraction + enrichment + validation | Built | Free | Proprietary |
| `script_breakdown.py` | Python extraction engine | Built | Free | Proprietary |
| `validate_breakdown.py` | Three-tier validation | Built | Free | Proprietary |
| `breakdown_editor.html` | Visual asset management | Built | Free | Proprietary |
| `breakdown_schema.json` | Canonical data contract | Built | Free | Proprietary |

### Visual Design (Phase 4)

| Tool | Role | Status | Cost | License |
|------|------|--------|------|---------|
| Starsend Casting Pipeline | Character hero → angles → expressions → lock | Built | Free | Proprietary |
| `prep_character_angles.py` | Generate angle shots from hero image | Built | API cost | Proprietary |
| `prep_expressions.py` | Generate 27-expression matrix per character | Built | API cost | Proprietary |
| `prep_location_refs.py` | Generate location moodboard refs | Built | API cost | Proprietary |
| `prep_prop_refs.py` | Generate prop reference shots | Built | API cost | Proprietary |
| `wash_mj_heroes.py` | Clean MidJourney artifacts from heroes | Built | Free | Proprietary |
| `visual_sync.py` | Design lock writeback (vision-based) | Built | Free | Proprietary |
| Production Console (Casting tab) | Visual casting workflow UI | Built | Free | Proprietary |
| Visual Bible template | Production design document template | Built | Free | Proprietary |

### Storyboard (Phase 5)

| Tool | Role | Status | Cost | License |
|------|------|--------|------|---------|
| Starsend Plan Pass (Stage 2) | Shot plans with 5 consumer groups | Built | Free | Proprietary |
| `generate_previs.py` | Previz generation via Flash 3.1 | Built | $0.039/frame | Proprietary |
| `scene_planner.py route_shot` | Router-pipeline shot routing | Built | Free | Proprietary |
| `preflight.py` | Pre-generation validation | Built | Free | Proprietary |
| 4-Gate Validation Framework | Ref consistency → artifacts → semantics → drift | Built | API cost | Proprietary |
| `validate_storyboard.py` | Storyboard verification | Built | Free | Proprietary |
| `asset_naming.py` | Asset naming convention utility | Built | Free | Proprietary |
| Production Console (Storyboard tab) | Shot editing + review UI | Built | Free | Proprietary |
| `storyboard_schema.json` | Canonical data contract (v3) | Built | Free | Proprietary |

### Visual Production (Phase 6)

| Tool | Role | Status | Cost | License |
|------|------|--------|------|---------|
| Gemini 3 Pro Image (NBP) | Keyframe generation | **Active** | $0.134/img | Commercial API |
| Gemini Flash 3.1 Image | Previz + exploration | **Active** | $0.039/img | Commercial API |
| Kling 3.0 | I2V video, precision edits | **Active** | $0.10/sec | Commercial API |
| SeedDance 2.0 | Multi-shot + dialogue video | **Active** | $0.013/sec | Commercial API |
| Veo 3.1 | Complex camera, ENV video | **Active** | $0.05/sec | Commercial API |
| Starsend Pipeline | Orchestration, routing, QC | **Active** | Free | Proprietary |
| Production Console (port 8430) | Review UI (Previz, Board, Dailies) | **Active** | Free | Proprietary |

**Retired:** Flux 2, Z-Image, fal.ai LoRA training, WAN 2.2, ComfyUI, RunPod A100 — replaced by frontier model API stack (Feb 27, 2026). LoRA pipeline preserved in `docs/archive/`.

### Post-Production (Phase 7)

| Tool | Role | Status | Cost | License |
|------|------|--------|------|---------|
| DaVinci Resolve / Final Cut Pro | Editing, assembly, color grading | Planned | Free (Resolve) / $300 (FCP) | Commercial |
| WAN 2.2 Animate Replace | Dialogue character swap (actor→AI) | Researched | ~$0.04-0.08/s (fal.ai) | Apache 2.0 |
| LivePortrait / MuseTalk | Lip sync fallback (audio-driven) | Planned | Free | Open source |
| AI Voice (TBD) | Dialogue generation | Planned | TBD | TBD |

### Hardware

| Device | Specs | Role | Status |
|--------|-------|------|--------|
| M4 MacBook Pro | 48GB RAM, 4TB SSD | Primary workstation: development, iteration | **ACTIVE** |
| M1 Ultra Mac Studio | 64GB RAM | Secondary workstation: batch processing, overnight renders, morning briefing | **ACTIVE** |

---

## 12. Cost Model

### Per-Episode Cost Breakdown (Estimated)

| Cost Category | Estimated Cost | Notes |
|---------------|---------------|-------|
| **Scripting** | ~$0 | Local Claude Code + narrative engine |
| **Previz** | ~$2.34 | ~60 shots × $0.039 (Flash 3.1) |
| **Keyframes** | ~$8.04 | ~60 shots × $0.134 (NBP) |
| **QC** | ~$0.34 | 4-gate validation framework |
| **Video** | ~$13 | Mix of Kling ($0.10/sec), SeedDance ($0.013/sec), Veo ($0.05/sec) |
| **Post-Production** | $20-100 | Human editor time — the primary remaining cost |
| **Total per episode** | **~$44-124** | |
| **Full season (60 ep)** | **~$1,400-1,800** | API costs only |

### Comparison to Traditional Production

| Production Method | Cost Per Minute of Content | Cost Per Episode (~1.5 min) |
|------|------|------|
| Traditional live-action (low budget) | $5,000-15,000 | $7,500-22,500 |
| Traditional live-action (mid budget) | $15,000-50,000 | $22,500-75,000 |
| Existing AI-assisted (API-dependent) | $500-2,000 | $750-3,000 |
| **Recoil pipeline (at scale)** | **$30-83** | **$44-124** |

**Cost reduction: 60-500x vs. traditional production.**

The key insight: the narrative engine (Phases 1-2) costs effectively $0 per episode because it runs on local infrastructure with a subscription model. Visual production (Phase 6) uses frontier model APIs — cheaper than local GPU infrastructure (no RunPod rental, no LoRA training), with better quality. The primary remaining cost is human editorial judgment in post-production.

### Marginal Cost Curve

| Volume | Marginal Cost Trend |
|--------|-------------------|
| First episode | Highest (ref generation, workflow development, learning) |
| Episodes 2-10 | Rapidly decreasing (refs amortized, workflows proven) |
| Episodes 11-60 | Near floor (repeating proven workflow, minimal new refs) |
| Second series | Lower floor (engine and pipeline reusable, only new character refs needed) |
| Series 3-10+ | Approaching asymptote (process fully optimized) |

---

## 13. What's Built vs. What's Planned

| Component | Phase | Status | Completion |
|-----------|-------|--------|------------|
| 34-point development checklist | 1 | Built | 100% |
| Development agent system (5 specialist agents) | 1 | Built | 100% |
| Validation gates (behavioral DNA, arc, comprehensive) | 1 | Built | 100% |
| Promotion pipeline (dev-to-scripting transformation) | 1 | Built | 100% |
| Treatment generation and validation | 2 | Built | 100% |
| Orchestrated episode generation (3 modes) | 2 | Built | 100% |
| Per-episode metrics validation | 2 | Built | 100% |
| Per-batch checkpoint validation | 2 | Built | 100% |
| Voice contamination detection | 2 | Built | 100% |
| Assessment lenses (7 lenses) | 2 | Built | 100% |
| Episode rewrite tooling | 2 | Built | 100% |
| Thread tracking and retrofitting | 2 | Built | 100% |
| Fountain compilation | 2 | Built | 100% |
| Script doctor diagnostic (Gemini integration) | 2.5 | Built | 100% |
| Script doctor annotation extraction | 2.5 | Built | 100% |
| Script doctor deep fix (structural P1s) | 2.5 | Built | 100% |
| Script doctor verification pass | 2.5 | Built | 100% |
| Script doctor manual workflow (dry-run + parse-response) | 2.5 | Built | 100% |
| Script breakdown extraction engine | 3 | Built | 100% |
| Breakdown validation script | 3 | Built | 100% |
| Breakdown Editor (HTML tool) | 3 | Built | 100% |
| Breakdown JSON schema | 3 | Built | 100% |
| Visual Bible template | 4 | Built | 100% |
| Starsend Casting Pipeline | 4 | Built | 100% |
| Expression Library Generation (27 refs/char) | 4 | Built | 100% |
| Location Reference Generation | 4 | Built | 100% |
| Prop Reference Generation | 4 | Built | 100% |
| Habitat zone consolidation | 4 | Built | 100% |
| Design Lock Writeback (visual_sync.py) | 4 | Built | 100% |
| LoRA training pipeline (fal.ai) | 4 | Archived | — |
| Starsend Plan Pass (Stage 2) | 5 | Built | 100% |
| Storyboard JSON schema (v3) | 5 | Built | 100% |
| Storyboard validation script | 5 | Built | 100% |
| Generation approach classification (4 types) | 5 | Built | 100% |
| Asset naming convention + utility | 5 | Built | 100% |
| 4-Gate Validation Framework | 5-6 | Built | 100% |
| Pre-Production Console (port 8420) | 3-5 | Built | 100% |
| Production Console (port 8430) | 5-6 | Built | 90% |
| /editors skill | 3-5 | Built | 100% |
| Revision Editor (HTML tool) | 2.5 | Built | 100% |
| Previz pipeline (Flash 3.1) | 6 | Built | 100% |
| Keyframe generation (NBP) | 6 | Built | 100% |
| Video routing (router-pipeline) | 6 | Built | 80% |
| Kling 3.0 I2V integration | 6 | Active | 90% |
| SeedDance 2.0 T2V + multi-shot | 6 | Active | 80% |
| Veo 3.1 integration | 6 | Active | 70% |
| Upscaling pipeline | 7 | Available | 20% |
| Lip sync integration | 7 | Planned | 0% |
| Compositing workflow | 7 | Planned | 0% |
| Sound design pipeline | 7 | Planned | 0% |
| Final assembly workflow | 7 | Planned | 0% |
| Distribution platform | 8 | Planned | 0% |

### Phase Completion Summary

| Phase | Name | Estimated Completion |
|-------|------|---------------------|
| Phase 1 | Development | 100% |
| Phase 2 | Scripting | 100% |
| Phase 3 | Script Breakdown | 100% |
| Phase 4 | Visual Design | 90% |
| Phase 5 | Storyboard | 95% |
| Phase 6 | Visual Production | 80% |
| Phase 7 | Post-Production | 5% |
| Phase 8 | Distribution | 0% |

---

## 14. Competitive Moat

### 1. Narrative Quality at Scale -- The Hardest Problem

Competitors can generate images. They can generate video. What they cannot do is generate **compelling 60-episode narrative arcs** with:
- Character consistency (behavioral DNA, not just appearance)
- Earned emotional beats (11 required beats at specific episodes)
- Pattern variety enforcement (no 4+ consecutive same hook or cliffhanger type)
- Thread continuity across 60 episodes (plants, advances, payoffs)
- Voice contamination prevention (characters don't blend into each other over time)

The narrative engine has 36 skills, 13 hooks, 72 Python tools, 21 agent protocols, and 7 assessment lenses. It was built through 7+ complete series of iteration. This is not a prompt template -- it is an engineering system.

**Why this matters:** AI-generated content has a "slop" problem. Most AI video content looks impressive for 10 seconds and becomes unwatchable after a minute. The narrative engine ensures that every episode in a 60-episode series has earned its dramatic moments, maintained character voice, and built on what came before. Story quality is what separates content people pay for from content people scroll past.

### 2. Owned Digital Actors

Character identity is maintained via high-quality reference image sets and a universal expression matrix (27 refs per character: 9 emotions × 3 intensities). These reference libraries are:
- **Portable**: Work with any frontier model that supports inline reference images
- **Owned IP**: Stored locally, not dependent on any single API provider
- **Continuously improvable**: New angles, expressions, or wardrobe variants can be added at any time
- **Marginal cost near zero**: Once the ref set is built (~$5-15/character), every subsequent generation uses it for free

This is the difference between renting actors and owning them. Traditional studios must re-negotiate with talent for every season. Our characters cost $5-15 to create and nothing to reuse.

> **LoRA-based identity ownership remains a viable option.** If frontier model APIs become prohibitively expensive or restrictive, the full LoRA training pipeline (`train_lora.py`, `batch_threepass.py`) is preserved in the codebase and archived documentation (`docs/archive/lora_training_best_practices.md`). LoRA `.safetensors` files are version-locked and platform-independent — a character trained once looks identical forever.

### 3. The Translation Bridge

No competitor has a structured interface between AI narrative quality and AI visual production. The typical approach is:
1. Write something (maybe with AI, maybe not)
2. Generate images (hoping they match)
3. Hope it works

Our approach:
1. Narrative engine generates validated, production-spec scripts
2. Translation bridge converts scripts into precise shot packets with prompts, aspect ratios, model routing, and reference assignments
3. Visual pipeline executes shot packets deterministically

The bridge is what makes the pipeline a **pipeline** rather than a series of disconnected experiments.

### 4. Quality Gates Prevent Slop

13 automated validation hooks run at every stage:
- Per-episode: word count, dialogue %, exchange count, format compliance
- Per-batch: pattern variety, emotional beats, continuity, meta-reference detection
- Per-phase: behavioral DNA validation, arc validation, treatment validation

These gates are automated Python scripts that run without human intervention. They catch errors that manual review misses and enforce standards consistently across hundreds of episodes. A human reviewer gets tired. The gates do not.

### 5. Full-Stack Ownership from Story to Screen

Most AI content companies own one piece of the pipeline:
- Some own generation tools but have no story engine
- Some have AI writing but no visual production
- Some have distribution but depend on third-party content

Recoil is building ownership across the entire chain: story development, scripting, translation, visual production, post-production, and distribution. This means:
- No single vendor can disrupt operations
- Margin capture at every stage
- Data flows from audience back to development (what cliffhangers convert best?)
- IP accumulates at every phase (scripts, character ref libraries, workflows, audience data)

### 6. The Content Flywheel

Each series produced:
- Generates revenue (distribution)
- Trains the narrative engine (what works, what doesn't)
- Creates reusable production assets (ref libraries, workflows, expression matrices)
- Builds audience data (what demographics engage, what cliffhangers convert)
- Informs the next series (faster development, better calibration)

Series 1 is the most expensive. Every subsequent series is cheaper, faster, and informed by data from the previous ones. This is a flywheel, not a linear cost.

---

## 15. Quality Assurance Architecture

The pipeline enforces quality through three tiers of automated validation. Every piece of content passes through multiple gates before reaching the next phase.

### Tier 1: Per-Episode Validation

Every episode is validated immediately after generation:

| Check | What It Catches |
|-------|----------------|
| Word count enforcement | Over/under target (hard reject) |
| Dialogue percentage | Excessive talking-head episodes |
| Exchange count | Runaway conversations that break pacing |
| Format compliance | Missing structural elements |
| Meta-reference detection | Characters referencing episode numbers or story structure |

Episodes that fail validation are rewritten and re-validated before the batch can proceed. No exceptions.

### Tier 2: Per-Batch Validation (Checkpoint Gates)

After every 5 episodes, a checkpoint gate runs:

| Check | What It Catches |
|-------|----------------|
| Pattern variety | 4+ consecutive same hook or cliffhanger **subtype** (main-category runs are soft flags) |
| Emotional beat schedule | Required beats missed or placed incorrectly |
| Continuity verification | Thread plants without payoffs, dangling references |
| Voice contamination | Characters blurring into same speech patterns |
| Hook/cliffhanger distribution | Series-wide ratios drifting from targets |

If a checkpoint fails, the batch is flagged and episodes are revised before continuing. The checkpoint records a snapshot of series state for recovery.

### Tier 3: Phase-Level Validation

Structural gates at major phase transitions:

| Gate | Transition | What It Validates |
|------|-----------|-------------------|
| 34-point checklist | Development → Promotion | All dramatic infrastructure exists |
| Behavioral DNA validation | Development → Promotion | Characters have filmable behaviors, not backstory |
| Arc validation | Development → Promotion | 60 episodes structurally sound |
| Pre-treatment gate | Promotion → Treatment | All promotion outputs present |
| Treatment validation | Treatment → Generation | Treatment covers all 60 episodes with required elements |
| Breakdown validation | Breakdown → Visual Design | All episodes processed, all characters present, wardrobe covered |
| Storyboard validation | Storyboard → Production | All shots have valid prompts, all script lines covered |

### Assessment Lenses

Seven specialized evaluation lenses can be run against any set of episodes:

| Lens | What It Evaluates |
|------|-------------------|
| Behavioral DNA | Do characters act according to their defined behaviors? |
| Voice | Are speech patterns distinct and consistent? |
| Texture | Does prose feel specific rather than generic? |
| Relationship Earning | Are emotional declarations earned through action? |
| Visual Richness | Can every line be filmed? |
| Continuity | Do references across episodes track correctly? |
| Double-View Continuity | Does rewatch reveal planted details? |

Each lens produces a scored report with specific findings and episode-level recommendations.

### Validation Statistics

| Metric | Count |
|--------|-------|
| Automated validation hooks | 13 |
| Python tools | 32 |
| Assessment lenses | 7 |
| Agent protocols | 21 |
| Development checklist items | 34 |
| Required emotional beats per series | 11 |
| Max consecutive same pattern | 3 |

Every number above is enforced by code, not by human discipline. The system catches errors that manual review misses and enforces standards consistently across hundreds of episodes.

---

## 15.5 Dual-Engine Architecture & Cross-Repo Bridge

The production pipeline spans two engines:

| Engine | Repo | Purpose | Phases |
|--------|------|---------|--------|
| **Recoil** | `/recoil/` | Narrative engine — scripting, validation, script doctor | 1-2.5 |
| **Visual Pipeline** | `recoil/pipeline/` | Visual production — previz, keyframes, video, review (formerly sibling `/starsend/`, absorbed 2026-03-30) | 3-6 |

### Cross-Repo Bridge

Recoil's `lib/model_registry.py` provides `get_model(role, category)` for model selection within the narrative engine. The visual pipeline's `lib/model_profiles.py` (at `recoil/pipeline/lib/model_profiles.py`) provides the equivalent for visual production. Both read from centralized model configurations (`recoil/pipeline/config/model_roles.json`).

The bridge point is the **breakdown**: Recoil's `/breakdown` command produces `breakdown.json` + `global_bible.json`, which Starsend's 3-stage pipeline (Camera Test → Global Bible → Plan Pass) consumes and enriches.

### Architecture Consultation (`/consult`)

The `/consult` skill runs multi-round architecture consultations via Gemini 3.1 Pro or Claude Opus 4.6. It packages project context (codebase, engine check results, audit commits) and structures a back-and-forth dialogue:

1. **Round 1 (Gemini):** Comprehensive audit — model consistency, dead imports, circular deps, pipeline handoff gaps
2. **Round 2 (Claude):** Review findings, verify/dispute, add context
3. **Round 3 (Gemini):** Deep dive on disputed items + new issues
4. **Round 4 (Claude):** Final synthesis, actionable fix list

Use after major engine changes, audits, or model migrations.

### Engine Health Checks

| Engine | Command | Checks | Categories |
|--------|---------|--------|------------|
| Recoil | `python3 tools/engine_check.py .` | 53 | 8 (structural, semantic, deep logic, GUI, visual pipeline, dead code, docs, security) |
| Visual Pipeline | `python3 recoil/pipeline/tools/recoil_check.py recoil/pipeline/` | 30 | 6 |

---

## 16. Emotional Beat Schedule

11 required emotional beats are mapped to specific episodes across the 60-episode arc. Missing beats are hard failures in arc validation.

> **Source of truth:** `/CONSTANTS.md` → Emotional Beat Schedule

| Episode | Beat Name | Description | Tolerance |
|---------|-----------|-------------|-----------|
| 10 | FIRST_CRACK | First vulnerability shown, relationship shifts from transaction | ±2 eps |
| 15 | THRESHOLD | Point of no return — protagonist crosses threshold | ±2 eps |
| 20 | DEEPENING | Investment despite themselves | ±2 eps |
| 26 | VULNERABILITY | First expressed care (verbalized, even awkwardly) | ±2 eps |
| 30 | MIDPOINT | World/self fundamentally different | ±2 eps |
| 32-33 | FRACTURE | Identity crisis — core belief challenged | ±2 eps |
| 36 | BETRAYAL_DOUBT | Trust tested or masks down | ±2 eps |
| 42 | COST | Loyalty test — choose relationship over goal | ±2 eps |
| 45 | ALL_IS_LOST | Lowest point, relationship threatened | ±2 eps |
| 50 | RECONCILIATION | Connection survives crisis | ±2 eps |
| 59-60 | RESOLUTION | Primary ache resolved (catharsis) | ±2 eps |

---

## 17. Command Reference

All 36 skills available in the microdrama pipeline:

| Command | Purpose | Phase |
|---------|---------|-------|
| `/load-context [project] [mode]` | Load essential context for session | All |
| `/develop [project]` | Interactive development through 34-point checklist | Development |
| `/showrunner [project]` | Agent-driven development with specialist sub-agents | Development |
| `/validate [project]` | Comprehensive pre-promotion validation | Development |
| `/promote [project]` | Transform development project into production scripting folder | Development → Scripting |
| `/treatment [project]` | Generate prose treatment from episode arc | Scripting |
| `/generate-script [project]` | Manual generation with user-controlled compaction | Scripting |
| `/generate-script-orchestrated [project]` | Production-grade generation with fresh sub-agents | Scripting |
| `/autogenerate-scripts [project]` | Fully autonomous generation (never stops) | Scripting |
| `/batch` | Internal skill for batch sub-agents (5 episodes per batch) | Scripting |
| `/assess [project] --lens [lens]` | Post-generation quality assessment through lenses | Scripting |
| `/dramatic-qc [project]` | Evaluate dramatic quality (voice, texture, earning) | Scripting |
| `/rewrite [project] ep [N] "[issue]"` | Targeted rewrite of specific episodes | Scripting |
| `/thread [project] "[name]" --episodes [N,N,N]` | Retrofit narrative threads across episodes | Scripting |
| `/script-doctor [project]` | Multi-pass diagnostic via Gemini (transitions + 6 dimensions, annotation-ready) | Scripting (Post-Generation) |
| `/revise [project] [annotations.json]` | Batch-apply annotations from script doctor or revision editor | Scripting (Revision) |
| `/novella [project] ep [N-M]` | Convert episodes to novella-format prose | Scripting |
| `/compile [project]` | Merge episodes into Fountain screenplay format | Scripting |
| `/breakdown [project] [ep N-M]` | Extract visual assets from scripts | Script Breakdown |
| `/visual-design [project]` | Create visual bible (lens package, HEX palettes) | Visual Design |
| `/storyboard [project] ep [N]` | Generate storyboard JSON per episode | Storyboard |
| `/imagine [description]` | Generate image with Flux 2 Klein via ComfyUI | Visual Production |
| `/golden-record [image]` | Save winning ComfyUI generation parameters | Visual Production |
| `/editors` | Launch Editor Hub — local dev server + browser landing page | Visual Editors |
| `/engine-check [--quick\|--full\|--fix\|--section X]` | 53-check engine audit (8 categories: structural, semantic, deep logic, GUI, visual pipeline, dead code, docs, security) | Maintenance |
| `/validate-docs` | Check doc consistency against CONSTANTS.md | Maintenance |
| `/update-guides` | Sync guides with engine changes | Maintenance |

---

## 18. Pre-Treatment Validation Gate

After promotion and before treatment generation, the pre-treatment validation gate verifies all promotion outputs are present and valid:

```bash
python3 .claude/hooks/validate_pre_treatment.py ./[project]
```

**What it checks:**

| Check | Requirement |
|-------|-------------|
| Series bible | `bible/series_bible.md` exists with content |
| Characters | `bible/characters.md` exists and passes format check |
| Episode arc | `bible/episode_arc.md` exists with 60 episodes |
| State | `state/current_state.json` initialized |
| Orchestration | `ORCHESTRATION.md` exists |

**Exit codes:** 0 = PASS (proceed to treatment), 1 = FAIL (fix promotion outputs first)

This gate prevents treatment generation from running against incomplete or malformed promotion outputs. It is a hard gate — treatment cannot proceed until it passes.

---

## Appendix: Glossary

| Term | Definition |
|------|------------|
| **Kill Box** | The 90-second, 5-section episode structure (Hook, Setup, Escalation, Turn, Cliffhanger) |
| **Behavioral DNA** | Filmable on-screen behaviors that define a character -- what they DO, not their backstory |
| **LoRA** | Low-Rank Adaptation -- a small file (.safetensors) that encodes a character's visual identity into a base model's weights. **Retired Feb 2026** — replaced by frontier model inline reference strategy. Pipeline preserved in `docs/archive/`. |
| **Sandwich Workflow** | Two-anchor video interpolation: start frame + end frame, video model fills the middle. Now driven by I2V (Kling 3.0) with inline references instead of LoRA-generated anchors. |
| **Golden Record** | Database of every successful generation with exact parameters for reproducibility |
| **Shot Packet** | Per-shot production document with prompt, aspect ratio, model assignment, reference images, and production notes |
| **Robin Hood Protocol** | (Legacy) Shot routing strategy from LoRA era. Replaced by router-pipeline architecture in `scene_planner.py` which routes all shots through frontier model APIs. |
| **Treatment** | The 3,000-4,000 word prose document that serves as the master input for episode generation |
| **THE MOMENT** | The single most important image or line in an episode -- the north star for generation |
| **Voice Contamination** | When character speech patterns blur together over many episodes, losing distinctiveness |
| **Pattern Variety** | The rule that prevents more than 3 consecutive episodes from using the same hook or cliffhanger **subtype** (e.g., M-PT, S-VP). Different subtypes within the same main category do NOT count as consecutive; main-category runs are informational soft flags only |
| **Emotional Beat Schedule** | 11 required emotional milestones mapped to specific episodes across the 60-episode arc |
| **Archetype-Worldview** | How the protagonist perceives and decodes reality (Technopath, Tactician, High-Roller, Survivor, etc.) |
| **Primary Ache** | The relationship outcome the audience desperately wants to see happen -- satisfied no earlier than Episode 59-60 |
| **Visual Bible** | Production design document specifying character designs, wardrobe, props, locations, color palette (HEX), VFX, and lighting guides for image generation |
| **Storyboard JSON** | Per-episode structured shot breakdown consumed by the Storyboard Editor and generation scripts |
| **Storyboard Editor** | HTML two-panel visual editor for reviewing and modifying storyboard shot breakdowns |
| **Inline Reference Images** | Reference images passed to frontier models (NBP, Flash) for identity persistence: character refs (hero, angles, expressions), wardrobe/props, environment/location refs. Replaces the retired Flux 2 reference slot system. |
| **Script Doctor** | Multi-pass series-level diagnostic tool that reads all 60 episodes in a single Gemini context window. Pass 1: structural transitions — both inter-episode (cliffhanger→hook) and intra-episode (Kill Box sections). Pass 2: 6 series-level dimensions. Close read uses mandatory two-pass protocol (same as treatment): first pass catches obvious gaps, second pass catches fix-introduced issues, obscured problems, and reverse-direction gaps plus Kill Box segment transitions. Not done until two consecutive passes find zero issues. Finds systemic issues invisible at the batch level |
| **Transition Logic (THEREFORE/BUT)** | The rule that every transition — both between episodes (cliffhanger→hook) and within episodes (Kill Box section boundaries) — must connect via THEREFORE (causal) or BUT (complication), never AND THEN (chronological). Enforced by Script Doctor Pass 1, which produces T-prefixed (inter) and I-prefixed (intra) findings |
| **Deep Fix** | Creative structural fix for P1 FLAG findings — produces bridge scene drafts and rewrite guidance rather than simple text substitution |
| **Annotation (Script Doctor)** | A specific location in an episode with an action type (REWRITE, DELETE, FLAG) and fix guidance, extracted from the diagnostic brief for `/revise` consumption |
| **Vitality Frame** | The script doctor's quality bar: scripts must feel alive, engaging, fun, and surprising — not just technically correct |
| **Latent Panel Anchoring** | Technique that reuses a shared reference latent across all shots to mathematically anchor character identity |
| **Editor Hub** | Local Python dev server (127.0.0.1:8420) + landing page that serves all visual editors with project data auto-loaded via API. Launched with `/editors` or `launch.sh`. |
| **Revision Editor** | HTML tool (`revision_editor.html`) for loading Fountain screenplays, viewing and editing revision annotations, and exporting revised scripts |
| **Visual Gate** | Two-gate automated QC pipeline (`visual_gate.py`) for AI-generated keyframes. Gate 1 detects artifacts (face blur, hand deformation, body proportion errors). Gate 2 checks semantic alignment (identity match, wardrobe, lighting, emotion, composition). Routes each frame to auto_pass, auto_reject, or edge_case (human review). |
| **Storyboard Review** | HTML tool (`storyboard_review.html`) for gate-aware frame review — auto-loads gate scores, pre-fills statuses and issue tags, filters edge cases, supports human override of auto-decisions |
| **Reference Workshop** | HTML tool (`references_editor.html`) for managing reference images — edit prompts, browse/replace generated refs, lock per variant, export as ZIP |
| **Dailies Editor** | HTML tool (`dailies_editor.html`) for reviewing generated assets per shot — timeline panel, shot cards, asset gallery with thumbnails, take selector, approve/retake workflow, keyboard shortcuts (A=approve, R=retake, arrows=navigate) |
| **Asset Naming Convention** | Standardized filename format `{PRJ}_EP{NNN}_S{NN}_T{NN}_{CHAR}[_{suffix}].{ext}` for all generated visual assets. Project code from ORCHESTRATION.md `## Asset Code` section. Utility: `asset_naming.py` |
| **Generation Approach** | Per-shot classification in storyboard v3 schema: `triptych_split_flf` (3-panel strip → split FLF), `standard_flf` (first+last → FLF), `held_frame_push` (Ken Burns), `held_frame_static` (no motion) |
| **Triptych Strip** | A single 1536x912 image containing 3 vertical panels (anticipation/peak/aftermath) generated as one coherent composition, then auto-split into individual keyframes. Used for climactic action moments. |
| **Split FLF** | Two-segment First-Last Frame video generation: segment 1 (f1→f2) + segment 2 (f2→f3), concatenated to final. Used with triptych shots for complex action arcs. |
| **E-Style Prompt** | ~150-180 word cinematic prose describing a decisive moment with active verbs, Arri Alexa Mini LF camera, Kodak Vision3 500T film stock. Used as `hero_frame` in triptych shots. |
| **Frontier Model API Strategy** | Use frontier model APIs (Gemini NBP, Kling, SeedDance, Veo) for all visual production. No local GPU dependency. Identity via inline reference images, not LoRA training. Model IDs centralized in `recoil/pipeline/config/model_roles.json`. |

---

*Document: PRODUCTION_PIPELINE_GUIDE.md*
*Created: 2026-01-29 | Updated: 2026-03-03 (Post-audit cleanup: inventory counts, dual-engine architecture section, glossary modernization, stale reference fixes.)*
*Companion: PRODUCTION_PIPELINE_GUIDE.html (interactive visualization)*
*Source of truth for numeric values: `/CONSTANTS.md`*
*Source of truth for workflow specification: `/WORKFLOW_SPEC.md`*
*Source of truth for video pipeline strategy: `RECOIL_VIDEO_PIPELINE_STRATEGY.md`*