docs: comprehensive Discord guide (rename + extend discord-bot-howto.md)

README.md

@@ -42,7 +42,7 @@ A lightweight, secure, cloud-native ACP harness that bridges **Discord, Slack**,
 <details>
 <summary><strong>Discord</strong></summary>
 
-See [docs/discord-bot-howto.md](docs/discord-bot-howto.md) for a detailed step-by-step guide.
+See [docs/discord.md](docs/discord.md) for a detailed step-by-step guide.
 
 </details>
 

docs/discord.md

@@ -0,0 +1,228 @@
+# Discord Guide
+
+Complete guide to setting up, configuring, and running OpenAB with Discord.
+
+## Bot Setup
+
+### 1. Create a Discord Application
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Click **New Application**
+3. Give it a name (e.g. `AgentBroker`) and click **Create**
+
+### 2. Enable Gateway Intents
+
+1. In your application, go to the **Bot** tab (left sidebar)
+2. Scroll down to **Privileged Gateway Intents**
+3. Enable **Message Content Intent**
+4. Enable **Server Members Intent** (recommended)
+5. Click **Save Changes**
+
+### 3. Get the Bot Token
+
+1. Still on the **Bot** tab, click **Reset Token**
+2. Copy the token — you'll need this for `DISCORD_BOT_TOKEN`
+3. Keep this token secret. If it leaks, reset it immediately
+
+### 4. Set Bot Permissions
+
+1. Go to **OAuth2** → **URL Generator** (left sidebar)
+2. Under **Scopes**, check `bot`
+3. Under **Bot Permissions**, check:
+   - Send Messages
+   - Send Messages in Threads
+   - Create Public Threads
+   - Read Message History
+   - Add Reactions
+   - Manage Messages
+4. Copy the generated URL at the bottom
+
+### 5. Invite the Bot to Your Server
+
+1. Open the URL from step 4 in your browser
+2. Select the server you want to add the bot to
+3. Click **Authorize**
+
+### 6. Get the Channel ID
+
+1. In Discord, go to **User Settings** → **Advanced** → enable **Developer Mode**
+2. Right-click the channel where you want the bot to respond
+3. Click **Copy Channel ID**
+4. Use this ID in `allowed_channels` in your config
+
+### 7. Get Your User ID (optional)
+
+1. Make sure **Developer Mode** is enabled (see step 6)
+2. Right-click your own username (in a message or the member list)
+3. Click **Copy User ID**
+4. Use this ID in `allowed_users` to restrict who can interact with the bot
+
+---
+
+## Configuration Reference
+
+```toml
+[discord]
+bot_token = "${DISCORD_BOT_TOKEN}"
+allowed_channels = ["123456789"]      # channel ID allowlist (empty = all)
+allowed_users = ["987654321"]         # user ID allowlist (empty = all)
+allow_bot_messages = "off"            # off | mentions | all
+allow_user_messages = "involved"      # involved | mentions
+trusted_bot_ids = []                  # bot user IDs allowed through (empty = any)
+```
+
+### `allowed_channels` / `allowed_users`
+
+| `allowed_channels` | `allowed_users` | Result |
+|---|---|---|
+| empty | empty | All users, all channels (default) |
+| set | empty | Only these channels, all users |
+| empty | set | All channels, only these users |
+| set | set | **AND** — must be in allowed channel AND allowed user |
+
+- Empty `allowed_users` (default) = no user filtering
+- Denied users get a 🚫 reaction and no reply
+
+### `allow_bot_messages`
+
+Controls whether the bot processes messages from other Discord bots.
+
+| Value | Behavior | Loop risk |
+|---|---|---|
+| `"off"` (default) | Ignore all bot messages | None |
+| `"mentions"` | Only process bot messages that @mention this bot | Very low |
+| `"all"` | Process all bot messages (capped at 10 consecutive) | Mitigated by turn cap |
+
+The bot's own messages are always ignored regardless of this setting.
+
+### `allow_user_messages`
+
+Controls whether the bot requires @mention in threads.
+
+| Value | Behavior |
+|---|---|
+| `"involved"` (default) | Respond in threads the bot owns or has participated in without @mention. Main channel always requires @mention. |
+| `"mentions"` | Always require @mention, even in the bot's own threads. |
+
+### `trusted_bot_ids`
+
+When `allow_bot_messages` is `"mentions"` or `"all"`, you can restrict which bots are allowed through:
+
+```toml
+trusted_bot_ids = ["123456789012345678"]  # only this bot's messages pass through
+```
+
+Empty (default) = any bot can pass through (subject to the mode check).
+
+---
+
+## @Mention Behavior
+
+**Always @mention the bot user, not the role.** Discord shows both in autocomplete — pick the one without the role icon.
+
+```
+✅ @AgentBroker hello     ← user mention, bot responds
+❌ @AgentBroker hello     ← role mention (with role icon), bot ignores
+```
+
+Role mentions are ignored because they are shared across bots and cause false positives in multi-bot setups. This is intentional since v0.7.8-beta.3 (#420, #440).
+
+---
+
+## Thread Behavior
+
+When you @mention the bot in a channel, it creates a **thread** from your message and responds there. After that:
+
+- **`involved` mode (default):** just type in the thread — no @mention needed
+- **`mentions` mode:** @mention required for every message, even in threads
+
+Each thread gets its own agent session. Sessions are cleaned up after `session_ttl_hours` (default: 24h).
+
+---
+
+## Multi-Bot Setup
+
+Multiple bots can share the same Discord channel. Each bot only responds to its own @mentions.
+
+### Helm example
+
+```bash
+helm install openab openab/openab \
+  --set agents.kiro.discord.botToken="$BOT_A_TOKEN" \
+  --set-string 'agents.kiro.discord.allowedChannels[0]=CHANNEL_ID' \
+  --set agents.dealer.discord.botToken="$BOT_B_TOKEN" \
+  --set-string 'agents.dealer.discord.allowedChannels[0]=CHANNEL_ID' \
+  --set agents.dealer.discord.enabled=true \
+  --set agents.dealer.command=kiro-cli \
+  --set 'agents.dealer.args={acp,--trust-all-tools}'
+```
+
+### Known limitations
+
+- **One thread per message:** when you @mention both bots in a single message, only the first bot creates a thread. The second bot's thread creation fails and the message is dropped. Workaround: @mention each bot in separate messages.
+- **Thread ownership:** a bot only responds in threads it owns or has participated in (`involved` mode). To have Bot B respond in Bot A's thread, use `mentions` mode and explicitly @mention Bot B.
+
+### Bot-to-bot communication
+
+To enable bots to collaborate (e.g. code review → deploy handoff):
+
+```toml
+# Bot that receives bot messages
+[discord]
+allow_bot_messages = "mentions"
+```
+
+See [multi-agent.md](multi-agent.md) for detailed examples.
+
+---
+
+## Helm Values
+
+```bash
+helm install openab openab/openab \
+  --set agents.kiro.discord.botToken="$DISCORD_BOT_TOKEN" \
+  --set-string 'agents.kiro.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
+  --set agents.kiro.discord.allowBotMessages=off \
+  --set agents.kiro.discord.allowUserMessages=involved
+```
+
+⚠️ Use `--set-string` for channel/user IDs to avoid float64 precision loss.
+
+---
+
+## Troubleshooting
+
+### Bot doesn't respond
+
+1. **Check channel ID** — make sure it's in `allowed_channels`
+2. **Check permissions** — bot needs Send Messages, Create Public Threads, Read Message History in the channel
+3. **Check intents** — Message Content Intent must be enabled in Developer Portal
+4. **Check @mention type** — use user mention, not role mention
+5. **Check if in a thread** — with `mentions` mode, @mention is required even in threads
+
+### Bot stops receiving messages after restart
+
+Discord Gateway may throttle event delivery after rapid reconnects. Use `scale 0 → wait 5s → scale 1` instead of `rollout restart`:
+
+```bash
+kubectl scale deployment/openab-kiro --replicas=0 && sleep 5 && kubectl scale deployment/openab-kiro --replicas=1
+```
+
+See [#455](https://github.com/openabdev/openab/issues/455) for details.
+
+### "Failed to create thread"
+
+Discord only allows one thread per message. If another bot already created a thread on the same message, this error appears. The message is dropped. This is a known limitation for multi-bot setups (#457).
+
+### "Sent invalid authentication"
+
+The bot token is wrong or expired. Reset it in the Developer Portal and redeploy.
+
+### "Failed to start agent"
+
+The agent CLI isn't authenticated. For kiro-cli:
+
+```bash
+kubectl exec -it deployment/openab-kiro -- kiro-cli login --use-device-flow
+kubectl rollout restart deployment/openab-kiro
+```