@agent-native/core 0.148.0 → 0.149.0

package/dist/templates/default/app/i18n/ar-SA.ts

@@ -232,7 +232,7 @@ const messages = {
     newTerminal: "محطة جديدة",
     panelOptions: "خيارات لوحة الوكيل",
     collapseSidebar: "طي الشريط الجانبي",
-    widenChat: "توسيع الدردشة إلى 75٪",
+    widenChat: "توسيع الدردشة",
     returnChatToLayout: "إعادة الدردشة إلى تخطيط الصفحة",
     hideChats: "إخفاء الدردشات",
     allChats: "جميع الدردشات",

package/dist/templates/default/app/i18n/de-DE.ts

@@ -234,7 +234,7 @@ const messages = {
     newTerminal: "Neues Terminal",
     panelOptions: "Optionen im Agentenpanel",
     collapseSidebar: "Seitenleiste einklappen",
-    widenChat: "Chat auf 75 % verbreitern",
+    widenChat: "Chat verbreitern",
     returnChatToLayout: "Chat zurück ins Layout",
     hideChats: "Chats ausblenden",
     allChats: "Alle Chats",

package/dist/templates/default/app/i18n/en-US.ts

@@ -229,7 +229,7 @@ const messages = {
     newTerminal: "New terminal",
     panelOptions: "Agent panel options",
     collapseSidebar: "Collapse sidebar",
-    widenChat: "Widen chat to 75%",
+    widenChat: "Widen chat",
     returnChatToLayout: "Return chat to layout",
     hideChats: "Hide chats",
     allChats: "All chats",

package/dist/templates/default/app/i18n/es-ES.ts

@@ -235,7 +235,7 @@ const messages = {
     newTerminal: "Nueva terminal",
     panelOptions: "Opciones del panel de agentes",
     collapseSidebar: "Contraer barra lateral",
-    widenChat: "Ampliar el chat al 75 %",
+    widenChat: "Ampliar el chat",
     returnChatToLayout: "Devolver el chat al diseño",
     hideChats: "Ocultar chats",
     allChats: "Todos los chats",

package/dist/templates/default/app/i18n/fr-FR.ts

@@ -236,7 +236,7 @@ const messages = {
     newTerminal: "Nouvelle borne",
     panelOptions: "Options du panneau d'agent",
     collapseSidebar: "Réduire la barre latérale",
-    widenChat: "Élargir le chat à 75 %",
+    widenChat: "Élargir le chat",
     returnChatToLayout: "Remettre le chat dans la mise en page",
     hideChats: "Masquer les discussions",
     allChats: "Toutes les discussions",

package/dist/templates/default/app/i18n/hi-IN.ts

@@ -221,7 +221,7 @@ const messages = {
     newTerminal: "नया टर्मिनल",
     panelOptions: "एजेंट पैनल विकल्प",
     collapseSidebar: "साइडबार समेटें",
-    widenChat: "चैट को 75% चौड़ा करें",
+    widenChat: "चैट को चौड़ा करें",
     returnChatToLayout: "चैट को लेआउट में वापस लाएँ",
     hideChats: "चैट छुपाएं",
     allChats: "सभी चैट",

package/dist/templates/default/app/i18n/ja-JP.ts

@@ -230,7 +230,7 @@ const messages = {
     newTerminal: "新しいターミナル",
     panelOptions: "エージェントパネルのオプション",
     collapseSidebar: "サイドバーを折りたたむ",
-    widenChat: "チャットを75%に広げる",
+    widenChat: "チャットを広げる",
     returnChatToLayout: "チャットをレイアウトに戻す",
     hideChats: "チャットを非表示にする",
     allChats: "すべてのチャット",

package/dist/templates/default/app/i18n/ko-KR.ts

@@ -225,7 +225,7 @@ const messages = {
     newTerminal: "새로운 터미널",
     panelOptions: "상담원 패널 옵션",
     collapseSidebar: "사이드바 접기",
-    widenChat: "채팅을 75% 너비로 넓히기",
+    widenChat: "채팅 넓히기",
     returnChatToLayout: "채팅을 레이아웃으로 되돌리기",
     hideChats: "채팅 숨기기",
     allChats: "모든 채팅",

package/dist/templates/default/app/i18n/pt-BR.ts

@@ -234,7 +234,7 @@ const messages = {
     newTerminal: "Novo terminal",
     panelOptions: "Opções do painel do agente",
     collapseSidebar: "Recolher barra lateral",
-    widenChat: "Ampliar o chat para 75%",
+    widenChat: "Ampliar o chat",
     returnChatToLayout: "Retornar o chat ao layout",
     hideChats: "Ocultar bate-papos",
     allChats: "Todos os bate-papos",

package/dist/templates/default/app/i18n/zh-CN.ts

@@ -219,7 +219,7 @@ const messages = {
     newTerminal: "新航站楼",
     panelOptions: "代理面板选项",
     collapseSidebar: "收起侧边栏",
-    widenChat: "将聊天窗口加宽到 75%",
+    widenChat: "加宽聊天窗口",
     returnChatToLayout: "将聊天窗口恢复到布局中",
     hideChats: "隐藏聊天记录",
     allChats: "所有聊天记录",

package/dist/templates/default/app/i18n/zh-TW.ts

@@ -217,7 +217,7 @@ const messages = {
     newTerminal: "新航站樓",
     panelOptions: "代理面板選項",
     collapseSidebar: "收起側邊欄",
-    widenChat: "將聊天視窗加寬至 75%",
+    widenChat: "將聊天視窗加寬",
     returnChatToLayout: "將聊天視窗放回版面配置",
     hideChats: "隱藏聊天紀錄",
     allChats: "所有聊天紀錄",

package/dist/templates/default/pnpm-workspace.yaml

@@ -6,3 +6,4 @@ overrides:
 allowBuilds:
   better-sqlite3: true
   esbuild: true
+  tesseract.js: true

package/dist/templates/workspace-root/pnpm-workspace.yaml

@@ -24,6 +24,7 @@ onlyBuiltDependencies:
   - esbuild
   - lightningcss
   - node-pty
+  - tesseract.js
 
 allowBuilds:
   "@swc/core": true
@@ -33,3 +34,4 @@ allowBuilds:
   esbuild: true
   lightningcss: true
   node-pty: true
+  tesseract.js: true

package/docs/content/actions.mdx

@@ -391,12 +391,15 @@ export default defineAction({
   description: "Create a lead in the CRM.",
   schema: z.object({ name: z.string(), company: z.string() }),
   run: async ({ name, company }, ctx) => {
+    if (!ctx?.userEmail) {
+      throw new Error("An authenticated user is required.");
+    }
     const db = getDb();
     await db.insert(schema.leads).values({
       id: crypto.randomUUID(),
       name,
       company,
-      ownerEmail: ctx?.userEmail ?? "system",
+      ownerEmail: ctx.userEmail,
     });
     return { ok: true };
   },

package/docs/content/agent-surfaces.mdx

@@ -10,7 +10,7 @@ A **surface** is the way users (or other systems) interact with your app: a chat
 
 ## How surfaces relate to each other
 
-The four main product shapes sit on a spectrum from most interactive to fully headless. What makes them composable is that the foundation stays the same throughout: the same actions, the same SQL database, and the same agent loop power every shape. Adding a new surface doesn't mean rewriting what's underneath — you're just adding a new way to reach the same operations.
+The four main product shapes sit on a spectrum from most interactive to fully headless. What makes them composable is that they share the same actions and SQL-backed app state. Use the framework agent loop when a surface needs an agent. Adding a new surface doesn't mean rewriting what's underneath — you're adding a new way to reach the same operations.
 
 <Diagram id="doc-block-hvdxgh" title="The surface spectrum" summary={"One action surface, four product shapes, each adding UI without changing the operation underneath."}>
 
@@ -37,7 +37,9 @@ The four main product shapes sit on a spectrum from most interactive to fully he
   </div>
 </div>
 <div class="diagram-base" data-rough>
-  <span class="diagram-muted">same actions · same SQL · same agent loop</span>
+  <span class="diagram-muted"
+    >same actions · SQL-backed state · agent loop where used</span
+  >
 </div>
 ```
 
@@ -192,7 +194,7 @@ Full apps add product UI around the same action and agent contract:
 
 ### SQL state
 
-App data, navigation, settings, and chat history are all durable. The agent reads and writes the same rows the UI does.
+App data, navigation, settings, and chat history are durable in SQL. The agent reads and writes the same rows the UI does.
 
 ### Context awareness
 
@@ -200,7 +202,7 @@ The agent knows the current route, selection, and focused object, so "edit this"
 
 ### Live sync
 
-Agent changes update the UI in real time, and UI changes update the agent's context. No polling, no refresh.
+Agent changes update the UI through live sync, and UI changes update the agent's context. The framework uses SSE with polling fallback, so users do not need to refresh manually.
 
 ### Deep links
 
@@ -224,9 +226,9 @@ want a complete product shape.
 
 Every Agent-Native app eventually needs a place where users can configure their agent: set standing instructions, review what it's done, connect MCP servers, manage automations, and control access. Building that UI from scratch is a lot of work. Agent-Native ships a pre-built full-page component, `AgentTabsPage`, that covers all of it across twelve tabs.
 
-Mount it at `/agent` in your app. Current templates pair that route with an app-navigation entry and pass `agentPageHref="/agent"` to `AgentSidebar`, so the sidebar's Resources and Settings modes can link to the full page without duplicating those flows.
+Mount it at `/settings/agent` in your app. Current templates use this as the canonical route and pass `agentPageHref="/settings/agent"` to `AgentSidebar`. `/agent` is kept as a legacy redirect.
 
-```tsx filename="app/routes/agent.tsx"
+```tsx filename="app/routes/settings.agent.tsx"
 import { AgentTabsPage } from "@agent-native/core/client/agent-chat";
 export default function AgentRoute() {
   return <AgentTabsPage />;

package/docs/content/automations.mdx

@@ -214,7 +214,7 @@ emit(
     customerEmail: "jane@example.com",
     total: 49.99,
   },
-  { owner: "steve@builder.io" },
+  { owner: "user@example.com" },
 );
 ```
 

package/docs/content/cloneable-saas.mdx

@@ -298,12 +298,12 @@ If you're scaffolding now, the CLI command is:
 npx @agent-native/core@latest create my-platform
 ```
 
-The CLI first asks **How do you want to start?** — pick **Full template(s)**
-to reach the multi-select picker (Chat and Headless each scaffold a single
-standalone app directly instead, skipping the picker). Pick one app
-(standalone) or several (workspace — apps share auth, brand, agent config, and
-database). Each picked app is scaffolded into `apps/<name>/` with every file
-you need. For a no-browser automation instead of an app UI, use
+The CLI first asks **How do you want to start?** — pick **Chat** for a minimal
+workspace with Chat and Dispatch, or pick **First-party template(s)** to reach the
+multi-select picker. Community and Headless are the standalone on-ramps.
+Workspace apps share auth, brand, agent config, and database; each app is
+scaffolded into `apps/<name>/` with every file you need. For a no-browser
+automation instead of an app 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/database.mdx

@@ -267,7 +267,12 @@ All database schema updates must be **strictly additive**.
 
 ### Safe Migration Path
 
-Instead of pushing directly, schema changes should be applied via SQL migrations executed at application startup. Implement additive migrations within a server plugin (e.g., `server/plugins/db.ts`) by invoking the framework's `runMigrations()` helper:
+Instead of pushing directly, schema changes should be applied via additive SQL
+migrations. For local development, implement them in a server plugin (e.g.
+`server/plugins/db.ts`) by invoking the framework's `runMigrations()` helper.
+For production or serverless deployments, run migrations in a release or deploy
+step instead of on the first request. The Chat template provides
+`pnpm migrate:production` for this.
 
 <AnnotatedCode
   id="doc-block-zaaj7e"

package/docs/content/deployment.mdx

@@ -435,19 +435,20 @@ The workspace build writes static assets under `dist/_workspace_static/` and rou
 
 ### Keep-warm and scale-to-zero databases {#netlify-keep-warm}
 
-The Netlify build emits a scheduled function that requests `/_agent-native/health` **every minute**. That keeps the server function and its database warm so the next visitor after an idle period doesn't pay a cold start (1–5s on Neon). On provisioned compute this is the right default.
+When enabled, the Netlify build emits a scheduled function that requests `/_agent-native/health` **every minute**. That keeps the server function and its database warm so the next visitor after an idle period doesn't pay a cold start (1–5s on Neon).
 
-**On a metered scale-to-zero database it is the wrong default.** A once-a-minute wake means autosuspend never fires, so the database bills and quota-limits as though it were awake continuously with nobody using the app. On a free-tier Neon this exhausts the compute quota, and the database then rejects **all** reads mid-session — the symptom is a dead app, not a slow one.
+Keep-warm is **disabled by default** because a once-a-minute wake prevents autosuspend on metered scale-to-zero databases. On a free-tier Neon this can exhaust the compute quota, and the database then rejects **all** reads mid-session — the symptom is a dead app, not a slow one. Set `AGENT_NATIVE_ENABLE_KEEP_WARM=1` when the lower next-visitor latency is worth the database awake-time.
 
-Three knobs, all opt-in, defaults unchanged:
+The keep-warm schedule and background-function warm only apply after the main keep-warm flag is enabled:
 
 | Variable                                    | Effect                                                                                                                                                                       |
 | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Skips the scheduled function entirely. The database is free to autosuspend; the next visitor after an idle period pays its cold start.                                       |
-| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Overrides the cadence with a 5-field cron expression, e.g. `*/5 * * * *`. An unparseable value **fails the build** rather than silently reverting to once a minute.          |
+| `AGENT_NATIVE_ENABLE_KEEP_WARM`             | Opts into the scheduled server/database warm. Unset by default.                                                                                                              |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Compatibility kill switch that wins over the opt-in flag when set.                                                                                                           |
+| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Overrides the cadence with a 5-field cron expression, e.g. `*/5 * * * *`. The default cadence when enabled is `* * * * *`; an unparseable value **fails the build**.         |
 | `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | Drops only the background-function warm, keeping the server warm. Warming `server` is one request; warming `-background` starts a fresh container that re-probes the schema. |
 
-If you are on a free or otherwise quota-limited database tier, set `AGENT_NATIVE_DISABLE_KEEP_WARM=1` or pick a slower cadence.
+If you are on a free or otherwise quota-limited database tier, leave `AGENT_NATIVE_ENABLE_KEEP_WARM` unset. If you opt in, use a slower cadence or set `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND=1` to drop the more expensive background warm.
 
 ### On-demand schema DDL {#skip-ensure-tables}
 
@@ -575,8 +576,9 @@ hosting behavior.
 | `APP_URL`                                   | Optional canonical public origin. Checked ahead of `BETTER_AUTH_URL` when resolving the A2A JWT audience, the OAuth public origin, self-dispatch webhook targets, and generated resource links. Set it explicitly on preview/staging deploys where the request host is unreliable.                                                                                      |
 | `AGENT_PROD_CODE_EXECUTION`                 | Optional production code-execution mode: `off` (default), `sandboxed`, or `trusted`. See [Production Code Execution](#production-code-execution).                                                                                                                                                                                                                       |
 | `AGENT_NATIVE_SSR_CACHE`                    | Deployment-wide SSR shell cache policy: unset/`on` keeps the default hard-cache, `off` sends `no-store`, or a duration such as `30s` / `5m` sets a shorter freshness. See [SSR Caching](#ssr-caching).                                                                                                                                                                  |
-| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Skip the Netlify keep-warm scheduled function so a scale-to-zero database can autosuspend. See [Keep-warm](#netlify-keep-warm).                                                                                                                                                                                                                                         |
-| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Override the keep-warm cadence with a 5-field cron expression (default `* * * * *`). An unparseable value fails the build. See [Keep-warm](#netlify-keep-warm).                                                                                                                                                                                                         |
+| `AGENT_NATIVE_ENABLE_KEEP_WARM`             | Opt into the Netlify keep-warm scheduled function. Unset by default; see [Keep-warm](#netlify-keep-warm).                                                                                                                                                                                                                                                               |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Compatibility kill switch for the Netlify keep-warm scheduled function. See [Keep-warm](#netlify-keep-warm).                                                                                                                                                                                                                                                            |
+| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Override the keep-warm cadence with a 5-field cron expression (default `* * * * *` when enabled). An unparseable value fails the build. See [Keep-warm](#netlify-keep-warm).                                                                                                                                                                                            |
 | `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | Drop only the background-function warm and keep the server warm. See [Keep-warm](#netlify-keep-warm).                                                                                                                                                                                                                                                                   |
 | `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS`     | Turn off the in-process backstop sweep timers (automation redispatch, agent-teams reconciliation, sandbox-execution recovery). On serverless these run per warm container, so their query rate scales with instance count. Set it **only** where a durable scheduler already drives the same recovery, or queued work will not be retried.                              |
 | `AGENT_NATIVE_SKIP_ENSURE_TABLES`           | Skip on-demand schema DDL entirely. Removes the schema-probe round trips every cold start pays before doing any work. Requires that your schema is already migrated — see [On-demand schema DDL](#skip-ensure-tables).                                                                                                                                                  |

package/docs/content/docs-components.mdx

@@ -105,7 +105,7 @@ pnpm install
 pnpm dev
 ```
 
-Open `http://localhost:3000`. The app is ready when **VITE ready** appears in the terminal.
+Open the local URL shown by the dev server. The app is ready when **VITE ready** appears in the terminal.
 
 ### Sign in
 
@@ -130,7 +130,7 @@ pnpm install
 pnpm dev
 ```
 
-Open `http://localhost:3000`. The app is ready when **VITE ready** appears in the terminal.
+Open the local URL shown by the dev server. The app is ready when **VITE ready** appears in the terminal.
 
 ### Sign in
 
@@ -215,13 +215,13 @@ Use `Notice` when a `Callout` would be too easy to skim past — something the r
 
 <Banner
   tone="warning"
-  body="This page describes the v9 API. See [Migrating to v10](/docs/migrating-v10) for what changed."
+  body="This page describes a beta API. Check the release notes before using it."
 />
 
 ```mdx
 <Banner
   tone="warning"
-  body="This page describes the v9 API. See [Migrating to v10](/docs/migrating-v10) for what changed."
+  body="This page describes a beta API. Check the release notes before using it."
 />
 ```
 
@@ -377,13 +377,17 @@ Use a fenced code block with the `mermaid` language tag. Mermaid supports flowch
       note: "New action — callable from agent, UI, and CLI",
     },
     { path: "actions/list-text-analyses.ts", change: "added" },
-    { path: "app/routes/analyses.tsx", change: "modified" },
+    { path: "app/routes/analyses.tsx", change: "added" },
     {
-      path: "app/config/nav.ts",
-      change: "modified",
-      note: "Add the new route to the sidebar nav",
+      path: "server/db/schema.ts",
+      change: "added",
+      note: "Define the app-owned table",
+    },
+    {
+      path: "server/plugins/db.ts",
+      change: "added",
+      note: "Run additive migrations",
     },
-    { path: "db/migrations/001_analyses.sql" },
   ]}
 />
 
@@ -397,13 +401,17 @@ Use a fenced code block with the `mermaid` language tag. Mermaid supports flowch
       note: "New action — callable from agent, UI, and CLI",
     },
     { path: "actions/list-text-analyses.ts", change: "added" },
-    { path: "app/routes/analyses.tsx", change: "modified" },
+    { path: "app/routes/analyses.tsx", change: "added" },
     {
-      path: "app/config/nav.ts",
-      change: "modified",
-      note: "Add the new route to the sidebar nav",
+      path: "server/db/schema.ts",
+      change: "added",
+      note: "Define the app-owned table",
+    },
+    {
+      path: "server/plugins/db.ts",
+      change: "added",
+      note: "Run additive migrations",
     },
-    { path: "db/migrations/001_analyses.sql" },
   ]}
 />
 ```

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

@@ -170,7 +170,7 @@ export default function AgentRoute() {
 }
 ```
 
-`<AgentPanel>` gives you the raw tabs (Chat / CLI / Resources) without the sidebar wrapper, the collapse button, or any state persistence. Put it wherever you want; you handle the layout.
+`<AgentPanel>` gives you the raw tabs (Chat / CLI / Resources) without the sidebar wrapper or the collapse button. Put it wherever you want; you control the surrounding layout.
 
 ### Selected props
 

package/docs/content/environment-variables.mdx

@@ -50,9 +50,10 @@ deployment-specific values in the environment or scoped secret store.
 | `ACCESS_TOKEN` / `ACCESS_TOKENS`               | Static bearer fallback for MCP and Connect clients.                                                                                                                     | One token or a delimited token list; these are not browser auth.                                               |
 | `AGENT_PROD_CODE_EXECUTION`                    | Production code-execution policy.                                                                                                                                       | `off`, `sandboxed`, or `trusted`. See [Production Code Execution](/docs/deployment#production-code-execution). |
 | `AGENT_NATIVE_SSR_CACHE`                       | Deployment-wide public SSR shell cache policy.                                                                                                                          | Unset/`on`, `off`, or a duration such as `30s` or `5m`. See [SSR Caching](/docs/deployment#ssr-caching).       |
-| `AGENT_NATIVE_DISABLE_KEEP_WARM`               | Lets a scale-to-zero database autosuspend instead of being woken every minute.                                                                                          | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
-| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`              | Keep-warm cadence override.                                                                                                                                             | A 5-field cron expression such as `*/5 * * * *`; an unparseable value fails the build.                         |
-| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND`    | Drops only the background-function warm and keeps the server warm.                                                                                                      | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
+| `AGENT_NATIVE_ENABLE_KEEP_WARM`                | Opts into the Netlify keep-warm scheduled function; unset by default.                                                                                                   | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM`               | Compatibility kill switch for the Netlify keep-warm scheduled function.                                                                                                 | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
+| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`              | Keep-warm cadence override when enabled.                                                                                                                                | A 5-field cron expression such as `*/5 * * * *`; an unparseable value fails the build.                         |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND`    | Drops only the background-function warm and keeps the server warm when keep-warm is enabled.                                                                            | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
 | `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS`        | Turns off the in-process backstop sweep timers where a durable scheduler drives the same work.                                                                          | `1`; queued work is not retried without another driver.                                                        |
 | `AGENT_NATIVE_SKIP_ENSURE_TABLES`              | Skips on-demand schema DDL for an already-migrated database.                                                                                                            | `1`; see [On-demand schema DDL](/docs/deployment#skip-ensure-tables). You own migrations when this is set.     |
 | `COOKIE_DOMAIN`                                | Shares auth cookies across same-database subdomains when explicitly configured.                                                                                         | A cookie domain.                                                                                               |

package/docs/content/getting-started-actions.mdx

@@ -72,7 +72,7 @@ export default defineAction({
 });
 ```
 
-Run it from the terminal:
+Run this from the app directory:
 
 ```bash
 pnpm action analyze-text --text "Hello world. How are you today?"
@@ -82,9 +82,10 @@ Or ask the agent in chat:
 
 > Run the analyze-text action on "Hello world. How are you today?"
 
-The built-in `data-chart` renderer turns the structured result into a chart in
-the transcript. There is no renderer file or `app/root.tsx` import to add. For
-custom native components, see [Native Chat UI](/docs/native-chat-ui).
+When the agent runs this action in chat, the built-in `data-chart` renderer
+turns the structured result into a chart in the transcript. There is no renderer
+file or `app/root.tsx` import to add. For custom native components, see
+[Native Chat UI](/docs/native-chat-ui).
 
 ## Continue
 

package/docs/content/getting-started-pages.mdx

@@ -6,14 +6,15 @@ description: "Build a React route that calls your action and displays its result
 # Add a Page
 
 This is part three of the Getting Started series. In [Add an Action](/docs/getting-started-actions)
-you created `analyze-text`. Here you'll call that same action from a route. No
-database is needed yet: Chat already includes the SQL runtime for when you need
-to persist domain data.
+you created `analyze-text`. Here you'll call that same action from a route. This
+example does not need a new database table. Chat already stores chat history in
+SQL; add your own tables when you need to persist domain data.
 
 ## Create the route {#add-a-page}
 
-Route files in `app/routes/` are picked up automatically. Create
-`app/routes/text-analyses.tsx`; it will be available at
+The dev server reads route files when it starts. Create
+`app/routes/text-analyses.tsx`, then restart `pnpm dev` if it is already
+running. The route will be available at
 `http://localhost:8080/text-analyses`.
 
 ```tsx filename="app/routes/text-analyses.tsx"
@@ -58,7 +59,7 @@ export default function TextAnalysesRoute() {
 ```
 
 `useActionQuery` calls the same read-only action the agent uses. The page does
-not need a custom API route, a second data layer, or SQL yet.
+not need a custom API route, a second data layer, or a new SQL table.
 
 Open `http://localhost:8080/text-analyses`, or ask the agent:
 

package/docs/content/getting-started.mdx

@@ -6,9 +6,9 @@ description: "Create a Chat app and configure an agent, then extend it with an a
 # Getting Started
 
 Agent-Native apps give the agent and the UI the same [actions](/docs/actions),
-SQL data, and application state. This is the hands-on path: start with chat,
-then add an action and a page. SQL is already configured in Chat and becomes an
-optional next step when results need to persist.
+SQL data, and application state. This path starts with Chat, which already
+creates the framework tables it needs and stores chat history in local SQLite by
+default. Add your own tables only when your app needs to persist domain data.
 
 <Steps>
 
@@ -65,4 +65,5 @@ Once the agent responds, continue with [Add an Action](/docs/getting-started-act
 
 - [What Is Agent-Native?](/docs/what-is-agent-native): the architecture behind this path.
 - [Chat Template](/docs/template-chat): what the starter app includes.
+- [Database](/docs/database): add app-owned tables when your app needs domain data.
 - [FAQ](/docs/faq): answers about models, hosting, and templates.

package/docs/content/notifications.mdx

@@ -14,7 +14,7 @@ import { notify } from "@agent-native/core/notifications";
 
 await notify(
   { severity: "info", title: "Booking confirmed", body: "Jane at 3pm" },
-  { owner: "steve@builder.io" },
+  { owner: "user@example.com" },
 );
 ```
 
@@ -238,14 +238,14 @@ import {
   deleteNotification,
 } from "@agent-native/core/notifications";
 
-const rows = await listNotifications("steve@builder.io", {
+const rows = await listNotifications("user@example.com", {
   unreadOnly: true,
   limit: 50,
 });
-const unread = await countUnread("steve@builder.io");
-await markNotificationRead(rows[0].id, "steve@builder.io");
-await markAllNotificationsRead("steve@builder.io");
-await deleteNotification(rows[0].id, "steve@builder.io");
+const unread = await countUnread("user@example.com");
+await markNotificationRead(rows[0].id, "user@example.com");
+await markAllNotificationsRead("user@example.com");
+await deleteNotification(rows[0].id, "user@example.com");
 ```
 
 Each function is owner-scoped — no cross-user reads, no cross-user writes.

package/docs/content/progress.mdx

@@ -15,7 +15,7 @@ import {
 } from "@agent-native/core/progress";
 
 const run = await startRun({
-  owner: "steve@builder.io",
+  owner: "user@example.com",
   title: "Triage 128 unread emails",
   step: "Fetching inbox",
 });
@@ -100,7 +100,7 @@ Create a run. Returns the full `AgentRun` with a generated id.
 
 ```ts
 const run = await startRun({
-  owner: "steve@builder.io",
+  owner: "user@example.com",
   title: "Ingest 1M rows",
   step: "Opening CSV",
   metadata: { jobId: "abc123", artifactPath: "s3://..." },
@@ -140,9 +140,9 @@ Also emits `run.progress.updated` with the terminal status.
 ```ts
 import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
 
-const active = await listRuns("steve@builder.io", { activeOnly: true });
-const run = await getRun("run-id", "steve@builder.io");
-await deleteRun("run-id", "steve@builder.io");
+const active = await listRuns("user@example.com", { activeOnly: true });
+const run = await getRun("run-id", "user@example.com");
+await deleteRun("run-id", "user@example.com");
 ```
 
 ## HTTP API {#http}

package/docs/content/routing.mdx

@@ -82,7 +82,9 @@ export default function SettingsPage() {
 }
 ```
 
-That's it — React Router picks it up automatically, no registration needed.
+That's it — React Router picks it up automatically after the route table is
+rebuilt. If `pnpm dev` is already running, restart it after adding the file. No
+registration is needed.
 
 ## Dynamic params {#dynamic-params}
 

package/docs/content/server-database.mdx

@@ -5,7 +5,7 @@ description: "Connect a portable SQL database to your agent-native app: schema h
 
 # Database
 
-Every agent-native app stores its state in SQL. The UI and the agent both read and write the same tables through the same actions, using the same [Drizzle ORM](https://orm.drizzle.team) client. When either side changes data, the other sees it through the polling layer.
+Every agent-native app stores its state in SQL. The UI and the agent both read and write the same tables through the same actions, using the same [Drizzle ORM](https://orm.drizzle.team) client. Live sync uses SSE with polling fallback, so changes appear in the other surface without a manual refresh.
 
 <Diagram id="doc-block-9mtx2f" title="How data flows to the database" summary="The UI and the agent both reach the database through the same Actions layer. Both callers use the same getDb() client and the same SQL tables. There is no separate backend for each.">
 
@@ -110,7 +110,7 @@ An app that uses the database needs three files:
 
 - `server/db/schema.ts`: table definitions
 - `server/db/index.ts`: the typed DB client singleton
-- `server/plugins/db.ts`: migrations that run at startup
+- `server/plugins/db.ts`: app-owned migrations for local startup
 
 ### 1. Define your schema {#schema}
 
@@ -208,7 +208,8 @@ Import `getDb` from this template-local path in actions and routes. Do not impor
 
 ### 3. Write migrations {#migrations}
 
-Schema changes are applied at startup via a Nitro plugin in `server/plugins/db.ts`. Use `runMigrations` from `@agent-native/core/db`:
+For local development, schema changes can run through a Nitro plugin in
+`server/plugins/db.ts`. Use `runMigrations` from `@agent-native/core/db`:
 
 <AnnotatedCode
   id="doc-block-7qwlpz"
@@ -242,7 +243,15 @@ Schema changes are applied at startup via a Nitro plugin in `server/plugins/db.t
   ]}
 />
 
-`runMigrations` runs each entry in order once, then records the version so it is skipped on future restarts. Entries are idempotent. The plugin is safe to call on every boot.
+`runMigrations` runs each pending entry in order once, records it as applied, and
+skips it on later runs. Give new entries a stable `name`; named migrations are
+tracked independently of their version number.
+
+<Callout tone="warning">
+  For production or serverless deployments, run migrations in a release or
+  deploy step instead of on the first request. The Chat template provides `pnpm
+  migrate:production` for this.
+</Callout>
 
 <Callout tone="warning">
   Give every new migration a stable `name` (e.g. `{ version: 4, name: