docs: document keyword alert subscription plugin

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

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