@agent-native/core 0.147.0 → 0.148.1

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/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/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

@@ -24,44 +24,45 @@ deployment-specific values in the environment or scoped secret store.
 
 ## Common application and deployment variables
 
-| Variable                                    | What it controls                                                                                                                                                        | Supported values or format                                                                                     |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `DATABASE_URL`                              | Primary SQL connection. Local development falls back to SQLite when it is unset. Production also accepts `<APP_NAME>_DATABASE_URL` or Netlify's `NETLIFY_DATABASE_URL`. | A provider-specific SQL URL, or unset for local SQLite.                                                        |
-| `DATABASE_AUTH_TOKEN`                       | Separate database token when the database provider requires one.                                                                                                        | An opaque provider token, or unset when the URL includes authentication.                                       |
-| `APP_URL`                                   | Optional canonical public origin used for auth, OAuth, A2A, webhooks, and generated links. Netlify and Vercel metadata are inferred when it is unset.                   | An absolute public `http(s)` origin.                                                                           |
-| `BETTER_AUTH_URL`                           | Optional Better Auth origin override. Known template or request context, `APP_URL`, and platform metadata such as Netlify or Vercel are used when it is unset.          | An absolute public `http(s)` origin.                                                                           |
-| `APP_BASE_PATH`                             | Mounts an app under a path such as `/mail`.                                                                                                                             | Unset for a standalone app, or a slash-prefixed path.                                                          |
-| `PORT`                                      | Local Node/Nitro server port.                                                                                                                                           | A decimal TCP port.                                                                                            |
-| `NITRO_PRESET`                              | Build and deployment adapter.                                                                                                                                           | A preset supported by the target host, such as `node`, `netlify`, `vercel`, or `cloudflare_pages`.             |
-| `BETTER_AUTH_SECRET`                        | Stable Better Auth session signing secret for standalone production apps. Workspace deploys can derive it from `A2A_SECRET`.                                            | A fresh random value of at least 32 characters.                                                                |
-| `OAUTH_STATE_SECRET`                        | Dedicated signing key for OAuth state envelopes. Falls back to `BETTER_AUTH_SECRET` when unset.                                                                         | A fresh random value of at least 32 characters.                                                                |
-| `A2A_SECRET`                                | Shared HMAC for trusted cross-app A2A calls and signed handoffs.                                                                                                        | One shared random value across trusted apps.                                                                   |
-| `SECRETS_ENCRYPTION_KEY`                    | Legacy app-local/shared encryption fallback.                                                                                                                            | A stable encryption key; prefer the workspace key for new shared vaults.                                       |
-| `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Stable encryption key for a workspace-shared secrets vault.                                                                                                             | The same stable key in every app that reads the vault.                                                         |
-| `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Previous workspace key during rotation.                                                                                                                                 | The old key only; remove it after migration.                                                                   |
-| `ANTHROPIC_API_KEY`                         | Optional deploy-level fallback for the embedded production agent.                                                                                                       | An API key; prefer scoped credentials for multi-tenant apps.                                                   |
-| `AGENT_ENGINE`                              | Explicitly selects the agent engine instead of auto-detecting from provider keys.                                                                                       | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`.                      |
-| `AGENT_ENGINE_PREFER_BYO_KEY`               | Prefers a provider key you set over the managed Builder gateway during auto-detection.                                                                                  | `true` or `1`; Builder still applies as the fallback when no provider key is set.                              |
-| `AUTH_MODE`                                 | Selects the local authentication behavior used by CLI and agent flows.                                                                                                  | Unset or `local`; this is not a browser login bypass.                                                          |
-| `AUTH_DISABLED`                             | Disables auth for local or preview-only work. Unset already means false.                                                                                                | `true` or `1`; never use on a public production app.                                                           |
-| `AUTH_MAGIC_LINK`                           | Controls the password-first versus magic-link sign-in path.                                                                                                             | `0` keeps password-first sign-in; otherwise a configured email transport can enable magic links.               |
-| `AUTH_SKIP_EMAIL_VERIFICATION`              | Skips signup email verification for local QA or previews.                                                                                                               | `1`; never use it to weaken production auth.                                                                   |
-| `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_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.                                                                                               |
-| `CORS_ALLOWED_ORIGINS`                      | Cross-origin request allowlist.                                                                                                                                         | A comma-separated list of exact origins.                                                                       |
-| `WEBHOOK_BASE_URL`                          | Optional public base URL for self-callback and webhook targets.                                                                                                         | An absolute public `http(s)` origin.                                                                           |
-| `APP_NAME`                                  | App identity used by workspace and app-scoped configuration.                                                                                                            | A short app name, such as `mail`.                                                                              |
-| `APP_ID` / `APP_TEMPLATE`                   | Optional app identity and generated-template metadata.                                                                                                                  | App-owned strings.                                                                                             |
-| `NODE_ENV`                                  | Node runtime mode.                                                                                                                                                      | Normally `development`, `test`, or `production`.                                                               |
-| `CI`                                        | Marks CI-driven test and build behavior.                                                                                                                                | A CI-provided truthy value.                                                                                    |
-| `DEBUG`                                     | Enables resolver-specific debug logging.                                                                                                                                | A resolver-supported truthy or namespace value.                                                                |
+| Variable                                       | What it controls                                                                                                                                                        | Supported values or format                                                                                     |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`                                 | Primary SQL connection. Local development falls back to SQLite when it is unset. Production also accepts `<APP_NAME>_DATABASE_URL` or Netlify's `NETLIFY_DATABASE_URL`. | A provider-specific SQL URL, or unset for local SQLite.                                                        |
+| `DATABASE_AUTH_TOKEN`                          | Separate database token when the database provider requires one.                                                                                                        | An opaque provider token, or unset when the URL includes authentication.                                       |
+| `APP_URL`                                      | Optional canonical public origin used for auth, OAuth, A2A, webhooks, and generated links. Netlify and Vercel metadata are inferred when it is unset.                   | An absolute public `http(s)` origin.                                                                           |
+| `BETTER_AUTH_URL`                              | Optional Better Auth origin override. Known template or request context, `APP_URL`, and platform metadata such as Netlify or Vercel are used when it is unset.          | An absolute public `http(s)` origin.                                                                           |
+| `APP_BASE_PATH`                                | Mounts an app under a path such as `/mail`.                                                                                                                             | Unset for a standalone app, or a slash-prefixed path.                                                          |
+| `PORT`                                         | Local Node/Nitro server port.                                                                                                                                           | A decimal TCP port.                                                                                            |
+| `NITRO_PRESET`                                 | Build and deployment adapter.                                                                                                                                           | A preset supported by the target host, such as `node`, `netlify`, `vercel`, or `cloudflare_pages`.             |
+| `BETTER_AUTH_SECRET`                           | Stable Better Auth session signing secret for standalone production apps. Workspace deploys can derive it from `A2A_SECRET`.                                            | A fresh random value of at least 32 characters.                                                                |
+| `OAUTH_STATE_SECRET`                           | Dedicated signing key for OAuth state envelopes. Falls back to `BETTER_AUTH_SECRET` when unset.                                                                         | A fresh random value of at least 32 characters.                                                                |
+| `A2A_SECRET`                                   | Shared HMAC for trusted cross-app A2A calls and signed handoffs.                                                                                                        | One shared random value across trusted apps.                                                                   |
+| `SECRETS_ENCRYPTION_KEY`                       | Legacy app-local/shared encryption fallback.                                                                                                                            | A stable encryption key; prefer the workspace key for new shared vaults.                                       |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY`             | Stable encryption key for a workspace-shared secrets vault.                                                                                                             | The same stable key in every app that reads the vault.                                                         |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS`    | Previous workspace key during rotation.                                                                                                                                 | The old key only; remove it after migration.                                                                   |
+| `ANTHROPIC_API_KEY`                            | Optional deploy-level fallback for the embedded production agent.                                                                                                       | An API key; prefer scoped credentials for multi-tenant apps.                                                   |
+| `AGENT_ENGINE`                                 | Explicitly selects the agent engine instead of auto-detecting from provider keys.                                                                                       | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`.                      |
+| `AGENT_ENGINE_PREFER_BYO_KEY`                  | Prefers a provider key you set over the managed Builder gateway during auto-detection.                                                                                  | `true` or `1`; Builder still applies as the fallback when no provider key is set.                              |
+| `AUTH_MODE`                                    | Selects the local authentication behavior used by CLI and agent flows.                                                                                                  | Unset or `local`; this is not a browser login bypass.                                                          |
+| `AGENT_NATIVE_ALLOW_BUILDER_PREVIEW_LOCAL_DEV` | Explicitly enables the existing local-dev sign-in button on approved Builder preview hosts during development.                                                          | `1` or `true`; requires development mode and must stay off public or production deployments.                   |
+| `AUTH_DISABLED`                                | Disables auth for local or preview-only work. Unset already means false.                                                                                                | `true` or `1`; never use on a public production app.                                                           |
+| `AUTH_MAGIC_LINK`                              | Controls the password-first versus magic-link sign-in path.                                                                                                             | `0` keeps password-first sign-in; otherwise a configured email transport can enable magic links.               |
+| `AUTH_SKIP_EMAIL_VERIFICATION`                 | Skips signup email verification for local QA or previews.                                                                                                               | `1`; never use it to weaken production auth.                                                                   |
+| `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_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.                                                                                               |
+| `CORS_ALLOWED_ORIGINS`                         | Cross-origin request allowlist.                                                                                                                                         | A comma-separated list of exact origins.                                                                       |
+| `WEBHOOK_BASE_URL`                             | Optional public base URL for self-callback and webhook targets.                                                                                                         | An absolute public `http(s)` origin.                                                                           |
+| `APP_NAME`                                     | App identity used by workspace and app-scoped configuration.                                                                                                            | A short app name, such as `mail`.                                                                              |
+| `APP_ID` / `APP_TEMPLATE`                      | Optional app identity and generated-template metadata.                                                                                                                  | App-owned strings.                                                                                             |
+| `NODE_ENV`                                     | Node runtime mode.                                                                                                                                                      | Normally `development`, `test`, or `production`.                                                               |
+| `CI`                                           | Marks CI-driven test and build behavior.                                                                                                                                | A CI-provided truthy value.                                                                                    |
+| `DEBUG`                                        | Enables resolver-specific debug logging.                                                                                                                                | A resolver-supported truthy or namespace value.                                                                |
 
 Generate strong secrets with:
 

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:

package/docs/content/server-overview.mdx

@@ -85,7 +85,7 @@ The `server/` directory is the infrastructure layer of an agent-native app. It h
 
 ## Where the Server Fits {#role}
 
-In a traditional web app, the server is where most logic lives. Business rules, data access, and presentation all happen inside route handlers. Agent-native apps work differently. Logic lives in actions, which the agent and UI share as equal partners. The server's job is coordination: run database migrations, configure authentication, mount the agent loop, and handle the narrow set of HTTP concerns that actions can't express on their own.
+In a traditional web app, the server is where most logic lives. Business rules, data access, and presentation all happen inside route handlers. Agent-native apps work differently. Logic lives in actions, which the agent and UI share as equal partners. The server's job is coordination: apply app-owned database migrations, configure authentication, mount the agent loop, and handle the narrow set of HTTP concerns that actions can't express on their own.
 
 <Diagram id="doc-block-server-overview-2" title="Traditional server vs. Agent Native">
 
@@ -194,19 +194,19 @@ Browser requests, the agent loop, and external API clients all route through the
 
 These are the directories and files inside `server/` that every agent-native app ships. Each corresponds to a specific piece of the server layer: what it does, when to reach for it, and how it connects to the rest of the framework.
 
-| Page                                      | What it covers                                                                      |
-| ----------------------------------------- | ----------------------------------------------------------------------------------- |
-| **[Database](/docs/server-database)**     | Schema definition with `table()` helpers, `getDb`, and ownable table patterns       |
-| **[Middleware](/docs/server-middleware)** | Auth guards in `server/middleware/` and why they run there instead of in a plugin   |
-| **[Plugins](/docs/server-plugins)**       | The three startup plugins every app ships: db migrations, auth, and agent-chat      |
-| **[Routes](/docs/server-routes)**         | File-based routes, the SSR catch-all, and scoping custom routes to the request user |
+| Page                                      | What it covers                                                                       |
+| ----------------------------------------- | ------------------------------------------------------------------------------------ |
+| **[Database](/docs/server-database)**     | Schema definition with `table()` helpers, `getDb`, and ownable table patterns        |
+| **[Middleware](/docs/server-middleware)** | Auth guards in `server/middleware/` and why they run there instead of in a plugin    |
+| **[Plugins](/docs/server-plugins)**       | Startup plugins for auth and agent-chat, plus optional app-owned database migrations |
+| **[Routes](/docs/server-routes)**         | File-based routes, the SSR catch-all, and scoping custom routes to the request user  |
 
 ## Nitro {#nitro}
 
 [Nitro](https://nitro.build) is the server toolkit that powers the agent-native HTTP layer. Most of what you'll configure in `server/` is Nitro: file-based routes, startup plugins, and middleware.
 
 - **File-based routing**: the filename maps directly to an HTTP method and URL path, with no registration needed. `server/routes/api/health.get.ts` becomes `GET /api/health` automatically. Visit [Routes](/docs/server-routes) for more details.
-- **Plugins**: code that runs once at server startup, before any request is served. Database migrations, auth configuration, and the agent-chat mount all happen in `server/plugins/`. Visit [Plugins](/docs/server-plugins) for more details.
+- **Plugins**: code registered at server startup and loaded once. Framework helpers initialize auth and the agent-chat mount; optional app-owned database migrations may still be running when the first request arrives. Visit [Plugins](/docs/server-plugins) for more details.
 - **Middleware**: code that runs on every incoming request before it reaches a route. The auth guard lives in `server/middleware/`. Visit [Middleware](/docs/server-middleware) for more details.
 
 Nitro is also deployment-agnostic. The same app deploys to Node.js, Cloudflare Workers, Netlify, Vercel, and other runtimes with no code changes. Just set a preset. See [Deployment](/docs/deployment).
@@ -230,5 +230,5 @@ Use custom `/api/*` routes only when you need a route-shaped protocol or binary/
 - [**Actions**](/docs/actions): the default operation surface. Reach for a custom route only when it doesn't fit.
 - [**Database**](/docs/server-database): the `getDb()`/schema pattern custom routes and actions both import
 - [**Middleware**](/docs/server-middleware): auth guards and the `server/middleware/` directory
-- [**Plugins**](/docs/server-plugins): startup plugins for migrations, auth, and the agent
+- [**Plugins**](/docs/server-plugins): startup plugins for auth, the agent, and optional app-owned migrations
 - [**Routes**](/docs/server-routes): file-based routes, request context, and the SSR catch-all

package/docs/content/server-plugins.mdx

@@ -5,7 +5,7 @@ description: "Startup plugins in server/plugins/ — what they are, the two plug
 
 # Plugins
 
-Plugins are startup hooks. Each file in `server/plugins/` exports a function that Nitro calls once when the server initializes, before any route is served. They are the right place for one-time setup: configuring auth, mounting the agent loop, running database migrations, or registering any other initialization code that needs to complete before requests arrive.
+Plugins are startup hooks. Nitro loads each file in `server/plugins/` once when the server initializes. They are the right place for one-time setup: configuring auth, mounting the agent loop, running database migrations, or registering other initialization code. Framework helpers coordinate their async setup; custom plugin work may still be in flight when the first request arrives.
 
 Nitro discovers plugins automatically from the filesystem. No registration or imports are required. Files run in alphabetical order, so execution order is controlled by filename prefix.
 
@@ -21,7 +21,7 @@ Apps that need custom database tables add a third:
 
 ```text
 server/plugins/
-  db.ts          -> run migrations on startup
+  db.ts          -> register app-owned migrations for local startup
 ```
 
 ## Auth Plugin {#auth-plugin}
@@ -80,7 +80,7 @@ screen when context matters.`,
 
 ## Database Plugin {#database-plugin}
 
-If your app defines custom database tables, add `server/plugins/db.ts` to run schema migrations at startup. It uses `runMigrations` from `@agent-native/core/db`:
+If your app defines custom database tables, add `server/plugins/db.ts` to register schema migrations for local startup. It uses `runMigrations` from `@agent-native/core/db`:
 
 ```ts filename="server/plugins/db.ts"
 import { runMigrations } from "@agent-native/core/db";
@@ -110,6 +110,12 @@ Each entry needs a `version` number and a `sql` string. Give it a stable `name`
   TABLE ... DROP COLUMN`, `DELETE FROM`) in startup plugins.
 </Callout>
 
+<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>
+
 ## Writing Custom Plugins {#custom-plugins}
 
 The framework helpers (`createAuthPlugin`, `createAgentChatPlugin`, `runMigrations`) each return a Nitro plugin function. For anything outside those helpers, write a plugin using `defineNitroPlugin`:
@@ -142,6 +148,6 @@ If you add custom plugins, prefix their filenames to control invocation order, b
 
 - [**Database**](/docs/server-database): schema helpers and the `getDb` pattern used inside plugins
 - [**Middleware**](/docs/server-middleware): the auth guard that enforces what the auth plugin configures
-- [**Routes**](/docs/server-routes): custom file routes served after plugins complete
+- [**Routes**](/docs/server-routes): custom file routes and when to use them
 - [**Writing Agent Instructions**](/docs/writing-agent-instructions): how to craft the `systemPrompt` in the agent-chat plugin
 - [**Nitro plugin docs**](https://nitro.build/guide/plugins): the full plugin API and lifecycle hooks