# Lotus Matrix Bot

Matrix bot for the Lotus Guild homeserver (`matrix.lotusguild.org`), built with `matrix-nio`.

## Status: Planning

## Todo

### Core Setup
- [ ] Project scaffolding (`bot.py`, config, `.env`, requirements)
- [ ] matrix-nio async client with E2EE support
- [ ] Device verification / trust storage
- [ ] Logging (rotating file + stdout, matching Discord bot pattern)
- [ ] Config validation (homeserver URL, access token, room IDs)
- [ ] Graceful shutdown and reconnection handling

### Command Porting (from Discord bot)
- [ ] `!help` - List all available commands
- [ ] `!ping` - Bot latency check
- [ ] `!8ball <question>` - Magic 8-ball
- [ ] `!fortune` - Fortune cookie message
- [ ] `!flip` - Coin flip
- [ ] `!roll <NdS>` - Dice roller
- [ ] `!random <min> <max>` - Random number generator
- [ ] `!rps <choice>` - Rock Paper Scissors
- [ ] `!poll <question>` - Poll (using reactions)
- [ ] `!trivia` - Trivia game (using reactions for answers)
- [ ] `!agent` - Random Valorant agent picker
- [ ] `!champion` - Random LoL champion picker
- [ ] `!problem` - Canada geese appreciation

### Integrations
- [ ] `!minecraft <username>` - RCON whitelist (Mojang API validation + RCON)
- [ ] `!hytale <username>` - Hytale whitelist request (audit log to admin room)
- [ ] `!ask <question>` - Ollama LLM integration (lotusllm model)

### Media Commands
- [ ] `!kill @user` - Kill GIF
- [ ] `!punch @user` - Punch GIF
- [ ] `!hug @user` - Hug GIF
- [ ] `!revive @user` - Revive GIF
- [ ] Media file management (GIF storage and random selection)

### Admin Commands
- [ ] `!clear <count>` - Redact messages (requires power level)
- [ ] `!health` - Bot stats (uptime, command counts, service status)
- [ ] Power level checks (Matrix equivalent of Discord role checks)

### Audit Logging
- [ ] Member join/leave events
- [ ] Message edits and redactions
- [ ] Room state changes
- [ ] Batched audit log posting to admin room

### Deployment
- [ ] Systemd service (`matrixbot.service`)
- [ ] Auto-deploy from Gitea webhook (matching Discord bot pattern)
- [ ] Deployment script (`/usr/local/bin/matrix_bot_deploy.sh`)
- [ ] Determine host LXC (new container or colocate with Synapse on 10.10.10.205)

### Not Porting (Discord-specific)
- Reaction roles (no Matrix equivalent)
- 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.205)
- **Dependencies**: matrix-nio[e2ee], aiohttp, python-dotenv, mcrcon

## Production Server
- **Host**: TBD
- **Bot Directory**: TBD
- **Service**: `matrixbot.service`

## Gitea
- **Repo**: https://code.lotusguild.org/LotusGuild/matrixBot