docs: document keyword alert subscription plugin

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/CHEATSHEET.md

@@ -53,12 +53,15 @@ format = "json"    # JSONL output (default: "text")
 ## Container
 
 ```bash
-make build            # Build image
+make build            # Build image (only for dep changes)
 make up               # Start (podman-compose)
 make down             # Stop
 make logs             # Follow logs
 ```
 
+Code, plugins, config, and data are bind-mounted. No rebuild needed for
+code changes -- restart the container or use `!reload` for plugins.
+
 ## Bot Commands
 
 ```
@@ -329,6 +332,21 @@ Names: lowercase alphanumeric + hyphens, 1-20 chars. Max 20 streamers/channel.
 Polls every 2min. Announces offline->live transitions. Persists across restarts.
 No API credentials needed (uses public GQL endpoint).
 
+## Alert
+
+```
+!alert add <name> <keyword...>   # Add keyword alert (admin)
+!alert del <name>                # Remove alert (admin)
+!alert list                      # List alerts
+!alert check <name>              # Force-poll now
+```
+
+Searches keywords across YouTube (InnerTube) and Twitch (GQL) simultaneously.
+Names: lowercase alphanumeric + hyphens, 1-20 chars. Keywords: 1-100 chars.
+Max 20 alerts/channel. Polls every 5min. Max 5 announcements per platform per cycle.
+Format: `[name/yt] Title -- URL` or `[name/tw] Title -- URL`.
+No API credentials needed. Persists across restarts.
+
 ## Plugin Template
 
 ```python

docs/USAGE.md

@@ -629,3 +629,41 @@ Polling and announcements:
 - Subscriptions persist across bot restarts via `bot.state`
 - `list` shows live/error status indicators next to each streamer
 - `check` forces an immediate poll and reports current status
+
+### `!alert` -- Keyword Alert Subscriptions
+
+Search keywords across multiple platforms (YouTube, Twitch) and announce new
+results. Unlike `!rss`/`!yt`/`!twitch` which follow specific channels/feeds,
+`!alert` searches keywords across all supported platforms simultaneously.
+
+```
+!alert add <name> <keyword...>   Add keyword alert (admin)
+!alert del <name>                Remove alert (admin)
+!alert list                      List alerts
+!alert check <name>              Force-poll now
+```
+
+- `add` and `del` require admin privileges
+- All subcommands must be used in a channel (not PM)
+- Name is required as the first argument after `add`; everything after is the keyword
+- Names must be lowercase alphanumeric + hyphens, 1-20 characters
+- Keywords: 1-100 characters, free-form text
+- Maximum 20 alerts per IRC channel
+
+Platforms searched:
+
+- **YouTube** -- InnerTube search API (no auth required)
+- **Twitch** -- Public GQL endpoint: live streams and VODs (no auth required)
+
+Polling and announcements:
+
+- Alerts are polled every 5 minutes by default
+- On `add`, existing results are recorded without announcing (prevents flood)
+- New results announced as `[name/yt] Title -- URL` or `[name/tw] Title -- URL`
+- Maximum 5 items announced per platform per poll; excess shown as `... and N more`
+- Titles are truncated to 80 characters
+- Each platform maintains its own seen list (capped at 200 per platform)
+- 5 consecutive errors doubles the poll interval (max 1 hour)
+- Subscriptions persist across bot restarts via `bot.state`
+- `list` shows error status indicators next to each alert
+- `check` forces an immediate poll across all platforms