@agent-native/core 0.59.0 → 0.60.0

package/docs/AGENTS.md

@@ -0,0 +1,57 @@
+# Agent Native Docs For Agents
+
+These docs are bundled with `@agent-native/core` and installed at:
+
+```txt
+node_modules/@agent-native/core/docs
+```
+
+Use these version-matched markdown docs before coding against Agent Native
+framework APIs or advanced features. Public docs are useful for browsing, but
+the package docs match the exact framework version installed in the app.
+
+## Fast Lookup
+
+From a generated app root:
+
+```bash
+pnpm action docs-search --list
+pnpm action docs-search --query "actions"
+pnpm action docs-search --slug actions
+```
+
+The built-in app agent also has a read-only `docs-search` tool with the same
+`list`, `query`, and `slug` options.
+
+If the action runner is unavailable, search the markdown files directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+```
+
+Then read the matching files under `node_modules/@agent-native/core/docs/content/`.
+
+## What To Read First
+
+| Task                                  | Start with                                                                                               |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Define or call app operations         | `content/actions.md`, `content/client.md`                                                                |
+| Add SQL data, schema, or access rules | `content/database.md`, `content/security.md`, `content/sharing.md`                                       |
+| Keep the UI and agent in sync         | `content/context-awareness.md`, `content/client.md`                                                      |
+| Build headless or chat-first apps     | `content/pure-agent-apps.md`, `content/agent-surfaces.md`, `content/using-your-agent.md`                 |
+| Add automations or scheduled work     | `content/automations.md`, `content/recurring-jobs.md`                                                    |
+| Compose apps or call sibling agents   | `content/a2a-protocol.md`, `content/multi-app-workspace.md`, `content/workspace.md`                      |
+| Expose tools to external agents       | `content/external-agents.md`, `content/mcp-protocol.md`, `content/mcp-apps.md`, `content/mcp-clients.md` |
+| Add integrations, setup, or secrets   | `content/onboarding.md`, `content/workspace-connections.md`, `content/security.md`                       |
+| Build extensions or custom widgets    | `content/extensions.md`, `content/agent-web-surfaces.md`                                                 |
+| Deploy or configure hosting           | `content/deployment.md`, `content/server.md`                                                             |
+| Write agent instructions or skills    | `content/skills-guide.md`, `content/writing-agent-instructions.md`                                       |
+
+## Rules
+
+- Prefer the app's own `AGENTS.md` and `.agents/skills/` for app-specific
+  behavior. Use this package docs tree for framework APIs and patterns.
+- If local instructions and package docs conflict, local app instructions win
+  for that app, but verify the framework API shape in package docs or types.
+- Do not invent Agent Native APIs. Search these docs and installed type
+  definitions before adding imports, routes, actions, or framework config.

package/docs/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: agent-native-docs
+description: "How to look up version-matched Agent Native framework docs in node_modules. Use before coding against @agent-native/core APIs or advanced features."
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing non-trivial Agent Native functionality, read the
+version-matched docs installed with `@agent-native/core`.
+
+## How
+
+1. Start from the generated app root.
+2. Search with `pnpm action docs-search --query "<feature>"`.
+3. Read a specific page with `pnpm action docs-search --slug <slug>`.
+4. If the action runner is unavailable, search
+   `node_modules/@agent-native/core/docs` directly with `rg`.
+5. For app-specific rules, also read the app's own `AGENTS.md` and any relevant
+   `.agents/skills/<name>/SKILL.md`.
+
+## 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 local package docs are present.
+- Do not add custom REST wrappers for normal app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.

package/docs/content/a2a-protocol.md

@@ -305,7 +305,7 @@ A mail agent needs analytics data. The analytics agent exposes a "run-query" ski
 
 ```ts
 // In the mail agent's actions/get-analytics.ts
-import { defineAction } from "@agent-native/core/server";
+import { defineAction } from "@agent-native/core/action";
 import { callAgent } from "@agent-native/core/a2a";
 import { z } from "zod";
 

package/docs/content/actions.md

@@ -19,11 +19,51 @@ One definition, seven consumers. This is rung 3 of the [ladder](/docs/what-is-ag
 If you are deciding whether to expose an operation headlessly, in chat, in an
 embedded sidecar, or as a full app screen, see [Agent Surfaces](/docs/agent-surfaces).
 
+## Start with one action {#hello-action}
+
+The primitive-first on-ramp is one action, not a template. In a headless
+scaffold such as `agent-native create my-agent --headless`, this can be the
+whole first app:
+
+```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}!` };
+  },
+});
+```
+
+Run it from the same folder:
+
+```bash
+pnpm action hello --name Steve
+```
+
+Then run the app-agent loop against the folder:
+
+```bash
+pnpm agent "Call hello for Steve and explain the result"
+```
+
+That is the same app-agent loop your scheduled jobs, chat UI, external MCP
+tools, and future screens will use. Chat and domain templates are for adding UI
+around actions, not a required prerequisite for the action itself.
+
 ## Defining an action {#defining}
 
 ```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({
@@ -229,7 +269,7 @@ User-owned tables must scope reads through `accessFilter` and writes through `as
 
 ```ts
 // actions/create-lead.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 import { getDb } from "../server/db/index.js";
 import * as schema from "../server/db/schema.js";
@@ -315,12 +355,12 @@ summaries, and insight cards; use [MCP Apps](/docs/mcp-apps) for inline UI in
 external MCP hosts.
 
 ```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: "Summarize response trends.",
@@ -411,7 +451,7 @@ Reads the current navigation state, fetches contextual data, and returns a snaps
 
 ```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 { z } from "zod";
 
@@ -438,7 +478,7 @@ Writes a one-shot navigation command to application state. The UI reads it, navi
 
 ```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/agent-surfaces.md

@@ -13,13 +13,13 @@ application.
 The useful way to choose is not by protocol first. Choose the product surface
 you want, then use the matching primitive.
 
-| Surface                       | Use it when                                                                                                 | Start with                                                         |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| **Headless agent/actions**    | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `defineAction`, HTTP, CLI, MCP, A2A                                |
-| **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop.                                   | `<AgentChatSurface>`, `<AssistantChat>`, `createAgentChatPlugin()` |
-| **Rich chat on your agent**   | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`            |
-| **Embedded sidecar**          | You already have a SaaS app and want an agent beside it with page context and host commands.                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`         |
-| **Full application**          | Humans and agents should share durable screens, data, navigation, and collaboration.                        | Templates, actions, SQL state, context awareness                   |
+| Surface                       | Use it when                                                                                                 | Start with                                                                                  |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **Headless agent/actions**    | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
+| **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop.                                   | [Chat template](/docs/template-chat), `<AgentChatSurface>`, `<AssistantChat>`               |
+| **Rich chat on your agent**   | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`                                     |
+| **Embedded sidecar**          | You already have a SaaS app and want an agent beside it with page context and host commands.                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`                                  |
+| **Full application**          | Humans and agents should share durable screens, data, navigation, and collaboration.                        | Templates, actions, SQL state, context awareness                                            |
 
 Those are stages, not separate products. A workflow can start as a headless
 action, appear in chat as a table or chart, and later become a full screen in an
@@ -31,11 +31,19 @@ Use the headless path when no one needs to stare at a custom app screen while
 the work runs: scheduled jobs, integrations, backend workflows, CLI loops,
 another agent, or an existing product calling into Agent-Native.
 
-Most headless integrations should start with actions:
+The smallest local path is a headless scaffold plus one action:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+cd my-agent
+pnpm install
+```
+
+Then define the durable operation:
 
 ```ts
 // actions/summarize-week.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
 export default defineAction({
@@ -52,14 +60,26 @@ One action is then callable as:
 
 - **HTTP** — `POST /_agent-native/actions/summarize-week`
 - **CLI** — `pnpm action summarize-week --formId form_123`
+- **App-agent CLI** — `pnpm agent "Summarize form_123"`
 - **MCP** — from Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot, and other MCP hosts
 - **A2A** — from another agent-native app or agent peer
 - **UI** — through `useActionQuery`, `useActionMutation`, or `callAction`
 - **Agent tool** — from the built-in chat loop
 
-If you need the whole agent loop headlessly, use the server API from a worker,
-job, integration webhook, or custom host. This is lower-level than actions: you
-provide the engine, model, messages, actions, and event sink yourself.
+This is not a no-database or stateless mode. The app-agent loop stores sessions,
+threads, runs, settings, credentials, application state, and share records in
+SQL. Local development defaults to SQLite; hosted headless apps should use a
+persistent SQL database.
+
+If you need the whole agent loop headlessly from the project folder, use:
+
+```bash
+pnpm agent "Summarize this week's forms."
+```
+
+Workers, jobs, integration webhooks, and custom hosts can use the server API
+directly. This is lower-level than actions: you provide the engine, model,
+messages, actions, and event sink yourself.
 
 ```ts
 import {
@@ -97,11 +117,49 @@ For most apps, scheduled prompts and integration webhooks already call this loop
 for you. Reach for direct `runAgentLoop()` when you are building a custom
 headless host, eval runner, or server-side orchestration surface.
 
+### Running against a folder {#folder-loop}
+
+If your goal is "run an agent against this folder," start with the app-agent
+loop in that folder: scaffold the headless app, add actions/instructions, run
+`pnpm agent "..."`. That keeps the work inside the same action/runtime/state
+contract the app will use in production.
+
+External coding harnesses are a separate product surface for embedding Claude
+Code, Codex, Pi, Cursor, Mastra, or similar runtimes inside an Agent-Native app.
+Use them when you are building a coding-agent product, not as the default way to
+start a local agent-native workflow.
+
+### Cloud repo access {#cloud-repo-access}
+
+For cloud headless apps that need repository access, the planned model is a
+GitHub connector plus token CRUD: list repositories, search files, read files,
+create or edit files, delete files, and revoke access through provider-scoped
+credentials.
+
+Do not treat a VM clone or long-lived sandbox checkout as the primary cloud
+repo-access model. Sandboxes still matter for isolated code execution, but
+repository access should be explicit, permissioned, auditable, and revocable
+through the connector layer.
+
+### Sharing sessions and runs {#sharing-runs}
+
+Headless sessions and runs are durable objects. Shareability should be phased:
+read/share links first, so teammates can inspect sanitized prompts, outputs,
+and run status; permissioned writable collaboration later, so continuing a run,
+approving actions, editing schedules, or changing configuration goes through
+explicit access checks.
+
 ## Rich chat on Agent-Native {#rich-chat}
 
 Use the built-in chat when the user should talk to the agent, see tool calls,
 approve work, inspect native results, and keep a durable thread history.
 
+For a full app starting point, use the [Chat template](/docs/template-chat):
+
+```bash
+npx @agent-native/core@latest create my-chat-app --template chat
+```
+
 The simplest full-page chat:
 
 ```tsx
@@ -131,6 +189,9 @@ components in the chat, without iframes. See [Native Chat UI](/docs/native-chat-
 Use this path when your agent is already built with another framework or
 runtime and you want Agent-Native's chat UI around it.
 
+The [Chat template](/docs/template-chat) is still useful here: keep its app
+shell and thread UI, then swap the runtime behind the chat plugin or route.
+
 `AgentChatRuntime` is the boundary. Your runtime streams normalized events;
 Agent-Native renders the composer, transcript, tool calls, approvals, native
 widgets, and app layout.
@@ -245,8 +306,9 @@ Full apps add product UI around the same action and agent contract:
 - **Deep links** — action results can open the right app view.
 - **Native chat widgets** — tables, charts, cards, approvals, and typed results appear inline.
 
-Start from a [template](/docs/cloneable-saas) when you want a complete app, or
-from [Starter](/docs/template-starter) when you want only the framework wiring.
+Start from the [Chat template](/docs/template-chat) when you want a minimal app
+around your actions, or from a domain [template](/docs/cloneable-saas) when you
+want a complete product shape.
 
 ## How to choose {#how-to-choose}
 

package/docs/content/cli-adapters.md

@@ -228,7 +228,7 @@ Actions can use CLI adapters directly for structured access:
 
 ```ts
 // actions/list-prs.ts
-import { defineAction } from "@agent-native/core/server";
+import { defineAction } from "@agent-native/core/action";
 import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
 import { z } from "zod";
 

package/docs/content/cloneable-saas.md

@@ -15,6 +15,7 @@ Each one is a real app you could use today, and the launching pad for your own v
 
 | Template                                  | What it is                                                                                                     |
 | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| [**Chat**](/docs/template-chat)           | Minimal chat-first app with durable threads, actions, auth, and a clean path to custom UI or your own backend. |
 | [**Mail**](/docs/template-mail)           | An agent-native Superhuman. Inbox, labels, AI triage, keyboard-first, drafts and sends through the agent.      |
 | [**Calendar**](/docs/template-calendar)   | An agent-native Google Calendar. Events, sync, public booking links, agent-driven scheduling.                  |
 | [**Content**](/docs/template-content)     | Open-source Obsidian for MDX. Local Markdown/MDX, Tiptap editor, Notion sync, real-time multi-user collab.     |
@@ -29,7 +30,7 @@ Each one is a real app you could use today, and the launching pad for your own v
 | [**Plan**](/docs/template-plan)           | Visual plans and PR recaps with diagrams, wireframes, and annotations.                                         |
 | [**Dispatch**](/docs/template-dispatch)   | The workspace control plane: shared secrets, reusable integrations, Slack/Telegram, scheduled jobs.            |
 
-Don't want a domain template? See [Pure-Agent Apps / Starter](/docs/pure-agent-apps) for the minimal scaffold.
+Don't want a domain template? Use [Chat](/docs/template-chat) when you want a basic app users can talk to immediately, or start action-first with [Pure-Agent Apps](/docs/pure-agent-apps).
 
 See the full catalog under [Templates](/templates), or jump straight to one — for example, [Dispatch](/docs/template-dispatch) is a great place to start if you want a workspace-style app.
 
@@ -72,11 +73,11 @@ You don't have to. Every template is also available as a hosted app on `agent-na
 
 ## Try it with a skill {#try-with-a-skill}
 
-Not ready to scaffold? You can add agent-native superpowers to a coding agent you already use with a single command — no app needed. See [Try it with a skill](/docs/getting-started#try-with-a-skill) in Getting Started.
+Not ready to scaffold? You can add agent-native superpowers to a coding agent you already use with a single command — no app needed. See the [Skills Guide](/docs/skills-guide#app-backed-skills).
 
 ## Building on this
 
-- [**Getting Started**](/docs/getting-started) — clone your first template and run it locally
+- [**Getting Started**](/docs/getting-started) — create a minimal chat app or headless action
 - [**Messaging the agent**](/docs/messaging) — how users (and you) talk to the agent that ships with each template
 - [**Multi-App Workspace**](/docs/multi-app-workspace) — bundle several templates into one workspace that shares auth, brand, and agent
 - [**Dispatch**](/docs/template-dispatch) — the workspace control plane template
@@ -90,7 +91,7 @@ If you're scaffolding now, the CLI command is:
 npx @agent-native/core@latest create my-platform
 ```
 
-You'll get a multi-select picker. Pick one app (standalone) or several (workspace — apps share auth, brand, agent config, and database). Each picked template is scaffolded into `apps/<name>/` with every file you need.
+You'll get a multi-select picker. Pick one app (standalone) or several (workspace — apps share auth, brand, agent config, and database). Each picked template is scaffolded into `apps/<name>/` with every file you need. For an action-only app instead of a template UI, use `npx @agent-native/core@latest create my-agent --headless`.
 
 Fill in `.env` (mostly `ANTHROPIC_API_KEY` and `DATABASE_URL`), `pnpm install`, `pnpm dev`, and it works. No "TODO: implement login," no placeholder routes.
 

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";
@@ -305,6 +305,15 @@ On the UI side you never poll or delete this key by hand. Both directions -- wri
 
 The `navigation` key belongs to the UI; the agent must never write to it directly. The agent writes `navigate`, the UI performs the move, and that move is what updates `navigation`.
 
+When the destination has a real URL, include a same-origin `path` on the
+`navigate` command and have the UI prefer that path before falling back to
+semantic fields. Keep app navigation single-channel: do not write both
+`navigate` and `__set_url__` for the same move. `__set_url__` is for the
+framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
+changes. For commands that can arrive while chat is streaming, commit the route
+with `navigate(path, { replace: true, flushSync: true })` instead of wrapping it
+in a view transition so the address bar and visible page stay together.
+
 ## The useNavigationState hook {#use-navigation-state}
 
 `useNavigationState` is **your app's hook, not a framework import.** Every template ships one at `app/hooks/use-navigation-state.ts` and calls it once from the app shell (`root.tsx`). It is the single place that wires navigation in both directions:
@@ -322,6 +331,7 @@ import { TAB_ID } from "@/lib/tab-id";
 interface NavigationState {
   view: "inbox" | "thread";
   threadId?: string;
+  path?: string;
 }
 
 export function useNavigationState() {
@@ -337,9 +347,11 @@ export function useNavigationState() {
 
     // agent → UI: turn a `navigate` command into a route to push.
     getCommandPath: (command) =>
-      command.view === "thread" && command.threadId
+      command.path ??
+      (command.view === "thread" && command.threadId
         ? `/thread/${command.threadId}`
-        : "/",
+        : "/"),
+    navigateOptions: { replace: true, flushSync: true },
   });
 }
 ```

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";
@@ -234,15 +236,20 @@ export function useNavigationState() {
       selectedId: searchParams.get("id"),
     }),
     getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
   });
 }
 ```
 
 Keep shareable filters in URL query params. The framework exposes them to the agent as `<current-url>` and the built-in agent can change them with `set-search-params`; `navigation` should hold semantic IDs and aliases, not a second copy of the full query string.
 
+For app navigation, prefer one `navigate` command that includes a same-origin
+`path` when the URL is known. Do not also write `__set_url__` for the same move;
+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";
 
@@ -251,6 +258,7 @@ export default defineAction({
   schema: z.object({
     view: z.enum(["home", "project"]),
     projectId: z.string().optional(),
+    path: z.string().optional(),
   }),
   run: async (args) => {
     await writeAppState("navigate", args);

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}