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

@@ -1,11 +1,22 @@
-# Trivia Module
+# Trivia module
 
-- Trivia is an **economic sink**: the entry fee is deducted immediately when starting, before the question is fetched. If the API call fails after payment, the user loses the fee. This is by design (prevents free retries).
-- Questions come from the **OpenTDB API** with base64 encoding to avoid HTML entity issues. The service decodes all fields from base64 before returning.
-- Sessions are in-memory (`Map` keyed by `userId_timestamp`). Lost on restart. Expired sessions are cleaned up every 30 seconds.
-- The cooldown is set **at session start**, not on answer submission. This means a user is on cooldown even if they never answer.
-- Answer correctness (`isCorrect`) is determined by the **caller** (interaction handler), not the service. The `submitAnswer` method trusts the `isCorrect` boolean. The session stores `correctIndex` for the UI layer to compare.
-- Reward calculation: `potentialReward = entryFee * rewardMultiplier`. The multiplier comes from config. Wrong answers get 0 (the entry fee is already gone).
-- Unlike most services, `TriviaService` is a **class instance** (not a plain object). This is because it needs constructor logic for the cleanup interval. The singleton is exported as `triviaService`.
-- The reward payment in `submitAnswer` reads the current balance and sets it directly (not using `sql` addition). This is a potential race condition under extreme concurrency but acceptable given the per-user cooldown.
-- Session is deleted before processing the reward to prevent double-submit, even if the reward transaction fails.
+## Model
+
+- `triviaService` is a class-backed singleton
+- active sessions live in memory
+- expired sessions are cleaned every 30 seconds
+
+## Flow
+
+1. `canPlayTrivia()` checks the cooldown timer.
+2. `startTrivia()` deducts the entry fee, fetches a question from OpenTDB, creates the session, and sets the cooldown.
+3. The bot view layer renders answer buttons using the stored shuffled answers and `correctIndex`.
+4. `submitAnswer()` removes the session and pays the reward only if the caller says the answer was correct.
+
+## Notes
+
+- questions are fetched from OpenTDB with `encode=base64` and decoded server-side
+- entry fee is deducted before the question fetch completes
+- cooldown is applied when the session starts, not when the answer is submitted
+- `submitAnswer()` trusts the caller's `isCorrect` boolean
+- reward payment currently reads and writes the balance directly inside the transaction instead of using `modifyUserBalance()`