@agent-native/core 0.59.1 → 0.60.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.59.1",
+  "version": "0.60.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -38,6 +38,14 @@
     "./brand-kit": "./dist/brand-kit/index.js",
     "./brand-kit/fig": "./dist/brand-kit/fig/index.js",
     "./data-widgets": "./dist/data-widgets/index.js",
+    "./action": {
+      "types": "./dist/action.d.ts",
+      "default": "./dist/action.js"
+    },
+    "./action-ui": {
+      "types": "./dist/action-ui.d.ts",
+      "default": "./dist/action-ui.js"
+    },
     "./agent-web": "./dist/agent-web/index.js",
     "./db": "./dist/db/index.js",
     "./db/schema": "./dist/db/schema.js",
@@ -118,6 +126,7 @@
     "./provider-api/actions/query-staged-dataset": "./dist/provider-api/actions/query-staged-dataset.js",
     "./provider-api/actions/list-staged-datasets": "./dist/provider-api/actions/list-staged-datasets.js",
     "./provider-api/actions/delete-staged-dataset": "./dist/provider-api/actions/delete-staged-dataset.js",
+    "./provider-api/actions/github-repo-files": "./dist/provider-api/actions/github-repo-files.js",
     "./local-artifacts": {
       "types": "./dist/local-artifacts/index.d.ts",
       "default": "./dist/local-artifacts/index.js"

package/src/templates/{starter-shell-sync.spec.ts → chat-shell-sync.spec.ts}

@@ -1,23 +1,23 @@
 /**
  * Guard: the scaffold template (packages/core/src/templates/default) and
- * templates/starter must ship byte-identical shell files so that scaffolded
- * apps start from exactly the same code as the reference starter template.
+ * templates/chat must ship byte-identical shell files so that scaffolded apps
+ * start from exactly the same code as the reference chat template.
  *
  * When you update entry.server.tsx or entry.client.tsx in either location,
  * update the other copy to match (copy in either direction — the content is
  * canonical, not the direction).
  *
  * Sync commands:
- *   # scaffold → starter
+ *   # scaffold → chat
  *   cp packages/core/src/templates/default/app/entry.server.tsx \
- *      templates/starter/app/entry.server.tsx
+ *      templates/chat/app/entry.server.tsx
  *   cp packages/core/src/templates/default/app/entry.client.tsx \
- *      templates/starter/app/entry.client.tsx
+ *      templates/chat/app/entry.client.tsx
  *
- *   # starter → scaffold
- *   cp templates/starter/app/entry.server.tsx \
+ *   # chat → scaffold
+ *   cp templates/chat/app/entry.server.tsx \
  *      packages/core/src/templates/default/app/entry.server.tsx
- *   cp templates/starter/app/entry.client.tsx \
+ *   cp templates/chat/app/entry.client.tsx \
  *      packages/core/src/templates/default/app/entry.client.tsx
  */
 
@@ -40,7 +40,7 @@ function workspaceRoot(): string {
 const ROOT = workspaceRoot();
 
 const SCAFFOLD_DIR = path.join(ROOT, "packages/core/src/templates/default/app");
-const STARTER_DIR = path.join(ROOT, "templates/starter/app");
+const CHAT_TEMPLATE_DIR = path.join(ROOT, "templates/chat/app");
 
 function md5(content: string): string {
   return crypto.createHash("md5").update(content).digest("hex");
@@ -51,7 +51,7 @@ function readFile(dir: string, filename: string): string {
 }
 
 /**
- * Shell files that must be byte-identical between scaffold and starter.
+ * Shell files that must be byte-identical between scaffold and chat template.
  * Each entry is [filename, reason]:
  *   entry.server.tsx — both import the app-local React Router ServerRouter
  *     and pass it into the shared core handler; any future change to the
@@ -70,20 +70,20 @@ const SHELL_FILES: Array<[string, string]> = [
   ],
 ];
 
-describe("starter-shell sync guard", () => {
-  it("keeps scaffold and starter shell files byte-identical", () => {
+describe("chat-shell sync guard", () => {
+  it("keeps scaffold and chat shell files byte-identical", () => {
     const violations: string[] = [];
 
     for (const [filename] of SHELL_FILES) {
       const scaffoldContent = readFile(SCAFFOLD_DIR, filename);
-      const starterContent = readFile(STARTER_DIR, filename);
+      const chatContent = readFile(CHAT_TEMPLATE_DIR, filename);
 
       const scaffoldHash = md5(scaffoldContent);
-      const starterHash = md5(starterContent);
+      const chatHash = md5(chatContent);
 
-      if (scaffoldHash !== starterHash) {
+      if (scaffoldHash !== chatHash) {
         violations.push(
-          `${filename}: scaffold (packages/core/src/templates/default/app) and starter (templates/starter/app) differ.\n` +
+          `${filename}: scaffold (packages/core/src/templates/default/app) and chat (templates/chat/app) differ.\n` +
             `  Update both to match or copy one to the other.`,
         );
       }
@@ -92,7 +92,7 @@ describe("starter-shell sync guard", () => {
     expect(
       violations,
       [
-        "Scaffold/starter shell files have drifted.",
+        "Scaffold/chat shell files have drifted.",
         "Copy the updated file to the other location to fix.",
         "",
         ...violations,
@@ -100,10 +100,10 @@ describe("starter-shell sync guard", () => {
     ).toEqual([]);
   });
 
-  it("every listed shell file exists in both scaffold and starter", () => {
+  it("every listed shell file exists in both scaffold and chat template", () => {
     for (const [filename, reason] of SHELL_FILES) {
       const scaffoldPath = path.join(SCAFFOLD_DIR, filename);
-      const starterPath = path.join(STARTER_DIR, filename);
+      const chatPath = path.join(CHAT_TEMPLATE_DIR, filename);
 
       expect(
         fs.existsSync(scaffoldPath),
@@ -111,8 +111,8 @@ describe("starter-shell sync guard", () => {
       ).toBe(true);
 
       expect(
-        fs.existsSync(starterPath),
-        `${filename} missing from starter (${reason})`,
+        fs.existsSync(chatPath),
+        `${filename} missing from chat template (${reason})`,
       ).toBe(true);
     }
   });

package/src/templates/default/.agents/skills/actions/SKILL.md

@@ -49,7 +49,7 @@ Use `defineAction` with a Zod schema (required for new actions):
 ```ts
 // actions/list-meals.ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { getDb } from "../server/db/index.js";
 import { meals } from "../server/db/schema.js";
 
@@ -352,7 +352,7 @@ This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all
   credentials belong in the encrypted secrets/credential/OAuth stores, never as
   hardcoded literals or shared env fallbacks.
 - **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
-- **Import from `@agent-native/core`** — Don't redefine `parseArgs()` or other utilities locally.
+- **Import action primitives from `@agent-native/core/action`** and CLI helpers such as `parseArgs()` from `@agent-native/core` — do not redefine framework utilities locally.
 - **Do not re-export actions as REST.** The mounted `/_agent-native/actions/:name` endpoint is the REST surface; duplicating it under `/api/*` creates drift and hides the operation from agents.
 
 ## Common Patterns
@@ -361,7 +361,7 @@ This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "List calendar events",
@@ -380,7 +380,7 @@ export default defineAction({
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "Log a meal",
@@ -400,7 +400,7 @@ export default defineAction({
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "Navigate the UI to a view",

package/src/templates/default/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, or advanced features.
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options.
+
+If the action runner is unavailable, search the package docs directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`.
+
+## Useful Slugs
+
+| Need | Slugs |
+| --- | --- |
+| Actions and typed client calls | `actions`, `client` |
+| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
+| UI state visible to the agent | `context-awareness` |
+| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
+| Automations and schedules | `automations`, `recurring-jobs` |
+| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.

package/src/templates/default/AGENTS.md

@@ -1,6 +1,6 @@
 # {{APP_NAME}} — Agent Guide
 
-This app follows the agent-native core philosophy: the agent and UI are equal partners. Everything the UI can do, the agent can do via actions. The agent always knows what you're looking at via application state. See the root AGENTS.md for full framework documentation.
+This app follows the agent-native core philosophy: the agent and UI are equal partners. Everything the UI can do, the agent can do via actions. The agent always knows what you're looking at via application state. Use the framework docs lookup below for version-matched Agent Native documentation.
 
 This is an **@agent-native/core** application -- the AI agent and UI share state through a SQL database, with SSE for in-process live sync and polling as the cross-process/serverless fallback.
 
@@ -13,6 +13,26 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 5. **Agent can update code** -- The agent can modify this app's source code directly.
 6. **No hardcoded secrets or private data** -- Never put API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals in source, docs, tests, fixtures, prompts, screenshots, application state, action responses, or generated content. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 
+## Framework Docs Lookup
+
+Version-matched Agent Native docs ship with `@agent-native/core` in
+`node_modules/@agent-native/core/docs`.
+
+- Use `pnpm action docs-search --query "<topic>"` to search framework docs,
+  bundled `AGENTS.md`, and codebase skills.
+- Use `pnpm action docs-search --slug <slug>` to read a full page. Start with
+  `actions`, `database`, `context-awareness`, `client`, `automations`,
+  `recurring-jobs`, `a2a-protocol`, `external-agents`, `mcp-protocol`,
+  `sharing`, `security`, `pure-agent-apps`, or `agent-surfaces`.
+- Use `pnpm action docs-search --list` to see everything available.
+- If the action runner is unavailable, read
+  `node_modules/@agent-native/core/docs/AGENTS.md` and search
+  `node_modules/@agent-native/core/docs/content/` directly with `rg`.
+
+Read these local package docs before implementing advanced Agent Native
+features. Prefer this app's own `AGENTS.md` and `.agents/skills/` for
+app-specific rules.
+
 ### Database Code
 
 - Define tables with `@agent-native/core/db/schema` helpers (`table`, `text`, `integer`, `real`, `now`, sharing helpers), never `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`.
@@ -115,6 +135,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 | Skill                 | When to read                                                                      |
 | --------------------- | --------------------------------------------------------------------------------- |
+| `agent-native-docs`   | Before using advanced Agent Native framework APIs or generated-app features       |
 | `adding-a-feature`    | **Read first when adding ANY new feature** — the four-area parity checklist       |
 | `real-time-sync`      | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
 | `storing-data`        | Before storing or reading any app state                                           |

package/src/templates/default/actions/hello.ts

@@ -1,4 +1,4 @@
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
 export default defineAction({

package/src/templates/default/actions/navigate.ts

@@ -1,4 +1,4 @@
-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/src/templates/default/actions/view-screen.ts

@@ -1,4 +1,4 @@
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { readAppState } from "@agent-native/core/application-state";
 import { z } from "zod";
 

package/src/templates/headless/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, or advanced features.
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options.
+
+If the action runner is unavailable, search the package docs directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`.
+
+## Useful Slugs
+
+| Need | Slugs |
+| --- | --- |
+| Actions and typed client calls | `actions`, `client` |
+| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
+| UI state visible to the agent | `context-awareness` |
+| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
+| Automations and schedules | `automations`, `recurring-jobs` |
+| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.

package/src/templates/headless/.env.example

@@ -0,0 +1,4 @@
+# Local development can use the SQLite fallback at data/app.db.
+# Set DATABASE_URL for a persistent hosted database.
+# DATABASE_URL=postgres://user:password@host:5432/database
+

package/src/templates/headless/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "all"
+}

package/src/templates/headless/AGENTS.md

@@ -0,0 +1,58 @@
+# {{APP_NAME}} - Agent Guide
+
+This is a headless Agent Native app. It starts with actions instead of a browser UI, so the first useful primitive is callable from the agent, CLI, and action runtime.
+
+This app is not stateless. The Agent Native runtime uses SQL-backed stores for app state, settings, auth/session data, resources, and other framework capabilities when those surfaces are used. Local development can use SQLite at `data/app.db`; hosted or long-lived deployments should set `DATABASE_URL` to a persistent database.
+
+## Working In This App
+
+- Prefer actions in `actions/` for every app operation. Do not create REST wrappers around actions.
+- Keep action inputs validated with Zod and return structured data, not JSON strings.
+- Do not hardcode API keys, tokens, webhook URLs, private data, or credential-looking literals.
+- There is intentionally no `app/` UI shell in this scaffold. When you need a browser UI, use the Chat template as the UI on-ramp and keep `agent-native add` for integration blueprints.
+
+## Framework Docs Lookup
+
+Version-matched Agent Native docs ship with `@agent-native/core` in
+`node_modules/@agent-native/core/docs`.
+
+- Use `pnpm action docs-search --query "<topic>"` to search framework docs,
+  bundled `AGENTS.md`, and codebase skills.
+- Use `pnpm action docs-search --slug <slug>` to read a full page. Start with
+  `actions`, `pure-agent-apps`, `automations`, `recurring-jobs`,
+  `a2a-protocol`, `external-agents`, `mcp-protocol`, `database`, `sharing`,
+  and `security` for advanced headless workflows.
+- Use `pnpm action docs-search --list` to see everything available.
+- If the action runner is unavailable, read
+  `node_modules/@agent-native/core/docs/AGENTS.md` and search
+  `node_modules/@agent-native/core/docs/content/` directly with `rg`.
+
+Read these local package docs before implementing advanced Agent Native
+features. Prefer this app's own `AGENTS.md` for app-specific rules.
+
+## Actions
+
+| Action      | Args              | Purpose                 |
+| ----------- | ----------------- | ----------------------- |
+| `hello`     | `[--name <name>]` | Return a greeting       |
+| `db-schema` |                   | Show SQL schema         |
+| `db-query`  | `--sql "SELECT"`  | Run a scoped SELECT     |
+| `db-exec`   | `--sql "UPDATE"`  | Last-resort maintenance |
+
+Run actions from this app root:
+
+```bash
+pnpm action hello --name Builder
+```
+
+Run the app-agent loop against those actions:
+
+```bash
+pnpm agent "Call the hello action for Builder and explain the result"
+```
+
+## Skills
+
+Skills in `.agents/skills/` provide detailed guidance. Read
+`.agents/skills/agent-native-docs/SKILL.md` before using advanced Agent Native
+framework APIs, generated-app features, automations, A2A, sharing, or MCP.

package/src/templates/headless/DEVELOPING.md

@@ -0,0 +1,22 @@
+# Developing {{APP_NAME}}
+
+Install dependencies, then run the hello action:
+
+```bash
+pnpm install
+pnpm action hello --name Builder
+```
+
+Then run the production app-agent loop against this folder:
+
+```bash
+pnpm agent "Call hello for Builder"
+```
+
+Useful checks:
+
+```bash
+pnpm typecheck
+```
+
+This scaffold intentionally has no `app/` directory, React Router config, Vite config, or dev server. Add those only when you are ready for a UI surface; the Chat template is the UI-first scaffold.