docs: fix stale endpoint paths and close architecture-doc gaps

[benders]

Closes #270. Second half of the documentation review; #269 covered the instruction conflicts. Independent of #269 — different files, no stacking.

Drift fixed

• hub-internals.md → /api/admin/hub/*. The activity and peers admin API was documented under /admin/*, which since Admin mount hardening: per-namespace handler partition (follow-up to #212) #226 mounts authRoutes only (server.ts:381). The doc contradicted the Admin mount hardening: per-namespace handler partition (follow-up to #212) #226 mount table in system-architecture.md. 4 lines.
• pitfalls.md merge paths qualified — hub/src/library/, not hub/src/services/.
• Four broken cross-doc anchors. hub-internals' Sonos/DLNA sections were consolidated into pointers to sonos.md/dlna.md, leaving #sonos-integration-issue-108 and #dlna-mediaserver-issue-175 dangling; two more slugs mis-encoded Hub/Player (the / is dropped, not hyphenated) and a backticked heading. Verified with a script that resolves every link and anchor across docs/, README.md, AGENTS.md, CLAUDE.md — all resolve.

Architecture-doc gaps closed

Three changes had landed without reaching system-architecture.md, which the AGENTS.md checklist requires for architectural work:

• Merge runs off the main thread (fix(merge): protect user data across re-merges (orphan audit + ID remap) and move merge off the event loop #242) — worker_threads Worker on its own connection to the same hub.db, process-wide mutex, terminate on Fastify onClose. Plus the two things that actually bite: SQLITE_BUSY on a main-thread write held across a merge, and never calling mergeLibraries() directly. This is the concurrency model; it was documented only in hub-internals and pitfalls.
• GET /api/version + SPA auto-update (SPA: auto-update on new version while preserving player + queue state #196) — why buildId hashes the on-disk index.html instead of tracking APP_VERSION, and why any difference (not a newer value) means "update available", so rollbacks propagate like upgrades.
• New Relic APM (Observability #3) — key-gated at the entrypoint, zero app-level integration.

Diagram

The deployment diagram showed rest --> hubdb but never the audio path, so streaming — the product — was invisible in the system diagram. It now shows /rest/* resolving the preferred source and bytes leaving via the local Navidrome or a signed peer /proxy/rest/stream.

Design decisions

New table in system-architecture.md: why each load-bearing choice was made and what it costs — one process/two contexts, in-process app.inject(), reversible passwords, mutual trust without quorum, merge-time source selection, the dual catalog, Subsonic-only Navidrome, tolerated legacy settings rows. That rationale existed only in .codebase-memory/adr.md: generated, untracked, referenced by nothing. It answers the "can we just undo X" questions that otherwise get re-litigated from scratch.

.codebase-memory/ is now gitignored — it was the untracked entry in git status.

Verification

git diff -w across the docs shows only the intended content changes; everything else is table realignment per the AGENTS.md padding rule (several tables were already ragged before this). Link/anchor check clean. pnpm verify green (826 hub + 166 frontend tests) — docs-only, but the checklist is the checklist.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q6d5j3DE1sqf6Gm34gEAAN