# Fornace Pi Usage Guide

> Operational manual for the Fornace Pi coding agent environment.
> Designed for both human operators and autonomous coding agents.
> Source: https://onboarding.fornace.app/usage
> Raw Markdown: https://onboarding.fornace.app/usage.md

---

## 1. Quick Reference & Core Commands

### Launching Pi

Always work inside `cmux` surfaces for persistent terminal sessions and supervisor monitoring:

```bash
# Open cmux (workspace orchestrator)
cmux

# Launch Pi in current directory
pi

# Or launch with a direct goal
pi "Review this repository and report architecture"
```

### Slash Commands Inside Pi

Shipped in the `fornace-setup` extension (`~/.pi/agent/extensions/fornace-setup.ts`):

| Command | Action | Description |
| :--- | :--- | :--- |
| `/fornace install` | Provision | Fresh installation of team skills, extensions, and DramaFoundry credentials |
| `/fornace update` | Update | Idempotent reconciliation of skills (1.14.3+), extensions (1.2.1+), and token refresh |
| `/fornace list` | Inspect | Lists installed team extensions, skill count, and DramaFoundry status |
| `/fornace doctor` | Diagnostic | Audits gateway key, Matchbox login, DramaFoundry credentials, and tools |
| `/fast session` | Compaction | Zero-model-cost mechanical context reduction. Call when context approaches 50%. |
| `/compact` | Compaction | Interactive summary-based context compaction |

---

## 2. Model Routing & Tiers

The Fornace Mantice gateway (`https://llm.fornace.net/v1`) serves four standard tiers.
Routes are cost-optimized; always use the least expensive capable tier for the task.

| Tier / Alias | Role & Capability | Best For |
| :--- | :--- | :--- |
| `fornace-flash` | Ultra-low latency, mechanical speed | Summaries, digests, RTK re-reads, mechanical edits |
| `fornace-fast` | Fast reconnaissance & search | File scouting, pattern matching, initial triage |
| `fornace-reasoning` | High-depth synthesis & planning | Architectural plans, system synthesis, complex debugging |
| `fornace-max` | Heavy engineering & coding | Substantial implementations, multi-file refactoring, production code |
| `fornace-astra` | High-tier recovery | **Explicit user request only.** Never use for routine work. |

### Subagent Roles

When delegating tasks using the `subagent` or `agent_spawn` tools:

- `quick`: `fornace-flash` for mechanical file manipulation or formatting.
- `scout`: `fornace-fast` for repo reconnaissance and finding files.
- `planner` / `researcher`: `fornace-reasoning` for synthesis and architectural planning.
- `builder` / `critic` / `operator`: `fornace-max` for substantial coding and adversarial review.

---

## 3. Generative Media & Video Workflows

All media work is governed by two strict operating rules:

### RULE ONE: No Traditional VFX
Every pixel of a repaired, altered, or generated frame must come from an AI model.
Never assemble, blend, patch, feather, clone, or composite pixels manually with OpenCV, PIL, or ffmpeg filter chains. Our code only trims clips, prepares model inputs, calls APIs, and measures results.

### RULE TWO: Approved Editors Only (Proposed First)
The approved video editors are **Wan 2.7 edit** (`fal-ai/wan/v2.7/edit-video`) and **FLUX 3 edit**.
Every edit must be proposed with current status, source defect, and intended change, awaiting explicit human approval.

### Video Skills Catalog

- `generative-media`: Umbrella entry gate. Checks `MODELS.md` freshness (< 7 days) and selects approved routes.
- `video-edit-pipeline`: Split footage at scene boundaries, edit parts in parallel, retime to source grid, conform over original audio.
- `long-form-character-video`: Direct 2-3 minute vertical stories. Fast pace (190-210 wpm), active physical business, populated public spaces, scene-specific sound.
- `thinksound-native`: Local sound beds, foley, and ambience on Apple Silicon Metal 4, mixed under dialogue at -33 LUFS.
- `dynamic-subtitles`: Remotion word-by-word highlighted subtitles with ASR timestamps.

---

## 4. DramaFoundry Production Workflow

DramaFoundry is the team's platform for turning novels and screenplays into multi-episode vertical drama series.

- **Web Application**: `https://dramafoundry.fornace.net`
- **Team Authentication**: Automatically provisioned by `/fornace install` or `setup.sh`. Stored in `~/.pi/agent/credentials/dramafoundry.json`.
- **Pi Skill**: `dramafoundry`

### Typical Workflow

1. **Manuscript Ingest**: Upload novel or script chapters; extract characters, locations, and episode arcs.
2. **Director Planning**: Automatic beat-by-beat storyboard decomposition with visual continuity prompts.
3. **Identity Sheets**: Generate character turnarounds and location references with FLUX / Ideogram.
4. **Per-Beat Generation**: Batch video rendering via MiniMax H3 Max Turbo, Wan 2.1, or Kling 3.0.
5. **Sound & Voice**: Dialogue synthesis with AuK / Fish Voice, ambient beds with ThinkSound.
6. **Conform & Export**: Dynamic caption overlay, lossless audio mux, vertical 9:16 export.

---

## 5. Paid Advertising & Growth Suite

Full multi-platform paid ads audit and creative generation via the 23-skill suite:

```bash
# Extract brand DNA (colors, typography, voice) from URL
/ads dna https://client-website.com

# Create strategic campaign brief and messaging pillars
/ads create

# Generate platform-sized ad visuals
/ads generate

# Audit paid accounts (Google, Meta, TikTok, LinkedIn, Apple, Amazon)
/ads audit
/ads google
/ads meta
```

---

## 6. Infrastructure, Cloudflare & GPU

- **Cloudflare Platform**: Use `cloudflare`, `agents-sdk`, `durable-objects`, `wrangler`, and `turnstile-spin`.
- **Web Verification**:
  - `autonomous-qa`: Real browser journey testing simulating human user.
  - `ui-audit`: Desktop and mobile visual audit matrix with screenshot capture.
- **GPU Rentals**:
  - Use `vast-gpu` wrapper over `forgia-executor` for disposable Vast.ai GPU instances.
  - Always prefer European instances; auto-recharge is enabled. Destroy instances when finished.

---

## 7. Team Communication & Identity

- **Telegram Bot (`@fornaceaibot`)**:
  - Team gateway: `/key` provisions or retrieves your personal Mantice gateway key.
  - Agent DMs: Pi can send direct messages to colleagues using the `fornceaibot` skill.
- **Fornace Matchbox**:
  - CLI: `fornace-matchbox login`
  - Enrolls Mac via passkey for automatic device-authenticated access to privileged provider capabilities (Meta, Stripe, Vercel, Fal.ai).
- **Honcho Shared Memory**:
  - Global teammate memory: `personal-ffrappo`, peer `ffrappo`.
  - Repository-scoped memory: `fornace/repo-<reponame>`.
  - Recall context before non-trivial work; persist durable facts.

---

## 8. Agent Prompt Templates (Copy & Paste into Pi)

### Task: Full Repository Audit & Freshness Check
```text
Audit this repository against our AGENTS.md rules. Run a freshness check on the active SDKs and platforms in play. Check that source files are ≤ 400 lines, no dead fallbacks exist, and native Apple Silicon is prioritized.
```

### Task: DramaFoundry Episode Production
```text
Using the dramafoundry skill, inspect the script at ./script.txt. Generate a beat plan for Episode 1, produce the character turnaround prompts, and verify the model gateway credentials.
```

### Task: Autonomous Web QA
```text
Run autonomous-qa on http://localhost:3000. Simulate a new user onboarding journey, catch any console errors or DOM flow blockers, and fix issues in place.
```