@assistant-ui/mcp-docs-server 0.1.34 → 0.1.36

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

@@ -15,18 +15,11 @@ Integrations are wiring guides for using third-party services with assistant-ui,
 
 ## Where integrations slot in
 
-```
-client  ──►  your API route  ──►  LLM provider
-                │                    ▲
-                │                    │
-     agent      │                    │  observability
-     frameworks │                    │  proxies
-     (e.g.      │                    │  (e.g. Helicone,
-     Mastra)    │                    │   Langfuse)
-                ▼                    │
-          run on the server,         │
-          then forward calls   ──────┘
-          to the provider
+```mermaid
+flowchart LR
+    client["client"] --> route["your API route"] --> provider["LLM provider"]
+    route -->|"agent frameworks (e.g. Mastra)"| server["run on the server,<br/>then forward calls"]
+    server -->|"observability proxies (e.g. Helicone, Langfuse)"| provider
 ```
 
 Integrations live on the server. **Agent frameworks** like Mastra take over the API route. **Gateways** swap the upstream provider URL. **Observability** logs or traces every call. **Auth** gates the route and scopes per-user data. **Persistence** and **attachments** are adapter recipes for storing chat data outside the default in-memory path.

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

@@ -11,10 +11,9 @@ Helicone is independent of which assistant-ui runtime you use. It slots in at th
 
 ## How it works
 
-```
-your server  ──►  Helicone proxy  ──►  OpenAI / Anthropic / etc.
-                  │
-                  └─ logs request, response, tokens, cost
+```mermaid
+flowchart LR
+    server["your server"] --> proxy["Helicone proxy<br/>(logs request, response, tokens, cost)"] --> provider["OpenAI / Anthropic / etc."]
 ```
 
 Calls pass through Helicone's edge before reaching the upstream provider. The proxy is transparent: response shape and streaming behavior are unchanged, you just gain a dashboard of every call.

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

@@ -13,11 +13,9 @@ Pick Langfuse when you want to see the agent's full call tree inside a single tu
 
 ## How it works
 
-```
-your route  ──►  AI SDK streamText (with experimental_telemetry)
-                  │
-                  ▼
-                  OpenTelemetry SDK  ──►  LangfuseSpanProcessor  ──►  Langfuse
+```mermaid
+flowchart LR
+    route["your route"] --> stream["AI SDK streamText<br/>(experimental_telemetry)"] --> otel["OpenTelemetry SDK"] --> proc["LangfuseSpanProcessor"] --> langfuse["Langfuse"]
 ```
 
 Langfuse subscribes to OpenTelemetry spans the AI SDK already emits when telemetry is enabled. No proxy, no wrapping; the SDK ships spans and Langfuse renders them.

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

@@ -15,8 +15,9 @@ This page covers the **AI SDK** path. If you use [`@assistant-ui/react-langgraph
 
 LangSmith provides a wrapper around the `ai` namespace. You call `wrapAISDK(ai)`, get back the same exports (`generateText`, `streamText`, `generateObject`, `streamObject`), and use those in place of the originals. Every call is then traced.
 
-```
-your route  ──►  wrapped streamText  ──►  LangSmith client  ──►  LangSmith
+```mermaid
+flowchart LR
+    route["your route"] --> stream["wrapped streamText"] --> client["LangSmith client"] --> langsmith["LangSmith"]
 ```
 
 ## Setup

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

@@ -18,9 +18,10 @@ If you're rolling your own auth, replace `auth()` calls with whatever your stack
 
 ## How it works
 
-```
-client  ──►  /api/threads/*   (RemoteThreadListAdapter)  ──►  threads table
-             /api/messages/*  (ThreadHistoryAdapter)     ──►  messages table
+```mermaid
+flowchart LR
+    client["client"] --> threads["/api/threads/*<br/>(RemoteThreadListAdapter)"] --> tt["threads table"]
+    client --> messages["/api/messages/*<br/>(ThreadHistoryAdapter)"] --> mt["messages table"]
 ```
 
 Two adapters, two tables:

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

@@ -103,6 +103,14 @@ import { ComposerPrimitive } from "@assistant-ui/react";
 
 The primitive's behavior (keyboard handling, disabled state, form submission) is merged onto your element. Your styles, your component, primitive wiring.
 
+<Callout type="info">
+Own the input DOM entirely, such as a `contentEditable` surface or editor
+library that cannot be expressed through `asChild` or `render`? See
+[Headless Composer Input](/docs/guides/headless-composer-input) for the
+unstable hook that supplies composer text and send gating without
+`ComposerPrimitive.Input`.
+</Callout>
+
 ### Unstable Trigger Popovers
 
 Composer includes an unstable **trigger popover** system for character-triggered popovers (e.g. `@` for mentions, `/` for slash commands). Multiple triggers coexist under a single `TriggerPopoverRoot`.

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

@@ -319,6 +319,30 @@ Renders a single message at a specific index in the thread.
 
 <PrimitivesTypeTable type="ThreadPrimitiveMessageByIndexProps" parameters={ThreadPrimitiveDocs.MessageByIndex.props} />
 
+### Unstable_MessageById
+
+Renders a single message by id with the same `components` surface as
+`MessageByIndex`. Pair it with `unstable_useThreadMessageIds` for virtualized or
+custom message lists that should stay attached to messages across reordering and
+windowing. Unknown ids render `null`.
+
+```tsx
+const messageIds = unstable_useThreadMessageIds();
+
+messageIds.map((messageId) => (
+  <ThreadPrimitive.Unstable_MessageById
+    key={messageId}
+    messageId={messageId}
+    components={{ Message: MyMessage }}
+  />
+));
+```
+
+<Callout type="warn">
+  `unstable_useThreadMessageIds` and `ThreadPrimitive.Unstable_MessageById` are
+  experimental and may change in any release.
+</Callout>
+
 ### ScrollToBottom
 
 Scrolls the viewport to the bottom. Automatically disabled when already at the bottom. Renders a `<button>` element unless `asChild` is set.

package/.docs/raw/docs/react-native/hooks.mdx

@@ -80,7 +80,7 @@ const runtime = useLocalRuntime(chatModel, {
 | `maxSteps` | `number` | Maximum tool call steps per run |
 | `cloud` | `AssistantCloud` | Optional cloud instance for persistence |
 | `adapters` | `object` | Optional adapter overrides (see below) |
-| `unstable_humanToolNames` | `string[]` | Tool names that pause the run for human approval |
+| `unstable_humanToolNames` | `string[]` | Tool names that pause the run until a result is added via `addResult` |
 
 The `adapters` option accepts the following fields (all optional):
 

package/.docs/raw/docs/runtimes/ag-ui/runtime-options.mdx

@@ -66,9 +66,9 @@ messages are gone on the next page load.
 `showThinking: false`, so imported reasoning messages are dropped at conversion
 time, the same way a live run never stores them.
 
-`fromAgUiMessages` reconstructs the text, reasoning, and tool calls of each
-message. Non-text message content such as images and files is not restored, so a
-backend that persists multimodal messages loads only their text on reload.
+`fromAgUiMessages` reconstructs the text, reasoning, and tool calls of each message. Multimodal user input (`image`, `audio`, `video`, and `document` parts, as well as legacy `binary` parts) is restored as attachments on the user message, so a backend that persists multimodal messages shows them again on reload and re-sends them on the next run. Legacy `binary` parts that only reference a file id are not restored.
+
+An assistant message whose tool call has no matching tool result is reconstructed with `requires-action` status, the same status the runtime derives for a pending tool call, so a reloaded human-in-the-loop call (for example an `ask_user` tool) is actionable rather than stuck. This matches how every other external-store runtime surfaces a pending tool call on reload. The AG-UI wire snapshot carries no run outcome, so a tool call that a successful run intentionally left without a result is also surfaced as actionable.
 
 ## Thread list (experimental)
 
@@ -133,6 +133,25 @@ await runtime.unstable_submitInterruptResponses(
 );
 ```
 
+### Steering away from an interrupt
+
+When the user ignores the interrupt UI and just sends a new message, use the `useAgUiSteerAway` hook. Every open interrupt defaults to `status: "cancelled"`, the new message is appended, and the run resumes with `resume: ResumeEntry[]` on the wire. With no pending interrupts it behaves like a normal append.
+
+```tsx
+const steerAway = useAgUiSteerAway();
+
+// the user typed a new message instead of answering the interrupt
+await steerAway("actually, let's do something else");
+```
+
+The message accepts a plain string or a partial `AppendMessage` (the parent defaults to the current head, which is the interrupted assistant message). Pass `responses` to override the status of specific interrupts; the rest still default to cancelled.
+
+```tsx
+await steerAway("continue without the file", [
+  { interruptId: "tool-1", status: "resolved", payload: { approved: true } },
+]);
+```
+
 ## Supported events
 
 The runtime parses the AG-UI event stream and maps each event type to assistant-ui state.

package/.docs/raw/docs/runtimes/concepts/stability.mdx

@@ -30,7 +30,7 @@ A non-exhaustive list of `unstable_` exports surfaced in the runtime docs.
 | API | Package | Notes |
 | --- | --- | --- |
 | `unstable_createMessageConverter` | `@assistant-ui/react` | Message-format converter used by AssistantTransport and DataStream. |
-| `unstable_humanToolNames` | `@assistant-ui/react` | Tool names that pause for human approval. Only available on LocalRuntime; not supported in DataStream. |
+| `unstable_humanToolNames` | `@assistant-ui/react` | Tool names that pause the run until a result is added via `addResult`. Only available on LocalRuntime; not supported in DataStream. |
 | `unstable_threadListAdapter` | `@assistant-ui/react-langgraph` | LangGraph thread-list adapter slot on `useLangGraphRuntime`. |
 | `unstable_createLangGraphStream` | `@assistant-ui/react-langgraph` | End-to-end cancellation primitive. |
 | `unstable_Provider` | Various adapters | Thread-scoped provider on `RemoteThreadListAdapter`. Must render children synchronously. |

package/.docs/raw/docs/runtimes/custom/data-stream.mdx

@@ -206,7 +206,7 @@ const runtime = useDataStreamRuntime({
 ## Tool integration
 
 <Callout type="warn">
-Human-in-the-loop tools (`unstable_humanToolNames`, `human()` interrupts) are not supported in the data stream runtime. Use [`LocalRuntime`](/docs/runtimes/custom/local-runtime) directly if you need approval flows.
+Human-in-the-loop tools (`unstable_humanToolNames`, `human()` interrupts) are not supported in the data stream runtime. Use [`LocalRuntime`](/docs/runtimes/custom/local-runtime#human-in-the-loop-tools) directly if you need them.
 </Callout>
 
 ### Frontend tools

package/.docs/raw/docs/runtimes/custom/external-store.mdx

@@ -299,6 +299,54 @@ runtime.thread.import(repo);
 
 Each message must have an explicit `id` and `parentId`; messages with the same `parentId` create branches. Parents must appear before children in the array.
 
+### Exporting a snapshot
+
+`thread.import()` has a counterpart, `thread.export()`, which captures the current thread (including its full branch tree) as a serializable `ExportedMessageRepository`. Use it to persist a conversation and re-import it later:
+
+```tsx
+// capture the current thread as a serializable snapshot
+const repo = runtime.thread.export();
+await saveToBackend(JSON.stringify(repo));
+
+// later, restore it into a runtime
+runtime.thread.import(repo);
+```
+
+The exported shape round-trips through `thread.import()` directly, so the same value is both your persistence format and what you load back.
+
+### Persisting branch selection
+
+If you store the full branch tree outside assistant-ui, persist the selected branch head too and pass it back as `messageRepository.headId`. `setMessages` still performs the branch switch; `unstable_onBranchChange` is an additional signal that fires after an explicit `switchToBranch` action, such as a BranchPicker click.
+
+```tsx
+const runtime = useExternalStoreRuntime({
+  messageRepository: {
+    messages: storedMessages,
+    headId: selectedHeadId,
+  },
+  setMessages: (messages) => {
+    setVisibleMessages(messages);
+  },
+  unstable_onBranchChange: ({ headId, visibleMessageIds }) => {
+    saveSelectedBranch({
+      headId,
+      visibleMessageIds,
+    });
+  },
+  onNew,
+});
+```
+
+`headId` is the canonical persisted head of the visible branch. Optimistic or transient message ids are not surfaced there. `visibleMessageIds` is the currently visible path in order, which can include an optimistic leaf while `headId` points to its persisted ancestor.
+
+The callback only fires for explicit branch switches, and consecutive switches that resolve to the same canonical head are de-duped. It does not fire on adapter resync, `messageRepository` reset, append, edit/regenerate, content-only updates, or while the thread is running.
+
+<Callout type="warn">
+  `unstable_onBranchChange` is under active development and may change without
+  notice. It complements `setMessages`; it does not enable branch switching by
+  itself.
+</Callout>
+
 ## Tool calling
 
 Handle tool results by updating the matching tool-call entry:
@@ -717,6 +765,12 @@ useExternalStoreRuntime({
       type: "(messages: readonly T[]) => void",
       description: "Update messages (required for branch switching).",
     },
+    {
+      name: "unstable_onBranchChange",
+      type: "(event: ExternalStoreBranchChange) => void",
+      description:
+        "Called after an explicit branch switch with the canonical persisted head id and visible message path. Complements setMessages and is unstable.",
+    },
     {
       name: "onEdit",
       type: "(message: AppendMessage) => Promise<void>",

package/.docs/raw/docs/runtimes/custom/local-runtime.mdx

@@ -457,18 +457,122 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 
 See the [tools guide](/docs/tools/defining-tools) for advanced patterns.
 
-### Human-in-the-loop approval
+### Human-in-the-loop tools
 
-Require user confirmation before specific tools execute:
+Tools listed in `unstable_humanToolNames` are not executed by code. The run pauses on the tool call and the user supplies the result through the tool UI:
 
 ```ts
 const runtime = useLocalRuntime(MyModelAdapter, {
-  unstable_humanToolNames: ["delete_file", "send_email"],
+  unstable_humanToolNames: ["send_email"],
+});
+```
+
+The pause is driven by the message status your adapter returns; `LocalRuntime` never sets it for you. When the model requests a human tool call, end the run with `status: { type: "requires-action", reason: "tool-calls" }`. Without that status, the runtime marks the message complete and nothing waits. Only return it while a listed tool call is missing its result: unresolved tool calls that are not listed do not hold the run, so the runtime would invoke your adapter again immediately.
+
+```tsx
+const MyModelAdapter: ChatModelAdapter = {
+  async run({ messages, abortSignal, unstable_getMessage }) {
+    const toolResults = unstable_getMessage().content.flatMap((part) =>
+      part.type === "tool-call" && part.result !== undefined
+        ? [{ toolCallId: part.toolCallId, result: part.result }]
+        : [],
+    );
+
+    const result = await fetch("<YOUR_API_ENDPOINT>", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ messages, toolResults }),
+      signal: abortSignal,
+    });
+    const data = await result.json();
+
+    if (data.toolCall) {
+      return {
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: data.toolCall.id,
+            toolName: data.toolCall.name,
+            args: data.toolCall.args,
+            argsText: JSON.stringify(data.toolCall.args),
+          },
+        ],
+        status: { type: "requires-action", reason: "tool-calls" },
+      };
+    }
+
+    return { content: [{ type: "text", text: data.text }] };
+  },
+};
+```
+
+The full loop:
+
+1. **The run pauses.** While a listed tool call has no result, the runtime stops invoking your adapter. The unresolved tool call part reports `status.type === "requires-action"` to its renderer.
+2. **The user responds.** The tool UI completes the call with `addResult(...)`. The stock [`ToolFallback`](/docs/ui/tool-fallback) component handles this out of the box: in the requires-action state it shows Allow and Deny buttons that record the decision as the tool result.
+3. **The run resumes.** Once every listed tool call has a result, the runtime invokes your adapter again. The resumed call receives the same `messages` array as before (it ends at the user message; the in-progress assistant message is not part of it), so read the recorded results from `unstable_getMessage().content` as shown above. Content returned by the resumed call is appended to the same assistant message.
+
+For a custom confirmation UI, register a human tool whose `render` completes the call with `addResult`. The shape of the result payload is yours to define; the adapter receives it verbatim and translates it for your backend:
+
+```tsx
+const toolkit = defineToolkit({
+  send_email: {
+    type: "human",
+    description: "Send an email after the user confirms",
+    parameters: z.object({ to: z.string(), subject: z.string() }),
+    render: ({ args, result, addResult }) => {
+      if (result) {
+        return <p>{result.approved ? "Sent" : `Cancelled: ${result.reason}`}</p>;
+      }
+      return (
+        <div>
+          <p>
+            Send "{args.subject}" to {args.to}?
+          </p>
+          <button onClick={() => addResult({ approved: true })}>Allow</button>
+          <button
+            onClick={() =>
+              addResult({ approved: false, reason: "User declined" })
+            }
+          >
+            Deny
+          </button>
+        </div>
+      );
+    },
+  },
 });
 ```
 
 `unstable_humanToolNames` is unstable; see [stability](/docs/runtimes/concepts/stability).
 
+### Approval gates
+
+The [server-side approval gate](/docs/tools/tool-ui#server-side-approval-gates) is also supported on `LocalRuntime`, for actions your backend executes after the user authorizes them. Where a human tool asks the user to supply the tool result, an approval gate asks the user to allow or block an action the adapter performs. Emit `approval: { id }` on the tool call part and end the run with the same `requires-action` status:
+
+```tsx
+return {
+  content: [
+    {
+      type: "tool-call",
+      toolCallId: data.toolCall.id,
+      toolName: data.toolCall.name,
+      args: data.toolCall.args,
+      argsText: JSON.stringify(data.toolCall.args),
+      approval: { id: data.toolCall.id },
+    },
+  ],
+  status: { type: "requires-action", reason: "tool-calls" },
+};
+```
+
+A tool call with a pending approval pauses the run, whether or not the tool is listed in `unstable_humanToolNames`. Always emit gates in the pending state (`approval: { id }` with no `approved` field); a part that arrives already decided is treated as resolved and the runtime invokes the adapter again immediately. The stock [`ToolFallback`](/docs/ui/tool-fallback) Allow and Deny buttons, or a custom renderer calling `respondToApproval({ approved, reason? })`, record the decision:
+
+- **Deny** sets `approval.approved: false` and synthesizes an error result (`{ error: reason || "Tool approval denied" }` with `isError: true`), so the model sees the denial.
+- **Allow** sets `approval.approved: true` and leaves the result empty; performing the action is your adapter's job.
+
+Once every pending approval on the message is decided and every listed human tool has a result, the runtime invokes your adapter again. Read the decisions from `unstable_getMessage().content`, perform the approved actions, and return the follow-up response. A tool call that carries an approval is owned by the gate: it does not additionally require a result, even when its name is listed in `unstable_humanToolNames`.
+
 ## Resuming a run
 
 `resumeRun` reconnects to an in-progress assistant run. Useful for page refresh, network reconnect, tab backgrounding, or thread switching when the backend is still generating.
@@ -743,7 +847,7 @@ const CustomAPIAdapter: ChatModelAdapter = {
       name: "unstable_humanToolNames",
       type: "string[]",
       description:
-        "Tool names that require human approval before execution (unstable).",
+        "Tool names that pause the run until the user supplies a result via addResult (unstable).",
     },
   ]}
 />

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

@@ -0,0 +1,100 @@
+---
+title: Eve Runtime
+description: Connect an Eve agent to assistant-ui with useEveAgentRuntime, eve/next, durable sessions, streaming messages, and human-in-the-loop approvals.
+---
+
+import { VercelIcon } from "@/components/icons/vercel";
+
+`@assistant-ui/eve` integrates assistant-ui with [Eve](https://eve.dev/), Vercel's filesystem-first framework for durable agents. It wraps Eve's `useEveAgent` hook and exposes it as an assistant-ui `ExternalStoreRuntime`, so Eve owns the session stream while assistant-ui renders messages, reasoning, dynamic tool calls, and approval requests.
+
+## When to use it
+
+Pick the Eve runtime when:
+
+- You want your agent implementation to live under `agent/` and be served by `eve/next`.
+- You want Eve sessions, continuation tokens, NDJSON streaming, and local development tooling.
+- You want assistant-ui to render Eve messages and human-in-the-loop tool approvals without writing a custom runtime adapter.
+
+## Architecture
+
+The Next.js app mounts Eve with `withEve()` and assistant-ui's registry transform with `withAui()`:
+
+```ts title="next.config.ts"
+import { withAui } from "@assistant-ui/next";
+import type { NextConfig } from "next";
+import { withEve } from "eve/next";
+
+const nextConfig: NextConfig = {};
+
+export default withEve(withAui(nextConfig));
+```
+
+On the client, `useEveAgentRuntime()` calls Eve's React hook and converts Eve message parts into assistant-ui thread messages:
+
+```tsx title="app/page.tsx"
+"use client";
+
+import { Thread } from "@/components/assistant-ui/thread";
+import { useEveAgentRuntime } from "@assistant-ui/eve";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+
+export default function Home() {
+  const runtime = useEveAgentRuntime();
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+## Requirements
+
+- Node.js 24 or higher.
+- React 18 or 19.
+- An Eve app mounted with `eve/next`.
+- A model credential for the model configured in `agent/agent.ts`.
+
+Eve's default gateway model ids route through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). Use `AI_GATEWAY_API_KEY` or Vercel OIDC, or configure a direct provider `LanguageModel`.
+
+## Install
+
+<PlatformTabs>
+<Tab value="React">
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/eve", "eve"]} />
+
+</Tab>
+<Tab value="React Native">
+
+Eve's browser hook talks to the Eve HTTP channel. There is not a React Native Eve runtime package yet.
+
+</Tab>
+<Tab value="React Ink">
+
+Use Eve's terminal UI directly for command-line agent sessions. There is not an Ink Eve runtime package yet.
+
+</Tab>
+</PlatformTabs>
+
+## Auth note
+
+Eve's built-in `eve` channel accepts localhost during development and trusted Vercel OIDC callers. It does not automatically admit browser users in production. Before deploying a public app, add `agent/channels/eve.ts` and wire the channel to your application auth.
+
+## Next
+
+<Cards>
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="Quickstart"
+    description="Scaffold the Eve template or add Eve to an existing assistant-ui app."
+    href="/docs/runtimes/eve/quickstart"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="Eve channel"
+    description="Routes, auth, session creation, and stream events in the default Eve HTTP channel."
+    href="https://eve.dev/docs/channels/eve"
+  />
+</Cards>

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

@@ -0,0 +1,143 @@
+---
+title: Quickstart
+description: From-template 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.
+
+## From the template
+
+<PlatformTabs>
+<Tab value="React">
+
+```sh
+npx create-assistant-ui@latest -t eve my-app
+cd my-app
+```
+
+Set a model credential:
+
+```sh title=".env.local"
+AI_GATEWAY_API_KEY=your-api-key
+```
+
+```sh
+npm run dev
+```
+
+Open http://localhost:3000 and send a message. The template includes:
+
+- `agent/agent.ts` for Eve runtime config.
+- `agent/instructions.md` for the always-on system prompt.
+- `next.config.ts` with `withEve(withAui(nextConfig))`.
+- `app/page.tsx` with `useEveAgentRuntime()`.
+
+</Tab>
+<Tab value="React Native">
+
+There is not a React Native Eve template yet.
+
+</Tab>
+<Tab value="React Ink">
+
+Use Eve's terminal UI directly for command-line agent sessions.
+
+</Tab>
+</PlatformTabs>
+
+## Manual setup in an existing app
+
+<Steps>
+<Step>
+
+### Install dependencies
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/eve", "eve"]} />
+
+</Step>
+<Step>
+
+### Mount Eve in Next.js
+
+```ts title="next.config.ts"
+import { withAui } from "@assistant-ui/next";
+import type { NextConfig } from "next";
+import { withEve } from "eve/next";
+
+const nextConfig: NextConfig = {};
+
+export default withEve(withAui(nextConfig));
+```
+
+</Step>
+<Step>
+
+### Add an Eve agent
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-sonnet-4.6",
+});
+```
+
+```md title="agent/instructions.md"
+You are a concise assistant. Use tools when they are available.
+```
+
+</Step>
+<Step>
+
+### Create the runtime
+
+```tsx title="app/page.tsx"
+"use client";
+
+import { Thread } from "@/components/assistant-ui/thread";
+import { useEveAgentRuntime } from "@assistant-ui/eve";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+
+export default function Home() {
+  const runtime = useEveAgentRuntime();
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Step>
+</Steps>
+
+## Production auth
+
+The default Eve channel is convenient for local development. For production browser users, define `agent/channels/eve.ts` and replace the default auth policy with your app's auth.
+
+```ts title="agent/channels/eve.ts"
+import { localDev, vercelOidc } from "eve/channels/auth";
+import { eveChannel } from "eve/channels/eve";
+
+export default eveChannel({
+  auth: [localDev(), vercelOidc()],
+});
+```
+
+That example keeps the development defaults. Swap in your Clerk, Auth.js, OIDC, or JWT verification before going live.
+
+## Next
+
+<Cards>
+  <Card
+    title="Eve overview"
+    description="Architecture, requirements, and runtime behavior."
+    href="/docs/runtimes/eve/overview"
+  />
+  <Card
+    title="API reference"
+    description="useEveAgentRuntime and message conversion helpers."
+    href="/docs/api-reference/integrations/eve"
+  />
+</Cards>