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

shared/modules/guild-settings/AGENTS.md

@@ -1,10 +1,32 @@
-# Guild Settings Module
+# Guild settings module
 
-- `updateSetting()` uses a hardcoded `keyMap` to map friendly key names to DB columns. Use exact key names (e.g., `"studentRole"` not `"studentRoleId"`). Unknown keys throw `UserError`.
-- Type coercion per column: Discord IDs → BigInt automatically; `colorRoleIds` must be array; `featureOverrides` must be object; `moderationDmOnWarn` must be boolean; `moderationAutoTimeoutThreshold` must be number. Null values set columns to NULL.
-- **Caching:** `getGuildConfig()` (in `shared/lib/config.ts`) caches transformed settings for 60 seconds. Every mutation (`upsertSettings`, `updateSetting`, `addColorRole`, `removeColorRole`) calls `invalidateGuildConfigCache(guildId)` immediately.
-- If settings don't exist for a guild, the cache returns safe defaults — no errors thrown.
-- `featureOverrides` is a sparse `Record<string, boolean>` — no keys are predefined. Consumers must check key existence.
-- **No Discord validation:** The service does not verify that role/channel IDs actually exist in Discord. Invalid IDs are stored silently.
-- `addColorRole()` / `removeColorRole()` fetch the full settings, mutate the array in JS, then upsert — this is not atomic and can race under concurrent requests.
-- `terminalMessageId` and `terminalChannelId` are separate DB columns but grouped as `terminal: { channelId, messageId }` in the cached config. Setting one without the other can create orphaned data.
+## Responsibilities
+
+- store raw per-guild settings in `guild_settings`
+- convert DB rows to string-friendly objects for the API
+- support the cached runtime view returned by `shared/lib/config.ts`
+
+## Main methods
+
+- `getSettings(guildId)`
+- `upsertSettings({ guildId, ...fields })`
+- `updateSetting(guildId, key, value)`
+- `deleteSettings(guildId)`
+- `addColorRole(guildId, roleId)`
+- `removeColorRole(guildId, roleId)`
+
+## Runtime cache
+
+- `shared/lib/config.ts` caches `getGuildConfig()` results for 60 seconds
+- API writes invalidate that cache immediately
+- the cached runtime shape is not identical to the DB shape:
+  - `studentRoleId` -> `studentRole`
+  - `visitorRoleId` -> `visitorRole`
+  - `colorRoleIds` -> `colorRoles`
+  - terminal fields are grouped under `terminal`
+
+## Notes
+
+- `updateSetting()` accepts friendly keys like `studentRole`, `welcomeChannel`, and `terminalMessage`
+- Discord IDs are stored as `bigint` in the DB and exposed as strings from the service
+- `addColorRole()` and `removeColorRole()` read-modify-write the whole array, so they are not atomic under concurrent updates