@agent-native/core 0.59.1 → 0.60.0

package/docs/content/code-agents-ui.md

@@ -67,7 +67,7 @@ That separation matters. The UI can be reused by templates, but native process c
 The old hidden `code` template has been removed. To build a browser-hosted Code surface, create a normal app and mount the shared UI package with a host implementation:
 
 ```bash
-npx @agent-native/core@latest create my-code-ui --template starter
+npx @agent-native/core@latest create my-code-ui --template chat
 cd my-code-ui
 pnpm add @agent-native/code-agents-ui
 pnpm install

package/docs/content/components.md

@@ -338,7 +338,7 @@ If you truly need raw text-in/text-out, keep it server-side and use
 action so the UI and agent share the same capability.
 
 ```ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { completeText } from "@agent-native/core/server";
 
 export default defineAction({

package/docs/content/context-awareness.md

@@ -186,7 +186,7 @@ Every template should have a `view-screen` action. It reads navigation and selec
 
 ```ts
 // actions/view-screen.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { readAppState } from "@agent-native/core/application-state";
 import { eq, inArray } from "drizzle-orm";
 import { z } from "zod";

package/docs/content/creating-templates.md

@@ -17,21 +17,23 @@ A good template:
 - Registers onboarding steps for required providers and secrets.
 - Works as a standalone app and as part of a multi-app workspace.
 
-## Start from Starter {#start-from-starter}
+## Start from Chat {#start-from-chat}
 
-Use the CLI-only Starter scaffold when you want a blank app with the framework wiring already in place:
+Use the Chat template when you want a minimal app with the framework wiring already in place:
 
 ```bash
-npx @agent-native/core@latest create my-template --template starter --standalone
+npx @agent-native/core@latest create my-template --template chat --standalone
 ```
 
-For a workspace with multiple apps, run the picker and include Starter with any domain templates you want:
+For a workspace with multiple apps, run the picker and include Chat with any domain templates you want:
 
 ```bash
 npx @agent-native/core@latest create my-platform
 ```
 
-Starter gives you auth, the agent sidebar, SQL-backed resources, tools, application state, actions, and polling sync. You add the domain model and product UI.
+Chat gives you auth, durable chat threads, SQL-backed resources, tools, application state, actions, and polling sync. You add the domain model and product UI.
+
+If you are not building a reusable UI template yet, use the headless on-ramp in [Getting Started](/docs/getting-started#create-your-agent): define one action, run it with `pnpm agent`, and add UI later when the workflow needs a durable surface.
 
 ## Project Structure {#project-structure}
 
@@ -137,7 +139,7 @@ Actions are the single source of truth for app behavior. The agent calls them as
 
 ```ts
 // actions/create-project.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { getDb } from "../server/db/index.js"; // getDb is created per app via createGetDb(schema) in server/db/index.ts
 import { nanoid } from "nanoid";
 import { z } from "zod";
@@ -247,7 +249,7 @@ that key is reserved for the framework URL tools and URL-only filter changes.
 
 ```ts
 // actions/navigate.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { writeAppState } from "@agent-native/core/application-state";
 import { z } from "zod";
 

package/docs/content/drop-in-agent.md

@@ -255,7 +255,7 @@ history, run state, or user steering, use `completeText()` from
 an action so the UI and agent share the same operation.
 
 ```ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { completeText } from "@agent-native/core/server";
 
 export default defineAction({

package/docs/content/faq.md

@@ -11,13 +11,15 @@ Common questions about agent-native, organized from "I'm just looking" to "I'm w
 
 ### What is agent-native? {#what-is-agent-native}
 
-Agent-native is a framework for building apps where the AI agent and the UI are equal partners. They share the same database, the same state, and they always stay in sync. Everything the UI can do, the agent can do — and vice versa. See [What Is Agent-Native?](/docs/what-is-agent-native) for the full explanation.
+Agent-native is a framework for building apps where the AI agent and the product surface around it are equal partners. That surface can start as one headless action, grow into rich chat, or become a full UI. The invariant is that agents and humans share the same actions, database, and state. See [What Is Agent-Native?](/docs/what-is-agent-native) for the full explanation.
 
 ### Who is this for? {#who-is-this-for}
 
 Agent-native is for people who want a real app and an AI agent to work from the same data and actions. The common paths are:
 
 - **Use a hosted app** if you want Mail, Calendar, Forms, Plan, or another finished template with no setup — start at the [template gallery](/templates).
+- **Start with Chat** if you want a basic app users can talk to immediately, then extend with actions and screens — start with [Getting Started](/docs/getting-started) or [Chat](/docs/template-chat).
+- **Start primitive-first** if you want one action and a headless app-agent loop before committing to UI — start with [Getting Started](/docs/getting-started).
 - **Fork and customize a template** if you want your own SaaS product with auth, database, UI, and agent actions already wired — see [Templates](/docs/cloneable-saas).
 - **Build from scratch** if you want the framework primitives for a new agent-driven product — start with [Getting Started](/docs/getting-started).
 - **Connect another agent or code tool** if you want Claude, ChatGPT, Codex, Cursor, or GitHub Copilot / VS Code to use an agent-native app — see [External Agents](/docs/external-agents) and [Skills Guide](/docs/skills-guide).
@@ -59,7 +61,7 @@ You can, but agent-native works best when built from the ground up. The architec
 
 ### What templates are available? {#what-templates-are-available}
 
-The framework ships with production-ready templates including [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (visual plans and PR recaps), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch), and more. Each is a complete app with UI, agent actions, database schema, and AI instructions ready to go. See [Templates](/docs/cloneable-saas) for the full catalog.
+The framework ships with production-ready templates including [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (visual plans and PR recaps), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch), and more. Each is a complete app with UI, agent actions, database schema, and AI instructions ready to go. See [Templates](/docs/cloneable-saas) for the full catalog.
 
 ### Can I customize templates? {#can-i-customize-templates}
 
@@ -67,11 +69,11 @@ That's the whole point. Fork a template and customize it by asking the agent. "A
 
 ### Can I build something the templates don't cover? {#build-from-scratch}
 
-Yes. Run `npx @agent-native/core@latest create my-app` and accept the default **Starter** selection in the picker (or pass `--template starter`) — you get the framework scaffolding (frontend, backend, agent panel, database) but no domain-specific code. See [Getting Started](/docs/getting-started). For agent-first products with no traditional UI, see [Pure-Agent Apps](/docs/pure-agent-apps).
+Yes. If you want a basic chat app, run `npx @agent-native/core@latest create my-chat-app --template chat`; you get durable chat threads, actions, auth, SQL-backed runtime state, and room to add your own screens. If you want the smallest action-first app with no UI, run `npx @agent-native/core@latest create my-agent --headless`. See [Getting Started](/docs/getting-started), [Pure-Agent Apps](/docs/pure-agent-apps), and [Chat](/docs/template-chat).
 
 ### Can I try it without forking a template? {#try-with-a-skill}
 
-Yes — install a skill into a coding agent you already use with one command and no scaffold required. See [Try it with a skill](/docs/getting-started#try-with-a-skill) in Getting Started for the full walkthrough.
+Yes — install a skill into a coding agent you already use with one command and no scaffold required. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for the walkthrough.
 
 ## Agent capabilities {#agent-capabilities}
 

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";