@assistant-ui/mcp-docs-server 0.2.0 → 0.2.2

package/.docs/raw/docs/integrations/persistence/custom-adapter.mdx

@@ -227,7 +227,7 @@ export async function POST(
 
 ### Implement `RemoteThreadListAdapter`
 
-The adapter calls your endpoints. `unstable_Provider` injects the per-thread history adapter so messages persist alongside metadata.
+The adapter calls your endpoints. `unstable_useAdapters` injects the per-thread history adapter on the `RemoteThreadList` store entry and on `useRemoteThreadListRuntime` when `unstable_Provider` is omitted. `unstable_Provider` is an optional React face for that runtime. On the `RemoteThreadList` store entry, key the thread factory with `withKey(id, …)` so history reloads when the visible thread changes.
 
 <PlatformTabs>
 <Tab value="React">
@@ -244,6 +244,51 @@ import {
 import { createAssistantStream } from "assistant-stream";
 import { useMemo } from "react";
 
+function useThreadListAdapters() {
+  const aui = useAui();
+  const history = useMemo<ThreadHistoryAdapter>(
+    () => ({
+      async load() {
+        return { messages: [] };
+      },
+      async append() {},
+      withFormat: (fmt) => ({
+        async load() {
+          const { remoteId } = aui.threadListItem.getState();
+          if (!remoteId) return { messages: [] };
+          const rows = await fetch(
+            `/api/threads/${remoteId}/messages`,
+          ).then((r) => r.json());
+          return {
+            messages: rows.map((row: any) =>
+              fmt.decode({
+                id: row.id,
+                parent_id: row.parent_id,
+                format: row.format,
+                content: row.content,
+              }),
+            ),
+          };
+        },
+        async append(item) {
+          const { remoteId } = await aui.threadListItem.initialize();
+          await fetch(`/api/threads/${remoteId}/messages`, {
+            method: "POST",
+            body: JSON.stringify({
+              id: fmt.getId(item.message),
+              parent_id: item.parentId,
+              format: fmt.format,
+              content: fmt.encode(item),
+            }),
+          });
+        },
+      }),
+    }),
+    [aui],
+  );
+  return useMemo(() => ({ history }), [history]);
+}
+
 export const threadListAdapter: RemoteThreadListAdapter = {
   async list() {
     const rows = await fetch("/api/threads").then((r) => r.json());
@@ -295,50 +340,11 @@ export const threadListAdapter: RemoteThreadListAdapter = {
       controller.appendText(title);
     });
   },
+  unstable_useAdapters: useThreadListAdapters,
   unstable_Provider({ children }) {
-    const aui = useAui();
-    const history = useMemo<ThreadHistoryAdapter>(
-      () => ({
-        async load() {
-          return { messages: [] };
-        },
-        async append() {},
-        withFormat: (fmt) => ({
-          async load() {
-            const { remoteId } = aui.threadListItem.getState();
-            if (!remoteId) return { messages: [] };
-            const rows = await fetch(
-              `/api/threads/${remoteId}/messages`,
-            ).then((r) => r.json());
-            return {
-              messages: rows.map((row: any) =>
-                fmt.decode({
-                  id: row.id,
-                  parent_id: row.parent_id,
-                  format: row.format,
-                  content: row.content,
-                }),
-              ),
-            };
-          },
-          async append(item) {
-            const { remoteId } = await aui.threadListItem.initialize();
-            await fetch(`/api/threads/${remoteId}/messages`, {
-              method: "POST",
-              body: JSON.stringify({
-                id: fmt.getId(item.message),
-                parent_id: item.parentId,
-                format: fmt.format,
-                content: fmt.encode(item),
-              }),
-            });
-          },
-        }),
-      }),
-      [aui],
-    );
+    const adapters = useThreadListAdapters();
     return (
-      <RuntimeAdapterProvider adapters={{ history }}>
+      <RuntimeAdapterProvider adapters={adapters}>
         {children}
       </RuntimeAdapterProvider>
     );
@@ -359,6 +365,51 @@ import {
 import { createAssistantStream } from "assistant-stream";
 import { useMemo } from "react";
 
+function useThreadListAdapters() {
+  const aui = useAui();
+  const history = useMemo<ThreadHistoryAdapter>(
+    () => ({
+      async load() {
+        return { messages: [] };
+      },
+      async append() {},
+      withFormat: (fmt) => ({
+        async load() {
+          const { remoteId } = aui.threadListItem.getState();
+          if (!remoteId) return { messages: [] };
+          const rows = await fetch(
+            `${API_URL}/threads/${remoteId}/messages`,
+          ).then((r) => r.json());
+          return {
+            messages: rows.map((row: any) =>
+              fmt.decode({
+                id: row.id,
+                parent_id: row.parent_id,
+                format: row.format,
+                content: row.content,
+              }),
+            ),
+          };
+        },
+        async append(item) {
+          const { remoteId } = await aui.threadListItem.initialize();
+          await fetch(`${API_URL}/threads/${remoteId}/messages`, {
+            method: "POST",
+            body: JSON.stringify({
+              id: fmt.getId(item.message),
+              parent_id: item.parentId,
+              format: fmt.format,
+              content: fmt.encode(item),
+            }),
+          });
+        },
+      }),
+    }),
+    [aui],
+  );
+  return useMemo(() => ({ history }), [history]);
+}
+
 export const threadListAdapter: RemoteThreadListAdapter = {
   async list() {
     const rows = await fetch(`${API_URL}/threads`).then((r) => r.json());
@@ -412,50 +463,11 @@ export const threadListAdapter: RemoteThreadListAdapter = {
       controller.appendText(title);
     });
   },
+  unstable_useAdapters: useThreadListAdapters,
   unstable_Provider({ children }) {
-    const aui = useAui();
-    const history = useMemo<ThreadHistoryAdapter>(
-      () => ({
-        async load() {
-          return { messages: [] };
-        },
-        async append() {},
-        withFormat: (fmt) => ({
-          async load() {
-            const { remoteId } = aui.threadListItem.getState();
-            if (!remoteId) return { messages: [] };
-            const rows = await fetch(
-              `${API_URL}/threads/${remoteId}/messages`,
-            ).then((r) => r.json());
-            return {
-              messages: rows.map((row: any) =>
-                fmt.decode({
-                  id: row.id,
-                  parent_id: row.parent_id,
-                  format: row.format,
-                  content: row.content,
-                }),
-              ),
-            };
-          },
-          async append(item) {
-            const { remoteId } = await aui.threadListItem.initialize();
-            await fetch(`${API_URL}/threads/${remoteId}/messages`, {
-              method: "POST",
-              body: JSON.stringify({
-                id: fmt.getId(item.message),
-                parent_id: item.parentId,
-                format: fmt.format,
-                content: fmt.encode(item),
-              }),
-            });
-          },
-        }),
-      }),
-      [aui],
-    );
+    const adapters = useThreadListAdapters();
     return (
-      <RuntimeAdapterProvider adapters={{ history }}>
+      <RuntimeAdapterProvider adapters={adapters}>
         {children}
       </RuntimeAdapterProvider>
     );
@@ -478,6 +490,51 @@ import {
 import { createAssistantStream } from "assistant-stream";
 import { useMemo } from "react";
 
+function useThreadListAdapters() {
+  const aui = useAui();
+  const history = useMemo<ThreadHistoryAdapter>(
+    () => ({
+      async load() {
+        return { messages: [] };
+      },
+      async append() {},
+      withFormat: (fmt) => ({
+        async load() {
+          const { remoteId } = aui.threadListItem.getState();
+          if (!remoteId) return { messages: [] };
+          const rows = await fetch(
+            `${API_URL}/threads/${remoteId}/messages`,
+          ).then((r) => r.json());
+          return {
+            messages: rows.map((row: any) =>
+              fmt.decode({
+                id: row.id,
+                parent_id: row.parent_id,
+                format: row.format,
+                content: row.content,
+              }),
+            ),
+          };
+        },
+        async append(item) {
+          const { remoteId } = await aui.threadListItem.initialize();
+          await fetch(`${API_URL}/threads/${remoteId}/messages`, {
+            method: "POST",
+            body: JSON.stringify({
+              id: fmt.getId(item.message),
+              parent_id: item.parentId,
+              format: fmt.format,
+              content: fmt.encode(item),
+            }),
+          });
+        },
+      }),
+    }),
+    [aui],
+  );
+  return useMemo(() => ({ history }), [history]);
+}
+
 export const threadListAdapter: RemoteThreadListAdapter = {
   async list() {
     const rows = await fetch(`${API_URL}/threads`).then((r) => r.json());
@@ -531,50 +588,11 @@ export const threadListAdapter: RemoteThreadListAdapter = {
       controller.appendText(title);
     });
   },
+  unstable_useAdapters: useThreadListAdapters,
   unstable_Provider({ children }) {
-    const aui = useAui();
-    const history = useMemo<ThreadHistoryAdapter>(
-      () => ({
-        async load() {
-          return { messages: [] };
-        },
-        async append() {},
-        withFormat: (fmt) => ({
-          async load() {
-            const { remoteId } = aui.threadListItem.getState();
-            if (!remoteId) return { messages: [] };
-            const rows = await fetch(
-              `${API_URL}/threads/${remoteId}/messages`,
-            ).then((r) => r.json());
-            return {
-              messages: rows.map((row: any) =>
-                fmt.decode({
-                  id: row.id,
-                  parent_id: row.parent_id,
-                  format: row.format,
-                  content: row.content,
-                }),
-              ),
-            };
-          },
-          async append(item) {
-            const { remoteId } = await aui.threadListItem.initialize();
-            await fetch(`${API_URL}/threads/${remoteId}/messages`, {
-              method: "POST",
-              body: JSON.stringify({
-                id: fmt.getId(item.message),
-                parent_id: item.parentId,
-                format: fmt.format,
-                content: fmt.encode(item),
-              }),
-            });
-          },
-        }),
-      }),
-      [aui],
-    );
+    const adapters = useThreadListAdapters();
     return (
-      <RuntimeAdapterProvider adapters={{ history }}>
+      <RuntimeAdapterProvider adapters={adapters}>
         {children}
       </RuntimeAdapterProvider>
     );
@@ -728,7 +746,7 @@ Send a message in a fresh thread. Check the database:
 
 ## Notes
 
-- **First-message race.** `append` may fire before the thread row exists. The `unstable_Provider` example above always awaits `aui.threadListItem.initialize()` before writing; do the same in any custom implementation.
+- **First-message race.** `append` may fire before the thread row exists. The example above always awaits `aui.threadListItem.initialize()` before writing; do the same in any custom implementation.
 - **Reload after async auth.** If `auth()` resolves after the initial `list()` call, threads won't appear until the user refreshes. Call `aui.threads.reload()` from a `useEffect` watching the session. Pattern is documented in [threads](/docs/runtimes/concepts/threads#reloading-after-async-authentication).
 - **Format string.** The `format` column is *not* a free-text label; it identifies the on-disk shape so multiple runtimes can coexist. Don't strip it. Don't make assumptions about its value (`useChatRuntime` is responsible for setting and decoding it).
 - **Pending approvals need `update`.** Tool call approvals persist across reloads only when the formatted adapter implements `update`; omitting it keeps the pre-approval snapshot out of storage by design.

package/.docs/raw/docs/migrations/toolkit-tools.mdx

@@ -73,20 +73,18 @@ export default defineToolkit({
 
 import {
   AssistantRuntimeProvider,
+  AuiConfig,
   Tools,
-  useAui,
 } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import toolkit from "./toolkit";
 
 export function App() {
   const runtime = useChatRuntime();
-  const aui = useAui({
-    tools: Tools({ toolkit }),
-  });
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
 
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
       <Thread />
     </AssistantRuntimeProvider>
   );
@@ -100,7 +98,7 @@ export function App() {
 1. Create a `Toolkit` object.
 2. Move each `toolName` into the toolkit key.
 3. Move `description`, `parameters`, `execute`, `providerOptions`, `render`, `renderText`, and `display` onto the toolkit entry.
-4. Register the toolkit once with `useAui({ tools: Tools({ toolkit }) })`.
+4. Register the toolkit once with `config={config}` on your runtime provider, where `const config = AuiConfig({ tools: Tools({ toolkit }) })`.
 5. Remove `<Tool />`, `<ToolUI />`, `useAssistantTool(...)`, and `useAssistantToolUI(...)` registrations.
 
 ## UI-Only Tool Renderers
@@ -126,7 +124,7 @@ export default defineToolkit({
 });
 ```
 
-Register it like any toolkit: `useAui({ tools: Tools({ toolkit }) })`.
+Register it like any toolkit: `config={config}` where `const config = AuiConfig({ tools: Tools({ toolkit }) })`.
 Render-only entries upload no schema and run no browser code — they only attach
 UI for matching tool-call message parts. For MCP server catalogs, spread
 `defineMcpToolkit({ ... })` in the same generative toolkit.
@@ -163,20 +161,24 @@ export default defineToolkit({
 ```
 
 ```tsx title="TaskBoard.tsx"
-import { AuiProvider, Tools, useAui, useAuiToolOverrides } from "@assistant-ui/react";
+import {
+  AuiConfig,
+  AuiProvider,
+  Tools,
+  useAui,
+  useAuiToolOverrides,
+} from "@assistant-ui/react";
 import { useState, type Dispatch, type SetStateAction } from "react";
 import type { Task } from "./task-board-toolkit";
 import toolkit from "./task-board-toolkit";
 
 function TaskBoard() {
   const [tasks, setTasks] = useState<Task[]>([]);
-
-  const aui = useAui({
-    tools: Tools({ toolkit }),
-  });
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
 
   return (
-    <AuiProvider value={aui}>
+    <AuiProvider extends={aui} config={config}>
       <TaskBoardToolOverrides setTasks={setTasks} />
       <TaskList tasks={tasks} />
     </AuiProvider>

package/.docs/raw/docs/migrations/v0-15.mdx

@@ -133,16 +133,130 @@ const aui = useAui(scopes, { parent });
 
 // After
 const Scoped = ({ children }) => {
-  const aui = useAui(scopes); // extends the AuiProvider parent
-  return <AuiProvider value={aui}>{children}</AuiProvider>;
+  const aui = useAui();
+  const config = AuiConfig(scopes);
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 };
 
-<AuiProvider value={parent}>
+const rootConfig = AuiConfig({});
+
+<AuiProvider extends={parent} config={rootConfig}>
   <Scoped />
 </AuiProvider>;
 ```
 
-Where `{ parent: null }` was used to detach from context, `<AuiProvider value={null}>` now provides an isolated empty root (experimental).
+Where `{ parent: null }` was used to detach from context, `<AuiProvider extends={null} config={config}>` where `const config = AuiConfig({})` now provides an isolated empty root.
+
+## `AuiProvider` Grammar
+
+`AuiProvider` takes a `config` built with `AuiConfig(...)` — raw object literals are a type error. At the top level, `config` alone creates the subtree's client. Nested under a parent provider, `extends` is mandatory: `extends={aui}` extends the parent, `extends={null}` isolates (dev-enforced). `ref` receives the resulting client after mount.
+
+```tsx
+const aui = useAui();
+const config = AuiConfig({ tools: Tools({ toolkit }) });
+
+// Top-level root
+<AuiProvider config={config}>
+
+// Nested: extend the parent
+<AuiProvider extends={aui} config={config}>
+
+// Nested: isolate from the parent
+<AuiProvider extends={null} config={config}>
+```
+
+`AuiConfig` is exported from `@assistant-ui/store` and re-exported from `@assistant-ui/react`, `@assistant-ui/react-native`, and `@assistant-ui/react-ink`.
+
+### `value` Prop Deprecated
+
+```tsx
+// Before
+<AuiProvider value={client}>
+<AuiProvider value={null}>
+
+// After
+const config = AuiConfig({});
+
+<AuiProvider extends={client} config={config}>
+<AuiProvider extends={null} config={config}>
+```
+
+The replacement exposes a client extending the given one, not the same instance — `useAui()` beneath it returns the new client, with scope access delegating to `client`. The deprecated `value={client}` form behaves the same way: it also exposes a derived client rather than the exact instance, and the given client must implement `subscribe`.
+
+### `useAui({ ... })` Extension Overload Deprecated
+
+```tsx
+// Before
+const aui = useAui({ tools: Tools({ toolkit }) });
+return <AuiProvider value={aui}>{children}</AuiProvider>;
+
+// After
+const aui = useAui();
+const config = AuiConfig({ tools: Tools({ toolkit }) });
+return (
+  <AuiProvider extends={aui} config={config}>
+    {children}
+  </AuiProvider>
+);
+```
+
+Where the extended client was passed to `<AssistantRuntimeProvider aui={aui}>`, use the new `config` prop instead — the scopes are provided alongside the runtime's threads scope:
+
+```tsx
+// Before
+const aui = useAui({ tools: Tools({ toolkit }) });
+return (
+  <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    {children}
+  </AssistantRuntimeProvider>
+);
+
+// After
+const config = AuiConfig({ tools: Tools({ toolkit }) });
+return (
+  <AssistantRuntimeProvider runtime={runtime} config={config}>
+    {children}
+  </AssistantRuntimeProvider>
+);
+```
+
+## Thread Switch Events: `threads.selectionChanged`
+
+The per-item thread switch events are deprecated in favor of a single event on the thread list. `threads.selectionChanged` fires once per switch and carries both sides of the transition:
+
+```ts
+// Before
+useAuiEvent("threadListItem.switchedTo", ({ threadId }) => {
+  // threadId: the newly selected thread
+});
+useAuiEvent("threadListItem.switchedAway", ({ threadId }) => {
+  // threadId: the thread that was switched away from
+});
+
+// After
+useAuiEvent("threads.selectionChanged", ({ threadId, previousThreadId }) => {
+  // threadId: the newly selected thread
+  // previousThreadId: the thread that was switched away from
+});
+```
+
+Like its predecessors, it does not fire for the initially selected thread on mount. The deprecated events still fire and will keep working until the next major.
+
+The deprecated pair was scope-filtered: inside a per-item `threadListItem` scope (such as `ThreadListPrimitive.Items`), `threadListItem.switchedTo` only fired for that item. `threads.selectionChanged` resolves against the shared `threads` scope, so every listener fires on every switch. Filter by id to reproduce the per-item behavior:
+
+```ts
+const id = useAuiState((s) => s.threadListItem.id);
+useAuiEvent("threads.selectionChanged", ({ threadId }) => {
+  if (threadId !== id) return;
+  // this item became selected
+});
+```
+
+The new event also fires in situations where the deprecated pair did not: `InMemoryThreadList` emits on selection changes (it previously emitted no switch events), and `switchToNewThread()` emits for the newly created thread. Selection-driven defaults such as `scrollToBottomOnThreadSwitch` and `unstable_focusOnThreadSwitched` now engage in both situations. Runtimes that resolve a deep-linked `threadId`/`initialThreadId` after mount (such as `useRemoteThreadListRuntime`) start on a placeholder new thread, so the deep link's resolution also fires the event — `previousThreadId` is the placeholder in that case.
 
 ## Still Deprecated (not removed)
 

package/.docs/raw/docs/primitives/attachment.mdx

@@ -53,7 +53,7 @@ import { AttachmentPrimitive, ComposerPrimitive } from "@assistant-ui/react";
 </ComposerPrimitive.Root>
 ```
 
-`Root` renders a `<div>`, `unstable_Thumb` renders a `<div>` showing the file extension with a leading dot (e.g., `.pdf`), `Name` renders plain text, and `Remove` renders a `<button>`.
+`Root` renders a `<div>`, `unstable_Thumb` renders a `<div>` showing the file extension with a leading dot (e.g., `.pdf`), or the attachment type (e.g., `image`) when the filename has no extension (including leading-dot names like `.env`), `Name` renders plain text, and `Remove` renders a `<button>`. If you pass `children` to `unstable_Thumb`, they override that text.
 
 <Callout type="info">
 Runtime setup: primitives require runtime context. Wrap your UI in `AssistantRuntimeProvider` with a runtime (for example `useLocalRuntime(...)`). See [Pick a Runtime](/docs/runtimes/pick-a-runtime).
@@ -124,7 +124,7 @@ Container for a single attachment item. Renders a `<div>` element unless `asChil
 
 ### unstable_Thumb
 
-Thumbnail slot for attachment previews. Renders a `<div>` element unless `asChild` is set.
+Thumbnail slot for attachment previews. Renders a `<div>` element unless `asChild` is set. By default it shows the file extension with a leading dot (e.g., `.pdf`); if you pass `children`, they override the automatic text.
 
 ```tsx
 <AttachmentPrimitive.unstable_Thumb className="flex size-10 items-center justify-center rounded bg-muted text-xs" />

package/.docs/raw/docs/primitives/composer.mdx

@@ -258,7 +258,7 @@ Renders a single attachment at a specific index.
 
 ### AttachmentDropzone
 
-Drag-and-drop zone for file attachments. Sets `data-dragging` when a file is being dragged over it. Renders a `<div>` element unless `asChild` is set.
+Drag-and-drop zone for file attachments. Sets `data-dragging` when a file is being dragged over it and the runtime supports attachments; without the attachments capability the dropzone accepts no files and shows no highlight. Non-file drags (text, links) are ignored. Renders a `<div>` element unless `asChild` is set.
 
 ```tsx
 <ComposerPrimitive.AttachmentDropzone className="rounded-xl border-2 border-dashed data-[dragging]:border-primary data-[dragging]:bg-primary/5">
@@ -507,7 +507,7 @@ Wrap your composer with `AttachmentDropzone` to support dragging files directly
 </ComposerPrimitive.AttachmentDropzone>
 ```
 
-The dropzone sets `data-dragging` when a file is being dragged over it, so you can style the active state with CSS.
+The dropzone sets `data-dragging` when a file is being dragged over it, so you can style the active state with CSS. It requires the runtime's attachments capability (an attachment adapter); without it the dropzone stays inert.
 
 ### With Voice Input
 

package/.docs/raw/docs/primitives/message.mdx

@@ -112,6 +112,37 @@ Runtime setup: primitives require runtime context. Wrap your UI in `AssistantRun
 For most new code, prefer `MessagePrimitive.Parts` with a `children` render function. When you need adjacent grouping, use `MessagePrimitive.GroupedParts`.
 </Callout>
 
+### Part Types
+
+A message part is one of three kinds, and which kind a new capability belongs to is decided by the list below rather than case by case.
+
+| Kind | Parts | Grows by |
+|------|-------|----------|
+| Modality | `text`, `image`, `file` | Never. `file` carries every non-image binary modality through its `mimeType`. |
+| Provider channel | `reasoning`, `source`, `tool-call`, `generative-ui` | Never. These mirror channels a model already emits. |
+| Extensibility | `data` | Freely, through `name`. This is the growth path for anything app-level. |
+
+`file` is the media carrier. Audio, video, PDFs and everything else are `{ type: "file", mimeType: "audio/mpeg" }` rather than part types of their own, so one renderer and one converter branch handle them all. The payload can be inline base64 or a URL; `sourceType` additionally allows an opaque storage id, which the LangChain-family runtimes honor and other adapters ignore.
+
+Anything that is not a modality the model consumes or a channel it emits is a `data` part, routed by `name`:
+
+```tsx
+<MessagePrimitive.Parts
+  components={{
+    data: {
+      by_name: { citation: MyCitation },
+      Fallback: MyDataFallback,
+    },
+  }}
+/>
+```
+
+<Callout type="warn">
+`Unstable_AudioMessagePart` and the `Unstable_Audio` slot are deprecated. The audio part cannot carry a filename, has no way to declare how its payload goes on the wire (no `sourceType`, so no storage id), and exists only on user messages, so a model that returns audio has no way to express it. Send audio as a `file` part with an `audio/*` mime type instead, and give it a filename.
+
+Adapter coverage for the file path is still uneven, so check your adapter's converter before relying on file parts. Known so far: `react-pi` and the assistant-transport runtime have no file part on their user-content surface at all, so one is dropped; `react-data-stream` carries the payload but not the filename. Existing audio parts keep working; they will not gain fields.
+</Callout>
+
 ### Tool Resolution
 
 Tool call parts resolve in this order:
@@ -149,7 +180,8 @@ Returning `null` still allows registered tool UIs and data renderer UIs to rende
 - `components.ChainOfThought` takes over all reasoning and tool-call rendering (mutually exclusive with `ToolGroup`, `ReasoningGroup`, `tools`, and `Reasoning`). This legacy path is deprecated; use `MessagePrimitive.GroupedParts` for grouped Chain of Thought in new code.
 - `data.by_name` and `data.Fallback` let you route custom data part types
 - `Quote` renders quoted message references from metadata
-- `Empty` and `Unstable_Audio` are available for edge and experimental rendering paths
+- `Empty` is available for edge rendering paths
+- `Unstable_Audio` is deprecated; render `audio/*` from the `File` slot instead
 
 ```tsx
 <MessagePrimitive.Parts

package/.docs/raw/docs/primitives/suggestion.mdx

@@ -106,7 +106,7 @@ Both render a `<span>` and accept `children` to override the value from state:
 
 `Trigger`'s `send` prop controls what happens on click:
 
-- **`send={true}`**: immediately sends the suggestion as a new message. When the thread is running, it falls back to populating the composer instead.
+- **`send={true}`**: immediately sends the suggestion as a new message. While a run is in progress, the suggestion is queued on runtimes that support queueing (leaving the composer draft untouched); otherwise the trigger is disabled.
 - **`send={false}`** (default): populates the composer text so the user can edit before sending
 
 ```tsx
@@ -130,11 +130,13 @@ When `send={false}`, the `clearComposer` prop controls whether the suggestion re
 
 ### Static configuration vs. runtime suggestions
 
-There are two separate data flows for suggestions:
+There are two data flows for suggestions:
 
 - **Static configuration** flows through the `suggestions` scope. Pass an array to `Suggestions(...)` in your runtime provider; render it with `ThreadPrimitive.Suggestions`. Best for welcome screen prompts.
 - **Runtime / dynamic suggestions** flow through `thread.suggestions`. Populate it via `SuggestionAdapter` (local runtime) or the `suggestions` field on `useExternalStoreRuntime`; render it with the shadcn `ThreadFollowupSuggestions` component or your own component reading `useAuiState((s) => s.thread.suggestions)`. Best for follow up prompts after a turn.
 
+When no static configuration is provided, the `suggestions` scope derives from `thread.suggestions`, so runtime suggestions also render through `ThreadPrimitive.Suggestions`. A static `Suggestions(...)` configuration takes precedence over the derived values.
+
 See [Suggested Prompts](/docs/guides/suggestions) for end to end examples.
 
 ### ThreadPrimitive.Suggestion (Legacy)

package/.docs/raw/docs/primitives/thread.mdx

@@ -143,7 +143,7 @@ Use `topAnchorMessageClamp` to control how much of a long user message remains v
 
 - `scrollToBottomOnRunStart` (default `true`): scrolls when `thread.runStart` fires
 - `scrollToBottomOnInitialize` (default `true`): scrolls when `thread.initialize` fires
-- `scrollToBottomOnThreadSwitch` (default `true`): scrolls when `threadListItem.switchedTo` fires
+- `scrollToBottomOnThreadSwitch` (default `true`): scrolls when `threads.selectionChanged` fires
 
 These work alongside `autoScroll`. If `autoScroll` is omitted, it defaults to `true` for `turnAnchor="bottom"` and `false` for `turnAnchor="top"`.