chat 4.29.0 → 4.31.0

package/docs/slack-primitives.mdx

@@ -0,0 +1,320 @@
+---
+title: Slack Low-Level APIs
+description: Use Slack request verification, formatting, Web API, and Block Kit helpers without the full Chat runtime.
+type: guide
+prerequisites:
+  - /adapters/official/slack
+related:
+  - /docs/handling-events
+  - /docs/cards
+  - /docs/slash-commands
+---
+
+The Slack adapter is the right default for most bots. It verifies requests, resolves tokens, parses Slack payloads, stores thread state, and routes events through `Chat`.
+
+Use the low-level Slack subpaths when your app already owns routing, state, sessions, or workflow execution and only needs the Slack-specific primitives.
+
+| Subpath | Use for |
+|---------|---------|
+| `@chat-adapter/slack/webhook` | Request verification, body parsing, Events API payloads, slash commands, interactions, and continuation data |
+| `@chat-adapter/slack/format` | Slack mrkdwn tokens, text objects, dates, links, mentions, and simple mrkdwn to Markdown conversion |
+| `@chat-adapter/slack/api` | Fetch-based Slack Web API calls, thread replies, views, and files without `@slack/web-api` |
+| `@chat-adapter/slack/blocks` | Runtime-free conversion from simple card objects and input requests to Slack Block Kit |
+
+<Callout type="info">
+  These subpaths are for custom runtimes. If you want Chat SDK to handle webhook routing, state, subscriptions, and platform normalization, use `createSlackAdapter` from `@chat-adapter/slack`.
+</Callout>
+
+## Webhooks
+
+[Slack signs incoming HTTP requests](https://docs.slack.dev/authentication/verifying-requests-from-slack/) with `x-slack-signature` and `x-slack-request-timestamp`. `verifySlackRequest` reads the request body, verifies the signature with your signing secret, and returns the raw body so you can parse it once.
+
+```typescript title="app/api/slack/route.ts" lineNumbers
+import {
+  parseSlackWebhookBody,
+  verifySlackRequest,
+} from "@chat-adapter/slack/webhook";
+import { postSlackMessage } from "@chat-adapter/slack/api";
+
+export async function POST(request: Request) {
+  const body = await verifySlackRequest(request, {
+    signingSecret: process.env.SLACK_SIGNING_SECRET!,
+  });
+
+  const payload = parseSlackWebhookBody(body, {
+    contentType: request.headers.get("content-type"),
+    headers: request.headers,
+  });
+
+  if (payload.kind === "url_verification") {
+    return Response.json({ challenge: payload.challenge });
+  }
+
+  if (payload.kind === "app_mention") {
+    await postSlackMessage({
+      channel: payload.continuation.channelId,
+      markdownText: `received: ${payload.text}`,
+      threadTs: payload.continuation.threadTs,
+      token: process.env.SLACK_BOT_TOKEN!,
+    });
+  }
+
+  return new Response(null, { status: 200 });
+}
+```
+
+[Slack slash commands](https://docs.slack.dev/interactivity/implementing-slash-commands/) and interactions should be acknowledged quickly. Slack documents a 3000 ms acknowledgement window for slash commands, so do slow work in your queue or workflow runtime after returning a 2xx response.
+
+If you do not need direct access to the verified raw body, `readSlackWebhook` combines verification and parsing:
+
+```typescript
+import { readSlackWebhook } from "@chat-adapter/slack/webhook";
+
+const payload = await readSlackWebhook(request, {
+  signingSecret: process.env.SLACK_SIGNING_SECRET!,
+});
+```
+
+If your framework already buffered the request body, use `verifySlackSignature` with the raw body and headers, then pass that same body to `parseSlackWebhookBody`.
+
+### Payloads
+
+`parseSlackWebhookBody` returns typed payloads:
+
+| Kind | Slack surface |
+|------|---------------|
+| `url_verification` | Events API URL verification |
+| `app_mention` | App mention events |
+| `direct_message` | Direct message events |
+| `slash_command` | Slash command form posts |
+| `block_actions` | Button, select, and Block Kit action payloads |
+| `block_suggestion` | External select suggestion payloads |
+| `view_submission` | Modal submissions |
+| `view_closed` | Modal close events |
+| `unsupported` | Valid Slack payloads not normalized by this helper yet |
+
+Message-like payloads include `continuation`, which contains provider-native reply context:
+
+```typescript
+type SlackContinuation = {
+  channelId: string;
+  enterpriseId?: string;
+  teamId?: string;
+  threadTs: string;
+};
+```
+
+This is not a Chat SDK `Thread`. It is the durable Slack data you need to reply later with `@chat-adapter/slack/api`.
+
+App mention and direct message payloads also include typed `files` parsed from Slack file objects. Each file keeps the raw Slack object plus common fields like `id`, `name`, `mimeType`, `size`, `url`, and `downloadUrl`.
+
+Interaction payloads expose convenience fields from Slack's raw payload:
+
+- `block_actions` includes `actions`, `messageBlocks`, `messagePromptBlock`, `messagePromptText`, `messageTs`, `triggerId`, `responseUrl`, `user`, and `continuation`
+- `view_submission` includes `callbackId`, `privateMetadata`, `values`, `responseUrls`, and `user`
+
+## Formatting
+
+Slack uses mrkdwn and special tokens for mentions, channels, dates, and links. The format subpath gives you small helpers for those strings.
+
+The helper surface includes `escapeSlackText`, `unescapeSlackText`, `createSlackPlainText`, `createSlackMrkdwn`, `formatSlackUser`, `formatSlackChannel`, `formatSlackUserGroup`, `formatSlackSpecialMention`, `formatSlackLink`, `formatSlackDate`, and simple mrkdwn to Markdown normalization.
+
+```typescript title="format.ts" lineNumbers
+import {
+  createSlackMrkdwn,
+  formatSlackDate,
+  formatSlackLink,
+  formatSlackUser,
+  slackMrkdwnToMarkdown,
+} from "@chat-adapter/slack/format";
+
+const text = createSlackMrkdwn(
+  `${formatSlackUser("U123")} approved ${formatSlackLink("https://example.com", "the deploy")}`
+);
+
+const when = formatSlackDate(
+  new Date("2026-05-27T12:00:00Z"),
+  "{date_short_pretty} at {time}",
+  "May 27 at 12:00"
+);
+
+const markdown = slackMrkdwnToMarkdown("hello <@U123|jane>, see <https://example.com|this>");
+```
+
+`linkBareSlackMentions` only links Slack user IDs like `@U123`. It does not resolve display names, because Slack mentions are ID-based.
+
+## Web API
+
+The API subpath calls [Slack Web API](https://docs.slack.dev/apis/web-api/) methods with `fetch`. It does not import `@slack/web-api`.
+
+```typescript title="slack.ts" lineNumbers
+import {
+  postSlackMessage,
+  sendSlackResponseUrl,
+  updateSlackMessage,
+} from "@chat-adapter/slack/api";
+
+const posted = await postSlackMessage({
+  channel: "C123",
+  markdownText: "**hello**",
+  token: process.env.SLACK_BOT_TOKEN!,
+});
+
+await updateSlackMessage({
+  channel: "C123",
+  text: "updated",
+  token: process.env.SLACK_BOT_TOKEN!,
+  ts: posted.id,
+});
+
+await sendSlackResponseUrl("https://hooks.slack.com/actions/T/1/abc", {
+  replaceOriginal: true,
+  text: "done",
+});
+```
+
+Use `callSlackApi` when you need a Slack method that does not have a helper yet:
+
+```typescript
+import { callSlackApi } from "@chat-adapter/slack/api";
+
+const result = await callSlackApi(
+  "reactions.add",
+  { channel: "C123", name: "white_check_mark", timestamp: "1710000000.000001" },
+  { token: process.env.SLACK_BOT_TOKEN! }
+);
+```
+
+`markdownText` maps to the `markdown_text` field on [`chat.postMessage`](https://docs.slack.dev/reference/methods/chat.postMessage/) and cannot be combined with `text` or `blocks`. Use `text` with `blocks` when you need fallback text.
+
+The subpath also includes `postSlackEphemeral`, `deleteSlackMessage`, `resolveSlackBotToken`, `encodeSlackApiBody`, and `assertSlackOk`.
+
+Use `fetchSlackThreadReplies` when a custom runtime needs to refresh a thread with [`conversations.replies`](https://docs.slack.dev/reference/methods/conversations.replies/):
+
+```typescript
+import { fetchSlackThreadReplies } from "@chat-adapter/slack/api";
+
+const replies = await fetchSlackThreadReplies({
+  channel: payload.continuation.channelId,
+  limit: 50,
+  token: process.env.SLACK_BOT_TOKEN!,
+  ts: payload.continuation.threadTs,
+});
+```
+
+Use `openSlackView` to open a modal from an interaction `trigger_id`:
+
+```typescript
+import { openSlackView } from "@chat-adapter/slack/api";
+
+await openSlackView({
+  token: process.env.SLACK_BOT_TOKEN!,
+  triggerId: payload.triggerId,
+  view: {
+    type: "modal",
+    title: { type: "plain_text", text: "Answer" },
+    blocks: [],
+  },
+});
+```
+
+### Files
+
+[Slack's current external upload flow](https://docs.slack.dev/changelog/2024-04-a-better-way-to-upload-files-is-here-to-stay) uses `files.getUploadURLExternal`, then uploads bytes to the returned URL, then calls `files.completeUploadExternal`.
+
+```typescript
+import { uploadSlackFiles } from "@chat-adapter/slack/api";
+
+await uploadSlackFiles(
+  [{ data: new Uint8Array([1, 2, 3]), filename: "report.txt" }],
+  {
+    channelId: "C123",
+    initialComment: "report attached",
+    token: process.env.SLACK_BOT_TOKEN!,
+  }
+);
+```
+
+Use `fetchSlackFile` for private Slack file URLs that require bearer token authorization.
+
+## Blocks
+
+The blocks subpath converts simple card objects into Slack Block Kit without importing the full `chat` JSX runtime.
+
+It exports `cardToSlackBlocks`, `cardToBlockKit`, `cardToSlackFallbackText`, `cardToFallbackText`, and `convertSlackEmojiPlaceholders`.
+
+```typescript title="blocks.ts" lineNumbers
+import {
+  cardToSlackBlocks,
+  cardToSlackFallbackText,
+} from "@chat-adapter/slack/blocks";
+import { postSlackMessage } from "@chat-adapter/slack/api";
+
+const card = {
+  children: [
+    { content: "deploy v2.4.1?", type: "text" },
+    {
+      children: [
+        { id: "approve", label: "Approve", style: "primary", type: "button" },
+        { id: "deny", label: "Deny", style: "danger", type: "button" },
+      ],
+      type: "actions",
+    },
+  ],
+  title: "Deployment",
+  type: "card",
+} as const;
+
+await postSlackMessage({
+  blocks: cardToSlackBlocks(card),
+  channel: "C123",
+  text: cardToSlackFallbackText(card),
+  token: process.env.SLACK_BOT_TOKEN!,
+});
+```
+
+Use the full Chat SDK card JSX when you want cross-platform rendering. Use `@chat-adapter/slack/blocks` when you are building a Slack-only runtime and want Block Kit output directly.
+
+The blocks subpath also includes small input request helpers for Slack-only runtimes:
+
+```typescript
+import {
+  inputRequestToSlackBlocks,
+  parseSlackInputResponse,
+} from "@chat-adapter/slack/blocks";
+import { postSlackMessage } from "@chat-adapter/slack/api";
+
+await postSlackMessage({
+  blocks: inputRequestToSlackBlocks({
+    options: [
+      { id: "approve", label: "Approve", style: "primary" },
+      { id: "deny", label: "Deny", style: "danger" },
+    ],
+    prompt: "Approve deploy?",
+    requestId: "deploy-1",
+  }),
+  channel: "C123",
+  text: "Approve deploy?",
+  token: process.env.SLACK_BOT_TOKEN!,
+});
+
+if (payload.kind === "block_actions") {
+  const action = payload.actions[0];
+  const response = action ? parseSlackInputResponse(action) : null;
+}
+```
+
+Set `display: "radio"` for radio buttons, or `display: "select"` for a static select menu. Set `allowFreeform: true` to add a "Type your answer" button next to the provided options.
+
+For freeform answers, use `buildSlackFreeformView` with `openSlackView`, then read the submitted value from `payload.values` with `parseSlackFreeformValue`.
+
+## Import boundaries
+
+The low-level Slack subpaths are designed to avoid the full runtime import graph:
+
+- no `chat` import
+- no `@chat-adapter/shared` import
+- no `@slack/web-api` import
+- no `@slack/socket-mode` import
+
+The package still installs the full Slack adapter dependencies. The subpaths keep your source and bundle imports clean, but they are not a package-size split.

package/docs/slash-commands.mdx

@@ -8,11 +8,12 @@ related:
   - /docs/modals
   - /adapters/official/slack
   - /adapters/official/discord
+  - /adapters/official/telegram
 ---
 
 Slash commands let users invoke your bot with `/command` syntax. Register handlers with `onSlashCommand` to respond.
 
-Slash commands are supported on [Slack](/adapters/official/slack) and [Discord](/adapters/official/discord).
+Slash commands are supported on [Slack](/adapters/official/slack), [Discord](/adapters/official/discord), and [Telegram](/adapters/official/telegram).
 
 ## Handle a specific command
 
@@ -112,6 +113,10 @@ bot.onModalSubmit("feedback_form", async (event) => {
 });
 ```
 
+## Telegram
+
+Telegram supports bot commands such as `/status` and `/status@mybot`. Register handlers with `onSlashCommand`; commands addressed to another bot are ignored as slash commands and continue through the normal message path.
+
 ## Discord
 
 Discord slash commands are received via [HTTP Interactions](/adapters/official/discord#http-interactions-vs-gateway) — no Gateway connection is needed. The adapter automatically sends a deferred response to Discord, then resolves it when your handler calls `event.channel.post()`.

package/docs/streaming.mdx

@@ -59,10 +59,10 @@ await thread.post(stream);
 | Platform | Method | Description |
 |----------|--------|-------------|
 | Slack | Native streaming API | Uses Slack's `chatStream` for smooth, real-time updates |
+| Telegram | Private chat rich draft previews | Uses Telegram's `sendRichMessageDraft` in private chats, persists the final response with `sendRichMessage`, and falls back to post + edit elsewhere |
 | Teams | Native (DMs) / Buffered (group chats) | Uses the Teams SDK's native `stream.emit()` for direct messages; accumulates chunks and posts one final message when no native streamer is active |
 | Google Chat | Post + Edit | Posts a message then edits it as chunks arrive |
 | Discord | Post + Edit | Posts a message then edits it as chunks arrive |
-| Telegram | Post + Edit | Posts a message then edits it as chunks arrive |
 | GitHub | Buffered | Accumulates chunks and posts one final comment |
 | Linear | Agent sessions / Post + Edit | Uses agent session activities in agent-session threads; falls back to post+edit comments in issue threads |
 | WhatsApp | Buffered | Accumulates chunks and sends one final message |

package/docs/teams-primitives.mdx

@@ -0,0 +1,255 @@
+---
+title: Teams Low-Level APIs
+description: Use Teams Activity parsing, Bot Connector calls, Graph reads, formatting, Adaptive Cards, and Task Module helpers without the full Chat runtime.
+type: guide
+prerequisites:
+  - /adapters/official/teams
+related:
+  - /docs/handling-events
+  - /docs/cards
+  - /docs/modals
+---
+
+The Teams adapter is the right default for most bots. It validates Bot Framework requests through the Microsoft Teams SDK, parses Activities, stores conversation context, renders Adaptive Cards, reads Graph history, and routes events through `Chat`.
+
+Use the low-level Teams subpaths when your app already owns routing, state, sessions, or workflow execution and only needs Teams-specific primitives.
+
+| Subpath | Use for |
+|---------|---------|
+| `@chat-adapter/teams/webhook` | Parse Bot Framework Activity JSON, classify common payloads, and extract continuation data |
+| `@chat-adapter/teams/api` | Fetch-based Bot Connector calls for messages, updates, deletes, typing, and conversations |
+| `@chat-adapter/teams/graph` | Fetch-based Microsoft Graph reads for chats, channels, channel messages, and replies |
+| `@chat-adapter/teams/format` | Teams HTML, mention, Markdown-ish, and emoji string helpers |
+| `@chat-adapter/teams/cards` | Runtime-free conversion from simple card objects and input requests to Adaptive Cards |
+| `@chat-adapter/teams/modals` | Runtime-free Task Module Adaptive Card helpers and submit parsing |
+
+<Callout type="warning">
+  The webhook subpath parses Activities only. It does not verify Microsoft Bot Framework JWTs. For production request validation, use `createTeamsAdapter` or the Microsoft Teams SDK request pipeline before handing the Activity to these helpers.
+</Callout>
+
+## Webhooks
+
+Teams sends Bot Framework Activity JSON. `readTeamsWebhook` reads the request body and classifies the Activity, but it intentionally does not perform JWT validation.
+
+```typescript title="app/api/teams/route.ts" lineNumbers
+import { postTeamsMessage } from "@chat-adapter/teams/api";
+import { readTeamsWebhook } from "@chat-adapter/teams/webhook";
+
+export async function POST(request: Request) {
+  const payload = await readTeamsWebhook(request, {
+    botAppId: process.env.TEAMS_APP_ID,
+  });
+
+  if (payload.kind === "message") {
+    await postTeamsMessage({
+      conversationId: payload.continuation.conversationId,
+      credentials: {
+        appId: process.env.TEAMS_APP_ID!,
+        appPassword: process.env.TEAMS_APP_PASSWORD!,
+        tenantId: payload.continuation.tenantId,
+      },
+      markdownText: `received: ${payload.text}`,
+      serviceUrl: payload.continuation.serviceUrl,
+    });
+  }
+
+  return new Response(null, { status: 200 });
+}
+```
+
+`parseTeamsWebhookBody` returns typed payloads:
+
+| Kind | Teams surface |
+|------|---------------|
+| `message` | Message activities |
+| `message_reaction` | Reaction activities |
+| `card_action` | Adaptive Card actions and `Action.Submit` message activities |
+| `dialog_open` | Task Module `task/fetch` invokes |
+| `dialog_submit` | Task Module `task/submit` invokes |
+| `conversation_update` | Conversation membership and install context updates |
+| `installation_update` | App installation updates |
+| `unsupported` | Valid Activities not normalized by this helper yet |
+
+Message-like payloads include `continuation`, which contains provider-native reply context:
+
+```typescript
+type TeamsContinuation = {
+  activityId?: string;
+  channelId?: string;
+  conversationId: string;
+  replyToId?: string;
+  serviceUrl: string;
+  teamId?: string;
+  tenantId?: string;
+};
+```
+
+This is not a Chat SDK `Thread`. It is the durable Teams data you need to reply later with `@chat-adapter/teams/api`.
+
+## Bot Connector API
+
+The API subpath calls the Bot Framework Connector REST API with `fetch`. It does not import `@microsoft/teams.apps`.
+
+```typescript title="teams.ts" lineNumbers
+import {
+  deleteTeamsMessage,
+  postTeamsMessage,
+  sendTeamsTyping,
+  updateTeamsMessage,
+} from "@chat-adapter/teams/api";
+
+const credentials = {
+  appId: process.env.TEAMS_APP_ID!,
+  appPassword: process.env.TEAMS_APP_PASSWORD!,
+  tenantId: process.env.TEAMS_APP_TENANT_ID!,
+};
+
+const posted = await postTeamsMessage({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  markdownText: "**hello**",
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+});
+
+await updateTeamsMessage({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  messageId: posted.id,
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+  text: "updated",
+});
+
+await sendTeamsTyping({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+});
+
+await deleteTeamsMessage({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  messageId: posted.id,
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+});
+```
+
+Use `accessToken` in `credentials` when your runtime already owns Microsoft token acquisition. A direct `accessToken` must be scoped for the API you call it against — the Bot Connector subpath (`/api`) needs a `https://api.botframework.com/.default` token, while the Graph subpath (`/graph`) needs a `https://graph.microsoft.com/.default` token. Passing the same token to both will fail against one of them. When you supply `appId`/`appPassword` instead, each subpath requests the correct scope for you.
+
+## Graph
+
+The Graph subpath reads Teams history with explicit Graph IDs. Unlike `TeamsAdapter`, it does not use the adapter state cache to infer `teamId`, `channelId`, or `chatId`.
+
+```typescript
+import { listTeamsChannelMessages } from "@chat-adapter/teams/graph";
+
+const messages = await listTeamsChannelMessages({
+  channelId: "19:channel@thread.tacv2",
+  credentials: {
+    appId: process.env.TEAMS_APP_ID!,
+    appPassword: process.env.TEAMS_APP_PASSWORD!,
+    tenantId: process.env.TEAMS_APP_TENANT_ID!,
+  },
+  limit: 25,
+  teamId: "19:team@thread.tacv2",
+});
+
+const latestText = messages.items[0]?.text;
+```
+
+Graph reads require the same Microsoft Graph permissions as the full adapter. Channel and group-chat reads can use RSC permissions; DM reads require Azure AD application permissions such as `Chat.Read.All`.
+
+## Formatting
+
+Teams renders message text as HTML. The format subpath provides small helpers for custom runtimes:
+
+```typescript
+import {
+  formatTeamsMention,
+  markdownToTeamsHtml,
+  teamsHtmlToMarkdown,
+} from "@chat-adapter/teams/format";
+
+const html = markdownToTeamsHtml(
+  `${formatTeamsMention("Ada")} approved **deploy v2.4.1**`
+);
+const markdown = teamsHtmlToMarkdown("<p>Hello <strong>world</strong></p>");
+```
+
+Use the full `TeamsFormatConverter` from `@chat-adapter/teams` when you need mdast conversion inside Chat SDK.
+
+## Cards
+
+The cards subpath converts simple card objects into Adaptive Card JSON without importing the full `chat` JSX runtime.
+
+```typescript title="cards.ts" lineNumbers
+import {
+  cardToAdaptiveCard,
+  cardToTeamsFallbackText,
+} from "@chat-adapter/teams/cards";
+import { postTeamsMessage } from "@chat-adapter/teams/api";
+
+const card = {
+  children: [
+    { content: "deploy v2.4.1?", type: "text" },
+    {
+      children: [
+        { id: "approve", label: "Approve", style: "primary", type: "button" },
+        { id: "deny", label: "Deny", style: "danger", type: "button" },
+      ],
+      type: "actions",
+    },
+  ],
+  title: "Deployment",
+  type: "card",
+} as const;
+
+await postTeamsMessage({
+  adaptiveCard: cardToAdaptiveCard(card),
+  conversationId: payload.continuation.conversationId,
+  credentials,
+  serviceUrl: payload.continuation.serviceUrl,
+  text: cardToTeamsFallbackText(card),
+});
+```
+
+Use the full Chat SDK card JSX when you want cross-platform rendering. Use `@chat-adapter/teams/cards` when you are building a Teams-only runtime and want Adaptive Card output directly.
+
+## Modals
+
+Teams Task Modules are invoke-based dialogs backed by Adaptive Cards. The modals subpath builds those cards and parses submit data.
+
+```typescript
+import {
+  modalToAdaptiveCard,
+  parseTeamsDialogSubmitValues,
+  toTeamsTaskModuleResponse,
+} from "@chat-adapter/teams/modals";
+
+const modal = {
+  callbackId: "deploy",
+  children: [
+    { content: "Why deploy now?", type: "text" },
+    { id: "reason", label: "Reason", type: "text_input" },
+  ],
+  title: "Deploy",
+  type: "modal",
+} as const;
+
+const card = modalToAdaptiveCard(modal, { contextId: "deploy-1" });
+const values = parseTeamsDialogSubmitValues(payload.value);
+
+return Response.json(
+  toTeamsTaskModuleResponse({ action: "update", modal }, { contextId: "deploy-1" })
+);
+```
+
+## Import Boundaries
+
+The low-level Teams subpaths are designed to avoid the full runtime import graph:
+
+- no `chat` import
+- no `@chat-adapter/shared` import
+- no `@microsoft/teams.apps` import
+- no full adapter import
+
+The package still installs the full Teams adapter dependencies. The subpaths keep your source and bundle imports clean, but they are not a package-size split.

package/docs/testing.mdx

@@ -5,7 +5,7 @@ type: guide
 prerequisites:
   - /docs/getting-started
 related:
-  - /docs/state
+  - /docs/state-adapters
   - /docs/handling-events
   - /docs/contributing/testing
 ---

package/docs/threads-messages-channels.mdx

@@ -83,7 +83,7 @@ await thread.startTyping();
 ```
 
 <Callout type="info">
-Not all platforms support typing indicators. The call is a no-op on unsupported platforms. See the [adapter feature matrix](/docs/adapters) for details.
+Not all platforms support typing indicators. The call is a no-op on unsupported platforms. See the [adapter feature matrix](/docs/platform-adapters) for details.
 </Callout>
 
 ### Message history
@@ -149,7 +149,7 @@ await scheduled.cancel();
 ```
 
 <Callout type="info">
-Scheduled messages are currently only supported by the Slack adapter. Other adapters throw `NotImplementedError`. See the [feature matrix](/docs/adapters) for details.
+Scheduled messages are currently only supported by the Slack adapter. Other adapters throw `NotImplementedError`. See the [feature matrix](/docs/platform-adapters) for details.
 </Callout>
 
 ## Messages

package/docs/usage.mdx

@@ -7,7 +7,7 @@ prerequisites:
 related:
   - /docs/handling-events
   - /docs/adapters
-  - /docs/state
+  - /docs/state-adapters
 ---
 
 The `Chat` class is the main entry point for your bot. It coordinates adapters, routes events to your handlers, and manages thread state.
@@ -34,10 +34,10 @@ bot.onNewMention(async (thread) => {
 ```
 
 <Callout type="info">
-  This example uses Redis. Chat SDK also supports [PostgreSQL](/adapters/official/postgres) and [ioredis](/adapters/official/ioredis) as production state adapters. See [State Adapters](/docs/state) for all options.
+  This example uses Redis. Chat SDK also supports [PostgreSQL](/adapters/official/postgres) and [ioredis](/adapters/official/ioredis) as production state adapters. See [State Adapters](/docs/state-adapters) for all options.
 </Callout>
 
-Each adapter factory auto-detects credentials from environment variables (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `REDIS_URL`, etc.), so you can get started with zero config. Pass explicit values to override.
+Each adapter factory auto-detects credentials from environment variables (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `REDIS_URL`, etc.), so you can get started with zero config. Pass explicit values to override. For setup UIs and build scripts, the [`chat/adapters` catalog](/docs/adapters#adapter-catalog-chatadapters) lists official and vendor-official adapter env specs without importing adapter packages.
 
 ## Multiple adapters