docs: make the README's channel list and capability claims match the code

[JiaDe-Wu]

Problem / Motivation

Two related drifts in the README's channel tables, both found by checking the transports rather than another prose list.

Channels that ship but are not listed. src/kiro_crew/docs/index.md — the packaged, user-facing feature index — lists ten chat channels. The README and CONTRIBUTING.md listed seven or eight, and the two absent from every one of those lists were Feishu (Lark) and iMessage. Both are fully shipped: a config section in config/loader.py, a TransportCapabilities declaration, a MessagingTransport, tests, and a packaged setup guide. README.md did not contain either string once.

Two rows claimed a capability their transport does not have. The Webex and WeChat rows both said "streaming replies", while webex/transport.py:71 and weixin/transport.py:67 declare streaming=False.

Why it matters

The README is the front door. A reader deciding whether Kiro Crew fits their setup cannot discover a channel that already exists and needs no work — they conclude it is unsupported and stop. That is the expensive kind of doc gap: it costs a user who would have succeeded.

A wrong capability claim costs differently. Someone picks Webex or WeChat because the table promised streaming, and finds out after setup that the answer arrives in one bubble. AGENTS.md names the general case: "a doc nobody updated is worse than no doc, because readers still trust it."

What changed (motivation → approach → change)

Four lists were behind, by different amounts:

List	Had	Missing
README "Add a messaging channel" paragraph	8	Feishu, iMessage
README architecture diagram, surfaces node	7	WhatsApp, Feishu, iMessage
README Surfaces table	7 rows	WhatsApp, Feishu, iMessage
CONTRIBUTING.md "Connect … later"	7	WhatsApp, Feishu, iMessage

Three details are deliberate rather than mechanical.

The two corrected rows are corrected differently, because the two cases are not the same failure. A find-and-replace of "streaming replies" would have been wrong for one of them:

• WeChat has no streaming at all. weixin/turn_renderer.py: "iLink has no message-edit / streaming primitive: every sendmessage creates a NEW chat bubble … this renderer BUFFERS the whole turn and emits it once on on_done", with the native typing indicator "the only progress affordance iLink offers". So its row now names the typing indicator and says the reply arrives as complete messages.
• Webex does show progress, just not a token stream. webex/renderer.py posts a placeholder and edits it into the answer, bounded by a 10-edit budget its docstring calls "the whole design" ("a typewriter edit-stream is structurally impossible"). So its row says progress shows as edits to one message, which the finished answer replaces.

WeCom keeps its "streaming replies" wording, because it earns it: streaming=True, and its renderer emits throttled replace-in-place stream frames over WS.

The three new Surfaces rows describe each channel rather than copying a neighbour. Feishu and iMessage both declare streaming=False, so they say replies arrive as complete messages — the phrasing the Teams row already uses — instead of inheriting the "streaming replies" every DM row around them carries.

The outbound-connection sentence gained a second exception. It read "Apart from Teams (which needs a public HTTPS webhook), these channels connect outbound, so you do not need to expose the dashboard port publicly." iMessage talks to Messages.app on the same Mac; adding it to the list above that sentence without amending the clause would have made the sentence false for one of its own members.

Tests

N/A — documentation only, no code path changes. The two gates that own this content pass:

./scripts/docs-lint.sh
  docs-lint: scanned 259 markdown files under docs, src/kiro_crew/docs, website/docs
  All documentation checks passed

BRAND_BASE_REF=upstream/main python3 scripts/check_brand_name.py
  brand gate: no misspellings of 'Kiro Crew' in the lines added since upstream/main ✓

Manual verification

Every claim was checked against code, not inferred:

• the ten channels come from the *Config fields in src/kiro_crew/config/loader.py — slack, wecom, telegram, weixin, whatsapp, feishu, discord, webex, teams, imessage
• each added link target exists in src/kiro_crew/docs/ and is reachable from that directory's index (docs-lint enforces the second half)
• streaming was read off all ten *_CAPABILITIES declarations: True for slack, wecom, telegram, discord, whatsapp; False for feishu, weixin, teams, webex, imessage. The table's claims now match that split
• the WeChat and Webex behaviour statements come from weixin/turn_renderer.py and webex/renderer.py's own docstrings, quoted above
• the iMessage locality claim comes from imessage-integration.md; the Feishu long-connection claim from feishu-integration.md

No new markdown file, no second doc on the subject, no index changes needed — every target was already indexed.

Related Issues

None open for this.

The capability half of the change is a follow-up to the Design Review bot's side-observation on the first revision of this PR, which applied the change's own accuracy standard to the rows it had not touched and found Webex and WeChat. I verified both independently before acting on it, and the verification is what produced the two different corrections above — the bot's finding was directionally right but treating them alike would have understated Webex.

[github-actions]

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 4eb1262ad6635ca38f9369fcbadc99f6c0addd7e via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4eb1262

[github-actions]

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 4eb1262ad6635ca38f9369fcbadc99f6c0addd7e via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Every factual claim in the diff checks out against the base tree: the ten channels match the *Config fields and streaming flags (webex/transport.py:71 and weixin/transport.py:67 are False; whatsapp/slack/wecom/telegram/discord True), the WhatsApp row's reactions/file claims match WHATSAPP_CAPABILITIES, the Webex 10-edit and WeChat typing-indicator wording quote the renderers' own docstrings, the iMessage same-Mac clause matches its packaged guide, and every new link target exists in src/kiro_crew/docs/. Scope is exactly what the description states — no phantom claims, no smuggled hunks.

Design-Verdict: PASS

Docs-only accuracy fix, every claim verified against the transports' declared capabilities; per-channel wording is grounded rather than copied, and scope matches the description exactly.

[DESIGN-REVIEWED] 4eb1262

[github-actions]

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed 4eb1262ad6635ca38f9369fcbadc99f6c0addd7e via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 4eb1262

[JiaDe-Wu]

Thanks — the Design Review side-observation was a real find, and it is now fixed in the same change (force-pushed as 51298de, one commit, title and body updated to cover both halves).

I verified it independently before acting on it, and the verification is why the two rows are corrected differently rather than by replacing the phrase in both:

WeChat has no streaming at all. weixin/turn_renderer.py, its own docstring:

iLink has no message-edit / streaming primitive: every sendmessage creates a NEW chat bubble. So unlike the WeCom renderer (which replaces one bubble via WS frames), this renderer BUFFERS the whole turn and emits it once on on_done … While the turn runs it holds the native "typing…" indicator on, which is the only progress affordance iLink offers.

So the row now names the typing indicator and says the reply arrives as complete messages.

Webex does show progress — just not a token stream. webex/renderer.py posts a placeholder and edits it into the answer, bounded by a 10-edit budget the module docstring calls "the whole design" ("a typewriter edit-stream is structurally impossible", and status edits spend from the same budget because Webex has no reactions API). Calling that "not streaming" and stopping there would have understated it, so the row says progress shows as edits to one message, which the finished answer replaces.

I also checked the row the observation did not name: WeCom keeps "streaming replies", because wecom/transport.py declares streaming=True and its renderer really does emit throttled replace-in-place WS stream frames. So the split across all ten declarations now matches the table — True for slack, wecom, telegram, discord, whatsapp; False for feishu, weixin, teams, webex, imessage.

One thing worth recording for whoever maintains this table: streaming is in the ledger's ASPIRATIONAL set in test_capability_ledger.py — "declared honestly, read by nothing yet" — so nothing enforces agreement between a row like this and the declaration beside it. That is exactly why two of them drifted, and why I checked each renderer's behaviour rather than trusting the flag alone. Not proposing a gate here; just noting that the fix is documentation-shaped and will drift again on its own.

[JiaDe-Wu]

Request: a re-run of the fork AI review lane for head 51298de27bb5. The one red on this PR is a pre-fix artifact, not a verdict, and it predates both guard landings.

The red is review incomplete, not a decision

The GPT 5.6 Review check-run's title is GPT 5.6 Review — review incomplete, and the <!-- codex-ai-review --> comment on this PR carries no [GPT-REVIEWED] or [BLOCK-MERGE] marker at all:

GPT 5.6 Review (fork) — ⚠️ review incomplete

No completed GPT verdict for this commit; see the Fork GPT 5.6 Review job logs.

So nothing was decided here. For contrast, the fork PRs that are red on this lane right now are red with a real verdict — #7157's check-run title is GPT 5.6 Review — changes requested (blocking) with a security-class finding. That is the lane working; this PR never got that far.

It predates both fixes

event	when
this PR's GPT 5.6 Review check completed	2026-09-03T18:27:02Z
#8342 — same-repo lane guard	merged 2026-09-04T10:04:46Z
#8450 — fork lane guard, closing #8344	merged 2026-09-06T06:11:21Z

#8344 described exactly this shape for fork-gpt-review.yml ("a fork PR whose later review run fails to produce a completed verdict replaces a posted verdict with a 'review incomplete' body"), and its guard landed about two hours ago.

The lane produces real verdicts now

• Fork GPT 5.6 Review (workflow 325798095) today: 21 success, 0 failure, 75 skipped, 4 still in flight.
• The ten most recently updated merged fork PRs all show GPT 5.6 Review = pass (fix(dashboard): end pointer drags when capture is lost (#8271) #8904, fix(dashboard): name the offender when the slots flush fails to serialize #8888, fix(dashboard): retire stale questions after consumed steers #8820, fix(aws-control): gate drive bootstrap on app-enabled inside the lock #8456, fix(design-tweak): stop the preview HTML scan enumerating a junctioned tree #8767, fix(sandbox): retry a spawn whose launcher interpreter is mid-rebuild #7670, fix(ci): parse indented adjudication verdicts #8408, fix(security): a destructive literal handed to a search verb is not an action #8805, fix(papyrus): refuse a junctioned path in the Compile link scan #8766, fix(sandbox): unmask an app backend's own state leaves for its spawn #8794) — the newest at 2026-09-06T06:17:13Z.

Why I am asking rather than pushing

A new head commit would re-trigger the lane, but it also discards the 57 check-runs that are currently green here and sends a +15/-9 docs diff back through the full backend matrix. That matrix has an open flake class — #4227's crashed-worker path on the POSIX shard, which reddened Coverage Gate on my #8228 with a diff that could not account for it, and which #8691 addresses. Trading a stale non-verdict for a fresh unrelated red seemed like the wrong direction on a docs-only change.

If pushing a rebase is the preferred route here, say so and I will do it — I just did not want to burn the green run on a guess.

[bolichen97]

Rebased onto main 02d7a2d0 by a maintainer as part of the 2026-09-08 open-PR audit. New head: 4eb1262a (was 51298de2).

Clean rebase, no conflicts. The diff is unchanged: 2 files, +15/-9, docs only.

Gates: no Python or frontend files changed, so the lint/test gates do not apply. I did verify the two new doc links resolve on current main (src/kiro_crew/docs/feishu-integration.md, src/kiro_crew/docs/imessage-integration.md) and that webex/transport.py and weixin/transport.py still declare streaming=False, so the corrected Surfaces rows are still accurate.

Please review the rebased branch. A maintainer push makes the maintainer the last pusher, so under this repo's last-push rule a second approver is needed. Reply here if anything looks wrong.