docs: comprehensive API documentation from source code

Replace existing docs with fresh documentation built entirely from source
code analysis. OpenAPI 3.1 spec as source of truth, plus human-readable
Markdown with curl examples, response samples, and workflow guides.

- OpenAPI 3.1 spec covering all 42 endpoints (validated against source)
- 7 endpoint reference docs (auth, games, sessions, picker, stats, votes, webhooks)
- WebSocket protocol documentation (auth, subscriptions, 4 event types)
- 4 guide documents (getting started, session lifecycle, voting, webhooks)
- API README with overview, auth docs, and quick reference table
- Old docs archived to docs/archive/

Made-with: Cursor

docs/api/endpoints/auth.md

@@ -0,0 +1,135 @@
+# Auth Endpoints
+
+Simple admin-key authentication. Single role (admin). No user management. Obtain a JWT from `POST /api/auth/login` and use it as a Bearer token for protected endpoints.
+
+## Endpoint Summary
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/api/auth/login` | No | Exchange admin key for JWT |
+| POST | `/api/auth/verify` | Bearer | Validate token and return user info |
+
+---
+
+## POST /api/auth/login
+
+Exchange an admin key for a JWT. Use the returned token in the `Authorization: Bearer <token>` header for protected routes. Tokens expire after 24 hours.
+
+### Authentication
+
+None. This endpoint is public.
+
+### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| key | string | Yes | Admin key (configured via `ADMIN_KEY` env) |
+
+```json
+{
+  "key": "your-admin-key"
+}
+```
+
+### Response
+
+**200 OK**
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "message": "Authentication successful",
+  "expiresIn": "24h"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| token | JWT to use in `Authorization: Bearer <token>` |
+| message | Success message |
+| expiresIn | Token lifetime |
+
+### Error Responses
+
+| Status | Body | When |
+|--------|------|------|
+| 400 | `{ "error": "Admin key is required" }` | `key` field missing |
+| 401 | `{ "error": "Invalid admin key" }` | Wrong key |
+
+### Example
+
+```bash
+curl -X POST http://localhost:5000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"key": "your-admin-key"}'
+```
+
+**Sample response:**
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJ0aW1lc3RhbXAiOjE3MTAwMDAwMDAwLCJpYXQiOjE3MTAwMDAwMDB9.abc123",
+  "message": "Authentication successful",
+  "expiresIn": "24h"
+}
+```
+
+---
+
+## POST /api/auth/verify
+
+Verify that the provided Bearer token is valid and return the decoded user payload.
+
+### Authentication
+
+Bearer token required. Include in header: `Authorization: Bearer <token>`.
+
+### Parameters
+
+None.
+
+### Response
+
+**200 OK**
+
+```json
+{
+  "valid": true,
+  "user": {
+    "role": "admin",
+    "timestamp": 1710000000000
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| valid | Always `true` when token is valid |
+| user.role | User role (always `"admin"`) |
+| user.timestamp | Unix ms when token was issued |
+
+### Error Responses
+
+| Status | Body | When |
+|--------|------|------|
+| 401 | `{ "error": "Access token required" }` | No `Authorization` header or Bearer token |
+| 403 | `{ "error": "Invalid or expired token" }` | Bad or expired token |
+
+### Example
+
+```bash
+curl -X POST http://localhost:5000/api/auth/verify \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+**Sample response:**
+
+```json
+{
+  "valid": true,
+  "user": {
+    "role": "admin",
+    "timestamp": 1710000000000
+  }
+}
+```