@assistant-ui/mcp-docs-server 0.1.39 → 0.2.1

package/.docs/raw/docs/runtimes/eve/quickstart.mdx

@@ -1,9 +1,9 @@
 ---
 title: Quickstart
-description: From-template and manual setup paths to a working Eve agent chat in assistant-ui.
+description: Template, Eve CLI, and manual setup paths to a working Eve agent chat in assistant-ui.
 ---
 
-Two paths to a running Eve-powered assistant-ui app. The template is fastest; the manual path is what you adapt when integrating into an existing Next.js project.
+Three paths to a running Eve-powered assistant-ui app. The template is fastest, `eve add` drops assistant-ui into an Eve app you already have, and the manual path is what you adapt when integrating into an existing Next.js project.
 
 ## From the template
 
@@ -45,6 +45,55 @@ Use Eve's terminal UI directly for command-line agent sessions.
 </Tab>
 </PlatformTabs>
 
+## With the Eve CLI
+
+For an Eve app that already exists, register the assistant-ui registry once and install the chat page from it:
+
+```sh
+eve registry add @assistant-ui=https://r.assistant-ui.com/{name}.json
+eve add @assistant-ui/eve-chat --overwrite
+```
+
+`eve registry add` records the namespace in your `package.json`. `eve add` then installs `@assistant-ui/react` and `@assistant-ui/eve`, writes `app/page.tsx`, and writes the thread component together with everything it imports into `components/assistant-ui` and `components/ui`. It expects an Eve app that carries the Next.js Web Chat scaffold, because the installed files import `@/lib/utils` through the `@/*` alias that `eve init --channel-web-nextjs` sets up.
+
+`--overwrite` is global rather than per file. It is what lets the item replace the scaffold's own `app/page.tsx`, and it also replaces any `components/assistant-ui` or `components/ui` file already in the project, including `avatar`, `button`, `collapsible`, `dialog`, and `tooltip`, so install on a clean tree and read the diff before keeping it. A plain `eve add` skips every pre-existing file instead, which leaves `app/page.tsx` untouched. Inspect an item before installing it with `eve registry view @assistant-ui/eve-chat`, and browse the rest of the registry with `eve registry list --registry @assistant-ui`.
+
+That namespace serves the Radix flavor, which matches the shadcn components in Eve's Next.js scaffold. Point it at `https://r.assistant-ui.com/base/{name}.json` instead for a Base UI project.
+
+The Eve CLI writes registry files without editing CSS, so add the styles the reasoning and tool components animate with to `app/globals.css` yourself:
+
+```css title="app/globals.css"
+@import "tw-shimmer";
+
+@custom-variant data-open (&:where([data-state="open"], [data-open]:not([data-open="false"])));
+@custom-variant data-closed (&:where([data-state="closed"], [data-closed]:not([data-closed="false"])));
+
+@theme inline {
+  @keyframes collapsible-down {
+    from {
+      height: 0;
+    }
+    to {
+      height: var(
+        --radix-collapsible-content-height,
+        var(--collapsible-panel-height, auto)
+      );
+    }
+  }
+  @keyframes collapsible-up {
+    from {
+      height: var(
+        --radix-collapsible-content-height,
+        var(--collapsible-panel-height, auto)
+      );
+    }
+    to {
+      height: 0;
+    }
+  }
+}
+```
+
 ## Manual setup in an existing app
 
 <Steps>

package/.docs/raw/docs/runtimes/google-adk/hooks.mdx

@@ -389,9 +389,9 @@ Register the renderer with a backend toolkit entry inside `AssistantRuntimeProvi
 ```tsx
 import {
   AssistantRuntimeProvider,
+  AuiConfig,
   defineToolkit,
   Tools,
-  useAui,
 } from "@assistant-ui/react";
 import {
   createAdkStream,
@@ -410,10 +410,9 @@ function App() {
   const runtime = useAdkRuntime({
     stream: createAdkStream({ api: "/api/chat" }),
   });
-  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>
   );
@@ -426,9 +425,9 @@ function App() {
 ```tsx
 import {
   AssistantRuntimeProvider,
+  AuiConfig,
   defineToolkit,
   Tools,
-  useAui,
 } from "@assistant-ui/react-native";
 import {
   createAdkStream,
@@ -450,10 +449,9 @@ function App() {
   const runtime = useAdkRuntime({
     stream: createAdkStream({ api: `${API_URL}/api/chat` }),
   });
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
       <View style={{ flex: 1 }}>
         <Thread />
       </View>
@@ -468,9 +466,9 @@ function App() {
 ```tsx
 import {
   AssistantRuntimeProvider,
+  AuiConfig,
   defineToolkit,
   Tools,
-  useAui,
 } from "@assistant-ui/react-ink";
 import {
   createAdkStream,
@@ -490,10 +488,9 @@ function App() {
   const runtime = useAdkRuntime({
     stream: createAdkStream({ api: "http://localhost:3000/api/chat" }),
   });
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
       <Box flexDirection="column">
         <Thread />
       </Box>

package/.docs/raw/docs/runtimes/langchain.mdx

@@ -5,7 +5,7 @@ description: Use LangChain's useStream hook with a React chat UI through assista
 
 import { LangGraphIcon } from "@/components/icons/langgraph";
 
-`@assistant-ui/react-langchain` wraps [`useStream`](https://docs.langchain.com/oss/javascript/langgraph-sdk/react-stream) from `@langchain/react` and exposes it as an assistant-ui runtime. It targets the same backend as [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph/overview) (LangGraph Cloud) but at a higher level, delegating stream plumbing to the upstream hook.
+`@assistant-ui/react-langchain` wraps [`useStream`](https://reference.langchain.com/javascript/langchain-react/use-stream) from `@langchain/react` and exposes it as an assistant-ui runtime. It targets the same backend as [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph/overview) (LangGraph Cloud) but at a higher level, delegating stream plumbing to the upstream hook.
 
 ## When to use it
 
@@ -32,7 +32,7 @@ Shared adapters (attachments, speech, feedback) work the same way described in [
 
 ## Requirements
 
-- A LangGraph Cloud API server (locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith)).
+- A LangGraph Cloud API server (locally via [LangGraph Studio](https://docs.langchain.com/langsmith/quick-start-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith)).
 - The graph state must include a `messages` key with LangChain-alike messages, or pass a custom `messagesKey`.
 
 ## Quickstart

package/.docs/raw/docs/runtimes/langgraph/overview.mdx

@@ -13,7 +13,7 @@ description: Build a chat UI for LangGraph agents in React with assistant-ui —
 
 Pick the LangGraph runtime when:
 
-- You have (or want) a LangGraph Cloud server, locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith).
+- You have (or want) a LangGraph Cloud server, locally via [LangGraph Studio](https://docs.langchain.com/langsmith/quick-start-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith).
 - Your graph state has a `messages` key with LangChain-alike messages.
 - You want generative UI (`ui_message`), per-message metadata, subgraph events, or checkpoint-based message editing.
 

package/.docs/raw/docs/runtimes/langgraph/streaming.mdx

@@ -108,7 +108,7 @@ See [Generative UI](/docs/runtimes/langgraph/generative-ui) for full setup: enab
 
 ## Queueing messages during a run
 
-Set `unstable_enableMessageQueue` to keep the composer usable while a run is streaming. A message sent during a run is held in `composer.queue` and sent once the run settles; steering a queued message runs it next.
+Set `unstable_enableMessageQueue` to keep the composer usable while a run is streaming. A message sent during a queued run steers by default — it lands in the steer lane, ahead of previously queued items; `send({ steer: false })` queues a follow-up behind them instead. Pending items are held in `composer.queue` and drain once the run settles.
 
 ```tsx
 const runtime = useLangGraphRuntime({

package/.docs/raw/docs/runtimes/langgraph/tutorial/part-2.mdx

@@ -94,7 +94,7 @@ This simply displays the tool name and arguments passed to it, but not the resul
 
 import { Thread } from "@/components/assistant-ui/thread";
 import { PriceSnapshotToolUI } from "@/components/tools/price-snapshot/PriceSnapshotTool";
-import { AuiProvider, defineToolkit, Tools, useAui } from "@assistant-ui/react";
+import { AuiConfig, AuiProvider, defineToolkit, Tools, useAui } from "@assistant-ui/react";
 
 const toolkit = defineToolkit({
   price_snapshot: {
@@ -104,10 +104,10 @@ const toolkit = defineToolkit({
 });
 
 export default function Home() {
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AuiProvider value={aui}>
+    <AuiProvider extends={aui} config={config}>
       <Thread />
     </AuiProvider>
   );
@@ -334,10 +334,10 @@ const toolkit = defineToolkit({
 });
 
 export default function Home() {
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AuiProvider value={aui}>
+    <AuiProvider extends={aui} config={config}>
       <Thread />
     </AuiProvider>
   );

package/.docs/raw/docs/runtimes/langgraph/tutorial/part-3.mdx

@@ -212,7 +212,7 @@ export function TransactionConfirmationPending(props: TransactionConfirmation) {
 import { Thread } from "@/components/assistant-ui/thread";
 import { PriceSnapshotToolUI } from "@/components/tools/price-snapshot/PriceSnapshotTool";
 import { PurchaseStockToolUI } from "@/components/tools/purchase-stock/PurchaseStockTool";
-import { AuiProvider, defineToolkit, Tools, useAui } from "@assistant-ui/react";
+import { AuiConfig, AuiProvider, defineToolkit, Tools, useAui } from "@assistant-ui/react";
 
 const toolkit = defineToolkit({
   price_snapshot: {
@@ -226,10 +226,10 @@ const toolkit = defineToolkit({
 });
 
 export default function Home() {
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AuiProvider value={aui}>
+    <AuiProvider extends={aui} config={config}>
       <Thread />
     </AuiProvider>
   );

package/.docs/raw/docs/runtimes/opencode/hooks.mdx

@@ -9,7 +9,9 @@ OpenCode-specific React hooks for interacting with the running session. All hook
 
 ## Permissions
 
-OpenCode pauses tool execution to ask the user for permission (e.g. running shell commands, writing files). `useOpenCodePermissions` returns the pending permission requests and a reply function:
+OpenCode pauses tool execution to ask the user for permission (e.g. running shell commands, writing files). Permissions linked to a tool call are projected into assistant-ui's standard tool approval contract, so the default `ToolFallback` renders working **Allow**, **Always allow**, and **Deny** actions without a custom permission component. The always option only appears when OpenCode offers patterns to persist.
+
+`useOpenCodePermissions` remains available for custom tool renderers and permission requests that are not linked to a tool call. It returns the pending permission requests and a reply function:
 
 ```tsx
 import { useOpenCodePermissions } from "@assistant-ui/react-opencode";
@@ -110,6 +112,7 @@ The returned `OpenCodeThreadState` includes:
 
 - `sessionId`, `session`, `sessionStatus`, `loadState`, `runState`
 - `messageOrder`, `messagesById`, `pendingUserMessages`
+- `childSessionsById` (OpenCode `task` child-session projections keyed by session ID)
 - `interactions.permissions` (pending + resolved), `interactions.questions` (pending + answered + rejected)
 - `unhandledEvents`, `sync` timestamps
 

package/.docs/raw/docs/runtimes/opencode/overview.mdx

@@ -28,6 +28,16 @@ If your backend is not OpenCode-based, see [picking a runtime](/docs/runtimes/pi
 - A running [OpenCode](https://opencode.ai/) server (defaults to `http://localhost:4096`).
 - React 18 or 19.
 
+## Sub-agent conversations
+
+OpenCode `task` tool calls expose their child session through tool metadata. The runtime loads those child sessions, keeps them synchronized from the same OpenCode event stream, and projects their transcripts into `ToolCallMessagePart.messages`. Parallel and recursively nested tasks are supported.
+
+Loading is eager, not keyed to what a renderer displays. Once a thread is subscribed, every `task` part in its transcript fetches its child session, and each child does the same for its own nested tasks, so a long session with many task calls fetches every sub-agent transcript whether or not any of them is expanded. Each child session is fetched once and then kept current from the event stream, so re-subscribing a thread does not refetch it.
+
+A `task` part carries `messages` only once its child session has loaded. While the child is still loading, the part projects as an ordinary tool call, so an empty `messages` array always means the sub-agent produced nothing rather than that its transcript is still in flight.
+
+Use assistant-ui's [`MessagePartPrimitive.Messages`](/docs/tools/multi-agent) inside a `task` tool renderer to display the child conversation. Nested conversations are read-only and inherit the parent thread's tool renderers.
+
 ## Install
 
 <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-opencode", "@opencode-ai/sdk"]} />

package/.docs/raw/docs/tools/a2ui.mdx

@@ -0,0 +1,107 @@
+---
+title: A2UI over AG-UI
+description: Render A2UI surfaces from AG-UI activity snapshots as generative UI, using the community a2ui-surface convention.
+platforms: ["react"]
+---
+
+[A2UI](https://a2ui.org/) is a declarative generative UI protocol: the agent streams surface operations (create a surface, upsert components, update a data model) and the host renders them from a pre-approved component catalog, with no code over the wire. The AG-UI ecosystem carries A2UI as `ACTIVITY_SNAPSHOT` events with `activityType: "a2ui-surface"` and the operations under `content.a2ui_operations`; this is the convention emitted by [`@ag-ui/a2ui-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2ui-middleware).
+
+`useAgUiRuntime` consumes these snapshots natively. Each surface becomes one tool-call part with `toolCallId` `a2ui:<surfaceId>` and `toolName` `"present"`, whose args are the converted generative UI spec, so surfaces render through the same path as the [`present` frontend tool](/docs/tools/generative-ui). Snapshots with any other `activityType` are ignored, and the MCP Apps activity path is unaffected.
+
+## Wire contract
+
+A backend paints or updates a surface by emitting an activity snapshot on the AG-UI stream:
+
+```json
+{
+  "type": "ACTIVITY_SNAPSHOT",
+  "messageId": "a2ui-surface-call_1",
+  "activityType": "a2ui-surface",
+  "replace": true,
+  "content": {
+    "a2ui_operations": [
+      { "version": "v0.9", "createSurface": { "surfaceId": "s1" } },
+      {
+        "version": "v0.9",
+        "updateComponents": {
+          "surfaceId": "s1",
+          "components": [
+            { "id": "root", "component": "Card", "title": "Order", "children": ["total"] },
+            { "id": "total", "component": "Text", "text": { "path": "/total" } }
+          ]
+        }
+      },
+      {
+        "version": "v0.9",
+        "updateDataModel": { "surfaceId": "s1", "path": "/", "contents": { "total": "$42" } }
+      }
+    ]
+  }
+}
+```
+
+- A snapshot with `replace: true` (the schema default) rebuilds that `messageId`'s surface state from the operations it carries. `replace: false` means the snapshot is ignored when that `messageId` has already been seen, matching the AG-UI event spec. The middleware always emits `replace: true`.
+- Surfaces are keyed by the `surfaceId` inside the operations, not by `messageId`. Multiple snapshots that share a `messageId` update their surfaces in place, and the synthesized part keeps its `toolCallId`, so the rendered surface updates without duplicating parts.
+- Component trees use the A2UI adjacency-list model: nodes reference children by id, the root node has id `root`, and props of shape `{ "path": "/x/y" }` are JSON Pointer bindings resolved against the surface data model. Both v0.9 and v1.0 operation payloads are accepted, including the v1.0 inline `components` and `dataModel` on `createSurface`.
+- Lifecycle snapshots that carry a `status` (such as `"building"`) but no `a2ui_operations` are tolerated and produce no part until operations arrive. A `deleteSurface` operation removes the surface's part.
+- The `a2ui:` tool-call id prefix is reserved for synthesized surface parts: they are client-side render artifacts and are excluded from the history sent back to the agent, so genuine agent tool calls must not use ids starting with `a2ui:`.
+
+## Quick start
+
+Register the `present` frontend tool from `@assistant-ui/react-generative-ui`; incoming surfaces then render with the default vocabulary:
+
+```tsx
+import {
+  JSONGenerativeUI,
+  defaultGenerativeUILibrary,
+} from "@assistant-ui/react-generative-ui";
+
+const generative = new JSONGenerativeUI({
+  library: defaultGenerativeUILibrary,
+});
+
+const toolkit = {
+  present: generative.present({ display: "standalone" }),
+};
+```
+
+Pass the toolkit to your assistant as on the [Generative UI](/docs/tools/generative-ui) page; no other configuration is needed on `useAgUiRuntime`.
+
+## Actions
+
+`Button` nodes dispatch `$action` objects with type `"a2ui:action"` through the action registry. Wire the registry to `useAgUiSendA2uiAction` inside a component; the hook returns a stable function, so the toolkit can be memoized on it:
+
+```tsx
+import { useMemo } from "react";
+import { useAgUiSendA2uiAction } from "@assistant-ui/react-ag-ui";
+import {
+  JSONGenerativeUI,
+  createActionRegistry,
+  defaultGenerativeUILibrary,
+} from "@assistant-ui/react-generative-ui";
+
+function useA2uiToolkit() {
+  const sendA2uiAction = useAgUiSendA2uiAction();
+  return useMemo(() => {
+    const generative = new JSONGenerativeUI({
+      library: defaultGenerativeUILibrary,
+      actions: createActionRegistry({
+        "a2ui:action": ({ payload }) => sendA2uiAction(payload),
+      }),
+    });
+    return { present: generative.present({ display: "standalone" }) };
+  }, [sendA2uiAction]);
+}
+```
+
+Sending an action triggers a run with no new user message, and the agent receives it as `forwardedProps.a2uiAction.userAction`, the convention `@ag-ui/a2ui-middleware` consumes. The action rides exactly one run; the `type` field is stripped and a `timestamp` is added when absent.
+
+The middleware turns the action into a synthetic `log_a2ui_event` tool-call pair that is never declared in `input.tools`; a backend that validates tool calls against the declared tool list will reject it.
+
+## Component mapping
+
+The converter maps the A2UI basic catalog onto the default generative UI vocabulary: `Text` becomes `Markdown` (`h1` to `h6` variants become `Header`, `caption` becomes `Caption`), `Column` becomes `Col`, `TextField` becomes `Input` (the control name is derived from the last segment of its binding path), `CheckBox` becomes `Checkbox`, and `Image`, `Row`, `Card`, `Divider`, `Button` map one to one. A node with template children expands into a `ListView` over the bound list. `Button` actions become `$action` objects with type `"a2ui:action"` carrying the action name, `surfaceId`, and `sourceComponentId`, which is how your action registry receives them. Unknown components and operations are skipped with a debug warning, and conversion is bounded (depth 32, 100 template items, 5000 nodes) so a malformed stream cannot hang the client.
+
+## Limitations
+
+- The upstream middleware currently emits v0.9 operation payloads; the renderer accepts v0.9 and v1.0 shapes.

package/.docs/raw/docs/tools/backend.mdx

@@ -42,7 +42,7 @@ export async function POST(req: Request) {
   const { messages, system, tools } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-nano"),
+    model: openai("gpt-5.6-luna"),
     system,
     messages: await convertToModelMessages(messages),
     tools: await aiToolkit.tools({ frontend: tools }),
@@ -79,7 +79,7 @@ export async function POST(req: Request) {
   const { messages, tools } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-nano"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
     tools: {
       ...frontendTools(tools ?? {}),

package/.docs/raw/docs/tools/defining-tools.mdx

@@ -115,21 +115,23 @@ The inner `"use client"` inside `execute` marks this as a **frontend** tool —
 
 ### Register the toolkit
 
-Import the toolkit in your runtime provider and pass it to `useAui` via `Tools`:
+Import the toolkit in your runtime provider and pass it to `config` via `Tools`:
 
 ```tsx title="app/MyRuntimeProvider.tsx"
 "use client";
 
-import { AssistantRuntimeProvider, Tools, useAui } from "@assistant-ui/react";
+import { AssistantRuntimeProvider, AuiConfig, Tools } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import toolkit from "./toolkit";
 
 export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
   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}
+    >
       {children}
     </AssistantRuntimeProvider>
   );
@@ -157,7 +159,7 @@ export async function POST(req: Request) {
   const { messages, tools } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-nano"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
     tools: await aiToolkit.tools({ frontend: tools }),
   });
@@ -368,7 +370,7 @@ export const toolkit = defineToolkit({
 });
 ```
 
-Register it exactly like a generative toolkit: `useAui({ tools: Tools({ toolkit }) })`. The key must match the tool name your backend or MCP server publishes. Render-only entries upload no schema and run no browser code — they only attach UI to matching tool-call message parts.
+Register it exactly like a generative toolkit: hoist `const config = AuiConfig({ tools: Tools({ toolkit }) })` in the component body and pass `config={config}`. The key must match the tool name your backend or MCP server publishes. Render-only entries upload no schema and run no browser code — they only attach UI to matching tool-call message parts.
 
 <Callout type="warn">
   This `{ type: "backend", render }` shape is **plain-toolkit only**. Inside a

package/.docs/raw/docs/tools/dynamic-tools.mdx

@@ -43,6 +43,7 @@ The component that owns the state registers the toolkit, then renders a small nu
 
 ```tsx title="app/TaskBoard.tsx"
 import {
+  AuiConfig,
   AuiProvider,
   Tools,
   useAui,
@@ -54,10 +55,10 @@ 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>
@@ -102,7 +103,8 @@ The override supplies **only** the `execute`; the description, parameters, and `
 <Callout type="info">
   Keep the override keys stable after mount, and let only one mounted provider
   define a given tool name at a time. The null-returning overrides component
-  re-binds the executor whenever the setter changes, without re-running `useAui`.
+  re-binds the executor whenever the setter changes, without remounting the
+  provider.
 </Callout>
 
 ## When to reach for this vs. Interactables

package/.docs/raw/docs/tools/interactables-legacy.mdx

@@ -33,18 +33,20 @@ Common use cases:
 ### 1. Register the Interactables scope
 
 ```tsx
-import { useAui, Interactables, AssistantRuntimeProvider } from "@assistant-ui/react";
+import { AuiConfig, Interactables, AssistantRuntimeProvider } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
 function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
   const runtime = useChatRuntime();
-
-  const aui = useAui({
+  const config = AuiConfig({
     interactables: Interactables(), // [!code ++]
   });
 
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+    <AssistantRuntimeProvider
+      runtime={runtime}
+      config={config}
+    >
       {children}
     </AssistantRuntimeProvider>
   );
@@ -54,7 +56,7 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 <Callout type="idea">
   The legacy `interactables: Interactables()` scope and the new
   `unstable_interactables: unstable_Interactables()` scope are mutually
-  exclusive. Mount only one interactables API in a single `useAui` provider.
+  exclusive. Mount only one interactables API in a single provider config.
 </Callout>
 
 ### 2. Create an interactable
@@ -266,10 +268,10 @@ const [state, { setState, setSelected, isPending, error, flush }] = useInteracta
 
 ### `Interactables`
 
-The scope resource that manages all interactables. Register it via `useAui`:
+The scope resource that manages all interactables. Register it via your provider's `config`:
 
 ```tsx
-const aui = useAui({
+AuiConfig({
   interactables: Interactables(),
 });
 ```
@@ -291,14 +293,25 @@ By default, interactable state is in-memory and lost on page refresh. You can ad
 
 ```tsx
 import { useEffect } from "react";
-import { useAui, Interactables } from "@assistant-ui/react";
+import { AuiConfig, AuiProvider, Interactables, useAui } from "@assistant-ui/react";
 
 function MyRuntimeProvider({ children }) {
-  const aui = useAui({ interactables: Interactables() });
+  const aui = useAui();
+  const config = AuiConfig({ interactables: Interactables() });
+  return (
+    <AuiProvider extends={aui} config={config}>
+      <PersistenceSetup />
+      {children}
+    </AuiProvider>
+  );
+}
+
+function PersistenceSetup() {
+  const aui = useAui();
 
   useEffect(() => {
     // Set up persistence adapter
-    aui.interactables().setPersistenceAdapter({
+    aui.interactables.setPersistenceAdapter({
       save: async (state) => {
         localStorage.setItem("interactables", JSON.stringify(state));
       },
@@ -307,11 +320,11 @@ function MyRuntimeProvider({ children }) {
     // Restore saved state on mount
     const saved = localStorage.getItem("interactables");
     if (saved) {
-      aui.interactables().importState(JSON.parse(saved));
+      aui.interactables.importState(JSON.parse(saved));
     }
   }, [aui]);
 
-  return /* ... */;
+  return null;
 }
 ```
 
@@ -334,10 +347,10 @@ State changes are automatically debounced (500ms) before saving. When a componen
 For custom persistence strategies, use `exportState` and `importState` directly:
 
 ```tsx
-const snapshot = aui.interactables().exportState();
+const snapshot = aui.interactables.exportState();
 // => { "note-1": { name: "note", state: { title: "Hello" } }, ... }
 
-aui.interactables().importState(snapshot);
+aui.interactables.importState(snapshot);
 // Imported state is picked up when components next register
 ```
 
@@ -346,7 +359,7 @@ aui.interactables().importState(snapshot);
 You can use `Interactables` alongside `Tools`:
 
 ```tsx
-const aui = useAui({
+AuiConfig({
   tools: Tools({ toolkit: myToolkit }),
   interactables: Interactables(),
 });