e.stopPropagation()}>
@@ -47,63 +86,37 @@ export function ChatModal({ onClose }: ChatModalProps) {
-
- {
- const response = await fetch("/api/chat", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({
- messages: openAIMessageFormat.toApi(messages),
- }),
- signal: abortController.signal,
- });
-
- if (!response.ok) {
- const err = await response
- .clone()
- .json()
- .catch(() => ({}));
- if (isDemoCreditsErrorPayload((err as { error?: unknown }).error)) {
- setShowOverviewCreditsDialog(true);
- return new Response("data: [DONE]\n\n", {
- headers: { "Content-Type": "text/event-stream" },
- });
- }
- }
-
- return response;
- }}
- streamProtocol={openAIAdapter()}
+
- Pre-built chat layouts (Copilot, Fullscreen, Bottom Tray) or build custom UIs with
- headless hooks. Fully themeable and accessible out of the box.
+ Drop in AgentInterface — a production-ready artifact chat surface with thread
+ history, conversation starters, and streaming — or build custom UIs with headless hooks.
+ Fully themeable and accessible out of the box.
-
-
-
+
+## Accessing conversations
+
+To build your own thread switcher or history view, read the data with hooks instead of touching storage. `useThread` selects from the current thread; `useThreadList` selects from all threads.
+
+```tsx
+import { useThread, useThreadList } from "@openuidev/react-ui";
+
+function ChatCount() {
+ const count = useThreadList((s) => s.threads.length);
+ return {count} chats;
+}
+```
+
+Both are selector hooks: pass a function that picks the slice you need, and the component re-renders only when that slice changes. They work anywhere inside `AgentInterface`. See [Hooks](/docs/agent/reference/hooks) for the full state.
+
+{message.content ?? ""}
;
+}
+```
+
+The component re-renders as the reply streams in, with `content` growing token by token. A `UserMessage` works the same way without `isStreaming`. Its `content` may be a string or, for multimodal input, an array.
+
+## A custom AssistantMessage
+
+A complete renderer that adds a copy button while still rendering markdown:
+
+```tsx
+import { AgentInterface, type AssistantMessage } from "@openuidev/react-ui";
+import ReactMarkdown from "react-markdown";
+
+function CustomAssistantMessage({ message }: { message: AssistantMessage }) {
+ const text = message.content ?? "";
+ return (
+
+ {text}
+
+
+ );
+}
+
+
+
+## Precedence
+
+When a message renders, `AgentInterface` picks the first matching renderer:
+
+1. **`components`:** your explicit override, when set for that message.
+2. **`componentLibrary` (GenUI):** rich rendering so the model can emit components inline.
+3. **Built-in default:** markdown for assistant, plain text for user, tool calls inline.
+
+The props compose. Set `components.AssistantMessage` and your component wins for assistant messages, while user messages still flow through GenUI or the default.
\ No newline at end of file
diff --git a/docs/content/docs/agent/customize/sidebar.mdx b/docs/content/docs/agent/customize/sidebar.mdx
new file mode 100644
index 000000000..8943e77b8
--- /dev/null
+++ b/docs/content/docs/agent/customize/sidebar.mdx
@@ -0,0 +1,98 @@
+---
+title: Sidebar
+description: Add your own nav items to the left sidebar, or replace it entirely through the Sidebar slot.
+---
+
+The left sidebar holds the header, the thread list, and (when artifact storage is configured) an artifact entry. Add a couple of your own links above the threads, or take over the whole region.
+
+Both go through the `Sidebar` slot. Its children replace the sidebar's inner content, so you re-include the default pieces you want to keep. `SidebarContent` and `SidebarSeparator` are primitives you compose inside the slot, not slots themselves.
+
+## Add nav items above the thread list
+
+The common case: a few of your own links, the default thread list underneath. Pass children to the `Sidebar` slot and re-include `SidebarHeader`, `ArtifactNav`, and `ThreadList`.
+
+```tsx
+import { AgentInterface } from "@openuidev/react-ui";
+import { Home, LayoutDashboard } from "lucide-react";
+
+
+
+## Wire items to pages
+
+A navigating item only changes the route. Pair it with a `Route` to render something there.
+
+```tsx
+
+
+ What can I help you build?
+
diff --git a/docs/content/docs/agent/getting-started/introduction.mdx b/docs/content/docs/agent/getting-started/introduction.mdx
new file mode 100644
index 000000000..a38a4ee66
--- /dev/null
+++ b/docs/content/docs/agent/getting-started/introduction.mdx
@@ -0,0 +1,48 @@
+---
+title: Agent Interface
+description: "A generative-UI toolkit for building agent interfaces in React: interactive components and artifacts inside a complete, streaming chat, on OpenUI Cloud or your own backend."
+---
+
+Agent Interface helps developers ship production agent UIs. Your agent renders interactive components and artifacts (dashboards, slides, reports) inside a complete, streaming chat, on OpenUI Cloud or your own backend.
+
+
+
+## Why Agent Interface?
+
+Building an agent UI from scratch is a lot of work before you ship a single feature. You wire up streaming and thread history, render every message, build the interactive components your agent returns, add panels for richer outputs, theme it all, and make it work on mobile.
+
+Agent Interface gives you that in one component. Give it a component library and your agent renders those components inline, streaming their props as they arrive. Durable outputs like dashboards, slides, and reports become artifacts your users can open, revisit, and edit. Connect it to OpenUI Cloud and it handles conversations, generative UI, and artifacts for you. You can also run it on your own backend.
+
+```tsx
+import { AgentInterface, fetchLLM, openAIResponsesAdapter, openAIConversationMessageFormat } from "@openuidev/react-ui";
+import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
+
+// Point the llm adapter at your backend route.
+const llm = fetchLLM({
+ url: "/api/chat",
+ streamAdapter: openAIResponsesAdapter(),
+ messageFormat: openAIConversationMessageFormat,
+});
+
+export default function App() {
+ return 
+
+## What you get
+
+- **Conversation history.** Threads and messages are stored and reloaded for you. No database to run, no endpoints to write.
+- **Production-grade generative UI.** A pre-tested, responsive, accessible component set. Invalid model output is detected and corrected before the user sees it, and a middleware layer normalizes model quirks so generation stays consistent across providers and model versions.
+- **Prebuilt artifacts.** Reports and presentations the agent generates and renders out of the box, with no renderer to build.
+- **Theming and white-labeling.** Fonts, colors, spacing, and component styles are configurable, so every agent-rendered UI is on-brand by default. Multiple brand configurations are supported.
+- **Production hardening.** Model fallbacks and a degraded mode when a provider is slow or down, version pinning and rollback to a known-good setup, and observability with an audit trail: render success, latency, token usage, and a record of what was rendered for whom.
+
+## Connect
+
+`AgentInterface` connects to Cloud through two props, both wired by the scaffold (or by hand, following the `openui-cloud` example in the repo):
+
+- **`llm`** points at a thin `/api/chat` route in your app that proxies to Cloud's Responses endpoint. Your `THESYS_API_KEY` stays on that route and never reaches the browser. On the client it uses `openAIResponsesAdapter()` with `openAIConversationMessageFormat`.
+- **`storage`** is `useOpenuiCloudStorage()` from `@openuidev/thesys`. It reads conversations and artifacts from Cloud directly, authenticated by a short-lived frontend token your app mints from a `/api/frontend-token` route (so the server key never reaches the browser).
+
+The component set (`chatLibrary`), artifact renderers, and categories also come from `@openuidev/thesys`.
+
+Add your server-side key:
+
+```bash
+THESYS_API_KEY=sk-th-your-key
+```
+
+Generate a key in the [Thesys console](https://console.thesys.dev/keys). See [Quickstart](/docs/agent/getting-started/quickstart) to scaffold a Cloud app.
+
+## OpenUI vs OpenUI Cloud
+
+| | OpenUI (open source) | OpenUI Cloud |
+|---|---|---|
+| Generative UI rendering | ✓ | ✓ |
+| Streaming and progressive rendering | ✓ | ✓ |
+| Production-grade components | Basic | Optimized, cross-browser tested |
+| Prebuilt report and presentation artifacts | ✗ | ✓ |
+| Theming and white-labeling | ✗ | ✓ |
+| Error detection and correction | ✗ | ✓ |
+| Cross-model consistency | ✗ | ✓ |
+| Fallbacks, versioning, observability | ✗ | ✓ |
+
+## Roadmap
+
+Coming next:
+
+- **Document exports.** Download reports and presentations as PDF, DOCX, and PPT.
+- **Live dashboards.** Dashboards backed by your business-specific data.
+- **Manual editing.** Edit generated reports and presentations by hand.
+- **Insights.** See what users ask, where they hit dead ends, and which usage patterns to build for next.
+- **Continual learning and memory.** Cloud learns how individual users prefer information presented and adapts over time.
diff --git a/docs/content/docs/agent/getting-started/quickstart.mdx b/docs/content/docs/agent/getting-started/quickstart.mdx
new file mode 100644
index 000000000..8ef1f7186
--- /dev/null
+++ b/docs/content/docs/agent/getting-started/quickstart.mdx
@@ -0,0 +1,84 @@
+---
+title: Quickstart
+description: Scaffold a working streaming chat agent (conversation history, tools, artifacts, and generative UI) in a few minutes with the OpenUI CLI.
+---
+
+The CLI scaffolds a complete Next.js app: a streaming chat with a sidebar, thread list, composer, and generative UI on by default. You write no boilerplate: create, connect, run.
+
+## 1. Create
+
+Run the create command and answer the prompts. One prompt asks **OpenUI Cloud or self-hosted?** Your choice decides which backend the scaffold wires up.
+
+
+
+ ),
+});
+
+// Best-effort parse of a possibly-partial JSON arg string.
+function tryParse(args: unknown): CodeArtifact | null {
+ if (typeof args !== "string") return null;
+ try {
+ return JSON.parse(args) as CodeArtifact;
+ } catch {
+ return null; // still mid-stream
+ }
+}
+```
+
+A few things to notice:
+
+- **`preview` vs `actual`:** `preview` is the compact card inline in the message; keep it small and give it an affordance that calls `controls.open()`. `actual` is the full view in the detailed-view panel or the artifact page. Here it uses the built-in `CodeBlock` component.
+- **`meta`:** return `meta: null` while streaming so the artifact joins the workspace only once complete; return `{ id, version, heading }` on the final pass to register it. Keep `id` stable across re-runs of the same artifact.
+- **`controls.isStreaming`:** the same component instance is reused across the streaming-to-complete transition, so this is a state swap, not a remount.
+
+## 3. Register it
+
+Hand your renderer to `