@agent-native/core 0.22.45 → 0.24.0

package/dist/templates/default/AGENTS.md

@@ -6,12 +6,19 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 
 ### Core Principles
 
-1. **Shared SQL database** -- All app state lives in SQL (SQLite locally, cloud DB via `DATABASE_URL` in production). Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
+1. **Shared SQL database** -- All app state lives in SQL. Local SQLite at `data/app.db` is the zero-setup dev fallback; deployed apps need a persistent `DATABASE_URL` so data survives container/serverless restarts. Turso is optional, not required: Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments are all valid when supported by the deploy. Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
 2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`.
 3. **Actions for agent operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`.
 4. **Live sync keeps the UI current** -- Database writes stream over `/_agent-native/events` first, with `/_agent-native/poll` as the fallback. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` / `useActionMutation` for action-backed data (preferred). If you use raw `useQuery`, fold `useChangeVersions([<source>, "action"])` into the key for targeted refreshes. See the `real-time-sync` and `adding-a-feature` skills.
 5. **Agent can update code** -- The agent can modify this app's source code directly.
 
+### Database Code
+
+- Define tables with `@agent-native/core/db/schema` helpers (`table`, `text`, `integer`, `real`, `now`, sharing helpers), never `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`.
+- Use Drizzle's query builder (`db.select`, `db.insert`, `db.update`, `db.delete`) plus portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads and writes.
+- Keep raw SQL out of normal actions, handlers, and stores. Use it only for additive migrations, health checks, or last-resort maintenance, and keep it parameterized and dialect-agnostic.
+- Do not write SQLite-only or Postgres-only syntax in product code. The same app should run on SQLite, Postgres, libSQL/Turso, D1, and other supported Drizzle backends.
+
 ### Authentication
 
 Auth is automatic and environment-driven:
@@ -77,12 +84,13 @@ You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at t
 | `hello`       | `[--name <name>]`                                                              | Example script                                                                          |
 | `db-schema`   |                                                                                | Show all tables, columns, types                                                         |
 | `db-query`    | `--sql "SELECT ..."`                                                           | Run a SELECT query                                                                      |
-| `db-exec`     | `--sql "INSERT ..."`                                                           | Run INSERT/UPDATE/DELETE (use for short/multi-column writes)                            |
+| `db-exec`     | `--sql "UPDATE ..."`                                                           | Last-resort ad-hoc maintenance; prefer domain actions and Drizzle code for product work |
 | `db-patch`    | `--table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` | Surgical search/replace on a large text column — sends a diff instead of the full value |
 
-**Pick the right SQL tool:**
+**For one-off maintenance, pick the right SQL tool:**
 
-- Use `db-exec UPDATE` for short columns, multi-column writes, or computed updates.
+- Use domain actions first. They validate input, enforce access, and refresh the UI.
+- Use `db-exec UPDATE` only when no domain action exists and you need a small ad-hoc change.
 - Use `db-patch` when you only need to tweak a small slice of a **large** text/JSON column (documents, slide HTML, dashboard/form JSON). It saves tokens by sending `{find, replace}` instead of re-transmitting the whole column. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` for replace-every-occurrence.
 - If a template-specific action exists (e.g. `edit-document`, `update-slide`), prefer it — those also push live updates to any open collaborative editor.
 

package/dist/templates/default/DEVELOPING.md

@@ -110,12 +110,14 @@ agentChat.submit("Generate something");
 
 ## Database
 
-By default, data is stored in SQLite at `data/app.db`. For production/cloud deployment, set `DATABASE_URL` to point to a remote database (Turso, Neon, Supabase, D1).
+Local development defaults to a SQLite file at `data/app.db`. That local file is for development; containers, previews, and serverless deploys can reset their filesystem. For production/cloud deployment, set `DATABASE_URL` to point to a persistent SQL database. Turso is optional, not required; common choices include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments when available.
 
-| Variable              | Required         | Description                                                |
-| --------------------- | ---------------- | ---------------------------------------------------------- |
-| `DATABASE_URL`        | No (has default) | Database connection string (default: `file:./data/app.db`) |
-| `DATABASE_AUTH_TOKEN` | For remote DBs   | Auth token for Turso or other remote databases             |
+When adding app data, define tables with `@agent-native/core/db/schema` helpers and use Drizzle's query builder for reads/writes. Do not import dialect-specific schema helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`, and do not write raw SQL in normal actions or handlers when Drizzle can express the query. Raw SQL belongs in additive migrations, health checks, or carefully scoped maintenance.
+
+| Variable              | Required                        | Description                                                                |
+| --------------------- | ------------------------------- | -------------------------------------------------------------------------- |
+| `DATABASE_URL`        | Production yes, local dev no    | Persistent SQL connection string (local dev default: `file:./data/app.db`) |
+| `DATABASE_AUTH_TOKEN` | Only when the provider needs it | Auth token for providers such as Turso/libSQL                              |
 
 ## Tech Stack
 

package/dist/templates/workspace-core/AGENTS.md

@@ -77,6 +77,13 @@ the same data unless the route is for uploads, streaming, webhooks, OAuth, or
 another route-only concern. Action-backed UI is what makes agent-created or
 agent-edited records appear without a manual refresh.
 
+App database code must be provider-agnostic. Define schemas with
+`@agent-native/core/db/schema` helpers and write app reads/writes with Drizzle's
+query builder and portable `drizzle-orm` operators. Do not import from
+`drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Keep raw SQL
+for additive migrations, health checks, or carefully scoped maintenance, and
+never write SQLite-only or Postgres-only product code.
+
 In local development, run
 `pnpm exec agent-native create <app-name> --template=<template>` from the
 workspace root. In production, Dispatch posts new-app requests to Builder

package/dist/templates/workspace-root/AGENTS.md

@@ -102,6 +102,12 @@ coding agents can discover the same workspace-wide guidance from the root.
   for the same data unless the route is for uploads, streaming, webhooks,
   OAuth, or another route-only concern. Action-backed UI is what makes
   agent-created or agent-edited records appear without a manual refresh.
+- App database code must be provider-agnostic. Define schemas with
+  `@agent-native/core/db/schema` helpers and write app reads/writes with
+  Drizzle's query builder and portable `drizzle-orm` operators. Do not import
+  from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates.
+  Keep raw SQL for additive migrations, health checks, or carefully scoped
+  maintenance, and never write SQLite-only or Postgres-only product code.
 - In local development, scaffold the app from the workspace root with
   `pnpm exec agent-native create <app-id> --template=<template>`. In production
   Dispatch posts the request to Builder branch creation; the Builder branch

package/docs/content/creating-templates.md

@@ -70,7 +70,7 @@ Do not add a `data/` directory for application state. Durable app data belongs i
 
 ## Model Data In SQL {#data-models}
 
-Define domain tables with the framework Drizzle helpers so schemas stay portable across SQLite, Postgres, D1, Turso, Supabase, and Neon:
+Define domain tables with the framework Drizzle helpers so schemas stay portable across SQLite, Postgres, D1, Turso, Supabase, Neon, and other supported backends:
 
 ```ts
 // server/db/schema.ts
@@ -102,14 +102,17 @@ export const projectShares = createSharesTable("project_shares", "project");
 
 Schema changes must be additive. Add tables and columns through `runMigrations()` in `server/plugins/db.ts`; never use destructive SQL, `drizzle-kit push`, table renames, or column drops.
 
+For app reads and writes, use Drizzle's query builder and portable operators from `drizzle-orm`. Do not write product code with raw SQL when Drizzle can express the query, and do not import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in templates.
+
 ```ts
 // server/plugins/db.ts
-import { runMigrations } from "@agent-native/core/db/migrations";
+import { runMigrations } from "@agent-native/core/db";
 
-export default runMigrations([
-  {
-    id: "001_create_projects",
-    sql: `CREATE TABLE IF NOT EXISTS projects (
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
       id TEXT PRIMARY KEY,
       title TEXT NOT NULL,
       status TEXT NOT NULL DEFAULT 'draft',
@@ -120,8 +123,10 @@ export default runMigrations([
       created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
       updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
     )`,
-  },
-]);
+    },
+  ],
+  { table: "my_app_migrations" },
+);
 ```
 
 Use the [Database](/docs/database) and [Security](/docs/security) docs before adding schemas that hold user or org data.
@@ -273,7 +278,7 @@ Projects are the top-level resource. They contain tasks and notes.
 ## Rules
 
 - Use `view-screen` before acting on "this project" if the current screen is unclear.
-- Use actions for project changes; do not write raw SQL unless debugging.
+- Use actions for project changes; do not write raw SQL except for one-off maintenance/debugging when no action exists.
 - For shared projects, check access through framework sharing helpers.
 ```
 

package/docs/content/database.md

@@ -1,19 +1,21 @@
 ---
 title: "Database"
-description: "Connect any SQL database to your agent-native app — SQLite for local dev, Postgres for production."
+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 any SQL database. By default, apps use SQLite with a local file — set `DATABASE_URL` to connect a production database.
+Agent-native apps use [Drizzle ORM](https://orm.drizzle.team) and support portable SQL backends. By default, apps use SQLite with a local file — set `DATABASE_URL` to connect a persistent production database.
 
 ## Default: SQLite {#default-sqlite}
 
 When `DATABASE_URL` is not set, the app creates a SQLite database at `data/app.db`. This is great for local development — no setup required.
 
+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.
+
 ## Connecting a Production Database {#production}
 
-Set `DATABASE_URL` in your `.env` file to connect a hosted database:
+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
@@ -27,18 +29,18 @@ DATABASE_URL=postgres://user:pass@localhost:5432/mydb
 
 # Turso (libSQL)
 DATABASE_URL=libsql://my-db-org.turso.io
-TURSO_AUTH_TOKEN=your-token
+DATABASE_AUTH_TOKEN=your-token
 ```
 
-The framework auto-detects the dialect from the URL and configures Drizzle accordingly.
+The framework auto-detects the dialect from the URL and configures Drizzle accordingly. The built-in adapters cover Postgres 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}
 
 When connected to Builder.io, your app can use a managed database that is provisioned and scaled automatically. This is the simplest path to production — no connection strings or database admin required. Coming soon.
 
-## Dialect-Agnostic Schema {#schema}
+## Dialect-Agnostic Schema And Queries {#schema}
 
-All SQL must work on both SQLite and Postgres. Never use SQLite-only syntax (`INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`) or Postgres-only syntax.
+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`:
 
@@ -66,9 +68,29 @@ export const tasks = table("tasks", {
 
 Never import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` directly. Always use `@agent-native/core/db/schema`.
 
-## Raw SQL Helpers {#raw-sql}
+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));
 
-For cases where you need raw SQL outside of Drizzle queries:
+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
@@ -97,15 +119,20 @@ Instead of pushing directly, schema changes should be applied via SQL migrations
 ```ts
 import { runMigrations } from "@agent-native/core/db";
 
-export default defineNitroPlugin(async () => {
-  // Executes pending SQL migrations safely at startup
-  await runMigrations();
-});
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
 ```
 
 ## Environment Variables {#environment-variables}
 
-| Variable           | Purpose                                           |
-| ------------------ | ------------------------------------------------- |
-| `DATABASE_URL`     | Database connection string (unset = local SQLite) |
-| `TURSO_AUTH_TOKEN` | Auth token for Turso (libSQL) databases           |
+| Variable              | Purpose                                                                                              |
+| --------------------- | ---------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`        | Persistent SQL connection string (unset = local SQLite, which is only durable for local development) |
+| `DATABASE_AUTH_TOKEN` | Auth token for providers that require a separate token, such as Turso/libSQL                         |

package/docs/content/deployment.md

@@ -7,6 +7,14 @@ description: "Deploy agent-native apps to any platform with Nitro presets — No
 
 Agent-native apps use [Nitro](https://nitro.build) under the hood, which means you can deploy to any platform with zero config changes — just set a preset.
 
+## Before You Deploy: Pick a Persistent Database {#persistent-database}
+
+Every deployed app needs a persistent SQL database. In local development, agent-native falls back to a SQLite file at `data/app.db`; that is convenient on your machine, but it is not durable in containers, previews, or serverless environments where the filesystem can be reset.
+
+Set `DATABASE_URL` in your deploy provider before promoting an app to production. Agent-native uses Drizzle for schema and queries, so the data layer is portable across Drizzle-compatible SQL backends. The built-in adapters auto-detect Postgres URLs, libSQL/Turso URLs, SQLite file URLs, and Cloudflare D1 bindings. Common choices include Neon or Supabase Postgres, Turso/libSQL, plain Postgres, durable SQLite, and Builder.io-managed environments when available. Turso is one option, not a requirement.
+
+Use `DATABASE_AUTH_TOKEN` only when your database provider requires a separate token, such as Turso/libSQL. For workspaces, all apps inherit the root `DATABASE_URL` by default; set `<APP_NAME>_DATABASE_URL` when one app should use a different database.
+
 ## Workspace Deploy: One Origin, Many Apps {#workspace-deploy}
 
 If your project is a [workspace](/docs/multi-app-workspace), you can ship every app in it to a single origin with one command:
@@ -200,13 +208,13 @@ export default defineConfig({
 
 ### Build / Runtime {#env-runtime}
 
-| Variable              | Description                                                                                                          |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `PORT`                | Server port (Node.js only)                                                                                           |
-| `NITRO_PRESET`        | Override build preset at build time                                                                                  |
-| `APP_BASE_PATH`       | Mount the app under a prefix (e.g. `/mail`). Set automatically by `agent-native deploy`; leave unset for standalone. |
-| `DATABASE_URL`        | Postgres / Turso / SQLite connection string. Required in production.                                                 |
-| `DATABASE_AUTH_TOKEN` | Auth token for Turso / libsql connections.                                                                           |
+| Variable              | Description                                                                                                                                                                                        |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                | Server port (Node.js only)                                                                                                                                                                         |
+| `NITRO_PRESET`        | Override build preset at build time                                                                                                                                                                |
+| `APP_BASE_PATH`       | Mount the app under a prefix (e.g. `/mail`). Set automatically by `agent-native deploy`; leave unset for standalone.                                                                               |
+| `DATABASE_URL`        | Persistent SQL connection string. Required in production; common options include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, and Builder.io-managed environments when available. |
+| `DATABASE_AUTH_TOKEN` | Auth token for providers that require a separate token, such as Turso/libSQL.                                                                                                                      |
 
 ### Required in Production {#env-required-prod}
 

package/docs/content/dispatch.md

@@ -19,7 +19,7 @@ Reach for Dispatch when any of these are true:
 - You want **one inbox for "the agent"** so users DM a single bot and the right specialist app picks up the work behind the scenes.
 - You have **workspace-wide secrets** (Stripe key, OpenAI key, third-party API tokens) that several apps need and you want one vault instead of copying values into every `.env`.
 - You want a **runtime approval flow** in front of sensitive changes (saved destinations, policy edits) so non-admins can request and admins can sign off without a code deploy.
-- You want **shared skills, instructions, and agent profiles** that every app in the workspace inherits — change once, reach all.
+- You want **shared skills, instructions, agent profiles, and MCP servers** that apps in the workspace inherit — change once, reach all.
 
 If you're running a single template standalone, you don't need Dispatch — each template can wire its own messaging integrations directly. See [Messaging](/docs/messaging) for the standalone setup.
 
@@ -76,6 +76,7 @@ Use the canonical paths to control how agents consume them:
 - `skills/<slug>/SKILL.md` for on-demand skills available through `/` commands and the prompt skill index
 - `context/<slug>.md` for brand, persona, positioning, messaging, company facts, and other reference material the agent reads when relevant
 - `agents/<slug>.md` for reusable custom agent profiles
+- `mcp-servers/<slug>.json` for HTTP MCP servers that should add external tools to granted app agents
 
 Starter global resources usually look like:
 
@@ -89,6 +90,11 @@ skills/company-voice/SKILL.md
 
 Set these to **All apps** when every app should inherit the same company facts, brand rules, messaging, safety constraints, and customer-facing writing style. Use selected-app grants only for resources that are genuinely app-specific.
 
+MCP server resources use JSON and are intentionally HTTP-only. Store tokens in
+Dispatch Vault, grant or sync those keys to the target apps, and reference them
+from headers with `${keys.NAME}` so the raw credential never lives in the
+resource body.
+
 The **Resources** page highlights this starter pack in a Global context section so admins can quickly see which files exist, whether they are scoped to all apps, restore missing starter files without overwriting existing ones, and edit their contents. Expand any resource to preview its effective runtime stack for a selected app/user: workspace default, organization/app override, then personal override. Each app card also has a **Context** view that shows exactly what that app receives: inherited workspace resources, selected grants, and auto-loaded instructions. Use a resource row's **Stack** control to inspect which layer wins for that app.
 
 This is how a team-wide change ("always use British English in customer-facing replies") or a shared brand guideline propagates without editing ten repos.

package/docs/content/embedding-sdk.md

@@ -14,6 +14,85 @@ Use it when you want an assistant that can:
 - Ask the host app to navigate, refresh data, remount a view, or open a resource after durable work completes.
 - Run as an iframe/sidebar now, while leaving room for a no-iframe package or hosted template later.
 
+## Embedded App And Picker Mode
+
+Use `@agent-native/embedding` when the host product wants to launch a complete
+Agent-Native app as a focused iframe surface: an asset picker, asset generator,
+form builder, calendar slot picker, approval panel, or any other task-specific
+workflow. This is intentionally smaller than the sidecar host bridge below: the
+iframe announces readiness, the host can send named messages, and the embedded
+app can emit domain events such as `chooseAsset` or `close`.
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+export function AssetPickerDialog({ close }) {
+  return (
+    <EmbeddedApp
+      url="https://assets.agent-native.com/picker"
+      className="h-full w-full"
+      onLoad={(ref) => {
+        ref.postMessage("configure", {
+          prompt: "Editorial blog hero",
+          aspectRatio: "16:9",
+        });
+      }}
+      onMessage={(name, payload) => {
+        if (name === "chooseAsset") {
+          const asset = payload as { url: string; altText?: string };
+          insertAsset(asset.url, asset.altText);
+          close();
+        }
+        if (name === "close") close();
+      }}
+    />
+  );
+}
+```
+
+Inside the embedded app, use the browser bridge to announce readiness and send
+events back to the host:
+
+```ts
+import {
+  announceEmbeddedAppReady,
+  sendEmbeddedAppMessage,
+} from "@agent-native/embedding/bridge";
+
+announceEmbeddedAppReady({ app: "assets", mode: "picker" });
+sendEmbeddedAppMessage("chooseAsset", {
+  url: asset.previewUrl,
+  assetId: asset.id,
+  altText: asset.altText,
+});
+```
+
+Assets also emits `chooseImage` as a compatibility alias for older image-picker
+hosts; new integrations should listen for `chooseAsset`.
+
+For hosted first-party apps, enable Cross-App SSO with Dispatch as the identity
+hub so `content.agent-native.com` and `assets.agent-native.com` link users by
+verified email. Iframe launches should still use short-lived, route-scoped
+embed sessions when they need third-party-cookie resilience; normal app cookies
+are not a complete embed auth story on their own.
+
+The same package includes agent endpoint helpers for protocol discovery and
+streaming text over A2A:
+
+```ts
+import { getA2AUrl, getMcpUrl, sendMessage } from "@agent-native/embedding";
+
+getMcpUrl("https://assets.agent-native.com");
+getA2AUrl("https://assets.agent-native.com");
+
+for await (const chunk of sendMessage(
+  "https://assets.agent-native.com",
+  "Generate a blog hero",
+)) {
+  append(chunk);
+}
+```
+
 ## Batteries-Included Embedded Mode
 
 For most SaaS hosts, use the full embedded runtime. The host mounts Agent-Native server routes into its existing app, passes its logged-in user to Agent-Native, and then renders the React sidebar/surface in the product UI. Agent-Native uses the host deployment, host session, and the configured `DATABASE_URL` to manage its own framework tables: chat threads, settings, application state, extensions, extension data, secrets, browser sessions, and action routes.

package/docs/content/extensions.md

@@ -130,6 +130,11 @@ If the extension needs an API key — a CRM token, a weather API — the agent t
 
 If you want to change something later, just say so: "Add a search box to my contact notes." The agent edits the HTML in place — no regeneration of the whole thing.
 
+Every change is versioned. Open the extension viewer's History control to see
+saved versions, inspect the diff from the previous version, and restore an
+older name/description/icon/content snapshot without changing ownership or
+sharing.
+
 ## What an extension can do {#capabilities}
 
 Inside the iframe sandbox, every extension has these helpers on `window`:

package/docs/content/key-concepts.md

@@ -96,10 +96,10 @@ export const forms = table("forms", {
 ```
 
 ```bash
-# Core actions for quick database access
+# Core actions for quick database inspection and one-off maintenance
 pnpm action db-schema                                       # show all tables
 pnpm action db-query --sql "SELECT * FROM forms"
-pnpm action db-exec --sql "INSERT INTO forms ..."
+pnpm action db-exec --sql "UPDATE forms SET status = ? WHERE id = ?" --args '["closed","form-1"]'
 # Surgical find/replace on a large text column — sends a diff, not the whole value
 pnpm action db-patch --table documents --column content \
   --where "id='doc-1'" --find "old heading" --replace "new heading"
@@ -227,7 +227,7 @@ There's no shared codebase to break. You own the app, and the agent evolves it f
 
 ## Database agnostic {#database-agnostic}
 
-The framework supports every Drizzle-supported database. Never write SQL that only works on one dialect.
+The framework supports portable Drizzle-backed SQL databases. Write app schemas with `@agent-native/core/db/schema` and app reads/writes with Drizzle's query builder so code can run across providers.
 
 - **SQLite** — local dev fallback when `DATABASE_URL` is unset
 - **Neon Postgres** — common in both dev and production
@@ -236,24 +236,22 @@ The framework supports every Drizzle-supported database. Never write SQL that on
 - **Cloudflare D1**
 - **Plain Postgres**
 
-Use the framework helpers for dialect-agnostic SQL:
+Use Drizzle's portable query DSL for normal app code:
 
 ```ts
-import { getDbExec, isPostgres, intType } from "@agent-native/core/db";
-
-// getDbExec() auto-converts ? params to $1 for Postgres
-const client = getDbExec();
-await client.execute({
-  sql: "SELECT * FROM forms WHERE owner_email = ?",
-  args: [email],
-});
-
-// Branch when syntax differs
-const upsert = isPostgres()
-  ? "INSERT INTO settings (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = $2"
-  : "INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)";
+import { and, desc, eq } from "drizzle-orm";
+
+const forms = await db
+  .select()
+  .from(schema.forms)
+  .where(
+    and(eq(schema.forms.ownerEmail, email), eq(schema.forms.status, "open")),
+  )
+  .orderBy(desc(schema.forms.createdAt));
 ```
 
+Use raw SQL only for additive migrations, health checks, or one-off maintenance, and keep it parameterized and dialect-agnostic.
+
 ## Hosting agnostic {#hosting-agnostic}
 
 The server runs on Nitro, which compiles to any deployment target:

package/docs/content/mcp-clients.md

@@ -159,6 +159,36 @@ If your workspace runs multiple agent-native apps (e.g. dispatch + mail + clips)
 
 Dispatch is the conventional hub — it already coordinates across apps.
 
+For new workspace setups, prefer **Dispatch workspace MCP resources** when you
+want the same All-app vs selected-app grant model used by workspace skills,
+instructions, and reference resources. Add a workspace resource with:
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+Save it under `mcp-servers/<name>.json` with kind `mcp-server`. All-app
+resources are loaded by every workspace app; selected resources load only in
+apps with an active Dispatch grant. Secret placeholders resolve from the app
+secret store, so put raw bearer tokens in Dispatch Vault and reference them
+with `${keys.NAME}` instead of storing them in the resource body.
+
+Apps refresh their merged MCP config about once a minute, so central resource
+edits, grant changes, and removals take effect without a deploy. Set
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` to disable that background refresh, or
+set it to a value of at least `5000` milliseconds to tune the interval.
+
+The older hub mode below remains useful for coarse “share every org-scope MCP
+server from Dispatch” setups and for deployments that already use the MCP
+settings UI as the source of truth.
+
 ### 1. Enable hub-serve on the hub app (dispatch)
 
 Set an env var in dispatch's deployment:

package/docs/content/multi-app-workspace.md

@@ -141,7 +141,7 @@ Use `packages/shared` for code-level defaults that should ship with the repo: pl
 Dispatch resources support two scopes:
 
 - **All apps** — global resources for every app in the workspace. Dispatch stores them once at workspace scope and every app agent inherits them at runtime; no copy or sync step is required.
-- **Selected apps** — resources granted per app for app-specific context. Use these sparingly; most company, brand, persona, positioning, messaging, and guardrail context should be All apps.
+- **Selected apps** — resources granted per app for app-specific context or tools. Use these sparingly; most company, brand, persona, positioning, messaging, and guardrail context should be All apps.
 
 Canonical paths control behavior:
 
@@ -151,8 +151,9 @@ Canonical paths control behavior:
 | Global skills           | `skills/<slug>/SKILL.md`                | Listed as workspace skills and read on demand   |
 | Brand/company resources | `context/<slug>.md`                     | Indexed every turn, read when relevant          |
 | Custom agent profiles   | `agents/<slug>.md`                      | Available as reusable local agent profiles      |
+| Shared HTTP MCP servers | `mcp-servers/<slug>.json`               | Loaded into granted apps' MCP tool registry     |
 
-This is the right home for core personas, positioning, messaging, company facts, brand guidelines, support policies, or other shared knowledge that many apps should benefit from.
+This is the right home for core personas, positioning, messaging, company facts, brand guidelines, support policies, shared skills, or shared HTTP MCP tools that many apps should benefit from.
 
 For a starter workspace, create these Dispatch resources and scope them to **All apps**:
 

package/docs/content/multi-tenancy.md

@@ -54,15 +54,15 @@ For full details on how scoping works at the SQL level, see [Security & Data Sco
 
 ## Adding multi-tenancy to a new table {#new-tables}
 
-When you add a new domain table, include `organization_id` to make it tenant-aware:
+When you add a new domain table, use the framework's dialect-agnostic schema helpers and include ownership columns to make it tenant-aware:
 
 ```typescript
-import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { table, text, ownableColumns } from "@agent-native/core/db/schema";
 
-export const projects = sqliteTable("projects", {
+export const projects = table("projects", {
   id: text("id").primaryKey(),
   title: text("title").notNull(),
-  organizationId: text("organization_id").notNull(),
+  ...ownableColumns(),
   // ... other columns
 });
 ```

package/docs/content/server.md

@@ -94,20 +94,23 @@ Plugins live in `server/plugins/` and run at startup. Use them for migrations, p
 
 ```ts
 // server/plugins/db.ts
-import { runMigrations } from "@agent-native/core/db/migrations";
+import { runMigrations } from "@agent-native/core/db";
 
-export default runMigrations([
-  {
-    id: "001_create_projects",
-    sql: `CREATE TABLE IF NOT EXISTS projects (
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
       id TEXT PRIMARY KEY,
       title TEXT NOT NULL,
       owner_email TEXT NOT NULL,
       org_id TEXT,
       created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
     )`,
-  },
-]);
+    },
+  ],
+  { table: "my_app_migrations" },
+);
 ```
 
 Migrations must be additive. Never put destructive SQL in startup plugins.