docs: address round-9 codex review findings

- interactive components: scope block_actions support to message-based
  blocks (modal-view containers are rejected before routing); attribution vs
  real-mention distinction
- multi-tenant: thread reconstruction validates only; credential lookup
  happens at post time
- reference: agent activities are thought/response/action/elicitation/error;
  plans/external URLs are session updates
- linear generic comments: subscription precedence over mention routing
- tutorial: qualify follow-up echoes under the default drop strategy

Author: ThomasK33

docs/how-to/interactive-components.md

@@ -3,7 +3,11 @@
 Buttons and menus are Interaction Events: normalized events with their own
 single-slot hook, `OnInteraction`, riding the same dispatch spine as messages
 (see [ADR 0004](../adr/0004-interactive-components.md)). This slice covers
-Slack `block_actions` — button clicks and menu selections.
+Slack `block_actions` on **messages** — button clicks and menu selections on
+Block Kit content posted to a channel, thread, or DM. `block_actions`
+originating inside a modal view carry a view container without a
+channel/message anchor and are not normalized yet; they are rejected before
+routing.
 
 There is deliberately no cross-platform card DSL. Portable posting stays plain
 text and portable Markdown; platform-native rich content (Block Kit) is posted
@@ -88,8 +92,10 @@ distinct `action_id`s where you can until #12 lands.
 The normalized `Actor` carries the Slack user ID, not a display name (the
 interactivity payload does not include one). Note that plain `chat.Text` is
 posted with Slack formatting disabled, so `<@USERID>` mention syntax renders
-literally; to render a real mention, resolve the display name via the Slack
-API or post native Block Kit content instead.
+literally. For plain-text *attribution*, resolve the display name via the
+Slack API and include it as ordinary text; for a real, clickable Slack
+mention, post native Block Kit content with an `mrkdwn` text element
+containing `<@USERID>`.
 
 **Known limitation:** the interaction event identity is currently anchored on
 the message timestamp, not the individual activation — so when the same user

docs/how-to/linear-agent-sessions.md

@@ -149,8 +149,12 @@ the flag must be set by something outside the runtime's serialized dispatch).
 ## Generic Issue Comments
 
 The adapter also participates in plain Linear issue comments (outside agent
-sessions): a comment that @-mentions your app routes to `OnNewMention` on a
-comment-backed thread, and `Thread.Post` replies in that comment thread.
+sessions): a comment that @-mentions your app arrives on a comment-backed
+thread, and `Thread.Post` replies in that comment thread. Normal routing
+precedence applies: the mention routes to `OnNewMention` only while the
+thread is unsubscribed — in a thread you have subscribed, every comment
+(mention or not) routes to `OnSubscribedMessage`, so do not put
+mention-specific handling exclusively in `OnNewMention`.
 Agent-activity methods (`PostThought`, `UpdateSession`, ...) are rejected on
 comment threads — they only make sense inside agent sessions.
 

docs/how-to/multi-tenant-install.md

@@ -120,6 +120,9 @@ Uninstalls: delete the row; subsequent events from that tenant resolve to
 
 Thread IDs, actors, and dedupe keys all carry the platform tenant, so two
 workspaces never collide in runtime state. Thread handle reconstruction
-(`bot.Thread(ctx, threadID)`) resolves credentials for the stored tenant
-through the same install store — proactive posts work across installs without
-extra plumbing.
+(`bot.Thread(ctx, threadID)`) decodes and validates the stored ID without
+touching the install store; the credential lookup for the stored tenant
+happens when the reconstructed handle actually posts. Proactive posts work
+across installs without extra plumbing — but a successful `bot.Thread` call
+is not proof the tenant is still installed; an uninstalled tenant surfaces as
+an error from the post.

docs/reference.md

@@ -61,7 +61,8 @@ platform-specific surfaces differ:
 | Rate-limit retry with typed `RateLimited` error | Yes | Yes |
 | Multi-tenant installs (`InstallStore`) | Yes | Yes |
 | Platform escape hatch | Raw payloads on events | `RawMessage`, `GraphQL` |
-| Agent activities (thought/action/elicitation/error/plan) | n/a | Yes |
+| Agent activities (thought/response/action/elicitation/error) | n/a | Yes |
+| Session updates (plan, external URLs) | n/a | Yes (`UpdateSession`) |
 
 For the tracked list of Linear agent APIs that are not yet wrapped in typed
 helpers, see [linear-agent-capabilities.md](linear-agent-capabilities.md).

docs/tutorials/slack-bot.md

@@ -187,8 +187,11 @@ bot.OnSubscribedMessage(func(ctx context.Context, ev *chat.MessageEvent) error {
 ```
 
 Restart the bot (`Ctrl-C`, then `go run ./examples/slack-hello-world` again)
-and mention it once more. From then on, every follow-up message in that thread
-gets echoed back — no mention required. Two things to notice:
+and mention it once more. From then on, follow-up messages in that thread get
+echoed back — no mention required. (If you type several messages faster than
+the bot replies, some may be skipped: the default concurrency strategy drops
+events that arrive while the thread's previous event is still being handled.)
+Two things to notice:
 
 - Replying never subscribes a thread. `Thread.Subscribe` is always an explicit
   decision, and it lasts until you call `Thread.Unsubscribe`.