docs: update docs for Mumble integration

Add Mumble sections to USAGE.md, CHEATSHEET.md, API.md, README.md. Mark Mumble done in ROADMAP.md and TODO.md. Update TASKS.md sprint.
2026-02-21 21:02:46 +01:00
parent 37c858f4d7
commit ca46042c41
7 changed files with 262 additions and 1 deletions
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -1474,3 +1474,83 @@ this automatically: `!help@mybot` becomes `!help`.
 All HTTP traffic (API calls, long-polling) routes through the SOCKS5
 proxy at `127.0.0.1:1080` via `derp.http.urlopen`. No direct outbound
 connections are made.
+
+## Mumble Integration
+
+Connect derp to a Mumble server via TCP/TLS protobuf control channel.
+Text chat only (no voice). All TCP is routed through the SOCKS5 proxy.
+No protobuf library dependency -- uses a minimal built-in varint/field
+encoder/decoder for the ~7 message types needed.
+
+### How It Works
+
+The bot connects to the Mumble server over TLS (via SOCKS5), sends
+Version and Authenticate messages, then enters a read loop. It tracks
+channels (ChannelState), users (UserState), and dispatches commands
+from TextMessage messages through the shared plugin registry.
+
+### Configuration
+
+```toml
+[mumble]
+enabled = true
+host = "mumble.example.com"        # Mumble server hostname
+port = 64738                        # Default Mumble port
+username = "derp"                   # Bot username
+password = ""                       # Server password (optional)
+tls_verify = false                  # Mumble commonly uses self-signed certs
+admins = ["admin_user"]             # Mumble usernames
+operators = []                      # Mumble usernames
+trusted = []                        # Mumble usernames
+```
+
+### Mumble Setup
+
+1. **Ensure a Mumble server** (Murmur/Mumble-server) is running and
+   accessible through the SOCKS5 proxy
+
+2. **Configure the bot** with the server hostname, port, and credentials
+
+3. **Configure permissions** using Mumble registered usernames. Use
+   `!whoami` to discover your username as the bot sees it.
+
+### Permission Tiers
+
+Same 4-tier model as IRC, but matches exact Mumble usernames instead of
+fnmatch hostmask patterns:
+
+```toml
+[mumble]
+admins = ["admin_user"]
+operators = ["oper_user"]
+trusted = ["trusted_user"]
+```
+
+### Plugin Compatibility
+
+Same compatibility as Teams/Telegram -- ~90% of plugins work without
+modification.
+
+| Feature | IRC | Mumble |
+|---------|-----|--------|
+| `bot.reply()` | Sends PRIVMSG | TextMessage to channel |
+| `bot.send()` | Sends PRIVMSG | TextMessage to channel |
+| `bot.action()` | CTCP ACTION | Italic HTML text (`<i>...</i>`) |
+| `bot.long_reply()` | Paste overflow | Paste overflow (same logic) |
+| `bot.state` | Per-server SQLite | Per-server SQLite |
+| `bot.join/part/kick/mode` | IRC commands | No-op (logged at debug) |
+| Event handlers (JOIN, etc.) | Fired on IRC events | Not triggered |
+| Hostmask ACL | fnmatch patterns | Exact usernames |
+
+### Text Encoding
+
+Mumble uses HTML for text messages. On receive, the bot strips tags and
+unescapes entities. On send, text is HTML-escaped. Action messages use
+`<i>` tags for italic formatting.
+
+### Transport
+
+All TCP connections route through the SOCKS5 proxy at `127.0.0.1:1080`
+via `derp.http.create_connection`. TLS is applied on top of the proxied
+socket. Mumble commonly uses self-signed certificates, so `tls_verify`
+defaults to `false`.