fix: remove spurious f-string prefix (ruff F541)

- Add !cancel command (anyone cancels own blackjack; PL50+ clears all room games)
- Add !wordlestats top-level command (wraps wordle stats function)
- Add !cleanwelcome admin command to purge stale welcome DM records
- !help now hides management section from sub-PL50 users, hides !health from non-admins
- !announce uses nio room cache for join_rule instead of an API call per room
- Fix _INVITEALL_BLOCKED comment (Commands is knock-gated, not restricted)
- welcome.py: skip duplicate DM if a pending welcome already exists for the user
- welcome.py: add clean_stale_dm_messages() helper
- welcome.py: replace no-op post_welcome_message with log_ready()
- bot.py: update import/call to match welcome.py rename

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitea/workflows/lint.yml

@@ -30,3 +30,66 @@ jobs:
 
       - name: Run ESLint
         run: npx eslint --ext .js hookshot/
+
+  python-lint:
+    name: Python (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install ruff
+        run: |
+          curl -sSL https://github.com/astral-sh/ruff/releases/download/0.8.6/ruff-x86_64-unknown-linux-gnu.tar.gz \
+            | tar -xz --strip-components=1
+          mv ruff /usr/local/bin/ruff
+
+      - name: Check syntax errors
+        run: ruff check matrixbot/ --select E9,F63,F7,F82 --output-format=github
+
+      - name: Run full lint
+        run: ruff check matrixbot/ --output-format=github
+
+  python-audit:
+    name: Python deps (pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install Python 3.10 and pip-audit
+        run: |
+          # Debian Bullseye only ships Python 3.9; use a prebuilt standalone binary
+          curl -sSL "https://github.com/indygreg/python-build-standalone/releases/download/20241002/cpython-3.10.15+20241002-x86_64-unknown-linux-gnu-install_only.tar.gz" \
+            | tar -xz -C /opt
+          # Install bot deps + pip-audit into the same env; --local below avoids
+          # pip-audit creating an internal venv (ensurepip fails on standalone builds)
+          /opt/python/bin/pip install --upgrade pip setuptools
+          /opt/python/bin/pip install pip-audit -r matrixbot/requirements.txt
+
+      - name: Audit matrixbot dependencies
+        # --local scans the env without spawning a venv (required for standalone Python)
+        # CVE-2026-3219 is in pip itself, not our code — ignore it explicitly
+        run: /opt/python/bin/pip-audit --local --ignore-vuln CVE-2026-3219
+
+  secret-scan:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install gitleaks
+        run: |
+          curl -sSL https://github.com/gitleaks/gitleaks/releases/download/v8.21.2/gitleaks_8.21.2_linux_x64.tar.gz \
+            | tar -xz gitleaks
+          mv gitleaks /usr/local/bin/gitleaks
+
+      - name: Scan for secrets
+        run: |
+          # Scan application code directories — deploy/ is excluded because
+          # it contains intentional Gitea webhook HMAC secrets in hooks-lxc*.json
+          for dir in matrixbot/ hookshot/ .gitea/ systemd/ cinny/ landing/; do
+            [ -d "$dir" ] || continue
+            gitleaks detect --source "$dir" --no-git --config .gitleaks.toml \
+              --redact --exit-code 1
+          done

.gitleaks.toml

@@ -0,0 +1,2 @@
+[extend]
+useDefault = true

README.md

@@ -6,25 +6,6 @@ Matrix server infrastructure for the Lotus Guild homeserver (`matrix.lotusguild.
 
 **Repo**: https://code.lotusguild.org/LotusGuild/matrix
 
-## Status: Phase 7 — Moderation & Client Customisation
-
----
-
-## Priority Order
-1. ~~PostgreSQL migration~~
-2. ~~TURN server~~
-3. ~~Room structure + space setup~~
-4. ~~Matrix bot (core + commands)~~
-5. ~~LiveKit / Element Call~~
-6. ~~SSO / OIDC (Authelia)~~
-7. ~~Webhook integrations (hookshot)~~
-8. ~~Voice stability & quality tuning~~
-9. ~~Custom Cinny client (chat.lotusguild.org)~~
-10. Custom emoji packs (partially finished)
-11. Cinny custom branding (Lotus Guild theme)
-12. ~~Draupnir moderation bot~~
-13. Push notifications (Sygnal)
-
 ---
 
 ## Repo Structure
@@ -66,18 +47,18 @@ matrix/
 
 ## Infrastructure
 
-| Service | IP | LXC | RAM | vCPUs | Disk | Versions |
-|---------|----|-----|-----|-------|------|----------|
-| Synapse | 10.10.10.29 | 151 | 8GB | 4 (Ryzen 9 7900) | 50GB | Synapse 1.149.0, LiveKit 1.9.11, hookshot 7.3.2, coturn latest |
-| PostgreSQL 17 | 10.10.10.44 | 109 | 6GB | 3 (Ryzen 9 7900) | 30GB | PostgreSQL 17.9 |
-| Cinny Web | 10.10.10.6 | 106 | 2GB | 1 | 8GB | Debian 12, nginx, Node 24, Cinny `dev` branch (nightly build) |
-| Draupnir | 10.10.10.24 | 110 | 1GB | 2 (Ryzen 9 7900) | 10GB | Draupnir v2.9.0, Node.js v22 |
-| Prometheus | 10.10.10.48 | 118 | — | — | — | Prometheus — scrapes all Matrix services |
-| Grafana | 10.10.10.49 | 107 | — | — | — | Grafana 12.4.0 — dashboard.lotusguild.org |
-| NPM | 10.10.10.27 | 139 | — | — | — | Nginx Proxy Manager + matrix landing page |
-| Authelia | 10.10.10.36 | 167 | — | — | — | SSO/OIDC provider |
-| LLDAP | 10.10.10.39 | 147 | — | — | — | LDAP user directory |
-| Uptime Kuma | 10.10.10.25 | 101 | — | — | — | Uptime monitoring (micro1 node) |
+| Service | IP | LXC | RAM | Disk | Versions |
+|---------|----|-----|-----|------|----------|
+| Synapse | 10.10.10.29 | 151 | 8GB | 50GB | Synapse 1.149.0, LiveKit 1.9.11, hookshot 7.3.2, coturn latest |
+| PostgreSQL 17 | 10.10.10.44 | 109 | 6GB | 30GB | PostgreSQL 17.9 |
+| Cinny Web | 10.10.10.6 | 106 | 2GB | 8GB | Debian 12, nginx, Node 24, Cinny `dev` branch (nightly build) |
+| Draupnir | 10.10.10.24 | 110 | 1GB | 10GB | Draupnir v2.9.0, Node.js v22 |
+| Prometheus | 10.10.10.48 | 118 | — | — | Prometheus — scrapes all Matrix services |
+| Grafana | 10.10.10.49 | 107 | — | — | Grafana 12.4.0 — dashboard.lotusguild.org |
+| NPM | 10.10.10.27 | 139 | — | — | Nginx Proxy Manager + matrix landing page |
+| Authelia | 10.10.10.36 | 167 | — | — | SSO/OIDC provider |
+| LLDAP | 10.10.10.39 | 147 | — | — | LDAP user directory |
+| Uptime Kuma | 10.10.10.25 | 101 | — | — | Uptime monitoring (micro1 node) |
 
 **Key paths on Synapse LXC (151):**
 - Synapse config: `/etc/matrix-synapse/homeserver.yaml`
@@ -541,6 +522,75 @@ Periodic `TLS/TCP socket error: Connection reset by peer` in coturn logs. Normal
 
 ---
 
+## LotusBot
+
+LotusBot (`@lotusbot:matrix.lotusguild.org`) is a Matrix bot running on LXC 151 at `/opt/matrixbot/`.  
+All commands use the `!` prefix. Run `!help` in any room for the full list.
+
+### AI / Fun
+
+| Command | Description |
+|---------|-------------|
+| `!ask <question>` | Ask the AI anything |
+| `!fortune` | Get a fortune cookie |
+| `!8ball <question>` | Magic 8-ball (yes/no/maybe, funny style). `--debug` shows raw AI output |
+| `!roast @user` | Roast someone |
+| `!story <prompt>` | Generate a short story |
+| `!debate <topic>` | AI argues both sides of a topic |
+
+### Games
+
+| Command | Description |
+|---------|-------------|
+| `!wordle` | Daily Wordle-style word game |
+| `!trivia [category]` | Trivia question (gaming/tech/movies/music/science/anime/etc.) |
+| `!rps <rock\|paper\|scissors>` | Rock Paper Scissors |
+| `!poll <question> \| option1 \| option2...` | Create a reaction poll |
+| `!hangman [--hard] [--extended]` | Hangman — `--hard` uses long words, `--extended` adds more body parts |
+| `!guess <letter or word>` | Guess a letter or the full word in hangman |
+| `!scramble` | Unscramble the word before time runs out |
+| `!wyr` | Would You Rather — two AI-generated options, vote with reactions |
+| `!riddle` | AI generates a riddle — try to solve it! |
+| `!numguess` | Number Guess — bot picks 1–100 |
+| `!ng <number>` | Guess in an active number game (temperature hints included) |
+| `!wordchain` | Word Chain — each word must start with the last letter of the previous |
+| `!wc <word>` | Add a word to the chain |
+| `!endwc` | End the word chain and see the final score |
+| `!acronym` | AI picks an acronym — submit the funniest expansion with `!ac` then vote |
+| `!ac <expansion>` | Submit an acronym expansion |
+| `!20q` | 20 Questions — AI thinks of something, you ask yes/no questions |
+| `!q <question>` | Ask a yes/no question in 20Q |
+| `!answer <guess>` | Guess the answer in 20Q |
+| `!nhie` | Never Have I Ever — react 🙋 (have) or 🙅 (never) |
+| `!hottake` | AI generates a hot take — react 🔥 (agree) or 💧 (disagree) |
+| `!ttt @user` | Tic-Tac-Toe — challenge someone |
+| `!move <1-9>` | Make a move in Tic-Tac-Toe |
+| `!blackjack` | Play Blackjack against the dealer |
+| `!hit` | Draw another card in Blackjack |
+| `!stand` | Stand — dealer plays out |
+| `!triviaduel @user` | Trivia Duel — first-to-3 battle |
+| `!da <A/B/C/D or answer>` | Answer in a Trivia Duel |
+
+### Random
+
+| Command | Description |
+|---------|-------------|
+| `!flip` | Flip a coin |
+| `!roll [NdN]` | Roll dice (e.g. `!roll 2d6`) |
+| `!random <min> <max>` | Random number in range |
+| `!champion` | Pick a random champion |
+| `!agent [role]` | Pick a random Valorant agent |
+
+### Server
+
+| Command | Description |
+|---------|-------------|
+| `!minecraft` | Check Minecraft server status |
+| `!ping` | Check bot latency |
+| `!health` | Bot health + uptime stats |
+
+---
+
 ## Tech Stack
 
 | Component | Technology | Version |

deploy/lxc151-hookshot.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Auto-deploy script for LXC 151 (matrix homeserver)
-# Handles: hookshot transformation functions, livekit service file (graceful)
+# Handles: hookshot transformation functions, livekit service file (graceful), matrixbot
 # Triggered by: Gitea webhook on push to main
 set -euo pipefail
 
@@ -45,6 +45,25 @@ else
         touch /run/livekit-restart-pending
         echo "Restart pending — will apply when no active calls."
     fi
+
+    # Matrixbot source files
+    if echo "$CHANGED" | grep -q '^matrixbot/'; then
+        echo "Deploying matrixbot changes..."
+        BOT_DIR="/opt/matrixbot"
+        BOT_FILES="bot.py callbacks.py commands.py config.py utils.py welcome.py wordle.py wordlist_answers.py wordlist_valid.py requirements.txt"
+        for f in $BOT_FILES; do
+            if [ -f "$REPO_DIR/matrixbot/$f" ]; then
+                cp "$REPO_DIR/matrixbot/$f" "$BOT_DIR/$f"
+            fi
+        done
+        systemctl restart matrixbot
+        sleep 2
+        if systemctl is-active --quiet matrixbot; then
+            echo "matrixbot restarted successfully."
+        else
+            echo "ERROR: matrixbot failed to restart."
+        fi
+    fi
 fi
 
 echo "=== $(date) === LXC151 deploy complete ==="

matrixbot/.env.example

@@ -0,0 +1,15 @@
+MATRIX_HOMESERVER=https://matrix.lotusguild.org
+MATRIX_USER_ID=@lotusbot:matrix.lotusguild.org
+MATRIX_ACCESS_TOKEN=
+MATRIX_DEVICE_ID=
+BOT_PREFIX=!
+ADMIN_USERS=@jared:matrix.lotusguild.org
+LOG_LEVEL=INFO
+
+# Integrations
+OLLAMA_URL=http://10.10.10.157:11434
+OLLAMA_MODEL=lotusllm
+MINECRAFT_RCON_HOST=10.10.10.67
+MINECRAFT_RCON_PORT=25575
+MINECRAFT_RCON_PASSWORD=
+COOLDOWN_SECONDS=120

matrixbot/.gitignore

@@ -0,0 +1,22 @@
+# Python venv
+bin/
+lib/
+lib64
+include/
+pyvenv.cfg
+__pycache__/
+*.pyc
+*.pyo
+
+# Secrets — never commit these
+.env
+credentials.json
+
+# Runtime state
+logs/
+nio_store/
+welcome_state.json
+wordle_stats.json
+
+# Stale copy
+app/

matrixbot/README.md

@@ -0,0 +1,229 @@
+# Lotus Matrix Bot & Server Roadmap
+
+Matrix bot and server improvements for the Lotus Guild homeserver (`matrix.lotusguild.org`).
+
+**Repo**: https://code.lotusguild.org/LotusGuild/matrixBot
+
+## Status: Phase 3 — Bot Features & SSO
+
+---
+
+## Priority Order (suggested)
+1. ~~PostgreSQL migration~~
+2. ~~TURN server~~
+3. ~~Room structure + space setup~~
+4. ~~Matrix bot (core + commands)~~
+5. ~~LiveKit / Element Call~~
+6. ~~SSO / OIDC (Authelia)~~
+7. Custom Element Web (chat.lotusguild.org with branding)
+8. Discord bridge (lets people transition gradually)
+9. Custom emoji packs (makes it feel like home)
+10. Moderation bot
+11. Everything else
+
+---
+
+## Infrastructure
+
+| Service | Host | IP | LXC | Notes |
+|---------|------|-----|-----|-------|
+| Synapse | micro1 | 10.10.10.29 | 151 | Homeserver + coturn + LiveKit |
+| PostgreSQL 17 | micro1 | 10.10.10.44 | 109 | Synapse database backend |
+| NPM | large1 | 10.10.10.27 | 139 | Reverse proxy + landing page |
+| Authelia | compute-storage-01 | 10.10.10.36 | 167 | SSO/OIDC provider |
+| LLDAP | large1 | 10.10.10.39 | 147 | LDAP user directory |
+
+**Key paths on Synapse LXC (10.10.10.29):**
+- Synapse config: `/etc/matrix-synapse/homeserver.yaml`
+- Synapse venv: `/opt/venvs/matrix-synapse/`
+- coturn config: `/etc/turnserver.conf`
+- LiveKit config: `/etc/livekit/config.yaml`
+- LiveKit service: `livekit-server.service` (systemd)
+- Synapse admin UI: `/var/www/synapse-admin/` (nginx on :8080)
+- Landing page: `/var/www/matrix-landing/index.html` (on NPM LXC 139)
+
+**Port forwarding (router -> 10.10.10.29):**
+- TCP+UDP 3478 (TURN signaling)
+- TCP 7881 (LiveKit TCP)
+- UDP 49152-65535 (media relay)
+- UDP 50100-50200 (LiveKit WebRTC media)
+
+---
+
+## Rooms (all v12)
+
+| Room | Room ID | Join Rule | Bot In |
+|------|---------|-----------|--------|
+| The Lotus Guild (space) | `!gSynpxmopNrtoxeSvj` | public | — |
+| General | `!wfokQ1-pE896scu_AOcCBA2s3L4qFo-PTBAFTd0WMI0` | public | no |
+| Welcome | `!Y-wvNosuytqBOWampH9k-ta7bYXW7okqwBQ7PuRVBWE` | public | yes |
+| Commands | `!ou56mVZQ8ZB7AhDYPmBV5_BR28WMZ4x5zwZkPCqjq1s` | restricted | yes |
+| Management | `!mEvR5fe3jMmzwd-FwNygD72OY_yu8H3UP_N-57oK7MI` | invite | no |
+| Memes | `!GK6v5cLEEnowIooQJv5jECfISUjADjt8aKhWv9VbG5U` | public | no |
+| Cool Kids | `!R7DT3QZHG9P8QQvX6zsZYxjkKgmUucxDz_n31qNrC94` | invite | no |
+
+**Power level roles (Cinny tags):**
+- 100: Owner (jared)
+- 50: The Nerdy Council (enhuynh, lonely)
+- 48: Panel of Geeks
+- 35: Cool Kids
+- 0: Member
+
+**Welcome room** has `events_default: 50` (users can't message) but `m.reaction: 0` (users can react to the welcome message to get invited to channels).
+
+---
+
+## Server - Quality of Life
+- [x] Migrate from SQLite to PostgreSQL
+- [x] Set up TURN/STUN server (coturn) for reliable voice/video calls behind NAT
+- [x] Enable URL previews in Synapse
+- [x] Increase upload size limit for media/GIFs (200MB)
+- [x] Enable message search (full-text search with PostgreSQL backend)
+- [x] Configure media retention policy (remote: 1yr, local: 3yr)
+- [x] Set up sliding sync (native in Synapse, no proxy needed)
+- [x] LiveKit server with systemd service for Element Call video rooms
+- [x] Default room version set to v12, all rooms upgraded
+- [x] Room publishing rules (jared + lotusbot can publish to directory)
+- [ ] Enable push notifications gateway for mobile clients
+
+## Server - Auth & SSO
+- [x] Token-based registration (registration tokens shared in Discord)
+- [x] SSO/OIDC via Authelia (`oidc_providers` in homeserver.yaml)
+- [x] `allow_existing_users: true` for linking existing accounts to SSO
+- [x] Password auth remains enabled alongside SSO
+
+## Server - Hardening
+- [x] Rate limiting configuration in Synapse
+- [x] E2EE enabled on all rooms
+- [ ] Federation allow/deny lists (decide if you want open federation or Lotus-only)
+- [ ] Regular Synapse version updates
+- [ ] Monitoring with Prometheus + Grafana
+- [ ] Synapse worker mode if performance becomes an issue
+
+## Server - Admin & Moderation
+- [x] Synapse admin API dashboard (synapse-admin v0.11.1 at http://10.10.10.29:8080)
+- [x] Power levels configured per room (Cinny tags for role hierarchy)
+- [x] Invite-only registration flow (token-based)
+- [ ] Set up Mjolnir or Draupnir (moderation bot for ban lists, spam protection)
+- [ ] Set up room ACLs for federation control (block known-bad servers)
+- [ ] Automated backups of Synapse database and media
+
+## Bridging (Transition Period)
+- [ ] Set up mautrix-discord bridge so messages flow between Discord and Matrix
+- [ ] Bridge key channels (general, gaming, memes, etc.)
+- [ ] Bridge voice channels if possible (experimental, may not be worth it)
+- [ ] Puppet bridging so Discord users appear as Matrix users and vice versa
+
+## Room Structure
+- [x] Set up "The Lotus Guild" space as top-level container
+- [x] General, Welcome, Commands, Management, Memes, Cool Kids rooms
+- [x] Welcome room with react-to-join onboarding
+- [x] Bot commands room (Commands — keeps bot spam contained)
+- [x] Voice/video call room (Element Call via LiveKit)
+- [x] Custom room avatars with Lotus Guild branding
+- [ ] Sub-spaces for categories (Gaming, Media, etc.)
+- [ ] Read-only announcements room
+- [ ] Game-specific rooms (Minecraft, Valorant, League, Hytale, etc.)
+
+## Custom Emoji & Stickers
+- [ ] Export all custom emojis from Discord server
+- [ ] Create Matrix emoji packs (per-room or space-wide)
+- [ ] Set up sticker picker widget in Element
+- [ ] Import/create Lotus Guild sticker pack
+
+## Element/Client Customization
+- [x] Landing page at matrix.lotusguild.org with client recommendations (Cinny, Commet, Element)
+- [ ] Custom Element Web instance (self-hosted on chat.lotusguild.org)
+- [ ] Custom theme with #980000 branding
+- [ ] Configure .well-known to point clients to custom Element Web instance
+
+## Widgets & Integrations
+- [ ] RSS bot for game news feeds
+- [ ] GitHub/Gitea notifications bot (push events to a dev room)
+
+---
+
+## Bot - Core Setup
+- [x] Project scaffolding (`bot.py`, config, `.env`, requirements)
+- [x] matrix-nio async client with E2EE support
+- [x] Device verification / trust storage (auto-trust all devices)
+- [x] Logging (rotating file + stdout)
+- [x] Config validation (homeserver URL, access token, device ID)
+- [x] Graceful shutdown handling (SIGTERM/SIGINT)
+- [x] Initial sync with startup token (ignores old messages)
+- [x] Auto-accept room invites
+
+## Bot - Commands (all implemented)
+- [x] `!help` — List all available commands
+- [x] `!ping` — Bot latency check
+- [x] `!8ball <question>` — Magic 8-ball
+- [x] `!fortune` — Fortune cookie message
+- [x] `!flip` — Coin flip
+- [x] `!roll <NdS>` — Dice roller
+- [x] `!random <min> <max>` — Random number generator
+- [x] `!rps <choice>` — Rock Paper Scissors
+- [x] `!poll <question>` — Poll (reactions)
+- [x] `!trivia` — Trivia game (reactions, 30s reveal)
+- [x] `!champion [lane]` — Random LoL champion picker
+- [x] `!agent [role]` — Random Valorant agent picker
+- [x] `!wordle` — Full Wordle game (daily puzzles, hard mode, stats, share)
+
+## Bot - Integrations
+- [x] `!minecraft <username>` — RCON whitelist
+- [x] `!ask <question>` — Ollama LLM integration (lotusllm, 2min cooldown)
+
+## Bot - Admin Commands
+- [x] `!health` — Bot stats (uptime, command counts, service status)
+
+## Bot - Welcome System
+- [x] Auto-post welcome message in Welcome room on startup
+- [x] React-to-join: users react with checkmark, bot invites to General, Commands, Memes
+- [x] Welcome message event ID persisted to `welcome_state.json`
+- [x] Reaction handler via `UnknownEvent` callback for `m.reaction` events
+
+## Bot - Wordle
+- [x] Daily puzzles with proper two-pass letter evaluation
+- [x] Hard mode with constraint validation
+- [x] Statistics tracking with persistence (`wordle_stats.json`)
+- [x] Cinny-compatible rendering (inline `<span>` tiles instead of `<table>`)
+- [x] DM-based gameplay (games happen in DMs, `!wordle share` posts to public room)
+- [x] Virtual keyboard display with letter state tracking
+
+## Bot - Deployment
+- [ ] Systemd service (`matrixbot.service`)
+- [ ] Auto-deploy from Gitea webhook
+- [ ] Deployment script
+- **Bot lives in**: Welcome (react-to-join) and Commands (all commands)
+
+## Bot - Not Porting (Discord-specific)
+- Reaction roles (replaced by react-to-join in Welcome room)
+- Status cycling (Matrix presence is simpler)
+- Guild-specific event handlers (channel create/delete, boost, etc.)
+
+---
+
+## Tech Stack
+- **Language**: Python 3
+- **Library**: matrix-nio (with E2EE)
+- **Homeserver**: matrix.lotusguild.org (Synapse on 10.10.10.29)
+- **Database**: PostgreSQL 17 on 10.10.10.44
+- **TURN**: coturn on 10.10.10.29 (colocated with Synapse)
+- **LiveKit**: livekit-server on 10.10.10.29 (systemd, public IP 162.192.14.139)
+- **SSO**: Authelia on 10.10.10.36 (OIDC provider, backed by LLDAP)
+- **Dependencies**: matrix-nio[e2ee], aiohttp, python-dotenv, mcrcon
+
+## Bot Files
+```
+matrixBot/
+├── bot.py              # Entry point, client setup, event callbacks
+├── callbacks.py        # Message + reaction event handlers
+├── commands.py         # Command registry + all command implementations
+├── config.py           # Environment config + validation
+├── utils.py            # send_text, send_html, send_reaction, get_or_create_dm
+├── welcome.py          # Welcome message + react-to-join logic
+├── wordle.py           # Full Wordle game engine
+├── wordlist_answers.py # Wordle answer word list
+├── wordlist_valid.py   # Wordle valid guess word list
+├── .env.example        # Environment template
+└── requirements.txt    # Python dependencies
+```

matrixbot/bot.py

@@ -0,0 +1,204 @@
+import asyncio
+import json
+import signal
+import sys
+from pathlib import Path
+
+from nio import (
+    AsyncClient,
+    AsyncClientConfig,
+    InviteMemberEvent,
+    LoginResponse,
+    ReactionEvent,
+    RoomMemberEvent,
+    RoomMessageText,
+    UnknownEvent,
+)
+
+from config import (
+    MATRIX_HOMESERVER,
+    MATRIX_USER_ID,
+    MATRIX_ACCESS_TOKEN,
+    MATRIX_DEVICE_ID,
+    MATRIX_PASSWORD,
+    LOG_LEVEL,
+    ConfigValidator,
+)
+from callbacks import Callbacks
+from utils import setup_logging
+from welcome import log_ready as _welcome_log_ready
+
+logger = setup_logging(LOG_LEVEL)
+
+CREDENTIALS_FILE = Path("credentials.json")
+STORE_PATH = Path("nio_store")
+
+
+def save_credentials(resp, homeserver):
+    data = {
+        "homeserver": homeserver,
+        "user_id": resp.user_id,
+        "device_id": resp.device_id,
+        "access_token": resp.access_token,
+    }
+    CREDENTIALS_FILE.write_text(json.dumps(data, indent=2))
+    logger.info("Credentials saved to %s", CREDENTIALS_FILE)
+
+
+async def trust_devices(client: AsyncClient):
+    """Query keys and trust all devices for all users we share rooms with."""
+    if not client.olm:
+        logger.warning("Olm not loaded, skipping device trust")
+        return
+
+    # Collect all users across all joined rooms
+    users = set()
+    for room in client.rooms.values():
+        for user_id in room.users:
+            users.add(user_id)
+
+    # Fetch device keys so the store is complete
+    if users:
+        await client.keys_query()
+
+    # Trust every device
+    for user_id, devices in client.device_store.items():
+        for device_id, olm_device in devices.items():
+            if not client.olm.is_device_verified(olm_device):
+                client.verify_device(olm_device)
+    logger.info("Trusted all known devices (%d users)", len(users))
+
+
+async def main():
+    errors = ConfigValidator.validate()
+    if errors:
+        for e in errors:
+            logger.error(e)
+        sys.exit(1)
+
+    STORE_PATH.mkdir(exist_ok=True)
+
+    client_config = AsyncClientConfig(
+        store_sync_tokens=True,
+        encryption_enabled=True,
+        store_name="matrixbot",
+    )
+
+    client = AsyncClient(
+        MATRIX_HOMESERVER,
+        MATRIX_USER_ID,
+        device_id=MATRIX_DEVICE_ID or None,
+        config=client_config,
+        store_path=str(STORE_PATH),
+    )
+
+    # Try saved credentials first, then .env token, then password login
+    logged_in = False
+    has_creds = False
+
+    if CREDENTIALS_FILE.exists():
+        creds = json.loads(CREDENTIALS_FILE.read_text())
+        client.access_token = creds["access_token"]
+        client.user_id = creds["user_id"]
+        client.device_id = creds["device_id"]
+        has_creds = True
+        logger.info("Loaded credentials from %s", CREDENTIALS_FILE)
+    elif MATRIX_ACCESS_TOKEN and MATRIX_DEVICE_ID:
+        client.access_token = MATRIX_ACCESS_TOKEN
+        client.user_id = MATRIX_USER_ID
+        client.device_id = MATRIX_DEVICE_ID
+        has_creds = True
+        logger.info("Using access token from .env")
+
+    # Load the olm/e2ee store only if we have a device_id
+    if has_creds:
+        client.load_store()
+
+    # Test the token with a sync; if it fails, fall back to password login
+    if has_creds and client.access_token:
+        logger.info("Testing existing access token...")
+        sync_resp = await client.sync(timeout=30000, full_state=True)
+        if hasattr(sync_resp, "next_batch"):
+            logged_in = True
+            logger.info("Existing token is valid")
+        else:
+            logger.warning("Existing token is invalid, will try password login")
+            client.access_token = ""
+
+    if not logged_in:
+        if not MATRIX_PASSWORD:
+            logger.error("No valid token and no MATRIX_PASSWORD set — cannot authenticate")
+            await client.close()
+            sys.exit(1)
+        logger.info("Logging in with password...")
+        login_resp = await client.login(MATRIX_PASSWORD, device_name="LotusBot")
+        if isinstance(login_resp, LoginResponse):
+            logger.info("Password login successful, device_id=%s", login_resp.device_id)
+            save_credentials(login_resp, MATRIX_HOMESERVER)
+            client.load_store()
+            sync_resp = await client.sync(timeout=30000, full_state=True)
+        else:
+            logger.error("Password login failed: %s", login_resp)
+            await client.close()
+            sys.exit(1)
+
+    callbacks = Callbacks(client)
+    client.add_event_callback(callbacks.message, RoomMessageText)
+    client.add_event_callback(callbacks.reaction, ReactionEvent)
+    client.add_event_callback(callbacks.unknown_event, UnknownEvent)
+    client.add_event_callback(callbacks.member, RoomMemberEvent)
+
+    # Auto-accept room invites
+    async def _auto_accept_invite(room, event):
+        if event.membership == "invite" and event.state_key == MATRIX_USER_ID:
+            logger.info("Auto-accepting invite to %s", room.room_id)
+            await client.join(room.room_id)
+
+    client.add_event_callback(_auto_accept_invite, InviteMemberEvent)
+
+    # Graceful shutdown
+    loop = asyncio.get_running_loop()
+    shutdown_event = asyncio.Event()
+
+    def _signal_handler():
+        logger.info("Shutdown signal received")
+        shutdown_event.set()
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        loop.add_signal_handler(sig, _signal_handler)
+
+    # Mark startup complete from the initial sync
+    if hasattr(sync_resp, "next_batch"):
+        callbacks.startup_sync_token = sync_resp.next_batch
+        logger.info("Initial sync complete, token: %s", sync_resp.next_batch[:20])
+    else:
+        logger.error("Initial sync failed: %s", sync_resp)
+        await client.close()
+        sys.exit(1)
+
+    # Trust devices after initial sync loads the device store
+    await trust_devices(client)
+
+    _welcome_log_ready()
+
+    logger.info("Bot ready as %s — listening for commands", MATRIX_USER_ID)
+
+    # Run sync_forever in a task so we can cancel on shutdown
+    async def _sync_loop():
+        await client.sync_forever(timeout=30000, full_state=False)
+
+    sync_task = asyncio.create_task(_sync_loop())
+
+    await shutdown_event.wait()
+    sync_task.cancel()
+    try:
+        await sync_task
+    except asyncio.CancelledError:
+        pass
+
+    await client.close()
+    logger.info("Bot shut down cleanly")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

matrixbot/callbacks.py

@@ -0,0 +1,145 @@
+import logging
+from functools import wraps
+
+from nio import AsyncClient
+
+from config import BOT_PREFIX, MATRIX_USER_ID
+from commands import (
+    COMMANDS,
+    metrics,
+    check_scramble_answer,
+    check_riddle_answer,
+    record_wyr_vote,
+    record_acronym_vote,
+    record_nhie_reaction,
+    record_hottake_reaction,
+)
+from welcome import handle_welcome_reaction, handle_space_join, SPACE_ROOM_ID
+
+logger = logging.getLogger("matrixbot")
+
+
+def handle_command_errors(func):
+    @wraps(func)
+    async def wrapper(client, room_id, sender, args):
+        try:
+            return await func(client, room_id, sender, args)
+        except Exception as e:
+            logger.error(f"Error in command {func.__name__}: {e}", exc_info=True)
+            metrics.record_error(func.__name__)
+            try:
+                from utils import send_text
+                await send_text(client, room_id, "An unexpected error occurred. Please try again later.")
+            except Exception as e2:
+                logger.error(f"Failed to send error message: {e2}", exc_info=True)
+    return wrapper
+
+
+class Callbacks:
+    def __init__(self, client: AsyncClient):
+        self.client = client
+        # Track the sync token so we ignore old messages on startup
+        self.startup_sync_token = None
+
+    async def message(self, room, event):
+        # Ignore messages from before the bot started
+        if self.startup_sync_token is None:
+            return
+
+        # Ignore our own messages
+        if event.sender == MATRIX_USER_ID:
+            return
+
+        body = event.body.strip() if event.body else ""
+
+        # Check active non-command games that monitor all room messages
+        if body and not body.startswith(BOT_PREFIX):
+            await check_scramble_answer(self.client, room.room_id, event.sender, body)
+            await check_riddle_answer(self.client, room.room_id, event.sender, body)
+            return
+
+        if not body.startswith(BOT_PREFIX):
+            return
+
+        # Parse command and args
+        without_prefix = body[len(BOT_PREFIX):]
+        parts = without_prefix.split(None, 1)
+        cmd_name = parts[0].lower() if parts else ""
+        args = parts[1] if len(parts) > 1 else ""
+
+        logger.info(f"Command '{cmd_name}' from {event.sender} in {room.room_id}")
+
+        handler_entry = COMMANDS.get(cmd_name)
+        if handler_entry is None:
+            return
+
+        handler, _ = handler_entry
+        metrics.record_command(cmd_name)
+        wrapped = handle_command_errors(handler)
+        await wrapped(self.client, room.room_id, event.sender, args)
+
+    async def reaction(self, room, event):
+        """Handle ReactionEvent (nio's native reaction type)."""
+        if self.startup_sync_token is None:
+            return
+        if event.sender == MATRIX_USER_ID:
+            return
+
+        reacted_event_id = event.reacts_to
+        key = event.key
+        logger.info("reaction: key=%r target=%s sender=%s", key, reacted_event_id[:16], event.sender)
+
+        await handle_welcome_reaction(self.client, room.room_id, event.sender, reacted_event_id, key)
+        record_wyr_vote(reacted_event_id, event.sender, key)
+        record_acronym_vote(reacted_event_id, event.sender, key)
+        record_nhie_reaction(reacted_event_id, event.sender, key)
+        record_hottake_reaction(reacted_event_id, event.sender, key)
+
+    async def unknown_event(self, room, event):
+        """Fallback handler for UnknownEvent — catches any m.reaction not parsed by nio."""
+        if self.startup_sync_token is None:
+            return
+        if event.sender == MATRIX_USER_ID:
+            return
+        if not hasattr(event, "source"):
+            return
+
+        content = event.source.get("content", {})
+        relates_to = content.get("m.relates_to", {})
+        if relates_to.get("rel_type") != "m.annotation":
+            return
+
+        reacted_event_id = relates_to.get("event_id", "")
+        key = relates_to.get("key", "")
+        logger.info("unknown_event reaction: key=%r target=%s sender=%s", key, reacted_event_id[:16], event.sender)
+
+        await handle_welcome_reaction(self.client, room.room_id, event.sender, reacted_event_id, key)
+        record_wyr_vote(reacted_event_id, event.sender, key)
+        record_acronym_vote(reacted_event_id, event.sender, key)
+        record_nhie_reaction(reacted_event_id, event.sender, key)
+        record_hottake_reaction(reacted_event_id, event.sender, key)
+
+    async def member(self, room, event):
+        """Handle m.room.member events — watch for Space joins."""
+        # Ignore events from before startup
+        if self.startup_sync_token is None:
+            return
+
+        # Only care about the Space
+        if room.room_id != SPACE_ROOM_ID:
+            return
+
+        # Ignore our own membership changes
+        if event.state_key == MATRIX_USER_ID:
+            return
+
+        # Only trigger on joins (not leaves, bans, etc.)
+        if event.membership != "join":
+            return
+
+        # Check if this is a new join (prev was not "join")
+        prev = event.prev_membership if hasattr(event, "prev_membership") else None
+        if prev == "join":
+            return  # Already was a member, this is a profile update or similar
+
+        await handle_space_join(self.client, event.state_key)

matrixbot/config.py

@@ -0,0 +1,47 @@
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+# Required
+MATRIX_HOMESERVER = os.getenv("MATRIX_HOMESERVER", "https://matrix.lotusguild.org")
+MATRIX_USER_ID = os.getenv("MATRIX_USER_ID", "@lotusbot:matrix.lotusguild.org")
+MATRIX_ACCESS_TOKEN = os.getenv("MATRIX_ACCESS_TOKEN", "")
+MATRIX_DEVICE_ID = os.getenv("MATRIX_DEVICE_ID", "")
+MATRIX_PASSWORD = os.getenv("MATRIX_PASSWORD", "")
+
+# Bot settings
+BOT_PREFIX = os.getenv("BOT_PREFIX", "!")
+ADMIN_USERS = [u.strip() for u in os.getenv("ADMIN_USERS", "").split(",") if u.strip()]
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
+
+# Integrations
+OLLAMA_URL = os.getenv("OLLAMA_URL", "http://10.10.10.157:11434")
+OLLAMA_MODEL = os.getenv("OLLAMA_MODEL", "phi4-mini:latest")
+CREATIVE_MODEL = os.getenv("CREATIVE_MODEL", "huihui_ai/llama3.2-abliterate:3b")
+ASK_MODEL = os.getenv("ASK_MODEL", "phi4-mini:latest")
+MINECRAFT_RCON_HOST = os.getenv("MINECRAFT_RCON_HOST", "10.10.10.67")
+MINECRAFT_RCON_PORT = int(os.getenv("MINECRAFT_RCON_PORT", "25575"))
+MINECRAFT_RCON_PASSWORD = os.getenv("MINECRAFT_RCON_PASSWORD", "")
+
+# Constants
+MAX_INPUT_LENGTH = 500
+MAX_DICE_SIDES = 100
+MAX_DICE_COUNT = 20
+COOLDOWN_SECONDS = int(os.getenv("COOLDOWN_SECONDS", "120"))
+RCON_TIMEOUT = 5.0
+MIN_USERNAME_LENGTH = 3
+MAX_USERNAME_LENGTH = 16
+
+
+class ConfigValidator:
+    REQUIRED = ["MATRIX_HOMESERVER", "MATRIX_USER_ID"]
+
+    @classmethod
+    def validate(cls):
+        errors = []
+        for var in cls.REQUIRED:
+            if not os.getenv(var):
+                errors.append(f"Missing required: {var}")
+        return errors

matrixbot/requirements.txt

@@ -0,0 +1,5 @@
+matrix-nio[e2e]
+python-dotenv>=1.2.2
+aiohttp
+markdown
+mcrcon

matrixbot/utils.py

@@ -0,0 +1,157 @@
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from nio import AsyncClient, RoomSendResponse
+from nio.exceptions import OlmUnverifiedDeviceError
+
+from config import MAX_INPUT_LENGTH
+
+
+def setup_logging(level="INFO"):
+    Path("logs").mkdir(exist_ok=True)
+
+    logger = logging.getLogger("matrixbot")
+    logger.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+    file_handler = RotatingFileHandler(
+        "logs/matrixbot.log",
+        maxBytes=10 * 1024 * 1024,
+        backupCount=5,
+    )
+    file_handler.setFormatter(
+        logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")
+    )
+
+    stream_handler = logging.StreamHandler()
+    stream_handler.setFormatter(
+        logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")
+    )
+
+    logger.addHandler(file_handler)
+    logger.addHandler(stream_handler)
+    return logger
+
+
+def _trust_all(client: AsyncClient):
+    """Trust all devices in the device store."""
+    if not client.olm:
+        return
+    for user_id, devices in client.device_store.items():
+        for device_id, olm_device in devices.items():
+            if not client.olm.is_device_verified(olm_device):
+                client.verify_device(olm_device)
+
+
+async def _room_send_trusted(client: AsyncClient, room_id: str, message_type: str, content: dict):
+    """Send a message, auto-trusting devices on OlmUnverifiedDeviceError."""
+    try:
+        return await client.room_send(
+            room_id, message_type=message_type, content=content,
+            ignore_unverified_devices=True,
+        )
+    except OlmUnverifiedDeviceError:
+        _trust_all(client)
+        return await client.room_send(
+            room_id, message_type=message_type, content=content,
+            ignore_unverified_devices=True,
+        )
+
+
+async def send_text(client: AsyncClient, room_id: str, text: str):
+    logger = logging.getLogger("matrixbot")
+    resp = await _room_send_trusted(
+        client, room_id,
+        message_type="m.room.message",
+        content={"msgtype": "m.text", "body": text},
+    )
+    if not isinstance(resp, RoomSendResponse):
+        logger.error("send_text failed: %s", resp)
+    return resp
+
+
+async def send_html(client: AsyncClient, room_id: str, plain: str, html: str):
+    logger = logging.getLogger("matrixbot")
+    resp = await _room_send_trusted(
+        client, room_id,
+        message_type="m.room.message",
+        content={
+            "msgtype": "m.text",
+            "body": plain,
+            "format": "org.matrix.custom.html",
+            "formatted_body": html,
+        },
+    )
+    if not isinstance(resp, RoomSendResponse):
+        logger.error("send_html failed: %s", resp)
+    return resp
+
+
+async def edit_html(client: AsyncClient, room_id: str, event_id: str, plain: str, html: str):
+    """Edit an existing message in place using m.replace."""
+    logger = logging.getLogger("matrixbot")
+    content = {
+        "msgtype": "m.text",
+        "body": f"* {plain}",
+        "format": "org.matrix.custom.html",
+        "formatted_body": html,
+        "m.new_content": {
+            "msgtype": "m.text",
+            "body": plain,
+            "format": "org.matrix.custom.html",
+            "formatted_body": html,
+        },
+        "m.relates_to": {
+            "rel_type": "m.replace",
+            "event_id": event_id,
+        },
+    }
+    resp = await _room_send_trusted(client, room_id, message_type="m.room.message", content=content)
+    if not isinstance(resp, RoomSendResponse):
+        logger.error("edit_html failed: %s", resp)
+    return resp
+
+
+async def send_reaction(client: AsyncClient, room_id: str, event_id: str, emoji: str):
+    return await _room_send_trusted(
+        client, room_id,
+        message_type="m.reaction",
+        content={
+            "m.relates_to": {
+                "rel_type": "m.annotation",
+                "event_id": event_id,
+                "key": emoji,
+            }
+        },
+    )
+
+
+async def get_or_create_dm(client: AsyncClient, user_id: str) -> str | None:
+    """Find an existing DM room with user_id, or create one. Returns room_id."""
+    logger = logging.getLogger("matrixbot")
+
+    # Check existing rooms for a DM with this user
+    for room_id, room in client.rooms.items():
+        if room.member_count == 2 and user_id in (m.user_id for m in room.users.values()):
+            return room_id
+
+    # Create a new DM room
+    from nio import RoomCreateResponse
+    resp = await client.room_create(
+        is_direct=True,
+        invite=[user_id],
+    )
+    if isinstance(resp, RoomCreateResponse):
+        logger.info("Created DM room %s with %s", resp.room_id, user_id)
+        # Sync so the new room appears in client.rooms before we try to send
+        await client.sync(timeout=5000)
+        return resp.room_id
+
+    logger.error("Failed to create DM room with %s: %s", user_id, resp)
+    return None
+
+
+def sanitize_input(text: str, max_length: int = MAX_INPUT_LENGTH) -> str:
+    text = text.strip()[:max_length]
+    text = "".join(char for char in text if char.isprintable())
+    return text

matrixbot/welcome.py

@@ -0,0 +1,170 @@
+"""Welcome module — DM new Space members.
+
+When a user joins the Space, the bot sends them a DM with a welcome
+message and a reaction button.  When they react, the bot invites them
+to the standard public channels (General, Commands, Memes).
+"""
+
+import json
+import logging
+from pathlib import Path
+
+from nio import AsyncClient
+
+from utils import send_html, send_reaction, get_or_create_dm
+from config import MATRIX_USER_ID
+
+logger = logging.getLogger("matrixbot")
+
+# The Space room to watch for new members
+SPACE_ROOM_ID = "!-1ZBnAH-JiCOV8MGSKN77zDGTuI3pgSdy8Unu_DrDyc"
+
+# Public channels to invite new members to.
+# Intentionally excludes: Management, Cool Kids, Spam and Stuff (invite-only),
+# and Commands (knock-gated — access granted deliberately by admins).
+INVITE_ROOMS = [
+    "!wfokQ1-pE896scu_AOcCBA2s3L4qFo-PTBAFTd0WMI0",  # General
+    "!GK6v5cLEEnowIooQJv5jECfISUjADjt8aKhWv9VbG5U",  # Memes
+    "!ktQu0gavhjpCMkgxk8SYdb6mnJRY-u7mY7_KfksV0SU",  # Music
+    "!ARbRFSPNp2U0MslWTBGoTT3gbmJJ25dPRL6enQntvPo",   # Voice
+    "!3gMjTHqV-r823ZrvXnck7waB0Pd8tiCu-zbF7mSS83E",   # Voice 2
+]
+
+WELCOME_EMOJI = "\u2705"  # checkmark
+
+STATE_FILE = Path("welcome_state.json")
+
+
+def _load_state() -> dict:
+    if STATE_FILE.exists():
+        try:
+            return json.loads(STATE_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {}
+
+
+def _save_state(state: dict):
+    try:
+        tmp = STATE_FILE.with_suffix(".tmp")
+        tmp.write_text(json.dumps(state, indent=2))
+        tmp.rename(STATE_FILE)
+    except OSError as e:
+        logger.error("Failed to save welcome state: %s", e)
+
+
+def clean_stale_dm_messages() -> int:
+    """Remove all pending welcome DM records. Returns count removed."""
+    state = _load_state()
+    pending = state.get("dm_welcome_messages", {})
+    count = len(pending)
+    if count:
+        state["dm_welcome_messages"] = {}
+        _save_state(state)
+    return count
+
+
+async def handle_space_join(client: AsyncClient, sender: str):
+    """Called when a new user joins the Space. DM them a welcome message."""
+    state = _load_state()
+    welcomed = state.get("welcomed_users", [])
+
+    if sender in welcomed:
+        return
+
+    # Skip if we already sent them a DM they haven't reacted to yet
+    pending = state.get("dm_welcome_messages", {})
+    if any(v["user"] == sender for v in pending.values()):
+        logger.debug("Already have a pending welcome DM for %s, skipping", sender)
+        return
+
+    logger.info("New Space member %s — sending welcome DM", sender)
+
+    dm_room = await get_or_create_dm(client, sender)
+    if not dm_room:
+        logger.error("Could not create DM with %s for welcome", sender)
+        return
+
+    plain = (
+        "Welcome to The Lotus Guild!\n\n"
+        f"React to this message with {WELCOME_EMOJI} to get invited to all public channels.\n\n"
+        "You'll be added to General, Memes, Music, and the Voice channels."
+    )
+    html = (
+        "<h3>Welcome to The Lotus Guild!</h3>"
+        f"<p>React to this message with {WELCOME_EMOJI} to get invited to all public channels.</p>"
+        "<p>You'll be added to <b>General</b>, <b>Memes</b>, <b>Music</b>, and the <b>Voice</b> channels.</p>"
+    )
+
+    resp = await send_html(client, dm_room, plain, html)
+    if hasattr(resp, "event_id"):
+        # Track the welcome message per user so we can match their reaction
+        dm_messages = state.get("dm_welcome_messages", {})
+        dm_messages[resp.event_id] = {"user": sender, "dm_room": dm_room}
+        state["dm_welcome_messages"] = dm_messages
+        _save_state(state)
+
+        # React to our own message to show what to click
+        await send_reaction(client, dm_room, resp.event_id, WELCOME_EMOJI)
+        logger.info("Sent welcome DM to %s (event %s)", sender, resp.event_id)
+    else:
+        logger.error("Failed to send welcome DM to %s: %s", sender, resp)
+
+
+async def handle_welcome_reaction(
+    client: AsyncClient, room_id: str, sender: str, reacted_event_id: str, key: str
+):
+    """Handle a reaction to a welcome DM. Invite user to channels."""
+    if sender == MATRIX_USER_ID:
+        return
+
+    if key != WELCOME_EMOJI:
+        return
+
+    state = _load_state()
+    dm_messages = state.get("dm_welcome_messages", {})
+    entry = dm_messages.get(reacted_event_id)
+
+    if not entry:
+        return
+
+    if entry["user"] != sender:
+        return
+
+    logger.info("Welcome reaction from %s — sending invites", sender)
+
+    invited_count = 0
+    for invite_room_id in INVITE_ROOMS:
+        room = client.rooms.get(invite_room_id)
+        if room and sender in (m.user_id for m in room.users.values()):
+            logger.debug("%s already in %s, skipping", sender, invite_room_id)
+            continue
+
+        try:
+            resp = await client.room_invite(invite_room_id, sender)
+            logger.info("Invited %s to %s: %s", sender, invite_room_id, resp)
+            invited_count += 1
+        except Exception as e:
+            logger.error("Failed to invite %s to %s: %s", sender, invite_room_id, e)
+
+    # Mark user as welcomed
+    welcomed = state.get("welcomed_users", [])
+    if sender not in welcomed:
+        welcomed.append(sender)
+        state["welcomed_users"] = welcomed
+
+    # Remove the DM message entry (one-time use)
+    del dm_messages[reacted_event_id]
+    state["dm_welcome_messages"] = dm_messages
+    _save_state(state)
+
+    # Confirm in DM
+    from utils import send_text
+    if invited_count > 0:
+        await send_text(client, room_id, f"You've been invited to {invited_count} channel(s). Check your invites!")
+    else:
+        await send_text(client, room_id, "You're already in all the channels!")
+
+
+def log_ready():
+    logger.info("Welcome module ready — watching Space for new members")

matrixbot/wordle.py

@@ -0,0 +1,821 @@
+"""Wordle game for Matrix bot.
+
+Full implementation with daily puzzles, statistics tracking,
+hard mode, shareable results, and rich HTML rendering.
+"""
+
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+
+import aiohttp
+from nio import AsyncClient
+
+from utils import send_text, send_html, get_or_create_dm
+from config import BOT_PREFIX
+
+from wordlist_answers import ANSWERS
+from wordlist_valid import VALID_GUESSES
+
+logger = logging.getLogger("matrixbot")
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_WORDLE_EPOCH = date(2021, 6, 19)
+
+# Cache: date string -> (word, puzzle_number)
+_nyt_cache: dict[str, tuple[str, int]] = {}
+
+# Build lookup sets at import time
+_ANSWER_LIST = [w.upper() for w in ANSWERS]
+_VALID_SET = frozenset(w.upper() for w in VALID_GUESSES) | frozenset(_ANSWER_LIST)
+
+# Tile colors (Wordle official palette)
+_TILE = {
+    2: {"bg": "#538d4e", "label": "correct"},    # Green
+    1: {"bg": "#b59f3b", "label": "present"},     # Yellow
+    0: {"bg": "#3a3a3c", "label": "absent"},      # Gray
+}
+_EMPTY_BG = "#121213"
+_EMPTY_BORDER = "#3a3a3c"
+
+# Emoji squares for plain-text fallback & share
+_EMOJI = {2: "\U0001f7e9", 1: "\U0001f7e8", 0: "\u2b1b"}
+
+# Keyboard layout
+_KB_ROWS = ["QWERTYUIOP", "ASDFGHJKL", "ZXCVBNM"]
+
+# Stats file
+STATS_FILE = Path("wordle_stats.json")
+
+# Congratulations messages by guess number
+_CONGRATS = {
+    1: "Genius!",
+    2: "Magnificent!",
+    3: "Impressive!",
+    4: "Splendid!",
+    5: "Great!",
+    6: "Phew!",
+}
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class WordleGame:
+    player_id: str
+    room_id: str
+    target: str
+    guesses: list = field(default_factory=list)
+    results: list = field(default_factory=list)
+    hard_mode: bool = False
+    daily_number: int = 0
+    started_at: float = field(default_factory=time.time)
+    finished: bool = False
+    won: bool = False
+    origin_room_id: str = ""  # Public room where game was started (for share)
+
+
+# Module-level state
+_active_games: dict[str, WordleGame] = {}
+_all_stats: dict[str, dict] = {}
+
+# ---------------------------------------------------------------------------
+# Stats persistence
+# ---------------------------------------------------------------------------
+
+def _load_stats():
+    global _all_stats
+    if STATS_FILE.exists():
+        try:
+            _all_stats = json.loads(STATS_FILE.read_text())
+        except (json.JSONDecodeError, OSError) as e:
+            logger.error("Failed to load wordle stats: %s", e)
+            _all_stats = {}
+    else:
+        _all_stats = {}
+
+
+def _save_stats():
+    try:
+        tmp = STATS_FILE.with_suffix(".tmp")
+        tmp.write_text(json.dumps(_all_stats, indent=2))
+        tmp.rename(STATS_FILE)
+    except OSError as e:
+        logger.error("Failed to save wordle stats: %s", e)
+
+
+def _get_player_stats(player_id: str) -> dict:
+    if player_id not in _all_stats:
+        _all_stats[player_id] = {
+            "games_played": 0,
+            "games_won": 0,
+            "current_streak": 0,
+            "max_streak": 0,
+            "guess_distribution": {str(i): 0 for i in range(1, 7)},
+            "last_daily": -1,
+            "hard_mode": False,
+            "last_daily_result": None,
+            "last_daily_guesses": None,
+        }
+    return _all_stats[player_id]
+
+
+def _record_game_result(player_id: str, game: WordleGame):
+    stats = _get_player_stats(player_id)
+    stats["games_played"] += 1
+
+    if game.won:
+        stats["games_won"] += 1
+        stats["current_streak"] += 1
+        stats["max_streak"] = max(stats["max_streak"], stats["current_streak"])
+        num_guesses = str(len(game.guesses))
+        stats["guess_distribution"][num_guesses] = (
+            stats["guess_distribution"].get(num_guesses, 0) + 1
+        )
+    else:
+        stats["current_streak"] = 0
+
+    stats["last_daily"] = game.daily_number
+    stats["last_daily_result"] = game.results
+    stats["last_daily_guesses"] = game.guesses
+    stats["last_daily_won"] = game.won
+    stats["last_daily_hard"] = game.hard_mode
+    stats["last_origin_room"] = game.origin_room_id
+
+    _save_stats()
+
+
+# ---------------------------------------------------------------------------
+# Core algorithms
+# ---------------------------------------------------------------------------
+
+async def get_daily_word() -> tuple[str, int]:
+    """Return (word, puzzle_number) for today's daily puzzle.
+
+    Fetches from the NYT Wordle API. Falls back to the local word list
+    if the request fails.
+    """
+    today = date.today()
+    date_str = today.strftime("%Y-%m-%d")
+
+    if date_str in _nyt_cache:
+        return _nyt_cache[date_str]
+
+    try:
+        url = f"https://www.nytimes.com/svc/wordle/v2/{date_str}.json"
+        timeout = aiohttp.ClientTimeout(total=5)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.get(url) as resp:
+                if resp.status == 200:
+                    data = await resp.json(content_type=None)
+                    word = data["solution"].upper()
+                    puzzle_number = int(data["id"])
+                    _nyt_cache[date_str] = (word, puzzle_number)
+                    logger.info("NYT Wordle #%d: %s", puzzle_number, word)
+                    return word, puzzle_number
+                else:
+                    logger.warning("NYT Wordle API returned %d, falling back to local list", resp.status)
+    except Exception as e:
+        logger.warning("Failed to fetch NYT Wordle word: %s — falling back to local list", e)
+
+    # Fallback: use local answer list
+    puzzle_number = (today - _WORDLE_EPOCH).days
+    word = _ANSWER_LIST[puzzle_number % len(_ANSWER_LIST)]
+    return word, puzzle_number
+
+
+def evaluate_guess(guess: str, target: str) -> list[int]:
+    """Evaluate a guess against the target. Returns list of 5 scores:
+    2 = correct position (green), 1 = wrong position (yellow), 0 = absent (gray).
+    Handles duplicate letters correctly with a two-pass approach.
+    """
+    result = [0] * 5
+    target_remaining = list(target)
+
+    # Pass 1: mark exact matches (green)
+    for i in range(5):
+        if guess[i] == target[i]:
+            result[i] = 2
+            target_remaining[i] = None
+
+    # Pass 2: mark present-but-wrong-position (yellow)
+    for i in range(5):
+        if result[i] == 2:
+            continue
+        if guess[i] in target_remaining:
+            result[i] = 1
+            target_remaining[target_remaining.index(guess[i])] = None
+
+    return result
+
+
+def validate_hard_mode(
+    guess: str,
+    previous_guesses: list[str],
+    previous_results: list[list[int]],
+) -> str | None:
+    """Return None if valid, or an error message if hard mode violated."""
+    for prev_guess, prev_result in zip(previous_guesses, previous_results):
+        for i, (letter, score) in enumerate(zip(prev_guess, prev_result)):
+            if score == 2 and guess[i] != letter:
+                return (
+                    f"Hard mode: position {i + 1} must be "
+                    f"'{letter}' (green from previous guess)"
+                )
+            if score == 1 and letter not in guess:
+                return (
+                    f"Hard mode: guess must contain "
+                    f"'{letter}' (yellow from previous guess)"
+                )
+    return None
+
+
+# ---------------------------------------------------------------------------
+# HTML rendering
+# ---------------------------------------------------------------------------
+
+def _tile_span(letter: str, bg: str) -> str:
+    """Render a single letter tile using Matrix-compatible attributes."""
+    return (
+        f'<font data-mx-bg-color="{bg}" data-mx-color="#ffffff">'
+        f"<b>\u00a0{letter}\u00a0</b></font>"
+    )
+
+
+def render_grid_html(game: WordleGame) -> str:
+    """Render the Wordle grid as inline spans (compatible with Cinny)."""
+    rows = []
+    for row_idx in range(6):
+        tiles = []
+        if row_idx < len(game.guesses):
+            guess = game.guesses[row_idx]
+            result = game.results[row_idx]
+            for letter, score in zip(guess, result):
+                bg = _TILE[score]["bg"]
+                tiles.append(_tile_span(letter, bg))
+        else:
+            for _ in range(5):
+                tiles.append(_tile_span("\u00a0", _EMPTY_BG))
+        rows.append("".join(tiles))
+
+    return "<br>".join(rows)
+
+
+def render_keyboard_html(game: WordleGame) -> str:
+    """Render a virtual keyboard showing letter states."""
+    letter_states: dict[str, int] = {}
+    for guess, result in zip(game.guesses, game.results):
+        for letter, score in zip(guess, result):
+            letter_states[letter] = max(letter_states.get(letter, -1), score)
+
+    kb_rows = []
+    for row in _KB_ROWS:
+        keys = []
+        for letter in row:
+            state = letter_states.get(letter, -1)
+            if state == -1:
+                bg, color = "#818384", "#ffffff"
+            elif state == 0:
+                bg, color = "#3a3a3c", "#555555"
+            elif state == 1:
+                bg, color = "#b59f3b", "#ffffff"
+            else:
+                bg, color = "#538d4e", "#ffffff"
+            keys.append(
+                f'<font data-mx-bg-color="{bg}" data-mx-color="{color}">'
+                f"{letter}</font>"
+            )
+        kb_rows.append(" ".join(keys))
+
+    return "<br>" + "<br>".join(kb_rows)
+
+
+def render_grid_plain(game: WordleGame) -> str:
+    """Plain text grid with emoji squares and letter markers."""
+    _marker = {2: "!", 1: "?", 0: "."}  # ! = correct, ? = wrong spot, . = absent
+    lines = []
+    for guess, result in zip(game.guesses, game.results):
+        emoji_row = "".join(_EMOJI[s] for s in result)
+        # Show each letter with a marker: [C!] = correct, [R?] = wrong spot, [A.] = absent
+        marked = " ".join(f"{letter}{_marker[score]}" for letter, score in zip(guess, result))
+        lines.append(f"{emoji_row}  {marked}")
+    return "\n".join(lines)
+
+
+def render_keyboard_plain(game: WordleGame) -> str:
+    """Plain text keyboard status."""
+    letter_states: dict[str, int] = {}
+    for guess, result in zip(game.guesses, game.results):
+        for letter, score in zip(guess, result):
+            letter_states[letter] = max(letter_states.get(letter, -1), score)
+
+    lines = []
+    for row in _KB_ROWS:
+        chars = []
+        for letter in row:
+            state = letter_states.get(letter, -1)
+            if state == 0:
+                chars.append("\u00b7")  # dimmed
+            elif state >= 1:
+                chars.append(letter)
+            else:
+                chars.append(letter.lower())
+        lines.append(" ".join(chars))
+    return "\n".join(lines)
+
+
+def render_stats_html(stats: dict) -> str:
+    """Render player statistics as HTML (Matrix-compatible)."""
+    played = stats["games_played"]
+    won = stats["games_won"]
+    win_pct = (won / max(played, 1)) * 100
+    streak = stats["current_streak"]
+    max_streak = stats["max_streak"]
+    dist = stats["guess_distribution"]
+    max_count = max((int(v) for v in dist.values()), default=1) or 1
+
+    html = "<strong>Wordle Statistics</strong><br><br>"
+    html += (
+        f"<b>{played}</b> Played | "
+        f"<b>{win_pct:.0f}%</b> Win | "
+        f"<b>{streak}</b> Streak | "
+        f"<b>{max_streak}</b> Best<br><br>"
+    )
+
+    html += "<strong>Guess Distribution</strong><br>"
+    for i in range(1, 7):
+        count = int(dist.get(str(i), 0))
+        is_max = count == max_count and count > 0
+        bar_len = max(int((count / max_count) * 10), 1) if max_count > 0 else 1
+        bar = "\u2588" * bar_len  # Block character for bar
+        if is_max and count > 0:
+            html += f'{i} <font data-mx-bg-color="#538d4e" data-mx-color="#ffffff"> {bar} {count} </font><br>'
+        else:
+            html += f'{i} <font data-mx-bg-color="#3a3a3c" data-mx-color="#ffffff"> {bar} {count} </font><br>'
+    return html
+
+
+def render_stats_plain(stats: dict) -> str:
+    """Plain text stats."""
+    played = stats["games_played"]
+    won = stats["games_won"]
+    win_pct = (won / max(played, 1)) * 100
+    streak = stats["current_streak"]
+    max_streak = stats["max_streak"]
+    dist = stats["guess_distribution"]
+    max_count = max((int(v) for v in dist.values()), default=1) or 1
+
+    lines = [
+        "Wordle Statistics",
+        f"Played: {played} | Win: {win_pct:.0f}% | Streak: {streak} | Max: {max_streak}",
+        "",
+        "Guess Distribution:",
+    ]
+    for i in range(1, 7):
+        count = int(dist.get(str(i), 0))
+        bar_len = max(round((count / max_count) * 16), 1) if count > 0 else 0
+        bar = "\u2588" * bar_len
+        lines.append(f"  {i}: {bar} {count}")
+
+    return "\n".join(lines)
+
+
+def generate_share(stats: dict) -> str:
+    """Generate the shareable emoji grid from last completed daily."""
+    results = stats.get("last_daily_result")
+    if not results:
+        return ""
+
+    won = stats.get("last_daily_won", False)
+    hard = stats.get("last_daily_hard", False)
+    daily_num = stats.get("last_daily", 0)
+    score = str(len(results)) if won else "X"
+    mode = "*" if hard else ""
+
+    header = f"Wordle {daily_num} {score}/6{mode}\n\n"
+    rows = []
+    for result in results:
+        rows.append("".join(_EMOJI[s] for s in result))
+    return header + "\n".join(rows)
+
+
+# ---------------------------------------------------------------------------
+# Subcommand handlers
+# ---------------------------------------------------------------------------
+
+async def wordle_help(client: AsyncClient, room_id: str):
+    """Show help text with rules and commands."""
+    p = BOT_PREFIX
+    plain = (
+        f"Wordle - Guess the 5-letter word in 6 tries!\n\n"
+        f"Commands:\n"
+        f"  {p}wordle         Start today's daily puzzle (or show current game)\n"
+        f"  {p}wordle <word>  Submit a 5-letter guess\n"
+        f"  {p}wordle stats   View your statistics\n"
+        f"  {p}wordle hard    Toggle hard mode\n"
+        f"  {p}wordle share   Share your last daily result\n"
+        f"  {p}wordle give up Forfeit current game\n"
+        f"  {p}wordle help    Show this help\n\n"
+        f"Rules:\n"
+        f"  - Each guess must be a valid 5-letter English word\n"
+        f"  - Green = correct letter, correct position\n"
+        f"  - Yellow = correct letter, wrong position\n"
+        f"  - Gray = letter not in the word\n"
+        f"  - Hard mode: must use all revealed hints in subsequent guesses\n"
+        f"  - Everyone gets the same daily word!"
+    )
+    html = (
+        "<h4>Wordle</h4>"
+        "<p>Guess the 5-letter word in 6 tries!</p>"
+        "<strong>Commands:</strong>"
+        "<ul>"
+        f"<li><code>{p}wordle</code> — Start today's daily puzzle</li>"
+        f"<li><code>{p}wordle &lt;word&gt;</code> — Submit a guess</li>"
+        f"<li><code>{p}wordle stats</code> — View your statistics</li>"
+        f"<li><code>{p}wordle hard</code> — Toggle hard mode</li>"
+        f"<li><code>{p}wordle share</code> — Share your last result</li>"
+        f"<li><code>{p}wordle give up</code> — Forfeit current game</li>"
+        "</ul>"
+        "<strong>How to play:</strong>"
+        "<ul>"
+        '<li><font data-mx-bg-color="#538d4e" data-mx-color="#ffffff"><b> G </b></font> '
+        "Green = correct letter, correct position</li>"
+        '<li><font data-mx-bg-color="#b59f3b" data-mx-color="#ffffff"><b> Y </b></font> '
+        "Yellow = correct letter, wrong position</li>"
+        '<li><font data-mx-bg-color="#3a3a3c" data-mx-color="#ffffff"><b> X </b></font> '
+        "Gray = letter not in the word</li>"
+        "</ul>"
+        "<p><em>Hard mode:</em> You must use all revealed hints in subsequent guesses.</p>"
+        "<p>Everyone gets the same daily word!</p>"
+    )
+    await send_html(client, room_id, plain, html)
+
+
+async def wordle_start_or_status(client: AsyncClient, room_id: str, sender: str, origin_room_id: str = ""):
+    """Start a new daily game or show current game status."""
+    # Check for active game
+    if sender in _active_games:
+        game = _active_games[sender]
+        if not game.finished:
+            _ = 6 - len(game.guesses)
+            grid_plain = render_grid_plain(game)
+            kb_plain = render_keyboard_plain(game)
+            plain = (
+                f"Wordle {game.daily_number} — "
+                f"Guess {len(game.guesses) + 1}/6\n\n"
+                f"{grid_plain}\n\n{kb_plain}"
+            )
+            grid_html = render_grid_html(game)
+            kb_html = render_keyboard_html(game)
+            mode = " (Hard Mode)" if game.hard_mode else ""
+            html = (
+                f''
+                f"<strong>Wordle {game.daily_number}{mode}</strong> — "
+                f"Guess {len(game.guesses) + 1}/6<br><br>"
+                f"{grid_html}{kb_html}"
+            )
+            await send_html(client, room_id, plain, html)
+            return
+
+    # Check if already completed today's puzzle
+    word, puzzle_number = await get_daily_word()
+    stats = _get_player_stats(sender)
+
+    if stats["last_daily"] == puzzle_number:
+        await send_text(
+            client, room_id,
+            f"You already completed today's Wordle (#{puzzle_number})! "
+            f"Use {BOT_PREFIX}wordle stats to see your results "
+            f"or {BOT_PREFIX}wordle share to share them."
+        )
+        return
+
+    # Start new game
+    hard_mode = stats.get("hard_mode", False)
+    game = WordleGame(
+        player_id=sender,
+        room_id=room_id,
+        target=word,
+        hard_mode=hard_mode,
+        daily_number=puzzle_number,
+        origin_room_id=origin_room_id or room_id,
+    )
+    _active_games[sender] = game
+
+    mode_str = " (Hard Mode)" if hard_mode else ""
+    grid_html = render_grid_html(game)
+    kb_html = render_keyboard_html(game)
+    plain = (
+        f"Wordle #{puzzle_number}{mode_str}\n"
+        f"Guess a 5-letter word! You have 6 attempts.\n"
+        f"Type {BOT_PREFIX}wordle <word> to guess."
+    )
+    html = (
+        f''
+        f"<strong>Wordle #{puzzle_number}{mode_str}</strong><br>"
+        f"Guess a 5-letter word! You have 6 attempts.<br>"
+        f"Type <code>{BOT_PREFIX}wordle &lt;word&gt;</code> to guess."
+        f"<br><br>{grid_html}{kb_html}"
+    )
+    await send_html(client, room_id, plain, html)
+
+
+async def wordle_guess(
+    client: AsyncClient, room_id: str, sender: str, guess: str
+):
+    """Process a guess."""
+    if sender not in _active_games:
+        await send_text(
+            client, room_id,
+            f"No active game. Start one with {BOT_PREFIX}wordle"
+        )
+        return
+
+    game = _active_games[sender]
+    if game.finished:
+        await send_text(
+            client, room_id,
+            f"Your game is already finished! "
+            f"Use {BOT_PREFIX}wordle to start a new daily puzzle."
+        )
+        return
+
+    # Validate word
+    if guess not in _VALID_SET:
+        await send_text(client, room_id, f"'{guess.lower()}' is not in the word list. Try again.")
+        return
+
+    # Hard mode validation
+    if game.hard_mode and game.guesses:
+        violation = validate_hard_mode(guess, game.guesses, game.results)
+        if violation:
+            await send_text(client, room_id, violation)
+            return
+
+    # Evaluate
+    result = evaluate_guess(guess, game.target)
+    game.guesses.append(guess)
+    game.results.append(result)
+
+    # Check win
+    if all(s == 2 for s in result):
+        game.finished = True
+        game.won = True
+        origin = game.origin_room_id
+        _record_game_result(sender, game)
+        del _active_games[sender]
+
+        num = len(game.guesses)
+        congrats = _CONGRATS.get(num, "Nice!")
+        grid_plain = render_grid_plain(game)
+        plain = (
+            f"{congrats} Wordle {game.daily_number} {num}/6"
+            f"{'*' if game.hard_mode else ''}\n\n"
+            f"{grid_plain}"
+        )
+        grid_html = render_grid_html(game)
+        mode = "*" if game.hard_mode else ""
+        html = (
+            f''
+            f"<strong>{congrats}</strong> "
+            f"Wordle {game.daily_number} {num}/6{mode}<br><br>"
+            f"{grid_html}"
+        )
+        await send_html(client, room_id, plain, html)
+        if origin and origin != room_id:
+            await wordle_share(client, origin, sender)
+        return
+
+    # Check loss (6 guesses used)
+    if len(game.guesses) >= 6:
+        game.finished = True
+        game.won = False
+        origin = game.origin_room_id
+        _record_game_result(sender, game)
+        del _active_games[sender]
+
+        grid_plain = render_grid_plain(game)
+        plain = (
+            f"Wordle {game.daily_number} X/6"
+            f"{'*' if game.hard_mode else ''}\n\n"
+            f"{grid_plain}\n\n"
+            f"The word was: {game.target}\n"
+            f"Better luck tomorrow!"
+        )
+        grid_html = render_grid_html(game)
+        mode = "*" if game.hard_mode else ""
+        html = (
+            f''
+            f"<strong>Wordle {game.daily_number} X/6{mode}</strong><br><br>"
+            f"{grid_html}<br>"
+            f'The word was: <font data-mx-color="#538d4e"><strong>'
+            f"{game.target}</strong></font><br>"
+            f"<em>Better luck tomorrow!</em>"
+        )
+        await send_html(client, room_id, plain, html)
+        if origin and origin != room_id:
+            await wordle_share(client, origin, sender)
+        return
+
+    # Still playing — show grid + keyboard
+    _ = 6 - len(game.guesses)
+    grid_plain = render_grid_plain(game)
+    kb_plain = render_keyboard_plain(game)
+    plain = (
+        f"Wordle {game.daily_number} — "
+        f"Guess {len(game.guesses) + 1}/6\n\n"
+        f"{grid_plain}\n\n{kb_plain}"
+    )
+    grid_html = render_grid_html(game)
+    kb_html = render_keyboard_html(game)
+    mode = " (Hard Mode)" if game.hard_mode else ""
+    html = (
+        f''
+        f"<strong>Wordle {game.daily_number}{mode}</strong> — "
+        f"Guess {len(game.guesses) + 1}/6<br><br>"
+        f"{grid_html}{kb_html}"
+    )
+    await send_html(client, room_id, plain, html)
+
+
+async def wordle_stats(client: AsyncClient, room_id: str, sender: str):
+    """Show player statistics."""
+    stats = _get_player_stats(sender)
+
+    if stats["games_played"] == 0:
+        await send_text(
+            client, room_id,
+            f"No Wordle stats yet! Start a game with {BOT_PREFIX}wordle"
+        )
+        return
+
+    plain = render_stats_plain(stats)
+    html = render_stats_html(stats)
+    await send_html(client, room_id, plain, html)
+
+
+async def wordle_toggle_hard(client: AsyncClient, room_id: str, sender: str):
+    """Toggle hard mode for the player."""
+    stats = _get_player_stats(sender)
+    new_mode = not stats.get("hard_mode", False)
+    stats["hard_mode"] = new_mode
+    _save_stats()
+
+    # Also update active game if one exists
+    if sender in _active_games:
+        game = _active_games[sender]
+        if not game.guesses:
+            # Only allow toggling before first guess
+            game.hard_mode = new_mode
+        elif new_mode:
+            await send_text(
+                client, room_id,
+                "Hard mode enabled for future games. "
+                "Cannot enable mid-game after guessing."
+            )
+            return
+        else:
+            game.hard_mode = False
+
+    status = "enabled" if new_mode else "disabled"
+    plain = (
+        f"Hard mode {status}. "
+        + ("You must use all revealed hints in subsequent guesses."
+           if new_mode else "Standard rules apply.")
+    )
+    await send_text(client, room_id, plain)
+
+
+async def wordle_share(client: AsyncClient, room_id: str, sender: str):
+    """Share the last completed daily result."""
+    stats = _get_player_stats(sender)
+    share_text = generate_share(stats)
+
+    if not share_text:
+        await send_text(
+            client, room_id,
+            f"No completed daily puzzle to share. Play one with {BOT_PREFIX}wordle"
+        )
+        return
+
+    await send_text(client, room_id, share_text)
+
+
+async def wordle_give_up(client: AsyncClient, room_id: str, sender: str):
+    """Forfeit the current game."""
+    if sender not in _active_games:
+        await send_text(
+            client, room_id,
+            f"No active game to give up. Start one with {BOT_PREFIX}wordle"
+        )
+        return
+
+    game = _active_games[sender]
+    if game.finished:
+        del _active_games[sender]
+        return
+
+    game.finished = True
+    game.won = False
+    origin = game.origin_room_id
+    _record_game_result(sender, game)
+    del _active_games[sender]
+
+    grid_plain = render_grid_plain(game)
+    plain = (
+        f"Game over! The word was: {game.target}\n\n"
+        f"{grid_plain}\n\n"
+        f"Better luck tomorrow!"
+    )
+    grid_html = render_grid_html(game)
+    html = (
+        f''
+        f"<strong>Game Over</strong><br><br>"
+        f"{grid_html}<br>"
+        f'The word was: <font data-mx-color="#538d4e"><strong>'
+        f"{game.target}</strong></font><br>"
+        f"<em>Better luck tomorrow!</em>"
+    )
+    await send_html(client, room_id, plain, html)
+    if origin and origin != room_id:
+        await wordle_share(client, origin, sender)
+
+
+# ---------------------------------------------------------------------------
+# Main router
+# ---------------------------------------------------------------------------
+
+async def _get_dm_room(client: AsyncClient, room_id: str, sender: str) -> tuple[str, str]:
+    """Get or create DM room for the sender. Returns (dm_room_id, origin_room_id).
+
+    If already in a DM, returns (room_id, stored_origin or room_id).
+    If in a public room, creates/finds DM and returns (dm_room_id, room_id).
+    """
+    # Check if this is already a DM (2 members)
+    room = client.rooms.get(room_id)
+    if room and room.member_count == 2:
+        # Already in DM — use origin from active game if available
+        game = _active_games.get(sender)
+        origin = game.origin_room_id if game and game.origin_room_id else room_id
+        return room_id, origin
+
+    # Public room — find/create DM
+    dm_room = await get_or_create_dm(client, sender)
+    if dm_room:
+        return dm_room, room_id
+
+    # Fallback to public room if DM creation fails
+    logger.warning("Could not create DM with %s, falling back to public room", sender)
+    return room_id, room_id
+
+
+async def handle_wordle(
+    client: AsyncClient, room_id: str, sender: str, args: str
+):
+    """Main entry point — dispatches to subcommands."""
+    parts = args.strip().split(None, 1)
+    subcmd = parts[0].lower() if parts else ""
+    sub_args = parts[1] if len(parts) > 1 else ""
+
+    # Share always goes to the public room
+    if subcmd == "share":
+        await wordle_share(client, room_id, sender)
+        return
+
+    # All other commands route through DM
+    dm_room, origin = await _get_dm_room(client, room_id, sender)
+
+    # Silently redirect to DM — origin room will get an auto-share when the game ends
+
+    if subcmd == "help":
+        await wordle_help(client, dm_room)
+    elif subcmd == "stats":
+        await wordle_stats(client, dm_room, sender)
+    elif subcmd == "hard":
+        await wordle_toggle_hard(client, dm_room, sender)
+    elif subcmd == "give" and sub_args.lower().startswith("up"):
+        await wordle_give_up(client, dm_room, sender)
+    elif subcmd == "":
+        await wordle_start_or_status(client, dm_room, sender, origin)
+    elif len(subcmd) == 5 and subcmd.isalpha():
+        await wordle_guess(client, dm_room, sender, subcmd.upper())
+    else:
+        await send_text(
+            client, room_id,
+            f"Invalid wordle command or guess. "
+            f"Guesses must be exactly 5 letters. "
+            f"Try {BOT_PREFIX}wordle help"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Load stats on module import
+# ---------------------------------------------------------------------------
+_load_stats()

matrixbot/wordlist_answers.py

@@ -0,0 +1,411 @@
+# Curated list of 2,309 five-letter words used as Wordle daily answers.
+# Common, well-known English words only.
+ANSWERS = [
+    "aback", "abase", "abate", "abbey", "abbot",
+    "abhor", "abide", "abled", "abode", "abort",
+    "about", "above", "abuse", "abyss", "acidy",
+    "acorn", "acrid", "actor", "acute", "adage",
+    "adapt", "adept", "admin", "admit", "adobe",
+    "adopt", "adore", "adorn", "adult", "aegis",
+    "afoot", "afoul", "after", "again", "agent",
+    "agile", "aging", "aglow", "agony", "agree",
+    "ahead", "aider", "aisle", "alarm", "album",
+    "alert", "algae", "alibi", "alien", "align",
+    "alike", "alive", "allay", "alley", "allot",
+    "allow", "alloy", "aloft", "alone", "along",
+    "aloof", "aloud", "alpha", "altar", "alter",
+    "amass", "amaze", "amber", "amble", "amend",
+    "amine", "amino", "amiss", "amity", "among",
+    "ample", "amply", "amuse", "angel", "anger",
+    "angle", "angry", "angst", "anime", "ankle",
+    "annex", "annoy", "annul", "anode", "antic",
+    "anvil", "aorta", "apart", "aphid", "aping",
+    "apnea", "apple", "apply", "apron", "aptly",
+    "arbor", "ardor", "arena", "argue", "arise",
+    "armor", "aroma", "arose", "array", "arrow",
+    "arson", "artsy", "ascot", "ashen", "aside",
+    "askew", "assay", "asset", "atoll", "atone",
+    "attic", "audio", "audit", "augur", "aunty",
+    "avian", "avoid", "await", "awake", "award",
+    "aware", "awash", "awful", "awoke", "axial",
+    "axiom", "azure", "bacon", "badge", "badly",
+    "bagel", "baggy", "baker", "balmy", "banal",
+    "banjo", "barge", "baron", "basal", "basic",
+    "basil", "basin", "basis", "baste", "batch",
+    "bathe", "baton", "batty", "bawdy", "bayou",
+    "beach", "beady", "beard", "beast", "beech",
+    "beefy", "befit", "began", "begat", "beget",
+    "begin", "begun", "being", "belch", "belly",
+    "below", "bench", "beret", "berry", "berth",
+    "beset", "betel", "bevel", "bible", "bicep",
+    "biddy", "bigot", "bilge", "billy", "binge",
+    "bingo", "biome", "birch", "birth", "black",
+    "blade", "blame", "bland", "blank", "blare",
+    "blast", "blaze", "bleak", "bleat", "bleed",
+    "blend", "bless", "blimp", "blind", "blini",
+    "bliss", "blitz", "bloat", "block", "bloke",
+    "blond", "blood", "bloom", "blown", "blues",
+    "bluff", "blunt", "blurb", "blurt", "blush",
+    "board", "boast", "bobby", "boney", "bonus",
+    "booby", "boost", "booth", "booty", "booze",
+    "boozy", "borax", "borne", "bosom", "bossy",
+    "botch", "bound", "bowel", "boxer", "brace",
+    "braid", "brain", "brake", "brand", "brash",
+    "brass", "brave", "bravo", "brawl", "brawn",
+    "bread", "break", "breed", "briar", "bribe",
+    "brick", "bride", "brief", "brine", "bring",
+    "brink", "briny", "brisk", "broad", "broil",
+    "broke", "brood", "brook", "broth", "brown",
+    "brush", "brunt", "brute", "buddy", "budge",
+    "buggy", "bugle", "build", "built", "bulge",
+    "bulky", "bully", "bunch", "bunny", "burly",
+    "burnt", "burst", "bushy", "butch", "butte",
+    "buyer", "bylaw", "cabal", "cabin", "cable",
+    "cadet", "camel", "cameo", "canal", "candy",
+    "canny", "canoe", "caper", "caput", "carat",
+    "cargo", "carol", "carry", "carve", "caste",
+    "catch", "cater", "cause", "cavil", "cease",
+    "cedar", "chain", "chair", "chalk", "champ",
+    "chant", "chaos", "chard", "charm", "chart",
+    "chase", "chasm", "cheap", "cheat", "check",
+    "cheek", "cheer", "chess", "chest", "chick",
+    "chide", "chief", "child", "chili", "chill",
+    "chime", "china", "chirp", "chock", "choir",
+    "choke", "chord", "chore", "chose", "chuck",
+    "chump", "chunk", "churn", "chute", "cider",
+    "cigar", "cinch", "civic", "civil", "claim",
+    "clamp", "clang", "clank", "clash", "clasp",
+    "class", "clean", "clear", "clerk", "click",
+    "cliff", "climb", "cling", "cloak", "clock",
+    "clone", "close", "cloth", "cloud", "clout",
+    "clown", "cluck", "clued", "clump", "clung",
+    "coach", "coast", "cobra", "cocoa", "colon",
+    "color", "comet", "comic", "comma", "conch",
+    "condo", "coney", "coral", "corny", "couch",
+    "could", "count", "coupe", "court", "cover",
+    "covet", "crack", "craft", "cramp", "crane",
+    "crank", "crash", "crass", "crate", "crave",
+    "crawl", "craze", "crazy", "creak", "cream",
+    "credo", "creed", "creek", "creep", "crest",
+    "crick", "cried", "crime", "crimp", "crisp",
+    "croak", "crock", "crone", "crony", "crook",
+    "cross", "crowd", "crown", "crude", "cruel",
+    "crush", "crust", "crypt", "cubic", "cumin",
+    "cupid", "curly", "curry", "curse", "curve",
+    "curvy", "cutie", "cycle", "cynic", "daddy",
+    "daily", "dairy", "daisy", "dally", "dance",
+    "dandy", "datum", "daunt", "dealt", "death",
+    "debut", "decay", "decal", "decor", "decoy",
+    "decry", "defer", "deign", "deity", "delay",
+    "delta", "delve", "demon", "demur", "denim",
+    "dense", "depot", "depth", "derby", "deter",
+    "detox", "deuce", "devil", "diary", "dicey",
+    "digit", "dilly", "dimly", "diner", "dingo",
+    "dingy", "diode", "dirge", "dirty", "disco",
+    "ditch", "ditto", "ditty", "diver", "dizzy",
+    "dodge", "dodgy", "dogma", "doing", "dolly",
+    "donor", "donut", "dopey", "doubt", "dough",
+    "dowdy", "dowel", "draft", "drain", "drake",
+    "drama", "drank", "drape", "drawl", "drawn",
+    "dread", "dream", "dress", "dried", "drift",
+    "drill", "drink", "drive", "droit", "droll",
+    "drone", "drool", "droop", "dross", "drove",
+    "drown", "drugs", "drunk", "dryer", "dryly",
+    "duchy", "dully", "dummy", "dunce", "dusty",
+    "duvet", "dwarf", "dwell", "dwelt", "dying",
+    "eager", "eagle", "early", "earth", "easel",
+    "eaten", "eater", "ebony", "eclat", "edict",
+    "edify", "eerie", "egret", "eight", "elder",
+    "elect", "elite", "elope", "elude", "email",
+    "ember", "emcee", "empty", "enact", "endow",
+    "enemy", "enjoy", "ennui", "ensue", "enter",
+    "entry", "envoy", "epoch", "equal", "equip",
+    "erase", "erode", "error", "erupt", "essay",
+    "ester", "ether", "ethic", "ethos", "evade",
+    "event", "every", "evict", "evoke", "exact",
+    "exalt", "excel", "exert", "exile", "exist",
+    "expat", "expel", "extol", "extra", "exude",
+    "exult", "fable", "facet", "fairy", "faith",
+    "false", "fancy", "fanny", "farce", "fatal",
+    "fatty", "fault", "fauna", "feast", "feign",
+    "feint", "fella", "felon", "femur", "fence",
+    "feral", "ferry", "fetal", "fetch", "fetid",
+    "fetus", "fever", "fiber", "fibre", "field",
+    "fiend", "fiery", "fifth", "fifty", "fight",
+    "filly", "filmy", "filth", "final", "finch",
+    "fishy", "fixer", "fizzy", "fjord", "flack",
+    "flail", "flair", "flake", "flaky", "flame",
+    "flank", "flare", "flash", "flask", "fleet",
+    "flesh", "flick", "flier", "fling", "flint",
+    "flirt", "float", "flock", "flood", "floor",
+    "flora", "floss", "flour", "flout", "flown",
+    "fluid", "fluke", "flung", "flunk", "flush",
+    "flute", "foamy", "focal", "focus", "foggy",
+    "folly", "foray", "force", "forge", "forgo",
+    "forte", "forth", "forty", "forum", "found",
+    "foyer", "frail", "frame", "frank", "fraud",
+    "freak", "freed", "fresh", "friar", "fried",
+    "frill", "frisk", "fritz", "frock", "frond",
+    "front", "frost", "frown", "froze", "fruit",
+    "frump", "fully", "fungi", "funky", "funny",
+    "furry", "fussy", "fuzzy", "gamma", "gamut",
+    "gassy", "gaudy", "gauge", "gaunt", "gauze",
+    "gavel", "gawky", "geeky", "genie", "genre",
+    "ghost", "giant", "giddy", "girth", "given",
+    "giver", "gland", "glare", "glass", "glaze",
+    "gleam", "glean", "glide", "glint", "gloat",
+    "globe", "gloom", "glory", "gloss", "glove",
+    "glyph", "gnash", "gnome", "godly", "going",
+    "golem", "golly", "gonad", "goner", "goody",
+    "gooey", "goofy", "goose", "gorge", "gouge",
+    "gourd", "grace", "grade", "graft", "grail",
+    "grain", "grand", "grant", "grape", "graph",
+    "grasp", "grass", "grate", "grave", "gravy",
+    "graze", "great", "greed", "green", "greet",
+    "grief", "grill", "grime", "grimy", "grind",
+    "gripe", "groan", "groat", "groin", "groom",
+    "grope", "gross", "group", "grout", "grove",
+    "growl", "grown", "gruel", "gruff", "grump",
+    "grunt", "guard", "guava", "guess", "guest",
+    "guide", "guild", "guilt", "guise", "gulch",
+    "gully", "gumbo", "gummy", "guppy", "gusto",
+    "gusty", "habit", "hairy", "halve", "handy",
+    "happy", "hardy", "harem", "harpy", "harry",
+    "harsh", "haste", "hasty", "hatch", "haunt",
+    "haven", "hazel", "heady", "heart", "heath",
+    "heavy", "hedge", "hefty", "heist", "helix",
+    "hello", "hence", "heron", "hilly", "hinge",
+    "hippo", "hippy", "hitch", "hoard", "hobby",
+    "hoist", "holly", "homer", "honey", "honor",
+    "hooey", "horde", "horny", "horse", "hotel",
+    "hotly", "hound", "house", "hover", "howdy",
+    "human", "humid", "humor", "humus", "hunch",
+    "hunky", "hurry", "husky", "hussy", "hutch",
+    "hyena", "hymen", "hyper", "icily", "icing",
+    "ideal", "idiom", "idiot", "idyll", "igloo",
+    "image", "imbue", "impel", "imply", "inane",
+    "inbox", "incur", "index", "inept", "inert",
+    "infer", "ingot", "inlay", "inlet", "inner",
+    "input", "inter", "intro", "ionic", "irate",
+    "irony", "islet", "issue", "itchy", "ivory",
+    "jazzy", "jelly", "jenny", "jerky", "jewel",
+    "jiffy", "jimmy", "joker", "jolly", "joust",
+    "judge", "juice", "juicy", "jumbo", "jumpy",
+    "juror", "karma", "kayak", "kebab", "khaki",
+    "kinky", "kiosk", "kitty", "knack", "knead",
+    "kneel", "knelt", "knife", "knock", "knoll",
+    "known", "koala", "kudos", "label", "labor",
+    "laden", "ladle", "lager", "lance", "lanky",
+    "lapel", "lapse", "large", "larva", "latch",
+    "later", "lathe", "latte", "laugh", "layer",
+    "leach", "leafy", "leaky", "leapt", "learn",
+    "lease", "leash", "least", "leave", "ledge",
+    "leech", "legal", "leggy", "lemon", "lemur",
+    "level", "lever", "libel", "light", "liken",
+    "lilac", "limbo", "linen", "liner", "lingo",
+    "lipid", "liter", "lithe", "liver", "livid",
+    "llama", "lobby", "local", "locus", "lodge",
+    "lofty", "logic", "login", "loopy", "loose",
+    "lorry", "loser", "lousy", "lover", "lower",
+    "lowly", "loyal", "lucid", "lucky", "lumen",
+    "lumpy", "lunar", "lunch", "lunge", "lupus",
+    "lusty", "lying", "lynch", "lyric", "macaw",
+    "macho", "macro", "madam", "madly", "magic",
+    "magma", "maize", "major", "maker", "mambo",
+    "mamma", "mango", "mangy", "mania", "manic",
+    "manly", "manor", "maple", "march", "marry",
+    "marsh", "mason", "match", "matey", "maxim",
+    "maybe", "mayor", "mealy", "meant", "meaty",
+    "media", "medic", "melee", "melon", "mercy",
+    "merge", "merit", "merry", "metal", "meter",
+    "midst", "might", "milky", "mimic", "mince",
+    "minor", "minus", "mirth", "miser", "missy",
+    "mocha", "modal", "model", "modem", "mogul",
+    "moist", "molar", "moldy", "money", "month",
+    "moody", "moose", "moral", "morph", "mossy",
+    "motel", "motif", "motor", "motto", "moult",
+    "mound", "mount", "mourn", "mouse", "mousy",
+    "mouth", "mover", "movie", "mower", "mucus",
+    "muddy", "mulch", "mummy", "mural", "murky",
+    "mushy", "music", "musty", "myrrh", "nadir",
+    "naive", "nanny", "nasal", "nasty", "natal",
+    "naval", "navel", "needy", "nerve", "never",
+    "newer", "newly", "nexus", "nicer", "niche",
+    "night", "ninja", "ninny", "ninth", "noble",
+    "nobly", "noise", "noisy", "nomad", "noose",
+    "north", "notch", "noted", "novel", "nudge",
+    "nurse", "nutty", "nylon", "nymph", "oaken",
+    "oasis", "occur", "ocean", "octet", "oddly",
+    "offal", "offer", "often", "olive", "omega",
+    "onset", "opera", "opium", "optic", "orbit",
+    "order", "organ", "other", "otter", "ought",
+    "ounce", "outdo", "outer", "ovary", "ovate",
+    "overt", "ovoid", "owing", "owner", "oxide",
+    "ozone", "paddy", "pagan", "paint", "paler",
+    "palsy", "panel", "panic", "pansy", "papal",
+    "paper", "parch", "parka", "parry", "parse",
+    "party", "pasta", "paste", "pasty", "patch",
+    "patio", "patsy", "patty", "pause", "payee",
+    "peace", "peach", "pearl", "pecan", "pedal",
+    "penal", "pence", "penny", "peppy", "perch",
+    "peril", "perky", "pesky", "petal", "petty",
+    "phase", "phone", "photo", "piano", "picky",
+    "piece", "piety", "piggy", "pilot", "pinch",
+    "piney", "pious", "piper", "pipit", "pixel",
+    "pixie", "pizza", "place", "plaid", "plain",
+    "plait", "plane", "plank", "plant", "plate",
+    "plaza", "plead", "pleat", "plied", "plier",
+    "pluck", "plumb", "plume", "plump", "plunk",
+    "plush", "poesy", "point", "poise", "poker",
+    "polar", "polka", "polyp", "pooch", "poppy",
+    "porch", "poser", "posit", "posse", "pouch",
+    "poult", "pound", "pouty", "power", "prank",
+    "prawn", "preen", "press", "price", "prick",
+    "pride", "pried", "prime", "primo", "print",
+    "prior", "prism", "privy", "prize", "probe",
+    "prone", "prong", "proof", "prose", "proud",
+    "prove", "prowl", "prude", "prune", "psalm",
+    "pubic", "pudgy", "pulse", "punch", "pupil",
+    "puppy", "puree", "purge", "purse", "pushy",
+    "putty", "pygmy", "quack", "quaff", "quail",
+    "quake", "qualm", "quart", "quasi", "queen",
+    "queer", "query", "quest", "queue", "quick",
+    "quiet", "quill", "quirk", "quite", "quota",
+    "quote", "quoth", "rabbi", "rabid", "racer",
+    "radar", "radii", "radio", "radon", "rally",
+    "ramen", "ranch", "randy", "range", "rapid",
+    "rarer", "raspy", "ratio", "raven", "rayon",
+    "razor", "reach", "react", "ready", "realm",
+    "rebel", "rebus", "rebut", "recap", "recur",
+    "reedy", "refer", "regal", "rehab", "reign",
+    "relax", "relay", "relic", "remit", "renal",
+    "renew", "repay", "repel", "reply", "rerun",
+    "reset", "resin", "retch", "retro", "retry",
+    "reuse", "revel", "rider", "ridge", "rifle",
+    "right", "rigid", "rigor", "rinse", "ripen",
+    "riper", "risen", "risky", "rival", "river",
+    "rivet", "roach", "roast", "robin", "robot",
+    "rocky", "rogue", "roomy", "roost", "rouge",
+    "rough", "round", "rouse", "route", "rover",
+    "rowdy", "rower", "royal", "ruddy", "rugby",
+    "ruler", "rumba", "rumor", "rupee", "rural",
+    "rusty", "sadly", "safer", "saint", "salad",
+    "sally", "salon", "salsa", "salty", "salve",
+    "salvo", "sandy", "saner", "sappy", "sassy",
+    "sauce", "saucy", "sauna", "saute", "savor",
+    "savoy", "savvy", "scald", "scale", "scalp",
+    "scaly", "scamp", "scant", "scare", "scarf",
+    "scary", "scene", "scent", "scion", "scoff",
+    "scold", "scone", "scoop", "scope", "score",
+    "scorn", "scout", "scowl", "scram", "scrap",
+    "scrub", "scrum", "sedan", "seedy", "segue",
+    "seize", "sense", "sepia", "serve", "setup",
+    "seven", "sever", "sewer", "shack", "shade",
+    "shady", "shaft", "shake", "shaky", "shall",
+    "shame", "shank", "shape", "shard", "share",
+    "shark", "sharp", "shave", "shawl", "shear",
+    "sheen", "sheep", "sheer", "sheet", "shelf",
+    "shell", "shift", "shine", "shiny", "shire",
+    "shirk", "shirt", "shoal", "shock", "shone",
+    "shook", "shoot", "shore", "shorn", "short",
+    "shout", "shove", "shown", "showy", "shrub",
+    "shrug", "shuck", "shunt", "siege", "sieve",
+    "sight", "sigma", "silky", "silly", "since",
+    "sinew", "siren", "sissy", "sixth", "sixty",
+    "sized", "skate", "skier", "skimp", "skirt",
+    "skull", "skunk", "slack", "slain", "slang",
+    "slant", "slash", "slate", "slave", "sleek",
+    "sleep", "sleet", "slept", "slice", "slide",
+    "slime", "slimy", "sling", "slink", "slope",
+    "sloth", "slump", "slung", "slunk", "slurp",
+    "smack", "small", "smart", "smash", "smear",
+    "smell", "smelt", "smile", "smirk", "smite",
+    "smith", "smock", "smoke", "smoky", "snack",
+    "snail", "snake", "snaky", "snare", "snarl",
+    "sneak", "sneer", "snide", "sniff", "snipe",
+    "snoop", "snore", "snort", "snout", "snowy",
+    "snuck", "snuff", "soapy", "sober", "solar",
+    "solid", "solve", "sonic", "sooth", "sooty",
+    "sorry", "sound", "south", "space", "spade",
+    "spank", "spare", "spark", "spasm", "spawn",
+    "speak", "spear", "speck", "speed", "spell",
+    "spend", "spent", "spice", "spicy", "spied",
+    "spike", "spiky", "spill", "spine", "spite",
+    "splat", "split", "spoil", "spoke", "spoof",
+    "spook", "spool", "spoon", "spore", "sport",
+    "spout", "spray", "spree", "sprig", "spunk",
+    "spurn", "squad", "squat", "squid", "stack",
+    "staff", "stage", "staid", "stain", "stair",
+    "stake", "stale", "stalk", "stall", "stamp",
+    "stand", "stank", "staph", "stare", "stark",
+    "start", "stash", "state", "stave", "stead",
+    "steak", "steal", "steam", "steel", "steep",
+    "steer", "stern", "stick", "stiff", "still",
+    "stilt", "sting", "stink", "stint", "stock",
+    "stoic", "stoke", "stole", "stomp", "stone",
+    "stony", "stood", "stool", "stoop", "store",
+    "stork", "storm", "story", "stout", "stove",
+    "strap", "straw", "stray", "strip", "strew",
+    "stuck", "study", "stuff", "stump", "stung",
+    "stunk", "stunt", "style", "suave", "sugar",
+    "suing", "suite", "sulky", "sunny", "super",
+    "surge", "surly", "sushi", "swamp", "swarm",
+    "swath", "swear", "sweat", "sweep", "sweet",
+    "swell", "swept", "swift", "swill", "swine",
+    "swing", "swipe", "swirl", "swish", "swoon",
+    "swoop", "sword", "swore", "sworn", "swung",
+    "synod", "syrup", "tabby", "table", "taboo",
+    "tacit", "tacky", "taffy", "taint", "taken",
+    "taker", "talon", "tamer", "tango", "tangy",
+    "taper", "tapir", "tardy", "tarot", "taste",
+    "tasty", "tatty", "taunt", "tawny", "teach",
+    "teary", "tease", "teddy", "teeth", "tempo",
+    "tenet", "tenor", "tense", "tenth", "tepee",
+    "tepid", "terra", "terse", "theft", "their",
+    "theme", "there", "thick", "thief", "thigh",
+    "thing", "think", "third", "thorn", "those",
+    "three", "threw", "throb", "throw", "thrum",
+    "thumb", "thump", "thyme", "tiara", "tidal",
+    "tiger", "tight", "timer", "timid", "tipsy",
+    "titan", "title", "toast", "today", "token",
+    "tonal", "tongs", "tonic", "tooth", "topaz",
+    "topic", "torch", "torso", "total", "totem",
+    "touch", "tough", "towel", "tower", "toxic",
+    "trace", "track", "trade", "trail", "train",
+    "trait", "tramp", "trash", "trawl", "tread",
+    "treat", "trend", "triad", "trial", "tribe",
+    "trick", "tried", "trill", "trite", "troll",
+    "troop", "trope", "troth", "trout", "truce",
+    "truck", "truly", "trump", "trunk", "truss",
+    "trust", "truth", "tryst", "tulip", "tumor",
+    "tuner", "tunic", "turbo", "tutor", "twain",
+    "twang", "tweak", "tweed", "tweet", "twice",
+    "twill", "twine", "twist", "tying", "udder",
+    "ulcer", "ultra", "umbra", "uncle", "uncut",
+    "under", "undid", "undue", "unfed", "unfit",
+    "unify", "union", "unite", "unity", "unlit",
+    "unmet", "unset", "untie", "until", "unwed",
+    "unzip", "upper", "upset", "urban", "usage",
+    "usher", "using", "usual", "usurp", "utero",
+    "utter", "vague", "valid", "valor", "valve",
+    "vapid", "vault", "vaunt", "vegan", "venue",
+    "verge", "verse", "vigor", "villa", "vinyl",
+    "viola", "viper", "viral", "virus", "visor",
+    "vista", "vital", "vivid", "vixen", "vocal",
+    "vodka", "vogue", "voice", "voila", "voter",
+    "vouch", "vowel", "vulva", "wacky", "wafer",
+    "wager", "wagon", "waist", "waltz", "watch",
+    "water", "waver", "waxen", "weary", "weave",
+    "wedge", "weedy", "weigh", "weird", "welch",
+    "whale", "wheat", "wheel", "where", "which",
+    "while", "whiff", "whine", "whiny", "whirl",
+    "whisk", "white", "whole", "whose", "widen",
+    "wider", "widow", "width", "wield", "wince",
+    "winch", "windy", "wiper", "wiser", "witch",
+    "witty", "woken", "woman", "women", "world",
+    "worry", "worse", "worst", "worth", "would",
+    "wound", "wrack", "wrath", "wreak", "wreck",
+    "wrest", "wring", "wrist", "write", "wrong",
+    "wrote", "yacht", "yearn", "yeast", "yield",
+    "young", "youth", "zebra", "zesty", "zonal",
+]