docs: update documentation for 4.27.0 release (#439)

* docs: update documentation for 4.27.0 release

* docs: fix broken apiUrl link in adapters feature matrix

* docs: fix error code thrown-by columns and add missing UNKNOWN_USER_ID_FORMAT

Author: dancer

apps/docs/content/docs/adapters.mdx

@@ -20,7 +20,7 @@ Ready to build your own? Follow the [building](/docs/contributing/building) guid
 | Edit message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
 | Delete message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
 | File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file | <Cross /> | <Cross /> | <Check /> Images, audio, docs |
-| Streaming | <Check /> Native | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Cross /> | <Cross /> | <Cross /> |
+| Streaming | <Check /> Native | <Warn /> Native (DMs) / Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Cross /> | <Cross /> | <Cross /> |
 | Scheduled messages | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 
 ### Rich content
@@ -47,6 +47,8 @@ Ready to build your own? Follow the [building](/docs/contributing/building) guid
 | Typing indicator | <Cross /> | <Check /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> |
 | DMs | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
 | Ephemeral messages | <Check /> Native | <Cross /> | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| User lookup ([`getUser`](/docs/api/chat#getuser)) | <Check /> | <Warn /> Cached | <Warn /> Cached | <Check /> | <Warn /> Seen users | <Check /> | <Check /> | <Cross /> |
+| Custom API endpoint (`apiUrl`) | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
 
 ### Message history
 

apps/docs/content/docs/api/chat.mdx

@@ -261,6 +261,44 @@ Returns `ModalResponse | undefined` to control the modal after submission:
 - `{ action: "update", modal: ModalElement }` — replace the modal content
 - `{ action: "push", modal: ModalElement }` — push a new modal view onto the stack
 
+### onOptionsLoad
+
+Fires when an `ExternalSelect` requests options dynamically. The handler is keyed on the select's `id` and must return options synchronously enough for Slack's 3-second budget (the adapter caps the loader at ~2.5s and substitutes an empty result on timeout). Slack-only.
+
+```typescript
+bot.onOptionsLoad("assignee", async (event) => {
+  const people = await peopleService.search(event.query);
+  return people.map((p) => ({ label: p.fullName, value: p.id }));
+});
+```
+
+Return an array of `OptionsLoadGroup` (`{ label, options }[]`) instead of a flat array to render grouped headers (e.g. "Recent" / "All"). Slack limits: max 100 groups, max 100 options per group.
+
+<TypeTable
+  type={{
+    'event.actionId': {
+      description: 'The id of the select requesting options (matches the id passed to bot.onOptionsLoad).',
+      type: 'string',
+    },
+    'event.query': {
+      description: 'The text the user has typed so far.',
+      type: 'string',
+    },
+    'event.user': {
+      description: 'The user requesting options.',
+      type: 'Author',
+    },
+    'event.adapter': {
+      description: 'The adapter that received this event.',
+      type: 'Adapter',
+    },
+    'event.raw': {
+      description: 'Raw platform-specific payload.',
+      type: 'unknown',
+    },
+  }}
+/>
+
 ### onSlashCommand
 
 Fires when a user invokes a `/command` in the message composer. Currently supported on Slack.
@@ -498,10 +536,16 @@ const user = await bot.getUser(message.author);
   - **GitHub** — `email` is `null` unless the user made it public, or you authenticated with the `user:email` scope.
   - **Linear** — full profile (incl. email + avatar) for any active workspace member.
 
-  Fields that aren't available return `undefined`. Numeric user IDs (Discord/Telegram/GitHub) can be ambiguous when multiple of those adapters are registered — call the platform's adapter directly (`adapter.getUser(userId)`) in that case.
+  Fields that aren't available return `undefined`. Numeric user IDs (Discord/Telegram/GitHub) can be ambiguous when multiple of those adapters are registered — `bot.getUser` throws a `ChatError` with code `AMBIGUOUS_USER_ID` in that case. Pass an `Author` from a message handler (which already carries the adapter), or call the adapter directly (`adapter.getUser(userId)`).
 </Callout>
 
-Adapters that don't support user lookups will throw a `ChatError` with code `NOT_SUPPORTED`. Handle both cases if your bot runs on multiple platforms:
+`bot.getUser` throws a `ChatError` in three cases. Handle them if your bot runs on multiple platforms:
+
+| Code | When |
+|------|------|
+| `NOT_SUPPORTED` | The resolved adapter doesn't implement `getUser` (e.g. WhatsApp) |
+| `AMBIGUOUS_USER_ID` | A numeric user ID could belong to more than one registered adapter (Discord/Telegram/GitHub) |
+| `UNKNOWN_USER_ID_FORMAT` | The `userId` string doesn't match any registered platform's ID format |
 
 ```typescript
 import { ChatError } from "chat";
@@ -512,8 +556,14 @@ try {
     // User not found on this platform
   }
 } catch (error) {
-  if (error instanceof ChatError && error.code === "NOT_SUPPORTED") {
-    // This adapter doesn't support user lookups
+  if (error instanceof ChatError) {
+    if (error.code === "NOT_SUPPORTED") {
+      // This adapter doesn't support user lookups
+    } else if (error.code === "AMBIGUOUS_USER_ID") {
+      // Pass message.author or call adapter.getUser(userId) directly
+    } else if (error.code === "UNKNOWN_USER_ID_FORMAT") {
+      // userId doesn't match any known platform format
+    }
   }
 }
 ```

apps/docs/content/docs/api/index.mdx

@@ -31,6 +31,8 @@ import { Chat, root, paragraph, text, Card, Button, emoji } from "chat";
 | Export | Description |
 |--------|-------------|
 | [`PostableMessage`](/docs/api/postable-message) | Union type accepted by `thread.post()` |
+| [`Plan`](/docs/api/postable-message#plan) | Step-by-step task list that mutates after posting |
+| [`StreamingPlan`](/docs/api/postable-message#streamingplan) | Wraps an async iterable with platform-specific streaming options |
 | [`Cards`](/docs/api/cards) | Rich card components — `Card`, `Text`, `Button`, `Actions`, etc. |
 | [`Markdown`](/docs/api/markdown) | AST builder functions — `root`, `paragraph`, `text`, `strong`, etc. |
 | [`Modals`](/docs/api/modals) | Modal form components — `Modal`, `TextInput`, `Select`, etc. |

apps/docs/content/docs/api/markdown.mdx

@@ -15,6 +15,25 @@ import {
 } from "chat";
 ```
 
+## Type re-exports
+
+The chat package re-exports mdast's union and content types so adapters and downstream code can build exhaustively-typed AST walkers without depending on `mdast` directly:
+
+```typescript
+import type { Nodes, Root, Content } from "chat";
+
+function render(node: Nodes): string {
+  switch (node.type) {
+    case "text": return node.value;
+    case "strong": return node.children.map(render).join("");
+    // ...
+    default: throw new Error(`Unhandled: ${node satisfies never}`);
+  }
+}
+```
+
+Adapters use this pattern to make the type checker reject the build when a new mdast node type is introduced upstream.
+
 ## Node builders
 
 ### root

apps/docs/content/docs/api/modals.mdx

@@ -167,6 +167,52 @@ Select({
   }}
 />
 
+## ExternalSelect
+
+Dropdown that loads options dynamically from a handler as the user types. Slack-only. Pair with [`bot.onOptionsLoad`](/docs/api/chat#onoptionsload) to supply options. See [Modals → ExternalSelect](/docs/modals#externalselect) for a full example, grouped-options support, and Slack setup notes.
+
+```typescript
+ExternalSelect({
+  id: "assignee",
+  label: "Assignee",
+  placeholder: "Search people",
+  minQueryLength: 1,
+  initialOption: { label: "Alice", value: "U123" },
+})
+```
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Input ID — used as the key in event.values.',
+      type: 'string',
+    },
+    label: {
+      description: 'Label displayed above the select.',
+      type: 'string',
+    },
+    placeholder: {
+      description: 'Placeholder text.',
+      type: 'string',
+    },
+    minQueryLength: {
+      description: 'Minimum characters before the loader fires (Slack default: 3).',
+      type: 'number',
+    },
+    initialOption: {
+      description: 'Pre-selected option when the modal opens. Unlike static Select where initialOption is a value string, ExternalSelect needs the full label/value object since the loader has not run yet.',
+      type: '{ label: string, value: string }',
+    },
+    optional: {
+      description: 'Whether the field can be left empty.',
+      type: 'boolean',
+      default: 'false',
+    },
+  }}
+/>
+
+The loader registered via `bot.onOptionsLoad("assignee", handler)` returns either a flat `SelectOptionElement[]` or `OptionsLoadGroup[]` (`{ label, options }[]`) for grouped options.
+
 ## RadioSelect
 
 Radio button group for mutually exclusive choices.

apps/docs/content/docs/api/postable-message.mdx

@@ -7,9 +7,14 @@ type: reference
 `PostableMessage` is the union of all message formats accepted by `thread.post()` and `sent.edit()`.
 
 ```typescript
-type PostableMessage = AdapterPostableMessage | AsyncIterable<string | StreamChunk | StreamEvent>;
+type PostableMessage =
+  | AdapterPostableMessage
+  | AsyncIterable<string | StreamChunk | StreamEvent>
+  | PostableObject;
 ```
 
+`PostableObject` covers `Plan` (mutable task lists) and `StreamingPlan` (streams with platform-specific options) — both documented below.
+
 ## String
 
 Raw text passed through as-is to the platform.
@@ -133,6 +138,55 @@ await thread.post({
   }}
 />
 
+## Plan
+
+A `Plan` is a step-by-step task list that mutates after posting. Each `addTask` / `updateTask` / `complete` call re-renders the same message in place. See [Plan API](/docs/streaming#plan-api) for full usage.
+
+```typescript
+import { Plan } from "chat";
+
+const plan = new Plan({ initialMessage: "Researching options..." });
+await thread.post(plan);
+await plan.addTask({ title: "Look up records" });
+await plan.complete({ completeMessage: "Done!" });
+```
+
+Adapters that don't support `PostableObject` editing render the plan as fallback text and ignore subsequent mutations.
+
+## StreamingPlan
+
+Wraps an async iterable with platform-specific streaming options. Use this when you need to pass options like task grouping or stop blocks through `thread.post()`. See [Streaming with options](/docs/streaming#streaming-with-options).
+
+```typescript
+import { StreamingPlan } from "chat";
+
+const planned = new StreamingPlan(stream, {
+  groupTasks: "plan",
+  endWith: [feedbackBlock],
+  updateIntervalMs: 750,
+});
+
+await thread.post(planned);
+```
+
+<TypeTable
+  type={{
+    groupTasks: {
+      description: 'Slack: render task_update chunks as `"plan"` (single grouped block) or `"timeline"` (inline cards, default).',
+      type: '"plan" | "timeline" | undefined',
+    },
+    endWith: {
+      description: 'Slack: Block Kit elements appended when the stream stops (e.g. retry / feedback buttons).',
+      type: 'unknown[] | undefined',
+    },
+    updateIntervalMs: {
+      description: 'Fallback adapters: minimum interval between post+edit cycles in ms.',
+      type: 'number | undefined',
+      default: '500',
+    },
+  }}
+/>
+
 ## AsyncIterable (streaming)
 
 An async iterable of strings, `StreamChunk` objects, or stream events. The SDK streams the message in real time using platform-native APIs where available.

apps/docs/content/docs/api/thread.mdx

@@ -39,7 +39,7 @@ A `Thread` is provided to your event handlers and represents a conversation thre
 
 ## post
 
-Post a message to the thread. Accepts strings, structured messages, cards, and streams.
+Post a message to the thread. Accepts strings, structured messages, cards, streams, and `PostableObject` instances (`Plan`, `StreamingPlan`).
 
 ```typescript
 // Plain text
@@ -56,11 +56,19 @@ await thread.post(Card({ title: "Hi", children: [Text("Hello")] }));
 
 // Stream (fullStream recommended for multi-step agents)
 await thread.post(result.fullStream);
+
+// Plan (mutable task list)
+const plan = new Plan({ initialMessage: "Working..." });
+await thread.post(plan);
+await plan.addTask({ title: "Step 1" });
+
+// Streaming with platform options
+await thread.post(new StreamingPlan(stream, { groupTasks: "plan" }));
 ```
 
 **Parameters:** `message: string | PostableMessage | CardJSXElement`
 
-**Returns:** `Promise<SentMessage>` — the sent message with `edit()`, `delete()`, `addReaction()`, and `removeReaction()` methods.
+**Returns:** `Promise<SentMessage | PostableObject>` — for plain messages and streams, a `SentMessage` with `edit()`, `delete()`, `addReaction()`, and `removeReaction()` methods; for `Plan` / `StreamingPlan` inputs, the same object is returned so you can keep mutating it.
 
 See [Posting Messages](/docs/posting-messages) for details on each format.
 

apps/docs/content/docs/concurrency.mdx

@@ -124,6 +124,10 @@ const bot = new Chat({
 | `debounceMs` | debounce | `1500` | Debounce window in milliseconds |
 | `maxConcurrent` | concurrent | `Infinity` | Max concurrent handlers per thread |
 
+<Callout type="warn">
+`maxConcurrent` only applies to the `concurrent` strategy. Pairing it with any other strategy logs a warning and the value is ignored. Setting `maxConcurrent` to a value less than `1` throws at construction time — `0` would deadlock the strategy and is rejected up front.
+</Callout>
+
 ## MessageContext
 
 All handler types (`onNewMention`, `onSubscribedMessage`, `onNewMessage`) accept an optional `MessageContext` as their last parameter. It is only populated when using the `queue` strategy and messages were skipped.

apps/docs/content/docs/error-handling.mdx

@@ -16,7 +16,19 @@ import { ChatError, RateLimitError, NotImplementedError, LockError } from "chat"
 
 ### ChatError
 
-Base error class for all SDK errors. Every error below extends `ChatError`.
+Base error class for all SDK errors. Every error below extends `ChatError`. The `code` property carries a machine-readable identifier you can branch on:
+
+| Code | Thrown by | Meaning |
+|------|-----------|---------|
+| `NOT_SUPPORTED` | `bot.openDM`, `bot.getUser` | The resolved adapter doesn't implement this method |
+| `INVALID_THREAD_ID` | `bot.thread`, internal routing | Thread ID does not match the `adapter:channel:thread` shape |
+| `INVALID_CHANNEL_ID` | `bot.channel` | Channel ID does not match the `adapter:channel` shape |
+| `ADAPTER_NOT_FOUND` | `bot.thread`, `bot.channel` | Thread/channel ID references an adapter that wasn't registered on this `Chat` instance |
+| `AMBIGUOUS_USER_ID` | `bot.getUser`, `bot.openDM` | Numeric user ID could match more than one registered adapter (Discord/Telegram/GitHub) |
+| `UNKNOWN_USER_ID_FORMAT` | `bot.getUser`, `bot.openDM` | The `userId` doesn't match any platform's known ID format |
+| `RATE_LIMITED` | Any platform call | Platform returned 429; see `RateLimitError` below |
+| `NOT_IMPLEMENTED` | Any platform call | The adapter doesn't implement this feature; see `NotImplementedError` below |
+| `LOCK_FAILED` | Inbound message routing | Distributed lock was busy; see `LockError` below |
 
 <TypeTable
   type={{
@@ -25,7 +37,7 @@ Base error class for all SDK errors. Every error below extends `ChatError`.
       type: 'string',
     },
     code: {
-      description: 'Machine-readable error code.',
+      description: 'Machine-readable error code (see table above).',
       type: 'string',
     },
     cause: {

apps/docs/content/docs/index.mdx

@@ -52,7 +52,7 @@ Each adapter factory auto-detects credentials from environment variables (`SLACK
 | Platform | Package | Mentions | Reactions | Cards | Modals | Streaming | DMs |
 |----------|---------|----------|-----------|-------|--------|-----------|-----|
 | Slack | `@chat-adapter/slack` | Yes | Yes | Yes | Yes | Native | Yes |
-| Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | No | Post+Edit | Yes |
+| Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | No | Native (DMs) / Post+Edit | Yes |
 | Google Chat | `@chat-adapter/gchat` | Yes | Yes | Yes | No | Post+Edit | Yes |
 | Discord | `@chat-adapter/discord` | Yes | Yes | Yes | No | Post+Edit | Yes |
 | Telegram | `@chat-adapter/telegram` | Yes | Yes | Partial | No | Post+Edit | Yes |