docs: LLM-ready documentation suite — LLM_CONTEXT.md, module deep-dives, JSON schemas, CLI reference

Complete documentation system for LLM consumption: primary LLM_CONTEXT.md
(27KB system overview), 4 module deep-dives (composer, reaper-builder,
reaper-scripting, calibrator), 2 JSON Schema draft-07 contracts, CLI
reference, and README correction (FL Studio -> REAPER identity).

.sdd/changes/archive/llm-docs/spec.md

@@ -0,0 +1,59 @@
+# 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