docs: note Kiro API-key MCP issue and fix multibot thread-owner docs

docs/discord.md

@@ -105,7 +105,9 @@ Controls whether the bot requires @mention in threads.
 |---|---|
 | `"involved"` | 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. |
-| `"multibot-mentions"` (default) | Same as `involved` in single-bot threads. In threads where other bots have also posted, requires @mention — prevents all bots from responding to every message. |
+| `"multibot-mentions"` (default) | Same as `involved` in single-bot threads. In threads where other bots have also posted, requires @mention — prevents all bots from responding to every message. This applies to the thread owner too: once another bot has posted in the thread, the owner also needs an @mention. |
+
+> **Note:** The thread-owner rule in `"multibot-mentions"` describes current behavior. It is tracked in [#1566](https://github.com/openabdev/openab/issues/1566), which calls it a bug, so it may change.
 
 #### Comparison
 
@@ -161,10 +163,13 @@ When `allow_user_messages = "multibot-mentions"` is set alongside `allowed_role_
 | Action | Result |
 |--------|--------|
 | `@Role review this` in a channel | All bots trigger (role mention = explicit mention) |
-| Follow-up in the thread without @mention | Only the thread owner responds (multibot gate kicks in) |
+| Follow-up in the thread without @mention | No bot responds once more than one bot has posted in the thread, including the thread owner (multibot gate kicks in) |
+| `@Bot follow up` in the thread | Only the mentioned bot responds |
 | `@Role follow up` in the thread | All bots respond again |
 
-This gives the best of both worlds: one role mention to summon all bots, but subsequent messages in the thread don't cause all bots to pile on.
+This gives the best of both worlds: one role mention to summon all bots, but subsequent messages in the thread don't cause all bots to pile on. In a multi-bot thread, address each follow-up with an @mention of the bot (or role) you want to answer.
+
+> **Note:** The owner-needs-@mention behavior above describes current behavior. It is tracked in [#1566](https://github.com/openabdev/openab/issues/1566), which calls it a bug, so it may change.
 
 ---
 

docs/kiro.md

@@ -55,6 +55,8 @@ To override a single agent's image instead of the global tag:
 
 Kiro CLI supports API key authentication via the `KIRO_API_KEY` environment variable. This is the **recommended** approach — it requires no manual OAuth login and is fully managed by AWS Secrets Manager.
 
+If MCP servers or web tools are disabled with this setup, see [Known issue: MCP and web tools disabled with `KIRO_API_KEY`](#known-issue-mcp-and-web-tools-disabled-with-kiro_api_key).
+
 #### Setup Steps
 
 1. **Enable API Keys in AWS Console** — Go to your AWS Console and search for "Kiro". Enable the API Keys feature. This option is only available through the AWS Console.
@@ -141,6 +143,40 @@ sequenceDiagram
 
 This makes the entire Kiro deployment **zero-touch** — fully automated with no login step required.
 
+#### Known issue: MCP and web tools disabled with `KIRO_API_KEY`
+
+> **Temporary note.** Remove this section once the upstream bug is fixed and a fixed Kiro CLI version has been tested.
+
+An upstream Kiro bug ([kirodotdev/Kiro#11777](https://github.com/kirodotdev/Kiro/issues/11777), reproduced on Kiro CLI 2.33.1) can leave an API-key-authenticated agent where chat works but MCP servers and web tools are unavailable. A successful `kiro-cli whoami` or a normal chat reply does not prove that MCP loaded. Typical symptoms in the Kiro logs:
+
+```text
+GetProfile failed on all endpoints for API key
+Failed to get governance config from API — MCP disabled, web tools disabled
+```
+
+ACP may also emit `_kiro.dev/mcp/governance_disabled` with `apiFailure: true`.
+
+**Workaround (tested): GitHub OAuth login instead of the API key**
+
+1. Inside the persistent agent home, as the agent user, log in without the API key in the environment and select **Use with GitHub** in the menu:
+
+   ```bash
+   env -u KIRO_API_KEY kiro-cli login --use-device-flow
+   ```
+
+2. Confirm the login method (not just the email):
+
+   ```bash
+   env -u KIRO_API_KEY kiro-cli whoami   # expect "Logged in with GitHub"
+   ```
+
+3. Stop passing `KIRO_API_KEY` to the agent subprocess: remove it from `[agent].env` (and from `inherit_env` or any wrapper that re-adds it). Unsetting it only in the login shell is not enough if OpenAB injects it again when spawning Kiro. If `config.toml` is generated, fix the generator too. For Helm installs, also remove the `KIRO_API_KEY` entry from `agents.<name>.secretEnv`, so the key is no longer injected into the container environment. The agent subprocess only receives it if `[agent].env` or `inherit_env` lists it, so make sure neither does.
+4. Make sure `~/.kiro/` and `~/.local/share/kiro-cli/` are persisted (see [Persisted Paths](#persisted-paths-pvc)).
+5. Restart OpenAB and start a fresh session so no API-key-authenticated Kiro process is reused.
+6. Verify that MCP servers initialize and that a real read-only tool call succeeds.
+
+When reporting this issue, include the image tag or digest and `kiro-cli --version`. Floating `nightly` tags follow the latest upstream CLI, so behavior can change without any OpenAB config change. See [#1576](https://github.com/openabdev/openab/issues/1576).
+
 ### Alternative: OAuth Device Flow (Legacy)
 
 If you cannot use an API key, Kiro CLI falls back to the OAuth device code flow. The PVC persists tokens across pod restarts.