From 551c8aece8f30f7495b8340e36fbabd5f49e4705 Mon Sep 17 00:00:00 2001
From: auric <auric@japegames.com>
Date: Sun, 22 Feb 2026 21:36:39 -0600
Subject: docs: document umbrella-bot in README and AGENTS

README gets a Matrix bot section covering setup, commands, config paths,
and dependencies. AGENTS gets the bot added to the file map and a full
Matrix bot section covering the formatting rules (markdown->HTML via the
markdown library, no emojis, no em dashes), power level requirements,
command/socket message mapping, tail data flow, and config layout.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index e4c83a6..30b5db8 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,9 @@ multiple server processes via log file tailing, RCON, and A2S probing,
 and exposes a Unix socket for CLI clients to attach, send commands, and
 receive real-time output.
 
+Comes with two clients: `umbrella-cli` (terminal) and `umbrella-bot`
+(Matrix room bridge).
+
 ## Features
 
 - Live log tailing via inotify with symlink resolution
@@ -108,6 +111,57 @@ umbrella-cli action <unit> <name>  # run a named action script
 umbrella-cli broadcast <message>   # send to all units' broadcast_cmd
 ```
 
+## Matrix bot
+
+`umbrella-bot` bridges a Matrix room to umbrella units. Requires a
+dedicated Matrix account and a room the bot is invited to.
+
+### Dependencies
+
+```bash
+pip install matrix-nio[e2e] aiofiles markdown
+```
+
+### Setup
+
+```bash
+# 1. Copy and edit the config (chmod 600 — contains bot password)
+sudo cp clients/umbrella-bot/bot.conf.example /etc/umbrella/bot.conf
+sudo chmod 600 /etc/umbrella/bot.conf
+
+# 2. First-run login — prints the device ID to add to bot.conf
+python3 clients/umbrella-bot/umbrella-bot.py --setup
+
+# 3. Run normally (or via systemd)
+python3 clients/umbrella-bot/umbrella-bot.py
+```
+
+A systemd unit is provided at `clients/umbrella-bot/umbrella-bot.service`.
+
+### Bot commands
+
+Users require power level >= 50 in the room.
+
+| Command | Description |
+|---------|-------------|
+| `!units` | List all units with state and player counts |
+| `!status <unit>` | Show unit state, players, and map |
+| `!tail <unit>` | Dump the last 30 lines of buffered output |
+| `!cmd <unit> <command>` | Send a console command (logged to audit log) |
+| `!broadcast <message>` | Send message to all running units |
+| `!restart <unit>` | Run the restart action |
+| `!update <unit>` | Run the update action |
+| `!action <unit> <action>` | Run a named action |
+| `!help` | Show command list |
+
+### Config paths
+
+| Path | Purpose |
+|------|---------|
+| `/etc/umbrella/bot.conf` | Bot credentials and room ID |
+| `/etc/umbrella/bot-store/` | E2E encryption key store (SQLite) |
+| `/var/log/umbrella/bot-audit.log` | Audit log of all `!cmd` invocations |
+
 ## Reload
 
 ```bash
-- 
cgit v1.2.3