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 |

matrixbot/bot.py

@@ -1,6 +1,5 @@
 import asyncio
 import json
-import logging
 import signal
 import sys
 from pathlib import Path
@@ -10,6 +9,7 @@ from nio import (
     AsyncClientConfig,
     InviteMemberEvent,
     LoginResponse,
+    ReactionEvent,
     RoomMemberEvent,
     RoomMessageText,
     UnknownEvent,
@@ -26,7 +26,7 @@ from config import (
 )
 from callbacks import Callbacks
 from utils import setup_logging
-from welcome import post_welcome_message
+from welcome import log_ready as _welcome_log_ready
 
 logger = setup_logging(LOG_LEVEL)
 
@@ -144,7 +144,8 @@ async def main():
 
     callbacks = Callbacks(client)
     client.add_event_callback(callbacks.message, RoomMessageText)
-    client.add_event_callback(callbacks.reaction, UnknownEvent)
+    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
@@ -178,8 +179,7 @@ async def main():
     # Trust devices after initial sync loads the device store
     await trust_devices(client)
 
-    # Post welcome message (idempotent — only posts if not already stored)
-    await post_welcome_message(client)
+    _welcome_log_ready()
 
     logger.info("Bot ready as %s — listening for commands", MATRIX_USER_ID)
 

matrixbot/callbacks.py

@@ -1,10 +1,19 @@
 import logging
 from functools import wraps
 
-from nio import AsyncClient, RoomMessageText, UnknownEvent
+from nio import AsyncClient
 
 from config import BOT_PREFIX, MATRIX_USER_ID
-from commands import COMMANDS, metrics
+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")
@@ -42,6 +51,13 @@ class Callbacks:
             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
 
@@ -63,16 +79,28 @@ class Callbacks:
         await wrapped(self.client, room.room_id, event.sender, args)
 
     async def reaction(self, room, event):
-        """Handle m.reaction events (sent as UnknownEvent by matrix-nio)."""
-        # Ignore events from before startup
+        """Handle ReactionEvent (nio's native reaction type)."""
         if self.startup_sync_token is None:
             return
-
-        # Ignore our own reactions
         if event.sender == MATRIX_USER_ID:
             return
 
-        # m.reaction events come as UnknownEvent with type "m.reaction"
+        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
 
@@ -83,10 +111,13 @@ class Callbacks:
 
         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
-        )
+        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."""

matrixbot/config.py

@@ -1,5 +1,4 @@
 import os
-import logging
 from dotenv import load_dotenv
 
 load_dotenv()
@@ -19,7 +18,9 @@ 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", "lotusllm")
+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", "")

matrixbot/requirements.txt

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

matrixbot/utils.py

@@ -87,6 +87,31 @@ async def send_html(client: AsyncClient, room_id: str, plain: str, html: str):
     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,

matrixbot/welcome.py

@@ -19,11 +19,15 @@ 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 (skip Management + Cool Kids)
+# 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 (v12)
-    "!ou56mVZQ8ZB7AhDYPmBV5_BR28WMZ4x5zwZkPCqjq1s",  # Commands (v12)
-    "!GK6v5cLEEnowIooQJv5jECfISUjADjt8aKhWv9VbG5U",  # Memes (v12)
+    "!wfokQ1-pE896scu_AOcCBA2s3L4qFo-PTBAFTd0WMI0",  # General
+    "!GK6v5cLEEnowIooQJv5jECfISUjADjt8aKhWv9VbG5U",  # Memes
+    "!ktQu0gavhjpCMkgxk8SYdb6mnJRY-u7mY7_KfksV0SU",  # Music
+    "!ARbRFSPNp2U0MslWTBGoTT3gbmJJ25dPRL6enQntvPo",   # Voice
+    "!3gMjTHqV-r823ZrvXnck7waB0Pd8tiCu-zbF7mSS83E",   # Voice 2
 ]
 
 WELCOME_EMOJI = "\u2705"  # checkmark
@@ -49,6 +53,17 @@ def _save_state(state: dict):
         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()
@@ -57,6 +72,12 @@ async def handle_space_join(client: AsyncClient, sender: str):
     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)
@@ -66,13 +87,13 @@ async def handle_space_join(client: AsyncClient, sender: str):
 
     plain = (
         "Welcome to The Lotus Guild!\n\n"
-        f"React to this message with {WELCOME_EMOJI} to get invited to all channels.\n\n"
-        "You'll be added to General, Commands, and Memes."
+        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 channels.</p>"
-        "<p>You'll be added to <b>General</b>, <b>Commands</b>, and <b>Memes</b>.</p>"
+        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)
@@ -145,6 +166,5 @@ async def handle_welcome_reaction(
         await send_text(client, room_id, "You're already in all the channels!")
 
 
-async def post_welcome_message(client: AsyncClient):
-    """No-op kept for backward compatibility with bot.py startup."""
+def log_ready():
     logger.info("Welcome module ready — watching Space for new members")

matrixbot/wordle.py

@@ -317,7 +317,6 @@ def render_keyboard_plain(game: WordleGame) -> str:
             letter_states[letter] = max(letter_states.get(letter, -1), score)
 
     lines = []
-    symbols = {-1: " ", 0: "\u2717", 1: "?", 2: "\u2713"}
     for row in _KB_ROWS:
         chars = []
         for letter in row:
@@ -465,7 +464,7 @@ async def wordle_start_or_status(client: AsyncClient, room_id: str, sender: str,
     if sender in _active_games:
         game = _active_games[sender]
         if not game.finished:
-            guesses_left = 6 - len(game.guesses)
+            _ = 6 - len(game.guesses)
             grid_plain = render_grid_plain(game)
             kb_plain = render_keyboard_plain(game)
             plain = (
@@ -626,7 +625,7 @@ async def wordle_guess(
         return
 
     # Still playing — show grid + keyboard
-    guesses_left = 6 - len(game.guesses)
+    _ = 6 - len(game.guesses)
     grid_plain = render_grid_plain(game)
     kb_plain = render_keyboard_plain(game)
     plain = (