docs: document dashboard auth and typed events

docs/api.md

@@ -27,15 +27,22 @@ The RedditBot web dashboard exposes a REST API for monitoring and controlling th
 
 **Content-Type**: `application/json` (except SSE)  
 **Response Format**: JSON  
-**Authentication**: None (local network only)
+**Authentication**: Dashboard session cookie or bearer token
 
 ---
 
 ## Authentication
 
-No authentication is required. The dashboard is intended for local network access only.
+The dashboard, API, SSE streams, and private media require the token configured
+through `WEB_DASHBOARD_TOKEN` (preferred) or `web.authToken`. Interactive users
+exchange the token for an HttpOnly, SameSite=Strict session cookie at
+`POST /auth/session`. API clients may instead send
+`Authorization: Bearer <token>`.
 
-> **Security Note**: If exposing the dashboard externally, add authentication (e.g., basic auth, reverse proxy with auth).
+`GET /auth/login` and `POST /auth/session` are the only unauthenticated
+dashboard routes. A rejected API request returns HTTP 401 with
+`{"error":"Dashboard authentication required"}`. Debug endpoints are absent
+unless `web.debugEnabled` is explicitly enabled.
 
 ---
 
@@ -976,22 +983,34 @@ All error responses follow this format:
 
 ## SSE Events
 
-The SSE log stream (`/api/logs/stream`) emits the following events:
+`GET /api/events/stream` is the typed resumable event stream used by the React
-
+dashboard. Each SSE frame contains `id`, `event`, and `data` fields. The data is
-### `log` Event
+the complete validated event envelope:
-
-Emitted for every log entry.
-
-**Data Format**:
 
 ```json
 {
+  "id": "1786201200000-000000",
+  "occurredAt": "2026-08-08T15:00:00.000Z",
+  "type": "log.created",
+  "payload": {
     "level": "info",
-  "message": "Processed post abc123 from r/gonewild",
+    "message": "Dashboard started"
-  "timestamp": "2024-01-15T10:30:00.000Z"
+  }
 }
 ```
 
+Clients may reconnect with `Last-Event-ID`; the server replays retained events
+after that ID in order. The stream sends heartbeats, bounds buffered events and
+slow-client queues, and requires the same dashboard authentication as the API.
+
+Current event families include bot status, message sent or failed,
+conversation updated, reply received, sync lifecycle and progress, rate-limit
+state, Reddit session state, and logs.
+
+`GET /api/logs/stream` remains temporarily available for the legacy dashboard.
+Its untyped `connected`, `log`, and `sync-progress` frames should not be used by
+new clients.
+
 **Log Levels**:
 
 | Level | Description |