milestone 27: diagnostics — operational failures land in one curated log, resolved history purgeable

docs/reference/api.md

@@ -4,7 +4,7 @@ nxdns serves its admin API itself, on `web.bind:web.port` (default port 8080), a
 
 The machine-readable contract is `src/web/openapi.yaml`, which the running server hands out unauthenticated at `GET /api/openapi.yaml`. Request and response schemas for every operation live there. When this page and the YAML disagree, the YAML wins.
 
-The route table is `src/web/routes.zig`; the [Operations](#operations) table below carries all 56 of its entries.
+The route table is `src/web/routes.zig`; the [Operations](#operations) table below carries all 60 of its entries.
 
 ## Conventions
 
@@ -109,6 +109,10 @@ Auth `open` means no session is required; `session` means a valid session cookie
 | GET | `/api/stats/timeseries` | session | counted | read | Bucketed counts for a period |
 | GET | `/api/lookup` | session | counted | read | Explain a domain |
 | GET | `/api/upstream/health` | session | counted | read | Upstream pool health |
+| GET | `/api/diagnostics` | session | counted | read | Operational event log |
+| DELETE | `/api/diagnostics` | session | counted | runtime action | Purge every resolved event |
+| GET | `/api/diagnostics/{id}` | session | counted | read | One operational event |
+| DELETE | `/api/diagnostics/{id}` | session | counted | runtime action | Purge one resolved event |
 | GET | `/api/groups` | session | counted | read | List groups |
 | POST | `/api/groups` | session | counted | config write | Create a group |
 | GET | `/api/groups/{id}` | session | counted | read | Read a group |
@@ -156,6 +160,8 @@ Auth `open` means no session is required; `session` means a valid session cookie
 
 There is no `POST /api/clients`: client rows come from DNS activity or import, never from the API.
 
+The two diagnostics deletes purge history only. `DELETE /api/diagnostics/{id}` answers 204 for a resolved event, 409 for one that is still active — an open episode is the current state of the box, not history — and 404 for an id no row holds. `DELETE /api/diagnostics` removes every resolved event and answers `{"purged": N}`, leaving the active ones. Events still resolve on their own; these only decide when the resolved rows go.
+
 Static assets are not routes. The router sends unmatched non-`/api` paths to the embedded SPA before any auth or rate-limit check.
 
 ## Settings keys