1 files changed, 14 insertions, 0 deletions

diff --git a/CONTEXT.md b/CONTEXT.md
index f39bb31..e272a7a 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -18,3 +18,17 @@ holds no implementation decisions or specs (those live in `docs/adr/`).
 - **Flush** — the `/record` action: snapshot the current recording buffer to an
   mp3 and upload it to Copyparty. Non-destructive — the buffer keeps recording
   after a flush, so successive calls may overlap.
+
+## Stats & Leaderboard
+
+- **User stats** — cumulative per-user counters (message count, total voice
+  active time, total voice AFK time) stored in the `user_stats` table. Persists
+  across restarts. Distinct from *voice activity* which is session-scoped.
+- **Voice activity** (session) — per-session timing metadata (join time, current
+  active/AFK durations, is_afk flag). Resets when user joins VC. Used for
+  real-time status, not leaderboard rankings.
+- **Leaderboard** — `/leaderboard` command group showing ranked user stats.
+  Metrics: `messages`, `active` (voice), `afk` (voice), `total` (voice active +
+  afk). Paged at 10 entries, descending by default.
+- **Tracked guild** — the guild containing `status_channel_id`. Message counts
+  are only tracked in this guild.