# GogoBee

Matrix community bot with E2EE, 50 plugins, passive tracking, scheduled posts, and optional LLM features.

Written in Go using [mautrix-go](https://github.com/mautrix/go) for encryption and [modernc.org/sqlite](https://modernc.org/sqlite) for storage.

---

## Table of Contents

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Running the Bot](#running-the-bot)
- [Commands](#commands)
- [Passive Features](#passive-features)
- [Scheduled Posts](#scheduled-posts)
- [Achievements](#achievements)
- [Personality Archetypes](#personality-archetypes)
- [External APIs](#external-apis)
- [Architecture](#architecture)
- [Database](#database)
- [Troubleshooting](#troubleshooting)

---

## Features

- **E2EE that actually works** - mautrix-go with goolm (pure Go). Crypto state lives in SQLite so device keys survive restarts. Cross-signing bootstraps on first run — the bot self-verifies its own device.
- **No CGo, no system deps** - builds to a single static binary. Cross-compile to whatever you want.
- **50 plugins** with dependency injection and ordered registration
- **Games & economy** - Euro virtual currency, Hangman (collaborative, threaded, tiered scoring, multilingual clue mode via DreamDict, difficulty tier display), Blackjack (1-4 players, auto-play timeout), UNO (solo vs bot or 2–4 player multiplayer via DMs, with optional No Mercy mode), Texas Hold'em (2-9 players, CFR-trained NPC bot, DM-based gameplay with Ollama coaching tips, 1-hour idle auto-close with 45-min warning), Wordle (daily cooperative, DreamDict-powered, 5-20 letter words, guess persistence across restarts, midnight expiry announcements, video game themed bonus words with category hints, dupe prevention across last 500 puzzles, earnings tracked in stats), Adventure (daily idle RPG via DMs — dungeon, mine, forage, fish, shop, or rest with TwinBee NPC distributing level-scaled rewards, mid-day random events, tier shorthand buying, holiday double actions, hospital revival system, Robbie the Friendly Bandit automated inventory cleaner), Arena (5-tier combat gauntlet with 20 unique monsters, risk-reward cashout system, death lockout, leaderboard), Co-op Dungeons (2–7 day party runs with funding tiers, TwinBee-narrated floor events with voting, spectator parimutuel betting, basket/mimic gift system, weighted-roll item distribution including masterworks at T4–T5), all with channel restriction
- **Moderation system** (optional) - deterministic detection only, no LLM. Word list with leetspeak variation matching, text/image flood, repeated messages, mention flooding, link rate limiting, invite flooding, join/leave cycling. Three-strike ladder (warn → mute → ban). Admin room notifications, DMs over public callouts.
- **Passive tracking** - XP, stats, streaks, achievements, markov corpus, keyword alerts, all running silently
- **Scheduled posts** via [robfig/cron](https://github.com/robfig/cron) - Palavra do Dia (Portuguese WOTD with en/fr translations and etymology), holidays, game releases, birthdays, anime/movie releases, concert digests, esteemed members
- **LLM integration** (optional) - Ollama-powered sentiment analysis, roast profiles, room vibes, tarot readings, conversation summaries
- **Markdown rendering** - auto-detects `**bold**`, `_italic_`, and `` `code` `` in messages and sends proper HTML to Matrix clients
- **Encrypted quote wall** - AES-256-GCM encrypted quotes at rest, reply-to-save, search, leaderboard
- **Space groups** - automatic room grouping via membership overlap. Leaderboards, stats, and trivia scores span all rooms in a group. No Matrix Spaces API needed — the bot infers community boundaries from shared members.
- **SQLite everything** - one file, no external database needed

---

## Requirements

- Go 1.22+
- A Matrix homeserver account for the bot

Optional:
- [Ollama](https://ollama.ai) for LLM features
- API keys for various services (see [Configuration](#configuration))

---

## Installation

### From Source

```bash
git clone https://github.com/prosolis/gogobee.git
cd gogobee
cp .env.example .env   # edit with your settings
go build -tags goolm -o gogobee .
./gogobee
```

### Docker

```bash
docker build -t gogobee .
docker run --env-file .env -v ./data:/app/data gogobee
```

### Docker Compose

```bash
docker compose up -d
```

---

## Configuration

Everything is configured through environment variables or a `.env` file.

### Required

| Variable | Description |
|----------|-------------|
| `HOMESERVER_URL` | Matrix homeserver URL, e.g. `https://matrix.org` |
| `BOT_USER_ID` | Bot's Matrix user ID, e.g. `@gogobee:matrix.org` |
| `BOT_PASSWORD` | Bot's Matrix password |

### Core (optional)

| Variable | Default | Description |
|----------|---------|-------------|
| `DATA_DIR` | `./data` | Where the database and device files live |
| `BOT_DISPLAY_NAME` | `GogoBee` | Display name |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error` |
| `ADMIN_USERS` | | Comma-separated admin user IDs |
| `BROADCAST_ROOMS` | | Comma-separated room IDs for scheduled posts |

### API Keys (optional)

| Variable | Service | Used By |
|----------|---------|---------|
| `RAWG_API_KEY` | [RAWG](https://rawg.io/apidocs) | `!game`, `!retro`, `!releases` |
| `DREAMDICT_URL` | DreamDict (self-hosted) | `!translate`, `!wotd`, `!antonym`, `!pronounce`, `!etymology`, `!difficulty`, `!rhyme`, `!define` (antonyms), Hangman (multilingual clues + difficulty tier), Wordle (word selection + guess validation + definitions) |
| `CALENDARIFIC_API_KEY` | [Calendarific](https://calendarific.com) | Holiday posts |
| `OPENWEATHER_API_KEY` | [OpenWeather](https://openweathermap.org/api) | `!weather` |
| `FINNHUB_API_KEY` | [Finnhub](https://finnhub.io) | `!stock` |
| `BANDSINTOWN_API_KEY` | [Bandsintown](https://artists.bandsintown.com) | `!concerts` |
| `TMDB_API_KEY` | [TMDB](https://www.themoviedb.org/documentation/api) | `!movie`, `!tv`, `!upcoming` |
| `SERPAPI_KEY` | [SerpAPI](https://serpapi.com) | Esteemed member image fetching |

### Services (optional)

| Variable | Description |
|----------|-------------|
| `OLLAMA_HOST` | Ollama server URL, e.g. `http://localhost:11434` |
| `OLLAMA_MODEL` | Model name, e.g. `llama3.2` |
| `DREAMDICT_URL` | DreamDict instance for `!translate`, `!wotd`, dictionary commands, Hangman clues, Wordle words (e.g. `http://127.0.0.1:7777`) |
| `LLM_SAMPLE_RATE` | Fraction of messages to classify (0.0–1.0, default `0.15`) |

### Encryption

| Variable | Description |
|----------|-------------|
| `QUOTE_ENCRYPTION_KEY` | Base64-encoded 32-byte AES-256 key for encrypted quote storage and Markov corpus. Generate with `openssl rand -base64 32`. If unset, `!quote` and `!markov` are disabled. |

### Miniflux RSS (optional)

| Variable | Default | Description |
|----------|---------|-------------|
| `MINIFLUX_URL` | | Miniflux instance URL, e.g. `https://rss.example.com` |
| `MINIFLUX_API_KEY` | | Miniflux API key (Settings → API Keys) |
| `MINIFLUX_POLL_INTERVAL` | `15` | Minutes between polls |
| `MINIFLUX_DEFAULT_ROOM` | `BROADCAST_ROOMS` | Default room for posts |
| `MINIFLUX_MAX_PER_POLL` | `5` | Max entries per feed per poll cycle |

### Feature Flags

| Variable | Description |
|----------|-------------|
| `FEATURE_URL_PREVIEW` | Set to anything to enable automatic URL previews |
| `FEATURE_SHADE` | Set to anything to enable the shade plugin (stub) |
| `FEATURE_TRIVIA` | Set to `false` to disable trivia (default: enabled) |
| `FEATURE_ESTEEMED` | Set to anything to enable satirical esteemed member posts |
| `ESTEEMED_ROOM` | Room ID for esteemed member posts (separate from broadcast rooms) |
| `FEATURE_MODERATION` | Set to `true` to enable the moderation system (disabled by default) |
| `FEATURE_MARKET` | Set to `true` to enable the market overview plugin |
| `MARKET_BROADCAST_SUMMARY` | Set to `true` to auto-post daily market summary to broadcast rooms |
| `DISABLE_WOTD_POST` | Set to `true` to suppress daily WOTD auto-post (the `!wotd` command and passive WOTD usage tracking still work) |

### Games & Economy

| Variable | Default | Description |
|----------|---------|-------------|
| `GAMES_ROOM` | | Room ID where game commands work (trivia, hangman, blackjack, holdem, wordle, flip) |
| `EURO_COOLDOWN_SECONDS` | `30` | Cooldown between passive euro earning per user |
| `EURO_DEBT_REMINDER` | `true` | Weekly DM reminder if player is in debt |
| `EURO_STARTING_CAP` | `2500` | Max starting balance seeded from corpus |
| `HANGMAN_MAX_WRONG_GUESSES` | `6` | Lives before game over |
| `HANGMAN_SOLUTION_BONUS_MULTIPLIER` | `2` | Bonus multiplier for early solution |
| `HANGMAN_PHRASE_FILE` | | Path to newline-delimited phrase file |
| `BLACKJACK_TIMEOUT_SECONDS` | `60` | Auto-play timeout per turn |
| `BLACKJACK_AUTOPLAY_THRESHOLD` | `15` | Stand at or above, hit below |
| `BLACKJACK_MIN_BET` | `1` | Minimum bet in euros |
| `BLACKJACK_MAX_BET` | `500` | Maximum bet per hand |
| `BLACKJACK_DEBT_LIMIT` | `1000` | Maximum debt before betting disabled |
| `UNO_MIN_BET` | `10` | Minimum wager in euros (solo) |
| `UNO_POT_TAUNT_THRESHOLD` | `500` | Pot size at which GogoBee starts taunting |
| `UNO_MULTI_MIN_BET` | `25` | Minimum ante for multiplayer UNO |
| `UNO_MULTI_MAX_BET` | `500` | Maximum ante for multiplayer UNO |
| `UNO_MULTI_LOBBY_TIMEOUT` | `300` | Lobby expiry in seconds |
| `UNO_MULTI_TURN_TIMEOUT` | `30` | Auto-play timeout in seconds |
| `UNO_MULTI_MAX_AUTOPLAY` | `3` | Consecutive auto-plays before forfeit |
| `HOLDEM_SMALL_BLIND` | `10` | Small blind amount |
| `HOLDEM_BIG_BLIND` | `20` | Big blind amount |
| `HOLDEM_MIN_BUYIN` | `200` | Minimum balance to join |
| `HOLDEM_MAX_BUYIN` | `2000` | Maximum stack at buy-in |
| `HOLDEM_TIMEOUT_SECONDS` | `90` | Action timeout per turn |
| `HOLDEM_NPC_NAME` | `TwinBee` | NPC bot display name |
| `HOLDEM_NPC_HOUSE_BALANCE` | `10000` | NPC starting bankroll |
| `HOLDEM_CFR_POLICY` | `data/policy.gob` | Path to CFR policy file |
| `WORDLE_DEFAULT_LENGTH` | `5` | Default word length (5-20) |
| `ADVENTURE_MORNING_HOUR` | `8` | Hour (UTC) to send morning DMs with daily choices |
| `ADVENTURE_SUMMARY_HOUR` | `20` | Hour (UTC) to post daily summary to games room |

### Moderation

All moderation settings are optional. The system is disabled unless `FEATURE_MODERATION=true`.

| Variable | Default | Description |
|----------|---------|-------------|
| `MOD_WORDLIST` | | Path to newline-delimited prohibited word list |
| `MOD_WORDLIST_VARIATIONS` | `true` | Check leetspeak/spaced variants |
| `MOD_STRIKE_EXPIRY_DAYS` | `30` | Days before strikes expire |
| `MOD_MUTE_DURATION_MINUTES` | `60` | Temp mute duration on strike 2 |
| `MOD_MAX_STRIKES` | `3` | Strikes before permanent ban |
| `MOD_FLOOD_MESSAGE_COUNT` | `5` | Messages in window = flood |
| `MOD_FLOOD_MESSAGE_WINDOW_SECONDS` | `10` | Text flood window |
| `MOD_FLOOD_IMAGE_COUNT` | `3` | Images/files in window = flood |
| `MOD_FLOOD_IMAGE_WINDOW_SECONDS` | `30` | Image flood window |
| `MOD_MAX_MESSAGE_LENGTH` | `2000` | Max chars per message (0 = disabled) |
| `MOD_REPEAT_COUNT` | `3` | Repeated messages before strike |
| `MOD_REPEAT_WINDOW_SECONDS` | `60` | Repeat detection window |
| `MOD_REPEAT_SIMILARITY_THRESHOLD` | `0.85` | How similar counts as "same" (0.0–1.0) |
| `MOD_MENTION_MAX` | `5` | Max unique @mentions per message |
| `MOD_MENTION_FLOOD_COUNT` | `3` | Mention-heavy messages in window |
| `MOD_MENTION_FLOOD_WINDOW_SECONDS` | `30` | Mention flood window |
| `MOD_LINK_RATE_NEW_MEMBER` | `3` | Max links per window (new members only) |
| `MOD_LINK_RATE_WINDOW_SECONDS` | `60` | Link rate window |
| `MOD_INVITE_MAX_PER_HOUR` | `5` | Max room invites per user per hour |
| `MOD_JOIN_LEAVE_COUNT` | `3` | Join/leave cycles before flag |
| `MOD_JOIN_LEAVE_WINDOW_MINUTES` | `10` | Join/leave window |
| `MOD_NEW_MEMBER_DAYS` | `14` | Days before a member is no longer "new" |
| `MOD_NEW_MEMBER_FLOOD_MULTIPLIER` | `0.5` | Multiply flood thresholds for new members |
| `MOD_ADMIN_ROOM` | | Dedicated room for mod notifications |
| `MOD_DM_ON_ACTION` | `true` | DM users when action is taken |

### Space Groups

| Variable | Default | Description |
|----------|---------|-------------|
| `SPACE_GROUP_THRESHOLD` | `50` | Percentage of the smaller room's members that must overlap to group rooms together (1–100) |
| `HOLIDAY_COUNTRIES` | `US` | Comma-separated ISO country codes for Calendarific holiday posts |

### Missing Members

| Variable | Default | Description |
|----------|---------|-------------|
| `MISSING_THRESHOLD_DAYS` | `14` | Days of inactivity before considered missing |
| `MISSING_MAX_DAYS` | `90` | Days after which they're considered gone, not missing |
| `MISSING_MIN_MESSAGES` | `10` | Minimum lifetime messages to be eligible |
| `MISSING_EXCLUDE_USERS` | | Comma-separated user IDs to never list as missing |

### Rate Limits

| Variable | Default | Description |
|----------|---------|-------------|
| `RATELIMIT_WEATHER` | `5` | Daily weather lookups per user |
| `RATELIMIT_CONCERTS` | `10` | Daily concert searches per user |

---

## Running the Bot

```bash
# dev
go run -tags goolm .

# prod
go build -tags goolm -o gogobee .
./gogobee
```

The `-tags goolm` flag selects the pure-Go crypto implementation. No C compiler or libolm needed.

### First Run

1. Start the bot. It logs in, creates a device, bootstraps cross-signing, and self-verifies automatically.
2. That's it. E2EE works across restarts from here on out.

---

## Commands

### XP & Leveling
| Command | Description |
|---------|-------------|
| `!rank` | Your level, XP, and progress |
| `!leaderboard` | Top 10 by XP |

### Reputation
| Command | Description |
|---------|-------------|
| `!rep [@user]` | Reputation count |
| `!repboard` | Top 10 by rep |

Rep is earned when someone thanks you. The bot detects this automatically.

### Stats & Personality
| Command | Description |
|---------|-------------|
| `!stats [@user]` | Message statistics (includes Wordle and UNO earnings) |
| `!superstatsexplusalpha [@user]` | Comprehensive profile: economy, games W/L, adventure levels, achievements, and more |
| `!rankings [category]` | Rankings by words, links, questions, or emojis |
| `!personality` | Your community archetype |

### Streaks
| Command | Description |
|---------|-------------|
| `!streak` | Current and longest streak |
| `!firstboard` | Top first-posters-of-the-day |

### Trivia
| Command | Description |
|---------|-------------|
| `!trivia [category] [difficulty]` | Start a question |
| `!trivia scores` | Room leaderboard |
| `!trivia categories` | List categories |
| `!trivia fastest` | Fastest answers |
| `!trivia stop` | End current question |

### Economy
| Command | Description |
|---------|-------------|
| `!balance` | Check your euro balance |
| `!baltop` | Euro leaderboard |
| `!baltransfer @user €amount` | Send euros to another player |

### Games (games channel only)
| Command | Description |
|---------|-------------|
| `!flip` | Coin flip |
| `!games` | List available games |
| `!hangman start [easy\|medium\|hard\|extreme]` | Start a Hangman game (optional difficulty) |
| `!hangman <lang> [--clue <lang>]` | Start a multilingual game (en/fr/pt-PT) with optional clue |
| `!hangman [letter]` | Guess a letter |
| `!hangman [phrase]` | Attempt full solution |
| `!hangman submit [phrase]` | Submit a phrase to the pool |
| `!hangman skip` | Skip game (admin only) |
| `!hangboard` | Hangman leaderboard |

### Blackjack (games channel only)
| Command | Description |
|---------|-------------|
| `!blackjack €amount` | Start/join a Blackjack table (1-4 players) |
| `!hit` | Take a card |
| `!stand` | End your turn |
| `!blackjack leave` | Leave before game starts |
| `!bjboard` | Blackjack leaderboard |
| `!twinbeeboard` | GogoBee's victory record against players |

### UNO (games channel only)

UNO can be played solo (vs GogoBee) or multiplayer (1-4 players + bots). All gameplay happens in DMs. The games channel is used for lobby management and public announcements.

| Command | Description |
|---------|-------------|
| `!uno €amount` | Start a solo game vs GogoBee |
| `!uno nomercy €amount` | Start a solo No Mercy game |
| `!uno nomercy 7-0 €amount` | Solo No Mercy with 7-0 rule |
| `!uno start €amount` | Create a multiplayer lobby |
| `!uno start nomercy €amount` | Multiplayer No Mercy lobby |
| `!uno start nomercy 7-0 €amount` | Multiplayer No Mercy with 7-0 rule |
| `!uno join` | Join an open lobby |
| `!uno addbot` | Add a bot opponent to the lobby (max 2, funded from community pot) |
| `!uno removebot` | Remove the last added bot from the lobby |
| `!uno go` | Start the game (host only, 2+ participants required) |
| `!uno leave` | Leave the lobby (refunds ante) |
| `!uno cancel` | Cancel the lobby (host/admin, refunds all) |

**DM commands during gameplay:** reply with a card number to play, `draw` to draw, `uno` to call UNO (required when you have 2 cards), `quit` to forfeit. During draw stacking, type `accept` to absorb the stack.

#### Classic Mode

Standard 108-card UNO deck. Draw one card per turn (pass if unplayable). Wild Draw Four can be challenged — if the challenger catches a bluff, the player draws 4 instead.

GogoBee has a personality system during solo play: she reads a book while playing, and puts it down when the game gets serious (opponent has few cards). Commentary changes based on book state.

#### No Mercy Mode

Based on UNO Show 'Em No Mercy (2023, Mattel). Bigger 168-card deck, meaner rules.

**New cards:**
| Card | Type | Effect |
|------|------|--------|
| Skip Everyone | Colored | Skips all other players — you go again |
| Discard All | Colored | Play it and discard every other card of that color from your hand |
| Draw Four | Colored | Like Wild Draw Four but matches by color (not wild) |
| Wild Reverse Draw Four | Wild | Reverse direction + draw 4 + pick a color |
| Wild Draw Six | Wild | Draw 6 + pick a color |
| Wild Draw Ten | Wild | Draw 10 + pick a color |
| Wild Color Roulette | Wild | Pick a color — next player flips cards from the deck until that color appears, keeping all flipped cards |

**Rule changes:**
- **Draw stacking** — when hit with a draw card, play a draw card of equal or higher value to pass the penalty to the next player. The stack keeps growing until someone can't (or won't) stack back. That player draws the entire total.
- **Draw until playable** — no more drawing one and passing. You keep drawing until you find a playable card.
- **Mercy rule** — reach 25 cards in your hand and you're eliminated.

#### 7-0 Rule (optional, No Mercy only)

Enabled by adding `7-0` to the command. When active:
- **Play a 7** — swap hands with another player of your choice (in multiplayer, you pick the target)
- **Play a 0** — all players pass their hand to the next player in play direction

#### Sudden Death

When a 2-player game (including bot matchups) exceeds 80 turns, a 20-turn countdown begins. At turn 100, both hands are scored by UNO card point values — lowest total wins. Tiebreaker: fewer cards, then advantage to the non-active player.

#### Multiplayer Bots

The default bot (GogoBee) is always present in multiplayer games. Up to 2 additional bots (WinBee, GwinBee) can be added via `!uno addbot` while the lobby is open. Addbot bots ante from the community pot, increasing the total pot. A single human can start a game if bots fill the remaining slots.

### Texas Hold'em (games channel only)

No-limit Texas Hold'em poker for 2-9 players. Buy-in is debited from your euro balance when you sit down; your remaining stack is cashed out when you leave. Private cards and coaching tips are delivered via DM — the room only sees start/end announcements.

An optional AI opponent (NPC) uses a CFR-trained poker solver. Add one with `!holdem addbot`.

| Command | Description |
|---------|-------------|
| `!holdem join` | Sit down at the table |
| `!holdem leave` | Leave the table (cashes out stack, shows refund) |
| `!holdem start` | Start dealing (2+ players) |
| `!holdem play` | Shortcut: join + start in one command |
| `!holdem addbot` | Add a CFR-trained AI opponent |
| `!holdem fold` | Fold your hand |
| `!holdem check` | Check (no bet to call) |
| `!holdem call` | Call the current bet |
| `!holdem raise <amount>` | Raise to a total of amount |
| `!holdem allin` | Go all-in |
| `!holdem status` | Current table state (sent via DM) |
| `!holdem help` | Show in-game help |

**DM commands:** `!holdem tips on/off` — toggle coaching tips (equity + pot odds analysis, powered by Ollama with rules-based fallback).

**Idle timeout:** Tables with no hands dealt close after 1 hour. A warning is posted at 45 minutes.

#### NPC Bot

The NPC opponent uses Counterfactual Regret Minimization (CFR), specifically the External Sampling variant of Monte Carlo CFR. Instead of hardcoding poker strategy, the bot learns one through millions of rounds of self-play. On each iteration, it plays both seats of a heads-up hand, tracks how much it "regrets" not having taken each alternative action, and gradually shifts its strategy toward the actions it regrets not taking. Over time, the strategy converges toward a Nash equilibrium — a point where no single change in play can improve its expected winnings against a perfect opponent. The trained policy ships as a single `.gob` file loaded at startup, and the bot plays a mixed strategy: it doesn't always make the same play in the same spot, but randomizes according to its trained probability distribution, which makes it harder to exploit.

The interesting engineering is in the abstraction layer. Real poker has roughly 10^17 possible game states — far too many for a tabular approach. We collapse this space down to around 23,000 information sets by bucketing hand strength into 12 equity tiers (computed via Monte Carlo rollout against random opponent hands), classifying boards as dry, wet, or paired based on flush/straight draw density and board pairing, tracking stack-to-pot ratio across 5 buckets, and encoding the last 6 actions as a compressed history string. All of this gets packed into a single `uint64` key — no string formatting, no allocations on the hot path. Preflop hands use a lookup table of the 169 strategically distinct hold'em starting hands, which eliminates Monte Carlo during the most frequently visited part of the game tree. Training runs at about 5 million iterations across all CPU cores with shared regret tables, periodic checkpointing, and regret pruning after a 500K warmup to skip deeply negative branches. The result is a bot that plays a solid, unpredictable game — not world-class, but strong enough to make the table interesting.

#### Training the NPC

A standalone training CLI is provided under `cmd/holdem-train/`. It requires the `training` build tag:

```bash
# Build the training CLI
go build -tags training -o holdem-train ./cmd/holdem-train/

# Train with 8 workers (defaults to all CPU cores if --workers is omitted)
./holdem-train --iterations 5000000 --workers 8 --output data/policy.gob

# Resume from a checkpoint
./holdem-train --iterations 5000000 --workers 8 --resume data/policy.gob.checkpoint --output data/policy.gob

# Validate the trained policy (10K hands vs random baseline)
./holdem-train --validate --output data/policy.gob
```

| Flag | Default | Description |
|------|---------|-------------|
| `--iterations` | `5000000` | Number of training iterations |
| `--workers` | `runtime.NumCPU()` | Parallel workers |
| `--output` | `data/policy.gob` | Output policy file |
| `--resume` | | Resume from checkpoint |
| `--validate` | `false` | Run validation instead of training |
| `--checkpoint-every` | `500000` | Checkpoint interval |
| `--seed` | `42` | Random seed |

Progress is logged with overall completion percentage and ETA. Checkpoints are saved every 30 seconds during parallel training.

### Wordle (games channel only)

Daily cooperative Wordle — one puzzle per day, the community works together with a shared 6-guess limit. Word selection powered by DreamDict with a bundled word list as fallback. A new puzzle auto-posts at midnight UTC. Word length is configurable (5-20 letters). Guesses persist across bot restarts. When a puzzle expires at midnight, the bot reveals the answer and announces it to the room. The puzzle pool includes video game themed words (loaded from `data/wordle_games.txt`) — when one is selected, a category hint is shown. Duplicate prevention ensures the same word won't appear within the last 500 puzzles.

| Command | Description |
|---------|-------------|
| `!wordle <word>` | Submit a guess for today's puzzle |
| `!wordle grid` | Re-post the current puzzle grid |
| `!wordle stats` | All-time leaderboard with community streak |
| `!wordle new` | Start a new puzzle (admin) |
| `!wordle new <5-20>` | New puzzle with specific word length (admin) |
| `!wordle skip` | Reveal answer and end puzzle (admin) |
| `!wordle help` | Show commands |

Economy rewards are tracked per player — `!wordle stats` shows total earnings.

### Adventure (DM-based idle RPG)

A daily DM-driven idle RPG where each player takes one action per day — dungeon, mine, fish, forage, visit the shop, blacksmith, or rest. Outcomes resolve with flavor text and loot is credited to your euro balance. An evening summary posts to the games room. TwinBee is a permanent NPC adventurer who distributes rewards to active players.

Characters auto-create on first `!adventure` (or `!adv`) command. All gameplay happens in DMs — reply to the bot's morning prompt with your choice. DM replies are only interpreted as adventure choices for 15 minutes after a menu is sent, so other DM-based games (UNO, Hold'em) won't conflict.

| Command | Description |
|---------|-------------|
| `!adventure` / `!adv` | Open today's action menu (sent via DM) |
| `!adventure status` | Character sheet (sent via DM) |
| `!adventure shop` | Browse equipment for sale (sent via DM) |
| `!adventure buy <item>` | Buy equipment by name or tier shorthand (`3 sword`, `t4 boots`) |
| `!adventure sell <item>` | Sell an inventory item (credits euro balance) |
| `!adventure sell all` | Sell entire inventory |
| `!adventure equip` | Equip masterwork gear from inventory |
| `!adventure inventory` | List current inventory |
| `!adventure leaderboard` | Top adventurers |
| `!adventure revive @user` | Revive a dead player (admin) |
| `!adventure respond <choice>` | Reply to today's action prompt (alternative to DM reply) |
| `!adventure summary` | Force daily summary post (admin) |
| `!adventure boost` | Double XP/money for all adventurers for a day (admin) |
| `!adventure babysit [week\|month\|status\|cancel]` | Hire TwinBee to run your daily action (trains your weakest gathering skill) |
| `!adventure blacksmith` | Show repair quotes for damaged gear |
| `!adventure repair [all\|<slot>]` | Repair one slot or all damaged gear at the blacksmith |
| `!adventure rivals` | Show the rival pool and any open challenges |
| `!thom [shop\|buy\|pay\|payoff\|autopay\|petbuy]` | Thom Krooke — housing, mortgage, and pet adoption broker |
| `!hospital` | Check in to St. Guildmore's Memorial Hospital for same-day revival (costs €25k × combat level) |

**DM replies:** Reply to the morning prompt with a number (`1`–`7`) or activity name (`dungeon`, `mine`, `fish`, `forage`, `shop`, `blacksmith`, `rest`). You can specify a location: `1 Soggy Cellar`, `mine 3`, etc.

#### Activities

Four activity types across 5 tiers of locations. Higher tiers require higher character level and equipment.

- **Dungeon** — combat XP, chance of death, best loot potential
- **Mining** — mining XP, cave-in risk, ore and gem drops
- **Fishing** — fishing XP, hazard risk, catch drops
- **Foraging** — foraging XP, wildlife hazards, herb and reagent drops

#### Mechanics

- **Equipment** — 5 slots (weapon, armor, helmet, boots, tool) with tiered upgrades from the shop. Equipment degrades on bad outcomes and breaks at 0 condition.
- **Masterwork gear** — rare skill-specific equipment drops from gathering activities (mining, fishing, foraging). 15 items across 5 tiers with decreasing drop rates (5% T1 down to 0.5% T5). Location-gated — drops only at matching tier. Auto-equips if better than current gear; otherwise goes to inventory for manual equipping via `!adventure equip`. Masterwork items provide a +5% skill bonus when the item's source skill matches the current activity. Character sheet marks masterwork items with a star.
- **Treasures** — rare collectibles (up to 3) that provide passive bonuses (XP multipliers, death chance reduction, loot quality). Prompted to discard when at cap.
- **Streaks** — consecutive days of activity grant escalating bonuses (XP, loot quality, death chance reduction). Resting resets your streak. Dead players' streaks are frozen — you won't lose your streak to involuntary downtime.
- **Grudge** — dying at a location marks it as your grudge. Returning there grants +10% success and +25% XP. Clears on success.
- **Party bonus** — if two players independently visit the same location on the same day, both get +10% loot value.
- **Death** — locked out for 6 hours. Natural respawn happens automatically when the timer expires. Use `!hospital` for immediate revival at a cost. Death's Reprieve (surviving a lethal roll) sets all equipment to 1 condition instead of destroying it. Dead players' streaks are preserved with a grace period — if you die and can't act on revival day, your streak won't reset.
- **Holidays** — on recognized holidays (~20/year across religious and cultural calendars), you get a second daily action. Hebrew and Islamic calendar support for floating holidays.
- **TwinBee NPC** — takes a daily action (location tier capped by best player's combined level), distributes loot share to active players scaled quadratically by level, and occasionally gifts random buffs.
- **Hospital** — St. Guildmore's Memorial Hospital offers same-day revival for dead players. The bill is comically inflated (€125k × combat level) but guild insurance covers 80%, leaving €25k × combat level. Players who can't afford it are discharged back to the natural respawn queue. Nurse Joy provides the bedside manner.
- **Robbie the Friendly Bandit** — an automated NPC who visits at a random hour each day (8:00–21:00 UTC). Robbie takes sub-tier gear from your inventory (shop gear below your equipped tier, masterwork gear you've outgrown), leaves €50 per item as a "handling fee," and donates everything to the community pot. If he takes masterwork gear and you don't already have one, he drops a "Get Out of Medical Debt Free" card. No player command — Robbie comes to you.
- **Mid-day events** — random events can trigger between actions, delivering bonus loot, buffs, or narrative encounters.
- **Chat level perks** — active chat participation boosts your adventurer. +5% XP per 10 chat levels (capped at +25% at level 50+), plus +0.5% rare drop chance per 10 levels.

#### Blacksmith & Repair

Equipment accumulates damage on bad outcomes and breaks at 0 condition. The blacksmith repairs gear for a per-point fee that scales with tier (base rates T0→T5: €1, €2, €5, €12, €30, €80; masterwork and arena gear use the next tier up). The cost has a mild convexity (`baseRate × damage × (1 + damage/200)`), so repairing earlier is slightly cheaper per point than letting gear sit at low condition — but not punitively so. `!adventure blacksmith` previews quotes; `!adventure repair all` or `!adventure repair <slot>` commits. Visiting the blacksmith counts as your daily action.

#### Babysitting Service

Busy days? Hire TwinBee to run your daily action for you. Daily cost is `€100 + combatLevel × €20`. TwinBee trains your weakest gathering skill (mining/fishing/foraging) so the service doubles as catch-up for neglected tracks. Subscribe by the week or month, or check/cancel anytime: `!adventure babysit week|month|status|cancel`.

#### Rival Duels

At combat level 5 and above you're entered into the rival pool. Every 3–4 days a random eligible player is matched as your rival and challenges you to a rock-paper-scissors duel via DM. You have 24 hours to accept and play. Stake is `(combatLevel / 5) × €1,000`, winner-take-all. Use `!adventure rivals` to see the pool and open challenges.

#### Housing & Mortgage (Thom Krooke)

Thom Krooke is the guild's housing broker. Four tiers are available:

| Tier | Name | Price |
|------|------|-------|
| 1 | Base | €75,000 |
| 2 | Livable | €150,000 |
| 3 | Comfortable | €300,000 |
| 4 | Established | €600,000 |

Buy outright or finance with a mortgage. Rates track the real-world US 5/1 ARM via the FRED API (`MORTGAGE5US` series; requires `FRED_API_KEY`, defaults to 6.5% if unset). Autopay pulls from your euro balance each day. Commands: `!thom shop`, `!thom buy <tier>`, `!thom pay <amount>`, `!thom payoff`, `!thom autopay on|off`, `!thom petbuy`.

#### Pets

Once you reach the Livable tier (HouseTier ≥ 2) a stray pet may show up at your door — 15% daily chance. When a pet arrives you'll get a DM prompt to `chase` it away or `feed` it to adopt. Each pet interaction grants +1.5 XP to a random skill. At pet Level 10, Thom unlocks pet armor for purchase (`!thom petbuy <tier>`).

#### Guest NPCs — Misty & Arina

Two rotating guest adventurers can be hired to join you on encounters:

- **Misty** — €100 hire fee, 7-day cooldown.
- **Arina** — €5,000 hire fee, 7-day cooldown.

After hiring, there's a 7.5% chance per action over the next 7 days that your NPC shows up mid-adventure and applies a buff to the outcome.

#### Arena (`!arena`)

A multi-tier combat gauntlet independent of the daily adventure action. Fight through 5 tiers of 4 rounds each — 20 unique named monsters with escalating lethality. Earnings accumulate across rounds but are forfeited on death. After clearing a tier, choose to descend deeper (keep earnings at risk) or cash out. Death locks you out of both arena and adventure for 6 hours. Each fight produces a turn-based combat log (Dragon Quest style) with fabricated HP pools and action narration — the outcome is determined by the roll, the log is assembled backward from the result. Arena losses award +60 participation XP.

| Command | Description |
|---------|-------------|
| `!arena` | Show the arena tier menu |
| `!arena tier <1-5>` | Select a tier (shows confirmation with R1 opponent) |
| `!arena fight` | Confirm entry / fight current round |
| `!arena cancel` | Back out of tier selection |
| `!arena descend` | Descend to next tier after clearing (earnings carry over, still at risk) |
| `!arena cashout` | Take your earnings and leave |
| `!arena stats` | Your personal arena stats |
| `!arena status` | Current run state |
| `!arena leaderboard` | Top arena players |
| `!arena help` | Arena help text |

**Mechanics:**
- **Death chance** — based on monster lethality, combat level, equipment tier, and battle skill. Clamped between 1% and 98%.
- **Rewards** — tier base payout * round number + battle skill * tier multiplier. Higher tiers and later rounds pay more.
- **Auto-cashout** — 10 minutes to decide after clearing a tier. GogoBee cashes out on your behalf if you're slow.
- **Tier entry confirmation** — `!arena tier N` previews the first opponent; `!arena fight` commits.

#### Co-op Dungeons (`!coop`)

Multi-day party runs separate from solo. 2–4 players, 2–7 days depending on tier, scaled rewards, and a public game-room thread the whole community watches. The combat action is consumed once at lock; subsequent days only ask for a daily funding decision (harvest activities continue normally).

| Tier | Days | Difficulty | Reward Pool | Optimal Funding |
|------|------|------------|-------------|-----------------|
| 1 | 2 | Moderate | €22,500 | Minimal/Standard |
| 2 | 3 | Hard | €40,000 | Standard |
| 3 | 4 | Very Hard | €72,500 | Standard |
| 4 | 5 | Brutal | €120,000 | Standard or Aggressive |
| 5 | 7 | Murderous | €600,000 | Aggressive (must commit) |

| Command | Description |
|---------|-------------|
| `!coop list` | Show open invites |
| `!coop start <1-5>` | Open an invite (24h window, pinned in the games room) |
| `!coop join [<id>]` | Join an open invite (defaults to most recent) |
| `!coop fund <tier>` | Set today's funding (`none` / `minimal` / `standard` / `aggressive` / `all_in`) |
| `!coop vote <A\|B\|C>` | Vote on the day's TwinBee-narrated floor event |
| `!coop bet <amount> <success\|failure>` | Spectator parimutuel bet (10% rake) |
| `!coop gift <run_id> <basket\|mimic>` | Send a gift (1 harvest action) |
| `!coop giftvote <id> <open\|leave>` | Party votes whether to open a received gift |
| `!coop status` | Your current run state |
| `!coop stats` | Community-wide aggregates: outcomes, gold flow, betting, gifts, helpfulness |
| `!coop cancel` | Leader cancels an open invite before lock |
| `!coop admgift <run_id> <basket\|mimic> [sender]` | Drop a gift into an active run, bypassing party-member and harvest-action checks (admin only — debug/testing) |
| `!coop help` | Co-op command list |

**Funding tiers** add to the per-floor success modifier: None −10%, Minimal +0%, Standard +8%, Aggressive +18%, All-In +30%. None is free; Minimal €500/day; Standard €1,500; Aggressive €4,000; All-In €10,000. Funding is non-refundable. Inactive players auto-play None.

**Floor events.** TwinBee narrates 1 of 4 categories per floor (Obstacle / Opportunity / Crisis / Encounter), tier-weighted. Each event has 2–3 options; majority vote wins, ties go to the leader, leader has the casting tiebreak. TwinBee always recommends an option — he is wrong roughly half the time. The party's vote modifier (−15 to +12 per floor depending on the option) stacks on the funding modifier. The 95% per-floor success cap means once you're saturated, more funding is wasted.

**Party strength factors.** Each member contributes a small per-floor modifier based on their combat level relative to the tier minimum (clamped ±8) plus a pet bonus (max +2.5 at pet level 10). A maxed veteran party at T5 can succeed at Standard funding where a fresh party would need Aggressive.

**Newbie liability.** Players below a tier's minimum combat level are flagged in the party post and capped at +8% funding modifier regardless of how much they pay. The party chose to let them in. Their reward share is unchanged — the cost is borne by the funding economy, not the post-run split.

**Spectator betting.** Parimutuel pool, 10% rake. Bets can be placed or increased any time during the run; positions are locked in (success or failure can't be switched). Party members can bet on their own run — sandbagging while heavily bet against is exploitative and visible. Odds line shows estimated success% based on party levels, pets, neutral funding assumption, and a hidden TwinBee Helpfulness Rating (rolling last 30 floor events: how often his recommendation was right). Helpfulness shifts the line ±20% but is never shown directly — players notice the line moves after events resolve.

**Gifts.** Anyone *not* in the run can spend one harvest action to send a Care Basket or a Mimic. The party never sees which type. Vote `open` or `leave`. Magnitudes are equalized across all four outcomes — both "always open" and "always leave" yield EV=0 with σ=6, so neither is risk-averse-dominant. The choice is purely about reading sender intent.

|             | Open | Leave |
|-------------|------|-------|
| **Care Basket** | +6% (boost) | −6% (basket explodes) |
| **Mimic**       | −6% (mimic does what mimics do) | +6% (sad mimic helps anyway) |

Multiple gifts stack additively — coordinated senders can swing odds significantly. The full gift log is public at end of run.

**Loot.** On success, gold pool splits evenly (5% community tax). 2–6 items drop from the corresponding solo dungeon loot table (count scales with tier). Each item goes to a member via weighted roll — your share of total funding is your odds. **T5 always drops a masterwork**; T4 has a 25% chance. Masterworks go to inventory (not auto-equipped) so winners with better gear can sell or trade.

**Wipes.** No reward. Funding is gone. No combat-action refund (the tick already gave you a fresh one at midnight). Bet pool pays out to the failure side. The dungeon does not editorialize.

**Pinning.** Invite posts are pinned in the games room when opened, unpinned when the run locks or cancels. Bot needs power level for state events.

### Reminders
| Command | Description |
|---------|-------------|
| `!remindme <time> <message>` | Set a reminder (natural language) |
| `!reminders` | Your pending reminders |
| `!unremind <id>` | Cancel a reminder |

### Presence
| Command | Description |
|---------|-------------|
| `!away [message]` | Set away status |
| `!afk [message]` | Same as away |
| `!back` | Clear away/afk |
| `!whois @user` | Profile card |

### Fun
| Command | Description |
|---------|-------------|
| `!roll [NdM+X]` | Dice (default 1d6) |
| `!8ball <question>` | Magic 8-ball |
| `!coin` | Coin flip |
| `!time [city\|@user]` | World clock (cities or user's timezone) |
| `!hltb <game>` | How Long To Beat |
| `!twinbee` | Twinbee series lore |
| `!poll <q> \| <a> \| <b>...` | Reaction poll |
| `!weather <location>` | Weather (needs API key) |
| `!dadjoke` | Dad joke |
| `!randomwiki` | Random Wikipedia article |

### Tools
| Command | Description |
|---------|-------------|
| `!calc <expression>` | Calculator, understands "5 plus 3" |
| `!qr <text>` | Generate QR code |

### Finance
| Command | Description |
|---------|-------------|
| `!stock <ticker>` | Stock quote (Finnhub) |
| `!stockwatch add\|list\|remove` | Stock watchlist |
| `!fx rate [EUR\|JPY\|CAD]` | Live USD exchange rate + quick signal |
| `!fx rate EUR/USD` | Cross-pair rate from first currency's perspective |
| `!fx report [EUR\|JPY\|CAD]` | Full analysis (averages, 52w range, buy score) |
| `!fx report EUR/JPY` | Cross-pair full analysis with computed history |
| `!fx setalert <currency> <rate>` | DM alert when rate hits threshold |
| `!fx alerts` | List your active alerts |
| `!fx delalert <currency> <rate>` | Remove an alert |
| `!howsthemarket` | Daily market snapshot with Ollama commentary (7 global indices) |
| `!marketstatus` | Exchange open/closed status (NYSE, LSE, Euronext, TSE) |
| `!marketreport week\|month\|year` | Historical trend report with Ollama narrative |
| `!marketreport vix` | VIX fear/greed trajectory |
| `!marketreport compare <index> <days>` | Single index over N days |

### Entertainment
| Command | Description |
|---------|-------------|
| `!game <query>` / `!retro <query>` | Game lookup (RAWG) |
| `!releases [month\|search <q>]` | Game releases |
| `!releasewatch add\|list\|remove` | Release watchlist |
| `!concerts <artist>` | Concert search |
| `!concerts watch\|watching\|unwatch` | Concert watchlist |
| `!anime <title>` | Anime search (MAL) |
| `!anime watch\|watching\|unwatch\|season\|upcoming` | Anime features |
| `!movie <title>` / `!tv <title>` | Movie/TV search (TMDB) |
| `!movie watch\|watching\|unwatch` | Movie watchlist |
| `!upcoming movies` | Upcoming movies |

### Lookup & Reference
| Command | Description |
|---------|-------------|
| `!wiki <topic>` | Wikipedia summary |
| `!define <word> [lang]` | Dictionary definition — searches all languages via DreamDict by default, or specify one (en/fr/pt-PT/zh). Includes antonyms when available. Falls back to free dictionary API for English if DreamDict is unavailable. |
| `!urban <term>` | Urban Dictionary |
| `!translate <word> [lang]` | Cross-language word lookup (en/fr/pt-PT, auto-detects source) |
| `!antonym <word> [lang]` | Antonyms for a word (en/fr/pt-PT/zh) |
| `!pronounce <word> [lang]` | Pronunciation data — IPA, CMU phonemes (en), Pinyin (zh) |
| `!etymology <word> [lang]` | Word origin and history from Wiktionary |
| `!difficulty <word> [lang]` | Difficulty score (Easy/Medium/Hard/Brutal) with frequency info |
| `!rhyme <word>` | Rhyming words via CMU phoneme matching (English only, `--all` for full list) |

### Personal
| Command | Description |
|---------|-------------|
| `!settz <timezone>` | Set timezone (IANA) |
| `!mytz` | Your timezone and current time |
| `!timezone list` | Common timezones |
| `!np [track]` | Now playing |
| `!backlog add\|list\|random\|done` | Personal backlog |
| `!watch <keyword>` | DM alerts for a keyword |
| `!watching` | List keyword watches |
| `!unwatch <keyword>` | Remove watch |

### Countdowns
| Command | Description |
|---------|-------------|
| `!countdown add "<label>" <YYYY-MM-DD>` | Public countdown |
| `!countdown private "<label>" <YYYY-MM-DD>` | Private countdown |
| `!countdown mine` | Your countdowns |
| `!countdown remove <id>` | Remove one |
| `!countdown [id]` | List all or show one |

### Birthdays
| Command | Description |
|---------|-------------|
| `!birthday set <MM-DD[-YYYY]>` | Set birthday |
| `!birthday remove` | Remove birthday |
| `!birthday show` | Show yours |
| `!birthdays` | Upcoming (next 30 days) |
| `!horoscope` | Daily horoscope (requires birthday to be set) |

### Community
| Command | Description |
|---------|-------------|
| `!quote` | Random quote (or reply to a message to save it) |
| `!quote @user` | Random quote from a specific user |
| `!quote search <text>` | Search quotes |
| `!quote "text" -- @user` | Manually save a quote attributed to a user |
| `!quote delete <id>` | Delete a quote (admin only) |
| `!quoteboard` | Top 5 most-quoted members |
| `!missing` | List members who haven't posted recently |
| `!missing post [@user]` | Generate a milk carton poster for the longest-absent (or specified) member |
| `!haveyouseenthem @user` | Generate a milk carton missing poster for a user |

### Markov
| Command | Description |
|---------|-------------|
| `!markov [@user]` | Generate a sentence in the style of a user (or yourself) |
| `!markov me` | Alias for generating from your own corpus |
| `!markov @user1 @user2` | Mashup — interleave both users' corpora |
| `!impersonate @user` | Alias for `!markov @user` |
| `!ghostwrite @user <prompt>` | Seed the Markov chain with a starting phrase |
| `!markov stats [@user]` | Corpus size, unique words, top 5 words, earliest date |
| `!markov forget` | Delete your own Markov corpus (DM confirmation) |
| `!markov forget @user` | Admin-only: clear another user's corpus |
| `!markov leaderboard` | Top 10 by corpus size |

### Emojiboard
| Command | Description |
|---------|-------------|
| `!emojiboard` | Top 10 most-used reaction emojis in this room |
| `!emojiboard @user` | Top emojis given by a specific user |
| `!emojiboard received [@user]` | Top emojis received by a user |
| `!emojiboard givers <emoji>` | Top 5 users who used a specific emoji most |
| `!emojiboard week` | Same as `!emojiboard` but last 7 days only |

### LLM (requires Ollama)
| Command | Description |
|---------|-------------|
| `!howami [@user]` | Roast profile |
| `!vibe` | Room energy check |
| `!tldr` | Summarize recent chat |
| `!sentiment [@user]` | Sentiment breakdown (10 categories) |
| `!potty [@user]` | Profanity count |
| `!pottyboard` | Profanity leaderboard |
| `!insults [@user]` | Insult stats |
| `!insultboard` | Insult leaderboard |
| `!tarot [@user]` | Draw a tarot card + LLM reading |
| `!tarotspread [@user]` | Three-card spread (Past/Present/Future) |

### Moderation (admin only, requires `FEATURE_MODERATION=true`)
| Command | Description |
|---------|-------------|
| `!mod warn @user [reason]` | Issue a manual warning (counts as a strike) |
| `!mod mute @user [duration]` | Manual mute (does not consume a strike) |
| `!mod unmute @user` | Remove mute |
| `!mod ban @user [reason]` | Permanent ban |
| `!mod strikes @user` | Show active strikes |
| `!mod forgive @user` | Clear all active strikes |
| `!mod history @user` | Full moderation history |
| `!mod reload` | Reload word list from disk |
| `!mod status` | Show current moderation config |
| `!mod test @user` | Simulate next violation without taking action |

### RSS / Miniflux (requires `MINIFLUX_URL`)
| Command | Description |
|---------|-------------|
| `!rss feeds` | List all feeds from Miniflux with IDs and categories |
| `!rss subscribe <feed_id> [#room]` | Route a feed to this room (admin only) |
| `!rss unsubscribe <feed_id>` | Stop routing a feed (admin only) |
| `!rss subscriptions` | List active subscriptions for this room |
| `!rss latest <feed_id>` | Manually fetch and post the latest entry |
| `!rss pause <feed_id>` | Pause feed routing (admin only) |
| `!rss resume <feed_id>` | Resume a paused feed (admin only) |
| `!rss status` | Show polling status (admin only) |

### Other
| Command | Description |
|---------|-------------|
| `!achievements [@user]` | Unlocked achievements |
| `!wotd` | Today's Palavra do Dia — Portuguese word with en/fr translations, etymology when available (use it in chat for 25 XP) |
| `!wotd force` | Pick a new word for today (moderator only) |
| `!botinfo` | Bot diagnostics (admin only) |
| `!help` | DMs the full command list |

---

## Passive Features

All of these run in the background without any commands:

- **XP** - 10 XP per message with 30s cooldown. Level-up announcements use Twinbee/Parodius themed messages.
- **Stats** - tracks words, chars, links, images, questions, emojis, and time-of-day patterns
- **Streaks** - consecutive days active, first poster of the day
- **Reputation** - detects "thanks", "ty", "thx", etc. with 24h cooldown per pair
- **Achievements** - 93 of them, checked silently on every message
- **Markov chains** - collects encrypted messages for `!markov` generation (10k cap per user, 90-day TTL)
- **Keyword alerts** - DMs you when someone says your watched keywords
- **Presence** - auto-clears away/afk when you send a message
- **Room milestones** - announces at 1k, 5k, 10k, 25k, 50k, 100k, 250k, 500k, 1M messages
- **Euro earning** - earn €0.50–€10 per message based on word count (30s cooldown). Starting balance seeded from corpus history (capped at €2,500)
- **URL previews** - OG tag extraction (feature-flagged, off by default)
- **Reactions** - logs all reactions for `!emojiboard`
- **Space groups** - rooms with sufficient member overlap are automatically grouped. Leaderboards, trivia scores, and other per-room features aggregate across the group. Recomputed hourly; persisted to SQLite. Uses strict clique-based grouping (every room must meet the threshold with every other room in the group).
- **LLM classification** - sentiment (10 categories), profanity, insults, WOTD usage (needs Ollama). Emoji reactions limited to fancy words (🎓), gratitude (💜), WOTD usage (📖), and insult responses
- **Message buffer** - last 50 messages per room held in memory for `!vibe` and `!tldr`. Not persisted to disk; resets on restart. Uptime reported when insufficient messages are buffered.

---

## Scheduled Posts

Uses [robfig/cron](https://github.com/robfig/cron). All times UTC.

| Time | Job | What it does |
|------|-----|--------------|
| 06:00 | Birthdays | Birthday shoutouts + 100 XP + €1,000 |
| 07:00 | Holidays | Multi-calendar holidays (US, Asian, Jewish, Islamic) |
| 08:00 | WOTD | Posts the Word of the Day (disable with `DISABLE_WOTD_POST=true`) |
| 09:00 Mon | Releases | Weekly game releases |
| 10:00 | Anime | Anime airing today |
| 11:00 | Movies | Movie releases today |
| 12:00 Sun | Concerts | Weekly concert digest |
| 13:00 Wed/Sun | Esteemed | Satirical esteemed community member posts (feature-flagged) |
| Every 30s | Reminders | Fires pending reminders |
| Hourly | Space groups | Refreshes room membership overlap and group mappings |
| 03:00 | Maintenance | Purges stale caches, old rate limits, expired logs, miniflux seen entries; runs SQLite optimize |
| 03:30 | Markov TTL | Purges markov corpus entries older than 90 days |
| 23:00 | Market | Daily market index pull (Yahoo Finance + Finnhub fallback, Ollama summary) |
| Every N min | Miniflux | Polls Miniflux for new feed entries (configurable, default 15m) |

---

## Achievements

93 achievements across 15 categories:

**Message Milestones** - first_message, 100_messages, 500_messages, 1000_messages, 5000_messages, 10000_messages

**Time-Based** - night_owl, early_bird, night_dweller, dawn_patrol

**Content** - wordsmith, link_collector, link_hoarder, shutterbug, photographer, question_master, emoji_lover, exclaimer

**Social** - welcome_wagon, rep_magnet, rep_star

**Streaks** - week_streak, two_week_streak, month_streak, quarter_streak, year_streak

**Trivia** - trivia_novice, trivia_master, trivia_legend

**Economy** - euro_first, euro_1k, euro_10k, euro_broke, euro_comeback, euro_generous

**Blackjack** - bj_first_win, bj_blackjack, bj_bust, bj_beat_twinbee, bj_100_hands

**UNO** - uno_first_win, uno_nomercy_win, uno_draw_stack, uno_comeback

**Texas Hold'em** - holdem_first_win, holdem_royal_flush, holdem_bluff, holdem_beat_npc, holdem_allin_win, holdem_bounty

**Hangman** - hangman_solve, hangman_first_guess, hangman_submitted, hangman_executioner

**Wordle** - wordle_solve, wordle_first_guess, wordle_streak_3, wordle_bonus, wordle_closer

**Adventure** - adv_first, adv_died, adv_revived, adv_streak_7, adv_streak_30, adv_max_level, adv_treasure_cap, adv_grudge_win, adv_party, adv_twinbee_gift

**Arena** - arena_first_blood, arena_tier1, arena_tier2, arena_tier3, arena_tier4, arena_tier5, arena_descend, arena_full_run, arena_death_t5, arena_omega, arena_cashout_big

**Community** - quote_saved, quote_saved_10, missing_poster, tarot_spread

**WOTD** - wotd_first, wotd_week, wotd_30, logophile

**Special** - markov_victim, birthday_set, timezone_set, profile_complete

---

## Personality Archetypes

Assigned based on your message patterns:

| Archetype | What it means |
|-----------|---------------|
| Chatterbox | You talk a lot |
| Novelist | Long messages |
| Inquisitor | Always asking questions |
| Linkmaster | Shares lots of links |
| Shutterbug | Lots of images |
| Enthusiast | Exclamation marks! |
| Regular | Solid community member |

---

## Sentiment Classification

Every message (subject to `LLM_SAMPLE_RATE`) is classified by Ollama into one of 10 sentiment categories. Per-user counts are tracked in the database and viewable via `!sentiment`. The LLM also returns a float score (-1.0 to 1.0) for each message, averaged per user to derive an overall mood shown in `!sentiment` output and fed into `!howami` roast profiles.

Selective emoji reactions are still active: 🎓 for fancy/uncommon words, 💜 for gratitude, and 📖 for WOTD usage. The bot also reacts when insulted. Sentiment and profanity emoji reactions are disabled — classification still runs and logs to the database, but the bot won't react with sentiment emojis.

| Sentiment | Score range | Example |
|-----------|-------------|---------|
| Positive | > 0.5 | "This is awesome, great work!" |
| Excited | > 0.5 | "OH MY GOD I can't wait for this!!" |
| Supportive | > 0.5 | "You've got this, don't give up" |
| Grateful | > 0.5 | "Thank you so much for helping me" |
| Humorous | > 0.5 | "lmao that's the funniest thing I've seen all day" |
| Curious | > 0.5 | "How does that work exactly?" |
| Neutral | — | "I'll be back in 10 minutes" |
| Sarcastic | < -0.5 | "Oh sure, that'll definitely work" |
| Frustrated | < -0.5 | "I've been trying to fix this for three hours" |
| Negative | < -0.5 | "This is broken and nobody cares" |

---

## External APIs

All optional. The bot works fine without any of them, you just won't have those specific features.

| Service | Free? | What for |
|---------|-------|----------|
| [RAWG](https://rawg.io/apidocs) | Yes | Game lookups, releases |
| DreamDict | Self-host | Translations, WOTD (etymology), Hangman (clues + difficulty), Wordle (word selection + validation), dictionary commands (antonyms, pronunciation, etymology, difficulty, rhymes) |
| [Calendarific](https://calendarific.com) | Yes (1k/mo) | Holiday calendar |
| [HebCal](https://www.hebcal.com) | Yes, no key | Jewish holidays |
| [Aladhan](https://aladhan.com/prayer-times-api) | Yes, no key | Islamic dates |
| [OpenWeather](https://openweathermap.org/api) | Yes (1k/day) | Weather |
| [Finnhub](https://finnhub.io) | Yes | Stock quotes, market index fallback |
| [Yahoo Finance](https://finance.yahoo.com) | Yes, no key | Market index snapshots (unofficial API) |
| [Frankfurter](https://frankfurter.dev) | Yes, no key | Forex rates (ECB-sourced) |
| [Bandsintown](https://artists.bandsintown.com) | Yes | Concert data |
| [Jikan/MAL](https://jikan.moe) | Yes, no key | Anime data |
| [TMDB](https://www.themoviedb.org) | Yes | Movie/TV data |
| [OpenTDB](https://opentdb.com) | Yes, no key | Trivia questions |
| [Wikipedia](https://en.wikipedia.org/api/rest_v1/) | Yes, no key | Wiki summaries |
| [Free Dictionary](https://dictionaryapi.dev) | Yes, no key | Definitions |
| [Urban Dictionary](https://rapidapi.com/community/api/urban-dictionary) | Yes, no key | Slang |
| [icanhazdadjoke](https://icanhazdadjoke.com) | Yes, no key | Dad jokes |
| [SerpAPI](https://serpapi.com) | Free (100/mo) | Image search for esteemed members |
| [HowLongToBeat](https://howlongtobeat.com) | Yes, no key | Game completion times |
| [Ollama](https://ollama.ai) | Self-host | LLM features (sentiment, tarot, vibes, roasts) |
| [Miniflux](https://miniflux.app) | Self-host | RSS feed routing |

---

## Architecture

```
gogobee/
├── main.go                  # Entry point, plugin registration, cron setup
├── go.mod / go.sum
├── data/
│   ├── policy.gob           # Pre-trained CFR policy for Hold'em NPC
│   └── wordle_games.txt     # Video game themed words for Wordle bonus puzzles
├── cmd/
│   ├── holdem-train/
│   │   └── main.go          # CFR training CLI (build tag: training)
│   └── holdem-seed/
│       └── main.go          # Seed policy generator
├── internal/
│   ├── bot/
│   │   ├── client.go        # mautrix client + E2EE (cryptohelper + goolm)
│   │   └── dispatch.go      # Plugin registry, event dispatch
│   ├── crypto/
│   │   └── crypto.go        # AES-256-GCM encryption, HMAC-SHA256
│   ├── db/
│   │   └── db.go            # SQLite schema (80+ tables), migrations
│   ├── plugin/
│   │   ├── plugin.go        # Plugin interface, Base helpers, context types
│   │   ├── xp.go            # XP & leveling
│   │   ├── reputation.go    # Thanks detection
│   │   ├── stats.go         # Message stats & milestones
│   │   ├── streaks.go       # Daily streaks
│   │   ├── trivia.go        # OpenTDB trivia
│   │   ├── reminders.go     # Reminders
│   │   ├── presence.go      # Away/AFK
│   │   ├── fun.go           # Dice, 8ball, polls, weather, etc.
│   │   ├── tools.go         # Calculator, QR codes
│   │   ├── user.go          # Timezone, quotes, backlog, keyword watches
│   │   ├── welcome.go       # New user detection, !help
│   │   ├── achievements.go  # 93 achievements
│   │   ├── reactions.go     # Reaction logging, emojiboard
│   │   ├── markov.go        # Markov chains
│   │   ├── urls.go          # URL previews
│   │   ├── llm_passive.go   # Ollama sentiment/profanity
│   │   ├── wotd.go          # Word of the Day
│   │   ├── holidays.go      # Multi-calendar holidays
│   │   ├── gaming.go        # Game releases
│   │   ├── birthday.go      # Birthdays
│   │   ├── retro.go         # Game lookups (RAWG)
│   │   ├── lookup.go        # Wiki, dictionary, urban, translate
│   │   ├── dictionary.go    # DreamDict commands (antonym, pronounce, etymology, difficulty, rhyme)
│   │   ├── countdown.go     # Countdowns
│   │   ├── stocks.go        # Stocks
│   │   ├── market.go        # Market indices (Yahoo Finance + Finnhub fallback)
│   │   ├── forex*.go        # Forex rates & alerts (Frankfurter v2)
│   │   ├── concerts.go      # Concerts
│   │   ├── anime.go         # Anime
│   │   ├── movies.go        # Movies/TV
│   │   ├── miniflux.go      # Miniflux RSS feed routing
│   │   ├── botinfo.go       # Admin diagnostics
│   │   ├── howami.go        # LLM roasts
│   │   ├── vibe.go          # Room vibe, TLDR
│   │   ├── shade.go         # Stub
│   │   ├── milkcarton.go    # Missing member milk carton posters
│   │   ├── quotewall.go     # Encrypted quote wall (AES-256-GCM)
│   │   ├── tarot.go         # LLM-powered tarot readings
│   │   ├── horoscope.go     # Daily horoscopes
│   │   ├── euro.go          # Euro virtual currency
│   │   ├── flip.go          # Coin flip, !games
│   │   ├── hangman.go       # Collaborative Hangman
│   │   ├── blackjack.go     # Multiplayer Blackjack
│   │   ├── uno.go           # Solo UNO vs bot (DM-based)
│   │   ├── uno_multi.go     # Multiplayer UNO (lobby + DM turns + addbot)
│   │   ├── uno_nomercy.go   # No Mercy mode (deck, stacking, mercy rule, 7-0, bot AI)
│   │   ├── uno_test.go      # UNO tests (sudden death, scoring)
│   │   ├── holdem.go        # Texas Hold'em plugin (commands, game lifecycle, NPC)
│   │   ├── holdem_game.go   # Game state, player types, deck, position labels
│   │   ├── holdem_betting.go # Blinds, action validation, side pots
│   │   ├── holdem_eval.go   # Hand evaluation, showdown, settlement
│   │   ├── holdem_render.go # Card glyphs, table view, announcements
│   │   ├── holdem_tips.go   # Ollama coaching tips with equity analysis
│   │   ├── holdem_equity.go # Monte Carlo equity engine
│   │   ├── holdem_cfr.go    # CFR policy table, NPC action selection, training
│   │   ├── wordle.go        # Daily Wordle plugin (commands, lifecycle, scheduler)
│   │   ├── wordle_game.go   # Puzzle state, scoring algorithm, letter tracking
│   │   ├── wordle_render.go # Emoji grid, keyboard, announcements, leaderboard
│   │   ├── wordle_wordnik.go # Wordnik API (random word, validation, definitions)
│   │   ├── wordle_fallback.go # Emergency word list loader
│   │   ├── adventure.go     # Adventure plugin (commands, DM routing, activity resolution)
│   │   ├── adventure_character.go # Character types, DB CRUD, level-up, equipment
│   │   ├── adventure_activities.go # Locations, probability engine, loot, XP tables
│   │   ├── adventure_shop.go # Shop listings, buy/sell, inventory
│   │   ├── adventure_treasure.go # Treasure definitions, drop logic, bonuses
│   │   ├── adventure_twinbee.go # TwinBee NPC, reward distribution, buff gifts
│   │   ├── adventure_render.go # Character sheet, DMs, daily summary, leaderboard
│   │   ├── adventure_events.go  # Mid-day random events
│   │   ├── adventure_hospital.go  # Hospital revival system (Nurse Joy, itemized bill, nudges)
│   │   ├── adventure_robbie.go    # Robbie the Friendly Bandit (automated inventory cleaner)
│   │   ├── adventure_scheduler.go # Morning DM, evening summary, midnight reset tickers
│   │   ├── adventure_holidays.go # Holiday detection (Hebrew/Islamic calendar, fixed dates)
│   │   ├── adventure_masterwork.go # Masterwork gear (15 tiered items, drop logic, equip command)
│   │   ├── adventure_arena.go    # Arena commands, combat resolution, DB CRUD, auto-cashout
│   │   ├── adventure_arena_combat.go # Arena combat log generator (action pools, HP narration)
│   │   ├── adventure_arena_monsters.go # 5 tiers, 20 monsters, death messages
│   │   ├── adventure_arena_render.go   # Arena UI rendering (menus, stats, leaderboard)
│   │   ├── adventure_flavor_*.go # Flavor text pools (dungeon, mining, fishing, treasure, twinbee, events, hospital, robbie, closing)
│   │   ├── esteemed.go      # Satirical esteemed member posts
│   │   ├── moderation.go   # Moderation system (strikes, word list, flood detection)
│   │   └── ratelimits.go    # Rate limiting
│   └── util/
│       ├── auth.go          # Matrix login, token check
│       ├── logger.go        # slog logging
│       └── parser.go        # Message parsing, XP math, archetypes
```

### Why Go?

**E2EE** - This project went through three SDK iterations: `matrix-bot-sdk` (no E2EE support), `matrix-js-sdk` (E2EE via `fake-indexeddb` with an in-memory crypto store that wiped device keys on every restart), and finally `mautrix-go` which stores crypto state in SQLite with cross-signing bootstrap. The bot self-verifies its own device on startup.

**Deployment** - Pure Go, no CGo. `go build -tags goolm` gives you a static binary with zero system dependencies. The TypeScript version needed Node.js, npm, a C compiler for better-sqlite3, and libolm.

**Scheduler** - Replaced a hand-rolled 60s tick loop with robfig/cron. Standard cron expressions, less code, fewer bugs.

**Plugins** - Go interfaces + struct embedding instead of abstract classes. Same pattern, less boilerplate.

---

## Database

Single SQLite file at `$DATA_DIR/gogobee.db`. Schema auto-creates on first run. WAL mode enabled.

80+ tables covering users, XP, stats, streaks, reputation, reminders, trivia, achievements, encrypted quotes (AES-256-GCM), backlog, keyword watches, scheduler config, birthdays, horoscopes, LLM classifications, stocks, market snapshots, forex rates/alerts, concerts, anime, movies, countdowns, presence, encrypted markov corpus, reaction log, miniflux RSS subscriptions, and various caches.

### Backup

```bash
# safe to run while the bot is up (WAL mode)
sqlite3 data/gogobee.db ".backup data/gogobee-backup.db"
```

---

## Troubleshooting

### E2EE

E2EE should just work. The bot bootstraps cross-signing and self-verifies its device on first run.

1. After restarts, the bot reuses its saved device and crypto state. No manual steps needed.
2. If things are really broken, delete `data/device.json` and `data/gogobee.db` to start fresh.

### Bot not responding in encrypted rooms

- Check that the bot joined the room (it auto-joins on invite)
- Look at logs for decryption errors

### API commands not working

- Check that the relevant API key is set in `.env`
- Look at logs for error messages
- Most APIs have rate limits; the bot caches responses to stay within them

### Build errors about libolm

```bash
# use the goolm tag:
go build -tags goolm -o gogobee .
```

---

## License

MIT