@agent-native/core 0.59.0 → 0.60.0

package/docs/content/getting-started.md

@@ -1,123 +1,113 @@
 ---
 title: "Getting Started"
-description: "Choose the right path: hosted apps, local setup, agent-native skills, or external-agent connections."
+description: "Create a chat-first agent-native app, or start headless with one action and add UI later."
 ---
 
 # Getting Started
 
-Agent-Native is for apps where a real UI and an AI agent share the same actions, data, and state. This page helps you choose the right starting point, then walks through the local setup path.
+Agent-Native is for apps where an AI agent and any UI around it share the same actions, data, and state. The default starting point is the [Chat template](/docs/template-chat): a minimal chat app with durable threads, a left sidebar, auth, live sync, and actions ready to extend.
 
-## Pick your path {#who-is-this-for}
+Start with Chat when you want a browser app users can talk to immediately. Start headless when you only want actions and the local app-agent loop for now.
 
-Start with the path that matches what you want to do next:
+If you already know you want a finished domain app, go to [Templates](/docs/cloneable-saas). If you are choosing between headless, chat, embedded, or full app, go to [Agent Surfaces](/docs/agent-surfaces). Otherwise, keep going.
 
-- **Use a starter app.** Browse the [template gallery](/templates). Hosted apps already include sign-in, data, and the agent sidebar. No install required.
-- **Build or customize your own app.** Continue with [Create a local app](#create-your-app). You'll scaffold a template, run it locally, then change the code, brand, data model, and integrations.
-- **Choose headless, chat, embedded, or full app.** Use [Agent Surfaces](/docs/agent-surfaces) when you know the workflow but not how much UI belongs around it.
-- **Add agent-native skills to a code tool.** Jump to [Try it with a skill](#try-with-a-skill) to add Plans or PR Recaps to Claude Code, Codex, or Cursor without scaffolding an app.
-- **Connect an external agent to an app.** Use [External Agents](/docs/external-agents) to connect Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP host to an existing app.
-
-If you're not sure, use the hosted app when you want to use software now. Use the local path when you want to own and change the software.
-
-## Create a local app {#create-your-app}
+## Create a chat app {#create-your-agent}
 
 You'll need [Node.js 22 or newer](https://nodejs.org) and [pnpm](https://pnpm.io) installed. Then run:
 
 ```bash
-npx @agent-native/core@latest create my-platform
-cd my-platform
-pnpm install && pnpm dev
+npx @agent-native/core@latest create my-chat-app --template chat
+cd my-chat-app
+pnpm install
+pnpm dev
 ```
 
-The `create` command opens a template picker. Pick one template for a single app, or pick several templates to create a workspace where the apps share auth, brand, and agent configuration. If you want one app directory instead of a workspace, pass `--standalone`.
-
-Open the URL the dev server prints. The workspace gateway always starts on port 8080 and serves every app through it; individual apps run on their own ports that are printed at startup. Standalone apps default to `http://localhost:3000`.
-
-### Agent credentials {#agent-credentials}
-
-In local development the embedded agent panel picks up your existing Claude Code or Codex CLI login automatically, or reads `ANTHROPIC_API_KEY` from a `.env` file in the project root. The database defaults to SQLite (stored at `data/app.db`) when `DATABASE_URL` is not set, so you can run the full stack with no external services. For production deployments — where you'll want Postgres, a persistent secret, and bring-your-own-key per user — see [Deployment](/docs/deployment).
-
-## What just happened? {#what-just-happened}
-
-You now have a real app running on your machine with an agent built into it:
-
-- The UI works like a normal SaaS product: routes, forms, tables, settings, and keyboard flows.
-- The agent panel can read the current screen and run the same actions the UI runs.
-- Changes stay in sync because the UI and agent share the same database and application state.
+This creates the minimal Chat app: a full-page chat route, durable chat threads, the standard left sidebar, an `actions/` folder, the framework runtime, and a SQLite database at `data/app.db` unless you set `DATABASE_URL`.
+
+Open the local URL, then ask the chat what actions are available. The scaffold includes one example action:
+
+```ts
+// actions/hello.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Say hello from the local agent.",
+  schema: z.object({
+    name: z.string().default("world"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ name }) => {
+    return { message: `Hello, ${name}!` };
+  },
+});
+```
 
-That parity between agent and UI is the whole point — see [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
+Run that action directly:
 
-## Pick a template {#templates}
+```bash
+pnpm action hello --name Steve
+```
 
-Templates are complete apps, not blank starters. Choose one when you want a familiar product to customize:
+Then run the same app-agent loop from the terminal:
 
-- **Productivity apps** — [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Content](/docs/template-content), [Slides](/docs/template-slides), [Design](/docs/template-design), [Clips](/docs/template-clips), and [Video](/docs/template-videos)
-- **Team and data apps** — [Analytics](/docs/template-analytics), [Brain](/docs/template-brain), [Dispatch](/docs/template-dispatch), [Assets](/docs/template-assets), and [Plan](/docs/template-plan)
-- **Bare starting point** — [Starter](/docs/template-starter), a minimal app with the framework wiring and no domain model
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
 
-Browse the [template gallery](/templates) for live hosted apps. See [Templates](/docs/cloneable-saas) for the full catalog and the clone → customize → deploy flow.
+That is the local app-agent loop. The chat UI, CLI, HTTP, MCP, A2A, jobs, and future screens can all call the same action surface.
 
-## Add more apps to a workspace {#creating-vs-adding-apps}
+## Start headless instead {#headless}
 
-`create` (above) makes a brand-new workspace. Once you have one, add more apps to it with `add-app`, run from the workspace root:
+Use headless mode when you want no browser app yet:
 
 ```bash
-cd my-platform
-npx @agent-native/core@latest add-app
+npx @agent-native/core@latest create my-agent --headless
+cd my-agent
 pnpm install
-pnpm dev
+pnpm action hello --name Steve
+pnpm agent "Call the hello action for Steve and explain what happened."
 ```
 
-If your terminal is inside `apps/content` or another app folder, the CLI still detects the workspace and adds the new app as a sibling under `apps/`. Go back to the workspace root before running `pnpm install` or `pnpm dev`.
+This creates the smallest local Agent-Native runtime: an `actions/` folder, instructions, the framework runtime, and SQL state. Later, add chat by starting from the [Chat template](/docs/template-chat) and moving your actions in, or by copying the Chat template's route/sidebar pattern into the headless app.
 
-To add another app from a specific template, pass a name and `--template`:
+### Agent credentials {#agent-credentials}
 
-```bash
-npx @agent-native/core@latest add-app design-lab --template design
-```
+In local development the agent command reads provider credentials from your environment, such as `ANTHROPIC_API_KEY` in a `.env` file in the project root. Browser chat surfaces can also use configured agent credentials. The full loop is not stateless: actions, auth/session data, application state, threads, and run history use SQL. Locally that defaults to SQLite; in production you will usually point `DATABASE_URL` at Postgres or another persistent SQL database. See [Deployment](/docs/deployment).
 
-## Try it with a skill {#try-with-a-skill}
+## What just happened? {#what-just-happened}
 
-Don't want to scaffold an app? Add agent-native capabilities to a coding agent you already use. Installing the **Plans** skill turns the plans your agent writes into structured, reviewable docs with diagrams, wireframes, and inline comments:
+You now have a real app-agent loop:
 
-```bash
-npx @agent-native/core@latest skills add visual-plan
-```
+- `hello` is one action definition, available to the agent, CLI, HTTP, MCP, A2A, and any future UI.
+- `pnpm agent` calls the same production app-agent loop used by chat, jobs, webhooks, and hosted runtimes.
+- Changes and history stay in sync because the local runtime uses SQL-backed state, even when you have no custom UI yet.
 
-That one command installs the skill instructions, registers the hosted MCP connector, and signs you in — no marketplace browsing, no manual OAuth. Then run `/visual-plan` in your agent. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for more skills, local/offline installs, and how app-backed skills work.
-
-Need the opposite direction, where Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP host calls an agent-native app? Use [External Agents](/docs/external-agents).
+That parity between agent and UI is the whole point. See [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
 
 ## Project structure {#project-structure}
 
-Every agent-native app — whether from a template or from scratch — follows the same structure:
+Every agent-native app follows the same structure:
 
 ```text
 my-app/
-  app/             # React frontend (routes, components, hooks)
-  server/          # Nitro API server (routes, plugins)
   actions/         # Agent-callable actions
+  app/             # React frontend in UI templates; omitted in headless apps
+  server/          # Nitro API server (routes, plugins)
   .agents/         # Agent instructions and skills
+  data/app.db      # Local SQLite runtime state when DATABASE_URL is unset
 ```
 
-Templates add domain-specific code on top: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`. Building from scratch? See [Creating Templates](/docs/creating-templates) for `vite.config.ts`, `tsconfig.json`, and Tailwind setup.
-
-## Architecture principles {#architecture-principles}
-
-The three principles that apply to every agent-native app:
-
-- **Agent + UI are equal partners** — everything the UI can do, the agent can do, and vice versa; they share the same database.
-- **Everything is an action** — agent tools, UI mutations, HTTP endpoints, MCP tools, and CLI commands are all the same `defineAction()` definition.
-- **All state in SQL** — app state, navigation, drafts, and settings live in the database so both agent and UI always see the same picture.
-
-The definitive six rules are in [Key Concepts](/docs/key-concepts).
+Templates add domain-specific code on top: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`. See [Creating Templates](/docs/creating-templates) when you are ready to build or publish a reusable template.
 
 ## Common next moves {#next-docs}
 
-Once your app is running, the usual next step is small and concrete:
+Once your agent is running, the usual next step is small and concrete:
 
-- **Ask the built-in agent what it sees** — open the agent panel and type "what app am I looking at, and what can you do here?" This verifies that the app, UI state, and agent loop are connected.
-- **Make one customization** — rename the app, change the first screen copy, or add a field to a form. The project `AGENTS.md` already tells coding agents how this repo is organized.
+- **Ask the built-in agent what it can do** — open Chat and type "what actions do you have, and what can you do here?" This verifies that the app-agent loop is connected.
+- **Add one real action** — replace `hello` with the smallest useful operation in your domain.
+- **Add UI only when it clarifies the work** — use [Agent Surfaces](/docs/agent-surfaces) to choose between headless, chat, embedded, and full-app surfaces.
 - **Deploy it** — see [Deployment](/docs/deployment) when you're ready to put the app on your own domain.
 
 Useful follow-up docs:

package/docs/content/key-concepts.md

@@ -1,6 +1,6 @@
 ---
 title: "Key Concepts"
-description: "How agent-native apps work: the four-area checklist, SQL database, agent chat bridge, polling sync, actions, external-agent entry points, context awareness, and portability."
+description: "How agent-native apps work: actions first, SQL database, app-agent loop, optional UI, polling sync, external-agent entry points, context awareness, and portability."
 ---
 
 # Key Concepts
@@ -16,7 +16,7 @@ Teams today have four options for AI-powered work, and none of them are ideal:
 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).
+Agent-native apps solve this by making the agent and any UI equal citizens of the same system. Think of it as Claude Code, but with durable actions, SQL state, and visual interfaces when the workflow needs them. A workflow can start as one callable action, then grow into chat, screens, schedules, or a full app without rewriting the operation.
 
 See [What Is Agent-Native?](/docs/what-is-agent-native) for the full vision and philosophy.
 
@@ -26,11 +26,11 @@ 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.
+> **Application** — The product surface around the agent. This may be action-only at first, rich chat, a small control plane, or a full React UI with dashboards, flows, and visualizations.
 >
 > **Computer** — Database, browser, code execution. Agents work directly with SQL and built-in tools; MCP servers are optional add-ons, not the foundation.
 
-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 — the environment that hosts the agent next to your app — with collaboration, visual editing, and managed infrastructure for teams.
+Headless apps can run the same production app-agent loop from the folder with `pnpm agent`, while UI apps mount the embedded agent panel and run locally with `pnpm dev`. In the cloud, Builder.io provides a managed frame — the environment that hosts the agent next to your app — with collaboration, visual editing, and managed infrastructure for teams.
 
 Six rules govern the architecture:
 
@@ -43,7 +43,7 @@ Six rules govern the architecture:
 
 ## The four-area checklist {#four-area-checklist}
 
-Every new feature must update all four areas. Skipping any one breaks the agent-native contract.
+Every user-facing feature should update all applicable areas. Skipping an applicable area breaks the agent-native contract; forcing a UI onto an action-only primitive is also a smell.
 
 | Area             | Description                                                    |
 | ---------------- | -------------------------------------------------------------- |
@@ -52,7 +52,7 @@ Every new feature must update all four areas. Skipping any one breaks the agent-
 | **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.
+A feature with only UI is invisible to the agent. A full UI 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. A headless operation can legitimately start with action + instructions and add UI/app-state later when humans need to browse, approve, configure, or share it.
 
 ## Data in SQL {#data-in-sql}
 
@@ -116,7 +116,7 @@ When the agent needs to do something complex — call an API, process data, quer
 
 ```ts
 // actions/fetch-data.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
 export default defineAction({
@@ -190,23 +190,23 @@ See [Context Awareness](/docs/context-awareness) for the full pattern: navigatio
 
 Agent-native supports a lot of agent-facing protocols because different hosts standardize different pieces of the same workflow. App authors should not have to choose among them or rebuild the same operation for each client. The center of gravity stays the action system.
 
-| Surface                     | Status              | What agent-native provides                                                                                                            | What you write                                    |
-| --------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| Agent tool calling          | Shipping            | The in-app agent sees actions as function tools with zod-derived JSON Schema.                                                         | `defineAction()`                                  |
-| UI actions                  | Shipping            | React calls the same action through `useActionMutation()` / `useActionQuery()`.                                                       | The same action                                   |
-| Native chat widgets         | Shipping            | Tool results with explicit widget discriminants can render native tables, charts, and typed app results in chat.                      | Structured action results                         |
-| AgentChatRuntime connectors | Shipping            | The chat shell can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or normalized HTTP streams. | Pick a runtime helper or stream normalized events |
-| HTTP and CLI                | Shipping            | Actions auto-mount at `/_agent-native/actions/:name` and run via `pnpm action <name>`.                                                | The same action                                   |
-| MCP server                  | Shipping            | External MCP hosts get Streamable HTTP tools, the `ask-agent` meta-tool, and optional MCP Apps resources.                             | The same action, plus optional `mcpApp`           |
-| MCP OAuth                   | Shipping            | Standard remote MCP OAuth, PKCE, dynamic client registration, refresh tokens, and `mcp:read` / `mcp:write` / `mcp:apps` scopes.       | Nothing per action                                |
-| MCP Apps                    | Shipping            | External hosts that support app resources can render iframe/native-host widgets, with deep-link fallback elsewhere.                   | Optional `mcpApp` metadata                        |
-| A2A                         | Shipping            | Other agents discover the agent card and call the app over JSON-RPC tasks.                                                            | The same actions and agent config                 |
-| Deep links                  | Shipping            | Action results can round-trip users into the running UI through `/_agent-native/open` and `agentnative://open`.                       | Optional `link` metadata                          |
-| MCP clients                 | Shipping            | The app can also consume local, remote, or hub-shared MCP servers as `mcp__...` tools.                                                | `mcp.config.json` or settings                     |
-| Instructions and skills     | Shipping            | `AGENTS.md`, skills, memory, slash commands, sub-agents, jobs, and automations live in the SQL-backed workspace.                      | Workspace resources, not protocol glue            |
-| Agent Web                   | Shipping            | Public pages can publish `robots.txt`, `sitemap.xml`, `llms.txt`, markdown mirrors, and structured metadata.                          | Route access plus `agentWeb` config               |
-| Extensions                  | Shipping            | Sandboxed mini-apps call app actions, persist extension data, and use proxied fetch helpers.                                          | Extension HTML using `appAction()`                |
-| ACP                         | Coding-agent/editor | Useful for coding agents inside editors/IDEs; not the general BYO app-chat runtime contract.                                          | Editor/agent adapter work                         |
+| Surface                     | Status              | What agent-native provides                                                                                                                              | What you write                                    |
+| --------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Agent tool calling          | Shipping            | The in-app agent sees actions as function tools with zod-derived JSON Schema.                                                                           | `defineAction()`                                  |
+| UI actions                  | Shipping            | React calls the same action through `useActionMutation()` / `useActionQuery()`.                                                                         | The same action                                   |
+| Native chat widgets         | Shipping            | Tool results with explicit widget discriminants can render native tables, charts, and typed app results in chat.                                        | Structured action results                         |
+| AgentChatRuntime connectors | Shipping            | The chat shell can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or normalized HTTP streams.                   | Pick a runtime helper or stream normalized events |
+| HTTP and CLI                | Shipping            | Actions auto-mount at `/_agent-native/actions/:name`, run via `pnpm action <name>`, and can be driven by the headless app-agent loop with `pnpm agent`. | The same action                                   |
+| MCP server                  | Shipping            | External MCP hosts get Streamable HTTP tools, the `ask-agent` meta-tool, and optional MCP Apps resources.                                               | The same action, plus optional `mcpApp`           |
+| MCP OAuth                   | Shipping            | Standard remote MCP OAuth, PKCE, dynamic client registration, refresh tokens, and `mcp:read` / `mcp:write` / `mcp:apps` scopes.                         | Nothing per action                                |
+| MCP Apps                    | Shipping            | External hosts that support app resources can render iframe/native-host widgets, with deep-link fallback elsewhere.                                     | Optional `mcpApp` metadata                        |
+| A2A                         | Shipping            | Other agents discover the agent card and call the app over JSON-RPC tasks.                                                                              | The same actions and agent config                 |
+| Deep links                  | Shipping            | Action results can round-trip users into the running UI through `/_agent-native/open` and `agentnative://open`.                                         | Optional `link` metadata                          |
+| MCP clients                 | Shipping            | The app can also consume local, remote, or hub-shared MCP servers as `mcp__...` tools.                                                                  | `mcp.config.json` or settings                     |
+| Instructions and skills     | Shipping            | `AGENTS.md`, skills, memory, slash commands, sub-agents, jobs, and automations live in the SQL-backed workspace.                                        | Workspace resources, not protocol glue            |
+| Agent Web                   | Shipping            | Public pages can publish `robots.txt`, `sitemap.xml`, `llms.txt`, markdown mirrors, and structured metadata.                                            | Route access plus `agentWeb` config               |
+| Extensions                  | Shipping            | Sandboxed mini-apps call app actions, persist extension data, and use proxied fetch helpers.                                                            | Extension HTML using `appAction()`                |
+| ACP                         | Coding-agent/editor | Useful for coding agents inside editors/IDEs; not the general BYO app-chat runtime contract.                                                            | Editor/agent adapter work                         |
 
 The practical rule is simple: implement domain operations as actions, add `readOnly`, `publicAgent`, `link`, `mcpApp`, or an explicit native widget result only when a surface needs it, and use skills/instructions for behavior. MCP, A2A, MCP Apps, MCP OAuth, UI mutations, native chat widgets, AgentChatRuntime connectors, CLI commands, and deep-link handoffs are adapters around that same core.
 

package/docs/content/native-chat-ui.md

@@ -38,12 +38,12 @@ Server actions should import the server-safe helpers and schemas from
 `@agent-native/core/client/chat` or `@agent-native/core/client`.
 
 ```ts
+import { defineAction } from "@agent-native/core/action";
+import { ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER } from "@agent-native/core/action-ui";
 import {
-  ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+  createDataInsightsWidgetResult,
   dataInsightsWidgetResultSchema,
-  defineAction,
-} from "@agent-native/core";
-import { createDataInsightsWidgetResult } from "@agent-native/core/data-widgets";
+} from "@agent-native/core/data-widgets";
 
 export default defineAction({
   description: "Analyze form responses.",

package/docs/content/pure-agent-apps.md

@@ -1,16 +1,18 @@
 ---
 title: "Pure-Agent Apps"
-description: "Apps where the agent is the whole product — open it, ask for what you want, and the agent does the rest."
+description: "Apps where the first product surface is the app-agent loop: define actions, run them locally, and add UI only when users need it."
 ---
 
 # Pure-Agent Apps
 
-This is the minimal end of agent-native — for the full-UI end, start from a [template](/docs/cloneable-saas). If you are choosing between headless, chat-first, embedded, and full-app shapes, start with [Agent Surfaces](/docs/agent-surfaces).
+This is the minimal end of agent-native: an app whose first user-facing surface is the agent loop, not a dashboard. For the full-UI end, start from a [template](/docs/cloneable-saas). If you are choosing between headless, chat-first, embedded, and full-app shapes, start with [Agent Surfaces](/docs/agent-surfaces).
 
-Imagine opening an app and seeing… just a chat. No dashboard. No sidebar full of menus. No forms. You ask for what you want — "summarize my unread emails," "post the daily metrics to Slack," "find the candidates who replied last week" — and the agent goes off and does it. The output shows up in chat, in Slack, in your inbox, wherever it belongs.
+Imagine opening an app and seeing just a chat. No dashboard. No sidebar full of menus. No forms. You ask for what you want - "summarize my unread emails," "post the daily metrics to Slack," "find the candidates who replied last week" - and the agent goes off and does it. The output shows up in chat, in Slack, in your inbox, wherever it belongs.
 
 That's a pure-agent app. The agent _is_ the product.
 
+It is still an app, not a stateless prompt. Actions, auth sessions, app state, thread history, run history, settings, credentials, and share records live in SQL. Locally that defaults to SQLite; hosted deployments should use a persistent SQL database.
+
 ## What it feels like to use one {#user-experience}
 
 Most apps are built around a UI: a database table you browse, a form you fill, a chart you read. The agent is a sidekick.
@@ -35,7 +37,7 @@ Pick the pure-agent pattern when:
 - **The domain is one-shot.** Research bot, summary generator, report writer. There's no persistent object that needs a list view.
 - **You're prototyping.** Ship the agent now; add a richer UI later if it turns out users actually want one.
 
-If your product is built around persistent objects users browse, pivot, and share — emails, events, documents, charts — pick a [template](/docs/cloneable-saas) instead. Those have full UIs _plus_ the agent.
+If your product is built around persistent objects users browse, pivot, and share - emails, events, documents, charts - pick a [template](/docs/cloneable-saas) instead. Those have full UIs _plus_ the agent.
 
 ## What ships in the box {#minimum-ui}
 
@@ -62,15 +64,17 @@ The trade-off: pure-agent apps don't give users a "browse-everything-at-a-glance
 
 If you're not a developer, you can usually start with the [Dispatch template](/docs/template-dispatch) — it's a workspace-style pure-agent app with Slack/Telegram, scheduled jobs, and shared secrets out of the box.
 
-For developers who want the absolute minimum, start from the **Starter** template:
+For developers who want the absolute minimum, start from a headless scaffold:
 
 ```bash
-npx @agent-native/core@latest create my-agent --template starter
+npx @agent-native/core@latest create my-agent --headless
 ```
 
-Starter gives you the architecture, the agent panel, the workspace, auth, polling, and one example action — and nothing else. Add your own actions in `actions/`, connect any MCP servers you need, write the relevant skills into the workspace, and you're done.
+This gives you the framework runtime, SQL-backed state, an `actions/` directory, and `pnpm agent` for running the local app-agent loop. Add one useful `defineAction()` and you have a real agent-native app. The same action can later render in chat, appear behind a button, expose an MCP tool, or move into a full UI without changing the core operation.
+
+Use [**Chat**](/docs/template-chat) when you are ready to add a browser UI but do not want a domain template. Chat is the add-UI scaffold path, not the required default for a pure-agent app.
 
-If you really want _zero_ UI except the agent, `app/routes/index.tsx` can render `<AgentPanel defaultMode="chat" />` fullscreen. The only thing the user sees is the chat. Everything else — job history, workspace, settings — is one click away in the panel's tabs.
+If you really want _zero_ custom UI except the agent, keep the app route focused on the built-in chat surface. The only thing the user sees is the chat. Everything else - job history, workspace, settings - is one click away in the panel's tabs.
 
 ### What you still get for free {#still-free}
 
@@ -80,16 +84,36 @@ Even with no custom UI, you still inherit every framework benefit:
 - **Recurring jobs** for scheduled work — "every morning at 7, summarize my unread emails and post to Slack."
 - **The workspace** for per-user customization, skills, memory, MCP connections.
 - **Sub-agent delegation** via [agent teams](/docs/agent-teams).
-- **Portability** — deploys to any serverless host, any SQL database.
+- **Portability** — deploys to any serverless host with any supported SQL database.
 - **Multi-tenant by default** — each user gets their own workspace without a dev-box.
 
 ### Adding a tiny bit of UI {#tiny-ui}
 
 Most pure-agent apps eventually want a little custom UI — not a dashboard, but maybe a status page, a job history, or a config screen. The [drop-in agent](/docs/drop-in-agent) components coexist with anything else you render. Add a single `/status` route that lists recent runs; keep everything else in the chat. That's usually enough.
 
+Future UI-grafting tooling should use a distinct verb or namespace. `agent-native add` already means integration blueprints such as providers, channels, and sandbox adapters, so it should not also mean "add UI to this headless app."
+
+## Repo access for cloud headless {#repo-access}
+
+Local headless apps run against the folder on your machine. For cloud headless
+apps that need repository access, the intended model is connector-scoped access:
+a GitHub connector and token CRUD that can list repositories, search files, read
+files, create or edit files, and delete files with the user's permission.
+
+Do not design this as "clone the user's repo into our VM" or "give the agent a long-lived sandbox copy of the repo" as the primary model. Sandboxes are useful for isolated code execution, but repo access should be a provider integration with explicit tokens, scoped permissions, auditability, and revocation.
+
+## Sharing sessions and runs {#sharing-runs}
+
+Pure-agent work produces durable sessions and runs. Shareability should roll out in phases:
+
+- **First:** read-only share links so a teammate can open a thread or run, inspect the sanitized transcript, outputs, and status, and follow along without taking control.
+- **Later:** permissioned writable collaboration, such as continuing a run, editing schedules, approving actions, or changing configuration with explicit access checks.
+
+That staged model keeps the first sharing surface useful without pretending collaborative control is solved before the permission model is ready.
+
 ## What's next
 
-- [**Getting Started**](/docs/getting-started) — clone the Starter template
+- [**Getting Started**](/docs/getting-started) — create a chat app or headless action first
 - [**Agent Surfaces**](/docs/agent-surfaces) — choose headless, rich chat, embedded sidecar, or full app
 - [**Messaging the agent**](/docs/messaging) — how users talk to the agent across web, Slack, Telegram, email
 - [**Recurring Jobs**](/docs/recurring-jobs) — scheduled prompts the agent runs on its own

package/docs/content/security.md

@@ -28,7 +28,7 @@ Use `defineAction` with a Zod `schema:` for every action. The framework validate
 
 ```typescript
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "Create a note",

package/docs/content/server.md

@@ -65,7 +65,7 @@ hatch.
 
 ```ts
 // actions/classify-message.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { completeText } from "@agent-native/core/server";
 import { z } from "zod";
 

package/docs/content/template-chat.md

@@ -0,0 +1,85 @@
+---
+title: "Chat Template"
+description: "A minimal chat-first agent-native app: durable chat threads, actions, application state, live sync, auth, and room to add your own UI."
+---
+
+# Chat Template
+
+Chat is the basic agent-native app starting point. It gives you a clean ChatGPT-style shell with chat at the center, a threads list on the left, standard app navigation, auth, live sync, actions, and one example action. Start here when you want a real browser app you can build on without committing to a domain template.
+
+If you want the smallest action-only runtime with no browser UI, start with [Pure-Agent Apps](/docs/pure-agent-apps). If you want a finished domain product shape, start from [Calendar](/docs/template-calendar), [Mail](/docs/template-mail), [Content](/docs/template-content), [Forms](/docs/template-forms), [Analytics](/docs/template-analytics), or another domain template.
+
+<!-- screenshot:
+  app: chat
+  view: /
+  shows: Full-page chat app with standard left sidebar, chat threads on the left, centered composer, suggested prompts, and no domain data
+  account: screenshot-account (no domain data needed — chat ships with no seed schema)
+  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
+-->
+
+![Chat template with a full-page agent chat surface and thread sidebar](/screenshots/chat.png)
+
+## What's in it {#whats-in-it}
+
+- **Full-page chat** on `/` using the framework chat surface and durable chat threads.
+- **Thread list in the app sidebar** so users can create, reopen, rename, pin, and archive chats.
+- **Agent chat plugin** pre-configured so the chat talks to the built-in app-agent loop once your agent credentials are set.
+- **Auth** via Better Auth — login, signup, sessions, organizations. The same flow runs locally and in production; in development email verification is skipped.
+- **Actions directory** with one example (`actions/hello.ts`) plus the standard `view-screen` and `navigate` actions.
+- **The framework's core tables** for application state, settings, sessions, resources, chat threads, run history, and other runtime state.
+- **Live sync** (`useDbSync`) already wired so UI auto-refreshes when the agent writes to SQL.
+- **AGENTS.md** with chat-first guidance for adding actions, routes, skills, and application state.
+
+## What's _not_ in it {#not-in-it}
+
+- No domain tables or seed data.
+- No dashboards, lists, charts, forms, or provider integrations.
+- No domain-specific actions beyond the example stub.
+
+That's the point. Chat is a thin, useful default shell for your own agent, not a domain product pretending to be generic.
+
+## When to pick it {#when-to-pick}
+
+- **You want a basic app users can talk to immediately** and then extend with actions and UI.
+- **You have a headless app that needs chat** as the first browser surface.
+- **You want to plug your own agent backend into a familiar chat UI** while keeping Agent-Native's actions, state, auth, and deployment shape.
+- **You are prototyping a custom internal tool** that does not match a domain template.
+
+## Scaffolding {#scaffolding}
+
+```bash
+npx @agent-native/core@latest create my-chat-app --template chat
+cd my-chat-app
+pnpm install
+pnpm dev
+```
+
+Or start with no UI and add a chat surface later:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+From there, copy the Chat template's `/` route and sidebar thread list into your app, or scaffold a Chat app and move your headless actions into its `actions/` directory. The key invariant stays the same: actions are the shared surface for chat, UI, HTTP, MCP, A2A, and CLI.
+
+## Use your own agent backend {#own-agent-backend}
+
+The template uses the built-in app-agent loop by default. To connect a custom backend, swap the chat runtime behind the agent chat plugin instead of rewriting the UI. The Chat route should stay a thin renderer around the shared chat surface; the backend choice belongs in the server plugin/runtime adapter.
+
+Use this when your model orchestration already lives elsewhere, but you still want an app with auth, threads, actions, UI state, and deployable pages.
+
+## First edits {#first-edits}
+
+After scaffolding, ask the agent:
+
+> Add a data model for `notes`. A note has an id, title, body, and owner. Render a notes page at `/notes`, add create/list actions, and keep chat able to create notes.
+
+The agent should add a Drizzle schema, actions, route, navigation, and instructions. Then you can use the notes feature from either the UI or chat.
+
+## What's next
+
+- [**Getting Started**](/docs) — choose between headless, chat, and domain templates
+- [**Agent Surfaces**](/docs/agent-surfaces) — headless, chat, embedded, and full-app patterns
+- [**Actions**](/docs/actions) — the action system chat and UI both call
+- [**Native Chat UI**](/docs/native-chat-ui) — chat surface primitives and runtime options
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) — action-only apps that can grow into Chat later

package/docs/content/template-dispatch.md

@@ -44,7 +44,7 @@ Use Dispatch when:
 - You want a **messaging hub** that routes Slack or Telegram into the right domain agent.
 - You want **scheduled jobs** that pull data from several apps.
 
-Skip it for a single-app scaffold — use the [Starter template](/docs/template-starter) or any of the domain templates directly.
+Skip it for a single-app scaffold — use the [Chat template](/docs/template-chat) or any of the domain templates directly.
 
 Live demo: [dispatch.agent-native.com](https://dispatch.agent-native.com).
 

package/docs/content/tracking.md

@@ -138,7 +138,7 @@ Call `track()` from action handlers to record user or agent activity:
 
 ```ts
 // actions/create-project.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { track } from "@agent-native/core/tracking";
 import { z } from "zod";
 

package/docs/content/what-is-agent-native.md

@@ -5,15 +5,16 @@ description: "Why most AI apps feel half-built, what makes an app truly agent-na
 
 # What Is Agent-Native?
 
-Agent-native is a way of building software where the AI agent and the UI are **equal partners**. Everything the agent can do, the UI can do. Everything the UI can do, the agent can do. They share the same database, the same state, and they stay in sync.
+Agent-native is a way of building software where the AI agent and the product surface around it are **equal partners**. That surface can be one headless action, a rich chat, or a full UI. The important part is that agents and humans share the same actions, database, and state.
 
 If you only remember one thing from this page, remember this: most AI apps today stop one step short of being useful, and that gap is the biggest mistake in the space right now.
 
 ## What it looks like as a user {#what-it-looks-like}
 
-Picture your inbox, calendar, form builder, or analytics dashboard. Sometimes the first screen is chat: you ask what you want, the agent guides setup, shows a table or chart, and opens the right app view. Sometimes chat is docked on the right side of a full application. In both cases, you can:
+Picture a background worker, inbox, calendar, form builder, or analytics dashboard. Sometimes there is no custom screen yet: you run one action or one headless app-agent prompt. Sometimes the first screen is chat: you ask what you want, the agent guides setup, shows a table or chart, and opens the right app view. Sometimes chat is docked on the right side of a full application. Across those shapes, you can:
 
-- **Click anything you'd normally click.** All the buttons, lists, dashboards, keyboard shortcuts — they all still work. This is a real app, not a chat window pretending to be one.
+- **Start with the real operation.** One durable action can run from the CLI, HTTP, MCP, A2A, the app-agent loop, and later a UI.
+- **Click anything you'd normally click when there is a UI.** All the buttons, lists, dashboards, keyboard shortcuts — they all call the same operations the agent can call.
 - **Or just ask.** Type "reply to the email from Sara saying I'll be there by 3" into the agent. It opens the right thread, drafts the reply, and shows it to you for approval — exactly as if you'd done it by hand.
 - **See what it sees.** Open an email, and the agent knows which one. Select a chart, and the agent knows which chart. Highlight a paragraph and hit Cmd+I, and the agent acts on just that paragraph.
 - **Watch it work.** As the agent does things — opens views, edits drafts, runs reports — the UI updates in real time. You can stop it, redirect it, or take over with the mouse at any moment.
@@ -138,7 +139,7 @@ Agent-native apps follow a fork-and-customize model. You start from a **template
 
 Because it's _your_ app, not shared infrastructure, the agent can safely evolve the code. Your app keeps improving as you use it. See [Templates](/docs/cloneable-saas) for the full story.
 
-Not ready to fork a whole template? You can also try agent-native by adding a **skill** to a coding agent you already use — install the Plans skill with `npx @agent-native/core@latest skills add visual-plan`. See [Try it with a skill](/docs/getting-started#try-with-a-skill).
+Not ready to fork a whole template? You can also try agent-native by adding a **skill** to a coding agent you already use — install the Plans skill with `npx @agent-native/core@latest skills add visual-plan`. See the [Skills Guide](/docs/skills-guide#app-backed-skills).
 
 ## Composable agents {#composable-agents}
 
@@ -152,7 +153,7 @@ If you're building or extending an agent-native app, here's the central pattern:
 
 ```ts
 // actions/reply-to-email.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
 export default defineAction({
@@ -185,7 +186,7 @@ One action, many surfaces: the agent calls it as a tool, the UI calls it as a ty
 
 ## What's next {#whats-next}
 
-- [**Getting Started**](/docs) — pick a template and run it
+- [**Getting Started**](/docs) — start with one action, pick a template, or install a skill
 - [**Agent Surfaces**](/docs/agent-surfaces) — choose headless, rich chat, embedded sidecar, or full app
 - [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, context awareness, portability
 - [**Templates**](/docs/cloneable-saas) — templates as complete products you own