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

package/.docs/raw/docs/ink/primitives.mdx

@@ -3,7 +3,7 @@ title: Primitives
 description: Composable terminal components for building chat UIs with Ink.
 ---
 
-Primitives are thin wrappers around Ink components (`Box`, `Text`, `TextInput`) that integrate with the assistant-ui runtime. They accept all standard Ink props and add runtime-aware behavior.
+Primitives are thin wrappers around Ink components (`Box`, `Text`) that integrate with the assistant-ui runtime. They accept all standard Ink props and add runtime-aware behavior.
 
 Primitives use namespace imports, the same pattern as the web package (e.g. `ThreadPrimitive.Root`, `ComposerPrimitive.Input`).
 
@@ -396,7 +396,7 @@ Renders the quoted text from `s.composer.quote?.text`. Pass `children` to overri
 
 ### QuoteDismiss
 
-Pressable that clears the active quote by calling `aui.composer().setQuote(undefined)`.
+Pressable that clears the active quote by calling `aui.composer.setQuote(undefined)`.
 
 ```tsx
 <ComposerPrimitive.QuoteDismiss>
@@ -683,7 +683,7 @@ Container `Box` for an attachment. Forwards all `Box` props.
 
 ### Remove
 
-`Pressable` that calls `aui.attachment().remove()` when activated (Enter while focused). Disabled when not focused or when the `disabled` prop is set.
+`Pressable` that calls `aui.attachment.remove()` when activated (Enter while focused). Disabled when not focused or when the `disabled` prop is set.
 
 | Prop | Type | Description |
 |------|------|-------------|
@@ -725,7 +725,7 @@ Renders the queue item's prompt with Ink `<Text>`. Pass `children` to override t
 
 ### Remove
 
-Pressable that removes the queue item by calling `aui.queueItem().remove()`.
+Pressable that removes the queue item by calling `aui.queueItem.remove()`.
 
 ```tsx
 <QueueItemPrimitive.Remove>
@@ -742,7 +742,7 @@ Remaining props are forwarded to the underlying `Pressable` (Ink `Box` props).
 
 ### Steer
 
-Pressable that promotes the queue item to run next by calling `aui.queueItem().steer()`.
+Pressable that promotes the queue item to run next by calling `aui.queueItem.steer()`.
 
 ```tsx
 <QueueItemPrimitive.Steer>
@@ -765,10 +765,17 @@ import { ActionBarPrimitive } from "@assistant-ui/react-ink";
 
 ### Copy
 
-Pressable that copies the message content. Supports function-as-children for copy state feedback.
+Pressable that copies the message content. Pass a platform clipboard writer through `copyToClipboard`. Supports function-as-children for copy state feedback.
+
+<InstallCommand npm={["clipboardy"]} />
 
 ```tsx
-<ActionBarPrimitive.Copy copiedDuration={3000}>
+import clipboard from "clipboardy";
+
+<ActionBarPrimitive.Copy
+  copiedDuration={3000}
+  copyToClipboard={clipboard.write}
+>
   {({ isCopied }) => <Text>{isCopied ? "[Copied!]" : "[Copy]"}</Text>}
 </ActionBarPrimitive.Copy>
 ```
@@ -776,7 +783,7 @@ Pressable that copies the message content. Supports function-as-children for cop
 | Prop | Type | Description |
 |------|------|-------------|
 | `copiedDuration` | `number` | Duration in ms to show "copied" state (default: 3000) |
-| `copyToClipboard` | `(text: string) => void` | Custom clipboard function |
+| `copyToClipboard` | `(text: string) => void \| Promise<void>` | Platform clipboard writer |
 
 ### Edit
 
@@ -1215,3 +1222,37 @@ Container `Box` for the status bar. Forwards all `Box` props; pass `gap` to spac
   <StatusBarPrimitive.Latency />
 </StatusBarPrimitive.Root>
 ```
+
+## TextInput
+
+```tsx
+import { TextInput } from "@assistant-ui/react-ink";
+```
+
+Store-free, controlled single/multi-line text field. Ink ships no native text input, so this is the terminal equivalent of the DOM `<textarea>` or React Native's `<TextInput>` — the editing engine (buffer, grapheme-aware cursor, and the full emacs/arrow keymap) without any runtime or composer coupling. `ComposerPrimitive.Input` is a thin adapter that wraps `TextInput` and binds it to the composer store; reach for `TextInput` directly when you need an editable field outside the thread composer (for example, editing a value before confirming an action).
+
+It is controlled on `value`/`onChange`, so an external owner can override the text at any time (the buffer absorbs the echo without thrashing the cursor). An owner may also transform the emitted text in `onChange` (uppercase, mask, reject); the buffer applies the corrected value while keeping the cursor at the edit position, snapped to a grapheme boundary. A replacement that does not respond to an edit (a programmatic set while idle) still places the cursor at the end:
+
+```tsx
+const [command, setCommand] = useState(approval.action.command);
+
+<TextInput
+  value={command}
+  onChange={setCommand}
+  submitOnEnter
+  onSubmit={(text) => runEdited(text)}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string` | Current text (controlled) |
+| `onChange` | `(text: string) => void` | Called with the next text whenever the buffer changes |
+| `onSubmit` | `(text: string) => void` | Called on Enter when `submitOnEnter` is set, with the text as displayed; owners that validate in `onChange` should validate again in `onSubmit` |
+| `submitOnEnter` | `boolean` | Whether Enter calls `onSubmit` (default: `false`) |
+| `placeholder` | `string` | Placeholder text when empty (default: `""`) |
+| `autoFocus` | `boolean` | Auto-focus on mount (default: `true`) |
+| `multiLine` | `boolean` | When true, Enter inserts a newline unless `submitOnEnter` is enabled |
+| `...rest` | `ComponentProps<typeof Box>` | Forwarded to the underlying Ink `Box` |
+
+Keyboard bindings, grapheme handling, and terminal-capability caveats are identical to [`ComposerPrimitive.Input`](#input).

package/.docs/raw/docs/integrations/auth/better-auth.mdx

@@ -22,7 +22,7 @@ Three integration points:
 
 1. **Auth handlers** mounted at `/api/auth/[...all]/route.ts` via `toNextJsHandler(auth)`.
 2. **API routes** read the session server-side with `auth.api.getSession({ headers: await headers() })`.
-3. **Reload-on-auth** uses better-auth's React client to detect sign-in and trigger `aui.threads().reload()`.
+3. **Reload-on-auth** uses better-auth's React client to detect sign-in and trigger `aui.threads.reload()`.
 
 `session.user.id` is exposed on the session object directly, so route handlers can scope queries against it.
 
@@ -136,7 +136,7 @@ export function ReloadOnAuth() {
   const aui = useAui();
   const { data: session, isPending } = authClient.useSession();
   useEffect(() => {
-    if (!isPending && session) aui.threads().reload();
+    if (!isPending && session) aui.threads.reload();
   }, [isPending, session?.user?.id]);
   return null;
 }

package/.docs/raw/docs/integrations/auth/clerk.mdx

@@ -102,7 +102,7 @@ const rows = await db
 
 ### Reload threads after async auth
 
-The first render of `<MyProvider>` may run before Clerk resolves the user on the client. Drop a small effect inside `<AssistantRuntimeProvider>` that calls `aui.threads().reload()` once the user is loaded:
+The first render of `<MyProvider>` may run before Clerk resolves the user on the client. Drop a small effect inside `<AssistantRuntimeProvider>` that calls `aui.threads.reload()` once the user is loaded:
 
 ```tsx title="app/components/ReloadOnAuth.tsx"
 "use client";
@@ -115,7 +115,7 @@ export function ReloadOnAuth() {
   const aui = useAui();
   const { isLoaded, isSignedIn, user } = useUser();
   useEffect(() => {
-    if (isLoaded && isSignedIn) aui.threads().reload();
+    if (isLoaded && isSignedIn) aui.threads.reload();
   }, [isLoaded, isSignedIn, user?.id]);
   return null;
 }

package/.docs/raw/docs/integrations/auth/next-auth.mdx

@@ -18,7 +18,7 @@ Three places auth touches the integration:
 
 1. **API routes** (`/api/chat`, `/api/threads/*`) call `auth()` server-side, return 401 if no session, then scope DB queries by `session.user.id`.
 2. **`RemoteThreadListAdapter`** does nothing auth-specific; the cookie travels with the `fetch` calls automatically (same origin).
-3. **Reload-on-auth**: if the session resolves after the initial render, call `aui.threads().reload()` so the list re-fetches with the new identity.
+3. **Reload-on-auth**: if the session resolves after the initial render, call `aui.threads.reload()` so the list re-fetches with the new identity.
 
 ## Setup
 
@@ -113,7 +113,7 @@ Apply the same pattern to `POST`, `PATCH`, and `DELETE` handlers. Always verify
 
 ### Reload threads after async auth
 
-The first render of `<MyProvider>` may run before `auth()` resolves on the client. The thread list will be empty until the user refreshes. Drop a small effect into the layout to call `aui.threads().reload()` once the session resolves.
+The first render of `<MyProvider>` may run before `auth()` resolves on the client. The thread list will be empty until the user refreshes. Drop a small effect into the layout to call `aui.threads.reload()` once the session resolves.
 
 `useSession` requires `<SessionProvider>` higher in the tree. Wrap your root layout's client subtree once:
 
@@ -140,7 +140,7 @@ export function ReloadOnAuth() {
   const aui = useAui();
   const { status, data } = useSession();
   useEffect(() => {
-    if (status === "authenticated") aui.threads().reload();
+    if (status === "authenticated") aui.threads.reload();
   }, [status, data?.user?.id]);
   return null;
 }

package/.docs/raw/docs/integrations/frameworks/ai-sdk.mdx

@@ -8,7 +8,7 @@ import { VercelIcon } from "@/components/icons/vercel";
 [Vercel AI SDK](https://ai-sdk.dev/) is the most common framework people pair with assistant-ui. The full setup, attachments, persistence, tool-call patterns, and version notes are documented under [runtimes/ai-sdk](/docs/runtimes/ai-sdk/overview); this page is the entry point in the integrations tree for discoverability and architecture context.
 
 <Callout type="info">
-If you arrived here looking to wire up your first chat: jump to [AI SDK v6 quickstart](/docs/runtimes/ai-sdk/v6). This page is a high-level pointer.
+If you arrived here looking to wire up your first chat: jump to [AI SDK v7 quickstart](/docs/runtimes/ai-sdk/v7). This page is a high-level pointer.
 </Callout>
 
 ## Where it slots in
@@ -27,14 +27,20 @@ flowchart LR
 
 ## Pick a version
 
-Three versions of `ai` are supported. New projects should pick **v6**; v5 and v4 are documented for migration and existing apps that haven't upgraded.
+Four versions of `ai` are supported. New projects should pick **v7**; v6, v5, and v4 are documented for migration and existing apps that haven't upgraded.
 
 <Cards>
   <Card
     icon={<VercelIcon width={20} height={20} />}
-    title="AI SDK v6 (current)"
+    title="AI SDK v7 (current)"
+    description="Requires ai@^7 and @ai-sdk/react@^4. Async convertToModelMessages, tool inputSchema, toUIMessageStreamResponse."
+    href="/docs/runtimes/ai-sdk/v7"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="AI SDK v6 (legacy)"
     description="Requires ai@^6 and @ai-sdk/react@^3. Async convertToModelMessages, tool inputSchema, toUIMessageStreamResponse."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v6-legacy"
   />
   <Card
     icon={<VercelIcon width={20} height={20} />}

package/.docs/raw/docs/integrations/frameworks/cloudflare-agents/overview.mdx

@@ -9,14 +9,14 @@ import { VercelIcon } from "@/components/icons/vercel";
 [Cloudflare Agents](https://developers.cloudflare.com/agents/) is Cloudflare's framework for stateful AI agents that run on Durable Objects at the edge. Each agent owns its own SQLite-backed message history, exposes a WebSocket channel for low-latency streaming, and can call tools (server-side or client-side).
 
 <Callout type="info">
-This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-cloudflare-agents` package. `@cloudflare/ai-chat`'s `useAgentChat` returns a structural extension of the AI SDK's `useChat`, so the existing [AI SDK runtime](/docs/runtimes/ai-sdk/v6) consumes it directly.
+This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-cloudflare-agents` package. `@cloudflare/ai-chat`'s `useAgentChat` returns a structural extension of the AI SDK's `useChat`, so the existing [AI SDK runtime](/docs/runtimes/ai-sdk/v7) consumes it directly.
 </Callout>
 
 ## Architecture
 
 Cloudflare Agents handles the server half: a Durable Object subclasses `AIChatAgent` from `@cloudflare/ai-chat`, owns the message history, and streams responses back over a WebSocket. `@cloudflare/ai-chat/react`'s `useAgentChat` hook wraps that WebSocket and exposes the same `messages`, `sendMessage`, `regenerate`, `status`, `stop`, `setMessages`, `addToolOutput` surface that the AI SDK's `useChat` does, plus a few Cloudflare-specific extras (`clearHistory`, `isServerStreaming`, `isToolContinuation`).
 
-assistant-ui handles the client half. `useAISDKRuntime` from [`@assistant-ui/react-ai-sdk`](/docs/runtimes/ai-sdk/v6) reads exactly those AI SDK methods off whatever you pass in, so feeding it `useAgentChat`'s return value yields a fully-featured runtime: streaming, tool calling, edit, reload, history import and export, attachments, suggestions.
+assistant-ui handles the client half. `useAISDKRuntime` from [`@assistant-ui/react-ai-sdk`](/docs/runtimes/ai-sdk/v7) reads exactly those AI SDK methods off whatever you pass in, so feeding it `useAgentChat`'s return value yields a fully-featured runtime: streaming, tool calling, edit, reload, history import and export, attachments, suggestions.
 
 Shared adapters (attachments, speech, feedback, history) work the same way as described in [adapters](/docs/runtimes/concepts/adapters). Multi-thread support needs a [custom thread list](/docs/runtimes/concepts/threads) wired around `useAISDKRuntime`; [AssistantCloud](/docs/cloud) integrates via `useChatRuntime` (which constructs its own `useChat` internally) and is not compatible with the `useAgentChat` wiring shown here.
 
@@ -277,6 +277,6 @@ Destructure these alongside `chat` and pass them into your UI directly; they don
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

package/.docs/raw/docs/integrations/frameworks/mastra/full-stack.mdx

@@ -183,6 +183,6 @@ Open `http://localhost:3000`, send a message like *"What can I make with eggs an
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

package/.docs/raw/docs/integrations/frameworks/mastra/overview.mdx

@@ -9,7 +9,7 @@ import { VercelIcon } from "@/components/icons/vercel";
 [Mastra](https://mastra.ai/) is an open-source TypeScript agent framework. It provides primitives for AI applications: agents with memory and tool calling, deterministic LLM workflows, RAG, model routing, workflow graphs, and automated evals.
 
 <Callout type="info">
-This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-mastra` package. You wire up Mastra through the standard [AI SDK runtime](/docs/runtimes/ai-sdk/v6) by routing your API endpoint through Mastra's agent stream.
+This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-mastra` package. You wire up Mastra through the standard [AI SDK runtime](/docs/runtimes/ai-sdk/v7) by routing your API endpoint through Mastra's agent stream.
 </Callout>
 
 ## Pick a pattern
@@ -19,7 +19,7 @@ This is an integration guide, not a runtime adapter. assistant-ui does not ship
 | [Full-stack](/docs/integrations/frameworks/mastra/full-stack) | One Next.js app: API routes call Mastra in-process. Simpler deployment, single repo. |
 | [Separate server](/docs/integrations/frameworks/mastra/separate-server) | Mastra runs as its own service; the Next.js frontend hits its API. Independent scaling, clearer separation of concerns. |
 
-Both use the same client-side `useChatRuntime` from [`@assistant-ui/react-ai-sdk`](/docs/runtimes/ai-sdk/v6). The only difference is where the Mastra agent lives.
+Both use the same client-side `useChatRuntime` from [`@assistant-ui/react-ai-sdk`](/docs/runtimes/ai-sdk/v7). The only difference is where the Mastra agent lives.
 
 ## Architecture
 
@@ -52,6 +52,6 @@ Shared adapters (attachments, speech, feedback, history) work the same way descr
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

package/.docs/raw/docs/integrations/frameworks/mastra/separate-server.mdx

@@ -196,6 +196,6 @@ Open `http://localhost:3000`, send a message, and confirm:
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that handles the client side of this integration."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

package/.docs/raw/docs/integrations/gateways/index.mdx

@@ -8,7 +8,7 @@ import { VercelIcon } from "@/components/icons/vercel";
 
 LLM gateways sit between your route handler and the upstream provider. They give you a single endpoint that fronts many providers, plus features like multi-provider fallback, prompt caching, and BYOK (bring-your-own-key) flows. Most are OpenAI API-compatible, so the integration is a `baseURL` swap on `createOpenAI` from `@ai-sdk/openai`.
 
-For pure observability (proxy that logs every call) see [Helicone](/docs/integrations/observability/helicone). The gateways here overlap in spirit but are positioned around routing rather than logging.
+For pure observability (proxy that logs every call) see [Helicone](/docs/integrations/observability/helicone). The gateways here overlap in spirit but are positioned around routing rather than logging. For local personal projects there is also a keyless option in the same `baseURL`-swap shape: a local OAuth proxy billed to your ChatGPT subscription; see [ChatGPT Subscription](/docs/guides/chatgpt-subscription).
 
 ## Compare
 
@@ -157,6 +157,6 @@ When to pick: self-host requirement, BYOK metering for end-users, or unified bil
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that ferries gateway responses to the chat UI."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

package/.docs/raw/docs/integrations/observability/helicone.mdx

@@ -124,6 +124,6 @@ If nothing appears, check the request in your network tab. The host should be `o
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The most common pairing: AI SDK route handler proxied through Helicone."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

package/.docs/raw/docs/integrations/observability/langfuse.mdx

@@ -156,6 +156,6 @@ If nothing appears, check the server logs for OTel errors and confirm `LANGFUSE_
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that emits the telemetry Langfuse consumes."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

package/.docs/raw/docs/integrations/observability/langsmith.mdx

@@ -35,7 +35,7 @@ LANGSMITH_API_KEY=lsv2_pt_...
 LANGSMITH_PROJECT=assistant-ui
 ```
 
-`LANGSMITH_PROJECT` controls which project receives traces; the default project applies if you omit it. See LangSmith's [environment variable reference](https://docs.langchain.com/langsmith/how_to_environment_variables) for the full list.
+`LANGSMITH_PROJECT` controls which project receives traces; the default project applies if you omit it. See LangSmith's [project configuration guide](https://docs.langchain.com/langsmith/log-traces-to-project) for details.
 
 </Step>
 <Step>
@@ -146,6 +146,6 @@ Send a message. The trace should appear in your LangSmith project within seconds
     icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that ferries traces from the route to the chat UI."
-    href="/docs/runtimes/ai-sdk/v6"
+    href="/docs/runtimes/ai-sdk/v7"
   />
 </Cards>

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

@@ -305,7 +305,7 @@ export const threadListAdapter: RemoteThreadListAdapter = {
         async append() {},
         withFormat: (fmt) => ({
           async load() {
-            const { remoteId } = aui.threadListItem().getState();
+            const { remoteId } = aui.threadListItem.getState();
             if (!remoteId) return { messages: [] };
             const rows = await fetch(
               `/api/threads/${remoteId}/messages`,
@@ -322,7 +322,7 @@ export const threadListAdapter: RemoteThreadListAdapter = {
             };
           },
           async append(item) {
-            const { remoteId } = await aui.threadListItem().initialize();
+            const { remoteId } = await aui.threadListItem.initialize();
             await fetch(`/api/threads/${remoteId}/messages`, {
               method: "POST",
               body: JSON.stringify({
@@ -422,7 +422,7 @@ export const threadListAdapter: RemoteThreadListAdapter = {
         async append() {},
         withFormat: (fmt) => ({
           async load() {
-            const { remoteId } = aui.threadListItem().getState();
+            const { remoteId } = aui.threadListItem.getState();
             if (!remoteId) return { messages: [] };
             const rows = await fetch(
               `${API_URL}/threads/${remoteId}/messages`,
@@ -439,7 +439,7 @@ export const threadListAdapter: RemoteThreadListAdapter = {
             };
           },
           async append(item) {
-            const { remoteId } = await aui.threadListItem().initialize();
+            const { remoteId } = await aui.threadListItem.initialize();
             await fetch(`${API_URL}/threads/${remoteId}/messages`, {
               method: "POST",
               body: JSON.stringify({
@@ -541,7 +541,7 @@ export const threadListAdapter: RemoteThreadListAdapter = {
         async append() {},
         withFormat: (fmt) => ({
           async load() {
-            const { remoteId } = aui.threadListItem().getState();
+            const { remoteId } = aui.threadListItem.getState();
             if (!remoteId) return { messages: [] };
             const rows = await fetch(
               `${API_URL}/threads/${remoteId}/messages`,
@@ -558,7 +558,7 @@ export const threadListAdapter: RemoteThreadListAdapter = {
             };
           },
           async append(item) {
-            const { remoteId } = await aui.threadListItem().initialize();
+            const { remoteId } = await aui.threadListItem.initialize();
             await fetch(`${API_URL}/threads/${remoteId}/messages`, {
               method: "POST",
               body: JSON.stringify({
@@ -592,6 +592,32 @@ The top-level `load`/`append` on the history adapter are required by the type bu
 </Step>
 <Step>
 
+### Support in-place updates (optional)
+
+The optional `update(item, localMessageId)` method on the object returned from `withFormat` lets the runtime rewrite an already-persisted message in place. It receives the same `{ parentId, message }` item shape as `append`, plus the id of the row to rewrite.
+
+The runtime calls `update` after a run for persisted messages whose content changed, to finalize assistant messages persisted early while waiting for tool call approval, and to refresh run timing metadata.
+
+`update` is opt-in. When it is absent, messages paused for tool approval are not persisted until the run reaches a terminal status, so a page refresh during the pause loses the pending approval state. Implementing `update` enables early persistence.
+
+```tsx title="runtime/thread-adapter.tsx"
+async update(item, localMessageId) {
+  const { remoteId } = await aui.threadListItem.initialize();
+  await fetch(`${API_URL}/threads/${remoteId}/messages/${localMessageId}`, {
+    method: "PATCH",
+    body: JSON.stringify({
+      format: fmt.format,
+      content: fmt.encode(item),
+    }),
+  });
+},
+```
+
+The backend needs a matching update route keyed by message id, mirroring the append route from the earlier step.
+
+</Step>
+<Step>
+
 ### Mount the runtime
 
 Wrap the app in a `useRemoteThreadListRuntime` that delegates per-thread runtime to `useChatRuntime`:
@@ -694,7 +720,7 @@ Send a message in a fresh thread. Check the database:
 
 - The `threads` table has a new row with the current `userId`.
 - The `messages` table has at least two rows (user + assistant) for that thread.
-- `format` matches what `fmt.format` wrote (`"ai-sdk/v6"` for AI SDK v6) and `content` is the encoded `UIMessage` (a `role` plus `parts`), not a placeholder blob.
+- `format` matches what `fmt.format` wrote (`"ai-sdk/v6"`) and `content` is the encoded `UIMessage` (a `role` plus `parts`), not a placeholder blob. The format string names the stored `UIMessage` shape, not the installed AI SDK major; it stays `"ai-sdk/v6"` on AI SDK v7 and must never be renamed, or previously stored history stops matching.
 - Reload the page; the thread list and the messages survive.
 
 </Step>
@@ -702,9 +728,10 @@ 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.
-- **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).
+- **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.
+- **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.
 - **`unstable_Provider` synchronous-children rule.** The Provider must render `children` on first commit; do not gate them behind suspense, loading state, or `useEffect`. Load data inside an always-rendered child.
 
 ## Related

package/.docs/raw/docs/migrations/index.mdx

@@ -0,0 +1,50 @@
+---
+title: Migration Guides
+description: Upgrade assistant-ui versions and migrate deprecated APIs and integrations.
+---
+
+Use these guides when upgrading assistant-ui or moving from APIs that have been deprecated or replaced.
+
+## Version upgrades
+
+<Cards>
+  <Card title="Migration to v0.14" href="/docs/migrations/v0-14">
+    Replace APIs removed after v0.11 and v0.12, and migrate primitive
+    `components` props to children render functions.
+  </Card>
+  <Card title="Migration to v0.12" href="/docs/migrations/v0-12">
+    Move from individual context hooks to the unified state API.
+  </Card>
+  <Card title="Migration to v0.11" href="/docs/migrations/v0-11">
+    Update code affected by the `ContentPart` to `MessagePart` rename.
+  </Card>
+</Cards>
+
+## APIs and integrations
+
+<Cards>
+  <Card title="Migrating Tools to Toolkits" href="/docs/migrations/toolkit-tools">
+    Move legacy tool and tool UI registrations to the toolkit API.
+  </Card>
+  <Card
+    title="Migrating to react-langgraph v0.7"
+    href="/docs/migrations/react-langgraph-v0-7"
+  >
+    Upgrade to the simplified LangGraph integration API.
+  </Card>
+  <Card
+    title="Using old React versions"
+    href="/docs/migrations/react-compatibility"
+  >
+    Review compatibility notes for React 18 and React 19.
+  </Card>
+</Cards>
+
+## Stability
+
+<Cards>
+  <Card title="Deprecation Policy" href="/docs/migrations/deprecation-policy">
+    Review stability guarantees and deprecation timelines for assistant-ui
+    features.
+  </Card>
+</Cards>

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

@@ -32,7 +32,7 @@ const WeatherTool = makeAssistantTool({
 });
 
 export function App() {
-  const runtime = useChatRuntime({ api: "/api/chat" });
+  const runtime = useChatRuntime();
 
   return (
     <AssistantRuntimeProvider runtime={runtime}>
@@ -80,7 +80,7 @@ import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import toolkit from "./toolkit";
 
 export function App() {
-  const runtime = useChatRuntime({ api: "/api/chat" });
+  const runtime = useChatRuntime();
   const aui = useAui({
     tools: Tools({ toolkit }),
   });
@@ -93,6 +93,8 @@ export function App() {
 }
 ```
 
+`useChatRuntime()` targets `/api/chat` by default. To point at a different endpoint or customize requests, see [Custom transport](/docs/runtimes/ai-sdk/v7#custom-transport).
+
 ## Mechanical Steps
 
 1. Create a `Toolkit` object.