@agent-native/core 0.6.1 → 0.7.1

package/docs/content/key-concepts.md

@@ -0,0 +1,246 @@
+---
+title: "Key Concepts"
+description: "How agent-native apps work: the four-area checklist, SQL database, agent chat bridge, polling sync, actions, context awareness, and portability."
+---
+
+# Key Concepts
+
+How agent-native apps work under the hood — the principles, the architecture, and why they're built this way.
+
+## Why agent-native {#why-agent-native}
+
+Teams today have four options for AI-powered work, and none of them are ideal:
+
+1. **Chat apps** (Claude Projects, ChatGPT) — accessible but not built for structured workflows. No persistent UI, no dashboards, no team collaboration.
+2. **Raw agent interfaces** (Claude Code, Cursor) — powerful but inaccessible to non-devs. No guardrails, no onboarding, no structured UI.
+3. **Custom AI apps** — limited. The AI can't see what you see, can't react to what you click, and can't update the app itself. No conversation history, no rollback, no skills.
+4. **Existing SaaS** (Amplitude, HubSpot, Google Slides) — bolting AI onto architectures that weren't designed for it. You can feel the seams.
+
+Agent-native apps solve this by making the agent and the UI equal citizens of the same system. Think of it as Claude Code, but with buttons and visual interfaces. The agent can do anything the UI can do (via natural language), and the UI can trigger anything the agent can do (via buttons).
+
+See [What Is Agent-Native?](/docs/what-is-agent-native) for the full vision and philosophy.
+
+## The architecture {#the-architecture}
+
+Every agent-native app is three things working together:
+
+> **Agent** — Autonomous AI that reads data, writes data, runs actions, and modifies code. Customizable with skills and instructions.
+>
+> **Application** — Full React UI with dashboards, flows, and visualizations. Guided experiences your team can use.
+>
+> **Computer** — Database, browser, code execution. Agents work directly with SQL and tools — no MCPs needed.
+
+Every app includes an embedded agent panel with chat and optional CLI terminal. Locally, you run `pnpm dev` and the agent is right there. In the cloud, Builder.io provides a managed frame with collaboration, visual editing, and managed infrastructure for teams.
+
+Six rules govern the architecture:
+
+1. **Data lives in SQL** — all app state lives in the database via Drizzle ORM
+2. **All AI goes through the agent** — no inline LLM calls
+3. **Actions for agent operations** — complex work runs as actions
+4. **Polling keeps the UI in sync** — database changes sync via lightweight polling
+5. **The agent can modify code** — the app evolves as you use it
+6. **Application state in SQL** — ephemeral UI state lives in the database, readable by both agent and UI
+
+## The four-area checklist {#four-area-checklist}
+
+Every new feature must update all four areas. Skipping any one breaks the agent-native contract.
+
+| Area             | Description                                                    |
+| ---------------- | -------------------------------------------------------------- |
+| **1. UI**        | Page, component, or dialog the user interacts with             |
+| **2. Action**    | Agent-callable action in actions/ for the same operation       |
+| **3. Skills**    | Update AGENTS.md and/or create a skill documenting the pattern |
+| **4. App-State** | Navigation state, view-screen data, and navigate commands      |
+
+A feature with only UI is invisible to the agent. A feature with only actions is invisible to the user. A feature without app-state means the agent is blind to what the user is doing.
+
+## Data in SQL {#data-in-sql}
+
+All application state lives in a SQL database via Drizzle ORM. The framework supports multiple databases — SQLite, Postgres (Neon, Supabase), Turso, Cloudflare D1. Users configure `DATABASE_URL` to choose their database.
+
+Core SQL stores are auto-created and available in every template:
+
+- `application_state` — ephemeral UI state (navigation, drafts, selections)
+- `settings` — persistent key-value config
+- `oauth_tokens` — OAuth credentials
+- `sessions` — auth sessions
+
+```bash
+// Drizzle schema for domain data
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+export const forms = sqliteTable("forms", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  schema: text("schema").notNull(), // JSON
+  ownerEmail: text("owner_email"),
+  createdAt: integer("created_at").notNull(),
+});
+
+// Core actions for quick database access
+pnpm action db-schema           # show all tables
+pnpm action db-query --sql "SELECT * FROM forms"
+pnpm action db-exec --sql "INSERT INTO forms ..."
+# Surgical find/replace on a large text column — sends a diff, not the whole value
+pnpm action db-patch --table documents --column content \
+  --where "id='doc-1'" --find "old heading" --replace "new heading"
+```
+
+## Agent chat bridge {#agent-chat-bridge}
+
+The UI never calls an LLM directly. When a user clicks "Generate chart" or "Write summary", the UI sends a message to the agent via `postMessage`. The agent does the work — with full conversation history, skills, instructions, and the ability to iterate.
+
+```ts
+// In a React component — delegate AI work to the agent
+import { sendToAgentChat } from "@agent-native/core";
+
+sendToAgentChat({
+  message: "Generate a chart showing signups by source",
+  context: "Dashboard ID: main, date range: last 30 days",
+  submit: true,
+});
+```
+
+Why not call an LLM inline?
+
+- **AI is non-deterministic.** You need conversation flow to give feedback and iterate — not one-shot buttons.
+- **Context matters.** The agent has your full codebase, instructions, skills, and history. An inline call has none of that.
+- **The agent can do more.** It can run actions, browse the web, modify code, and chain multiple steps together.
+- **Headless execution.** Because everything goes through the agent, any app can be driven entirely from Slack, Telegram, or another agent via [A2A](/docs/a2a-protocol).
+
+## Actions system {#actions-system}
+
+When the agent needs to do something complex — call an API, process data, query the database — it runs an action. Actions are TypeScript files in `actions/` that export a default async function:
+
+```ts
+// actions/fetch-data.ts
+import { parseArgs } from "@agent-native/core";
+
+export default async function fetchData(args: string[]) {
+  const { source } = parseArgs(args);
+  const res = await fetch(`https://api.example.com/${source}`);
+  const data = await res.json();
+  console.log(JSON.stringify(data, null, 2));
+}
+```
+
+```bash
+# Agent runs actions via CLI
+pnpm action fetch-data --source=signups
+```
+
+This means anything the UI can do, the agent can do — and vice versa. The UI calls `POST /api/fetch-data`, the agent calls `pnpm action fetch-data`. Same logic, same results, different entry points.
+
+## Polling sync {#polling-sync}
+
+Database changes are synced to the UI via lightweight polling. When the agent writes to the database (application state, settings, or domain data), a version counter increments. The client `useDbSync()` hook (formerly `useFileWatcher`) polls `/_agent-native/poll` every 2 seconds and invalidates React Query caches when changes are detected.
+
+```ts
+// Client: invalidate caches on database changes
+import { useDbSync } from "@agent-native/core";
+
+useDbSync({
+  queryClient,
+  queryKeys: ["app-state", "settings", "forms"],
+});
+```
+
+The flow is:
+
+1. Agent runs an action that writes to the database
+2. Version counter increments
+3. `useDbSync` detects the new version on next poll
+4. React Query caches are invalidated
+5. Components re-fetch and render the new data
+
+This works in all deployment environments — including serverless and edge — because it uses the database, not in-memory state or file system watchers.
+
+## Frames {#frames}
+
+Agent-native apps include an embedded agent panel that provides the AI agent alongside the app UI. This is what makes the architecture work: the agent needs a computer (database, browser, code execution), and the app needs the agent for AI work.
+
+> **Embedded Agent Panel** — Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally. Free and open source.
+>
+> **Cloud** — Deploy to any cloud with real-time collaboration, visual editing, roles and permissions. Best for teams.
+
+## Context awareness {#context-awareness}
+
+The agent always knows what the user is looking at. The UI writes a `navigation` key to application-state on every route change. The agent reads it via the `view-screen` action before acting.
+
+See [Context Awareness](/docs/context-awareness) for the full pattern: navigation state, view-screen, navigate commands, and jitter prevention.
+
+## APIs & CLIs, not MCPs {#apis-and-clis}
+
+Agent-native apps can work with MCP servers, but the architecture leans heavily on something more standard: **regular APIs and CLIs accessed through code execution**. Agents are great at writing code that calls `fetch()` or runs a CLI command — no special protocol needed.
+
+- **No wrapper layer.** Call APIs directly with `fetch()` or use official SDKs.
+- **Any CLI works.** `ffmpeg`, `gh`, `aws`, `gcloud` — if it runs in a terminal, the agent can use it.
+- **Code is the protocol.** TypeScript actions are more expressive than any tool schema.
+- **MCP is additive.** Use MCP servers alongside actions if you want, but they're not required.
+
+## Agent modifies code {#agent-modifies-code}
+
+This is a feature, not a bug. The agent can safely edit the app's source code: components, routes, styles, actions.
+
+There's no shared codebase to break. You own the app, and the agent evolves it for you over time:
+
+1. Fork a template (e.g. the analytics template)
+2. Customize it by asking the agent
+3. "Add a new chart type for cohort analysis" — the agent builds it
+4. "Connect to our Stripe account" — the agent writes the integration
+5. Your app keeps improving without manual development
+
+## Database agnostic {#database-agnostic}
+
+The framework supports every Drizzle-supported database. Never write SQL that only works on one dialect.
+
+- **SQLite** — local dev fallback when `DATABASE_URL` is unset
+- **Neon Postgres** — common in both dev and production
+- **Turso** (libSQL) — edge-friendly SQLite-compatible
+- **Supabase Postgres**
+- **Cloudflare D1**
+- **Plain Postgres**
+
+Use the framework helpers for dialect-agnostic SQL:
+
+```ts
+import { getDbExec, isPostgres, intType } from "@agent-native/core/db/client";
+
+// getDbExec() auto-converts ? params to $1 for Postgres
+const client = getDbExec();
+await client.execute({
+  sql: "SELECT * FROM forms WHERE owner_email = ?",
+  args: [email],
+});
+
+// Branch when syntax differs
+const upsert = isPostgres()
+  ? "INSERT INTO settings (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = $2"
+  : "INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)";
+```
+
+## Hosting agnostic {#hosting-agnostic}
+
+The server runs on Nitro, which compiles to any deployment target:
+
+- Node.js — local dev, traditional servers
+- Cloudflare Workers/Pages
+- Netlify Functions/Edge
+- Vercel Serverless/Edge
+- Deno Deploy
+- AWS Lambda
+- Bun
+
+Never use Node-specific APIs (`fs`, `child_process`, `path`) in server routes or plugins. These don't exist in Workers/edge environments. Actions in `actions/` run in Node.js and can use Node APIs freely.
+
+Never assume a persistent server process. Serverless and edge environments are stateless — no in-memory caches, no long-lived connections. Use the SQL database for all state.
+
+## Deep dives {#deep-dives}
+
+For detailed guidance on specific patterns:
+
+- [What Is Agent-Native?](/docs/what-is-agent-native) — the vision and philosophy
+- [Context Awareness](/docs/context-awareness) — navigation state, view-screen, navigate commands
+- [Skills Guide](/docs/skills-guide) — framework skills, domain skills, creating custom skills
+- [A2A Protocol](/docs/a2a-protocol) — agent-to-agent communication
+- [Enterprise Workspace](/docs/enterprise-workspace) — host many apps in one monorepo with shared auth, skills, components, and credentials

package/docs/content/mcp-clients.md

@@ -0,0 +1,110 @@
+---
+title: "MCP Clients"
+description: "Connect your agent-native app to local MCP servers (claude-in-chrome, filesystem, playwright, etc) so the agent gains their tools."
+---
+
+# MCP Clients
+
+Agent-native apps can also act as MCP **clients** — connecting to locally installed MCP servers and exposing their tools to the agent chat. This is the symmetric counterpart to the [MCP Protocol](./mcp-protocol.md) (which makes your app an MCP server).
+
+With one config file, every agent-native app in your workspace gains access to tools provided by MCP servers on your machine: `claude-in-chrome` for browser automation, `@modelcontextprotocol/server-filesystem` for reading files, `@modelcontextprotocol/server-playwright` for browser testing, and anything else that speaks MCP.
+
+## Adding a local MCP server {#adding-a-server}
+
+Create `mcp.config.json` at your workspace root (or at an individual app root — workspace root wins when both exist):
+
+```jsonc
+{
+  "$schema": "https://agent-native.com/schema/mcp.config.json",
+  "servers": {
+    "claude-in-chrome": {
+      "command": "claude-in-chrome-mcp",
+      "args": [],
+      "env": { "LOG_LEVEL": "info" },
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-playwright"],
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/me/projects",
+      ],
+    },
+  },
+}
+```
+
+On next app start you'll see:
+
+```
+[mcp-client] loaded config from /path/to/mcp.config.json (3 server(s))
+[mcp-client] connected to claude-in-chrome: 12 tools
+[mcp-client] connected to playwright: 9 tools
+[mcp-client] connected to filesystem: 4 tools
+```
+
+The tools are registered in the agent's tool registry with the prefix `mcp__<server-id>__<tool-name>` so they can't collide with your template's actions.
+
+## Config precedence {#precedence}
+
+MCP configuration is resolved in this order, first match wins:
+
+1. **Workspace root `mcp.config.json`** — detected via `agent-native.workspaceCore` in `package.json`. Shared across every app in the workspace.
+2. **App-root `mcp.config.json`** — per-app override if you don't want an MCP server available in every app.
+3. **`MCP_SERVERS` env var** — JSON string with the same shape, for CI/production where a file doesn't make sense.
+
+## Production deploys: `MCP_SERVERS` {#mcp-servers-env}
+
+For production deploys set the full config shape (or the inner server map) as an environment variable:
+
+```bash
+MCP_SERVERS='{"servers":{"playwright":{"command":"npx","args":["-y","@modelcontextprotocol/server-playwright"]}}}'
+```
+
+MCP tools only activate in Node runtimes — Cloudflare Workers and other edge targets silently skip MCP and continue with the rest of the app working normally.
+
+## Auto-detect: `claude-in-chrome` {#autodetect}
+
+If you have **no** `mcp.config.json` and the `claude-in-chrome-mcp` binary is on `PATH` (or in the well-known install location `~/.claude-in-chrome/bin/claude-in-chrome-mcp`), agent-native auto-registers it as a default MCP server. Set `AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1` to opt out.
+
+This means users who've installed the claude-in-chrome extension get browser control across every agent-native app they open with no config changes.
+
+## Status route {#status-route}
+
+Every app exposes `GET /_agent-native/mcp/status` for tooling and onboarding:
+
+```json
+{
+  "configuredServers": ["claude-in-chrome", "playwright"],
+  "connectedServers": ["claude-in-chrome", "playwright"],
+  "totalTools": 21,
+  "tools": [
+    {
+      "source": "claude-in-chrome",
+      "name": "mcp__claude-in-chrome__navigate",
+      "description": "Navigate the browser to a URL"
+    }
+  ],
+  "errors": {}
+}
+```
+
+Use this to build "claude-in-chrome detected — your agent can now drive Chrome" onboarding hints, or debug MCP connection problems.
+
+## Failure modes {#failures}
+
+Individual MCP server failures never take down the agent:
+
+- A misconfigured `command` → the server is skipped, its error appears in `/mcp/status` under `errors.<server-id>`, and every other server continues to work.
+- The MCP SDK is missing from `node_modules` → all MCP functionality is skipped with a warning; agent chat keeps working with zero MCP tools.
+- Running in an edge runtime → MCP client is a no-op.
+
+Agent-native will always boot; broken MCP configuration just means fewer tools.
+
+## Security {#security}
+
+MCP tools run on your machine with whatever permissions the spawned process has. Treat `mcp.config.json` like any other list of executables you're willing to let the agent drive. Tools from MCP servers appear in the agent's tool-use loop just like your template's own actions, so make sure you trust every server you configure.

package/docs/content/mcp-protocol.md

@@ -0,0 +1,168 @@
+---
+title: "MCP Protocol"
+description: "Expose your agent-native app as a remote MCP server so Claude Code, Cursor, and other AI tools can call your app's actions directly."
+---
+
+# MCP Protocol
+
+Every agent-native app automatically exposes a remote MCP (Model Context Protocol) server. This lets external AI tools like Claude Code, Cursor, and Windsurf discover and call your app's actions directly — no extra code needed.
+
+## Overview {#overview}
+
+MCP is the standard protocol for connecting AI tools to external capabilities. When you deploy an agent-native app, it auto-mounts an MCP endpoint alongside the existing A2A endpoint. Any MCP-compatible client can connect and use your app's tools.
+
+Key concepts:
+
+- **Auto-mounted** — every app gets `/_agent-native/mcp` for free, no setup required
+- **Streamable HTTP** — uses the modern MCP transport over standard HTTP (POST + SSE)
+- **Same actions** — the exact same action registry that powers agent chat and A2A
+- **`ask-agent` tool** — a meta-tool that delegates to the full agent loop for complex tasks
+- **Bearer auth** — uses `ACCESS_TOKEN` or `A2A_SECRET` for authentication
+
+## MCP vs A2A {#mcp-vs-a2a}
+
+Both protocols are auto-mounted. Use whichever fits your use case:
+
+|                    | MCP                                   | A2A                                          |
+| ------------------ | ------------------------------------- | -------------------------------------------- |
+| **Best for**       | External tools calling your app       | Agent-to-agent communication                 |
+| **Protocol**       | MCP Streamable HTTP                   | JSON-RPC 2.0                                 |
+| **Tool discovery** | `tools/list`                          | Agent card at `/.well-known/agent-card.json` |
+| **Endpoint**       | `/_agent-native/mcp`                  | `/_agent-native/a2a`                         |
+| **Supported by**   | Claude Code, Cursor, Windsurf, Cowork | Other agent-native apps                      |
+| **Execution**      | Direct tool calls (no extra LLM)      | Full agent loop (LLM reasoning)              |
+
+You can also use the `ask-agent` MCP tool to get the best of both worlds — call it from Claude Code and let your app's agent reason through complex tasks.
+
+## Connecting from Claude Code {#claude-code}
+
+Add your app as a remote MCP server in Claude Code's config:
+
+```jsonc
+// ~/.claude/mcp_servers.json
+{
+  "mail": {
+    "type": "url",
+    "url": "https://mail.example.com/_agent-native/mcp",
+    "headers": {
+      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
+    },
+  },
+}
+```
+
+Then in Claude Code, you can use your app's tools naturally:
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
+```
+
+## Connecting from other MCP clients {#other-clients}
+
+Any MCP client that supports Streamable HTTP transport can connect. The endpoint is:
+
+```
+POST https://your-app.example.com/_agent-native/mcp
+```
+
+The server supports the standard MCP handshake: `initialize` → `initialized` → `tools/list` → `tools/call`.
+
+## Tools {#tools}
+
+All actions registered in your app are exposed as MCP tools. The mapping is direct:
+
+| Action property    | MCP tool property |
+| ------------------ | ----------------- |
+| `tool.description` | `description`     |
+| `tool.parameters`  | `inputSchema`     |
+| Action name        | Tool name         |
+
+### The `ask-agent` tool {#ask-agent}
+
+In addition to individual action tools, every MCP server includes an `ask-agent` meta-tool. This sends a natural-language message to the app's AI agent and returns the response.
+
+Use `ask-agent` for complex tasks that benefit from the agent's reasoning and context:
+
+```json
+{
+  "name": "ask-agent",
+  "arguments": {
+    "message": "Draft a follow-up email to the Q3 planning thread with John, summarizing the action items we discussed"
+  }
+}
+```
+
+The agent runs the same loop as the interactive chat — it can call multiple tools, reason about context, and produce a thoughtful response.
+
+## Authentication {#authentication}
+
+The MCP endpoint uses the same auth as the rest of the app:
+
+| Env var         | How it works                                                |
+| --------------- | ----------------------------------------------------------- |
+| `ACCESS_TOKEN`  | Bearer token — client sends `Authorization: Bearer <token>` |
+| `ACCESS_TOKENS` | Comma-separated list of valid tokens                        |
+| `A2A_SECRET`    | JWT-based auth — tokens are verified cryptographically      |
+| _(none set)_    | No auth required (dev mode)                                 |
+
+In production, set `ACCESS_TOKEN` or `A2A_SECRET` to secure the endpoint. In development (no auth env vars configured), all requests are allowed.
+
+## Custom MCP setup {#custom-setup}
+
+The MCP server is auto-mounted by the agent-chat plugin. For most apps, no configuration is needed. If you need custom behavior, you can mount it manually in a server plugin:
+
+```ts
+// server/plugins/mcp.ts
+import { mountMCP } from "@agent-native/core/mcp";
+import { autoDiscoverActions } from "@agent-native/core/server";
+
+export default defineNitroPlugin(async (nitro) => {
+  const actions = await autoDiscoverActions(import.meta.url);
+
+  mountMCP(nitro.h3App, {
+    name: "My App",
+    description: "Custom MCP server",
+    actions,
+    // Optional: provide ask-agent handler
+    askAgent: async (message) => {
+      // Your custom agent logic
+      return "Response";
+    },
+  });
+});
+```
+
+## Example: analytics from Claude Code {#example}
+
+You have a deployed analytics app at `analytics.example.com`. From Claude Code:
+
+```jsonc
+// ~/.claude/mcp_servers.json
+{
+  "analytics": {
+    "type": "url",
+    "url": "https://analytics.example.com/_agent-native/mcp",
+    "headers": { "Authorization": "Bearer sk-analytics-token" },
+  },
+}
+```
+
+Now in Claude Code:
+
+```
+> How many signups did we get last week?
+
+Claude Code calls: run-query(sql: "SELECT count(*) FROM signups WHERE created_at > now() - interval '7 days'")
+→ "1,247 signups last week"
+```
+
+For more complex analysis:
+
+```
+> Ask the analytics agent to prepare a full breakdown of Q3 signups by source, with trends
+
+Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
+→ The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
+```

package/docs/content/onboarding.md

@@ -0,0 +1,107 @@
+# Onboarding
+
+The framework-level onboarding system gives every template a shared setup
+experience in the agent chat sidebar. Users see a checklist of setup steps,
+each with one or more ways to complete it — paste an API key, connect
+Builder, or ask the agent to do it for them.
+
+The system is **auto-mounted**. Templates don't need to wire anything to get
+the three built-in steps (LLM, database, auth). To add app-specific steps
+(Gmail, Slack, Notion, etc.), call `registerOnboardingStep()` from a server
+plugin.
+
+## Auto-mounted routes
+
+All routes live under `/_agent-native/onboarding/`:
+
+| Route                                               | Purpose                           |
+| --------------------------------------------------- | --------------------------------- |
+| `GET /_agent-native/onboarding/steps`               | List steps with completion status |
+| `POST /_agent-native/onboarding/steps/:id/complete` | Mark step complete (override)     |
+| `POST /_agent-native/onboarding/dismiss`            | Dismiss the onboarding banner     |
+| `POST /_agent-native/onboarding/reopen`             | Clear dismissal (re-show panel)   |
+| `GET /_agent-native/onboarding/dismissed`           | Read dismissal + allComplete flag |
+
+## Adding a step from a template
+
+```ts
+// server/plugins/my-onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "gmail",
+    order: 100,
+    title: "Connect Gmail",
+    description: "Grant read/send access so the agent can work with email.",
+    methods: [
+      {
+        id: "oauth",
+        kind: "link",
+        primary: true,
+        label: "Sign in with Google",
+        payload: {
+          url: "/_agent-native/google/auth-url?scope=mail",
+          external: false,
+        },
+      },
+      {
+        id: "delegate",
+        kind: "agent-task",
+        label: "Let the agent set it up",
+        badge: "beta",
+        payload: {
+          prompt: "Walk me through connecting Gmail. Set env vars as needed.",
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GMAIL_REFRESH_TOKEN,
+  });
+});
+```
+
+## Method kinds
+
+| Kind               | Payload                   | Use for                                   |
+| ------------------ | ------------------------- | ----------------------------------------- |
+| `link`             | `{ url, external? }`      | Send user to an OAuth flow or docs page   |
+| `form`             | `{ fields, writeScope? }` | Collect env vars (keys, secrets, URLs)    |
+| `builder-cli-auth` | `{ scope: "browser" }`    | Connect Builder (unlocks shared infra)    |
+| `agent-task`       | `{ prompt }`              | Send a prompt to the agent chat to handle |
+
+The `primary: true` flag marks a method as the big CTA for its step.
+
+## Built-in steps
+
+| ID         | Required | Description                                   |
+| ---------- | -------- | --------------------------------------------- |
+| `llm`      | yes      | ANTHROPIC_API_KEY or Builder connection       |
+| `database` | no       | SQLite default or a DATABASE_URL for Postgres |
+| `auth`     | no       | Local dev mode, Google OAuth, or access token |
+
+Any of these can be overridden by re-registering with the same `id` after the
+defaults load.
+
+## Client usage
+
+The panel is already inside `<AgentPanel>`. To build a custom layout:
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```