docs(cli): document backend framework selection

docs/content/docs/api-reference/cli.mdx

@@ -53,37 +53,56 @@ openui create [options]
 
 **Options**
 
-| Flag                        | Description                                                      |
-| --------------------------- | ---------------------------------------------------------------- |
-| `-n, --name <string>`       | Project name (interactive default: `openui-agent`)               |
-| `-t, --template <template>` | AI backend: `openui-cloud` (recommended) or `openui-self-hosted` |
-| `--api-key <key>`           | OpenUI Cloud API key; skips sign-in for the Cloud setup          |
-| `--auth <method>`           | Cloud auth method: `oauth` or `skip`; `manual` is deprecated     |
-| `--skill`                   | Install the OpenUI agent skill for AI coding assistants          |
-| `--no-skill`                | Skip installing the OpenUI agent skill                           |
-| `--no-install`              | Scaffold without running dependency installation                 |
-| `-i, --immediate`           | Start the development server after installing dependencies       |
-| `--no-immediate`            | Install dependencies without starting the development server     |
-| `--no-interactive`          | Fail instead of prompting for missing input                      |
-| `--agent-name <name>`       | Declare the invoking coding-agent slug (default: `unknown`)      |
-
-When run interactively (default), the CLI prompts for any missing options, installs dependencies with the detected package manager, starts the development server, and opens its local URL in the default browser. There is no separate start-server prompt; pass `--no-immediate` to install and exit instead. For most prototypes and evaluations, start with **OpenUI Cloud, the recommended default**: hosted models, managed conversation history and streaming, built-in tools, and ready-to-use reports and presentations without operating the model, storage, or artifact infrastructure. Choose **self-hosted** when owning the OpenAI-compatible provider, AI route, and persistence is a requirement.
+| Flag                              | Description                                                      |
+| --------------------------------- | ---------------------------------------------------------------- |
+| `-n, --name <string>`             | Project name (interactive default: `openui-agent`)               |
+| `-t, --template <template>`       | AI backend: `openui-cloud` (recommended) or `openui-self-hosted` |
+| `--backend-framework <framework>` | Backend integration: `default`, `langgraph`, or `vercel-ai-sdk`  |
+| `--api-key <key>`                 | OpenUI Cloud API key; skips sign-in for the Cloud setup          |
+| `--auth <method>`                 | Cloud auth method: `oauth` or `skip`; `manual` is deprecated     |
+| `--skill`                         | Install the OpenUI agent skill for AI coding assistants          |
+| `--no-skill`                      | Skip installing the OpenUI agent skill                           |
+| `--no-install`                    | Scaffold without running dependency installation                 |
+| `-i, --immediate`                 | Start the development server after installing dependencies       |
+| `--no-immediate`                  | Install dependencies without starting the development server     |
+| `--no-interactive`                | Fail instead of prompting for missing input                      |
+| `--agent-name <name>`             | Declare the invoking coding-agent slug (default: `unknown`)      |
+
+When run interactively (default), the CLI prompts for any missing options, including the backend framework, then asks whether to start the development server after installing dependencies with the detected package manager. The start prompt defaults to yes; answering no preserves the existing install-and-exit behavior and prints the `cd` and dev commands. For most prototypes and evaluations, start with **OpenUI Cloud, the recommended default**: hosted models, managed conversation history and streaming, built-in tools, and ready-to-use reports and presentations without operating the model, storage, or artifact infrastructure. Choose **self-hosted** when owning the OpenAI-compatible provider, AI route, and persistence is a requirement.
 
 In non-interactive mode, dependencies are installed without starting the long-running development server. Pass `--immediate` to install, start, and open the app, or `--no-install` to scaffold only.
 
 `--immediate` and `--no-immediate` are mutually exclusive; passing both exits with an error.
 
 **What it does**
 
-1. Resolves the project name and AI setup
+1. Resolves the project name, AI setup, and backend framework
 2. Copies the selected Next.js template into `<name>/`
 3. Rewrites `workspace:*` dependency versions to `latest`
 4. Writes the relevant `.env` values, including Thesys sign-in/API-key setup for OpenUI Cloud
 5. Optionally installs the [OpenUI agent skill](/docs/openui-lang/agent-skill) for AI coding assistants (e.g. Claude, Cursor, Copilot)
 6. Auto-detects your package manager (npm, pnpm, yarn, bun)
 7. Installs dependencies unless skipped, then optionally starts the development server in the generated directory
 
-The generated project includes a `generate:prompt` script that runs `openui generate` as part of `dev` and `build`.
+**Backend frameworks**
+
+| Value           | OpenUI Cloud route                           | Self-hosted route                        |
+| --------------- | -------------------------------------------- | ---------------------------------------- |
+| `default`       | Direct OpenAI SDK Responses proxy            | Direct OpenAI SDK Chat Completions proxy |
+| `langgraph`     | LangGraph Agent Server + Cloud provider      | LangGraph Agent Server + your provider   |
+| `vercel-ai-sdk` | Vercel AI SDK Next.js agent + Cloud provider | Vercel AI SDK `streamText()` route       |
+
+The CLI applies the selected framework's final route/page files, dependencies, and deployment configuration over the base template. Both Vercel AI SDK variants are standard Next.js deployments with `streamText()`, `toUIMessageStreamResponse()`, and `vercelAIAdapter()`. Both LangGraph variants separate the Agent Server described by `langgraph.json` from the Next.js frontend/proxy. The proxy uses `@openuidev/langchain`, and the browser consumes its AG-UI stream with `agUIAdapter()`.
+
+For both Cloud variants, the framework owns orchestration and application tool execution. OpenUI Cloud is attached as the Responses model provider and conversation store. Reports, presentations, web search, image search, and configured MCP tools remain provider-executed Cloud tools. For either LangGraph template, `pnpm dev` starts the local Agent Server and Next.js together. Deploy the Next.js frontend to Vercel and point `LANGGRAPH_API_URL` at wherever the Agent Server runs.
+
+All four framework routes include a `get_weather` example backed by Open-Meteo. Ask “What’s the weather in Berlin?” to verify the selected framework’s native multi-step tool loop.
+
+**Conversation storage**
+
+Every OpenUI Cloud variant uses OpenUI Cloud as its only durable conversation and artifact store. The browser connects directly through `useOpenuiCloudStorage()` with a short-lived frontend token. The `threadId` sent to `/api/chat` is the Cloud conversation id, and each backend appends model turns to it with `conversation: threadId` and `store: true`. The Vercel AI SDK route does not create a second store. The Cloud LangGraph relay creates and deletes a temporary Agent Server thread for each run; configure a separate LangGraph checkpointer only when graph state, interrupts, or resumable runs must persist independently.
+
+The self-hosted variants do not configure durable storage. `AgentInterface` keeps messages in memory for the current page session and sends that history to `/api/chat`; refreshing the page loses it. The self-hosted LangGraph relay also creates and deletes a temporary Agent Server thread for each run. Pass a storage implementation to `AgentInterface` and back it with your own database when persistence is required; add a LangGraph checkpointer only for graph-specific durable state.
 
 **Agent skill**
 
@@ -102,6 +121,12 @@ pnpx @openuidev/cli@latest create --name my-app --template openui-cloud
 pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted
 pnpx @openuidev/cli@latest create --name my-app --template openui-cloud --immediate
 
+# Select a backend framework explicitly
+pnpx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph
+pnpx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk
+pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph
+pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
+
 # Non-interactive
 pnpx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
 
@@ -118,6 +143,12 @@ bunx @openuidev/cli@latest create
 bunx @openuidev/cli@latest create --name my-app --template openui-cloud
 bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted
 
+# Select a backend framework explicitly
+bunx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph
+bunx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk
+bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph
+bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
+
 # Non-interactive
 bunx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
 
@@ -134,6 +165,12 @@ yarn dlx @openuidev/cli@latest create
 yarn dlx @openuidev/cli@latest create --name my-app --template openui-cloud
 yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted
 
+# Select a backend framework explicitly
+yarn dlx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph
+yarn dlx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk
+yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph
+yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
+
 # Non-interactive
 yarn dlx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
 
@@ -150,6 +187,12 @@ npx @openuidev/cli@latest create
 npx @openuidev/cli@latest create --name my-app --template openui-cloud
 npx @openuidev/cli@latest create --name my-app --template openui-self-hosted
 
+# Select a backend framework explicitly
+npx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph
+npx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk
+npx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph
+npx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
+
 # Non-interactive
 npx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
 

packages/openui-cli/README.md

@@ -12,6 +12,7 @@ It currently supports two workflows:
 - scaffolding a new OpenUI app from one of two templates:
   - **OpenUI Cloud (recommended)** — hosted models with managed conversations, streaming, built-in tools, and ready-to-use report and presentation artifacts
   - **Self-hosted** — bring an OpenAI-compatible model key and own the AI route and persistence
+- keeping the default minimal SDK route or adding a LangGraph or Vercel AI SDK backend to either template
 - generating a system prompt or JSON Schema from a `createLibrary()` export
 
 ## Install
@@ -39,6 +40,15 @@ npx @openuidev/cli@latest create --template openui-cloud
 npx @openuidev/cli@latest create --template openui-self-hosted
 ```
 
+Choose a backend framework directly (the default is `default`, the template's minimal SDK route):
+
+```bash
+npx @openuidev/cli@latest create --template openui-cloud --backend-framework langgraph
+npx @openuidev/cli@latest create --template openui-cloud --backend-framework vercel-ai-sdk
+npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework langgraph
+npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework vercel-ai-sdk
+```
+
 Generate a prompt from a library file:
 
 ```bash
@@ -65,10 +75,11 @@ Options:
 
 - `-n, --name <string>`: Project name (interactive default: `openui-agent`)
 - `-t, --template <template>`: AI backend — `openui-cloud` (managed) or `openui-self-hosted` (bring your provider)
+- `--backend-framework <framework>`: API route implementation — `default`, `langgraph`, or `vercel-ai-sdk`
 - `--skill`: Install the OpenUI agent skill for AI coding assistants
 - `--no-skill`: Skip installing the OpenUI agent skill
 - `--no-install`: Scaffold without running the package install
-- `-i, --immediate`: Start the development server after installing dependencies
+- `-i, --immediate`: Start the development server after installing dependencies; the CLI refuses to start when the template's required API key is unavailable
 - `--no-immediate`: Install dependencies without starting the development server
 - `--no-interactive`: Fail instead of prompting for missing required input
 - `--api-key <key>`: (cloud template) OpenUI Cloud API key; skips sign-in
@@ -81,6 +92,7 @@ What it does:
 
 - prompts for the project name, defaulting to `openui-agent`, if you do not pass `--name`
 - uses the `openui-cloud` template when you do not pass `--template` (interactive runs no longer ask; `--template openui-self-hosted` still works)
+- prompts for a backend framework after the template; non-interactive usage defaults to `default`
 - copies the bundled template into a new directory
 - rewrites monorepo-local dependencies (`workspace:`, `file:`, `catalog:`) in the generated `package.json` to `latest`
 - installs dependencies automatically using the detected package manager (unless `--no-install`)
@@ -94,6 +106,28 @@ What it does:
 - **OpenUI Cloud (recommended default)** — start here for prototypes and evaluations. You get hosted models, managed conversation history and streaming, built-in tools, and ready-to-use report and presentation artifacts without operating the model, storage, or artifact infrastructure.
 - **Self-hosted** — choose this when owning the OpenAI-compatible provider integration, AI route, and persistence is a requirement. It is not offered as an interactive choice; request it with `--template openui-self-hosted`.
 
+#### Backend frameworks
+
+| Value           | OpenUI Cloud route                           | Self-hosted route                        |
+| --------------- | -------------------------------------------- | ---------------------------------------- |
+| `default`       | Direct OpenAI SDK Responses proxy            | Direct OpenAI SDK Chat Completions proxy |
+| `langgraph`     | LangGraph Agent Server + Cloud provider      | LangGraph Agent Server + your provider   |
+| `vercel-ai-sdk` | Vercel AI SDK Next.js agent + Cloud provider | Vercel AI SDK `streamText()` route       |
+
+The default implementation is part of each base template. For LangGraph or Vercel AI SDK, the CLI applies one backend overlay containing the final files plus a manifest for its dependencies, scripts, removals, and onboarding text. Both Vercel AI SDK variants are standard Next.js deployments whose `streamText()` result returns `toUIMessageStreamResponse()` for `vercelAIAdapter()`. Both LangGraph variants separate the Agent Server described by `langgraph.json` from the Next.js frontend/proxy. The proxy uses `@openuidev/langchain`, and the browser consumes its AG-UI stream with `agUIAdapter()`.
+
+In both Cloud framework variants, the selected framework owns the agent orchestration and application tool loop. OpenUI Cloud is attached as the Responses model provider and conversation store. Reports, presentations, web search, image search, and configured MCP tools remain provider-executed Cloud tools, while application tools such as `get_weather` execute inside LangGraph or the Vercel AI SDK. Choosing a Cloud framework does not configure a user-owned model provider; choose `openui-self-hosted` for that.
+
+For either generated LangGraph app, `pnpm dev` starts both Next.js and the local Agent Server. Deploy the Next.js frontend to Vercel, then point `LANGGRAPH_API_URL` at wherever the Agent Server runs. The Cloud graph needs `THESYS_API_KEY`; the self-hosted graph needs the selected provider credentials such as `OPENAI_API_KEY`.
+
+Every Cloud route includes `get_weather` as its example app-owned function tool. The LangGraph and Vercel AI SDK variants define and execute that tool through the selected framework while leaving Cloud-owned tools unchanged. The two self-hosted framework routes include the same weather example and run it through their native multi-step tool loops, making the selected backend directly testable after scaffolding.
+
+#### Conversation storage
+
+Every OpenUI Cloud variant uses OpenUI Cloud as its only durable conversation and artifact store. The browser connects directly through `useOpenuiCloudStorage()` with a short-lived frontend token, and `/api/chat` appends each turn to the same Cloud conversation with `conversation: threadId` and `store: true`. Vercel does not add a second store. The Cloud LangGraph relay creates a temporary Agent Server thread for each run and deletes it afterward; that thread is not the chat-history store. Configure a LangGraph checkpointer separately only when the graph itself needs durable state, interrupts, or resumable runs.
+
+The self-hosted variants do not configure durable storage. `AgentInterface` keeps the conversation in memory for the current page session and sends that history to `/api/chat`; refreshing the page loses it. The self-hosted LangGraph relay also creates and deletes a temporary Agent Server thread for each run. Pass a storage implementation to `AgentInterface` and back it with your own database when persistence is required; add a LangGraph checkpointer only for graph-specific durable state.
+
 #### Template-specific `.env`
 
 - **OpenUI Cloud** — obtains an OpenUI Cloud API key and writes `THESYS_API_KEY` plus `DEMO_USER_ID=demo-user` to `.env`. The key is resolved by, in order:
@@ -109,7 +143,12 @@ Examples:
 
 ```bash
 openui create
+openui create --name my-app --template openui-self-hosted
+openui create --name my-app --template openui-self-hosted --backend-framework langgraph
+openui create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
 openui create --name my-app --template openui-cloud --auth oauth
+openui create --name my-app --template openui-cloud --backend-framework langgraph --auth oauth
+openui create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk --auth oauth
 openui create --name my-app --template openui-cloud --api-key tk_your_key
 openui create --name my-app --template openui-self-hosted
 openui create --name my-app --template openui-cloud --immediate