docs: rename CLAUDE.md to AGENTS.md across the project

api/src/AGENTS.md

@@ -0,0 +1,31 @@
+# API Layer
+
+## Server
+- Bun's native `serve()` API — no Express/Fastify. Custom `handleRequest()` dispatcher with pathname prefix matching.
+- Route modules export `{ name: string, handler: RouteHandler }`. Handlers return `null` for non-matching paths.
+
+## Authentication
+- Discord OAuth2 with session cookies (`aurora_session`, HttpOnly, 7-day TTL).
+- In-memory session store — sessions lost on restart.
+- Role-based: `admin` vs `player` (admins set via `ADMIN_USER_IDS` env var).
+- Non-enrolled users (not in DB) get 403 even with valid Discord auth.
+- Call `getSession(req)` for all protected routes.
+
+## Response Conventions
+- Success: `jsonResponse(data, status)` — uses custom BigInt-safe JSON replacer.
+- Error: `errorResponse(message, status, details?)` → `{ error, details? }`
+- Validation: `validationErrorResponse(zodError)` → `{ error: "Invalid payload", issues: [...] }`
+- Zod schemas centralized in `schemas.ts`.
+
+## WebSocket
+- Upgrade via `/ws` endpoint (requires auth).
+- Pub/sub via Bun's `.publish()` / `.subscribe()` on channels: `dashboard`, `lobby`, `room:${roomId}`.
+- Dashboard stats broadcast every 5 seconds. Game events are room-scoped.
+- Hard limit: 200 concurrent WS connections (429 rejection), 16KB max payload, 60s idle timeout.
+- Fire-and-forget broadcasts — no ack mechanism.
+
+## Gotchas
+- All DB IDs are BigInt — JSON responses must use the custom `jsonReplacer`.
+- No rate limiting on HTTP routes.
+- Some routes accept multipart form data (e.g., item icon upload) — manual parsing, not abstracted.
+- Asset directories resolve relative to `import.meta.dir`.