docs: consolidate root-level *.md documentation into discoverable structure (two-phase)

[ford442]

Problem

The repo root holds ~35 Markdown files (HARMONIZER_IMPLEMENTATION.md, HOLOGRAPHIC_KNOBS.md, RUBBERBAND_*.md, JC303_STACK_OVERFLOW_FIX.md, TTS_*.md, IMPLEMENTATION_SUMMARY*.md, etc.). Discoverability is poor, onboarding is hostile for new contributors and agents (Jules, Copilot, Claude), and git log / PR diffs against root are noisy. Autonomous agents including Jules and Claude reference these files for context — when they can't find them, they hallucinate or make redundant calls.

This is a two-phase resolution. Phase 1 is zero-risk and ships immediately. Phase 2 is the physical migration, deferred until active sprint velocity drops.

---

Phase 1 — Ship Now: DOCS.md Root Index (zero-move, zero-risk)

Do not move any files. Add a single DOCS.md at repo root that indexes every Markdown file under topic headings with one-sentence summaries and relative links.

Why Phase 1 first

During active feature work, a bulk rename/move of 35 files creates:

• Merge-conflict blast radius on every open branch touching any doc
• git blame discontinuity — GitHub web blame does not follow renames without ?follow-renames=true; agents and contributors hit dead walls
• Case-sensitivity trap — root already contains both CLAUDE.md and claude.md; on APFS/Windows a checkout or automated agent performing git mv on one while the other stays can corrupt the git index
• External raw-URL 404s — GitHub provides no redirect for moved raw files; any link in issues, Discord, chat history, or external sites breaks permanently

Phase 1 resolves the stated pain points (discoverability, agent context efficiency) at zero cost.

Phase 1 acceptance criteria

• DOCS.md exists at repo root
• Every root *.md file (except DOCS.md itself) is listed with a one-sentence summary and working relative link
• Files are grouped under topic headings: Audio Engine, WASM / C++, UI / UX, TTS / Vocal, Deployment, Refactoring / Architecture, Archive / History, Active Working Docs
• AGENTS.md and claude.md updated to reference DOCS.md as the entry point for context lookup
• docs/README.md stub created that redirects: See [DOCS.md](../DOCS.md) at root for the full index. (so a future docs/ tree has a home immediately)
• npm run build still passes

---

Phase 2 — Deferred: Physical Migration into docs/ (when sprint cools)

Execute only after Phase 1 is live and the current holographic-knob / TTS / WASM sprint concludes.

Ambiguity rule (from design review)

Domain Isolation over Lifecycle Phase. If a doc pertains to a specific subsystem (TTS, Rubberband, 3D Knobs), it belongs in that subsystem's folder regardless of whether it discusses design, implementation, or deployment of that feature. The deployment/, refactoring/, and archive/ folders are strictly reserved for global, app-wide processes.

Target folder structure

Destination	Files
docs/audio-engine/	HARMONIZER_IMPLEMENTATION.md, MULTISAMPLE_GENERATOR_DESIGN.md, MULTISAMPLE_IMPLEMENTATION_SUMMARY.md, RUBBERBAND_ANALYSIS.md, RUBBERBAND_DESIGN.md, RUBBERBAND_ENHANCEMENT_PLAN.md, RUBBERBAND_INTEGRATION_GUIDE.md, SUSTAIN_PROCESSOR_RUBBERBAND_GUIDE.md, programmatic_composer.md
docs/wasm/	JC303_STACK_OVERFLOW_FIX.md, OPEN303_FALLBACK_MODES.md, OPEN303_STACK_OVERFLOW_FIX.md, OPENMP_IMPLEMENTATION.md, OPENMP_RUBBERBAND_PATCHES.md, jc303-fix-plan.md, jc303-technical-analysis.md, BUILD_NOTES.md
docs/ui/	HOLOGRAPHIC_COMPARISON.md, HOLOGRAPHIC_KNOBS.md, HOLOGRAPHIC_USER_GUIDE.md, kbd-plan.md, live-kbd-plan.md, progress-bar-critique.md, progress-bar-design.md
docs/tts/	TTS_DEPLOYMENT.md, TTS_IMPLEMENTATION_SUMMARY.md, TTS_PER_BANK_VERIFICATION.md, TTS_VISUAL_GUIDE.md, VOCAL_WORKSTATION_PLAN.md
docs/deployment/	CLOUD_API_VERIFICATION.md, DEPLOYMENT_CONFIG.md, DEVELOPER_CONTEXT.md
docs/refactoring/	APP_REFACTORING_SUMMARY.md, PERFORMANCE_MIGRATION_STRATEGY.md, REFACTORING_SUMMARY.md, streamlining.md
docs/archive/	IMPLEMENTATION_COMPLETE.md, IMPLEMENTATION_SUMMARY.md, IMPLEMENTATION_SUMMARY_3D_KNOBS.md, INTEGRATION_SUMMARY.md, PR_SUMMARY.md, SECTIONS_3_4_SUMMARY.md, features-implementation.md, plan.md, work_jan26.md
Stay at root	README.md, AGENTS.md, claude.md, CLAUDE.md, weekly_plan.md, agent_plan.md, bug-report.md, DOCS.md

Phase 2 chunked into 4 PRs (keep diffs reviewable, minimize rebase surface)

PR A — Archive & Refactoring Foundation

• Create docs/README.md, docs/archive/, docs/refactoring/
• Move the 13 archive/refactoring files via git mv
• Update AGENTS.md, README.md, DOCS.md to point to new paths

PR B — UI & TTS Subsystems

• Create docs/ui/, docs/tts/
• Move 12 UI/TTS files via git mv
• Update .Jules/palette.md and .jules/ agent instructions to point to new UI doc paths (critical — Jules reads these for context)

PR C — Audio Engine & WASM Backend

• Create docs/audio-engine/, docs/wasm/
• Move 17 DSP/C++ files via git mv
• Audit verify_harmonizer.py, verify_envelope.py, WASM .sh build scripts for hardcoded root paths

PR D — Deployment & Final Index

• Create docs/deployment/
• Move 3 deployment/config files
• Complete docs/README.md with full index
• Verify deploy.py, update_app.py still execute; confirm no CI YAML references broke

Phase 2 dependency scan (must complete before PR A)

Before opening any Phase 2 PR, audit these for hardcoded root *.md paths:

• README.md, AGENTS.md, claude.md — inline links to moved docs
• .Jules/palette.md, .jules/*.md — agent context file references
• update_plan.py, update_plan_final.py, verify*.py — may programmatically read/parse root .md checklists
• src/** — check for any import ... from '../../*.md' (Vite can import MD files; would break build)
• .github/workflows/*.yml — any step that globs root *.md
• rebuild_open303.sh, tools/build_jc303_omp.sh — echo/read BUILD_NOTES.md?

Phase 2 acceptance criteria

• Root contains ≤ 8 *.md files
• docs/README.md indexes every moved file with one-sentence summary
• git mv used for every move (no delete+create)
• No broken intra-repo Markdown links (grep or link-checker run)
• npm run build passes
• Agent instruction files (.Jules/, .jules/) updated for new paths
• All Python scripts still execute without path errors

---

Open questions (resolved by design review)

1. agent_plan.md / weekly_plan.md at root? → Stay at root. Active working docs.
2. Active vs. archive tagging? → docs/archive/ folder is the tag. DOCS.md index notes "archive" in the heading.
3. Case-sensitivity (CLAUDE.md vs claude.md)? → Both stay at root. Do not touch either file in Phase 2. Explicit exclusion in all git mv scripts.
4. External raw-URL breakage? → Phase 1 (no moves) has zero risk. Before Phase 2 PR A opens, search open issues + known external references and add stub files at old root paths for any confirmed external links.