1 files changed, 63 insertions, 0 deletions
diff --git a/docs/herald.md b/docs/herald.md
new file mode 100644
index 0000000..d651d4f
--- /dev/null
+++ b/docs/herald.md
@@ -0,0 +1,63 @@
+# herald
+
+Owner-follow bot with a configurable keyword responder.
+
+Herald tracks the owner's IRC presence and mirrors their channel movements.
+It can also respond to keywords in channel messages with random replies.
+
+## Dependencies
+
+No external libraries required.
+
+## Plugins
+
+| File | Role |
+|------|------|
+| `commands.py` | Follow logic and admin commands |
+| `respond.py` | Keyword-based auto-responder |
+
+## Commands (owner only)
+
+| Command | Description |
+|---------|-------------|
+| `!pause` | Pause keyword responses |
+| `!resume` | Resume keyword responses |
+| `!follow on` | Start tracking owner's channels (checks every 30s via WHOIS) |
+| `!follow off` | Stop tracking |
+| `!unfollow` | Immediately leave all follow-joined channels |
+| `!join #channel` | Join a channel manually |
+| `!part [#channel]` | Leave a channel |
+| `!chans` | List channels |
+| `!help` | Show usage (PM) |
+
+## Automatic behaviour
+
+- When the owner PARTs a channel, herald leaves too (unless it's a preconfigured channel).
+- When the owner QUITs, herald leaves all non-preconfigured channels.
+- With `!follow on`, herald also joins any channel the owner is in that herald isn't.
+
+Preconfigured channels are the ones listed under `channels` in the config.
+
+## Keyword responder (`respond.py`)
+
+Configure in `[respond]`:
+
+```ini
+[respond]
+keywords =
+    hello
+    hi there
+responses =
+    Hey!
+    What's up?
+```
+
+When any `keyword` appears (case-insensitive) in a channel message, herald
+replies with a randomly chosen response.
+
+## Config keys
+
+| Key | Description |
+|-----|-------------|
+| `[respond] keywords` | Newline-separated list of trigger words |
+| `[respond] responses` | Newline-separated list of possible replies |