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

@@ -1,11 +1,37 @@
-# Inventory Module
+# Inventory module
 
-- Inventory has two hard limits from config: **max slots** (distinct item types) and **max stack size** (quantity per item). Both are enforced in `addItem` and will throw `UserError` if exceeded.
-- When quantity reaches 0, the inventory row is **deleted** (not kept with quantity 0). This means slot count = row count.
-- `buyItem` delegates balance deduction to `economyService.modifyUserBalance` within the same transaction to ensure atomicity. Never deduct balance directly when purchasing.
-- Item usage is driven by a JSON `usageData` field on the item record. Items without `usageData.effects` cannot be used. The `consume` flag in `usageData` controls whether the item is removed after use.
-- **Effect system**: effects are validated at runtime via Zod (`EffectPayloadSchema`) before execution. The registry maps effect type strings to handler functions. Adding a new effect type requires: (1) add to `EffectType` enum in constants, (2) add Zod schema variant in `effect.types.ts`, (3) add handler in `effect.handlers.ts`, (4) register in `effect.registry.ts`.
-- `XP_BOOST` and `TEMP_ROLE` effects use `userTimers` with upsert -- activating while already active **replaces** the timer (does not stack or extend).
-- `TEMP_ROLE` only records the timer in DB; actual Discord role assignment must happen in the bot command layer.
-- `LOOTBOX` effect uses weighted random selection. Weights are relative, not percentages. A `NOTHING` loot type is valid and intentional.
-- The `getAutocompleteItems` method filters to only show items that have usable effects, so non-usable items won't appear in the `/use` autocomplete.
+## Main methods
+
+- `addItem()`
+- `removeItem()`
+- `getInventory()`
+- `buyItem()`
+- `getItem()`
+- `useItem()`
+- `getAutocompleteItems()`
+
+## Rules
+
+- max slots and max stack size come from runtime config
+- removing the last quantity deletes the inventory row
+- `buyItem()` uses `economyService.modifyUserBalance()` and `addItem()` in one transaction
+
+## Item usage
+
+- item behavior is driven by `items.usageData`
+- items without `usageData.effects` are not usable
+- `usageData.consume` controls whether the item is removed after use
+- effect execution is routed through `effect.registry.ts`
+
+To add a new effect type, update:
+
+- `shared/lib/constants.ts`
+- `effect.types.ts`
+- `effect.handlers.ts`
+- `effect.registry.ts`
+
+## Notes
+
+- XP boost and temp-role effects are timer-based and overwrite existing timers rather than stacking
+- temp-role effects only write timer data; actual Discord role assignment is handled outside this service
+- autocomplete only returns usable items