# llm-docs Specification

## Purpose

Documentation-only capability. Defines 9 LLM-ready files that ground any LLM in the REAPER `.rpp` generation system. Zero code changes — all artifacts are additive under `docs/` plus a README rewrite.

## Requirements

### Requirement: LLM_CONTEXT.md Aggregates System Knowledge

`docs/LLM_CONTEXT.md` MUST be a single entry-point file under 40KB that an LLM can read to understand the entire system. Content MUST include: system description, ASCII architecture diagram, all dataclass definitions from `src/core/schema.py`, module index mapping each `src/` directory to its role, pipeline steps (compose → build → calibrate → validate), plugin system (`PLUGIN_REGISTRY`, `ALIAS_MAP`, presets), ReaScript protocol, CLI reference for `scripts/compose.py`, `scripts/generate.py`, `scripts/run_in_reaper.py`, naming conventions, and extension guide. File MUST be valid markdown.

#### Scenario: LLM grounds from LLM_CONTEXT.md alone

- GIVEN an LLM with no prior knowledge of fl_control
- WHEN it reads `docs/LLM_CONTEXT.md`
- THEN it identifies REAPER `.rpp` as the target format, understands `SongDefinition` → `TrackDef` → `ClipDef` as the core data model, knows module layout under `src/`, and locates CLI entry points
- AND the file is under 40KB valid markdown with all required sections present

### Requirement: Module Deep-Dives Enable Targeted Modification

Each module doc under `docs/modules/` MUST document: public API signatures with types, data flow in/out, dependencies, and known gotchas. Each MUST reference `LLM_CONTEXT.md` as parent.

#### Scenario: LLM modifies a module after reading its deep-dive

- GIVEN `docs/modules/reaper-builder.md` exists
- WHEN an LLM reads it
- THEN it identifies `RPPBuilder`, `PLUGIN_REGISTRY` format (key → display_name, filename, uid_guid), `write()` signature, and dependency on `src/core/schema.py`

### Requirement: JSON Schemas Match Dataclass Definitions

`docs/schemas/song-definition.json` MUST be JSON Schema draft-07 matching every field in `SongDefinition`, `SongMeta`, `TrackDef`, `ClipDef`, `MidiNote`, `SectionDef`, `PluginDef`, `PatternDef`, `ArrangementItemDef`, `CCEvent` as defined in `src/core/schema.py`. `docs/schemas/reascript-protocol.json` MUST match `ReaScriptCommand` and `ReaScriptResult` in `src/reaper_scripting/commands.py`. Field names, types, and required/optional flags MUST match the dataclass source exactly.

#### Scenario: Schema validates SongDefinition instance

- GIVEN a `SongDefinition` serialized via `to_json()`
- WHEN validated against `song-definition.json`
- THEN zero schema violations; every field name, type, and required constraint matches the dataclass

### Requirement: README.md Reflects True System Identity

`README.md` MUST NOT reference FL Studio, `.flp` files, or MCP server. MUST reference REAPER `.rpp` generation, list real CLI entry points (`compose.py`, `generate.py`, `run_in_reaper.py`), and point to `docs/LLM_CONTEXT.md`.

#### Scenario: New developer reads README

- GIVEN a developer reading `README.md`
- THEN they see "REAPER", ".rpp", and `docs/LLM_CONTEXT.md`
- AND they see NO mention of "FL Studio", ".flp", or "MCP"

### Requirement: Cross-Reference Integrity

All internal markdown links in docs MUST resolve to existing files or headings. Module names in docs MUST match actual Python module names under `src/`. Dataclass field names in docs MUST match `src/core/schema.py` exactly.

#### Scenario: Links resolve and names match code

- GIVEN all doc files under `docs/`
- WHEN an LLM or human follows every `[link](./path)` reference
- THEN every link resolves; no broken cross-references exist
- AND all module and field names match their definitions in code