docs: add dashboard and announce API documentation

Made-with: Cursor

docs/api.md

@@ -177,6 +177,35 @@ Returns a specific show by internal database ID.
 
 ---
 
+## Dashboard Endpoints
+
+These routes are only available when the dashboard is enabled (all three `NTR_WEB_*` env vars set).
+
+### `GET /login`
+
+Serves the login page.
+
+### `POST /login`
+
+Authenticates with username and password. Sets a session cookie on success, redirects to `/dashboard`.
+
+**Form Data**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `username` | string | Dashboard username |
+| `password` | string | Dashboard password |
+
+### `GET /logout`
+
+Clears the session cookie and redirects to `/login`.
+
+### `GET /dashboard`
+
+Serves the playlist dashboard page. Requires a valid session cookie (redirects to `/login` if absent).
+
+---
+
 ## Admin Endpoints
 
 All admin endpoints require a bearer token via the `Authorization` header:
@@ -308,6 +337,37 @@ Move a track to a new position within the current week's show.
 
 ---
 
+### `POST /admin/announce`
+
+Broadcasts a track announcement to all connected WebSocket subscribers (IRC bots). The announcement is formatted as: `Now Playing: Song #N: Title by Artist - URL`.
+
+Accepts either a bearer token OR a valid session cookie.
+
+**Request Body**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `show_id` | integer | yes | Show database ID |
+| `position` | integer | yes | Track position in the show |
+
+**Response**
+
+```json
+{
+  "status": "announced",
+  "message": "Now Playing: Song #1: Night Drive by SomeArtist - https://soundcloud.com/..."
+}
+```
+
+**Errors**
+
+| Status | Detail |
+|--------|--------|
+| 401 | `"Unauthorized"` |
+| 404 | `"No track at position {n}"` |
+
+---
+
 ## Track Object
 
 Returned inside playlist and show detail responses.
@@ -338,3 +398,47 @@ All timestamps in API responses are UTC. The boundary shifts by 1 hour across DS
 |--------|---------|--------------|
 | EST (Nov -- Mar) | Wed 22:00 | Thu 03:00 |
 | EDT (Mar -- Nov) | Wed 22:00 | Thu 02:00 |
+
+---
+
+## WebSocket
+
+### `WS /ws/announce`
+
+WebSocket endpoint for receiving announce broadcasts. Used by IRC bot plugins.
+
+**Authentication**
+
+After connecting, send a subscribe message:
+
+```json
+{"type": "subscribe", "token": "<NTR_ADMIN_TOKEN>"}
+```
+
+Invalid token closes the connection with code `4001`.
+
+**Messages from server**
+
+Announce broadcast:
+```json
+{"type": "announce", "message": "Now Playing: Song #1: Title by Artist - URL"}
+```
+
+Status update (sent on subscriber connect/disconnect):
+```json
+{"type": "status", "subscribers": 2}
+```
+
+---
+
+## Dashboard Configuration
+
+The web dashboard is optional. Enable it by setting all three environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NTR_WEB_USER` | *(required)* | Dashboard login username |
+| `NTR_WEB_PASSWORD` | *(required)* | Dashboard login password |
+| `NTR_SECRET_KEY` | *(required)* | Secret key for session cookie signing |
+
+If any of these are absent, dashboard routes are not mounted and the API works exactly as before.