chat 4.30.0 → 4.32.0

package/docs/conversation-history.mdx

@@ -3,7 +3,7 @@ title: Conversation History
 description: Persist messages per user across every platform — for LLM context, audit, or compliance.
 type: guide
 prerequisites:
-  - /docs/state
+  - /docs/state-adapters
 related:
   - /docs/handling-events
   - /docs/api/transcripts

package/docs/create-chat-sdk.mdx

@@ -0,0 +1,143 @@
+---
+title: CLI
+description: Scaffold a Chat SDK bot app with a single command.
+---
+
+`create-chat-sdk` creates a minimal Next.js app for Chat SDK bots.
+
+The CLI will generate your `Chat` configuration, webhook route, `.env.example` file, dependencies, and optional Web adapter route from the adapter catalog.
+
+## Quick start
+
+<CodeBlockTabs defaultValue="npm">
+  <CodeBlockTabsList>
+    <CodeBlockTabsTrigger value="npm">npm</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="pnpm">pnpm</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="yarn">yarn</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="bun">bun</CodeBlockTabsTrigger>
+  </CodeBlockTabsList>
+  <CodeBlockTab value="npm">
+```bash
+npm create chat-sdk@latest my-bot
+```
+  </CodeBlockTab>
+  <CodeBlockTab value="pnpm">
+```bash
+pnpm create chat-sdk@latest my-bot
+```
+  </CodeBlockTab>
+  <CodeBlockTab value="yarn">
+```bash
+yarn create chat-sdk my-bot
+```
+  </CodeBlockTab>
+  <CodeBlockTab value="bun">
+```bash
+bunx create-chat-sdk@latest my-bot
+```
+  </CodeBlockTab>
+</CodeBlockTabs>
+
+<Callout type="info">
+  `create-chat-sdk` automatically detects when it is being run by Cursor, Claude Code, or another coding agent. In agent environments, pass at least one platform adapter with `--adapter`; the state adapter defaults to `memory`. The CLI runs non-interactively and uses `my-bot` when no project name is provided. Pass `--interactive` to force prompts.
+</Callout>
+
+## Non-interactive usage
+
+Pass platform and state adapters with `--adapter`:
+
+```bash
+npm create chat-sdk@latest -- my-bot --adapter slack redis -y
+```
+
+<Callout type="warn">
+  With npm, the `--` separator is required because npm consumes flags before it (`-y` is npm's own `--yes`) instead of forwarding them to the CLI. `pnpm create` and `yarn create` forward flags without it.
+</Callout>
+
+The interactive prompt lists official adapters by default. Pass `--vendor` to list only vendor-official adapters instead. Automation and coding agents can install any CLI-supported official or vendor adapter directly with `--adapter`.
+
+Adapters that require a long-running process, including Matrix and Lark, cannot run on the webhook-only serverless runtime and are not available through the CLI. Add them to an existing project manually instead.
+
+<AdapterSlugList />
+
+Examples:
+
+```bash
+npm create chat-sdk@latest -- slack-bot --adapter slack memory -y --skip-install
+npm create chat-sdk@latest -- gchat-bot --adapter gchat redis -y --pm pnpm
+npm create chat-sdk@latest -- email-bot --adapter resend postgres -y --no-git
+npm create chat-sdk@latest -- my-bot --adapter slack memory -y --force
+```
+
+## What gets generated
+
+The scaffolded app is webhook-only. It does not include pages, layouts, or a client UI.
+
+```txt
+src/
+  lib/bot.ts                              Bot configuration and handlers
+  app/api/webhooks/[platform]/route.ts    Dynamic platform webhook route
+  app/api/chat/route.ts                   Web adapter route, only when selected
+  app/api/discord/gateway/route.ts        Discord Gateway listener, only when selected
+.env.example                              Required environment variables
+next.config.ts                            Next.js server config
+vercel.json                               Cron schedules, only when needed
+.chat-sdk.json                            Generated file ownership for safe reruns
+package.json                              Adapter dependencies
+```
+
+Webhook endpoints use the selected adapter slug:
+
+```txt
+/api/webhooks/slack
+/api/webhooks/gchat
+/api/webhooks/discord
+```
+
+When the [Web adapter](/adapters/official/web) is selected, the CLI also creates `/api/chat` for browser chat requests and a small `getUser` auth stub. Replace the stub with your app's real authentication logic so each web conversation can be associated with the correct user.
+
+When the [Discord adapter](/adapters/official/discord) is selected, the CLI also creates a Gateway listener at `/api/discord/gateway` and a `vercel.json` cron that calls it. Discord delivers slash commands and button clicks to the webhook route, but regular messages and reactions only arrive over the Gateway WebSocket, so the cron keeps that connection alive and forwards events to `/api/webhooks/discord`. Set a `CRON_SECRET` environment variable to authenticate the cron requests. The generated serverless Gateway cron requires [Vercel Pro or Enterprise](https://vercel.com/docs/cron-jobs/usage-and-pricing) because it runs every nine minutes.
+
+## Reference
+
+| Option | Description |
+| --- | --- |
+| `[name]` | Name of the project. |
+| `-d, --description <text>` | Project description. |
+| `--adapter <values...>` | Platform or state adapters to include. |
+| `--vendor` | List only vendor-official adapters in the interactive prompt. |
+| `--pm <manager>` | Package manager to use: `npm`, `yarn`, `pnpm`, or `bun`. |
+| `-y, --yes` | Skip prompts and accept defaults. |
+| `--interactive` | Always prompt, even when a coding agent environment is detected. |
+| `-f, --force` | Overwrite generated files in an existing directory. |
+| `-s, --skip-install` | Skip dependency installation. |
+| `--no-git` | Skip git repository initialization. |
+| `-q, --quiet` | Suppress non-essential output. |
+
+Color output follows the [NO_COLOR standard](https://no-color.org/) — set `NO_COLOR=1` to disable colors.
+
+## Customize your bot
+
+Most bot behavior lives in `src/lib/bot.ts`. Start there when you want to:
+
+- Add or change handlers like `onNewMention`, `onSubscribedMessage`, `onNewMessage`, reactions, actions, or slash commands.
+- Adjust adapter configuration, for example passing explicit credentials or platform-specific options instead of relying only on environment variables.
+- If you selected the memory state adapter, switch to Redis, ioredis, or PostgreSQL before deploying to production.
+
+The generated file includes starter handlers for mentions and subscribed thread replies.
+
+## Next steps
+
+After scaffolding:
+
+```bash
+cd my-bot
+cp .env.example .env.local
+npm run dev
+```
+
+Fill in the generated environment variables, expose your local server, and configure each selected platform to call its `/api/webhooks/{adapter}` endpoint.
+
+## Resources
+
+See guides, templates, and examples on the [resources](/resources) page.

package/docs/ephemeral-messages.mdx

@@ -32,6 +32,8 @@ The `fallbackToDM` option is required and controls behavior on platforms without
 | Discord | No | DM fallback | Persists in DM |
 | Teams | No | DM fallback | Persists in DM |
 
+Discord slash command responses can be made ephemeral with the Discord adapter's [`interactionFlags` option](/adapters/official/discord#interaction-flags). Outside that interaction flow, `postEphemeral` still follows the fallback behavior.
+
 ## Check for fallback
 
 ```typescript title="lib/bot.ts" lineNumbers

package/docs/error-handling.mdx

@@ -105,7 +105,7 @@ try {
   }}
 />
 
-See the [feature matrix](/docs/adapters) for which features are supported on each platform.
+See the [feature matrix](/docs/platform-adapters) for which features are supported on each platform.
 
 ### LockError
 

package/docs/getting-started.mdx

@@ -19,14 +19,14 @@ Learn the core patterns for handling incoming events and posting messages back t
 Connect your bot to chat platforms and persist state across restarts.
 
 <Cards>
-  <Card title="Platform Adapters" description="Platform-specific adapters for Slack, Teams, Google Chat, Discord, Telegram, GitHub, and Linear." href="/docs/adapters" />
-  <Card title="State Adapters" description="Pluggable state adapters for thread subscriptions, distributed locking, and caching." href="/docs/state" />
+  <Card title="Platform Adapters" description="Platform-specific adapters for Slack, Teams, Google Chat, Discord, Telegram, GitHub, and Linear." href="/docs/platform-adapters" />
+  <Card title="State Adapters" description="Pluggable state adapters for thread subscriptions, distributed locking, and caching." href="/docs/state-adapters" />
 </Cards>
 
 Browse all official and community adapters on the [Adapters](/adapters) page.
 
 ## Resources
 
-- [The Complete Guide to Chat SDK](https://vercel.com/kb/guide/the-complete-guide-to-chat-sdk) — End-to-end walkthrough that takes you from zero to a deployed multi-platform bot, covering adapters, state, handlers, cards, and streaming.
+- [The Complete Guide to Chat SDK](https://vercel.com/kb/guide/the-complete-guide-to-chat-sdk?utm_source=chat-sdk_site&utm_medium=docs&utm_campaign=getting-started&utm_content=the-complete-guide-to-chat-sdk) — End-to-end walkthrough that takes you from zero to a deployed multi-platform bot, covering adapters, state, handlers, cards, and streaming.
 
-See all guides and templates on the [resources](/resources) page.
+See all guides and templates on the [resources](/resources?utm_source=chat-sdk_site&utm_medium=docs&utm_campaign=getting-started&utm_content=resources) page.

package/docs/index.mdx

@@ -55,7 +55,7 @@ Each adapter factory auto-detects credentials from environment variables (`SLACK
 | Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | Yes | Native (DMs) / Buffered | 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 | Private chat drafts / Post+Edit | Yes |
+| Telegram | `@chat-adapter/telegram` | Yes | Yes | Partial | No | Rich drafts / Post+Edit | Yes |
 | GitHub | `@chat-adapter/github` | Yes | Yes | No | No | Buffered | No |
 | Linear | `@chat-adapter/linear` | Yes | Yes | No | No | Agent sessions / Post+Edit | No |
 | WhatsApp | `@chat-adapter/whatsapp` | N/A | Yes | Partial | No | Buffered | Yes |

package/docs/meta.json

@@ -3,6 +3,7 @@
   "pages": [
     "index",
     "getting-started",
+    "create-chat-sdk",
     "---Usage---",
     "usage",
     "threads-messages-channels",
@@ -14,8 +15,10 @@
     "...ai",
     "---Adapters---",
     "adapters",
+    "platform-adapters",
     "slack-primitives",
-    "state",
+    "teams-primitives",
+    "state-adapters",
     "---Messaging---",
     "streaming",
     "direct-messages",

package/docs/platform-adapters.mdx

@@ -0,0 +1,148 @@
+---
+title: Platform Adapters
+description: Platform-specific adapters that connect your bot to any messaging platform.
+type: overview
+prerequisites:
+  - /docs/getting-started
+  - /docs/adapters
+---
+
+Platform adapters handle webhook verification, message parsing, and API calls for each messaging platform. Install only the adapters you need. Browse all available adapters, including community-built ones, on the [Adapters](/adapters) page.
+
+Need a browser chat UI? See the [Web adapter](/adapters/official/web). It speaks the AI SDK UI stream protocol and works with React (`@ai-sdk/react`), Vue (`@ai-sdk/vue`), and Svelte (`@ai-sdk/svelte`), so the same bot serves Slack, Teams, and any browser framework out of the box.
+
+Ready to build your own? Follow the [building](/docs/contributing/building) guide.
+
+## Feature matrix
+
+<GlobalFeatureMatrix type="platform" />
+
+### Messaging
+
+| Feature | [Slack](/adapters/slack) | [Teams](/adapters/teams) | [Google Chat](/adapters/gchat) | [Discord](/adapters/discord) | [Telegram](/adapters/telegram) | [GitHub](/adapters/github) | [Linear](/adapters/linear) | [WhatsApp](/adapters/whatsapp) | [Messenger](/adapters/messenger) |
+|---------|-------|-------|-------------|---------|---------|--------|--------|-----------|-----------|
+| Post message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Edit message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| Delete message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file/media | <Cross /> | <Cross /> | <Check /> Images, audio, docs | <Cross /> |
+| Streaming | <Check /> Native | <Warn /> Native (DMs) / Buffered | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Rich drafts / Post+Edit | <Warn /> Buffered | <Warn /> Agent sessions / Post+Edit | <Warn /> Buffered | <Warn /> Buffered |
+| Scheduled messages | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+
+### Rich content
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown | WhatsApp templates | Generic/Button Templates |
+| Buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard callbacks | <Cross /> | <Cross /> | <Check /> Interactive replies | <Warn /> Max 3, postback |
+| Link buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard URLs | <Cross /> | <Cross /> | <Cross /> | <Check /> |
+| Select menus | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Tables | <Check /> Block Kit | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Warn /> Native messages / ASCII cards | <Check /> GFM | <Check /> GFM | <Cross /> | <Warn /> ASCII |
+| Fields | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Template variables | <Warn /> ASCII |
+| Images in cards | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Check /> | <Check /> |
+| Modals | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+
+### Conversations
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Slash commands | <Check /> | <Cross /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Mentions | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> |
+| Add reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
+| Remove reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Warn /> | <Warn /> | <Check /> | <Cross /> |
+| Typing indicator | <Check /> | <Check /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Warn /> Agent sessions | <Warn /> | <Check /> |
+| DMs | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
+| Ephemeral messages | <Check /> Native | <Cross /> | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| User lookup ([`getUser`](/docs/api/chat#getuser)) | <Check /> | <Warn /> Cached | <Warn /> Cached | <Check /> | <Warn /> Seen users | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Parent subject ([`message.subject`](/docs/subject)) | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Native client ([`.webClient` / `.octokit` / `.linearClient`](/docs/api/chat#getadapter)) | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Custom API endpoint (`apiUrl`) | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+
+### Message history
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Fetch messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Check /> | <Warn /> Cached sent messages only | <Warn /> Cached sent messages only |
+| Fetch single message | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| Fetch thread info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Fetch channel messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| List threads | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> |
+| Fetch channel info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
+| Post channel message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
+
+<Callout type="info">
+<Warn /> indicates partial support. The feature works with limitations. See individual adapter pages for details.
+</Callout>
+
+## How adapters work
+
+Each adapter implements a standard interface that the `Chat` class uses to route events and send messages. When a webhook arrives:
+
+1. The adapter verifies the request signature
+2. Parses the platform-specific payload into a normalized `Message`
+3. Routes to your handlers via the `Chat` class
+4. Converts outgoing messages from markdown/AST/cards to the platform's native format
+
+## Using multiple adapters
+
+Register multiple [adapters](/adapters) and your event handlers work across all of them:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createTeamsAdapter } from "@chat-adapter/teams";
+import { createGoogleChatAdapter } from "@chat-adapter/gchat";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter(),
+    teams: createTeamsAdapter(),
+    gchat: createGoogleChatAdapter(),
+  },
+  state: createRedisState(),
+});
+
+// This handler fires for mentions on any platform
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post("Hello!");
+});
+```
+
+Each adapter auto-detects credentials from environment variables, so you only need to pass config when overriding defaults.
+
+<Callout type="info">
+  The examples above use Redis for state. See [State Adapters](/docs/state-adapters) for all available options.
+</Callout>
+
+Each adapter creates a webhook handler accessible via `bot.webhooks.<name>`.
+
+## Customizing an adapter via subclassing
+
+Each official adapter exposes its extension surface as `protected` members so you can subclass it to override or extend platform-specific behavior without forking the package. Use this when you need to handle a payload type the built-in adapter doesn't cover, intercept verification, or wrap an existing handler.
+
+```typescript title="lib/custom-telegram.ts" lineNumbers
+import { TelegramAdapter, type TelegramUpdate } from "@chat-adapter/telegram";
+import type { WebhookOptions } from "chat";
+
+export class CustomTelegramAdapter extends TelegramAdapter {
+  protected override processUpdate(
+    update: TelegramUpdate,
+    options?: WebhookOptions
+  ): void {
+    // Handle a payload type the base adapter doesn't, e.g. chat_join_request.
+    if ("chat_join_request" in update) {
+      this.logger.info("Received chat_join_request", { update });
+      return;
+    }
+    super.processUpdate(update, options);
+  }
+}
+```
+
+Construct your subclass anywhere you'd construct the base adapter, for example, `adapters: { telegram: new CustomTelegramAdapter({ ... }) }`. Members marked `private` intentionally remain inaccessible. If you find a hook you need that isn't `protected`, please open an issue.
+
+<Callout type="warn">
+  The `protected` extension surface is intentionally broader than the public API but is not yet considered fully stable. Method signatures may evolve in minor releases as we learn from real-world subclasses. Pin the adapter version you build against, watch the changelog for the affected adapter, and prefer overriding the smallest hook that solves your problem so upgrades stay easy. If you rely on a particular hook, please open an issue so we can promote it to a stable, documented extension point.
+</Callout>

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,10 +113,16 @@ 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()`.
 
+To make selected Discord slash command responses ephemeral, return `DiscordInteractionResponseFlag.Ephemeral` from the Discord adapter's [`interactionFlags` option](/adapters/official/discord#interaction-flags).
+
 ### Subcommands
 
 Discord supports subcommand groups and subcommands. The adapter flattens these into the `event.command` path:

package/docs/streaming.mdx

@@ -59,7 +59,7 @@ await thread.post(stream);
 | Platform | Method | Description |
 |----------|--------|-------------|
 | Slack | Native streaming API | Uses Slack's `chatStream` for smooth, real-time updates |
-| Telegram | Private chat draft previews | Uses Telegram's `sendMessageDraft` in private chats and falls back to post + edit elsewhere |
+| 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 |
@@ -217,11 +217,14 @@ await plan.addTask({ title: "Summarize findings" });
 await plan.complete({ completeMessage: "Done!" });
 ```
 
-By default `updateTask()` mutates the most recent `in_progress` task. Pass `{ id }` to target a specific task — useful when work runs in parallel or out of order:
+By default `updateTask()` mutates the most recent `in_progress` task. For parallel work, pass `autoCompletePrevious: false` to `addTask()` so earlier tasks stay in progress; then pass `{ id }` to `updateTask()` to target a specific task when updates run out of order:
 
 ```typescript
 const fetchTask = await plan.addTask({ title: "Fetch data" });
-const transformTask = await plan.addTask({ title: "Transform" });
+const transformTask = await plan.addTask({
+  title: "Transform",
+  autoCompletePrevious: false,
+});
 
 // Update a specific task by id, even if it isn't the most recent in_progress one.
 await plan.updateTask({ id: fetchTask.id, output: "Got 42 rows" });
@@ -232,7 +235,7 @@ Adapters that don't support PostableObject editing (e.g. WhatsApp) render the pl
 
 | Method | Description |
 |--------|-------------|
-| `addTask({ title, children? })` | Append a new task. The previous in-progress task is auto-completed |
+| `addTask({ title, children?, autoCompletePrevious? })` | Append a new task. When `autoCompletePrevious` is true (default), existing in-progress tasks are marked complete first; pass `false` for parallel workflows |
 | `updateTask(input)` | Mutate the current (or `{ id }`-targeted) task's `output`, `status`, or `title` |
 | `complete({ completeMessage })` | Mark all in-progress tasks complete and update the plan title |
 | `reset({ initialMessage })` | Discard all tasks and start fresh with a new initial message — useful when re-using a plan handle for a new run |