chore: tighten repo structure — clean README, consolidate docs, untrack runtime state

[slittycode]

Goal

Move the repo toward a tight, scannable shape — one canonical agent guide, one README, one place for past-tense plans. No code changes; only docs, layout, and .gitignore.

Inspired by how minimal tool repos like soundscope feel — README + src/ + LICENSE and not much else at the root. ASA is a two-app monorepo so the floor is higher, but the same hygiene principles apply.

Before / After at the root

Before	After
README.md (222 lines, mostly setup)	README.md (~80 lines, scannable intro + doc index)
CLAUDE.md (248)	CLAUDE.md (precedence chain updated)
AGENTS.md (512)	AGENTS.md (thin pointer to CLAUDE.md)
CODEX.md (84)	removed
OPTIMIZATION_PLAN.md (484)	→ docs/history/optimization-plan.md
PLAN-phase1-hardening.md (592)	→ docs/history/phase1-hardening-plan.md
ASA_System_Design.docx (42 KB binary, tracked)	untracked + gitignored
.runtime/analysis_runs.sqlite3 (live runtime state, tracked!)	untracked + gitignored
advisory/phase1_audit/ (8 audit/deck files)	→ docs/history/phase1-audit/
docs/archive/	→ docs/history/archive/
apps/{ui,backend}/LICENSE (identical to root)	removed
apps/{ui,backend}/CODEX.md	removed

What's in docs/history/

A single place for past-tense docs — completed plans, one-shot audits, archived results. New docs/history/README.md calls this out explicitly so future readers don't mistake it for living documentation.

New docs/SETUP.md

Absorbs everything that was crowding README.md: bootstrap, manual venv path, Phase 2 / Gemini wiring, env var gotchas, runtime profiles, upload limits, verification commands, release-position note. README links into it.

Stale-link cleanup

References to the old docs/archive/... path updated in:

• CHANGELOG.md
• tests/ground_truth/README.md
• scripts/calibrate_confidence.py (comment referencing the moved plan)

Why these choices

User-confirmed picks before the cleanup:

• Agent docs: Keep CLAUDE.md canonical; keep AGENTS.md as a stub so tools that look for AGENTS.md by name (Codex, OpenHands) still find it. Drop CODEX.md.
• Plan docs: Move to docs/history/ with one index README rather than deleting outright — preserve as paper trail.
• .docx files: Untrack but keep locally via .gitignore (source-of-truth presumably lives in Drive/Notion).

Diff summary

66 files changed, 276 insertions(+), 927 deletions(-)

Net ~650 fewer lines of root-level / stale doc surface, plus one untracked sqlite that had no business being in git.

What was deliberately not touched

Per CLAUDE.md's "Recent Refactors (don't undo)" section:

• apps/backend/ module split (analyze_core/_detection/_rhythm/_segments/_structure/_transcription)
• apps/ui/src/services/ split into focused service files
• Hosted runtime seams (runtime_profile.py, worker.py, artifact_storage.py, auth_context.py)

Other deliberate non-changes:

• Per-app CHANGELOG.md kept (root note explicitly says these are imported history, not monorepo release history).
• Per-app AGENTS.md kept as substantive app overlays (only root-level agent-doc duplication was collapsed).
• dsp_json_override legacy field path not removed — out of scope for a doc-cleanup PR.

Verification

Cleanup is doc/layout-only, no source code touched outside comments and links. The frontend npm run verify and backend unittest discover paths are unaffected; canonical paths (scripts/dev.sh, apps/backend/scripts/bootstrap.sh, the analyze.py contract) all still resolve.

https://claude.ai/code/session_01GvD1K33Jev3vrQXRsX9WAG

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE

Summary

Docs-only cleanup: README rewritten to ~80 lines, setup detail moved to new docs/SETUP.md, AGENTS.md reduced to a convention pointer, three CODEX.md files removed (content absorbed into CLAUDE.md + per-app AGENTS.md), historical plan/audit docs consolidated under docs/history/, and two .docx binaries and a live SQLite database untracked from git. The one non-doc change is a single comment line in scripts/calibrate_confidence.py updating a path reference. No source logic was touched.

Findings

Worth considering:
The CLAUDE.md precedence chain was corrected from PURPOSE.md > AGENTS.md chain > this file to PURPOSE.md > this file > per-app AGENTS.md. The old ordering was wrong — CLAUDE.md was listed as lower-precedence than a thin pointer doc — so this is a fix, not a regression. Just worth knowing the chain changed if any agent has it cached.

Nothing else.

Test results

Not run — no executable logic changed. The only .py file touched is a comment-only edit in a script that isn't part of the backend test suite.

Phase boundary check

Clean. No source files in apps/ modified.

---

Generated by Claude Code