docs: update docs for Telegram integration

docs/USAGE.md

@@ -1400,3 +1400,77 @@ The bot returns a JSON response:
 ```
 
 Multiple reply lines are joined with `\n`.
+
+## Telegram Integration
+
+Connect derp to Telegram via long-polling (`getUpdates`). All outbound HTTP
+is routed through the SOCKS5 proxy. No public endpoint required, no Telegram
+SDK dependency.
+
+### How It Works
+
+The bot calls `getUpdates` in a loop with a long-poll timeout (default 30s).
+When a message arrives with the configured prefix, it is dispatched through
+the shared plugin registry. Replies are sent immediately via `sendMessage`.
+
+### Configuration
+
+```toml
+[telegram]
+enabled = true
+bot_token = "123456:ABC-DEF..."    # from @BotFather
+poll_timeout = 30                   # long-poll timeout in seconds
+admins = [123456789]                # Telegram user IDs (numeric)
+operators = []                      # Telegram user IDs
+trusted = []                        # Telegram user IDs
+```
+
+### Telegram Setup
+
+1. **Create a bot** via [@BotFather](https://t.me/BotFather):
+   - `/newbot` and follow the prompts
+   - Copy the bot token and set `bot_token` in config
+
+2. **Add the bot** to a group or send it a DM
+
+3. **Configure permissions** using Telegram user IDs. Use `!whoami` to
+   discover your numeric user ID.
+
+### Permission Tiers
+
+Same 4-tier model as IRC, but matches exact Telegram user IDs (numeric
+strings) instead of fnmatch hostmask patterns:
+
+```toml
+[telegram]
+admins = [123456789]
+operators = [987654321]
+trusted = [111222333]
+```
+
+### Plugin Compatibility
+
+Same compatibility as Teams -- ~90% of plugins work without modification.
+
+| Feature | IRC | Telegram |
+|---------|-----|----------|
+| `bot.reply()` | Sends PRIVMSG | `sendMessage` API call |
+| `bot.send()` | Sends PRIVMSG | `sendMessage` API call |
+| `bot.action()` | CTCP ACTION | Italic Markdown text |
+| `bot.long_reply()` | Paste overflow | Paste overflow (same logic) |
+| `bot.state` | Per-server SQLite | Per-server SQLite |
+| `bot.join/part/kick/mode` | IRC commands | No-op (logged at debug) |
+| Event handlers (JOIN, etc.) | Fired on IRC events | Not triggered |
+| Hostmask ACL | fnmatch patterns | Exact user IDs |
+| Message limit | 512 bytes (IRC) | 4096 chars (Telegram) |
+
+### Group Commands
+
+In groups, Telegram appends `@botusername` to commands. The bot strips
+this automatically: `!help@mybot` becomes `!help`.
+
+### Transport
+
+All HTTP traffic (API calls, long-polling) routes through the SOCKS5
+proxy at `127.0.0.1:1080` via `derp.http.urlopen`. No direct outbound
+connections are made.