Refresh repository documentation

- Rewrite AGENTS and README files to match the current app layout
- Document API routes, trivia UI, and the active panel design language

api/README.md

@@ -1,30 +1,130 @@
-# Aurora Web API
+# Aurora API
 
-The web API provides a REST interface and WebSocket support for accessing Aurora bot data and configuration.
+Aurora's API is a Bun server that runs inside the same process as the Discord bot. It serves REST routes, the authenticated WebSocket endpoint, static assets, and built panel files.
 
-## API Endpoints
+## Runtime model
 
-- `GET /api/stats` - Real-time bot statistics
-- `GET /api/settings` - Bot configuration
-- `GET /api/users` - User data
-- `GET /api/items` - Item catalog
-- `GET /api/quests` - Quest information
-- `GET /api/transactions` - Economy data
-- `GET /api/health` - Health check
+- Entry point: `api/src/server.ts`
+- Route dispatcher: `api/src/routes/index.ts`
+- Auth: Discord OAuth with in-memory session cookies
+- WebSocket: `/ws`
+- Static assets: `/assets/*`
+- Built panel fallback: `panel/dist`
+
+## Access model
+
+Public:
+
+- `GET /api/health`
+- `/auth/discord`
+- `/auth/callback`
+- `POST /auth/logout`
+- `GET /auth/me`
+
+Player-accessible API routes:
+
+- `GET /api/stats`
+- `GET /api/health`
+- `GET /api/me`
+- `GET /api/me/inventory`
+
+Admin-only API routes:
+
+- everything else under `/api/*`
+
+Admin vs player is derived from `ADMIN_USER_IDS`. A user must already exist in the `users` table to complete panel login.
+
+## Route summary
+
+### Auth
+
+- `GET /auth/discord`
+- `GET /auth/callback`
+- `POST /auth/logout`
+- `GET /auth/me`
+
+### Dashboard and system
+
+- `GET /api/health`
+- `GET /api/stats`
+- `GET /api/stats/activity`
+- `POST /api/actions/reload-commands`
+- `POST /api/actions/clear-cache`
+- `POST /api/actions/maintenance-mode`
+
+### Settings
+
+- `GET /api/settings`
+- `POST /api/settings`
+- `GET /api/settings/meta`
+- `GET /api/guilds/:guildId/settings`
+- `PUT|PATCH /api/guilds/:guildId/settings`
+- `DELETE /api/guilds/:guildId/settings`
+
+### Users, classes, and inventory
+
+- `GET /api/me`
+- `GET /api/me/inventory`
+- `GET /api/users`
+- `GET /api/users/:id`
+- `PUT /api/users/:id`
+- `GET /api/users/:id/inventory`
+- `POST /api/users/:id/inventory`
+- `DELETE /api/users/:id/inventory/:itemId`
+- `GET /api/classes`
+- `POST /api/classes`
+- `PUT /api/classes/:id`
+- `DELETE /api/classes/:id`
+
+### Game content
+
+- `GET /api/items`
+- `POST /api/items`
+- `GET /api/items/:id`
+- `PUT /api/items/:id`
+- `DELETE /api/items/:id`
+- `POST /api/items/:id/icon`
+- `GET /api/quests`
+- `POST /api/quests`
+- `PUT /api/quests/:id`
+- `DELETE /api/quests/:id`
+- `GET /api/lootdrops`
+- `POST /api/lootdrops`
+- `DELETE /api/lootdrops/:messageId`
+
+### Moderation and economy history
+
+- `GET /api/moderation`
+- `POST /api/moderation`
+- `GET /api/transactions`
 
 ## WebSocket
 
-Connect to `/ws` for real-time updates:
-- Stats broadcasts every 5 seconds
-- Event notifications via system bus
-- PING/PONG heartbeat support
+`/ws` requires a valid `aurora_session` cookie.
+
+Current behavior:
+
+- dashboard clients subscribe to `dashboard`
+- game clients also use lobby and room-scoped traffic through `GameServer`
+- `PING` from the client returns `PONG`
+- dashboard stats are broadcast every 5 seconds while at least one client is connected
+- hard limits in `api/src/server.ts`:
+  - 200 concurrent connections
+  - 16 KB max payload
+  - 60 second idle timeout
 
 ## Development
 
-The API runs automatically when you start the bot:
+Start the backend:
 
 ```bash
 bun run dev
 ```
 
-The API will be available at `http://localhost:3000`
+Optional panel dev server:
+
+```bash
+bun run panel:dev
+```
+
+Panel dev runs on `http://localhost:5173` and proxies API/auth/assets/WebSocket requests to `http://localhost:3000`.