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

package/.docs/raw/docs/(reference)/api-reference/integrations/eve.mdx

@@ -36,15 +36,36 @@ Converts an assistant-ui append message into the message payload accepted by
 Eve's `send` API.
 
 ```ts
-const getEveMessageContent: (message: AppendMessage) => NonNullable<SendTurnPayload["message"]>;
+const getEveMessageContent: (message: AppendMessage) => EveMessageContent;
 ```
 
 ### toEveInputResponse
 
 Converts an assistant-ui tool approval response into an Eve input response.
 
+When `inputRequest` is known, every returned response carries either an
+option the request declares or a free-form answer. A literal option match
+wins, then the `"approve"` / `"cancel"` option the response's boolean decision
+names, then the response's `reason` text when the request takes a free-form
+answer (`display: "text"`, `allowFreeform`, or no options at all, and never
+`display: "confirmation"`) and the response is not a refusal.
+A one-argument call, or a part with no request, still forwards a caller
+`optionId` as it always has, including ids the request never declared.
+
+A response the known request cannot record as the answer it asked for throws
+instead of being submitted, because eve resolves a request the moment any
+response for it arrives, and an empty one is recorded as an answer with no
+content. Not sending leaves the request pending, so the caller can retry or
+the user can answer it as an ordinary message.
+
+With no request to map against — a one-argument call, or a part carrying no
+`toolMetadata.eve.inputRequest` — the response maps as it always has, to the
+literal `"approve"` / `"cancel"` option every eve approval declares. Guessing
+a display mode is what this mapper stopped doing; an unknown request is not
+a guess about one.
+
 ```ts
-const toEveInputResponse: (response: RespondToToolApprovalOptions) => InputResponse;
+const toEveInputResponse: (response: RespondToToolApprovalOptions, inputRequest?: EveMessageInputRequest) => InputResponse;
 ```
 
 ### useEveAgentRuntime
@@ -56,4 +77,42 @@ session, supports cancellation, and maps Eve input requests to assistant-ui
 tool approval UI.
 
 <ParametersTable {...eve_useEveAgentRuntime} />
+
+### useEveError
+
+Read the last Eve session error from the runtime extras.
+
+```ts
+const useEveError: () => Error | undefined;
+```
+
+### useEveEvents
+
+Read the authoritative Eve server event stream from the runtime extras.
+Defaults to an empty array outside an Eve runtime.
+
+```ts
+const useEveEvents: () => EveRuntimeExtras["events"];
+```
+
+### useEveReset
+
+Returns a function that resets the Eve session: aborts any in-flight turn,
+recreates the owned session, and clears events and projected data. Pending
+staged messages and tool execution state are discarded. Safe to render
+outside an Eve runtime; invoking the returned function there throws.
+
+```ts
+const useEveReset: () => () => void;
+```
+
+### useEveSession
+
+Read the current Eve session cursor from the runtime extras. Persist it to
+resume the session later via `initialSession`. `undefined` when no session
+exists yet or outside an Eve runtime.
+
+```ts
+const useEveSession: () => EveRuntimeExtras["session"] | undefined;
+```
 {/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/integrations/index.mdx

@@ -7,14 +7,14 @@ description: Package-level APIs for connecting assistant-ui React to the Vercel
 {/* The page list is generated from exported APIs; edit only the manual prose slot. */}
 
 {/* api-manual:start */}
-Integration packages connect assistant-ui to adjacent React and AI ecosystems. Use this section when you need the exact hooks, options, and helper exports for a package such as `@assistant-ui/react-ai-sdk`, `@assistant-ui/react-data-stream`, `@assistant-ui/cloud-ai-sdk`, or `@assistant-ui/eve`.
+Integration packages connect assistant-ui to adjacent React and AI ecosystems. Use this section when you need the exact hooks, options, and helper exports for a package such as `@assistant-ui/ai-sdk`, `@assistant-ui/react-data-stream`, `@assistant-ui/cloud-ai-sdk`, or `@assistant-ui/eve`.
 {/* api-manual:end */}
 
 ## Pages
 
 <Cards>
-  <Card title={"@assistant-ui/react-ai-sdk"} href={"/docs/api-reference/integrations/react-ai-sdk"}>
-    {"Vercel AI SDK runtime hooks, chat transports, and message conversion utilities for assistant-ui React applications."}
+  <Card title={"@assistant-ui/ai-sdk"} href={"/docs/api-reference/integrations/ai-sdk"}>
+    {"Vercel AI SDK runtime hooks, chat transports, and message conversion utilities for assistant-ui applications."}
   </Card>
   <Card title={"@assistant-ui/react-data-stream"} href={"/docs/api-reference/integrations/react-data-stream"}>
     {"Data stream runtime hook and message conversion utilities for custom assistant-ui streaming backends."}

package/.docs/raw/docs/(reference)/api-reference/overview.mdx

@@ -46,8 +46,8 @@ The React API reference is organized by how you build with assistant-ui:
   <Card title="Adapters" href="/docs/api-reference/adapters/model">
     Runtime extension points for attachments, persistence, feedback, speech, dictation, and suggestions.
   </Card>
-  <Card title="Integrations" href="/docs/api-reference/integrations/react-ai-sdk">
-    Package-level APIs for integrations such as `@assistant-ui/react-ai-sdk` and `@assistant-ui/cloud-ai-sdk`.
+  <Card title="Integrations" href="/docs/api-reference/integrations/ai-sdk">
+    Package-level APIs for integrations such as `@assistant-ui/ai-sdk` and `@assistant-ui/cloud-ai-sdk`.
   </Card>
   <Card title="Runtime State" href="/docs/api-reference/runtimes/assistant-runtime">
     Runtime action and state shapes used by `useAui` and `useAuiState`.

package/.docs/raw/docs/(reference)/api-reference/primitives/composer.mdx

@@ -336,11 +336,11 @@ Only takes effect when `submitMode` resolves to `"enter"` (the default); `"ctrlE
 )}
 
 ```tsx
-<ComposerPrimitive.If dictation>
+<AuiIf condition={(s) => s.composer.dictation != null}>
   <div className="dictation-preview">
     <ComposerPrimitive.DictationTranscript />
   </div>
-</ComposerPrimitive.If>
+</AuiIf>
 ```
 
 <ParametersTable {...ComposerPrimitiveDictationTranscriptProps} />
@@ -616,4 +616,22 @@ Only takes effect when `submitMode` resolves to `"enter"` (the default); `"ctrlE
 {ComposerPrimitiveDocs.Unstable_RegisteredTrigger?.props && (
   <ParametersTable type={ComposerPrimitiveDocs.Unstable_RegisteredTrigger?.element} parameters={ComposerPrimitiveDocs.Unstable_RegisteredTrigger.props} />
 )}
+
+### Unstable_TriggerMatcher
+
+{ComposerPrimitiveDocs.Unstable_TriggerMatcher?.deprecated && (
+  <Callout type="warn">
+    <strong>Deprecated.</strong> {ComposerPrimitiveDocs.Unstable_TriggerMatcher.deprecated}
+  </Callout>
+)}
+
+{ComposerPrimitiveDocs.Unstable_TriggerMatcher?.description}
+
+{ComposerPrimitiveDocs.Unstable_TriggerMatcher?.element && (
+  <p>This primitive renders a <code>{`<${ComposerPrimitiveDocs.Unstable_TriggerMatcher?.element}>`}</code> element unless <code>asChild</code> is set.</p>
+)}
+
+{ComposerPrimitiveDocs.Unstable_TriggerMatcher?.props && (
+  <ParametersTable type={ComposerPrimitiveDocs.Unstable_TriggerMatcher?.element} parameters={ComposerPrimitiveDocs.Unstable_TriggerMatcher.props} />
+)}
 {/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/tools/interactables.mdx

@@ -114,7 +114,7 @@ Reads the interactable snapshots stamped on a message's
 `metadata.custom.interactables`, or `undefined` if none. This is the read
 half of the snapshot channel — integrations use it to surface interactable
 state to the model (see `unstable_injectInteractableContext` in
-`@assistant-ui/react-ai-sdk` for the AI SDK implementation).
+`@assistant-ui/ai-sdk` for the AI SDK implementation).
 
 <ParametersTable {...unstable_getInteractableSnapshots} />
 

package/.docs/raw/docs/(reference)/api-reference/tools/status.mdx

@@ -57,6 +57,6 @@ function ToolDuration() {
 ```
 
 ```ts
-const useToolCallElapsed: () => number;
+const useToolCallElapsed: () => number | undefined;
 ```
 {/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/transport/frame.mdx

@@ -51,7 +51,7 @@ function MyComponent() {
 
   useAssistantFrameHost({
     iframeRef,
-    targetOrigin: "https://trusted-domain.com", // optional
+    targetOrigin: "https://trusted-domain.com",
   });
 
   return <iframe ref={iframeRef} src="..." />;

package/.docs/raw/docs/(reference)/api-reference/utilities/miscellaneous.mdx

@@ -3,7 +3,7 @@ title: Utilities
 description: Miscellaneous @assistant-ui/react utilities for custom rendering, composition, and advanced assistant UI behavior.
 ---
 
-import { AssistantCloud, AuiConfig, ChainOfThoughtClient, DevToolsHooks, InMemoryThreadList, SingleThreadList, Suggestions, useSmooth } from "@/generated/typeDocs";
+import { AssistantCloud, AuiConfig, ChainOfThoughtClient, DevToolsHooks, InMemoryThreadList, MessageNotSentError, RemoteThreadList, SingleThreadList, Suggestions, useSmooth } from "@/generated/typeDocs";
 
 {/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
 {/* Do not edit manually. */}
@@ -59,6 +59,34 @@ const createMessageQueue: (driver: MessageQueueDriver) => MessageQueueController
 
 <ParametersTable {...InMemoryThreadList} />
 
+### isMessageNotSentError
+
+```ts
+const isMessageNotSentError: (error: unknown) => error is MessageNotSentError;
+```
+
+### MessageNotSentError
+
+Rejection reason for a send that never reached the backend, so nothing ran
+and nothing is recoverable from the thread. A runtime adapter throws it from
+`onNew` to hand the message back to the thread composer, which restores the
+draft it cleared at dispatch time when nothing has claimed the composer
+since. An edit composer closes at dispatch, so a rejected edit is not
+restored.
+
+<ParametersTable {...MessageNotSentError} />
+
+### RemoteThreadList
+
+`AuiConfig` `threads` entry backed by a `RemoteThreadListAdapter`. Thread
+bodies are born from the `thread` factory inside the client tree, so any
+`AssistantClient` host can run a remote or cloud list. Per-thread history
+and attachments come from `unstable_useAdapters`. `useRemoteThreadListRuntime`
+uses the same hook when `unstable_Provider` is omitted. Key the factory
+with `withKey` so history reloads when the visible thread changes.
+
+<ParametersTable {...RemoteThreadList} />
+
 ### SingleThreadList
 
 <ParametersTable {...SingleThreadList} />
@@ -85,6 +113,9 @@ Takes the current part state and a `smooth` argument: `false` disables,
 `true` uses the default rate, and a SmoothOptions object tunes
 the reveal. Returns the part state with `text` replaced by the revealed
 prefix and `status` reporting `running` until the reveal catches up.
+If the source settles before any character has been revealed, the text
+is committed immediately so a missed animation frame cannot leave an
+empty bubble.
 
 The reveal auto-disables under `prefers-reduced-motion: reduce`,
 committing the full text immediately; this takes precedence over an

package/.docs/raw/docs/(reference)/api-reference/voice/session.mdx

@@ -31,7 +31,7 @@ const useVoiceControls: () => { connect: () => void; disconnect: () => void; mut
 ### useVoiceState
 
 ```ts
-const useVoiceState: () => VoiceSessionState;
+const useVoiceState: () => VoiceSessionState | undefined;
 ```
 
 ### useVoiceVolume

package/.docs/raw/docs/cloud/ai-sdk-assistant-ui.mdx

@@ -19,7 +19,7 @@ This integration provides:
 
 ## How It Works
 
-The `useChatRuntime` hook from `@assistant-ui/react-ai-sdk` wraps AI SDK's `useChat` and adds cloud persistence via the `cloud` parameter. The runtime automatically:
+The `useChatRuntime` hook from `@assistant-ui/ai-sdk` wraps AI SDK's `useChat` and adds cloud persistence via the `cloud` parameter. `AISDKThreads({ cloud })` is the store-entry list for `AuiConfig` / `createAssistantClient` hosts. That host mounts only the visible thread, so a switch cancels an in-flight run. The runtime automatically:
 
 1. Creates a cloud thread on the first user message
 2. Persists messages as they complete streaming
@@ -102,17 +102,17 @@ Install the required packages:
 <PlatformTabs>
 <Tab value="React">
 
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk"]} />
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/ai-sdk"]} />
 
 </Tab>
 <Tab value="React Native">
 
-<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-ai-sdk", "assistant-cloud"]} />
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/ai-sdk", "assistant-cloud"]} />
 
 </Tab>
 <Tab value="React Ink">
 
-<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-ai-sdk", "assistant-cloud", "ink", "react"]} />
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/ai-sdk", "assistant-cloud", "ink", "react"]} />
 
 </Tab>
 </PlatformTabs>
@@ -133,7 +133,7 @@ Create a client-side AssistantCloud instance and integrate it with your AI SDK r
 
 import { useMemo } from "react";
 import { AssistantCloud, AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 import { ThreadList } from "@/components/assistant-ui/thread-list";
 import { Thread } from "@/components/assistant-ui/thread";
 
@@ -174,7 +174,7 @@ import {
   ThreadListPrimitive,
 } from "@assistant-ui/react-native";
 import { AssistantCloud } from "assistant-cloud";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 import { Thread } from "@/components/assistant-ui/thread";
 
 async function getAssistantToken() {
@@ -236,7 +236,7 @@ import {
   ThreadListPrimitive,
 } from "@assistant-ui/react-ink";
 import { AssistantCloud } from "assistant-cloud";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 import { Thread } from "./components/thread.js";
 
 async function getAssistantToken() {
@@ -453,7 +453,7 @@ The React example above uses anonymous mode for quick demos. For production apps
 import { useMemo } from "react";
 import { useAuth } from "@clerk/nextjs";
 import { AssistantCloud } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 
 function Chat() {
   const { getToken } = useAuth();
@@ -474,7 +474,7 @@ function Chat() {
 ```tsx
 import { useMemo } from "react";
 import { AssistantCloud } from "assistant-cloud";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 
 async function getAssistantToken() {
   // Return a user token from your native auth provider.
@@ -498,7 +498,7 @@ function Chat() {
 ```tsx
 import { useMemo } from "react";
 import { AssistantCloud } from "assistant-cloud";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 
 async function getAssistantToken() {
   // Return a user token from your CLI auth flow.

package/.docs/raw/docs/cloud/ai-sdk.mdx

@@ -332,7 +332,7 @@ Plus all other properties from AI SDK's [`UseChatHelpers`](https://sdk.vercel.ai
 | Value | Type | Description |
 |-------|------|-------------|
 | `threads.cloud` | `AssistantCloud` | The cloud instance used for thread operations |
-| `threads.threads` | `CloudThread[]` | Active threads sorted by recency |
+| `threads.threads` | `CloudThread[]` | Threads sorted by recency; includes archived threads when supplied by `useThreads({ includeArchived: true })` |
 | `threads.threadId` | `string \| null` | Current thread ID (`null` for a new unsaved chat) |
 | `threads.selectThread` | `(id: string \| null) => void` | Switch threads or pass `null` for a new chat |
 | `threads.isLoading` | `boolean` | `true` during initial load or refresh |
@@ -355,6 +355,8 @@ const myThreads = useThreads({ cloud: myCloud });
 const { messages, sendMessage } = useCloudChat({ threads: myThreads });
 ```
 
+`useThreads` requests 20 threads per page and follows Cloud cursors until all matching threads are loaded. With `includeArchived`, active and archived pages load concurrently and the complete list is committed after both finish.
+
 **Parameters:**
 
 | Parameter | Type | Description |
@@ -378,7 +380,7 @@ The `useCloudChat` hook automatically reports run telemetry to Assistant Cloud a
 **Requires route configuration:**
 - `model_id` — The model used for the response
 - `input_tokens` / `output_tokens` — Token usage statistics
-- `reasoning_tokens` — Tokens used for chain-of-thought reasoning (e.g. GPT-5.4 Mini or GPT-5.5 models)
+- `reasoning_tokens` — Tokens used for chain-of-thought reasoning (e.g. GPT-5.6 Luna or other reasoning models)
 - `cached_input_tokens` — Input tokens served from the provider's prompt cache
 
 To capture model and usage data, configure the `messageMetadata` callback in your AI SDK route:

package/.docs/raw/docs/cloud/index.mdx

@@ -16,7 +16,7 @@ Assistant Cloud is a hosted service that adds thread management, message persist
 
 | Backend | Standalone Mode | With assistant-ui |
 |---------|----------------|-------------------|
-| AI SDK | [`useCloudChat`](/docs/cloud/ai-sdk) | [`useChatRuntime`](/docs/cloud/ai-sdk-assistant-ui) |
+| AI SDK | [`useCloudChat`](/docs/cloud/ai-sdk) | [`useChatRuntime`](/docs/cloud/ai-sdk-assistant-ui) / `AISDKThreads` |
 | LangGraph | — | [`useLangGraphRuntime`](/docs/cloud/langgraph) |
 | Custom | — | Local Runtime |
 

package/.docs/raw/docs/copilots/assistant-frame.mdx

@@ -29,7 +29,10 @@ import { z } from "zod";
 const registry = new ModelContextRegistry();
 
 // Expose the registry to the parent window
-AssistantFrameProvider.addModelContextProvider(registry);
+AssistantFrameProvider.addModelContextProvider(
+  registry,
+  "https://parent-app.com",
+);
 
 // Add tools that will be available to the parent assistant
 registry.addTool({
@@ -70,7 +73,7 @@ function ParentComponent() {
   // Connect to the iframe's model context
   useAssistantFrameHost({
     iframeRef,
-    targetOrigin: "https://trusted-iframe-domain.com", // optional for increased security
+    targetOrigin: "https://trusted-iframe-domain.com",
   });
 
   return (
@@ -160,9 +163,15 @@ analyticsRegistry.addTool({
 
 // Register both providers
 const unsubscribe1 =
-  AssistantFrameProvider.addModelContextProvider(catalogRegistry);
+  AssistantFrameProvider.addModelContextProvider(
+    catalogRegistry,
+    "https://parent-app.com",
+  );
 const unsubscribe2 =
-  AssistantFrameProvider.addModelContextProvider(analyticsRegistry);
+  AssistantFrameProvider.addModelContextProvider(
+    analyticsRegistry,
+    "https://parent-app.com",
+  );
 
 // Later, unsubscribe if needed
 unsubscribe1();
@@ -173,7 +182,7 @@ unsubscribe2();
 
 #### Origin Validation
 
-Both the provider and host can specify allowed origins for security:
+Both the provider and host validate message origins. They default to the current page's origin, so cross-origin frames must specify the exact trusted origin on both sides:
 
 ```tsx
 // In iframe - only accept messages from specific parent
@@ -222,10 +231,12 @@ Registers a model context provider to share with parent windows.
 ```tsx
 const unsubscribe = AssistantFrameProvider.addModelContextProvider(
   registry,
-  "https://parent-domain.com", // Optional origin restriction
+  "https://parent-domain.com",
 );
 ```
 
+When `targetOrigin` is omitted, the provider only communicates with `window.location.origin`. All providers in a frame share one origin policy. Registering an explicit origin tightens an existing wildcard policy, while registering two different explicit origins throws an error. Unsubscribing drops that registration's requirement. The wildcard value `*` is available as an explicit opt-in, but it should not be used for contexts that expose tools or sensitive instructions.
+
 ##### `dispose()`
 
 Cleans up all resources and removes all providers.
@@ -243,7 +254,7 @@ Class that connects to an iframe's model context providers.
 ```tsx
 const host = new AssistantFrameHost(
   iframeWindow,
-  targetOrigin? // Optional origin restriction
+  targetOrigin?, // Defaults to window.location.origin
 );
 ```
 
@@ -283,7 +294,7 @@ React hook that manages the lifecycle of an AssistantFrameHost.
 ```tsx
 useAssistantFrameHost({
   iframeRef: RefObject<HTMLIFrameElement>,
-  targetOrigin?: string,
+  targetOrigin?: string, // Defaults to window.location.origin
 });
 ```
 

package/.docs/raw/docs/guides/attachments.mdx

@@ -4,7 +4,7 @@ description: Let users attach images, PDFs, and other files to AI chat messages
 platforms: ["react"]
 ---
 
-import { AttachmentSample } from "@/components/docs/samples/attachment";
+import { AttachmentSample } from "@/components/pages/docs/samples/attachment";
 
 Enable users to attach files to their messages, enhancing conversations with images, documents, and other content.
 
@@ -44,7 +44,7 @@ This adds `/components/assistant-ui/attachment.tsx` to your project.
 For `useChatRuntime`, attachments work automatically without additional configuration:
 
 ```tsx title="/app/MyRuntimeProvider.tsx"
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 
 const runtime = useChatRuntime();
 ```
@@ -118,7 +118,7 @@ Build your own adapters for specialized file handling. Below are complete exampl
 
 ### Vision-Capable Image Adapter
 
-Send images to vision-capable LLMs like GPT-5.4, Claude Sonnet 4.6, or Gemini Pro Vision:
+Send images to vision-capable LLMs like GPT-5.6, Claude Sonnet 4.6, or Gemini Pro Vision:
 
 ```tsx
 import {
@@ -276,7 +276,7 @@ const MyModelAdapter: ChatModelAdapter = {
         msg.role === "user" &&
         msg.content.some((part) => part.type === "image")
       ) {
-        // Format for GPT-5.4 or similar vision models
+        // Format for GPT-5.6 or similar vision models
         return {
           role: "user",
           content: msg.content.map((part) => {

package/.docs/raw/docs/guides/branching.mdx

@@ -4,7 +4,7 @@ description: Edit messages or regenerate AI responses, then switch between alter
 platforms: ["react"]
 ---
 
-import { BranchingSample } from "@/components/docs/samples/branching";
+import { BranchingSample } from "@/components/pages/docs/samples/branching";
 
 Branching lets users navigate between alternative versions of a message. A new branch is created when:
 

package/.docs/raw/docs/guides/chatgpt-subscription.mdx

@@ -30,7 +30,7 @@ In your chat route, swap `@ai-sdk/openai` for the OAuth provider. Starting from
 
 ```ts title="/app/api/chat/route.ts" {10}
 import { createOpenAIOAuth } from "openai-oauth-provider";
-import { frontendTools } from "@assistant-ui/react-ai-sdk";
+import { frontendTools } from "@assistant-ui/ai-sdk";
 import {
   type JSONSchema7,
   streamText,

package/.docs/raw/docs/guides/context-api.mdx

@@ -519,34 +519,32 @@ The table below covers the most commonly used actions. For the full catalog, see
 
 ### Events vs State Observation
 
-`useAuiEvent` is the escape hatch for **transient occurrences that are not derivable from state**. State-derivable transitions (attachment list changing, run progress, thread switching) should be observed with `useAuiState`, not subscribed via events.
+Use `useAuiState` to render the current value of something; use `useAuiEvent` to react to the moment something happens. Both are supported: many events mark a transition you could also observe in state, and subscribing to the event is the intended way to run a side effect at that transition.
 
 The rule of thumb:
 
-1. Can you read the new value from state right now? → use `useAuiState`.
+1. Rendering a value? → use `useAuiState`.
 2. Are you the caller and want immediate feedback? → catch the rejection / read the return value.
-3. Did something happen that has no representation in state at all? → use `useAuiEvent`.
+3. Running a side effect when something happens? → use `useAuiEvent`.
 
-Most existing events are kept for backward compatibility but duplicate state. They are marked `@deprecated` in the type definitions; new code should follow the rule above.
-
-#### Currently Recommended (Truly Transient)
+#### Available Events
 
 | Event                         | When It Fires                                                                |
 | ----------------------------- | ---------------------------------------------------------------------------- |
-| `composer.attachmentAddError` | An `addAttachment()` call failed. Payload `reason` discriminates `no-adapter` / `not-accepted` / `adapter-error`. `no-adapter` and `not-accepted` are non-state-derivable. `adapter-error` is partially state-derivable: if the adapter produced any attachment before failing, the errored attachment also appears in `composer.attachments` with `status.reason === "error"`. The event additionally surfaces a human-readable `message` (and the underlying `Error` instance via the low-level `runtime.unstable_on("attachmentAddError")` API; `useAuiEvent` payloads omit it because raw `Error` objects are not store-serializable). |
+| `threads.selectionChanged`    | The main thread selection changed. Payload carries `threadId` (newly selected) and `previousThreadId`. Does not fire for the initially selected thread on mount. |
+| `thread.runStart` / `runEnd`  | A run started / ended on the thread (also visible as `isRunning` flipping)   |
+| `thread.initialize`           | The thread transitioned from new to initialized, before the first message is added |
 | `thread.modelContextUpdate`   | The model context provider notified a change. The model context lives in a provider, not in thread state, so this event has no state-derivable equivalent. |
+| `composer.send`               | The user sent the composer contents; `messageId` is set for edit-composer sends |
+| `composer.attachmentAdd`      | An attachment was added to the composer                                      |
+| `composer.attachmentAddError` | An `addAttachment()` call failed. Payload `reason` discriminates `no-adapter` / `not-accepted` / `adapter-error`. The event additionally surfaces a human-readable `message` (and the underlying `Error` instance via the low-level `runtime.unstable_on("attachmentAddError")` API; `useAuiEvent` payloads omit it because raw `Error` objects are not store-serializable). |
 
-#### Legacy (State-Derivable, Prefer `useAuiState`)
-
-These events fire at the same transition you can observe via state. They are kept for backward compatibility but new code should observe state instead.
+#### Deprecated Events
 
-| Legacy Event                                 | Observe Instead                                                |
-| -------------------------------------------- | -------------------------------------------------------------- |
-| `composer.send`                              | composer `text` clearing                                       |
-| `composer.attachmentAdd`                     | composer `attachments`                                         |
-| `thread.runStart` / `runEnd`                 | thread `isRunning` flipping to `true` / `false`                |
-| `thread.initialize`                          | thread `messages` becoming non-empty (or `isEmpty` flipping)   |
-| `threadListItem.switchedTo` / `switchedAway` | compare `s.threads.mainThreadId` against `s.threadListItem.id` |
+| Deprecated Event              | Use Instead                                                                  |
+| ----------------------------- | ---------------------------------------------------------------------------- |
+| `threadListItem.switchedTo`   | `threads.selectionChanged` — its `threadId` is the newly selected thread     |
+| `threadListItem.switchedAway` | `threads.selectionChanged` — its `previousThreadId` is the thread switched away from |
 
 ## Troubleshooting
 

package/.docs/raw/docs/guides/dictation.mdx

@@ -4,7 +4,7 @@ description: Add voice dictation to your AI chat composer with the Web Speech AP
 platforms: ["react"]
 ---
 
-import { DictationSample } from "@/components/docs/samples/dictation";
+import { DictationSample } from "@/components/pages/docs/samples/dictation";
 
 assistant-ui supports speech-to-text (dictation) via the `DictationAdapter` interface. Users speak into the microphone and transcribed text lands in the composer, either as interim preview or as committed final text.
 
@@ -283,7 +283,7 @@ This pattern records until the user stops dictation, then commits a single final
 
 ## Custom realtime providers
 
-You can implement `DictationAdapter` against any streaming STT service. [ElevenLabs Scribe](https://elevenlabs.io/docs/capabilities/speech-to-text) is one option for low-latency WebSocket transcription; scaffold a full example with:
+You can implement `DictationAdapter` against any streaming STT service. [ElevenLabs Scribe](https://elevenlabs.io/docs/overview/capabilities/speech-to-text) is one option for low-latency WebSocket transcription; scaffold a full example with:
 
 ```bash
 npx assistant-ui create my-app -e with-elevenlabs-scribe

package/.docs/raw/docs/guides/electron.mdx

@@ -38,7 +38,7 @@ import { AssistantRuntimeProvider } from "@assistant-ui/react";
 import {
   AssistantChatTransport,
   useChatRuntime,
-} from "@assistant-ui/react-ai-sdk";
+} from "@assistant-ui/ai-sdk";
 
 const transport = new AssistantChatTransport({
   api: "https://api.example.com/chat",

package/.docs/raw/docs/guides/latex.mdx

@@ -4,7 +4,7 @@ description: Render LaTeX math expressions in AI chat messages with KaTeX — dr
 platforms: ["react"]
 ---
 
-import { PackageManagerTabs } from "@/components/docs/fumadocs/install/package-manager-tabs";
+import { PackageManagerTabs } from "@/components/pages/docs/fumadocs/install/package-manager-tabs";
 
 Render LaTeX mathematical expressions in chat messages using KaTeX.
 

package/.docs/raw/docs/guides/mentions.mdx

@@ -82,6 +82,8 @@ const myAdapter: Unstable_TriggerAdapter = {
 
 The built-in `unstable_useLiveCompletionAdapter` wraps an async fetcher with debouncing, stale-request cancellation (results for an outdated query are dropped), and a single-entry cache. Its `search` returns the last results synchronously and schedules a debounced fetch when the query changes; when results arrive the returned `adapter` re-creates, which re-runs the popover lookup so the fresh items render. It also reports `isLoading`, which you pass to the popover to show a loading state.
 
+When the fetcher reads from an account- or workspace-specific source, pass that source ID as `cacheKey`. Changing the key clears cached results and cancels any pending result from the previous source.
+
 ```tsx
 import {
   unstable_useLiveCompletionAdapter,

package/.docs/raw/docs/guides/message-timing.mdx

@@ -100,7 +100,7 @@ Timing is tracked automatically on the client side by observing streaming state
 </Callout>
 
 ```tsx
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 
 const runtime = useChatRuntime();
 // useMessageTiming() works out of the box
@@ -174,14 +174,20 @@ const runtime = useLangGraphRuntime({ stream: myStream });
 // useMessageTiming() works out of the box
 ```
 
-### AG-UI (`useAgUiThreadRuntime`)
+### AG-UI (`useAgUiRuntime`)
 
 Timing is tracked automatically on the client side by the AG-UI run aggregator. Each emitted message includes timing metadata computed from stream chunk observations.
 
 ```tsx
-import { useAgUiThreadRuntime } from "@assistant-ui/react-ag-ui";
-
-const runtime = useAgUiThreadRuntime({ runtimeUrl: "..." });
+import { useMemo } from "react";
+import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";
+import { HttpAgent } from "@ag-ui/client";
+
+const agent = useMemo(
+  () => new HttpAgent({ url: "http://localhost:8000/agent" }),
+  [],
+);
+const runtime = useAgUiRuntime({ agent });
 // useMessageTiming() works out of the box
 ```