1 files changed, 82 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e7b6642
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# irc-bots
+
+A collection of [Sopel](https://sopel.chat/) IRC bots for self-hosted servers.
+
+| Bot | Purpose | Doc |
+|-----|---------|-----|
+| [alfred](alfred/) | Server management, bot control, file hosting, soju bouncer | [docs/alfred.md](docs/alfred.md) |
+| [osterman](osterman/) | Channel moderation, auto-modes, idle tracking | [docs/osterman.md](docs/osterman.md) |
+| [daffy](daffy/) | Duck hunting game | [docs/daffy.md](docs/daffy.md) |
+| [contessa](contessa/) | Recipe suggestions | [docs/contessa.md](docs/contessa.md) |
+| [shireen](shireen/) | News headlines and weather | [docs/shireen.md](docs/shireen.md) |
+| [daft](daft/) | YouTube playlist manager | [docs/daft.md](docs/daft.md) |
+| [herald](herald/) | Owner-follow bot and keyword responder | [docs/herald.md](docs/herald.md) |
+| [salvador](salvador/) | Image-to-mIRC-art renderer | [docs/salvador.md](docs/salvador.md) |
+
+## Requirements
+
+- Python 3.9+
+- [Sopel](https://sopel.chat/) 8.x
+
+```
+pip install sopel
+```
+
+Bot-specific dependencies:
+
+| Bot | Extra |
+|-----|-------|
+| alfred | `pip install requests` |
+| salvador | `pip install Pillow` |
+
+All others use only the standard library.
+
+## Install
+
+1. Clone or copy this repo.
+
+2. Copy the example config for the bot you want and fill in your details:
+   ```
+   cp alfred/alfred.cfg ~/.config/sopel/alfred.cfg
+   $EDITOR ~/.config/sopel/alfred.cfg
+   ```
+   Set `nick`, `host`, `port`, `owner`, and any `[section]` paths.
+   The `extra` key must point to the bot's directory (e.g. `/path/to/irc-bots/alfred`).
+
+3. Create any required data directories:
+   ```
+   mkdir -p /var/log/<botname>
+   # contessa: place recipes.json at the path set in [contessa] recipes_path
+   # shireen:  data.json is created automatically on first run
+   # osterman: db.json and track.db are created automatically on first run
+   # daffy:    scores.db is created automatically on first run
+   ```
+
+4. Start the bot:
+   ```
+   sopel --config ~/.config/sopel/<botname>.cfg
+   ```
+
+5. (Optional) Register as a service. Example OpenRC init script:
+   ```sh
+   #!/sbin/openrc-run
+   supervisor=supervise-daemon
+   command="/usr/bin/sopel"
+   command_args="--config /home/user/.config/sopel/<botname>.cfg"
+   command_user="user"
+   output_log="/var/log/<botname>/daemon.log"
+   error_log="/var/log/<botname>/daemon.log"
+   depend() { need net; }
+   ```
+
+## Notes
+
+- All bots use `!` as the command prefix by default (set `prefix` in config).
+- All bots share `!join`, `!part`, `!chans`, and `!help` as owner-only admin commands.
+  When multiple bots are in the same channel and the owner types one of these, all bots act - that's intentional.
+- **osterman** uses short-form aliases (`!b`, `!k`, `!v`, etc.) that are unique to it.
+  No other bot in this collection uses conflicting short forms.
+
+## License
+
+MIT - see [LICENSE](LICENSE).