[chaodu-agent]

What problem does this solve?

Two documentation gaps reported by users:

1. docs/kiro.md recommends KIRO_API_KEY auth, but an upstream Kiro bug (kiro-cli headless with API key: GetProfile returns "User is not authorized to access this feature", governance fails, MCP and web tools disabled (Pro, Google sign-in) kirodotdev/Kiro#11777, reproduced on Kiro CLI 2.33.1) can leave chat working while MCP servers and web tools are disabled. Users following the recommended path get no hint why.
2. docs/discord.md contradicts itself about multibot-mentions. The allow_user_messages comparison table (multi-bot thread, no @mention: no reply) matches the code, but the allowed_role_ids section says "Follow-up in the thread without @mention: Only the thread owner responds". In crates/openab-core/src/discord.rs (AllowUsers::MultibotMentions), the thread owner is marked involved but still returns early when another bot has posted, so the owner also needs an @mention.

Closes #1576
Refs #1566

Discord Discussion URL: Not applicable - maintainer docs fix for #1576 / #1566

Review Contract

Goal

• Warn Kiro users about the upstream API-key MCP/web-tools failure and document the tested GitHub OAuth workaround from docs: document Kiro API-key MCP failure and GitHub login workaround (upstream #11777) #1576.
• Make docs/discord.md describe current multibot-mentions behavior consistently, including for the thread owner.

Non-goals

• No code changes. Behavior of AllowUsers::MultibotMentions is unchanged.
• Does not add the proposed thread_owner_involved setting from bug(discord): thread owner stops answering un-mentioned messages in multibot-mentions threads (docs say it should) #1566; that stays open for a separate decision, which is why this PR uses "Refs bug(discord): thread owner stops answering un-mentioned messages in multibot-mentions threads (docs say it should) #1566" rather than closing it.
• Does not change the recommended Kiro auth method, the default image channel, or the channel-specific guides.

Accepted Residual Risks

• The Kiro note is temporary and may go stale once upstream fixes #11777. Mitigation: the note says to remove it after a fixed Kiro CLI version is tested, and links the upstream issue.
• The workaround was tested by the reporter with GitHub login on Kiro CLI 2.33.1 only; other providers and versions are not claimed.

Acceptance Criteria

• docs/kiro.md Authentication section has a known-issue note linking kiro-cli headless with API key: GetProfile returns "User is not authorized to access this feature", governance fails, MCP and web tools disabled (Pro, Google sign-in) kirodotdev/Kiro#11777, naming the affected version (2.33.1), and describing the GitHub OAuth workaround steps from docs: document Kiro API-key MCP failure and GitHub login workaround (upstream #11777) #1576.
• The note says to remove it once upstream is fixed.
• docs/discord.md no longer claims the thread owner answers un-mentioned follow-ups in multi-bot threads; both sections agree with AllowUsers::MultibotMentions in discord.rs.
• No source files changed.

Follow-ups

• Decide on bug(discord): thread owner stops answering un-mentioned messages in multibot-mentions threads (docs say it should) #1566's opt-in thread_owner_involved proposal separately.
• Revisit and remove the Kiro known-issue note after upstream #11777 is fixed and verified.

At a Glance

N/A - docs-only change.

Prior Art & Industry Research

Not applicable - docs-only correction of existing behavior and an upstream known-issue note.

OpenClaw: Not applicable - docs-only.

Hermes Agent: Not applicable - docs-only.

Proposed Solution

• docs/kiro.md: new "Known issue: MCP and web tools disabled with KIRO_API_KEY" subsection under the API key section, with log symptoms, the six workaround steps (device login with env -u KIRO_API_KEY, verify "Logged in with GitHub", stop forwarding the key to the agent subprocess, persist ~/.kiro/ and ~/.local/share/kiro-cli/, restart with a fresh session, verify a real tool call), and a diagnostics hint for nightly tags.
• docs/discord.md: the multibot-mentions row in the allow_user_messages table now states the owner also needs an @mention once another bot posted; the allowed_role_ids interaction table row is corrected, and a row for @Bot follow up is added.

Why this approach?

The issue for #1566 itself offers this as the alternative if current behavior is kept. Fixing the docs to match the code is low-risk and removes the contradiction now, while the behavior change remains a separate product decision.

Alternatives Considered

• Implement thread_owner_involved (bug(discord): thread owner stops answering un-mentioned messages in multibot-mentions threads (docs say it should) #1566 proposal): a behavior/config change that needs maintainer decision; out of scope here.
• Drop the API key recommendation for Kiro: too broad for an upstream bug that may be fixed soon.

Validation

• Docs-only change; no Rust, Helm, or workflow files touched.
• Checked the discord.md wording against AllowUsers::MultibotMentions in crates/openab-core/src/discord.rs (owner path sets involved = true but still returns when other_bot is true).
• Internal anchor #persisted-paths-pvc matches the existing "Persisted Paths (PVC)" heading.
• CI on this PR.

[chaodu-agent]

Note

LGTM ✅ - The round-2 finding is fixed: workaround step 3 now names both [agent].env and inherit_env as the ways KIRO_API_KEY reaches the Kiro subprocess, which matches the code. No open findings remain.

What This PR Does

Fixes two documentation gaps. docs/kiro.md recommends KIRO_API_KEY without warning about an upstream Kiro bug (kirodotdev/Kiro#11777) that disables MCP servers and web tools under API-key auth. docs/discord.md contradicted itself about whether the thread owner answers follow-ups without an @mention in multibot-mentions mode.

How It Works

• docs/kiro.md: a callout under "Recommended: API Key" (line 58) links to a new temporary "Known issue" subsection (line 146). That subsection lists log symptoms, a six-step GitHub OAuth workaround, and the condition for removing it.
• docs/discord.md: the multibot-mentions row (line 108) and the allowed_role_ids interaction table (line 166) now say that once another bot has posted, the thread owner also needs an @mention. A @Bot follow up row is added, and both spots link bug(discord): thread owner stops answering un-mentioned messages in multibot-mentions threads (docs say it should) #1566 because the behavior may change.
• New in b1862a6: the last sentence of step 3 now reads "The agent subprocess only receives it if [agent].env or inherit_env lists it, so make sure neither does."

Findings

#	Severity	Finding	Location
1	🟢	Step 3 now matches how build_agent_env forwards env to the Kiro subprocess	docs/kiro.md:173
2	🟢	Discord thread-owner wording matches the gate in code and its unit tests	docs/discord.md:108, docs/discord.md:166
3	🟢	Kiro note is scoped, version-pinned, self-expiring, and asks for a real tool call as proof	docs/kiro.md:146-178
4	🟢	Links and in-page anchors resolve; docs-only change with passing checks	-

Finding Details

🟢 F1: Step 3 env-forwarding sentence is now correct

build_agent_env in crates/openab-core/src/acp/connection.rs (lines 206-227) copies every [agent].env entry into the child env, then adds each inherit_env key from the OpenAB process env if not already set. The child is spawned after env_clear() (line 395). So [agent].env and inherit_env are the only two paths, and the corrected sentence names both. Container-level sources (secretEnv, envFrom) only reach Kiro through inherit_env, which the sentence already covers, and generated or remote configs are covered by "If config.toml is generated, fix the generator too."

🟢 F2: Discord docs match the code

In crates/openab-core/src/discord.rs the owner path sets involved = true but still returns when another bot has posted. The pure decision function and its unit tests encode the same rule, and role mentions count as mentions, so the @Role follow up row is right.

🟢 F3: Well-scoped temporary note

The note links the upstream issue, names the tested CLI version (2.33.1), says to remove it once a fixed version is verified, and warns that kiro-cli whoami or a chat reply does not prove MCP loaded. OAuth state stays on the existing PVC paths, the same exposure as the existing "Alternative: OAuth Device Flow" section.

🟢 F4: Links, anchors, and CI

#1566, #1576, and kirodotdev/Kiro#11777 return HTTP 200. #known-issue-mcp-and-web-tools-disabled-with-kiro_api_key and #persisted-paths-pvc match their headings. git diff --check is clean. check, validate, and the review-loop checks pass; Rust jobs are correctly skipped by path filters.

Round 2 Findings Status

• Round 2 F1 (step 3 said only inherit_env forwards the key): Addressed in b1862a6. The sentence now names [agent].env and inherit_env. The suggested mention of envFrom and configUrl is Accepted as not needed: both only matter through inherit_env or a generated config, which step 3 already covers.
• Round 2 F2-F5 (praise): still hold; see F2-F4.

Follow-ups (outside this diff, non-blocking)

• Correct the stale "auto-added to inherit_env" comments at charts/openab/values.yaml:71-73 and :371 for the main chart (separate PR).
• Add link-only pointers to the Known issue section from channel guides that copy the KIRO_API_KEY setup (docs/feishu.md, docs/google-chat.md, docs/line.md, docs/msteams-*.md, docs/telegram.md, docs/wecom.md, docs/refarch/telegram-cloudflare-tunnel.md).
• Remove the Kiro known-issue section after kiro-cli headless with API key: GetProfile returns "User is not authorized to access this feature", governance fails, MCP and web tools disabled (Pro, Google sign-in) kirodotdev/Kiro#11777 is fixed and verified.

Reviewer Verdicts

Reviewer	Angle	Verdict	Key finding
Reviewer A	Architecture/General	LGTM	F2, F3, F4; no blockers
Coordinator baseline	-	LGTM	Verified F1 against connection.rs; re-checked diff, anchors, and CI

Two reviewers did not report for this round; this aggregate is based on the reviews above.

Inline Comments and External Feedback

No inline review comments, submitted reviews, or comments from other users exist on this PR at the reviewed head, so there are no threads to answer or resolve.

Baseline Check

• PR opened: 2026-10-28
• Head SHA: b1862a6d92da53870de12560773707c8a4efb57e; base main; merge-base 02a8b24378e1e2dc1d5e2861525d21a05693d170
• Diff: docs/discord.md +8/-3, docs/kiro.md +36 (4 commits, docs only)
• Main already has: the API-key setup and the "Alternative: OAuth Device Flow" section in docs/kiro.md, and the multibot-mentions mode table in docs/discord.md
• Net-new value: the Kiro API-key MCP caveat with a tested workaround, and a correction of the wrong thread-owner row in docs/discord.md

5. Three Reasons We Might Not Need This PR

1. The upstream bug may be fixed soon - the Kiro section would then be churn. Counter: it is self-expiring with a stated removal condition, and users hit it now (docs: document Kiro API-key MCP failure and GitHub login workaround (upstream #11777) #1576).
2. The warning lives only in docs/kiro.md - channel guides that copy the KIRO_API_KEY snippet still do not point to it. Counter: keeping one source makes later removal a single edit; link-only pointers are tracked as a follow-up.
3. The workaround trades zero-touch API-key auth for interactive OAuth and long-lived tokens on the PVC - not suitable as a general unattended path. Counter: it is framed as a workaround for a broken path, not a new recommendation.