docs: close architecture.md coverage gaps + de-link CLAUDE.md from user docs - #138
Merged
Conversation
…er docs Audited docs/architecture.md against the tree. Symbol-level accuracy was good (1 of 1185 backticked identifiers was wrong); the drift was coverage. Corrections: * api.format_dma_latency() -> api.format_write_latency(), the real method. * Two code comments pointed at CLAUDE.md sections that were never written (dsp.py's "[dsp]" and config.py's "ensemble coordination"). New architecture.md sections for two undocumented subsystems: * dsp.py — the 4-bit DAC's pre-emphasis/AGC/expander/compressor/limiter chain: why the order is load-bearing, the streaming-continuity invariant, and AGC's measured level-vs-VAD limitation. * orchestrator.py + orchestrators/ — the conductor/follower broadcast protocol behind `orchestrate = true`, incl. the follower-role guards in Playlist._safe_setup and BigTextSpan's publish-before-begin ordering. Completed the CLAUDE.md module tree, which was missing 16 files (backend.py, teensyrom_*.py, doctor.py, dsp.py, ensemble.py, orchestrator.py + orchestrators/, dither.py, camera.py, profiler.py, rolling_palette.py, audio_marker.py, overlays/menu.py, and helpers). CLAUDE.md is AI-facing project instructions, so it is no longer offered to humans as a reference: README.md, docs/*.md, the asset READMEs, code comments, and codecov.yml now point at docs/architecture.md, docs/usage.md, or the source, and architecture.md stands on its own.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Audit of
docs/architecture.mdagainst the current tree, plus the follow-on fixes.What the audit found
Symbol-level accuracy was already good: of the 1,185 backticked identifiers in the doc, exactly one didn't resolve against the codebase. The real drift was coverage — 30
###sections for 72 modules, with several substantial subsystems documented nowhere.Corrections
api.format_dma_latency()doesn't exist; the method isapi.format_write_latency().dsp.py's "see CLAUDE.md[dsp]" andconfig.py's "See CLAUDE.md ensemble coordination". Both now point somewhere real.New sections
dsp.py— the 4-bit DAC's pre-emphasis → AGC → expander → compressor → limiter chain: why that order is load-bearing, the streaming-continuity invariant every processor must preserve (and why AGC smooths per-sample to keep it), and AGC's measured level-vs-VAD limitation.orchestrator.py+orchestrators/— the conductor/follower broadcast protocol behindorchestrate = true: registry resolution, why the events live onEnsemblerather than the orchestrator, the follower-role guards inPlaylist._safe_setup/_safe_teardown, and BigTextSpan's publish-before-begin()ordering.Tree completion
The CLAUDE.md module tree was missing 16 files, including the entire TeensyROM backend (
teensyrom_api.py,teensyrom_dma.py),backend.py, anddoctor.py— the largest module in the tree.CLAUDE.md is no longer suggested to humans
CLAUDE.md is AI-facing project instructions. README.md,
docs/*.md, the asset READMEs, code comments, and codecov.yml previously linked to it as a human reference; they now point atdocs/architecture.md,docs/usage.md, or the source.docs/architecture.mdno longer opens by describing itself as a companion to CLAUDE.md — it stands on its own.Verification
make lint,make typecheck(mypy --strict + pyright),make test(2633 tests) all pass.CLAUDE.mdreferences remain outside CLAUDE.md itself, all 1,237 doc identifiers resolve, and every relative link across the human-facing docs resolves.Docs only — no behavior change, no hardware testing needed.