# Proposal: LLM-Ready Documentation

## Intent

No LLM can read this codebase and understand it. README.md is wrong (claims FL Studio `.flp`, mentions non-existent MCP server). `.sdd/design.md` references dead `FLPBuilder`. `docs/` is empty. An LLM encountering this project today would be misled for 3+ rounds before discovering it targets REAPER `.rpp`, not FL Studio `.flp`. We need a single entry-point document that instantly grounds any LLM in the real architecture.

## Scope

### In Scope
- `docs/LLM_CONTEXT.md` — primary entry point: architecture, data model, pipeline, module map, CLI reference, naming conventions, how to extend
- `docs/CLI.md` — complete CLI reference (compose, generate, run_in_reaper)
- `docs/modules/composer.md` — composition engine: pattern generators, converters, melody engine
- `docs/modules/reaper-builder.md` — RPP format, `RPPBuilder`, plugin registry (~150 plugins), presets
- `docs/modules/reaper-scripting.md` — ReaScript generation protocol, command/result JSON bridge
- `docs/modules/calibrator.md` — mix calibration presets and post-processing pipeline
- `docs/schemas/song-definition.json` — JSON Schema for `SongDefinition` (SongMeta, TrackDef, ClipDef, MidiNote, SectionDef)
- `docs/schemas/reascript-protocol.json` — JSON Schema for command.json / result.json contract
- `README.md` — fix: FL Studio → REAPER, remove MCP references, correct project structure

### Out of Scope
- `.sdd/design.md` update (separate change)
- Sphinx/pdoc API docs generation
- i18n docs
- Human-focused tutorials

## Capabilities

### New Capabilities
None — documentation only; no behavioral capability changes.

### Modified Capabilities
None.

## Approach

Hybrid: one primary file (`LLM_CONTEXT.md`, ~30KB) as immediate grounding document for any LLM session, plus modular deep-dive docs and JSON Schemas for contract validation. All docs live under existing `docs/` directory. Schemas use standard JSON Schema draft-2020-12. README.md gets a truth-preserving rewrite. Zero code changes — docs are generated manually with LLM assistance, not via docstring extraction.

## Affected Areas

| Area | Impact | Description |
|------|--------|-------------|
| `docs/` | New | Fill with 9 files: LLM_CONTEXT.md, CLI.md, modules/*.md, schemas/*.json |
| `README.md` | Modified | Fix FL Studio → REAPER, remove MCP, correct structure |

## Risks

| Risk | Likelihood | Mitigation |
|------|------------|------------|
| LLM_CONTEXT.md diverges from code | Low | Docs reference exact source files; verified during spec phase via grep cross-check |
| Plugin registry changes break builder docs | Low | Registry path is stable; doc notes it reflects current `PLUGIN_REGISTRY` dict |

## Rollback Plan

`git revert` the commit. All changes are additive to `docs/` + README.md rewrite; no code paths depend on docs. Revert is instant with zero side effects.

## Dependencies

- None (read-only source inspection; no new packages)

## Success Criteria

- [ ] LLM given only `docs/LLM_CONTEXT.md` correctly identifies: REAPER target, RPP format, module structure, CLI entry points
- [ ] JSON Schemas validate against actual `SongDefinition` and reascript command structures
- [ ] README.md accurately reflects project name, target DAW, and real features
- [ ] All module docs reference actual source files and class names