docs: document the HTML match report (report subcommand + API)

README.md

@@ -28,7 +28,8 @@ do work that is not already done, and resume cleanly after an interruption.
   clinical trials — embeddings, biomedical entity annotations, and parsed
   eligibility constraints — and builds a local search index.
 - **Match** ingests a patient, retrieves candidate trials, and reasons over each
-  trial's eligibility criteria to produce a ranked, explained shortlist.
+  trial's eligibility criteria to produce a ranked, explained shortlist — rendered
+  as a self-contained HTML report you can open in any browser.
 
 Trials, models, indexes, and results all live on your own machine.
 
@@ -142,6 +143,11 @@ trialmatchai e2e --input data/patients/omop_extract
 Results land in `results/<patient_id>/` (ranked trials + eligibility
 explanations). Re-running skips patients already matched.
 
+Each run also writes a self-contained HTML report you can open in a browser:
+`results/index.html` is a front page over every matched patient, and
+`results/<patient_id>/report.html` is one patient on its own. (Disable with
+`reporting.emit_html: false`.)
+
 ### Keeping trials current
 
 Validate the installation, then fold new or changed ClinicalTrials.gov studies
@@ -280,6 +286,7 @@ The commands below are convenience presets over that pipeline.
 | `trialmatchai e2e` | Ingest a patient and match end-to-end (idempotent, per-patient resume) |
 | `trialmatchai import-patient` | Import text, FHIR, Phenopacket, or OMOP patient data into a profile |
 | `trialmatchai run` | Match already-staged patient profiles |
+| `trialmatchai report` | Render a self-contained HTML match report — one patient (`--patient <id>`) or a unified front page over all (`--all`) |
 | `trialmatchai trec` | Benchmark: end-to-end evaluation on the official TREC Clinical Trials tracks |
 
 **Utility**

docs/api.md

@@ -51,3 +51,14 @@ orchestration stages and evaluation metrics are documented for programmatic use.
         - parse_qrels
         - corpus_ncts
         - evaluate
+
+## HTML report
+
+::: trialmatchai.interop.exporters.html_report
+    options:
+      members:
+        - build_report_model
+        - profile_to_model
+        - profile_to_html_report
+        - render_unified_html
+        - render_html_report

docs/index.md

@@ -29,7 +29,7 @@ many times** — and both are idempotent: finished work is never redone.
 trialmatchai bootstrap-data            # fetch the prepared corpus + adapters (Zenodo)
 trialmatchai build --concepts          # prepare + index + concept store (resumable)
 trialmatchai e2e --input patient.txt   # ingest + match one patient
-# -> results/<patient_id>/ranked_trials.json
+# -> results/<patient_id>/ranked_trials.json  +  a self-contained results/index.html
 ```
 
 ## One pipeline, maximally modular

docs/pipeline.md

@@ -71,6 +71,22 @@ These are thin wrappers over the pipeline that add their own setup:
 Every command is idempotent and resumable: re-running continues from the last
 completed work.
 
+## Reports
+
+Matching writes a self-contained, offline HTML report (no server, no build step,
+no CDN). It is emitted automatically at the end of a run —
+`<output_dir>/<patient_id>/report.html` per patient and `<output_dir>/index.html`
+as a front page across all patients — and can be regenerated from existing results
+without re-matching:
+
+```bash
+trialmatchai report --patient 1009     # one patient        -> <output_dir>/1009/report.html
+trialmatchai report --all              # unified front page -> <output_dir>/index.html
+```
+
+Auto-emit is gated by `reporting.emit_html` (default `true`; disabled for `trec`
+benchmark sweeps).
+
 ## Python API
 
 ```python