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

package/.docs/raw/docs/(docs)/index.mdx

@@ -1,88 +1,21 @@
 ---
 title: Documentation
-description: Build production-grade AI chat experiences in React with assistant-ui — components, runtimes, and primitives for ChatGPT-style UIs, copilots, and agents.
+description: Components, runtimes, and primitives for building AI chat interfaces in React, React Native, and the terminal.
 platforms: ["react"]
 ---
 
-import { PanelsTopLeft, Database, Terminal } from "lucide-react";
+<Quickstart />
 
-assistant-ui helps you create beautiful, enterprise-grade AI chat interfaces in minutes. Whether you're building a ChatGPT clone, a customer support chatbot, an AI assistant, or a complex multi-agent application, assistant-ui provides the frontend primitive components and state management layers to focus on what makes your application unique.
+## One library, any interface
 
-<Callout type="tip">
-  Already using the AI SDK with your own UI? Add [cloud persistence with just one hook](/docs/cloud/ai-sdk), no UI library required.
-</Callout>
+<DemoShowcase />
 
-## Key Features
+## Bring your own backend
 
-<Cards>
-  <Card icon={<PanelsTopLeft className="text-purple-300" />} title="Instant Chat UI">
-    Pre-built beautiful, customizable chat interfaces out of the box. Easy to quickly iterate on your idea.
-  </Card>
+A runtime connects these components to your AI backend. Pick the one that matches your stack.
 
-  <Card icon={<PanelsTopLeft className="text-blue-300" />} title="Chat State Management">
-    Powerful state management for chat interactions, optimized for streaming responses and efficient rendering.
-  </Card>
+<RuntimeGrid />
 
-  <Card icon={<Database className="text-green-300" />} title="High Performance">
-    Optimized for speed and efficiency with minimal bundle size, ensuring your AI chat interfaces remain responsive.
-  </Card>
+## Everything else
 
-  <Card icon={<Terminal className="text-orange-300" />} title="Framework Agnostic">
-    Easily integrate with any backend system, whether using Vercel AI SDK, direct LLM connections, or custom solutions. Works with any React-based framework.
-  </Card>
-</Cards>
-
-## Quick Try
-
-The fastest way to get started:
-
-```sh
-npx assistant-ui@latest create
-```
-
-This creates a new project with everything configured. Or choose a template:
-
-```sh
-# Minimal starter
-npx assistant-ui@latest create -t minimal
-
-# Assistant Cloud - with persistence and thread management
-npx assistant-ui@latest create -t cloud
-
-# Assistant Cloud + Clerk authentication
-npx assistant-ui@latest create -t cloud-clerk
-
-# LangGraph starter (react-langchain adapter)
-npx assistant-ui@latest create -t langchain
-
-# MCP starter template
-npx assistant-ui@latest create -t mcp
-
-# Eve agent starter template
-npx assistant-ui@latest create -t eve
-```
-
-## What's Next?
-
-<Cards>
-  <Card
-    title="Installation"
-    description="Full installation guide with CLI and manual setup options"
-    href="/docs/installation"
-  />
-  <Card
-    title="Agent Skills"
-    description="Use AI tools to build with assistant-ui faster"
-    href="/docs/llm"
-  />
-  <Card
-    title="Pick a Runtime"
-    description="Choose the right runtime for your needs"
-    href="/docs/runtimes/pick-a-runtime"
-  />
-  <Card
-    title="Examples"
-    description="Explore full implementations and demos"
-    href="/examples"
-  />
-</Cards>
+<QuickLinks />

package/.docs/raw/docs/(docs)/installation.mdx

@@ -22,28 +22,14 @@ The fastest way to get started with assistant-ui.
 npx assistant-ui@latest create
 ```
 
-Or choose a template:
+Or start from a template:
 
 ```sh
-# Minimal starter
-npx assistant-ui@latest create -t minimal
-
-# Assistant Cloud - with persistence and thread management
 npx assistant-ui@latest create -t cloud
-
-# Assistant Cloud + Clerk authentication
-npx assistant-ui@latest create -t cloud-clerk
-
-# LangGraph starter (react-langchain adapter)
-npx assistant-ui@latest create -t langchain
-
-# MCP starter template
-npx assistant-ui@latest create -t mcp
-
-# Eve agent starter template
-npx assistant-ui@latest create -t eve
 ```
 
+The [CLI reference](/docs/cli#create) lists every template and example, and what each one includes.
+
 **Add to an existing project:**
 
 ```sh
@@ -154,7 +140,7 @@ export const maxDuration = 30;
 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: frontendTools(tools),
@@ -481,8 +467,8 @@ export default function MyApp() {
   />
   <Card
     title="Generative UI"
-    description="Create rich UI components for tool executions"
-    href="/docs/tools/tool-ui"
+    description="Let the model compose UI from a component vocabulary you ship"
+    href="/docs/tools/generative-ui"
   />
   <Card
     title="Add Persistence"

package/.docs/raw/docs/(reference)/api-reference/context-providers/assistant-runtime-provider.mdx

@@ -48,15 +48,35 @@ primitives built on it. Components rendered outside an `AuiProvider`
 receive a default client whose scope accessors throw on use, so
 missing-provider mistakes surface at the point of use.
 
+`config` is required and must be built with [AuiConfig](/docs/api-reference/utilities/miscellaneous#auiconfig). At the top
+level, `config` alone creates this subtree's own client. Under a parent
+provider, `extends` is mandatory: pass `extends={aui}` to extend the parent
+client or `extends={null}` to isolate from it (enforced with a dev error).
+Configs are identity-insensitive — a fresh object per render is safe.
+A config whose scopes are all Derived keeps its scope set fixed
+at mount (dev-enforced); configs with a root scope, and empty configs,
+may grow and shrink scopes across renders. `ref` receives the resulting
+client after mount.
+
 When mounting a runtime built with one of the runtime hooks, use
 [AssistantRuntimeProvider](/docs/api-reference/context-providers/assistant-runtime-provider#assistantruntimeprovider) — it installs an `AuiProvider`
 internally — rather than wiring `AuiProvider` yourself.
 
 ```tsx
-function ScopedAssistant({ children, scopes }) {
-  const aui = useAui(scopes);
-
-  return <AuiProvider value={aui}>{children}</AuiProvider>;
+function MessageScope({ index, children }) {
+  const aui = useAui();
+  const config = AuiConfig({
+    message: Derived({
+      source: "thread",
+      query: { index },
+      get: (aui) => aui.thread.message({ index }),
+    }),
+  });
+  return (
+    <AuiProvider extends={aui} config={config}>
+      {children}
+    </AuiProvider>
+  );
 }
 ```
 

package/.docs/raw/docs/(reference)/api-reference/generative-ui/slack.mdx

@@ -63,7 +63,11 @@ The blocks and non-fatal warnings produced by Slack conversion.
 
 ### SlackConversionWarning
 
-A non-fatal downgrade reported during Slack conversion.
+A non-fatal note reported during Slack conversion.
+
+`clamped` removed content to fit a limit, `dropped` discarded a node or one
+of its props and may leave a placeholder note behind, and `fallback` emitted
+the node in a different form than requested.
 
 <ParametersTable {...SlackConversionWarning} />
 

package/.docs/raw/docs/(reference)/api-reference/generative-ui/teams.mdx

@@ -50,14 +50,21 @@ The attachments and non-fatal warnings produced by [toTeamsAttachments](/docs/ap
 
 ### TeamsConversionWarning
 
-A non-fatal downgrade reported during Teams conversion.
+A non-fatal note reported during Teams conversion.
+
+`clamped` removed content to fit a limit, `dropped` discarded a node or one
+of its props and may leave a placeholder note behind, and `fallback`
+emitted the node in a different form than requested. `advisory` changed
+nothing at all and notes content Teams may still render poorly or refuse,
+such as a payload over the byte budget or a `Row` past the recommended
+column count.
 
 <ParametersTable {...TeamsConversionWarning} />
 
 ### toAdaptiveCard
 
 Converts a generative-ui tree into a Microsoft Teams Adaptive Card and
-non-fatal downgrade warnings. Sizes, weights, and colors map to Adaptive
+non-fatal conversion warnings. Sizes, weights, and colors map to Adaptive
 Card's semantic enums rather than raw values. An Input/Select/RadioGroup/
 Checkbox/DatePicker whose id would be the reserved RESERVED_INPUT_ID
 is renamed with a warning (see `decodeSubmitData`). Never throws: an

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

@@ -33,7 +33,7 @@ function QuoteBlock() {
 ```
 
 ```ts
-const useMessageQuote: () => QuoteInfo;
+const useMessageQuote: () => QuoteInfo | undefined;
 ```
 
 ### useMessageTiming
@@ -51,7 +51,7 @@ function MessageStats() {
 ```
 
 ```ts
-const useMessageTiming: () => MessageTiming;
+const useMessageTiming: () => MessageTiming | undefined;
 ```
 
 ### useRuntimeAdapters

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

@@ -36,7 +36,15 @@ 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.
+
+```ts
+const toEveInputResponse: (response: RespondToToolApprovalOptions) => InputResponse;
 ```
 
 ### useEveAgentRuntime
@@ -48,4 +56,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/react-ai-sdk.mdx

@@ -3,7 +3,7 @@ title: "@assistant-ui/react-ai-sdk"
 description: Vercel AI SDK runtime hooks, chat transports, and message conversion utilities for assistant-ui React applications.
 ---
 
-import { reactAiSdk_AISDKToolkit, reactAiSdk_AssistantChatTransport, reactAiSdk_createResumableSessionStorage, reactAiSdk_getThreadMessageTokenUsage, reactAiSdk_injectQuoteContext, reactAiSdk_unstable_injectInteractableContext, reactAiSdk_useAISDKRuntime, reactAiSdk_useChatRuntime } from "@/generated/integrationTypeDocs";
+import { reactAiSdk_AISDKChat, reactAiSdk_AISDKThreads, reactAiSdk_AISDKToolkit, reactAiSdk_AssistantChatTransport, reactAiSdk_createResumableSessionStorage, reactAiSdk_getThreadMessageTokenUsage, reactAiSdk_injectQuoteContext, reactAiSdk_unstable_injectInteractableContext, reactAiSdk_useAISDKRuntime, reactAiSdk_useChatRuntime } from "@/generated/integrationTypeDocs";
 
 {/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
 {/* Do not edit manually. */}
@@ -14,6 +14,31 @@ import { reactAiSdk_AISDKToolkit, reactAiSdk_AssistantChatTransport, reactAiSdk_
 
 ## API Reference
 
+### AISDKChat
+
+`AuiConfig` entry that runs the AI SDK chat as the `threads` scope. Hosts the
+same orchestration as `useChatRuntime` inside the client's own resource tree,
+so it works with any `AssistantClient` host, React or not. Single thread; the
+multi-thread and assistant-cloud surface is [AISDKThreads](/docs/api-reference/integrations/react-ai-sdk#aisdkthreads). The chat
+id is captured when the entry mounts, so a later `id` change in the options
+has no effect.
+
+<ParametersTable {...reactAiSdk_AISDKChat} />
+
+### AISDKThreads
+
+`AuiConfig` entry that runs one AI SDK chat per thread. Hosts the same
+per-thread orchestration as [AISDKChat](/docs/api-reference/integrations/react-ai-sdk#aisdkchat) inside the client's own
+resource tree, so it works with any `AssistantClient` host, React or not.
+Without `cloud`, threads live in memory for the client's lifetime and keep
+their history across switches; each thread's chat id is its thread id.
+With `cloud`, the list is a `RemoteThreadList` and the factory is keyed so
+cloud history reloads on a switch. The store entry mounts only the visible
+thread, so a switch cancels an in-flight run. Model context is
+registered on the visible thread only.
+
+<ParametersTable {...reactAiSdk_AISDKThreads} />
+
 ### AISDKToolkit
 
 <ParametersTable {...reactAiSdk_AISDKToolkit} />
@@ -109,7 +134,7 @@ runtime hook. `undefined` when the current thread is not backed by the AI
 SDK runtime.
 
 ```ts
-const useAISDKChat: <UI_MESSAGE extends UIMessage = UIMessage<unknown, UIDataTypes, UITools>>() => UseChatHelpers<UI_MESSAGE>;
+const useAISDKChat: <UI_MESSAGE extends UIMessage = UIMessage<unknown, UIDataTypes, UITools>>() => UseChatHelpers<UI_MESSAGE> | undefined;
 ```
 
 ### useAISDKError
@@ -119,7 +144,7 @@ Read the last AI SDK chat error object from the runtime extras.
 the AI SDK runtime.
 
 ```ts
-const useAISDKError: () => Error;
+const useAISDKError: () => Error | undefined;
 ```
 
 ### useAISDKRuntime
@@ -133,7 +158,7 @@ const useAISDKError: () => Error;
 ### useThreadTokenUsage
 
 ```ts
-function useThreadTokenUsage(): ThreadTokenUsage;
+function useThreadTokenUsage(): ThreadTokenUsage | undefined;
 ```
 
 ### generativeTools

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/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, 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. */}
@@ -18,6 +18,29 @@ import { AssistantCloud, ChainOfThoughtClient, DevToolsHooks, InMemoryThreadList
 
 <ParametersTable {...AssistantCloud} />
 
+### AuiConfig
+
+Builds a config for [AuiProvider](/docs/api-reference/context-providers/assistant-runtime-provider#auiprovider); the `config` prop only accepts
+configs built with this helper.
+
+A config is plain data: it can be hoisted to module scope, created inline
+per render, or memoized — the provider never relies on config identity.
+
+```tsx
+const aui = useAui();
+const config = AuiConfig({
+  message: Derived({
+    source: "thread",
+    query: { index: 0 },
+    get: (aui) => aui.thread.message({ index: 0 }),
+  }),
+});
+
+<AuiProvider extends={aui} config={config}>{children}</AuiProvider>;
+```
+
+<ParametersTable {...AuiConfig} />
+
 ### ChainOfThoughtClient
 
 <ParametersTable {...ChainOfThoughtClient} />
@@ -36,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} />

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/react-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
@@ -393,7 +393,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages,
   });
 

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 |
@@ -378,7 +378,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:
@@ -391,7 +391,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages,
   });
 
@@ -459,7 +459,7 @@ export async function POST(req: Request) {
   const samplingCalls: Record<string, SamplingCallData[]> = {};
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages,
     tools: {
       delegate_to_gemini: tool({

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/model-context.mdx

@@ -63,6 +63,7 @@ export default defineToolkit({
 
 ```tsx title="app/Form.tsx"
 import {
+  AuiConfig,
   AuiProvider,
   makeAssistantVisible,
   Tools,
@@ -77,10 +78,10 @@ const ClickableButton = makeAssistantVisible(Button, {
 
 // Use in your component
 function Form() {
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AuiProvider value={aui}>
+    <AuiProvider extends={aui} config={config}>
       <form>{/* form fields */}</form>
     </AuiProvider>
   );

package/.docs/raw/docs/copilots/motivation.mdx

@@ -131,15 +131,15 @@ export default defineToolkit({
 ```
 
 ```tsx title="app/SmartTransactionHistory.tsx"
-import { AuiProvider, Tools, useAui } from "@assistant-ui/react";
+import { AuiConfig, AuiProvider, Tools, useAui } from "@assistant-ui/react";
 import toolkit from "./transaction-toolkit";
 
 function SmartTransactionHistory() {
-  const aui = useAui({ tools: Tools({ toolkit }) });
-
   // Previous instructions...
+  const aui = useAui();
+  const config = AuiConfig({ tools: Tools({ toolkit }) });
   return (
-    <AuiProvider value={aui}>
+    <AuiProvider extends={aui} config={config}>
       <TransactionHistory transactions={transactions} />
     </AuiProvider>
   );

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

@@ -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/chain-of-thought.mdx

@@ -109,7 +109,7 @@ export async function POST(req: Request) {
   const { messages } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-5.4-mini"),
+    model: openai("gpt-5.6-luna"),
     messages: await convertToModelMessages(messages),
   });
 

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