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

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

@@ -1,188 +0,0 @@
----
-title: better-auth
-description: TypeScript-first auth with database-owned sessions; gate the chat route and scope threads to the signed-in user.
----
-
-[better-auth](https://www.better-auth.com/) is a TypeScript-first auth library that owns the session, the user table, and the cookie story end to end. It pairs naturally with assistant-ui's [custom thread persistence](/docs/integrations/persistence/custom-adapter): the same database holds users and threads, and `session.user.id` flows directly into your where clauses.
-
-This page covers the non-cloud path. AssistantCloud users should see [cloud authorization](/docs/cloud/authorization) for the JWT-exchange pattern.
-
-## How it works
-
-```mermaid
-flowchart LR
-    browser["browser"] --> routes["/api/auth/[...all]<br/>/api/chat<br/>/api/threads/*"]
-    routes --> handlers["better-auth handlers"]
-    routes --> session["auth.api.getSession({ headers })"]
-    handlers --> session
-    session --> uid["session.user.id"] --> scope["scope queries by userId"]
-```
-
-Three integration points:
-
-1. **Auth handlers** mounted at `/api/auth/[...all]/route.ts` via `toNextJsHandler(auth)`.
-2. **API routes** read the session server-side with `auth.api.getSession({ headers: await headers() })`.
-3. **Reload-on-auth** uses better-auth's React client to detect sign-in and trigger `aui.threads.reload()`.
-
-`session.user.id` is exposed on the session object directly, so route handlers can scope queries against it.
-
-## Setup
-
-This guide assumes you already have better-auth configured. If not, follow the [better-auth Next.js guide](https://www.better-auth.com/docs/integrations/next) first; the steps below pick up after `auth.ts` exports a `betterAuth(...)` instance.
-
-<Steps>
-<Step>
-
-### Confirm the auth handler is mounted
-
-better-auth ships its own catch-all handler. Make sure it's wired:
-
-```ts title="app/api/auth/[...all]/route.ts"
-import { auth } from "@/auth";
-import { toNextJsHandler } from "better-auth/next-js";
-
-export const { GET, POST } = toNextJsHandler(auth);
-```
-
-Without this, sign-in, sign-out, and session refresh requests have nowhere to land.
-
-</Step>
-<Step>
-
-### Gate the chat route
-
-Resolve the session server-side with `auth.api.getSession`. It accepts request headers (which carry the session cookie) and returns `null` for unauthenticated requests.
-
-```ts title="app/api/chat/route.ts"
-import { auth } from "@/auth";
-import { headers } from "next/headers";
-import { openai } from "@ai-sdk/openai";
-import { streamText, convertToModelMessages } from "ai";
-import type { UIMessage } from "ai";
-
-export async function POST(req: Request) {
-  const session = await auth.api.getSession({ headers: await headers() });
-  if (!session) return new Response("Unauthorized", { status: 401 });
-
-  const { messages }: { messages: UIMessage[] } = await req.json();
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    messages: await convertToModelMessages(messages),
-  });
-  return result.toUIMessageStreamResponse();
-}
-```
-
-`headers()` from `next/headers` returns the active request's headers in App Router route handlers. Always `await` it.
-
-</Step>
-<Step>
-
-### Scope thread queries by user
-
-If you use [custom thread persistence](/docs/integrations/persistence/custom-adapter), every endpoint must filter by `session.user.id`. The pattern mirrors the chat route:
-
-```ts title="app/api/threads/route.ts"
-import { auth } from "@/auth";
-import { headers } from "next/headers";
-import { db } from "@/db";
-import { threads } from "@/db/schema";
-import { eq, desc } from "drizzle-orm";
-
-export async function GET() {
-  const session = await auth.api.getSession({ headers: await headers() });
-  if (!session) return new Response(null, { status: 401 });
-
-  const rows = await db
-    .select()
-    .from(threads)
-    .where(eq(threads.userId, session.user.id))
-    .orderBy(desc(threads.updatedAt));
-
-  return Response.json(rows);
-}
-```
-
-If your better-auth schema lives in the same database as your threads table, you can also reference `users.id` as a foreign key for cascading deletes.
-
-</Step>
-<Step>
-
-### Set up the React client
-
-Create the client once and import it from a shared module so all hooks share state:
-
-```ts title="lib/auth-client.ts"
-import { createAuthClient } from "better-auth/react";
-
-export const authClient = createAuthClient();
-```
-
-</Step>
-<Step>
-
-### Reload threads after async auth
-
-`useSession` from the React client tracks the live session. Drop a small effect inside `<AssistantRuntimeProvider>` that reloads the thread list when the user signs in:
-
-```tsx title="app/components/ReloadOnAuth.tsx"
-"use client";
-
-import { useAui } from "@assistant-ui/react";
-import { authClient } from "@/lib/auth-client";
-import { useEffect } from "react";
-
-export function ReloadOnAuth() {
-  const aui = useAui();
-  const { data: session, isPending } = authClient.useSession();
-  useEffect(() => {
-    if (!isPending && session) aui.threads.reload();
-  }, [isPending, session?.user?.id]);
-  return null;
-}
-```
-
-Mount this component anywhere inside your `<AssistantRuntimeProvider>` subtree (typically next to the runtime's provider in `MyProvider`). `reload()` discards in-flight responses from superseded calls, so it is safe to invoke on every auth transition.
-
-</Step>
-<Step>
-
-### Run and verify
-
-Sign in. Check:
-
-- `/api/chat` returns `200` when authenticated; `401` when not.
-- `/api/threads` returns only the current user's threads.
-- A second user (incognito tab) sees a different thread list.
-- The session cookie set by `/api/auth/sign-in/*` is `HttpOnly` and travels with same-origin fetches.
-
-</Step>
-</Steps>
-
-## Notes
-
-- **`session.user.id` is populated by default.** The `id` field comes from the user row better-auth manages, so route handlers can scope queries without any callback configuration.
-- **Cookie-based, same-origin.** Browser fetches automatically include the session cookie. If you split the API onto a different host, set `credentials: "include"` and configure CORS on the API.
-- **Database alignment.** If you use Drizzle and put both better-auth's user schema and your threads schema in the same database, foreign keys keep deletes consistent. better-auth's CLI generates the user schema; add your `threads` table referencing `user.id`.
-- **Edge runtime.** `auth.api.getSession` works in both Node and Edge runtimes when better-auth is configured for an edge-compatible adapter.
-- **Cloud users.** [AssistantCloud's auth-provider integrations](/docs/cloud/authorization) cover Clerk, Auth0, Supabase, and Firebase via JWT exchange. To pair Cloud with better-auth, use the [backend-server token approach](/docs/cloud/authorization#backend-server-approach): resolve `session.user.id` server-side, mint an Assistant Cloud token with that id as the `userId`, and return it from a token endpoint.
-
-## Related
-
-<Cards>
-  <Card
-    title="Custom thread persistence"
-    description="The persistence story this page builds on; required for per-user threads outside AssistantCloud."
-    href="/docs/integrations/persistence/custom-adapter"
-  />
-  <Card
-    title="Auth.js (next-auth)"
-    description="The other common Next.js auth library. Different session shape; same wiring approach."
-    href="/docs/integrations/auth/next-auth"
-  />
-  <Card
-    title="Threads (concepts)"
-    description="The full RemoteThreadListAdapter contract and reload-on-auth pattern."
-    href="/docs/runtimes/concepts/threads"
-  />
-</Cards>

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

@@ -1,166 +0,0 @@
----
-title: Clerk
-description: Gate the chat route and scope thread persistence to the signed-in user with Clerk.
----
-
-[Clerk](https://clerk.com/) is a hosted auth platform that integrates with Next.js through `@clerk/nextjs`. This page covers using it with assistant-ui *without* AssistantCloud: middleware-based route gating, server-side `auth()` checks, and per-user scoping on a custom thread list.
-
-If you use AssistantCloud, see [cloud authorization](/docs/cloud/authorization) instead. Cloud handles the Clerk JWT exchange for you and gives you workspace-scoped threads with no DB code.
-
-## How it works
-
-```mermaid
-flowchart LR
-    browser["browser"] --> mw["clerkMiddleware<br/>(proxy.ts)"] --> routes["/api/chat<br/>/api/threads/*"] --> auth["auth() returns { userId }"] --> scope["scope queries by userId"]
-```
-
-Three places Clerk touches the integration:
-
-1. **Middleware** runs before every request and sets up the auth context the rest of the app reads.
-2. **API routes** (`/api/chat`, `/api/threads/*`) call `await auth()` from `@clerk/nextjs/server`, return 401 when `userId` is null, then scope DB queries by that id.
-3. **Reload-on-auth** uses `useUser` from `@clerk/nextjs` so the thread list re-fetches when the user signs in.
-
-Clerk's `auth()` returns `userId` directly, so the route handler can scope queries without any callback configuration.
-
-## Setup
-
-This guide assumes you already have Clerk configured in your Next.js app. If not, follow the [Clerk Next.js quickstart](https://clerk.com/docs/quickstarts/nextjs) first; the steps below pick up after `<ClerkProvider>` wraps your root layout and `clerkMiddleware()` is in place.
-
-<Steps>
-<Step>
-
-### Gate the chat route
-
-Add an `auth()` check to the AI SDK route. Return 401 before calling the model so unauthenticated traffic doesn't burn provider credits.
-
-```ts title="app/api/chat/route.ts"
-import { auth } from "@clerk/nextjs/server";
-import { openai } from "@ai-sdk/openai";
-import { streamText, convertToModelMessages } from "ai";
-import type { UIMessage } from "ai";
-
-export async function POST(req: Request) {
-  const { userId } = await auth();
-  if (!userId) return new Response("Unauthorized", { status: 401 });
-
-  const { messages }: { messages: UIMessage[] } = await req.json();
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    messages: await convertToModelMessages(messages),
-  });
-  return result.toUIMessageStreamResponse();
-}
-```
-
-</Step>
-<Step>
-
-### Scope thread queries by user
-
-If you also use [custom thread persistence](/docs/integrations/persistence/custom-adapter), every thread-list endpoint must filter by `userId`. Without scoping, any signed-in user can list everyone's threads.
-
-```ts title="app/api/threads/route.ts"
-import { auth } from "@clerk/nextjs/server";
-import { db } from "@/db";
-import { threads } from "@/db/schema";
-import { eq, desc } from "drizzle-orm";
-
-export async function GET() {
-  const { userId } = await auth();
-  if (!userId) return new Response(null, { status: 401 });
-
-  const rows = await db
-    .select()
-    .from(threads)
-    .where(eq(threads.userId, userId))
-    .orderBy(desc(threads.updatedAt));
-
-  return Response.json(rows);
-}
-```
-
-For organization-scoped threads (Clerk Orgs), pull `orgId` from `auth()` and add it to the where clause. The combination is a stable workspace key:
-
-```ts
-import { and, eq } from "drizzle-orm";
-
-const { userId, orgId } = await auth();
-if (!userId) return new Response(null, { status: 401 });
-
-const rows = await db
-  .select()
-  .from(threads)
-  .where(
-    orgId
-      ? and(eq(threads.orgId, orgId), eq(threads.userId, userId))
-      : eq(threads.userId, userId),
-  );
-```
-
-</Step>
-<Step>
-
-### Reload threads after async auth
-
-The first render of `<MyProvider>` may run before Clerk resolves the user on the client. Drop a small effect inside `<AssistantRuntimeProvider>` that calls `aui.threads.reload()` once the user is loaded:
-
-```tsx title="app/components/ReloadOnAuth.tsx"
-"use client";
-
-import { useAui } from "@assistant-ui/react";
-import { useUser } from "@clerk/nextjs";
-import { useEffect } from "react";
-
-export function ReloadOnAuth() {
-  const aui = useAui();
-  const { isLoaded, isSignedIn, user } = useUser();
-  useEffect(() => {
-    if (isLoaded && isSignedIn) aui.threads.reload();
-  }, [isLoaded, isSignedIn, user?.id]);
-  return null;
-}
-```
-
-Mount this component anywhere inside your `<AssistantRuntimeProvider>` subtree (typically next to the runtime's provider in `MyProvider`). `reload()` discards in-flight responses from superseded calls, so it is safe to invoke on every auth transition (sign in, sign out, organization switch).
-
-</Step>
-<Step>
-
-### Run and verify
-
-Sign in. Check:
-
-- `/api/chat` returns `200` with a streaming response when authenticated; `401` when not.
-- `/api/threads` returns only the current user's threads.
-- Switching users (incognito tab, different account) shows a different thread list.
-- Switching active organization in Clerk's `<OrganizationSwitcher>` triggers a reload (if you wired `orgId` into the where clause).
-
-</Step>
-</Steps>
-
-## Notes
-
-- **Cookies are automatic.** Clerk's session cookie travels with same-origin fetches; no `credentials: "include"` is needed for browser requests to your own API routes.
-- **Server contexts.** `auth()` from `@clerk/nextjs/server` runs in any Next.js server context: server components, route handlers, and server actions. See Clerk's [`auth()` reference](https://clerk.com/docs/references/nextjs/auth) for the supported surfaces.
-- **Cloud users.** If you use AssistantCloud, prefer the [Clerk JWT template integration](/docs/cloud/authorization) over the pattern on this page. Cloud handles workspace assignment and you don't need to build the thread persistence yourself.
-- **B2B with organizations.** Clerk Orgs map cleanly to multi-tenant chat: scope by `orgId` in addition to `userId`, surface Clerk's `<OrganizationSwitcher>` (from `@clerk/nextjs`), and re-fetch threads on org change.
-
-## Related
-
-<Cards>
-  <Card
-    title="Custom thread persistence"
-    description="The persistence story this page builds on; required for per-user threads outside AssistantCloud."
-    href="/docs/integrations/persistence/custom-adapter"
-  />
-  <Card
-    title="AssistantCloud authorization"
-    description="The cloud-managed alternative: Clerk JWT template plus workspace scoping, no DB code."
-    href="/docs/cloud/authorization"
-  />
-  <Card
-    title="Threads (concepts)"
-    description="The full RemoteThreadListAdapter contract and reload-on-auth pattern."
-    href="/docs/runtimes/concepts/threads"
-  />
-</Cards>

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

@@ -1,191 +0,0 @@
----
-title: Auth.js (next-auth)
-description: Gate the chat route and scope thread persistence to the signed-in user with Auth.js v5.
----
-
-[Auth.js](https://authjs.dev/) (formerly NextAuth) is the dominant OSS auth library in the Next.js ecosystem. This page covers using it with assistant-ui *without* AssistantCloud: session-cookie auth, server-side `auth()` checks on the API route, and per-user scoping on a custom thread list.
-
-If you use AssistantCloud, see [cloud authorization](/docs/cloud) instead; cloud handles JWT exchange for you.
-
-## How it works
-
-```mermaid
-flowchart LR
-    browser["browser"] --> routes["/api/chat<br/>/api/threads/*"] --> auth["auth() returns session"] --> scope["scope queries by<br/>session.user.id"] --> db["database"]
-```
-
-Three places auth touches the integration:
-
-1. **API routes** (`/api/chat`, `/api/threads/*`) call `auth()` server-side, return 401 if no session, then scope DB queries by `session.user.id`.
-2. **`RemoteThreadListAdapter`** does nothing auth-specific; the cookie travels with the `fetch` calls automatically (same origin).
-3. **Reload-on-auth**: if the session resolves after the initial render, call `aui.threads.reload()` so the list re-fetches with the new identity.
-
-## Setup
-
-This guide assumes you already have Auth.js configured. If not, follow the [Auth.js installation guide](https://authjs.dev/getting-started/installation?framework=Next.js) first; the steps below pick up after `auth.ts` exports `{ handlers, signIn, signOut, auth }`.
-
-<Steps>
-<Step>
-
-### Populate `session.user.id`
-
-By default, Auth.js v5 does **not** include a stable `id` on `session.user`; only `email`, `name`, and `image` are exposed. Without this step, the scoping queries below all run with `userId: undefined` and silently match every row.
-
-Add `jwt` and `session` callbacks to your Auth.js config so the user id flows through. For the JWT session strategy:
-
-```ts title="auth.ts"
-import NextAuth from "next-auth";
-
-export const { handlers, signIn, signOut, auth } = NextAuth({
-  providers: [/* your providers */],
-  callbacks: {
-    async jwt({ token, user }) {
-      if (user) token.id = user.id;
-      return token;
-    },
-    async session({ session, token }) {
-      if (token.id) session.user.id = token.id as string;
-      return session;
-    },
-  },
-});
-```
-
-If you use the database session strategy, replace the `jwt`/`session` pair with a single `session` callback that copies from the `user` argument: `session.user.id = user.id`. See [Auth.js: extending the session](https://authjs.dev/guides/extending-the-session) for the full pattern.
-
-</Step>
-<Step>
-
-### Gate the chat route
-
-Add an `auth()` check to the existing AI SDK route. Return 401 before calling the model so unauthenticated traffic doesn't burn provider credits.
-
-```ts title="app/api/chat/route.ts"
-import { auth } from "@/auth";
-import { openai } from "@ai-sdk/openai";
-import { streamText, convertToModelMessages } from "ai";
-import type { UIMessage } from "ai";
-
-export async function POST(req: Request) {
-  const session = await auth();
-  if (!session?.user) return new Response("Unauthorized", { status: 401 });
-
-  const { messages }: { messages: UIMessage[] } = await req.json();
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    messages: await convertToModelMessages(messages),
-  });
-  return result.toUIMessageStreamResponse();
-}
-```
-
-</Step>
-<Step>
-
-### Scope thread queries by user
-
-If you also use [custom thread persistence](/docs/integrations/persistence/custom-adapter), every thread-list endpoint must filter by `session.user.id`. Without scoping, any signed-in user can list everyone's threads.
-
-```ts title="app/api/threads/route.ts"
-import { auth } from "@/auth";
-import { db } from "@/db";
-import { threads } from "@/db/schema";
-import { eq, desc } from "drizzle-orm";
-
-export async function GET() {
-  const session = await auth();
-  if (!session?.user) return new Response(null, { status: 401 });
-
-  const rows = await db
-    .select()
-    .from(threads)
-    .where(eq(threads.userId, session.user.id))
-    .orderBy(desc(threads.updatedAt));
-
-  return Response.json(rows);
-}
-```
-
-Apply the same pattern to `POST`, `PATCH`, and `DELETE` handlers. Always verify ownership before mutating.
-
-</Step>
-<Step>
-
-### Reload threads after async auth
-
-The first render of `<MyProvider>` may run before `auth()` resolves on the client. The thread list will be empty until the user refreshes. Drop a small effect into the layout to call `aui.threads.reload()` once the session resolves.
-
-`useSession` requires `<SessionProvider>` higher in the tree. Wrap your root layout's client subtree once:
-
-```tsx title="app/providers.tsx"
-"use client";
-
-import { SessionProvider } from "next-auth/react";
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return <SessionProvider>{children}</SessionProvider>;
-}
-```
-
-Then inside the assistant runtime provider, mount a small effect:
-
-```tsx title="app/components/ReloadOnAuth.tsx"
-"use client";
-
-import { useAui } from "@assistant-ui/react";
-import { useSession } from "next-auth/react";
-import { useEffect } from "react";
-
-export function ReloadOnAuth() {
-  const aui = useAui();
-  const { status, data } = useSession();
-  useEffect(() => {
-    if (status === "authenticated") aui.threads.reload();
-  }, [status, data?.user?.id]);
-  return null;
-}
-```
-
-`reload()` discards in-flight responses from superseded calls, so it is safe to invoke on every auth transition.
-
-</Step>
-<Step>
-
-### Run and verify
-
-Sign in. Check:
-
-- `/api/chat` returns `200` with a streaming response when authenticated; `401` when not.
-- `/api/threads` returns only the current user's threads.
-- A second user (incognito tab, different account) sees a different thread list.
-- Signing out and back in does not show the previous user's threads even briefly; if it does, `ReloadOnAuth` isn't mounted or isn't watching the right session field.
-
-</Step>
-</Steps>
-
-## Notes
-
-- **Same-origin cookies.** Browser cookies travel automatically when frontend and API are on the same origin. If you split the API onto a different host, set `credentials: "include"` on every `fetch` and configure CORS on the API.
-- **Edge runtime.** `auth()` runs in Edge contexts only when your DB adapter is edge-compatible. If you use Prisma, Drizzle-over-`pg`, or another non-edge adapter together with Edge route handlers or pre-Next.js 16 middleware, follow Auth.js's [split-config pattern](https://authjs.dev/guides/edge-compatibility): keep a shared `auth.config.ts` without the adapter, instantiate the full `auth.ts` with the adapter elsewhere, and import only the config-instantiated `auth` inside middleware. Next.js 16+ runs `proxy.ts` on Node, so this workaround is generally unnecessary there.
-- **Roles and orgs.** For B2B SaaS where admins see all threads under an org, add `orgId` to the `threads` table, store the user's role in the session via the Auth.js callbacks, and gate `list()` accordingly. The pattern is the same; the `where` clause just gets richer.
-- **OAuth providers.** This page is provider-agnostic. The same `auth()` pattern works whether you wired GitHub, Google, credentials, or a passkey provider in `auth.ts`.
-
-## Related
-
-<Cards>
-  <Card
-    title="Custom thread persistence"
-    description="The persistence story this page assumes; required for per-user threads outside AssistantCloud."
-    href="/docs/integrations/persistence/custom-adapter"
-  />
-  <Card
-    title="AssistantCloud"
-    description="The managed alternative; cloud handles JWT exchange with Clerk, Auth0, Supabase, Firebase."
-    href="/docs/cloud"
-  />
-  <Card
-    title="Threads (concepts)"
-    description="The full RemoteThreadListAdapter contract and reload-on-auth pattern."
-    href="/docs/runtimes/concepts/threads"
-  />
-</Cards>

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

@@ -1,88 +0,0 @@
----
-title: Vercel AI SDK Integration
-description: Wire the Vercel AI SDK into a React chat UI with assistant-ui — useChat, streaming, tools, attachments, multi-step agents, and persistence covered end-to-end.
----
-
-import { VercelIcon } from "@/components/icons/vercel";
-
-[Vercel AI SDK](https://ai-sdk.dev/) is the most common framework people pair with assistant-ui. The full setup, attachments, persistence, tool-call patterns, and version notes are documented under [runtimes/ai-sdk](/docs/runtimes/ai-sdk/overview); this page is the entry point in the integrations tree for discoverability and architecture context.
-
-<Callout type="info">
-If you arrived here looking to wire up your first chat: jump to [AI SDK v7 quickstart](/docs/runtimes/ai-sdk/v7). This page is a high-level pointer.
-</Callout>
-
-## Where it slots in
-
-```mermaid
-flowchart LR
-    client["client"]
-    runtime["useChatRuntime (react-ai-sdk)<br/>(thread state · tool calls · attachments<br/>speech · dictation · feedback adapters)"]
-    api["/api/chat<br/>(streamText)"]
-    provider["provider"]
-
-    client --> runtime --> api --> provider
-```
-
-`@assistant-ui/react-ai-sdk` wraps the AI SDK's `useChat` hook and exposes it as an assistant-ui runtime. The runtime owns conversation state on the client; your `/api/chat` route returns a UI message stream from `streamText`. Everything else (tools, attachments, observability, gateways, custom persistence) layers on top of this base.
-
-## Pick a version
-
-Four versions of `ai` are supported. New projects should pick **v7**; v6, v5, and v4 are documented for migration and existing apps that haven't upgraded.
-
-<Cards>
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="AI SDK v7 (current)"
-    description="Requires ai@^7 and @ai-sdk/react@^4. Async convertToModelMessages, tool inputSchema, toUIMessageStreamResponse."
-    href="/docs/runtimes/ai-sdk/v7"
-  />
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="AI SDK v6 (legacy)"
-    description="Requires ai@^6 and @ai-sdk/react@^3. Async convertToModelMessages, tool inputSchema, toUIMessageStreamResponse."
-    href="/docs/runtimes/ai-sdk/v6-legacy"
-  />
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="AI SDK v5 (legacy)"
-    description="Requires ai@^5 and @ai-sdk/react@^2. Synchronous convertToModelMessages, transitional API."
-    href="/docs/runtimes/ai-sdk/v5-legacy"
-  />
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="AI SDK v4 (legacy)"
-    description="The original useChat-based path. Maintained for migration only."
-    href="/docs/runtimes/ai-sdk/v4-legacy"
-  />
-</Cards>
-
-## When to pick AI SDK
-
-AI SDK is the default choice for new projects on Next.js, Remix, or any framework with a Node-compatible API route. Pick it when:
-
-- You want a single direct path from the chat UI to your model with the smallest possible code surface.
-- You will compose with a framework like [Mastra](/docs/integrations/frameworks/mastra/overview), an [observability tool](/docs/integrations/observability/helicone), an [LLM gateway](/docs/integrations/gateways), or [tools through MCP](/docs/tools/mcp), all of which assume an AI SDK route.
-- You want first-party `frontendTools`, attachments, multi-step tool calls, token-usage metadata, and persisted history via `withFormat`.
-
-If you need streaming agent state (subgraph events, generative UI messages), look at [LangGraph](/docs/runtimes/langgraph/overview) instead. If you have a different protocol-shaped backend (A2A, AG-UI, OpenCode), see [pick a runtime](/docs/runtimes/pick-a-runtime).
-
-## Related
-
-<Cards>
-  <Card
-    icon={<VercelIcon width={20} height={20} />}
-    title="AI SDK runtime overview"
-    description="The full runtime documentation and version selector."
-    href="/docs/runtimes/ai-sdk/overview"
-  />
-  <Card
-    title="Pick a runtime"
-    description="Decision guide if you're not sure AI SDK is the right runtime."
-    href="/docs/runtimes/pick-a-runtime"
-  />
-  <Card
-    title="Mastra"
-    description="The other framework integration in this section. Wired through AI SDK."
-    href="/docs/integrations/frameworks/mastra/overview"
-  />
-</Cards>