docs: audio engine architecture + AI agent CLAUDE.md

[mogul]

Reconstructed from slopsmith/slopsmith-desktop#249 — original PR by @topkoa. Commits replayed with original authorship onto the current main.

Summary

Two new docs that make the native audio engine — and the repo as a whole — discoverable to both AI agents and human maintainers:

• docs/audio-engine-architecture.md — describes the native audio + ML detection internals: the audio device callback, the lock-free input ring buffer, the two-tier pitch detection (YIN + Basic Pitch via ONNX), the ChordScorer constraint path, the NoteVerifier background thread, the N-API surface, and the threading invariants every contributor needs to keep in mind. ~12 KB markdown.
• CLAUDE.md at repo root — brief AI agent entry point. Orients on what this repo is vs the sister byrongamatos/slopsmith repo, indexes docs/, cross-links the slopsmith-side docs that describe what consumes the IPC surface this engine exposes, captures threading invariants + build flags + common gotchas in one place.

Motivation

The detection pipeline has substantial moving parts (input ring, two detectors, one verifier thread, sandboxed plugin hosting, split-mode duplex for ASIO) and the only documentation lived in opening comments at the top of each source file. A maintainer wanting to debug into the audio path had to read AudioEngine + PitchDetector + MlNoteDetector + ChordScorer + NoteVerifier + NodeAddon + audio-bridge to assemble the picture.

Separately, an AI agent landing in this repo had no obvious starting point — README.md is install-focused and wouldn't lead them to docs/. The new CLAUDE.md is the navigation hub that other repos in the slopsmith ecosystem already have.

Audience

Both new files target engineers extending or debugging the C++ engine, the ML detector, or the IPC layer. The architecture doc is deliberately denser (assumes JUCE / juce::Thread / atomics fluency); the CLAUDE.md is a brief orientation that links into it.

Companion PR

The renderer-side picture — how note_detect consumes these IPC methods, registers the setNoteStateProvider, and feeds the highway — is documented in a sibling draft PR: byrongamatos/slopsmith#414 — docs: add real-time scoring + hit-feedback pipeline docs. The new docs in this PR link to it; it links back here.

Test plan

• All file:line citations and quoted code verified against current main
• Build flag references (SLOPSMITH_ONNX_SUPPORT) match MlNoteDetector.h / MlNoteDetector.cpp
• ASCII component map matches the actual class layout (NoteVerifier, MlNoteDetector, PitchDetector, ChordScorer)
• CLAUDE.md cross-links to the slopsmith repo resolve
• Reviewer eyeballs the "Threading invariants" section against current code (esp. lock-free guarantees in audioDeviceIOCallbackWithContext)
• Reviewer eyeballs CLAUDE.md's repo orientation — particularly the file-map under src/ and the cross-repo split (audio engine here, library/chart/viz there)

🤖 Generated with Claude Code