docs: restructure OpenUI Cloud API guides

docs/content/docs/openui-cloud/api/artifacts.mdx

@@ -0,0 +1,76 @@
+---
+title: Chat Completions (Artifacts)
+description: "Generate and edit standalone OpenUI Cloud presentations and reports with a Chat Completions-compatible endpoint."
+---
+
+The Artifact Chat Completions API generates a standalone slide deck or report as an OpenUI Lang program. Use it when the artifact lifecycle is separate from an agent's Responses stream.
+
+**Endpoint:** `POST https://api.thesys.dev/v1/artifact/chat/completions`
+
+Use the `artifactClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration.
+
+## Generate an artifact
+
+Every request includes `metadata.thesys` as a JSON string with your artifact `id` and a `c1_artifact_type` of `"slides"` or `"report"`.
+
+```ts
+const artifact = await artifactClient.chat.completions.create({
+  model: "openai/gpt-5",
+  messages: [{ role: "user", content: "Create a three-slide deck on Q4 results." }],
+  metadata: {
+    thesys: JSON.stringify({
+      id: "art_1",
+      c1_artifact_type: "slides",
+    }),
+  },
+});
+
+const program = artifact.choices[0].message.content;
+```
+
+The response content is a raw OpenUI Lang program rooted at `SlideShow` or `ReportView`. OpenUI Cloud validates and repairs it before returning it. Set `stream: true` to receive the program progressively.
+
+## Render an artifact
+
+Render the returned program with the matching managed viewer:
+
+```tsx
+import { Presentation, Report } from "@openuidev/thesys";
+import "@openuidev/thesys/styles.css";
+
+export function Artifact({ kind, program }: { kind: "slides" | "report"; program: string }) {
+  return kind === "slides" ? (
+    <Presentation response={program} preview={false} />
+  ) : (
+    <Report response={program} preview={false} />
+  );
+}
+```
+
+Pass `isStreaming` while accumulating a streamed program.
+
+## Edit an artifact
+
+Send the current OpenUI Lang program as an assistant message, describe the change in the next user message, and set `is_edit: true`.
+
+```ts
+const edited = await artifactClient.chat.completions.create({
+  model: "openai/gpt-5",
+  messages: [
+    { role: "assistant", content: previousProgram },
+    { role: "user", content: "Make slide 2 about European revenue." },
+  ],
+  metadata: {
+    thesys: JSON.stringify({
+      id: "art_1",
+      c1_artifact_type: "slides",
+      is_edit: true,
+    }),
+  },
+  stream: true,
+});
+```
+
+The response is a patch-mode OpenUI Lang program merged against the assistant-message base.
+
+Use the [Responses API](/docs/openui-cloud/api/responses#generate-slides-and-reports) instead when artifacts should be stored, opened, and edited as part of a persistent agent conversation.

docs/content/docs/openui-cloud/api/chat-completions.mdx

@@ -0,0 +1,129 @@
+---
+title: Chat Completions (Embed)
+description: "Use the OpenAI-compatible embed endpoint for text, managed or self-hosted generative UI, and function tools."
+---
+
+The Embed Chat Completions API is a drop-in endpoint for applications that already use `chat.completions.create()`. It preserves the standard message format and supports text or OpenUI Lang responses.
+
+**Endpoint:** `POST https://api.thesys.dev/v1/embed/chat/completions`
+
+Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration.
+
+## Make a managed UI request
+
+Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library.
+
+```ts title="server.ts"
+import { generateSystemPrompt } from "@openuidev/thesys-server";
+
+const completion = await embedClient.chat.completions.create({
+  model: "openai/gpt-5",
+  messages: [
+    { role: "system", content: generateSystemPrompt() },
+    { role: "user", content: "Compare quarterly revenue by region." },
+  ],
+});
+
+console.log(completion.choices[0].message.content);
+```
+
+The returned message content is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and custom component workflow.
+
+## Stream and render responses
+
+Set `stream: true` on the server. In the browser, pair the Chat Completions stream adapter with the OpenAI message format:
+
+```tsx title="cloud-chat.tsx"
+"use client";
+
+import { AgentInterface, fetchLLM, openAIAdapter, openAIMessageFormat } from "@openuidev/react-ui";
+import { chatLibrary } from "@openuidev/thesys";
+import "@openuidev/thesys/styles.css";
+
+const llm = fetchLLM({
+  url: "/api/chat",
+  streamAdapter: openAIAdapter(),
+  messageFormat: openAIMessageFormat,
+});
+
+export function Chat() {
+  return <AgentInterface llm={llm} componentLibrary={chatLibrary} />;
+}
+```
+
+Use `openAIAdapter()` when your route preserves the raw `data:` SSE response. If it returns the OpenAI SDK stream through `.toReadableStream()` instead, use `openAIReadableStreamAdapter()`. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats) for the exact pairings.
+
+## Manage conversation history
+
+Chat Completions is message-based. Keep the conversation in your application and include the system message plus the relevant `user`, `assistant`, and `tool` messages on every turn.
+
+The [Conversations API](/docs/openui-cloud/api/conversations) integrates with Responses, not Embed Chat Completions. Choose Responses when you want Cloud-managed persistent history.
+
+## Use function tools
+
+Embed Chat Completions accepts `function` tools only and does not execute them. Run the standard loop in your application:
+
+1. Send the messages and function declarations.
+2. Read `tool_calls` from the assistant message.
+3. Execute each function in your application.
+4. Append the assistant tool-call message and each `role: "tool"` result.
+5. Repeat until the model returns a final response.
+
+Hosted `web_search`, `image_search`, remote MCP, and artifacts-as-tool are available on the [Responses API](/docs/openui-cloud/api/responses#use-tools). For standalone slides or reports, use [Chat Completions for artifacts](/docs/openui-cloud/api/artifacts).
+
+## Use other generation modes
+
+### Plain text passthrough
+
+Use a `{provider}/{model}` model ID without the managed `generateSystemPrompt()` sentinel. OpenUI Cloud forwards your messages and system prompt without injecting a generative UI prompt or component schema.
+
+```ts
+const completion = await embedClient.chat.completions.create({
+  model: "openai/gpt-5",
+  messages: [
+    { role: "system", content: "You are a concise product analyst." },
+    { role: "user", content: "Summarize the risks in this launch plan." },
+  ],
+});
+
+console.log(completion.choices[0].message.content);
+```
+
+OpenAI, Anthropic, and Google model IDs route to those providers. Unknown providers route through OpenRouter.
+
+### Self-hosted generative UI
+
+Compile the complete system prompt in your application from a generated OpenUI library spec. The endpoint forwards that prompt verbatim; the model returns OpenUI Lang for your client-side renderer.
+
+```ts
+import { generateSystemPrompt } from "@openuidev/lang-core";
+import library from "./generated/library.spec.json";
+
+const completion = await embedClient.chat.completions.create({
+  model: "openai/gpt-5",
+  messages: [
+    {
+      role: "system",
+      content: generateSystemPrompt({
+        library,
+        promptOptions,
+      }),
+    },
+    ...messages,
+  ],
+  stream: true,
+});
+```
+
+In this mode, prompt assembly, output validation, and rendering are owned by your application.
+
+### Request-level provider key
+
+For a request-level self-hosted key flow, encrypt the provider key with `POST /encryption/encrypt`, then include this object in the request body:
+
+```ts
+byok: {
+  provider,
+  encryptedApiKey,
+}
+```

docs/content/docs/openui-cloud/api/conversations.mdx

@@ -0,0 +1,93 @@
+---
+title: Conversations API
+description: "Create persistent OpenUI Cloud conversations, inspect their items, and connect them to Responses and Agent Interface."
+---
+
+The Conversations API stores persistent threads and their items. Responses can read and append to a conversation, while `AgentInterface` uses the same API to list threads and reload messages.
+
+**Base URL:** `https://api.thesys.dev/v1`
+
+Use the `conversationClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication and the shared OpenAI SDK clients.
+
+<Callout type="info">
+  Conversations integrate with the Responses API. Embed Chat Completions applications own and resend
+  their own `messages` history.
+</Callout>
+
+## Create a conversation
+
+Create the conversation before the first stored response:
+
+```ts
+const conversation = await conversationClient.conversations.create({
+  metadata: { workspace: "acme" },
+});
+```
+
+Then send only the new turn to Responses and set `store: true`:
+
+```ts
+import { generateSystemPrompt } from "@openuidev/thesys-server";
+
+const response = await embedClient.responses.create({
+  model: "openai/gpt-5",
+  conversation: conversation.id,
+  input: "Compare quarterly revenue by region.",
+  instructions: generateSystemPrompt(),
+  store: true,
+  stream: true,
+});
+```
+
+Every later response with the same `conversation` ID can use the stored context without resending the full history.
+
+## Read conversation items
+
+List the messages, tool calls, and tool outputs stored in a conversation:
+
+```ts
+const page = await conversationClient.conversations.items.list(conversation.id, {
+  order: "asc",
+  limit: 100,
+});
+
+for (const item of page.data) {
+  console.log(item.type, item.id);
+}
+```
+
+The OpenAI SDK also exposes `retrieve`, `update`, and `delete` for conversations, and create, retrieve, list, and delete operations for conversation items.
+
+## Endpoint summary
+
+| Method                    | Path                                                  | Purpose                                     |
+| ------------------------- | ----------------------------------------------------- | ------------------------------------------- |
+| `GET` / `POST`            | `/v1/conversations`                                   | List or create conversations.               |
+| `GET` / `POST` / `DELETE` | `/v1/conversations/{conversation_id}`                 | Retrieve, update, or delete a conversation. |
+| `GET` / `POST`            | `/v1/conversations/{conversation_id}/items`           | List or add conversation items.             |
+| `GET` / `DELETE`          | `/v1/conversations/{conversation_id}/items/{item_id}` | Retrieve or delete one item.                |
+
+Server-side requests authenticate with the API key described in the [API overview](/docs/openui-cloud/api/overview#authenticate).
+
+## Connect Agent Interface
+
+In the browser, use `useOpenuiCloudStorage()` instead of calling the raw endpoints. It lists conversations, loads their items, and persists artifact state for `AgentInterface`.
+
+```tsx
+import { AgentInterface } from "@openuidev/react-ui";
+import { useOpenuiCloudStorage } from "@openuidev/thesys";
+
+export function Chat() {
+  const storage = useOpenuiCloudStorage({
+    token: "/api/frontend-token",
+    apiBaseUrl: "https://api.thesys.dev",
+    features: { artifact: true },
+  });
+
+  return <AgentInterface llm={llm} storage={storage} />;
+}
+```
+
+The `/api/frontend-token` server route mints a short-lived token with `POST /v1/frontend-tokens`, binding it to your authenticated `user_id` and optional `app_id`. The browser sends that token as `x-thesys-frontend-token`; the server API key never leaves your backend.
+
+Use the current [frontend-token route](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/app/api/frontend-token/route.ts) and [Cloud storage setup](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/components/cloud-chat.tsx) as complete references.

docs/content/docs/openui-cloud/api/overview.mdx

@@ -0,0 +1,71 @@
+---
+title: API Overview
+description: "Choose an OpenUI Cloud API and configure the shared authentication, clients, models, and persistence behavior."
+---
+
+OpenUI Cloud exposes four related API surfaces. Choose the generation shape and state model that fit your application, then use the focused API guide for implementation details.
+
+## Choose an API
+
+| API                                                                 | Endpoint                             | Use it for                                                                                                            |
+| ------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| [Responses](/docs/openui-cloud/api/responses)                       | `POST /v1/embed/responses`           | New agent applications, hosted tools, persistent conversations, and artifacts inside the agent stream.                |
+| [Chat Completions (Embed)](/docs/openui-cloud/api/chat-completions) | `POST /v1/embed/chat/completions`    | Existing Chat Completions applications, plain text, managed or self-hosted generative UI, and app-run function tools. |
+| [Chat Completions (Artifacts)](/docs/openui-cloud/api/artifacts)    | `POST /v1/artifact/chat/completions` | Standalone slide or report generation and explicit program-based edits.                                               |
+| [Conversations](/docs/openui-cloud/api/conversations)               | `/v1/conversations`                  | Persistent Responses threads, items, and the storage plane used by `AgentInterface`.                                  |
+
+Responses is the recommended starting point for new agent applications. The two Chat Completions endpoints let existing integrations keep their message format, while Conversations provides persistent state for Responses.
+
+## Authenticate
+
+Create an API key in the [Thesys console](https://console.thesys.dev/keys) and configure `THESYS_API_KEY` on your server. Server-side requests use:
+
+```http
+Authorization: Bearer $THESYS_API_KEY
+```
+
+Never expose this key to browser code. Browser access to conversations and artifacts uses a scoped, short-lived frontend token instead; see the [Conversations API](/docs/openui-cloud/api/conversations#connect-agent-interface).
+
+## Configure the clients
+
+The generation endpoints and core Conversations operations are compatible with the stock OpenAI SDK. Use a client for each base URL your application needs:
+
+```ts title="lib/openui-cloud.ts"
+import OpenAI from "openai";
+
+const common = { apiKey: process.env.THESYS_API_KEY };
+
+export const embedClient = new OpenAI({
+  ...common,
+  baseURL: "https://api.thesys.dev/v1/embed",
+});
+
+export const artifactClient = new OpenAI({
+  ...common,
+  baseURL: "https://api.thesys.dev/v1/artifact",
+});
+
+export const conversationClient = new OpenAI({
+  ...common,
+  baseURL: "https://api.thesys.dev/v1",
+});
+```
+
+The Embed and Artifact generation endpoints support streaming and non-streaming requests.
+
+## Choose a state model
+
+| Flow                                            | Where history lives                                                 |
+| ----------------------------------------------- | ------------------------------------------------------------------- |
+| Responses with `conversation` and `store: true` | OpenUI Cloud stores the persistent conversation and response items. |
+| Responses with `previous_response_id`           | OpenUI Cloud chains stored responses without a named conversation.  |
+| Responses with full `input` history             | Your application stores and resends history.                        |
+| Embed Chat Completions                          | Your application stores and resends the `messages` array.           |
+| Artifact Chat Completions                       | Each edit request includes the current artifact program explicitly. |
+
+## Shared configuration
+
+- Use `{provider}/{model}` model IDs across generation endpoints. See [Models and BYOK](/docs/openui-cloud/models-and-byok) for supported models and provider credentials.
+- Use the built-in chat library or provide your own components. See [Component Library](/docs/openui-cloud/build/component-library).
+- Keep generation behind a server route and match the browser adapter to the selected response protocol. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats).
+- For the relationship between generation, storage, and rendering, see [How it works](/docs/openui-cloud/how-it-works).