docs: sync AGENTS.md files against post-#141 codebase

apps/backend/AGENTS.md

@@ -129,6 +129,8 @@ python3.11 -m venv venv
 - `recommendation_evaluation.py` + `scripts/evaluate_recommendations.py`: **Research-only.** Recommendation-quality scorer for `GOAL.md`'s recommendation-proof campaign. Grades Phase 2 recs against `tests/fixtures/recommendation_tracks/` known-settings fixtures using a role/parameter/direction-band rubric, per-domain breakdown, and a chain-of-custody penalty that mirrors `phase2Validator.ts`. CLI supports `--source baseline|gemini|deterministic`, `--self-test`, `--report`, `--verification-artifact`. Companion: `scripts/emit_deterministic_recs.ts` is the Node 23+ TS bridge that wraps `apps/ui/src/data/abletonDevices.ts` into the scorer's normalized shape. Status doc: `NEEDS.md`; verdict write-up: `RECOMMENDATION_VERDICT.md`. Off the product path.
 - `live12_catalogue.py`: Source-extracted Live 12 device/parameter catalogue loader. Reads `data/live12_catalogue.json` (generated by repo-root `scripts/build_live12_catalogue.py` from upstream `gluon/AbletonLive12_MIDIRemoteScripts`), validates against the published schema, and exposes `Live12Catalogue.has_device` (case-insensitive), exact-match parameter lookup, and `fuzzy_resolve`. Static-source extraction carries no `type/min/max/unit/default`; reserved for future runtime-introspection enrichment. Imported by `phase2_catalogue_gates.py` and the catalogue tests.
 - `loudness_backend.py`: Selectable Phase 1 loudness backend (default-off experiment, WS3b). `ASA_LOUDNESS_BACKEND=wasm` overrides the four integrated/range/momentary-max/short-term-max LUFS scalars with readings from the native `measure-cli` binary (source-identical to `packages/loudness-spectro-wasm`). `truePeak` and `lufsCurve` stay on Essentia. Any failure degrades back to Essentia silently. Default is `essentia` (no-op). Covered by `tests/test_loudness_backend.py`.
+- `separation_backend.py`: Selectable Phase 1 stem-separation backend (default-off experiment). `ASA_SEPARATION_BACKEND=msst` swaps torchaudio Hybrid Demucs for MSST/BS-RoFormer from a `SUC-DriverOld/MSST-WebUI` checkout, keeping the `{stem_name: wav_path}` contract (`vocals/bass/drums/other`, 44.1 kHz) unchanged. MSST runs in its own venv via `scripts/msst_separate_runner.py` subprocess under `ASA_MSST_PYTHON`; any failure degrades back to Demucs silently. Default is `demucs` (no-op). See `separation_ab.py` for the research-only A/B harness. Covered by `tests/test_separation_backend.py`.
+- `separation_ab.py`: Research-only A/B harness for comparing Demucs and MSST separation backends on quality (SI-SDR) and runtime. Driven by `scripts/ab_separation_backends.py`. Deleting this file restores the product exactly.
 - `phase2_catalogue_gates.py`: **Warn-and-keep** Live 12 source-catalogue annotation of Phase 2 recommendations. Cross-checks every `{device, parameter, value, phase1Fields}` record against `Live12Catalogue` and emits `RECOMMENDATION_UNVERIFIED` events on `validationWarnings` for `device_unknown`, `parameter_unknown`, `value_out_of_range`, `citation_missing`. NEVER drops or rewrites — an earlier fuzzy-rewrite path produced confidently-wrong output (wrong EQ band + wrong A/B curve), so the contract is warn-only. Wired into `server.py` after `_validate_phase2_citation_paths`. Lives separately from `server_phase2.py` so unit tests can run without the FastAPI/pydantic import chain.
 - `utils/cleanup.py`: Periodic artifact cleanup helpers used by the server background-task loop.
 - `tests/test_server.py`: OpenAPI and envelope contract tests.
@@ -138,6 +140,7 @@ python3.11 -m venv venv
 - `tests/test_beat_evaluation.py`, `tests/test_loudness_rec_evaluation.py`: unit coverage for the research/eval-only beat and loudness-recommendation harnesses.
 - `tests/test_mt3_transcription.py`: unit coverage for the optional MT3 polyphonic backend module.
 - `tests/test_loudness_backend.py`: unit coverage for `loudness_backend.py` (the selectable LUFS backend).
+- `tests/test_separation_backend.py`: unit coverage for `separation_backend.py` (dispatch, fallback, model registry, and runner-helper contracts — no MSST install required).
 - `tests/test_loudness_r128.py`: contract tests for ADR 0002 unit changes — `analyze_true_peak` emits dBTP, `analyze_plr` is a dB-domain subtraction.
 - `tests/test_analysis_runtime.py`: SQLite run-state, stage queue, and artifact-metadata behavior.
 - `tests/test_server_phase2.py`: Phase 2 route contracts, `_validate_phase2_citation_paths`, and Gemini upload path behavior.
@@ -167,6 +170,8 @@ Under `apps/backend/scripts/` (not on the product path):
 - `evaluate_phase1.py`, `evaluate_structure_sweep.py`, `evaluate_polyphonic.py`, `evaluate_beats.py`, `evaluate_loudness_recs.py`, `evaluate_recommendations.py`, `build_beat_manifest.py`, `genre_check.py`, `audit_pass1.py`, `replay_catalog_validation.py`: research and audit harnesses for measurement quality, beat/downbeat and loudness-recommendation gates, the recommendation-quality scorer, and prompt-output review. Outputs land under `.runtime/` and are intentionally not wired into the live API. The beat gate's optional neural deps (`beat_this`, `mir_eval`) live in `requirements-eval.txt` — install into a separate venv, never the product venv.
 - `emit_deterministic_recs.ts`: Node 23+ native-TS bridge for `evaluate_recommendations.py --source deterministic`. Wraps `apps/ui/src/data/abletonDevices.ts` so the deterministic recommendation path can be scored against the same fixtures as Gemini without a TypeScript build step. No `npm install` needed.
 - `parity_probe_synth_backends.py`: Maintainer probe that renders the same deterministic `ClipPlan` through both FluidSynth and `symusic.Synthesizer` and reports RMS / peak / spectral-centroid deltas, with a documented tolerance and pass/fail verdict written to `.runtime/parity/synth_parity.json`. Use before flipping the `ASA_SAMPLE_SYNTH_BACKEND` auto default away from FluidSynth — never invoked by the runtime.
+- `msst_separate_runner.py`: Runs in the MSST venv (not the product venv) under `ASA_MSST_PYTHON`. Invoked by `separation_backend.py` as a subprocess; imports `MSSeparator` from a `SUC-DriverOld/MSST-WebUI` checkout, writes canonical `vocals/bass/drums/other` 44.1 kHz WAVs, and prints a one-line JSON manifest to stdout. Operator tooling only — never imported by the product venv.
+- `ab_separation_backends.py`: A/B harness CLI (wraps `separation_ab.py`) comparing Demucs vs MSST on quality and runtime: always-available synthetic SI-SDR smoke-test plus optional real-track reference-free proxies. Writes `.runtime/separation_ab/report.json`. Research-only; deleting `separation_ab.py` restores the product exactly.
 
 ## Code Style
 

apps/ui/AGENTS.md

@@ -100,6 +100,7 @@ RUN_GEMINI_LIVE_SMOKE=true VITE_ENABLE_PHASE2_GEMINI=true GEMINI_API_KEY=your_ke
 - `src/services/transcriptionPianorollClient.ts`: velocity-encoded transcription pianoroll matrix via `/api/analysis-runs/{run_id}/transcription/pianoroll`. Backed by `apps/backend/transcription_pianoroll.py`; rendered in `components/TranscriptionPianoroll.tsx` / `TranscriptionPianorollBlock.tsx`.
 - `src/services/mt3Client.ts`: opt-in MT3 polyphonic transcription client. POSTs `/api/analysis-runs/{run_id}/mt3-transcriptions` and polls the run snapshot for the additive `mt3` namespace. Surfaced only when the user opts in; measurement remains authoritative.
 - `src/services/sampleGenerationClient.ts`: Phase 3 audition-sample POST/GET against `/api/analysis-runs/{run_id}/samples` plus per-clip artifact streaming.
+- `src/services/patchSmith.ts`: Phase 3 Vital preset generation — builds a `.vital` preset JSON from Phase 1 measurements alone, with every parameter citing the exact Phase 1 field(s) that justify it. Surfaced in `components/PatchSmithPanel.tsx`.
 - `src/services/browserLoudness/`: browser-side WASM loudness integration (WS3c). `loader.ts` dynamically imports the built `loudness-spectro-wasm` web glue from `VITE_BROWSER_LOUDNESS_WASM_URL` (off by default — `pkg/` is not a build dep). `wavDecoder.ts` decodes audio to PCM; `parity.ts` defines `BrowserLoudnessReading`. Degrades gracefully when the URL is unset.
 - `src/services/audioFile.ts`: client-side audio validation, blank-MIME extension fallback, and preview-URL lifecycle.
 - `src/services/mixDoctor.ts`: client-side spectral-balance scoring against genre profiles. Genre profile data lives in `src/data/genreProfiles.ts`.