docs: Day-8 close-out — AGENTS §12-§14 + README Day-8 row

- AGENTS §12 documents the multi-modal explainer surface
(explain(payload, modality)), §13 the Experiments routes
(/experiments/runs, /experiments/diff) and disable-mlflow contract,
§14 the HF Spaces deploy surface (Dockerfile.hf, supervisord.conf,
build-time artifact baking).
- README adds Day 8 to the status table (184 tests green) and points
to the Day-8 plan + new endpoints + new deploy artifacts.
- DoD-1 through DoD-5 all green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -231,3 +231,48 @@ behavior:
 The `POST /explain/bbb` endpoint mirrors this contract. Pydantic
 enforces a non-empty `top_features` list (422 on empty); every other
 failure mode degrades to template + WARNING log + `source="template"`.
+
+## 12. Multi-Modal Explainer (Day 8)
+
+`src/llm/explainer.py` exposes `explain(payload, modality)` where
+`modality ∈ {"bbb", "eeg", "mri"}`. Each modality has its own
+deterministic template (`_template_explain_bbb / _eeg / _mri`) and
+its own LLM prompt header. Unknown modality strings degrade to the
+BBB template with a warning log; the function never raises. The
+hybrid OpenRouter fallback contract from §11 applies uniformly.
+
+The API exposes three matching endpoints — `POST /explain/{bbb,eeg,mri}` —
+each on the `explain_router` (`/explain` prefix). Streamlit surfaces
+the BBB version in the AI Assistant tab and the EEG/MRI versions as
+inline expanders inside their respective pipeline tabs.
+
+## 13. Experiments Surface (Day 8)
+
+`GET /experiments/runs` returns up to 50 most recent MLflow runs
+across the bbb/eeg/mri experiments, flattened into a list of
+`MLflowRunSummary` (run_id, experiment_name, start_time, status,
+metrics, params). `POST /experiments/diff {run_id_a, run_id_b}`
+returns a side-by-side metric+param diff (`RunDiffRow`).
+
+When `NEUROBRIDGE_DISABLE_MLFLOW=1`, both endpoints return empty
+responses without raising — required for the HF Spaces deployment
+where there is no writable mlruns/ tree. Unknown run ids → 404.
+
+The Streamlit "Experiments" tab is the user-facing surface. Cached
+in session state with an explicit Refresh button.
+
+## 14. Deploy Surface (Day 8)
+
+`Dockerfile.hf` is the Hugging Face Spaces image. Single container,
+two processes (FastAPI :8000 + Streamlit :7860) launched via
+`supervisord.conf`. Build-time `RUN python -m src.models.bbb_model`
+bakes the model artifact into the image so the first `/predict/bbb`
+call is instant on cold start.
+
+Default environment: `DEPLOY_ENV=hf_spaces`,
+`NEUROBRIDGE_DISABLE_MLFLOW=1`, `NEUROBRIDGE_DISABLE_LLM=1`.
+Operators can opt back into LLM by setting `OPENROUTER_API_KEY` in
+the HF Space's Secrets panel and unsetting the disable flag.
+
+The README's YAML front-matter declares the Space metadata
+(SDK=docker, port=7860, app_file=src/frontend/app.py).

README.md

@@ -38,6 +38,7 @@ short_description: Living decision system for BBB, EEG, and MRI clinical ML
 | 5 | Decision Layer (Model + XAI + Interactive UI) | [`bbb_model.py`](src/models/bbb_model.py) — RandomForest + SHAP + `POST /predict/bbb` | Shipped — 158 tests green |
 | 6 | Final Polish & Demo Features (Edge cases + Calibration + ComBat viz) | Calibration metadata + edge-case probes + `POST /pipeline/mri/diagnostics` | Shipped — 165 tests green |
 | 7 | Final 5% (Drift, Traceability & Agents) | Per-worker drift z-score + MLflow provenance badge + `POST /explain/bbb` (LLM + template fallback) + AI Assistant tab | Shipped — 175 tests green |
+| Day 8 — The Grand Finale (Multi-Modal Agents, Track 5 & Public Deploy) | Shipped — 184 tests green |
 
 ## Quick Start
 
@@ -220,6 +221,9 @@ finishes in under 4 seconds on a 2024 laptop.
 - **Day-7 plan (full TDD task breakdown):** [`docs/superpowers/plans/2026-05-05-day7-drift-traceability-agents.md`](docs/superpowers/plans/2026-05-05-day7-drift-traceability-agents.md)
 - **New surface:** `POST /explain/bbb` — natural-language rationale (LLM + deterministic fallback)
 - **New surface:** `drift_z` / `rolling_n` / `provenance` fields in `POST /predict/bbb` response
+- **Day-8 plan (full TDD task breakdown):** [`docs/superpowers/plans/2026-05-06-day8-grand-finale.md`](docs/superpowers/plans/2026-05-06-day8-grand-finale.md)
+- **New surfaces:** `POST /explain/eeg`, `POST /explain/mri`, `GET /experiments/runs`, `POST /experiments/diff`
+- **New deploy artifacts:** `Dockerfile.hf`, `supervisord.conf`
 
 ## Day 7 — Demo Recipe