jerelvelarde · Oct 9, 2026 · Oct 7, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026
diff --git a/.env.example b/.env.example
@@ -1,9 +1,21 @@
+# Agent settings: place these in apps/agent/.env.
+# Use the key for the selected provider; never expose keys to the browser.
 ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
 
-# Claude model — strong models are required for reliable UI generation
-# Recommended: claude-fable-5 (default), claude-opus-5-5
-# Fallback: gpt-* names route to OpenAI (requires OPENAI_API_KEY)
-LLM_MODEL=claude-fable-5
+# chat-latest follows ChatGPT Instant. gpt-* uses OpenAI; claude-* uses Anthropic.
+# Model access/availability must be verified with your provider.
+# Blank or unsupported prefixes and missing selected-provider keys fail at startup.
+LLM_MODEL=chat-latest
+
+# Jev selects the renderer and visualization before each new user turn.
+TYPESAFE_API_KEY=
+JEV_MODEL=jev-latest
+
+# Frontend settings: place these in apps/app/.env.local.
+# LANGGRAPH_DEPLOYMENT_URL defaults to http://localhost:8123.
+# LANGGRAPH_DEPLOYMENT_URL=http://localhost:8123
+# MCP_SERVER_URL=http://localhost:3100/mcp
 
 # Rate limiting (per IP) — disabled by default
 RATE_LIMIT_ENABLED=false

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,286 +1,44 @@
-# CopilotKit + LangGraph Todo Demo
+# Open Generative UI by CopilotKit
 
-## Purpose
+This repository builds a general assistant experience around **answers you can interact with**: understand a topic, compare options, or make a useful tool. It is not primarily a todo-list template. Existing todo and form tools are compatibility examples, not the product's organizing concept.
 
-This repository serves as both a **showcase** and **template** for building AI agents with CopilotKit and LangGraph. It demonstrates how CopilotKit can drive interactive UI beyond just chat, using a **collaborative todo list** as the primary example.
+## Boundaries and source of truth
 
-**Target audience:** Developers evaluating CopilotKit or starting new projects with AI agents.
+- Frontend: `apps/app/`, Next.js and CopilotKit v2.
+- Agent: `apps/agent/main.py`, `src/prompt.py`, `src/model.py`, and `skills/`.
+- Custom UI: `apps/app/src/components/generative-ui/open-generative-ui/`.
+- Validated host callbacks: `apps/app/src/lib/sandbox/`.
+- Standalone MCP: `apps/mcp/`; its HTML assembler and legacy bridge are separate from the web app.
+- Shared styling: `packages/design-system/`.
 
-## Core Concept
+Use the product name in visible copy. Preserve repository URLs, package names, `openGenerativeUI`, `generateSandboxedUi`, activity/event names, and deployment service names unless a task explicitly migrates them.
 
-The todo list demonstrates **agent-driven UI** where:
-- The agent can manipulate application state (adding todos, updating status, organizing tasks)
-- Users can interact with the same state (editing titles, checking off tasks, deleting todos)
-- Both agent and user changes update the same shared state
-- The UI reactively updates based on agent state changes
+## Agent behavior
 
-This uses CopilotKit's **v2 agent state pattern** where state lives in the agent and syncs to the frontend.
+Choose text for direct answers, native components when their schemas fit, and custom UI when a diagram or interaction helps. There is no mandatory acknowledgement/plan/build/narrate sequence. Distinct sections may use multiple tools; do not repeat a successful build merely because it returned "UI generated".
 
-## Architecture
+Label sample assumptions and distinguish user inputs, retrieved evidence, and calculated values. `query_data` returns a metadata envelope with bundled sample CSV rows and does not apply its query. There is no built-in live weather or business-data connection. Never imply a mock form authenticates or persists data.
 
-This is a **Turborepo monorepo** with three apps:
+Generated controls must work, validate numerical edge cases, support keyboard access and narrow screens, and expose useful errors. Use the user's selected values when sending a deliberate follow-up. Each follow-up is a new turn/output; do not assume a cross-call patch API or persist iframe state through rerenders.
 
-### Repository Structure
+## Streaming contract
 
-```
-apps/
-├── app/                         # Next.js frontend
-│   ├── src/
-│   │   ├── app/
-│   │   │   ├── page.tsx        # Main page - wires up all components
-│   │   │   └── api/copilotkit/ # CopilotKit API route
-│   │   ├── components/
-│   │   │   ├── canvas/         # Todo list UI
-│   │   │   │   ├── index.tsx   # Canvas container
-│   │   │   │   ├── todo-list.tsx    # Todo list with columns
-│   │   │   │   ├── todo-column.tsx  # Column (pending/completed)
-│   │   │   │   └── todo-card.tsx    # Individual todo card
-│   │   │   ├── example-layout/ # Layout: chat + canvas side-by-side
-│   │   │   └── generative-ui/  # Example generative UI components
-│   │   └── hooks/
-│   │       ├── use-generative-ui-examples.tsx  # Example CopilotKit patterns
-│   │       └── use-example-suggestions.tsx     # Chat suggestions
-├── agent/                       # LangGraph Python agent
-│   ├── main.py                  # Agent entry point
-│   └── src/
-│       ├── todos.py             # Todo tools and state schema
-│       └── query.py             # Example data query tool
-└── mcp/                         # MCP (Model Context Protocol) integration
-```
-
-## Key Pattern: Agent State with CopilotKit v2
-
-The todo list uses **CopilotKit v2's agent state pattern** where state lives in the agent backend and syncs bidirectionally with the frontend.
-
-### How It Works
-
-1. **Agent defines state schema and tools** (Python)
-   ```python
-   # apps/agent/src/todos.py
-   class Todo(TypedDict):
-       id: str
-       title: str
-       description: str
-       emoji: str
-       status: Literal["pending", "completed"]
-
-   class AgentState(TypedDict):
-       todos: list[Todo]
-
-   @tool
-   def manage_todos(todos: list[Todo], runtime: ToolRuntime) -> Command:
-       """Manage the current todos."""
-       return Command(update={"todos": todos, ...})
-   ```
-
-2. **Frontend reads from agent state**
-   ```typescript
-   // apps/app/src/components/canvas/index.tsx
-   const { agent } = useAgent();
-
-   return (
-     <TodoList
-       todos={agent.state?.todos || []}
-       onUpdate={(updatedTodos) => agent.setState({ todos: updatedTodos })}
-       isAgentRunning={agent.isRunning}
-     />
-   );
-   ```
-
-3. **User interactions update agent state**
-   ```typescript
-   // User clicks checkbox → frontend calls agent.setState()
-   const toggleStatus = (todo) => {
-     const updated = todos.map(t =>
-       t.id === todo.id ? { ...t, status: t.status === "completed" ? "pending" : "completed" } : t
-     );
-     agent.setState({ todos: updated });
-   };
-   ```
-
-4. **Agent can manipulate state via tools**
-   - The agent calls `manage_todos` tool to update the todo list
-   - Both user and agent changes update the same `agent.state.todos`
-   - Frontend automatically re-renders when state changes
-
-### Why This Pattern?
-
-- **Single source of truth**: State lives in the agent, not duplicated in frontend
-- **Bidirectional sync**: User changes → agent state, Agent changes → UI update
-- **Simple**: No need for separate frontend state management
-- **Observable**: Agent has full visibility into state changes
-
-## Implementation Details
-
-### Agent Backend
-
-**Agent Definition** (`apps/agent/main.py`):
-```python
-from langchain.agents import create_agent
-from copilotkit import CopilotKitMiddleware
-from src.todos import todo_tools, AgentState
-
-agent = create_agent(
-    model="claude-fable-5",
-    tools=[*todo_tools, ...],  # manage_todos, get_todos
-    middleware=[CopilotKitMiddleware()],
-    state_schema=AgentState,  # Defines state shape
-    system_prompt="You are a helpful assistant..."
-)
-```
-
-**Todo Tools** (`apps/agent/src/todos.py`):
-```python
-@tool
-def manage_todos(todos: list[Todo], runtime: ToolRuntime) -> Command:
-    """Manage the current todos."""
-    # Ensure todos have unique IDs
-    for todo in todos:
-        if "id" not in todo or not todo["id"]:
-            todo["id"] = str(uuid.uuid4())
-
-    # Update agent state
-    return Command(update={
-        "todos": todos,
-        "messages": [ToolMessage(...)]
-    })
-
-@tool
-def get_todos(runtime: ToolRuntime):
-    """Get the current todos."""
-    return runtime.state.get("todos", [])
-```
-
-### Frontend
-
-**Canvas Component** (`apps/app/src/components/canvas/index.tsx`):
-```typescript
-export function Canvas() {
-  const { agent } = useAgent();  // CopilotKit v2 hook
-
-  return (
-    <div className="h-full p-8 bg-gray-50">
-      <TodoList
-        // Read state from agent
-        todos={agent.state?.todos || []}
-        // Update state in agent
-        onUpdate={(updatedTodos) => agent.setState({ todos: updatedTodos })}
-        // React to agent execution
-        isAgentRunning={agent.isRunning}
-      />
-    </div>
-  );
-}
-```
-
-**Todo List** (`apps/app/src/components/canvas/todo-list.tsx`):
-```typescript
-export function TodoList({ todos, onUpdate, isAgentRunning }: TodoListProps) {
-  const toggleStatus = (todo: Todo) => {
-    const updated = todos.map((t) =>
-      t.id === todo.id
-        ? { ...t, status: t.status === "completed" ? "pending" : "completed" }
-        : t
-    );
-    onUpdate(updated);  // Calls agent.setState()
-  };
-
-  const addTodo = () => {
-    const newTodo = { id: crypto.randomUUID(), ... };
-    onUpdate([...todos, newTodo]);
-  };
-
-  return (
-    <div className="flex gap-8">
-      <TodoColumn title="To Do" todos={pendingTodos} onAddTodo={addTodo} ... />
-      <TodoColumn title="Done" todos={completedTodos} ... />
-    </div>
-  );
-}
-```
-
-### How State Flows
-
-1. **User adds/edits todo** → Frontend calls `agent.setState({ todos: [...] })`
-2. **Agent state updates** → CopilotKit syncs to backend
-3. **Agent observes change** → Can respond via `manage_todos` tool
-4. **Agent modifies todos** → Calls `manage_todos` tool
-5. **State syncs to frontend** → `agent.state.todos` updates
-6. **UI re-renders** → React sees new state and updates display
+Emit `initialHeight`, `placeholderMessages`, `css`, `html`, `jsFunctions`, `jsExpressions` in that order. Styles belong in `css`; functions and invocations use their separate channels. Those JavaScript channels run as classic scripts, so dynamic imports with await belong inside async functions, never at top level.
 
-**Key insight**: State lives in the agent, frontend just reads/writes to it via CopilotKit hooks.
+Use the existing validated `Websandbox.connection.remote.sendPrompt({ text })` and HTTPS `openLink({ url })` bridge. Do not replace it with unrestricted parent messages. The sandbox has no same-origin storage or fetch access. Preserve preview isolation, final sandbox initialization, and incremental streaming behavior.
 
-## Tech Stack
+## Configuration and checks
 
-- **Frontend**: Next.js 16, React 19, TailwindCSS 4
-- **Agent**: LangGraph (Python), Anthropic Claude (Fable 5)
-- **CopilotKit**: React hooks for agent integration (v2)
-- **Monorepo**: Turborepo with pnpm workspaces
-- **Other**: MCP (Model Context Protocol) integration, Recharts for generative UI examples
-
-## Development
-
-This is a Turborepo monorepo using pnpm workspaces.
+The local default model is `chat-latest` (ChatGPT Instant). `claude-*` requires `ANTHROPIC_API_KEY`; `chat-latest` and `gpt-*` require `OPENAI_API_KEY`. Jev routing requires `TYPESAFE_API_KEY`. Do not invent native model APIs or silently change pinned model IDs. See `render.yaml` for its separate explicit deployment model setting.
 
 ```bash
-# Install dependencies (all apps)
 pnpm install
-
-# Start all apps (app, agent, mcp)
-pnpm dev
-
-# Start individually
-pnpm dev:app    # Next.js frontend on port 3000
-pnpm dev:agent  # LangGraph agent on port 8123
-pnpm dev:mcp    # MCP server
-
-# Build all apps
-pnpm build
-
-# Lint all apps
+pnpm test
+uv run --directory apps/agent pytest
 pnpm lint
+pnpm build
 ```
 
-### Environment Setup
-
-```bash
-# Set Anthropic API key for the agent
-echo 'ANTHROPIC_API_KEY=your-key-here' > apps/agent/.env
-```
-
-## Design Principles
-
-1. **Simple over complex** - The todo list is intentionally simple and focused
-2. **CopilotKit v2 patterns** - Uses modern agent state management
-3. **Template-first** - Code is meant to be forked and extended
-4. **Showcasing agent-driven UI** - Demonstrates AI manipulating application state beyond chat
-
-## Future Enhancements
-
-Possible extensions to demonstrate more CopilotKit capabilities:
-- Todo categories/tags/priorities
-- Agent-driven task organization (auto-categorize, suggest priorities)
-- Due dates and reminders
-- Subtasks and dependencies
-- Export/import todo lists
-- Undo/redo with state history
-- Real-time collaboration
-
----
-
-## Key Takeaways for Developers
-
-**State Management Pattern**: This app uses CopilotKit v2's agent state pattern where:
-- State is defined in the agent backend (Python TypedDict)
-- Frontend reads via `agent.state.todos`
-- Frontend writes via `agent.setState({ todos: ... })`
-- Agent can modify state via tools (`manage_todos`)
-- Changes sync bidirectionally automatically
-
-**When extending this template**:
-- Define state schema in the agent (`AgentState`)
-- Create tools that manipulate state via `Command(update={...})`
-- Use `useAgent()` hook in frontend to read/write state
-- Let CopilotKit handle the sync - no manual state management needed
+Use focused tests while developing, then relevant workspace checks. Inspect the [launch workflow](docs/deployment.md#verification-and-launch) for browser and live-provider validation. A rendered chat shell does not prove AI generation works. Keep secrets out of source, generated UI, logs, and screenshots. Do not describe a local build as a deployed release.
 
-This pattern works great for **agent-driven applications** where the AI needs to manipulate structured application state, not just chat.
+See [Architecture](docs/architecture.md) and [Product and agent behavior](docs/interactive-answers.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Contributing to Open Intelligent UI
+# Contributing to Open Generative UI
 
 ⭐ Thank you for your interest in contributing!!
 
@@ -23,18 +23,18 @@ If you find a bug in the source code, you can help us by [submitting an issue](h
 
 ## Missing a feature?
 
-So, you've got an awesome feature in mind? Throw it over to us by [creating an issue](https://github.com/CopilotKit/OpenIntelligentUI/issues/new) on our GitHub Repo.
+So, you've got an awesome feature in mind? Throw it over to us by [creating an issue](https://github.com/CopilotKit/open-generative-ui/issues/new) on our GitHub Repo.
 
 # How do I make a code contribution?
 
 ## Step 1: Make a fork
 
-Fork the [OpenIntelligentUI](https://github.com/CopilotKit/OpenIntelligentUI/issues) repository to your GitHub account. This means that you'll have a copy of the repository under _your-GitHub-username/OpenIntelligentUI_.
+Fork the [OpenIntelligentUI](https://github.com/CopilotKit/OpenIntelligentUI) repository to your GitHub account. This means that you'll have a copy of the repository under _your-GitHub-username/OpenIntelligentUI_.
 
 ## Step 2: Clone the repository to your local machine
 
 ```bash
-git clone https://github.com/<your-GitHub-username>/OpenIntelligentUI
+git clone https://github.com/<your-GitHub-username>/OpenGenerativeUI
 ```
 
 ## Step 3: Prepare the development environment

diff --git a/Makefile b/Makefile
@@ -8,8 +8,8 @@ install: ## Install all dependencies (Node + Python)
 
 setup: install ## Full setup: install deps and create .env from template
 	@if [ ! -f apps/agent/.env ]; then \
-		echo "ANTHROPIC_API_KEY=your-key-here" > apps/agent/.env; \
-		echo "Created apps/agent/.env — add your OpenAI API key"; \
+		printf '%s\n' 'OPENAI_API_KEY=' 'TYPESAFE_API_KEY=' 'LLM_MODEL=chat-latest' 'JEV_MODEL=jev-latest' > apps/agent/.env; \
+		echo "Created apps/agent/.env — set OPENAI_API_KEY and TYPESAFE_API_KEY"; \
 	else \
 		echo "apps/agent/.env already exists, skipping"; \
 	fi