README.md

@@ -418,6 +418,29 @@ was a one-file change (`sftp_paramiko.py` replacing `sftp_stub.py`).
 the `paramiko` extras aren't installed so the test suite stays green on
 Linux dev boxes.
 
+## Batches, Reconciliation, and Activity
+
+These read/write endpoints are the core operator surface for browsing
+the parsed record and acting on matches. They predate the per-SP
+endpoint reference sections in the **Roadmap** and are listed here in
+one place so the route inventory stays discoverable.
+
+| Method | Path                                          | Notes                                                            |
+| ------ | --------------------------------------------- | ---------------------------------------------------------------- |
+| GET    | `/api/batches`                                | All parsed batches, newest first. `?limit=` (1–1000, default 100). |
+| GET    | `/api/batches/{batch_id}`                     | One batch detail (envelope, claims / remits, validation summary). |
+| GET    | `/api/batch-diff?a=<id>&b=<id>`               | Side-by-side diff of two batches: `added` / `removed` / `changed` claims + envelope metadata for each. Both query params required. |
+| GET    | `/api/reconciliation/unmatched`               | `{"claims": [...], "remittances": [...]}` — every Claim with no paired Remittance and vice versa. The two lists are always present (empty list, never absent) so the UI can index unconditionally. |
+| POST   | `/api/reconciliation/match`                   | Body `{claim_id, remit_id}`. Manually pair a claim with a remit. `400` on missing ids, `404` on unknown id, `409` on already-matched or terminal-state claim. |
+| POST   | `/api/reconciliation/unmatch`                 | Body `{claim_id}`. Remove the current match and reset the claim to `submitted`. `404` on unknown id, `409` on no current match. |
+| GET    | `/api/providers`                              | Distinct providers across parsed claims. `?npi=`, `?state=`, `?limit=`, `?offset=`. Distinct from `/api/config/providers/{npi}` (SP9 config table) — this endpoint surfaces providers derived from the parsed claim stream. |
+| GET    | `/api/activity`                               | Recent activity events. `?kind=`, `?since=`, `?limit=` (1–500, default 200). Powers the Activity page; the streaming counterpart `/api/activity/stream` is documented under **Live updates**. |
+
+The per-SP endpoint blocks at the bottom of the **Roadmap** cover the
+SP-specific routes (parse, 999/TA1/277CA, Inbox, claim drawer, line
+reconciliation, outbound 837, multi-payer config, audit log, 277CA,
+key rotation, payer-rejected acknowledge).
+
 ## Persistence
 
 Parsed batches, claims, remittances, matches, 277CA rejections,