7bcd8052a9
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).
66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
# 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
|