Files

renato97 7bcd8052a9 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).

2026-05-04 10:30:24 -03:00

3.3 KiB

Raw Blame History

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

3.3 KiB Raw Blame History