@agent-native/core 0.164.4 → 0.164.12

package/docs/content/workspace-deployment.mdx

@@ -0,0 +1,350 @@
+---
+title: "Workspace Deployment"
+description: "Ship every app in an agent-native workspace to one origin with a single command, or self-host a workspace with Docker Compose."
+---
+
+# Workspace Deployment
+
+If your project is a [workspace](/docs/multi-app-workspace) with more than one app, you can deploy every app to a single origin instead of managing separate deployments per app. This page covers the managed one-command path and a self-hosted Docker Compose alternative. See [Deployment](/docs/deployment) for picking a database, a preset, and a platform first.
+
+## One Origin, Many Apps {#workspace-deploy}
+
+Ship every app in a workspace to a single origin with one command:
+
+```bash
+npx @agent-native/core@latest deploy
+# https://your-agents.com/mail/*       → apps/mail
+# https://your-agents.com/calendar/*   → apps/calendar
+# https://your-agents.com/forms/*      → apps/forms
+```
+
+<Diagram id="doc-block-1aw1umr" title="One origin, many apps" summary={"Each workspace app is built with its own base path and mounted under a path prefix on a single origin. Login and cross-app A2A are same-origin and free as a result."}>
+
+```html
+<div class="diagram-ws">
+  <div class="diagram-panel" data-rough>
+    <strong>https://your-agents.com</strong>
+    <div class="diagram-row">
+      <span class="diagram-pill accent">/mail/*</span
+      ><small class="diagram-muted">apps/mail</small>
+    </div>
+    <div class="diagram-row">
+      <span class="diagram-pill accent">/calendar/*</span
+      ><small class="diagram-muted">apps/calendar</small>
+    </div>
+    <div class="diagram-row">
+      <span class="diagram-pill accent">/forms/*</span
+      ><small class="diagram-muted">apps/forms</small>
+    </div>
+  </div>
+  <div class="diagram-col wins">
+    <span class="diagram-pill ok">shared login session</span
+    ><span class="diagram-pill ok">zero-config cross-app A2A</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-ws {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+.diagram-ws .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+}
+.diagram-ws .diagram-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.diagram-ws .wins {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  align-items: flex-start;
+}
+```
+
+</Diagram>
+
+**Same-origin** means every app looks like part of the same website to the browser. That gives you two big wins for free:
+
+- **Shared login session**. Log into any app, and every app is logged in.
+- **Zero-config cross-app A2A**. Tagging `@calendar` from mail is a same-origin fetch. There's no CORS and no JWT signing between siblings.
+
+<Callout tone="info">
+
+Under the hood, each app is built with its own **base path**, a URL prefix like `/mail` set via `APP_BASE_PATH`/`VITE_APP_BASE_PATH`, then packaged for the target Nitro preset. Cloudflare Pages routes through a generated **dispatcher worker**, a small script at `dist/_worker.js` that reads the incoming path and forwards the request to the matching app. Netlify uses one function per app plus generated redirects. Vercel writes a workspace-level `.vercel/output` using the Build Output API.
+
+</Callout>
+
+Publish the build for your platform:
+
+<TabsBlock
+  id="doc-block-wsdeploytabs1"
+  tabs={[
+    {
+      id: "cloudflare",
+      label: "Cloudflare (default)",
+      blocks: [
+        {
+          type: "code",
+          id: "wf-cf",
+          data: { code: "wrangler pages deploy dist", language: "bash" },
+        },
+      ],
+    },
+    {
+      id: "netlify",
+      label: "Netlify",
+      blocks: [
+        {
+          type: "code",
+          id: "wf-nl",
+          data: {
+            code: "npx @agent-native/core@latest deploy --preset netlify",
+            language: "bash",
+          },
+        },
+      ],
+    },
+    {
+      id: "vercel",
+      label: "Vercel",
+      blocks: [
+        {
+          type: "code",
+          id: "wf-vc",
+          data: {
+            code: "npx @agent-native/core@latest deploy --preset vercel",
+            language: "bash",
+          },
+        },
+      ],
+    },
+  ]}
+/>
+
+<Callout tone="warning">
+
+Hosted workspace builds require `A2A_SECRET` in the deploy provider environment. Without it, Slack, inbound webhooks, and cross-app A2A resume don't work, since those all go through signed background processors. Local `--build-only` artifact checks still run without it.
+
+</Callout>
+
+<Callout tone="info">
+
+Wiring up a provider build command instead of deploying by hand? Add `--build-only` to the same command, for example `npx @agent-native/core@latest deploy --preset vercel --build-only`. It writes the output directly, so no `vercel.json` is required for workspace routing.
+
+Prefer a separate domain per app instead of one shared origin? Every app in the workspace is still independently deployable. Run `cd apps/<name> && npx @agent-native/core@latest build` like a standalone scaffold.
+
+</Callout>
+
+## Self-hosted Workspace with Docker Compose {#workspace-docker-compose}
+
+A workspace is not one Nitro server process today. Each app still builds to its own `.output/` directory and runs its own Node/Nitro server, so self-hosting a workspace means running several servers behind a single entry point.
+
+<Diagram id="doc-block-3selfhost1" title="Self-hosted workspace shape" summary={"One reverse proxy in front of one container per app, all pointing at the same Postgres database."}>
+
+```html
+<div class="diagram-selfhost">
+  <div class="diagram-box" data-rough>Internet</div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center" data-rough>
+    <span class="diagram-pill accent">proxy</span
+    ><small class="diagram-muted">routes by path prefix</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-row">
+      <span class="diagram-pill">/mail</span
+      ><small class="diagram-muted">mail container</small>
+    </div>
+    <div class="diagram-row">
+      <span class="diagram-pill">/calendar</span
+      ><small class="diagram-muted">calendar container</small>
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
+  <div class="diagram-box" data-rough>
+    Shared Postgres<br /><small class="diagram-muted">one DATABASE_URL</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-selfhost {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-selfhost .diagram-panel.center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  padding: 14px 16px;
+}
+.diagram-selfhost .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.diagram-selfhost .diagram-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.diagram-selfhost .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+A **reverse proxy** is that single entry point in the picture above: it receives every request and forwards it to the right container based on the URL path, the same job Cloudflare's dispatcher worker does for a managed deploy. On a VPS, that means one container per workspace app, all pointing at the same Postgres database and shared production secrets, with the proxy in front.
+
+<Steps>
+
+### Build each app with a matching base path
+
+The base path is a build-time input for the client bundle and a runtime input for the server. Build each app with the same path the proxy will route to it:
+
+```bash maxLines=8
+APP_BASE_PATH=/mail VITE_APP_BASE_PATH=/mail npx @agent-native/core@latest build
+node .output/server/index.mjs
+```
+
+### Write a reusable Dockerfile
+
+Take the app name and path prefix as build arguments, so one Dockerfile serves every app in the workspace:
+
+```dockerfile filename="Dockerfile.workspace-app" maxLines=12
+FROM node:24-slim AS build
+WORKDIR /workspace
+RUN corepack enable
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages ./packages
+COPY apps ./apps
+ARG APP_NAME
+ARG APP_BASE_PATH
+ENV APP_BASE_PATH=$APP_BASE_PATH
+ENV VITE_APP_BASE_PATH=$APP_BASE_PATH
+RUN pnpm install --frozen-lockfile
+RUN pnpm --dir apps/$APP_NAME build
+
+FROM node:24-slim
+WORKDIR /app
+ARG APP_NAME
+ARG APP_BASE_PATH
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV APP_BASE_PATH=$APP_BASE_PATH
+COPY --from=build /workspace/apps/$APP_NAME/.output .output
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+### Compose Postgres, the apps, and the proxy
+
+This example uses Caddy because it can terminate HTTP locally or sit behind Cloudflare's SSL proxy, but the important part is the path-prefix routing:
+
+```yaml filename="docker-compose.yml" maxLines=30
+services:
+  postgres:
+    image: postgres:17
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: agent_native
+      POSTGRES_USER: agent_native
+      POSTGRES_PASSWORD: change-me
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  mail:
+    build:
+      context: .
+      dockerfile: Dockerfile.workspace-app
+      args:
+        APP_NAME: mail
+        APP_BASE_PATH: /mail
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: postgres://agent_native:change-me@postgres:5432/agent_native
+      BETTER_AUTH_URL: https://agents.example.com/mail
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      A2A_SECRET: ${A2A_SECRET}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+    depends_on:
+      - postgres
+
+  calendar:
+    build:
+      context: .
+      dockerfile: Dockerfile.workspace-app
+      args:
+        APP_NAME: calendar
+        APP_BASE_PATH: /calendar
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: postgres://agent_native:change-me@postgres:5432/agent_native
+      BETTER_AUTH_URL: https://agents.example.com/calendar
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      A2A_SECRET: ${A2A_SECRET}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+    depends_on:
+      - postgres
+
+  proxy:
+    image: caddy:2
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+    depends_on:
+      - mail
+      - calendar
+
+volumes:
+  postgres-data:
+```
+
+### Configure the proxy
+
+```caddyfile filename="Caddyfile"
+agents.example.com {
+  reverse_proxy /mail* mail:3000
+  reverse_proxy /calendar* calendar:3000
+}
+```
+
+</Steps>
+
+<Callout tone="info">
+
+- Keep `DATABASE_URL`, `BETTER_AUTH_SECRET`, `A2A_SECRET`, and other production
+  secrets identical across app containers when you want shared auth, shared
+  credentials, and cross-app A2A.
+- Set `BETTER_AUTH_URL` to the public URL for that app path. OAuth callback URLs
+  should use the same public URL.
+- Do not rely on the container filesystem for production data. Use Postgres (or
+  another persistent SQL backend) for `DATABASE_URL`.
+- If Cloudflare terminates TLS in front of the VPS, configure Cloudflare to send
+  normal `X-Forwarded-Proto` / `X-Forwarded-Host` headers and route the public
+  host to the proxy container.
+
+</Callout>
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database, a Nitro preset, and a platform before deploying a workspace
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — the workspace model this page's `deploy` command builds on
+- [**Security**](/docs/security) — the production checklist and opt-in flags for a hosted deployment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.164.4",
+  "version": "0.164.12",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -428,7 +428,7 @@
     "yjs": "^13.6.32",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.5",
-    "@agent-native/toolkit": "^0.16.6"
+    "@agent-native/toolkit": "^0.16.7"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/docs/content/agents.mdx

@@ -1,9 +0,0 @@
----
-title: "Agents"
-description: "Agent configuration, instructions, and the surfaces agents operate through."
-draft: true
----
-
-# Agents
-
-This section is coming soon. In the meantime, see [Writing Agent Instructions](/docs/writing-agent-instructions), [Skills](/docs/skills-guide), and [Agent Surfaces](/docs/agent-surfaces) for existing coverage.

package/docs/content/database.mdx

@@ -1,317 +0,0 @@
----
-title: "Database"
-description: "Connect a portable SQL database to your agent-native app and write provider-agnostic Drizzle code."
----
-
-# Database
-
-Agent-native apps use [Drizzle ORM](https://orm.drizzle.team) and support portable SQL backends. For anything beyond local development, connect a persistent SQL database — Postgres, libSQL/Turso, or another Drizzle-compatible backend — by setting `DATABASE_URL`. When that variable is unset, the app falls back to a zero-config local SQLite file so you can start developing immediately. For local development that should behave like Postgres without running a separate database server, opt into PGlite with `DATABASE_URL=pglite:./data/pglite`.
-
-<Diagram id="doc-block-vykcz4" title="One schema, many backends" summary={"App code uses the framework's dialect-agnostic helpers. The dialect is auto-detected from DATABASE_URL at runtime; unset means a local SQLite file."}>
-
-```html
-<div class="diagram-db">
-  <div class="diagram-panel center" data-rough>
-    <span class="diagram-pill accent">@agent-native/core/db/schema</span
-    ><small class="diagram-muted">table · text · integer · real · now</small
-    ><small class="diagram-muted">+ Drizzle query DSL</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="diagram-box" data-rough>
-    DATABASE_URL<br /><small class="diagram-muted">dialect auto-detected</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="diagram-grid">
-    <span class="diagram-pill"
-      >Postgres<br /><small class="diagram-muted">Neon · Supabase</small></span
-    ><span class="diagram-pill">libSQL / Turso</span
-    ><span class="diagram-pill">Cloudflare D1</span
-    ><span class="diagram-pill warn"
-      >SQLite file<br /><small class="diagram-muted"
-        >unset = local dev only</small
-      ></span
-    ><span class="diagram-pill warn"
-      >PGlite<br /><small class="diagram-muted"
-        >local Postgres opt-in</small
-      ></span
-    >
-  </div>
-</div>
-```
-
-```css
-.diagram-db {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-db .center {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: 4px;
-  padding: 14px 16px;
-}
-.diagram-db .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-.diagram-db .diagram-grid {
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  gap: 8px;
-}
-```
-
-</Diagram>
-
-## Local default: SQLite file {#default-sqlite}
-
-When `DATABASE_URL` is not set, the app creates a SQLite database at `data/app.db`. This is the zero-config default for local development — no setup required. It is meant for development only; for production, set `DATABASE_URL` to a persistent SQL database.
-
-Do not rely on that local file for deployed apps. Containers, serverless functions, and preview environments may reset their filesystem, which means a local SQLite file can disappear between restarts. Set `DATABASE_URL` to a persistent hosted database before production use.
-
-## Local Postgres Opt-In: PGlite {#local-pglite}
-
-Install the optional PGlite package, then set `DATABASE_URL=pglite:./data/pglite` to run the app against [PGlite](https://pglite.dev/), a local WASM Postgres database:
-
-```bash
-pnpm add @electric-sql/pglite@^0.5.3
-```
-
-This keeps local development on the Postgres dialect, including Postgres schema helpers and migrations, without requiring Docker or a hosted database.
-
-PGlite is still local development storage. Treat it like the SQLite fallback for durability and sharing: use it to test Postgres-shaped behavior on your machine, then set `DATABASE_URL` to a persistent hosted database for production, previews, or any shared environment.
-
-## Connecting a Production Database {#production}
-
-Set `DATABASE_URL` in your `.env` file or deploy-provider environment to connect a hosted database. Turso is not required; use whichever Drizzle-compatible SQL backend fits your deployment:
-
-```bash
-# Neon Postgres
-DATABASE_URL=postgres://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/mydb?sslmode=require
-
-# Supabase Postgres
-DATABASE_URL=postgres://postgres.xxxx:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres
-
-# Plain Postgres
-DATABASE_URL=postgres://user:pass@localhost:5432/mydb
-
-# Local PGlite (Postgres dialect, local development only)
-DATABASE_URL=pglite:./data/pglite
-
-# Turso (libSQL)
-DATABASE_URL=libsql://my-db-org.turso.io
-DATABASE_AUTH_TOKEN=your-token
-```
-
-The framework auto-detects the dialect from the URL and configures Drizzle accordingly. The built-in adapters cover Postgres URLs, local PGlite URLs, libSQL/Turso URLs, SQLite file URLs, and Cloudflare D1 bindings. Common production choices include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, and Builder.io-managed environments when available.
-
-## Builder.io Managed Database {#builder-managed}
-
-_Planned (not yet available):_ when connected to Builder.io, your app will be able to use a managed database provisioned automatically, with no connection strings required.
-
-## Where the DB Client Lives {#db-client}
-
-Each template creates a lazy, singleton Drizzle client by calling `createGetDb(schema)` from `@agent-native/core/db`. The canonical location is `server/db/index.ts`:
-
-```ts filename="server/db/index.ts"
-import { createGetDb } from "@agent-native/core/db";
-import * as schema from "./schema.js";
-
-export const getDb = createGetDb(schema);
-```
-
-Import `getDb` from this template-local path — `../../server/db/index.js` in routes, `../server/db/index.js` in actions — rather than from `@agent-native/core` directly. The core export returns a generic untyped instance; the template's `getDb()` carries your schema types. See [Server](/docs/server-routes#request-context) for how actions and custom routes each import it.
-
-## Dialect-Agnostic Schema And Queries {#schema}
-
-App database code should use Drizzle's schema and query DSL so it can run across providers. Never write SQLite-only syntax (`INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`) or Postgres-only syntax in product code.
-
-Use the framework's schema helpers from `@agent-native/core/db/schema`:
-
-```ts
-import { table, text, integer, real, now } from "@agent-native/core/db/schema";
-
-export const tasks = table("tasks", {
-  id: text("id").primaryKey(),
-  title: text("title").notNull(),
-  priority: integer("priority").notNull().default(0),
-  weight: real("weight"),
-  done: integer("done", { mode: "boolean" }).notNull().default(false),
-  ownerEmail: text("owner_email").notNull(),
-  createdAt: text("created_at").notNull().default(now()),
-});
-```
-
-| Helper    | Purpose                                                         |
-| --------- | --------------------------------------------------------------- |
-| `table`   | Define a table — delegates to `pgTable` or `sqliteTable`        |
-| `text`    | Text column, supports `{ enum: [...] }`                         |
-| `integer` | Integer column, `{ mode: "boolean" }` maps to Postgres boolean  |
-| `real`    | Float column — `real` on SQLite, `double precision` on Postgres |
-| `now`     | Dialect-agnostic current timestamp for `.default(now())`        |
-
-The `tasks` table above defines the same columns on every backend:
-
-<DataModel
-  id="doc-block-14e70da"
-  title="The tasks table"
-  summary={
-    "Defined once with the framework helpers; the dialect is chosen at runtime from DATABASE_URL."
-  }
-  entities={[
-    {
-      id: "tasks",
-      name: "tasks",
-      note: "Domain table. Add owner_email (or ...ownableColumns()) so SQL-level scoping can filter rows to the authenticated user.",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-          nullable: false,
-        },
-        {
-          name: "title",
-          type: "text",
-          nullable: false,
-        },
-        {
-          name: "priority",
-          type: "integer",
-          nullable: false,
-          note: "default 0",
-        },
-        {
-          name: "weight",
-          type: "real",
-          nullable: true,
-        },
-        {
-          name: "done",
-          type: "integer (boolean mode)",
-          nullable: false,
-          note: "default false; maps to a Postgres boolean",
-        },
-        {
-          name: "owner_email",
-          type: "text",
-          nullable: false,
-          note: "enables data scoping",
-        },
-        {
-          name: "created_at",
-          type: "text",
-          nullable: false,
-          note: "default now()",
-        },
-      ],
-    },
-  ]}
-/>
-
-Never import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` directly. Always use `@agent-native/core/db/schema`.
-
-Tables that store user-facing data must include an `owner_email` column so the framework's SQL-level scoping can filter rows to the authenticated user — see [Security](/docs/security#data-scoping). Tables that also support sharing with other users or orgs should spread `...ownableColumns()` instead, which adds `owner_email`, `org_id`, and `visibility` in one call — see [Sharing](/docs/sharing#building).
-
-For reads and writes, use Drizzle's query builder and portable operators from `drizzle-orm`:
-
-```ts
-import { and, desc, eq } from "drizzle-orm";
-import { getDb } from "../server/db/index.js";
-import { tasks } from "../server/db/schema.js";
-
-const db = getDb();
-
-const openTasks = await db
-  .select()
-  .from(tasks)
-  .where(and(eq(tasks.ownerEmail, userEmail), eq(tasks.done, false)))
-  .orderBy(desc(tasks.createdAt));
-
-await db.update(tasks).set({ done: true }).where(eq(tasks.id, taskId));
-```
-
-## Raw SQL Escape Hatches {#raw-sql}
-
-Raw SQL is not the default app-code API. Use it only for additive migrations, health checks, carefully reviewed advanced queries that Drizzle cannot express, or one-off maintenance. Keep it parameterized and dialect-agnostic. For timestamps in Drizzle schemas, prefer `.default(now())`; for migration SQL, use `runMigrations()` so framework-supported compatibility rewrites and dialect-gated statements stay centralized.
-
-For cases where you truly need raw SQL outside of Drizzle queries:
-
-- `getDbExec()` — auto-converts `?` params to `$1` for Postgres
-- `isPostgres()` — runtime dialect check
-- `intType()` — returns the correct integer type for the current dialect
-
-## Migrations and Schema Updates {#migrations}
-
-In hosted environments, multiple deployment previews, branches, and the production server share the same underlying database. Therefore, database schema updates must follow strict constraints to avoid data loss and service disruption.
-
-### The "Zero Destructive Changes" Rule
-
-All database schema updates must be **strictly additive**.
-
-- **Do not drop tables or columns.**
-- **Do not rename tables or columns.** Renaming a column or table looks like a drop + create sequence to Drizzle, which will permanently delete your existing production data.
-- If a column needs to be renamed or replaced, add the new column alongside the old one, update your application code to read from/write to both, migrate the data, and only retire the old column in a later release once no active deployments are referencing it.
-
-<Callout tone="risk">
-  **Never run `drizzle-kit push` against a production database.** Template
-  database schemas only define app-specific domain tables; they do not define
-  central framework tables (`user`, `session`, `application_state`, etc.). If
-  you run `drizzle-kit push` against production, Drizzle will detect these
-  framework tables as "not in schema" and attempt to drop them, causing
-  immediate system-wide failure and data loss.
-</Callout>
-
-### Safe Migration Path
-
-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"
-  title="An additive migration plugin"
-  filename="server/plugins/db.ts"
-  language="ts"
-  code={
-    'import { runMigrations } from "@agent-native/core/db";\n\nexport default runMigrations(\n  [\n    {\n      version: 1,\n      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,\n    },\n    {\n      // Dialect-gated: runs only on the matching backend. Omit the other key\n      // to make it a no-op on that dialect.\n      version: 2,\n      sql: {\n        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,\n        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only\n      },\n    },\n  ],\n  { table: "my_app_migrations" },\n);'
-  }
-  annotations={[
-    {
-      lines: "6-7",
-      label: "Additive only",
-      note: "`ADD COLUMN IF NOT EXISTS` is safe to re-run and never drops data. Renames look like drop+create to Drizzle, so add-then-migrate instead.",
-    },
-    {
-      lines: "13-16",
-      label: "Dialect gating",
-      note: "Pass an object keyed by dialect to run different SQL per backend. Make the other key a no-op (`SELECT 1`) for Postgres-only or SQLite-only features.",
-    },
-    {
-      lines: "19",
-      label: "Per-app version table",
-      note: "Each app tracks its own applied versions so migrations are idempotent across restarts and instances.",
-    },
-  ]}
-/>
-
-## Environment Variables {#environment-variables}
-
-| Variable              | Purpose                                                                                                 |
-| --------------------- | ------------------------------------------------------------------------------------------------------- |
-| `DATABASE_URL`        | Persistent SQL connection string (unset = local SQLite; `pglite:./data/pglite` = local Postgres opt-in) |
-| `DATABASE_AUTH_TOKEN` | Auth token for providers that require a separate token, such as Turso/libSQL                            |
-
-## What's next
-
-- [**Security — Data Scoping**](/docs/security#data-scoping) — how `owner_email` and access helpers scope reads and writes
-- [**Sharing**](/docs/sharing#building) — `ownableColumns()` and the visibility model for shared resources
-- [**Server**](/docs/server-routes#request-context) — how actions and custom routes each import `getDb`
-- [**Deployment**](/docs/deployment#persistent-database) — connecting a persistent database per deploy target
-- [**Actions**](/docs/actions-access-control#access-control) — a complete, paste-ready action that reads and writes through `getDb`/`schema`