@assistant-ui/mcp-docs-server 0.1.31 → 0.1.33

package/.docs/organized/code-examples/with-chain-of-thought.md

@@ -3,46 +3,132 @@
 ## app/api/chat/route.ts
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
+import { createOpenAI } from "@ai-sdk/openai";
 import {
   streamText,
   convertToModelMessages,
   tool,
   stepCountIs,
   zodSchema,
+  createUIMessageStream,
+  JsonToSseTransformStream,
 } from "ai";
-import type { UIMessage } from "ai";
+import type { UIMessage, UIMessageStreamWriter } from "ai";
 import { frontendTools } from "@assistant-ui/react-ai-sdk";
 import { z } from "zod";
 
 export const maxDuration = 30;
 
+type SearchResult = { id: string; url: string; title: string };
+
+const searchSources = (query: string): SearchResult[] => {
+  const q = query.toLowerCase();
+  if (q.includes("fibonacci")) {
+    return [
+      {
+        id: "src-fib-1",
+        url: "https://en.wikipedia.org/wiki/Fibonacci_number",
+        title: "Fibonacci number (Wikipedia)",
+      },
+      {
+        id: "src-fib-2",
+        url: "https://oeis.org/A000045",
+        title: "OEIS A000045: Fibonacci numbers",
+      },
+    ];
+  }
+  if (
+    q.includes("renewable") ||
+    q.includes("energy") ||
+    q.includes("climate")
+  ) {
+    return [
+      {
+        id: "src-iea",
+        url: "https://www.iea.org/reports/renewables-2024",
+        title: "IEA Renewables 2024",
+      },
+      {
+        id: "src-irena",
+        url: "https://www.irena.org/Publications",
+        title: "IRENA Publications",
+      },
+    ];
+  }
+  return [
+    {
+      id: "src-wiki",
+      url: `https://en.wikipedia.org/wiki/Special:Search?search=${encodeURIComponent(query)}`,
+      title: "Wikipedia search results",
+    },
+    {
+      id: "src-web",
+      url: `https://duckduckgo.com/?q=${encodeURIComponent(query)}`,
+      title: `Web results for: ${query}`,
+    },
+  ];
+};
+
 export async function POST(req: Request) {
   const {
     messages,
     tools,
   }: { messages: UIMessage[]; tools: Record<string, any> } = await req.json();
 
+  const uiStream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      if (!process.env.OPENAI_API_KEY) {
+        await streamFallback(writer, messages);
+        return;
+      }
+      await streamModel(writer, messages, tools);
+    },
+  });
+
+  return new Response(
+    uiStream
+      .pipeThrough(new JsonToSseTransformStream())
+      .pipeThrough(new TextEncoderStream()),
+    {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+      },
+    },
+  );
+}
+
+async function streamModel(
+  writer: UIMessageStreamWriter,
+  messages: UIMessage[],
+  frontendToolDefs: Record<string, any>,
+) {
+  const toolNameByCall = new Map<string, string>();
+  const openai = createOpenAI({
+    apiKey: process.env.OPENAI_API_KEY!,
+    ...(process.env.OPENAI_BASE_URL && {
+      baseURL: process.env.OPENAI_BASE_URL,
+    }),
+  });
+
   const result = streamText({
-    // Use a reasoning model to showcase chain of thought
+    // Reasoning model so the chain-of-thought group has real content.
     model: openai("gpt-5.4-mini"),
     messages: await convertToModelMessages(messages),
     stopWhen: stepCountIs(10),
     tools: {
-      // Frontend tools registered via makeAssistantTool (e.g. execute_js)
-      ...frontendTools(tools),
-
-      // Backend-only tools
+      ...frontendTools(frontendToolDefs),
       get_current_weather: tool({
         description: "Get the current weather for a city",
-        inputSchema: zodSchema(
-          z.object({
-            city: z.string(),
-          }),
-        ),
-        execute: async ({ city }) => {
-          return `The weather in ${city} is sunny, 72°F`;
-        },
+        inputSchema: zodSchema(z.object({ city: z.string() })),
+        execute: async ({ city }) => `The weather in ${city} is sunny, 72°F`,
+      }),
+      search_web: tool({
+        description:
+          "Search the web for citations on a topic. Returns a list of source URLs and titles the assistant should consult.",
+        inputSchema: zodSchema(z.object({ query: z.string() })),
+        execute: async ({ query }) => ({ sources: searchSources(query) }),
       }),
     },
     providerOptions: {
@@ -53,9 +139,106 @@ export async function POST(req: Request) {
     },
   });
 
-  return result.toUIMessageStreamResponse({ sendReasoning: true });
+  // Forward model chunks, then synthesize `source-url` parts from each
+  // `search_web` tool output so the UI renders them as `source` parts. OpenAI
+  // does not natively emit `source-url` chunks without web search, so the route
+  // produces them deterministically from the tool result.
+  for await (const chunk of result.toUIMessageStream({ sendReasoning: true })) {
+    writer.write(chunk);
+
+    if (chunk.type === "tool-input-available") {
+      toolNameByCall.set(chunk.toolCallId, chunk.toolName);
+    }
+    if (
+      chunk.type === "tool-output-available" &&
+      toolNameByCall.get(chunk.toolCallId) === "search_web"
+    ) {
+      const output = chunk.output as { sources?: SearchResult[] };
+      for (const source of output.sources ?? []) {
+        writer.write({
+          type: "source-url",
+          sourceId: `${source.id}-${crypto.randomUUID()}`,
+          url: source.url,
+          title: source.title,
+        });
+      }
+    }
+  }
+}
+
+async function streamFallback(
+  writer: UIMessageStreamWriter,
+  messages: UIMessage[],
+) {
+  const lastUserText =
+    messages
+      .filter((m) => m.role === "user")
+      .at(-1)
+      ?.parts.flatMap((p) => (p.type === "text" ? [p.text] : []))
+      .join(" ") ?? "your question";
+
+  const messageId = `msg-${crypto.randomUUID()}`;
+  const reasoningId = `r-${crypto.randomUUID()}`;
+  const textId = `t-${crypto.randomUUID()}`;
+  const toolCallId = `call-${crypto.randomUUID()}`;
+  const sources = searchSources(lastUserText);
+
+  writer.write({ type: "start", messageId });
+  writer.write({ type: "start-step" });
+
+  writer.write({ type: "reasoning-start", id: reasoningId });
+  const reasoning =
+    "OPENAI_API_KEY is not set, so this response is generated deterministically by the route. " +
+    "A real run emits the same chunk shapes from the model: a reasoning step, " +
+    "a search_web tool call, source-url parts derived from the tool output, " +
+    "and a final answer that summarises the sources.";
+  for (const word of reasoning.match(/\S+\s*|\s+/g) ?? [reasoning]) {
+    writer.write({ type: "reasoning-delta", id: reasoningId, delta: word });
+    await sleep(15);
+  }
+  writer.write({ type: "reasoning-end", id: reasoningId });
+
+  writer.write({
+    type: "tool-input-available",
+    toolCallId,
+    toolName: "search_web",
+    input: { query: lastUserText },
+  });
+  await sleep(150);
+  writer.write({
+    type: "tool-output-available",
+    toolCallId,
+    output: { sources },
+  });
+
+  for (const source of sources) {
+    writer.write({
+      type: "source-url",
+      sourceId: `${source.id}-${crypto.randomUUID()}`,
+      url: source.url,
+      title: source.title,
+    });
+  }
+
+  writer.write({ type: "text-start", id: textId });
+  const answer =
+    `\n\nMock answer for: "${lastUserText}". ` +
+    "The badges above are structured `source` message parts emitted as " +
+    "`source-url` chunks, not URLs scraped from text. Set `OPENAI_API_KEY` " +
+    "to switch to a real model run.";
+  for (const word of answer.match(/\S+\s*|\s+/g) ?? [answer]) {
+    writer.write({ type: "text-delta", id: textId, delta: word });
+    await sleep(15);
+  }
+  writer.write({ type: "text-end", id: textId });
+
+  writer.write({ type: "finish-step" });
+  writer.write({ type: "finish" });
 }
 
+const sleep = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
+
 ```
 
 ## app/globals.css
@@ -194,7 +377,8 @@ import "./globals.css";
 
 export const metadata: Metadata = {
   title: "Chain of Thought Example",
-  description: "Example using MessagePrimitive.GroupedParts with AI SDK",
+  description:
+    "Reasoning, tool calls, and source citations rendered as grouped message parts.",
 };
 
 export default function RootLayout({
@@ -218,13 +402,16 @@ export default function RootLayout({
 
 import { type FC, type PropsWithChildren, useState } from "react";
 import { MarkdownText } from "@/components/assistant-ui/markdown-text";
+import { Sources } from "@/components/assistant-ui/sources";
 import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
 import { Button } from "@/components/ui/button";
 import {
-  AuiIf,
   ComposerPrimitive,
+  groupPartByType,
   MessagePrimitive,
+  SuggestionPrimitive,
   ThreadPrimitive,
+  useThread,
 } from "@assistant-ui/react";
 import {
   ArrowDownIcon,
@@ -237,10 +424,14 @@ import {
 export const MyThread: FC = () => {
   return (
     <ThreadPrimitive.Root
-      className="flex h-full flex-col bg-background"
+      className="bg-background flex h-full flex-col"
       style={{ ["--thread-max-width" as string]: "44rem" }}
     >
       <ThreadPrimitive.Viewport className="flex flex-1 flex-col overflow-y-scroll scroll-smooth px-4 pt-8">
+        <ThreadPrimitive.Empty>
+          <ThreadWelcome />
+        </ThreadPrimitive.Empty>
+
         <ThreadPrimitive.Messages>
           {({ message }) => {
             if (message.role === "user") return <UserMessage />;
@@ -269,11 +460,43 @@ const Text: FC<{ text: string }> = ({ text }) => {
   return <p>{text}</p>;
 };
 
+const ThreadWelcome: FC = () => {
+  return (
+    <div className="mx-auto flex w-full max-w-(--thread-max-width) grow flex-col justify-center gap-6">
+      <div>
+        <h1 className="text-2xl font-semibold">
+          What should we think through?
+        </h1>
+      </div>
+      <div className="flex flex-wrap gap-2">
+        <ThreadPrimitive.Suggestions>
+          {() => <ThreadSuggestionItem />}
+        </ThreadPrimitive.Suggestions>
+      </div>
+    </div>
+  );
+};
+
+const ThreadSuggestionItem: FC = () => {
+  return (
+    <SuggestionPrimitive.Trigger send asChild>
+      <Button
+        type="button"
+        variant="ghost"
+        className="bg-background hover:bg-muted h-auto w-full flex-col items-start justify-start gap-1 rounded-2xl border px-4 py-3 text-start text-sm sm:w-[calc(50%-0.25rem)]"
+      >
+        <SuggestionPrimitive.Title className="font-medium" />
+        <SuggestionPrimitive.Description className="text-muted-foreground empty:hidden" />
+      </Button>
+    </SuggestionPrimitive.Trigger>
+  );
+};
+
 const UserMessage: FC = () => {
   return (
     <MessagePrimitive.Root className="mx-auto w-full max-w-(--thread-max-width) py-3">
       <div className="flex justify-end">
-        <div className="max-w-[80%] rounded-2xl bg-primary px-4 py-2 text-primary-foreground">
+        <div className="bg-primary text-primary-foreground max-w-[80%] rounded-2xl px-4 py-2">
           <MessagePrimitive.Parts>
             {({ part }) => {
               if (part.type === "text") return <Text {...part} />;
@@ -291,13 +514,11 @@ const AssistantMessage: FC = () => {
     <MessagePrimitive.Root className="mx-auto w-full max-w-(--thread-max-width) py-3">
       <div className="flex flex-col gap-2 px-2 leading-relaxed">
         <MessagePrimitive.GroupedParts
-          groupBy={(part) => {
-            if (part.type === "reasoning")
-              return ["group-chainOfThought", "group-reasoning"];
-            if (part.type === "tool-call")
-              return ["group-chainOfThought", "group-tool"];
-            return null;
-          }}
+          groupBy={groupPartByType({
+            reasoning: ["group-chainOfThought", "group-reasoning"],
+            "tool-call": ["group-chainOfThought", "group-tool"],
+            source: ["group-sources"],
+          })}
         >
           {({ part, children }) => {
             switch (part.type) {
@@ -309,12 +530,16 @@ const AssistantMessage: FC = () => {
                 return (
                   <PartLayout label="Taking action">{children}</PartLayout>
                 );
+              case "group-sources":
+                return <SourcesLayout>{children}</SourcesLayout>;
               case "text":
                 return <MarkdownText />;
               case "reasoning":
                 return <Reasoning {...part} />;
               case "tool-call":
                 return <ToolCall {...part} />;
+              case "source":
+                return <Sources {...part} />;
               default:
                 return null;
             }
@@ -332,7 +557,7 @@ const ChainOfThoughtGroup: FC<PropsWithChildren> = ({ children }) => {
     <div className="my-2 rounded-lg border">
       <button
         type="button"
-        className="flex w-full cursor-pointer items-center gap-2 px-4 py-2 font-medium text-sm hover:bg-muted/50"
+        className="hover:bg-muted/50 flex w-full cursor-pointer items-center gap-2 px-4 py-2 text-sm font-medium"
         onClick={() => setOpen((o) => !o)}
       >
         {open ? (
@@ -347,6 +572,15 @@ const ChainOfThoughtGroup: FC<PropsWithChildren> = ({ children }) => {
   );
 };
 
+const SourcesLayout: FC<PropsWithChildren> = ({ children }) => {
+  return (
+    <div className="flex flex-wrap items-center gap-1.5">
+      <span className="text-muted-foreground mr-1 text-xs">Sources</span>
+      {children}
+    </div>
+  );
+};
+
 const PartLayout: FC<PropsWithChildren<{ label: string }>> = ({
   children,
   label,
@@ -357,7 +591,7 @@ const PartLayout: FC<PropsWithChildren<{ label: string }>> = ({
     <div className="border-t">
       <button
         type="button"
-        className="flex w-full cursor-pointer items-center gap-2 px-4 py-1.5 text-muted-foreground text-xs hover:bg-muted/50"
+        className="text-muted-foreground hover:bg-muted/50 flex w-full cursor-pointer items-center gap-2 px-4 py-1.5 text-xs"
         onClick={() => setOpen((o) => !o)}
       >
         {open ? (
@@ -374,7 +608,7 @@ const PartLayout: FC<PropsWithChildren<{ label: string }>> = ({
 
 const Reasoning: FC<{ text: string }> = ({ text }) => {
   return (
-    <p className="whitespace-pre-wrap px-4 py-2 text-muted-foreground text-sm italic">
+    <p className="text-muted-foreground px-4 py-2 text-sm whitespace-pre-wrap italic">
       {text}
     </p>
   );
@@ -398,16 +632,18 @@ const ToolCall: FC<{ toolName: string; status: { type: string } }> = ({
 };
 
 const Composer: FC = () => {
+  const isRunning = useThread((state) => state.isRunning);
+
   return (
-    <ComposerPrimitive.Root className="flex w-full flex-col rounded-2xl border border-input bg-background px-1 pt-2 outline-none transition-shadow has-[textarea:focus-visible]:border-ring has-[textarea:focus-visible]:ring-2 has-[textarea:focus-visible]:ring-ring/20">
+    <ComposerPrimitive.Root className="border-input bg-background has-[textarea:focus-visible]:border-ring has-[textarea:focus-visible]:ring-ring/20 flex w-full flex-col rounded-2xl border px-1 pt-2 transition-shadow outline-none has-[textarea:focus-visible]:ring-2">
       <ComposerPrimitive.Input
         placeholder="Send a message..."
-        className="mb-1 max-h-32 min-h-14 w-full resize-none bg-transparent px-4 pt-2 pb-3 text-sm outline-none placeholder:text-muted-foreground"
+        className="placeholder:text-muted-foreground mb-1 max-h-32 min-h-14 w-full resize-none bg-transparent px-4 pt-2 pb-3 text-sm outline-none"
         rows={1}
         autoFocus
       />
       <div className="relative mx-2 mb-2 flex items-center justify-end">
-        <AuiIf condition={(s) => !s.thread.isRunning}>
+        {!isRunning ? (
           <ComposerPrimitive.Send asChild>
             <TooltipIconButton
               tooltip="Send"
@@ -419,8 +655,7 @@ const Composer: FC = () => {
               <ArrowUpIcon className="size-4" />
             </TooltipIconButton>
           </ComposerPrimitive.Send>
-        </AuiIf>
-        <AuiIf condition={(s) => s.thread.isRunning}>
+        ) : (
           <ComposerPrimitive.Cancel asChild>
             <Button
               type="button"
@@ -431,7 +666,7 @@ const Composer: FC = () => {
               <SquareIcon className="size-3 fill-current" />
             </Button>
           </ComposerPrimitive.Cancel>
-        </AuiIf>
+        )}
       </div>
     </ComposerPrimitive.Root>
   );
@@ -446,7 +681,8 @@ const Composer: FC = () => {
 
 import {
   AssistantRuntimeProvider,
-  makeAssistantTool,
+  Tools,
+  type Toolkit,
   useAui,
   AuiProvider,
   Suggestions,
@@ -456,53 +692,56 @@ import { z } from "zod";
 import { MyThread } from "./MyThread";
 import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
 
-const ExecuteJsTool = makeAssistantTool({
-  toolName: "execute_js",
-  description: "Execute JavaScript code and return the result",
-  parameters: z.object({
-    code: z.string().describe("The JavaScript code to execute"),
-  }),
-  execute: async ({ code }) => {
-    try {
-      // biome-ignore lint/security/noGlobalEval: example code
-      const result = eval(code);
-      return { success: true, result: String(result) };
-    } catch (e) {
-      return { success: false, error: String(e) };
-    }
+const toolkit = {
+  execute_js: {
+    type: "frontend",
+    description: "Execute JavaScript code and return the result",
+    parameters: z.object({
+      code: z.string().describe("The JavaScript code to execute"),
+    }),
+    execute: async ({ code }) => {
+      try {
+        const result = eval(code);
+        return { success: true, result: String(result) };
+      } catch (e) {
+        return { success: false, error: String(e) };
+      }
+    },
+    render: ({ args, result, status }) => (
+      <div className="bg-muted/30 my-2 rounded-lg border p-4 text-sm">
+        <p className="mb-1 font-semibold">execute_js</p>
+        <pre className="bg-background rounded p-2 font-mono text-xs whitespace-pre-wrap">
+          {args.code}
+        </pre>
+        {status.type !== "running" && result && (
+          <div className="mt-2 border-t pt-2">
+            <p className="text-muted-foreground font-semibold">
+              {result.success ? "Result:" : "Error:"}
+            </p>
+            <pre className="font-mono text-xs whitespace-pre-wrap">
+              {result.success ? result.result : result.error}
+            </pre>
+          </div>
+        )}
+      </div>
+    ),
   },
-  render: ({ args, result, status }) => (
-    <div className="my-2 rounded-lg border bg-muted/30 p-4 text-sm">
-      <p className="mb-1 font-semibold">execute_js</p>
-      <pre className="whitespace-pre-wrap rounded bg-background p-2 font-mono text-xs">
-        {args.code}
-      </pre>
-      {status.type !== "running" && result && (
-        <div className="mt-2 border-t pt-2">
-          <p className="font-semibold text-muted-foreground">
-            {result.success ? "Result:" : "Error:"}
-          </p>
-          <pre className="whitespace-pre-wrap font-mono text-xs">
-            {result.success ? result.result : result.error}
-          </pre>
-        </div>
-      )}
-    </div>
-  ),
-});
+} satisfies Toolkit;
 
 function MyThreadWithSuggestions() {
   const aui = useAui({
     suggestions: Suggestions([
       {
         title: "Calculate Fibonacci(20)",
-        label: "step by step with code",
-        prompt: "Calculate the 20th Fibonacci number using JavaScript.",
+        label: "with chain of thought",
+        prompt:
+          "Calculate the 20th Fibonacci number using JavaScript and show your reasoning.",
       },
       {
-        title: "What is 2^16?",
-        label: "show your reasoning",
-        prompt: "What is 2 to the power of 16? Show your work step by step.",
+        title: "Research with citations",
+        label: "show sources",
+        prompt:
+          "Research recent developments in renewable energy and cite your sources.",
       },
     ]),
   });
@@ -517,10 +756,12 @@ export default function Home() {
   const runtime = useChatRuntime({
     sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
   });
+  const aui = useAui({
+    tools: Tools({ toolkit }),
+  });
 
   return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <ExecuteJsTool />
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
       <div className="h-full">
         <MyThreadWithSuggestions />
       </div>
@@ -563,12 +804,13 @@ export default function Home() {
 ## next.config.js
 
 ```javascript
+import { withAui } from "@assistant-ui/next";
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   transpilePackages: ["@assistant-ui/react", "@assistant-ui/react-ai-sdk"],
 };
 
-export default nextConfig;
+export default withAui(nextConfig);
 
 ```
 
@@ -586,29 +828,30 @@ export default nextConfig;
     "start": "next start"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.61",
+    "@ai-sdk/openai": "^3.0.67",
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-ai-sdk": "workspace:*",
     "@assistant-ui/react-markdown": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
-    "ai": "^6.0.175",
+    "ai": "^6.0.193",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.14.0",
-    "next": "^16.2.4",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
-    "tailwind-merge": "^3.5.0",
+    "lucide-react": "^1.17.0",
+    "next": "^16.2.6",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "tailwind-merge": "^3.6.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@assistant-ui/next": "workspace:*",
     "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4.2.4",
-    "@types/node": "^25.6.0",
-    "@types/react": "^19.2.14",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
-    "postcss": "^8.5.14",
-    "tailwindcss": "^4.2.4",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.0",
     "tw-animate-css": "^1.4.0",
     "typescript": "^6.0.3"
   }
@@ -616,6 +859,97 @@ export default nextConfig;
 
 ```
 
+## README.md
+
+```markdown
+# Chain of Thought Example
+
+A real chat flow that renders reasoning, tool calls, and source citations as grouped message parts. Demonstrates `MessagePrimitive.GroupedParts` with a nested `groupBy` path, plus structured `source` parts emitted from a search tool.
+
+## Quick start
+
+### Using the CLI
+
+```bash
+npx assistant-ui@latest create my-app --example with-chain-of-thought
+cd my-app
+```
+
+### Environment variables
+
+`OPENAI_API_KEY` is optional. With the key set the route runs a real reasoning model and a `search_web` tool; without it the route streams a deterministic mock response with the same chunk shapes, so the UI is fully demonstrable offline.
+
+Create `.env.local`:
+
+```
+OPENAI_API_KEY=sk-...
+```
+
+### Run
+
+```bash
+npm install
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## What the example demonstrates
+
+| Concern | Where it lives |
+|---|---|
+| Real chat flow with `useChatRuntime` | `app/page.tsx` |
+| Reasoning, tool calls, source citations streamed as message parts | `app/api/chat/route.ts` |
+| Nested adjacency-based grouping with `MessagePrimitive.GroupedParts` | `app/MyThread.tsx` |
+| `Sources` component rendering `source` parts | `app/MyThread.tsx` |
+| Fallback path that runs without an API key | `app/api/chat/route.ts` (`streamFallback`) |
+
+## How parts are grouped
+
+The thread groups three part types under one collapsible "Thinking" section, then renders source badges in a row below it. The grouping is configured on `MessagePrimitive.GroupedParts`:
+
+```tsx
+<MessagePrimitive.GroupedParts
+  groupBy={(part) => {
+    if (part.type === "reasoning") return ["group-chainOfThought", "group-reasoning"];
+    if (part.type === "tool-call") return ["group-chainOfThought", "group-tool"];
+    if (part.type === "source") return ["group-chainOfThought", "group-sources"];
+    return null;
+  }}
+>
+```
+
+Each part is mapped to a nested group key path. Adjacent parts that share a path are coalesced and rendered through the matching `group-*` case in the render function. `null` leaves a part ungrouped.
+
+This is the canonical pattern. For non-adjacent clustering (parts that share an identifier but appear at different positions in the message), see [`/docs/ui/part-grouping`](https://www.assistant-ui.com/docs/ui/part-grouping).
+
+## How sources are emitted
+
+The route emits structured `source-url` chunks; `@assistant-ui/react-ai-sdk` converts them to `source` message parts that the `Sources` component renders as badges. They are not URLs scraped from assistant text.
+
+```ts
+writer.write({
+  type: "source-url",
+  sourceId: "src-1",
+  url: "https://example.com/report",
+  title: "Example report",
+});
+```
+
+In the real path the `search_web` tool returns sources in its output, and the route writes one `source-url` chunk per result immediately after the `tool-output-available` chunk. In the fallback path the same shape is written directly. The UI rendering is identical in both modes.
+
+## Why these features live together
+
+Chain-of-thought, tool calls, and citation sources are the parts of an assistant turn a user typically wants to inspect together. Grouping them under one collapsible keeps the message tidy by default and reveals the full reasoning trail on demand.
+
+## Related documentation
+
+- [Message Part Grouping](https://www.assistant-ui.com/docs/ui/part-grouping)
+- [Sources component](https://www.assistant-ui.com/docs/ui/sources)
+- [AI SDK v6 runtime](https://www.assistant-ui.com/docs/runtimes/ai-sdk/v6)
+
+```
+
 ## tsconfig.json
 
 ```json
@@ -631,6 +965,7 @@ export default nextConfig;
       "@/lib/utils": ["../../packages/ui/src/lib/utils"],
       "@assistant-ui/ui/*": ["../../packages/ui/src/*"],
       "@assistant-ui/*": ["../../packages/*/src"],
+      "@assistant-ui/core/*": ["../../packages/core/src/*"],
       "@assistant-ui/react/*": ["../../packages/react/src/*"],
       "@assistant-ui/tap/*": ["../../packages/tap/src/*"],
       "assistant-stream": ["../../packages/assistant-stream/src"]