# DramaFoundry — Operator & Agent Guide

> End-to-end manual for producing multi-episode vertical drama series from novels and screenplays.
> Web Portal: https://dramafoundry.fornace.net
> Source Repo: https://github.com/ffrappo/dramafoundry
> Gateway Repo: https://github.com/ffrappo/dramafoundry-gateway
> Machine-Readable Raw: https://onboarding.fornace.app/dramafoundry.md

---

## 1. Quick Access & Credentials

DramaFoundry runs as a unified production service for the Fornace team.

- **Hosted URL**: `https://dramafoundry.fornace.net`
- **Model Gateway**: `dramafoundry-gateway` on port `8781` reverse-proxied to Mantice / Fal.ai.
- **Teammate Authentication**:
  - Automatically provisioned during `setup.sh` or inside Pi via `/fornace install` and `/fornace update`.
  - Credentials stored at: `~/.pi/agent/credentials/dramafoundry.json` (mode `600`).
  - Contains your personal bearer token (`dfa_...`), username, and gateway endpoint.

---

## 2. Architecture & Capabilities

DramaFoundry uses a single-machine hexagonal architecture (FastAPI engine + local SQLite store + in-process task scheduler). It requires **no external PostgreSQL or Redis cluster**.

```
Browser UI (React :8080) / Pi Agent (MCP)
           │
           ▼
FastAPI Engine (:8780)
   ├── Ingest & Script Decomposition (Cognee story graph)
   ├── Director Planning & Visual Identity Engine
   ├── In-process Task Scheduler & EventSource Stream
   └── Local SQLite Store (state/<user>/<project>/data.db)
           │
           ▼
dramafoundry-gateway (:8781)
   ├── MiniMax H3 Max Turbo (Lip-synced character speech)
   ├── Wan 2.1 / Wan 2.7 (Approved scene transitions & edits)
   ├── Kling 3.0 (Multi-shot dramatic action)
   ├── Fal.ai (FLUX / Ideogram identity turnarounds)
   └── AuK / Fish Audio / ThinkSound (Local Metal audio beds)
```

---

## 3. The 6-Stage Production Pipeline

### Stage 1: Manuscript Ingestion & Script Breakdown
Upload raw text, markdown, or screenplay files.
- The **story graph** extracts characters, relationships, and temporal chronology.
- The **script writer agent** breaks the chapter into episodic narrative arcs and discrete dramatic beats (typically 12–25 beats per 60–90 second episode).
- Each beat receives dialogue, speaker tags, camera framing, and action descriptions.

### Stage 2: Character Identity & Visual Bible
Maintains visual character consistency across all shots:
- Generates character turnaround sheets (front, 45°, profile) using FLUX / Ideogram.
- Creates location reference images (day, night, interior, exterior) used as visual anchors.
- Assigns persistent visual tokens and wardrobe descriptors per character.

### Stage 3: Beat Keyframing & Composition Grids
- Decomposes each beat into candidate visual sketches.
- Generates 2x2 or 3x3 candidate grid pools.
- Uses automated visual quality detection to select optimal composition framing.

### Stage 4: Per-Beat Video Generation
- Selected keyframes are rendered into motion clips using approved models.
- **MiniMax H3 Max Turbo**: Used for dialogue shots where lip-sync and character acting must match the script.
- **Wan 2.7 / Wan 3.0**: Used for complex environmental motion, beauty shots, and facial nuance.
- **Kling 3.0**: Used for high-action choreography and dynamic camera tracking.

### Stage 5: Voice Acting & Local Sound Design
- **Dialogue Voiceover**: Synthesized via AuK (Apple Silicon native 8-bit) or Fish Audio, matching the character voice profile.
- **Audio Sync Rule**: The generated mouth movement and audio timing must align exactly.
- **Ambient Beds & Foley**: Background foley and room tone generated locally via `thinksound-native` (Metal 4), mixed under voice at **-33 LUFS**.

### Stage 6: Assembly, Dynamic Captions & Delivery
- **Subtitle Overlay**: Dynamic word-highlighted vertical subtitles burned via Remotion with precise ASR word timestamps.
- **Conform**: Lossless FFmpeg remuxing on the native vertical 9:16 frame grid.
- **Checkpoint Resumption**: Every beat's video, audio, and metadata are saved independently. If a single beat needs re-rendering, only that beat is rerun; completed beats remain untouched.

---

## 4. Working with DramaFoundry from Pi Coding Agent

The `dramafoundry` Pi skill (`~/.pi/agent/skills/dramafoundry`) connects Pi directly to the production backend.

### Prerequisites in Environment
- `FORNACE_GATEWAY_URL`: `https://dramafoundry.fornace.net` (or local `http://127.0.0.1:8780`)
- `FORNACE_PROJECT_ID`: The active project identifier
- `FORNACE_AGENT_TOKEN`: Your bearer token from `~/.pi/agent/credentials/dramafoundry.json`

### Grounding Rules for Agents
1. **Never guess API endpoints or file paths**: Always inspect `GET /api/v1/projects/${FORNACE_PROJECT_ID}/pipeline/status` to determine the authoritative `next_step`.
2. **Never hallucinate URLs**: Only return the relative `*_url` fields (`sketch_url`, `video_url`, `audio_url`) provided by the API response.
3. **Single Write Step per Turn**: Never trigger multiple heavy render steps in a single turn without waiting for the task queue.
4. **No Traditional VFX**: Never attempt to fix frames using OpenCV or PIL filter chains. Route all visual modifications back through approved generative models.

---

## 5. Self-Hosting & Local Development

To run the full DramaFoundry stack locally on an Apple Silicon or Linux machine:

```bash
# Clone DramaFoundry and the gateway side by side
git clone https://github.com/ffrappo/dramafoundry.git
git clone https://github.com/ffrappo/dramafoundry-gateway.git
cd dramafoundry

# Configure environment
cp .env.example .env

# Launch in-process stack
docker compose up -d --build
```

### Services Started
- **`api`** (`:8780`): FastAPI creation backend and task runner.
- **`newapi`** (`:8781`): `dramafoundry-gateway` model routing adapter.
- **`web`** (`:8080`): Production React web UI.

---

## 6. Common Pitfalls & Solutions

| Issue | Cause | Solution |
| :--- | :--- | :--- |
| `HTTP 401 Unauthorized` | Missing or rotated token | Run `/fornace update` inside Pi to reconcile credentials. |
| `Queue task full (429)` | Prior render step still active | Check `GET /tasks` and wait for existing render to complete. |
| `First frame missing` | Step skipped in pipeline | Run sketch selection (`selected_regen`) before `single_video`. |
| `Lip-sync drift` | Replaced audio track | Never replace MiniMax H3's embedded audio track after generation. |
| `No available video fragments` | Calling compose prematurely | Verify all beat videos are rendered before triggering `compose_episode`. |