From bbf89c9dd83868b158bc068515e9929e2fea5354 Mon Sep 17 00:00:00 2001
From: Tyler <tyler@crispygoat.com>
Date: Sun, 21 Jun 2026 02:07:27 -0600
Subject: [PATCH] docs: add Batches, Reconciliation, and Activity endpoint
 reference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README's SP-specific endpoint reference blocks (SP3-SP15 in the
Roadmap) cover the per-SP additions, but the pre-existing core operator
surface was never documented as a single block. This pass adds the
missing endpoints:

- GET /api/batches, GET /api/batches/{batch_id} — batch list + detail.
- GET /api/batch-diff?a=<id>&b=<id> — side-by-side diff between two
  batches (added/removed/changed claims + envelope metadata).
- GET /api/reconciliation/unmatched — every claim with no paired
  remit and every remit with no paired claim; powers the
  reconciliation review UI.
- POST /api/reconciliation/match — manual pair (claim_id, remit_id);
  400/404/409 contract.
- POST /api/reconciliation/unmatch — remove a match and reset the
  claim to 'submitted'.
- GET /api/providers — distinct providers from the parsed claim
  stream. Distinct from /api/config/providers/{npi} (the SP9 config
  table endpoint).
- GET /api/activity — recent activity events. Powers the Activity
  page; the streaming counterpart /api/activity/stream is already
  documented under 'Live updates'.

These 7 routes are referenced by the UI (BatchesList, BatchDetail,
BatchDiffView, Reconciliation page, Providers page, Activity page) but
were missing from the README's route inventory. The new section sits
between 'SFTP Wire-Up' and 'Persistence', with a one-paragraph pointer
to the per-SP endpoint reference blocks for SP-specific routes.

No code changes. No tests touched.
---
 README.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/README.md b/README.md
index a456b8f..e410d76 100644
--- a/README.md
+++ b/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,