docs: document YouTube follow plugin

docs/USAGE.md

@@ -562,3 +562,39 @@ Polling and announcements:
 - Supports HTTP conditional requests (`ETag`, `If-Modified-Since`)
 - 5 consecutive errors doubles the poll interval (max 1 hour)
 - Feed subscriptions persist across bot restarts via `bot.state`
+
+### `!yt` -- YouTube Channel Subscriptions
+
+Follow YouTube channels and announce new videos in IRC channels. Accepts any
+YouTube URL (video, channel, handle, shorts, embed) and resolves it to the
+channel's Atom feed.
+
+```
+!yt follow <url> [name]    Follow a YouTube channel (admin)
+!yt unfollow <name>        Unfollow a channel (admin)
+!yt list                   List followed channels
+!yt check <name>           Force-poll a channel now
+```
+
+- `follow` and `unfollow` require admin privileges
+- All subcommands must be used in a channel (not PM)
+- If `name` is omitted on `follow`, it is derived from the channel title
+- Names must be lowercase alphanumeric + hyphens, 1-20 characters
+- Maximum 20 channels per IRC channel
+
+URL resolution:
+
+- `/channel/UCXXX` URLs extract the channel ID directly
+- All other YouTube URLs (handles, videos, shorts) fetch the page to resolve
+- Constructs the YouTube Atom feed URL from the resolved channel ID
+
+Polling and announcements:
+
+- Channels are polled every 10 minutes by default
+- On `follow`, existing videos are recorded without announcing (prevents flood)
+- New videos are announced as `[name] Video Title -- https://www.youtube.com/watch?v=ID`
+- Maximum 5 videos announced per poll; excess shown as `... and N more`
+- Titles are truncated to 80 characters
+- Supports HTTP conditional requests (`ETag`, `If-Modified-Since`)
+- 5 consecutive errors doubles the poll interval (max 1 hour)
+- Subscriptions persist across bot restarts via `bot.state`