@agent-native/core 0.164.11 → 0.164.12

package/docs/content/netlify.mdx

@@ -0,0 +1,47 @@
+---
+title: "Netlify"
+description: "Deploy an agent-native app to Netlify with the Netlify Nitro preset, and configure keep-warm for scale-to-zero databases."
+---
+
+# Netlify
+
+The Nitro `netlify` preset works well and, in practice, has given us much faster cold starts than Cloudflare Pages (~200ms TTFB vs ~9s) for templates that talk to external Postgres (Neon). Either set the preset in `vite.config.ts`:
+
+```ts filename="vite.config.ts"
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "netlify" } })],
+});
+```
+
+…or set `NITRO_PRESET=netlify` at build time.
+
+For a workspace, deploy every app from one Netlify site by running:
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+The workspace build writes static assets under `dist/_workspace_static/` and routes each app to its own Netlify function without forced asset redirects, so files like `/mail/assets/...` are served statically before the server function handles app routes.
+
+## Keep-warm and scale-to-zero databases {#netlify-keep-warm}
+
+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).
+
+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.
+
+The keep-warm schedule and background-function warm only apply after the main keep-warm flag is enabled:
+
+| Variable                                    | Effect                                                                                                                                                                       |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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, 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.
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database and a preset before your first production deploy
+- [**SSR Caching**](/docs/ssr-caching) — the default cache policy and Netlify's separate `netlify-cdn-cache-control` behavior
+- [**Node.js & Docker**](/docs/node-docker), [**Vercel**](/docs/vercel), [**Cloudflare**](/docs/cloudflare), and [**Other Platforms**](/docs/other-platforms) — the other Nitro presets

package/docs/content/node-docker.mdx

@@ -0,0 +1,138 @@
+---
+title: "Node.js & Docker"
+description: "Deploy an agent-native app with the default Node.js Nitro preset, standalone or containerized with Docker."
+---
+
+# Node.js & Docker
+
+Node.js is the default Nitro preset. This page covers running it directly and containerizing it with Docker. See [Deployment](/docs/deployment) for picking a database first, and [Workspace Deployment](/docs/workspace-deployment#workspace-docker-compose) for self-hosting a multi-app workspace with Docker Compose.
+
+## Fast path: self-host a Chat app locally {#self-host-quickstart}
+
+There are two good starting points, depending on your role:
+
+- **Building an app?** Start with [Getting Started](/docs/getting-started), then return here when you are ready to put the result somewhere permanent.
+- **Operating an app?** Use the local Docker path below first. It exercises the same Node.js, Postgres, authentication, and environment-variable shape you will use on a small server.
+
+The local stack intentionally uses a fake auth secret, trust authentication, and a local Postgres volume. It is for `localhost`, not an internet-facing deployment. Do not reuse the trust-authentication setting in production.
+
+### 1. Create the app
+
+```bash
+npx @agent-native/core@latest create my-app --standalone --template chat
+cd my-app
+pnpm install
+```
+
+The install step creates the lockfile that the production Dockerfile below copies into its build stage.
+
+### 2. Add the local Docker files
+
+Create `Dockerfile`, `.dockerignore`, and `docker-compose.yml` in the app root. `docker compose up --build` needs the Dockerfile, and `.dockerignore` keeps host-only files such as `node_modules` out of the Linux build context. Compose starts Postgres only on the private Compose network.
+
+You can also download the [Dockerfile](https://www.agent-native.com/examples/self-hosted-chat/Dockerfile), [.dockerignore](https://www.agent-native.com/examples/self-hosted-chat/.dockerignore), [Compose file](https://www.agent-native.com/examples/self-hosted-chat/docker-compose.yml), and [environment template](https://www.agent-native.com/examples/self-hosted-chat/env.example) as a starter fixture. The [Dockerfile](#docker) below matches the fixture.
+
+```yaml filename="docker-compose.yml" maxLines=40
+services:
+  app:
+    build: .
+    ports:
+      - "127.0.0.1:3000:3000"
+    environment:
+      DATABASE_URL: postgres://agent_native@postgres:5432/agent_native
+      BETTER_AUTH_SECRET: local-development-secret-change-me-1234567890
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  postgres:
+    image: postgres:18
+    environment:
+      POSTGRES_DB: agent_native
+      POSTGRES_USER: agent_native
+      POSTGRES_HOST_AUTH_METHOD: trust
+    volumes:
+      - postgres-data-v18:/var/lib/postgresql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U agent_native -d agent_native"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  postgres-data-v18:
+```
+
+PostgreSQL 18 uses `/var/lib/postgresql` as its volume mount path, unlike PostgreSQL 17 and earlier. The versioned volume name keeps this fresh fixture separate from older local stacks. If you are upgrading an existing PostgreSQL 17 or earlier stack, back up and migrate its data before changing the image or mount path. Do not point this fixture at the old volume without a migration.
+
+### 3. Run it
+
+```bash
+docker compose up --build
+```
+
+Open [http://localhost:3000](http://localhost:3000). The app infers its local auth origin from the browser request. Set `ANTHROPIC_API_KEY` in a local `.env` file if you want to use the embedded agent; leave it empty if you only want to verify that the app and database start. Stop the stack with `docker compose down`; add `-v` when you intentionally want to reset the local database.
+
+Before putting this on the public internet, replace the example secret, configure HTTPS and OAuth callback URLs, use a persistent production database, and complete the [production environment checklist](/docs/deployment-environment-variables#env-required-prod).
+
+## Node.js (Default) {#nodejs}
+
+The default preset. Build and run:
+
+```bash
+npx @agent-native/core@latest build
+node .output/server/index.mjs
+```
+
+Set `PORT` to configure the listen port (default: `3000`).
+
+Use the current Node.js LTS line for production deploys. As of May 2026, that
+is Node.js 24. Node.js 20 reached end-of-life on April 30, 2026 and no longer
+receives upstream security updates.
+
+## Docker {#docker}
+
+This Dockerfile works for the standalone app created above. Run `pnpm install` before building so `pnpm-lock.yaml` exists in the build context. Keep the dependency manifest and lockfile in sync when you update the app.
+
+```dockerfile filename="Dockerfile"
+FROM node:24-slim AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:24-slim
+WORKDIR /app
+COPY --from=build /app/.output .output
+# data/ is a runtime-created SQLite directory. Do not copy a dev DB into prod.
+# For production, set DATABASE_URL to a hosted Postgres or Turso instance.
+RUN mkdir -p /app/data
+ENV NODE_ENV=production
+ENV PORT=3000
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+Create `.dockerignore` alongside the Dockerfile:
+
+```text filename=".dockerignore"
+node_modules
+.output
+data
+.env
+.env.*
+!.env.example
+.git
+```
+
+Self-hosting a multi-app workspace with Docker Compose, built on this same
+standalone Dockerfile, is covered in
+[Workspace Deployment](/docs/workspace-deployment#workspace-docker-compose).
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database and a preset before your first production deploy
+- [**Workspace Deployment**](/docs/workspace-deployment) — self-host a multi-app workspace with Docker Compose
+- [**Vercel**](/docs/vercel), [**Netlify**](/docs/netlify), [**Cloudflare**](/docs/cloudflare), and [**Other Platforms**](/docs/other-platforms) — the other Nitro presets

package/docs/content/organizations-teams-permissions.mdx

@@ -338,7 +338,7 @@ There is no single useful list of every environment variable in an app: each
 template and provider adds its own integration settings. The table below is the
 framework-level set developers most often need. Feature-specific variables stay
 on the page for the feature that owns them, and
-[Deployment → Environment Variables](/docs/deployment#environment-variables) is
+[Deployment: Environment Variables](/docs/deployment-environment-variables) is
 the canonical production checklist (build/runtime vars, required secrets such as
 `ANTHROPIC_API_KEY` and `A2A_SECRET`, and production code execution) — the
 tables below don't repeat what's already covered there.
@@ -364,7 +364,7 @@ tables below don't repeat what's already covered there.
 
 `APP_URL`, `BETTER_AUTH_URL` / `VITE_BETTER_AUTH_URL`, `PORT`,
 `APP_BASE_PATH` / `VITE_APP_BASE_PATH`, and `NITRO_PRESET` are documented in
-[Deployment → Environment Variables](/docs/deployment#environment-variables).
+[Deployment: Environment Variables](/docs/deployment-environment-variables).
 
 ### Authentication, cookies, and org defaults
 
@@ -399,7 +399,7 @@ org/workspace-specific and aren't covered on either of those pages:
 | `AGENT_MAX_OUTPUT_TOKENS`      | Default output-token limit for the agent.                                             |
 
 `ANTHROPIC_API_KEY` and `AGENT_PROD_CODE_EXECUTION` are documented in
-[Deployment → Environment Variables](/docs/deployment#environment-variables).
+[Deployment: Environment Variables](/docs/deployment-environment-variables).
 
 ### Optional framework integrations
 
@@ -489,6 +489,6 @@ For a new team app, configure in this order:
 - [**Multi-Tenancy**](/docs/multi-tenancy) — org switching and tenant isolation
 - [**Security — Data Scoping**](/docs/security#data-scoping) — SQL scoping and access guards
 - [**Sharing & Privacy**](/docs/sharing) — resource visibility and share roles
-- [**Database**](/docs/database) — schema and connection details
-- [**Deployment**](/docs/deployment#environment-variables) — production and provider environment
+- [**Database**](/docs/server-database) — schema and connection details
+- [**Deployment: Environment Variables**](/docs/deployment-environment-variables) — production and provider environment
 - [**Org & Team Kit**](/docs/toolkit-org-team) — reusable UI components and hooks

package/docs/content/other-platforms.mdx

@@ -0,0 +1,27 @@
+---
+title: "Other Platforms"
+description: "Deploy an agent-native app to AWS Lambda or Deno Deploy with the matching Nitro preset."
+---
+
+# Other Platforms
+
+## AWS Lambda {#aws-lambda}
+
+```ts filename="vite.config.ts"
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "aws_lambda" } })],
+});
+```
+
+## Deno Deploy {#deno-deploy}
+
+```ts filename="vite.config.ts"
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "deno_deploy" } })],
+});
+```
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database and a preset before your first production deploy
+- [**Node.js & Docker**](/docs/node-docker), [**Vercel**](/docs/vercel), [**Netlify**](/docs/netlify), and [**Cloudflare**](/docs/cloudflare) — the other Nitro presets

package/docs/content/ssr-caching.mdx

@@ -0,0 +1,45 @@
+---
+title: "SSR Caching"
+description: "The default hard-cache policy for SSR HTML and React Router .data responses, and how to override it with AGENT_NATIVE_SSR_CACHE."
+---
+
+# SSR Caching
+
+Every SSR HTML response and every React Router `.data` response is one impersonal, public shell. `createH3SSRHandler` strips cookies before rendering, so the same bytes are correct for every visitor and all personalization happens on the client after load. That is what makes it safe to stamp a single hard-cache policy on those responses by default:
+
+```txt
+cache-control: public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600
+```
+
+The same value is mirrored onto `cdn-cache-control`. `netlify-cdn-cache-control` carries its own longer-lived default instead, `public, durable, s-maxage=31536000, stale-while-revalidate=604800, stale-if-error=3600`, since Netlify's CDN reads that header separately from the standard one. One shared CDN entry then serves the whole site instead of a per-request render. This is the single biggest lever on first-response latency. Leave it on unless one of the cases below applies to your deployment.
+
+## Overriding with `AGENT_NATIVE_SSR_CACHE` {#ssr-cache-env}
+
+Set `AGENT_NATIVE_SSR_CACHE` in the deploy environment to change the policy for the whole deployment:
+
+| Value                                               | Result                                                                                                                                                                                                                                                       |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| unset, `on`, `default`, `true`, `1`                 | The default policy above, unchanged. Recommended for best performance.                                                                                                                                                                                       |
+| `off`, `false`, `0`, `none`, `no-store`, `disabled` | `no-store` on `cache-control`, `cdn-cache-control`, and `netlify-cdn-cache-control`.                                                                                                                                                                         |
+| A duration: `30`, `30s`, `5m`, `2h`                 | `public, max-age=<n>, stale-while-revalidate=<n>, stale-if-error=3600` on `cache-control` and `cdn-cache-control`. `netlify-cdn-cache-control` uses the same duration with `public, durable, s-maxage=<n>, stale-while-revalidate=<n>, stale-if-error=3600`. |
+
+Bare numbers are seconds. `stale-while-revalidate` deliberately mirrors `max-age` for a custom duration: a short freshness window paired with the default seven-day stale window would hand back exactly the staleness you opted out of. An unrecognized value logs a warning and falls back to the default, so a typo can never silently disable the CDN.
+
+Turn it down or off when either of these is true:
+
+1. **Your host does not purge its CDN on deploy.** Netlify and Vercel do. Some self-managed setups do not. Without a purge, a shipped build can keep serving the previous shell for `max-age` plus `stale-while-revalidate`.
+2. **Your loaders return mutable public data.** After a successful mutation, a `useRevalidator()` or redirect-after-action re-fetch can read the browser's cached `.data` copy instead of fresh loader output.
+
+The setting applies to every public-shell surface: React Router SSR HTML and `.data`, the login HTML shell, the `/_agent-native/speculation-rules.json` route, the docs site, and the public-form SSR in the forms template. The generated Cloudflare Worker resolves it at build time, so set it in the deploy environment before the build runs.
+
+Three things to keep in mind:
+
+- **Turning caching off does not make SSR personalized.** Cookies are still stripped before render and SSR loaders still see the anonymous branch. Per-user data must still be resolved client-side. This variable controls cache _duration_ only.
+- **It is deployment-wide, not per-route, by design.** A per-route or per-request cache override is how one visitor's payload ends up in another visitor's shared CDN entry, so the framework does not offer one. `guard:ssr-cache-shell` enforces it.
+- **For mutation-fresh data, prefer actions over disabling the cache.** App data belongs in [actions](/docs/actions-overview), read from the client with `useActionQuery` / `useActionMutation` and kept live by `useDbSync()` polling. None of that goes through the SSR shell cache. Keep SSR loaders rendering the public shell, and reach for this variable only when you genuinely want loader data fresher.
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database and a preset before your first production deploy
+- [**Deployment: Environment Variables**](/docs/deployment-environment-variables) — the full production env var reference
+- [**Netlify**](/docs/netlify) — why `netlify-cdn-cache-control` carries its own longer-lived default

package/docs/content/template-assets-developers.mdx

@@ -366,7 +366,7 @@ The schema is strictly additive — hosted templates share their production
 database across every deploy context, so add columns via
 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...` in a new migration version in
 `server/plugins/db.ts`; never rename or drop a column, and never run
-`drizzle-kit push` against production. See [Database](/docs/database#migrations)
+`drizzle-kit push` against production. See [Database](/docs/server-database#migrations)
 for the full migration pattern.
 
 ## Customizing it
@@ -451,6 +451,6 @@ on the integrations page.
 
 - [**Using Assets from other apps and agents**](/docs/template-assets-integrations) — embedding, A2A, Creative Context, and the packaged skill bundle
 - [**Sharing & Privacy**](/docs/sharing#building) — `ownableColumns()` and the visibility model this template relies on
-- [**Database**](/docs/database) — migrations, dialects, and `getDb`/`schema`
+- [**Database**](/docs/server-database) — migrations, dialects, and `getDb`/`schema`
 - [**Actions**](/docs/actions-access-control#access-control) — the action system powering every entry above
 - [**Assets**](/docs/template-assets) — back to the overview

package/docs/content/template-chat-developers.mdx

@@ -72,7 +72,7 @@ Three routes are mounted whether or not your app ever links to them:
   ]}
 />
 
-**Database** (`/database`) is the same `DbAdminPage` every template gets — a direct table browser/editor over the app's SQL database. See [Database](/docs/database) for the connection model behind it.
+**Database** (`/database`) is the same `DbAdminPage` every template gets — a direct table browser/editor over the app's SQL database. See [Database](/docs/server-database) for the connection model behind it.
 
 **Observability** (`/observability`) is the same zero-config `ObservabilityDashboard` every template gets: traces, cost, evals, and feedback for every agent run, computed from data already in your own database. See [Agent Observability](/docs/observability).
 
@@ -82,7 +82,7 @@ Three routes are mounted whether or not your app ever links to them:
 
 - [**Chat Template**](/docs/template-chat) — what ships by default and when to pick it
 - [**Your first feature in Chat**](/docs/template-chat-first-edits) — the starter chat route, annotated, plus a full feature walkthrough
-- [**Database**](/docs/database) — connecting a real database and the portable-SQL model
+- [**Database**](/docs/server-database) — connecting a real database and the portable-SQL model
 - [**Agent Observability**](/docs/observability) — what the dashboard tracks and how
 - [**Extensions**](/docs/extensions) — building mini-apps inside a template
 - [**Authentication**](/docs/authentication) — sessions, organizations, and protected routes

package/docs/content/template-content-developers.mdx

@@ -394,7 +394,7 @@ The places to look when changing behavior:
 - **`app/components/editor/`** — the Tiptap editor. Add a new node type under `extensions/` and register it in `DocumentEditor.tsx`. The bubble toolbar, slash menu, and hover previews are all component files you can edit.
 - **`.agents/skills/`** — guidance the agent reads before acting: `content`, `document-editing`, `notion-integration`, `creative-context`, plus the framework skills. Add a new skill folder when you add a capability big enough to need its own guidance.
 - **`AGENTS.md`** — the top-level agent guide with the action cheatsheet. Update it whenever you add a feature so the agent discovers it without exploring.
-- **`server/db/schema.ts`** — the data model. Content has no `db:push` script; it relies on strictly additive migrations that run on startup. Migrations must never drop, rename, or destructively alter existing tables or columns — see [Database](/docs/database#migrations).
+- **`server/db/schema.ts`** — the data model. Content has no `db:push` script; it relies on strictly additive migrations that run on startup. Migrations must never drop, rename, or destructively alter existing tables or columns — see [Database](/docs/server-database#migrations).
 - **A new external-source adapter** — implement the `ContentDatabaseSourceAdapter` interface in `actions/_content-database-source-adapters.ts` (see the existing `builder-cms`, `local-table`, and `notion-database` adapters) and wire it into `attach-content-database-source`. Every adapter reads into the same change-set/review pipeline described on the [Databases page](/docs/template-content-databases#connecting-an-external-source) — a new adapter should not bypass it with a direct write.
 - **`shared/content-source.ts`** — the local-folder sync contract (filenames, frontmatter, parsing, serialization). Extend this if you change what an exported file looks like.
 - **`shared/nfm.ts`** — the Notion-Flavored Markdown converter. Extend this if you add block types that need to round-trip through Notion.
@@ -407,6 +407,6 @@ The agent can make most of these changes itself — ask it to "add a tags column
 - [Writing & organizing documents](/docs/template-content-editing) — the non-developer view of the editor and sharing model
 - [Databases, properties & forms](/docs/template-content-databases) — the full inline-database and external-source data model
 - [Local files, Notion & Builder CMS sync](/docs/template-content-sync) — the non-developer view of every sync surface
-- [Database](/docs/database) — the framework's Drizzle conventions and migration rules
+- [Database](/docs/server-database) — the framework's Drizzle conventions and migration rules
 - [Actions](/docs/actions-overview) — the action system every operation above is built on
 - [Sharing](/docs/sharing) — the share-grant model `document_shares` builds on

package/docs/content/{local-file-mode.mdx → template-content-local-files.mdx}

@@ -142,5 +142,6 @@ less likely to leave half the product living in a parallel universe.
 
 ## What's next
 
-- [**Database**](/docs/database) — the SQL model every Content page and space is backed by, mode switch or not
+- [**Database**](/docs/server-database) — the SQL model every Content page and space is backed by, mode switch or not
 - [**Content**](/docs/template-content) — the app this connects to: spaces, the Files database, and the editor built on top of it
+- [**Content: Local Files, Notion & Builder CMS Sync**](/docs/template-content-sync) — connecting a folder day-to-day, local MDX components, and conflict handling

package/docs/content/template-content-sync.mdx

@@ -83,7 +83,7 @@ To open Content for an existing repo directly against a folder:
 npx @agent-native/core@latest content .
 ```
 
-This starts normal database-backed Content and registers an opaque local-folder connection in `agent-native.json` — it does not switch the app into a separate local-only mode. See [Local folder sources](/docs/local-file-mode) for the manifest format, truth policies, and Desktop bridge details.
+This starts normal database-backed Content and registers an opaque local-folder connection in `agent-native.json` — it does not switch the app into a separate local-only mode. See [Local folder sources](/docs/template-content-local-files) for the manifest format, truth policies, and Desktop bridge details.
 
 ### Local MDX components
 
@@ -145,5 +145,5 @@ Every document belongs to a **space** — your personal space, or one shared wit
 - [Content overview](/docs/template-content) — what the app is and how to get started
 - [Writing & organizing documents](/docs/template-content-editing) — the editor and sharing model these synced documents use
 - [Databases, properties & forms](/docs/template-content-databases) — syncing rows inside a database, rather than whole documents
-- [Local folder sources](/docs/local-file-mode) — full configuration, truth policies, and conflict handling reference
+- [Local folder sources](/docs/template-content-local-files) — full configuration, truth policies, and conflict handling reference
 - [Developer Guide](/docs/template-content-developers) — the full sync action inventory and data model

package/docs/content/toolkit-agent-ux.mdx

@@ -85,7 +85,7 @@ chat surface, not just the input — see [Drop-in Agent](/docs/drop-in-agent).
 
 - [**Using Your Agent**](/docs/using-your-agent) — the end-user model/composer
   experience this kit implements.
-- [**Human Approval**](/docs/human-approval) — the approval-gate contract
+- [**Human Approval**](/docs/actions-access-control#needs-approval) — the approval-gate contract
   behind approval prompts.
 - [**Progress**](/docs/progress) — the run data `<RunsTray>` polls and renders.
 - [**Native Chat UI**](/docs/native-chat-ui) — build a custom chat surface on

package/docs/content/toolkit-resources.mdx

@@ -108,8 +108,8 @@ the same shape and invalidate the tree/resource queries on success.
 
 ## What's next
 
-- [**Local File Mode**](/docs/local-file-mode) — repo-backed resources where
-  files are the source of truth.
+- [**Local folder sources**](/docs/template-content-local-files) — repo-backed
+  resources where files are the source of truth.
 - [**File Uploads**](/docs/file-uploads) — the shared attachment path resource
   uploads reuse.
 - [**Component API**](/docs/components#resources) — the full prop reference for

package/docs/content/updating-ui-in-production.mdx

@@ -0,0 +1,35 @@
+---
+title: "Updating UI in Production"
+description: "How a deployed app's UI gets updated after launch, and Builder.io's separate managed workflow for visual editing in production."
+---
+
+# Updating UI in Production
+
+The ordinary deployed app agent works through app tools (actions, database,
+MCP, and configured integrations) rather than receiving ambient access to the
+app's source code. Source changes belong in the repository's development
+workflow. An embedded, local, or Builder frame can edit the repository when
+that frame is intentionally granted workspace and write tooling.
+
+In a standard production deployment with [production code execution](/docs/actions-agent-tools#production-code-execution) left off, the agent has access to app tools (actions, database, MCP) but not the filesystem. This means the agent can read and write data, run actions, and interact with external services. It can't edit your React components or add new routes on a deployed instance.
+
+## Builder.io: Visual Editing in Production {#builderio}
+
+[Builder.io](https://www.builder.io?utm_source=agent-native&utm_medium=docs&utm_campaign=framework&utm_content=deployment) is a separate managed code-capable workflow where an agent can modify your app's UI in production. Connect your repo to Builder.io (free tier available) and prompt for UI changes directly. No redeploy needed.
+
+**Connect Builder** in Settings uses Builder OAuth (`builder:ai:invoke`) with a same-origin HTTPS callback under `/_agent-native/builder/callback`, so hosted origins such as Railway work without a domain allowlist. Legacy `BUILDER_*` private keys remain a runtime fallback for existing connections.
+
+**How it works:**
+
+1. Connect your agent-native repo to Builder.io (free tier available)
+2. Builder.io provides a cloud frame with the agent, visual editing, and real-time collaboration
+3. Prompt the agent to make UI changes. It edits your components, routes, and styles live
+4. Changes are committed back to your repo
+
+See [Frames](/docs/frames) for more on the embedded agent panel vs. cloud frame options.
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database and a preset before your first production deploy
+- [**Frames**](/docs/frames) — the embedded agent panel vs. Builder.io's cloud frame for production UI edits
+- [**Production Agent Access**](/docs/actions-agent-tools) — what tools the deployed agent has by default

package/docs/content/vercel.mdx

@@ -0,0 +1,38 @@
+---
+title: "Vercel"
+description: "Deploy an agent-native app to Vercel with the Vercel Nitro preset, standalone or as a workspace."
+---
+
+# Vercel
+
+```ts filename="vite.config.ts"
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "vercel" } })],
+});
+```
+
+Deploy via the Vercel CLI or git push:
+
+```bash
+vercel deploy
+```
+
+For a workspace, build every app into one Vercel Build Output API bundle:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+For Vercel Git deployments, set the build command to:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel --build-only
+```
+
+The workspace build copies each app's Nitro `vercel` output into the root `.vercel/output`, gives each function its own mount-path environment, and writes the route config that serves apps at `/<app-id>`.
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database and a preset before your first production deploy
+- [**Workspace Deployment**](/docs/workspace-deployment) — the `deploy --preset vercel` workspace build in full
+- [**Node.js & Docker**](/docs/node-docker), [**Netlify**](/docs/netlify), [**Cloudflare**](/docs/cloudflare), and [**Other Platforms**](/docs/other-platforms) — the other Nitro presets

package/docs/content/what-is-agent-native.mdx

@@ -51,7 +51,7 @@ Three shared foundations make this possible:
 - **Shared operations.** People trigger them through the UI, while agents call
   them directly. Agent-Native defines each operation once as an
   [action](/docs/actions-overview).
-- **[Shared data](/docs/database)** holds the work and information the
+- **[Shared data](/docs/server-database)** holds the work and information the
   application needs to preserve. Depending on the application, that might be
   customer records, project plans, conversations, or reports. The UI and agent
   both read and update this shared data.