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/leveling/AGENTS.md

@@ -1,9 +1,26 @@
-# Leveling Module
+# Leveling module
 
-- **Level is derived, not stored.** Total XP is the source of truth. `getLevelFromXp()` recalculates level from cumulative XP on every `addXp()` call. Levels are monotonic — they never decrease.
-- XP curve is a power law: `xpForLevel(n) = floor(base * n^exponent)` where defaults are `base: 100`, `exponent: 1.5`. Config comes from `gameSettingsService` (30s cache TTL).
-- Chat XP (`processChatXp()`) awards random XP between `minXp` (5) and `maxXp` (15) per message, gated by a 60-second per-user cooldown (`TimerType.COOLDOWN`, key `TimerKey.CHAT_XP`). The cooldown is upserted atomically.
-- Quest/reward XP uses `addXp()` directly — it bypasses the chat cooldown.
-- XP boost multipliers come from active `TimerType.EFFECT` timers with key `'xp_boost'` (metadata field: `multiplier`).
-- All XP values are `bigint` in the DB but converted to `Number` for arithmetic. Watch for overflow at extremely high XP values.
-- `addXp()` and `processChatXp()` run inside transactions. They emit `XP_GAINED` (fire-and-forget) which the quest system listens to — the weight equals the XP amount.
+## Model
+
+- total XP is the source of truth
+- level is derived from XP on each award
+- XP curve is driven by `config.leveling.base` and `config.leveling.exponent`
+
+## Main methods
+
+- `getXpToReachLevel(level)`
+- `getLevelFromXp(totalXp)`
+- `getXpForNextLevel(currentLevel)`
+- `addXp(userId, amount)`
+- `processChatXp(userId)`
+
+## Chat XP
+
+- gated by a `user_timers` cooldown on `TimerKey.CHAT_XP`
+- base award is random between `config.leveling.chat.minXp` and `maxXp`
+- active XP boost timers can multiply the award
+
+## Notes
+
+- `addXp()` emits `XP_GAINED` for quest progression
+- the level curve currently converts `bigint` XP to `number` for the math loop, so extremely large totals would be the stress point to watch