@agent-native/core 0.141.4 → 0.141.5

package/docs/content/server-routes.mdx

@@ -0,0 +1,194 @@
+---
+title: "Routes"
+description: "File-based Nitro server routes, the SSR catch-all, naming conventions, and scoping custom routes to the authenticated user."
+---
+
+# Routes
+
+Server routing in an agent-native app is split across two surfaces.
+
+**Framework routes** at `/_agent-native/*` are managed by the framework. They expose the agent chat loop, sync polling, action endpoints, and other core capabilities. You do not create or modify these routes.
+
+**Custom file routes** in `server/routes/` are where you add your own endpoints. Nitro picks them up automatically based on where they sit in the directory tree — no registration or config needed. The filename sets the HTTP method, the directory path becomes the URL path, and each file exports a single handler.
+
+## Framework-Mounted Routes {#framework-routes}
+
+The framework reserves the `/_agent-native/` namespace for its own endpoints. Never put custom routes here. This table is representative, not exhaustive.
+
+| Route prefix                     | Purpose                                                                         |
+| -------------------------------- | ------------------------------------------------------------------------------- |
+| `/_agent-native/actions/:name`   | Action HTTP endpoints                                                           |
+| `/_agent-native/agent-chat`      | Agent chat loop                                                                 |
+| `/_agent-native/poll`            | SQL-backed UI sync                                                              |
+| `/_agent-native/runs`            | Progress primitive. The `RunsTray` polls this; see [Progress](/docs/progress)   |
+| `/_agent-native/resources/*`     | Workspace resources                                                             |
+| `/_agent-native/extensions/*`    | Runtime extensions and extension proxy (legacy alias: `/_agent-native/tools/*`) |
+| `/_agent-native/integrations/*`  | Messaging/webhook integrations                                                  |
+| `/_agent-native/a2a`             | Agent-to-agent JSON-RPC                                                         |
+| `/mcp`                           | MCP endpoint                                                                    |
+| `/_agent-native/onboarding/*`    | Setup checklist                                                                 |
+| `/_agent-native/observability/*` | Traces, feedback, evals, experiments                                            |
+| `/_agent-native/file-upload`     | File upload provider endpoint                                                   |
+
+Custom app routes go in `/api/*` or another path that doesn't collide with `/_agent-native/`.
+
+## When to Use a Custom Route {#when-custom-routes}
+
+Actions cover the vast majority of app operations. Reach for a file route in `server/routes/` only when you need something an action can't express.
+
+<Comparison>
+
+### Use a custom route {#use-custom-route}
+
+- File uploads or multipart form data
+- Streaming responses or server-sent events (SSE)
+- Inbound webhooks that need raw body verification
+- OAuth callbacks
+- Public unauthenticated pages
+- External REST contracts that require a specific URL path or response shape
+
+### Use an action instead {#use-action-instead}
+
+- Operations the UI and agent both need
+- Reading or writing app data
+- HTTP-shaped endpoints (use the `http` option in [Actions](/docs/actions))
+- Anything that should be an agent tool, MCP tool, or CLI command
+- Standard JSON request/response APIs
+
+</Comparison>
+
+### Example: Inbound webhook {#example-webhook}
+
+Webhooks are a clear case for a custom route. External services send a raw HTTP body that must be read as bytes before parsing, so you can verify the request signature. Actions receive pre-parsed JSON and cannot access the raw body, which makes signature verification impossible inside one.
+
+The route below handles an inbound webhook at `POST /api/webhooks/events`. It reads the raw body, verifies an HMAC signature, then processes the payload.
+
+```ts filename="server/routes/api/webhooks/events.post.ts"
+import { createHmac, timingSafeEqual } from "crypto";
+import { createError, defineEventHandler, getHeader, readRawBody } from "h3";
+
+export default defineEventHandler(async (event) => {
+  const secret = process.env.WEBHOOK_SECRET;
+  const signature = getHeader(event, "x-webhook-signature");
+  const rawBody = await readRawBody(event);
+
+  if (!secret || !signature || !rawBody) {
+    throw createError({ statusCode: 400, statusMessage: "Bad Request" });
+  }
+
+  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
+  if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+    throw createError({ statusCode: 401, statusMessage: "Invalid signature" });
+  }
+
+  const payload = JSON.parse(rawBody) as { type: string; data: unknown };
+  // handle payload.type ...
+
+  return { received: true };
+});
+```
+
+Nitro maps this file to `POST /api/webhooks/events` automatically. The `WEBHOOK_SECRET` environment variable should be set to the signing secret provided by the external service.
+
+## File-Based Routes {#file-based-routes}
+
+The directory path becomes the URL path, and the filename suffix sets the HTTP method. A file at `server/routes/api/items/[id].get.ts` maps to `GET /api/items/:id` — `items/` comes from the directory, `[id]` becomes the `:id` param, and `.get` sets the method.
+
+```text
+server/routes/
+  api/
+    items/
+      index.get.ts         -> GET    /api/items
+      index.post.ts        -> POST   /api/items
+      [id].get.ts          -> GET    /api/items/:id
+      [id].patch.ts        -> PATCH  /api/items/:id
+      [id].delete.ts       -> DELETE /api/items/:id
+    webhooks/
+      stripe.post.ts       -> POST   /api/webhooks/stripe
+  [...page].get.ts         -> SSR catch-all for public pages
+```
+
+`defineEventHandler` is the H3 primitive for writing a route. It wraps your handler function and gives it access to the `event` object, which carries the request, response, router params, query string, headers, and body. Returning a value from the handler sends it as the response — a plain object becomes JSON automatically. Throwing a `createError` sends the appropriate HTTP error status.
+
+Router params like `[id]` are read from `event` with `getRouterParam`:
+
+```ts filename="server/routes/api/items/[id].get.ts"
+import { defineEventHandler, getRouterParam, createError } from "h3";
+
+export default defineEventHandler((event) => {
+  const id = getRouterParam(event, "id");
+  if (!id) throw createError({ statusCode: 400, statusMessage: "Missing id" });
+  // fetch and return the item by id
+});
+```
+
+### Naming conventions {#naming-conventions}
+
+| File path (relative to `server/routes/`) | HTTP method | URL path         |
+| ---------------------------------------- | ----------- | ---------------- |
+| `api/items/index.get.ts`                 | GET         | `/api/items`     |
+| `api/items/index.post.ts`                | POST        | `/api/items`     |
+| `api/items/[id].get.ts`                  | GET         | `/api/items/:id` |
+| `api/items/[id].patch.ts`                | PATCH       | `/api/items/:id` |
+| `api/items/[id].delete.ts`               | DELETE      | `/api/items/:id` |
+| `api/items/[...slug].get.ts`             | GET         | `/api/items/*`   |
+
+## Request Context and Access {#request-context}
+
+Actions mounted by the framework automatically run with request context. Custom routes do not. If a custom route reads or writes ownable resources, load the session and wrap the work:
+
+<AnnotatedCode
+  id="doc-block-server-routes-ctx"
+  title="Scoping a custom route to the request user"
+  filename="server/routes/api/projects.get.ts"
+  language="ts"
+  code={
+    'import { defineEventHandler, createError } from "h3";\nimport { getSession, runWithRequestContext } from "@agent-native/core/server";\nimport { getDb } from "../../db/index.js";\nimport { accessFilter } from "@agent-native/core/sharing";\nimport * as schema from "../../db/schema";\n\nexport default defineEventHandler(async (event) => {\n  const session = await getSession(event);\n  if (!session?.email) {\n    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });\n  }\n\n  return runWithRequestContext(\n    { userEmail: session.email, orgId: session.orgId },\n    async () => {\n      const db = getDb();\n      return db\n        .select()\n        .from(schema.projects)\n        .where(accessFilter(schema.projects, schema.projectShares));\n    },\n  );\n});'
+  }
+  annotations={[
+    {
+      lines: "8-11",
+      label: "Custom routes have no auto-context",
+      note: "Unlike actions, a file route must load the session itself and fail closed when there is no authenticated user.",
+    },
+    {
+      lines: "13",
+      label: "Establish request context",
+      note: "`runWithRequestContext` makes the user/org available to scoping helpers for the duration of the work.",
+    },
+    {
+      lines: "17-20",
+      label: "Scope ownable reads",
+      note: "`accessFilter` constrains the query to rows the caller may see. Never run an unscoped `db.select().from(ownableTable)` here.",
+    },
+  ]}
+/>
+
+`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`, so custom routes import it from the template path (`../../db/index.js`), not from `@agent-native/core/db`. See [Database](/docs/server-database#db-client).
+
+<Callout tone="warning">
+  Do not run unscoped `db.select().from(ownableTable)` in custom routes. Always
+  establish request context with `runWithRequestContext` before querying ownable
+  data.
+</Callout>
+
+## SSR Catch-All {#ssr-catch-all}
+
+The `[...page].get.ts` route at the root of `server/routes/` handles server-side rendering for public-facing pages. It uses `createH3SSRHandler` to hand off to the React Router build:
+
+```ts filename="server/routes/[...page].get.ts"
+import { createH3SSRHandler } from "@agent-native/core/server/ssr-handler";
+
+export default createH3SSRHandler(
+  () => import("virtual:react-router/server-build"),
+);
+```
+
+Every SSR response is an impersonal, public shell cached at the CDN. Never read cookies, session state, or auth branches in this handler. Personalization happens client-side after hydration.
+
+## What's next {#whats-next}
+
+- [**Actions**](/docs/actions): the preferred surface for app operations; reach for a route only when it doesn't fit
+- [**Plugins**](/docs/server-plugins): startup plugins that run before routes are served
+- [**Middleware**](/docs/server-middleware): auth guards that protect all routes including `/api/*`
+- [**Security**](/docs/security#access-guards): `accessFilter`/`assertAccess` and the full data-scoping model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.141.4",
+  "version": "0.141.5",
   "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": {

package/docs/content/server.mdx

@@ -1,469 +0,0 @@
----
-title: "Server"
-description: "Nitro server routes, plugins, framework-mounted routes, request context, and SQL-backed sync."
----
-
-# Server
-
-Agent-native apps use [Nitro](https://nitro.build) for server routes and plugins. Most product behavior should live in [Actions](/docs/actions); custom routes are for protocol surfaces that actions do not fit: uploads, streaming, public pages, webhooks, OAuth callbacks, and provider-specific APIs.
-
-<Diagram id="doc-block-1cve8m0" title="What runs on the server" summary="Actions are the default. Custom file routes and framework-mounted routes share the same Nitro app and the same SQL database.">
-
-```html
-<div class="diagram-server">
-  <div class="diagram-col entry">
-    <div class="diagram-node">Browser / UI</div>
-    <div class="diagram-node">Agent loop</div>
-    <div class="diagram-node">
-      External clients<br /><small class="diagram-muted"
-        >HTTP · MCP · A2A</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="diagram-panel" data-rough>
-    <strong>Nitro server</strong>
-    <div class="diagram-row">
-      <span class="diagram-pill accent">Actions</span
-      ><small class="diagram-muted">default surface</small>
-    </div>
-    <div class="diagram-row">
-      <span class="diagram-pill">/_agent-native/*</span
-      ><small class="diagram-muted">framework routes</small>
-    </div>
-    <div class="diagram-row">
-      <span class="diagram-pill">/api/*</span
-      ><small class="diagram-muted">custom file routes</small>
-    </div>
-    <div class="diagram-row">
-      <span class="diagram-pill">plugins</span
-      ><small class="diagram-muted">startup: migrations, jobs</small>
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="diagram-box" data-rough>
-    SQL database<br /><small class="diagram-muted"
-      >Drizzle · the coordination point</small
-    >
-  </div>
-</div>
-```
-
-```css
-.diagram-server {
-  display: flex;
-  align-items: center;
-  gap: 14px;
-  flex-wrap: wrap;
-}
-.diagram-server .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-server .diagram-panel {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px 16px;
-}
-.diagram-server .diagram-row {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-.diagram-server .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-## File-Based Routes {#file-based-routes}
-
-Routes live in `server/routes/` and Nitro maps filenames to methods and paths:
-
-```text
-server/routes/
-  api/
-    health.get.ts              -> GET  /api/health
-    uploads.post.ts            -> POST /api/uploads
-    webhooks/
-      stripe.post.ts           -> POST /api/webhooks/stripe
-  [...page].get.ts             -> SSR catch-all for public pages
-```
-
-Each route exports a `defineEventHandler`:
-
-```ts filename="server/routes/api/health.get.ts"
-import { defineEventHandler } from "h3";
-
-export default defineEventHandler(() => ({
-  ok: true,
-  service: "my-template",
-}));
-```
-
-### Route naming conventions {#route-naming-conventions}
-
-| File name pattern  | HTTP method | Example path                |
-| ------------------ | ----------- | --------------------------- |
-| `index.get.ts`     | GET         | `/api/items`                |
-| `index.post.ts`    | POST        | `/api/items`                |
-| `[id].get.ts`      | GET         | `/api/items/:id`            |
-| `[id].patch.ts`    | PATCH       | `/api/items/:id`            |
-| `[id].delete.ts`   | DELETE      | `/api/items/:id`            |
-| `[...slug].get.ts` | GET         | `/api/items/*` or catch-all |
-
-## Prefer Actions For App Operations {#actions-first}
-
-If the UI and agent both need to do something, define an action instead of a custom API route. Actions automatically become:
-
-- Agent tools.
-- Typed frontend hooks.
-- HTTP endpoints under `/_agent-native/actions/:name`.
-- MCP and A2A-callable tools.
-- CLI commands for development.
-
-Use custom `/api/*` routes only when you need a route-shaped protocol or binary/streaming behavior. See [Actions](/docs/actions).
-
-### API-Only Apps {#api-only-apps}
-
-You do not need an Express server just because the app is API-only. An agent-native app already ships with a Nitro/H3 server, and `defineAction()` is the default API surface. Define operations in `actions/`; the framework mounts each action at `/_agent-native/actions/<name>` with schema validation and request context.
-
-Use the action `http` option to shape direct HTTP access: actions are `POST` by default, `http: { method: "GET" | "PUT" | "DELETE" }` changes the verb, and `http: false` keeps an action off HTTP. Reach for `server/routes/api/*` only for route-shaped or protocol concerns: file uploads, streaming/SSE, webhooks, OAuth callbacks, public pages, or an external REST shape that cannot be represented cleanly as an action. Do not create `/api/*` routes that mostly wrap or re-export actions.
-
-For a read-only status endpoint, keep it as an action:
-
-```ts filename="actions/get-status.ts"
-import { defineAction } from "@agent-native/core/action";
-import { z } from "zod";
-
-export default defineAction({
-  description: "Return API service status",
-  schema: z.object({
-    service: z.string().optional(),
-  }),
-  http: { method: "GET" },
-  run: async ({ service }) => ({
-    ok: true,
-    service: service ?? "api",
-    checkedAt: new Date().toISOString(),
-  }),
-});
-```
-
-Call it directly over HTTP:
-
-```http
-GET /_agent-native/actions/get-status?service=billing
-```
-
-For `POST` and other write actions, send a JSON body to the same action path.
-
-## One-Shot Text Completion {#complete-text}
-
-Most AI work should go through the agent chat so users can see, steer, and audit
-what happened. For narrow server-side transforms that intentionally do not need
-tools, chat history, or run state, use `completeText()` as an explicit escape
-hatch.
-
-```ts filename="actions/classify-message.ts"
-import { defineAction } from "@agent-native/core/action";
-import { completeText } from "@agent-native/core/server";
-import { z } from "zod";
-
-export default defineAction({
-  description: "Classify a short message",
-  schema: z.object({ body: z.string() }),
-  run: async ({ body }) => {
-    const result = await completeText({
-      systemPrompt:
-        "Return exactly one label: urgent, follow-up, waiting, or archive.",
-      input: body,
-      maxOutputTokens: 16,
-      temperature: 0,
-    });
-
-    return { label: result.text.trim() };
-  },
-});
-```
-
-`completeText()` runs through the same configured engine layer as the agent
-chat, including Builder, Anthropic, AI SDK providers, user/app model defaults,
-request-scoped secrets, and engine-normalized errors. It is server-only; do not
-call model providers from client code. If the operation is user-facing, wrap it
-in an action so the UI and agent share the same capability.
-
-## Request Context And Access {#request-context}
-
-Actions mounted by the framework automatically run with request context. Custom routes do not. If a custom route reads or writes ownable resources, load the session and wrap the work:
-
-<AnnotatedCode
-  id="doc-block-z4ll"
-  title="Scoping a custom route to the request user"
-  filename="server/routes/api/projects.get.ts"
-  language="ts"
-  code={
-    'import { defineEventHandler, createError } from "h3";\nimport { getSession, runWithRequestContext } from "@agent-native/core/server";\nimport { getDb } from "../../db/index.js";\nimport { accessFilter } from "@agent-native/core/sharing";\nimport * as schema from "../../db/schema";\n\nexport default defineEventHandler(async (event) => {\n  const session = await getSession(event);\n  if (!session?.email) {\n    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });\n  }\n\n  return runWithRequestContext(\n    { userEmail: session.email, orgId: session.orgId },\n    async () => {\n      const db = getDb();\n      return db\n        .select()\n        .from(schema.projects)\n        .where(accessFilter(schema.projects, schema.projectShares));\n    },\n  );\n});'
-  }
-  annotations={[
-    {
-      lines: "7-10",
-      label: "Custom routes have no auto-context",
-      note: "Unlike actions, a file route must load the session itself and fail closed when there is no authenticated user.",
-    },
-    {
-      lines: "12-13",
-      label: "Establish request context",
-      note: "`runWithRequestContext` makes the user/org available to scoping helpers for the duration of the work.",
-    },
-    {
-      lines: "18-19",
-      label: "Scope ownable reads",
-      note: "`accessFilter` constrains the query to rows the caller may see. Never run an unscoped `db.select().from(ownableTable)` here.",
-    },
-  ]}
-/>
-
-`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`, so custom routes import it from the template (`../../db/index.js`), not from `@agent-native/core/db`; see [Database — Where the DB Client Lives](/docs/database#db-client). Do not run unscoped `db.select().from(ownableTable)` in custom routes.
-
-## Server Plugins {#server-plugins}
-
-Plugins live in `server/plugins/` and run at startup. Use them for migrations, provider setup, recurring jobs, integration adapters, and framework plugin configuration.
-
-```ts filename="server/plugins/db.ts"
-import { runMigrations } from "@agent-native/core/db";
-
-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.
-
-## Framework-Mounted Routes {#framework-routes}
-
-The framework mounts its own routes under `/_agent-native/`. Treat that namespace as reserved. This table is representative, not exhaustive — it lists the routes most templates touch directly.
-
-| Route prefix                     | Purpose                                                                         |
-| -------------------------------- | ------------------------------------------------------------------------------- |
-| `/_agent-native/actions/:name`   | Action HTTP endpoints                                                           |
-| `/_agent-native/agent-chat`      | Agent chat loop                                                                 |
-| `/_agent-native/poll`            | SQL-backed UI sync                                                              |
-| `/_agent-native/runs`            | Progress primitive — the `RunsTray` polls this; see [Progress](/docs/progress)  |
-| `/_agent-native/resources/*`     | Workspace resources                                                             |
-| `/_agent-native/extensions/*`    | Runtime extensions and extension proxy (legacy alias: `/_agent-native/tools/*`) |
-| `/_agent-native/integrations/*`  | Messaging/webhook integrations                                                  |
-| `/_agent-native/a2a`             | Agent-to-agent JSON-RPC                                                         |
-| `/mcp`                           | MCP endpoint                                                                    |
-| `/_agent-native/onboarding/*`    | Setup checklist                                                                 |
-| `/_agent-native/observability/*` | Traces, feedback, evals, experiments                                            |
-| `/_agent-native/file-upload`     | File upload provider endpoint                                                   |
-
-Custom app routes should use `/api/*`, public app paths, or provider-specific callback paths that do not collide with `/_agent-native/`.
-
-## SQL-Backed Sync {#sync}
-
-Agent-native does not rely on filesystem watchers or sticky in-memory state. When actions or framework helpers mutate data, the database sync version increments. The client `useDbSync()` hook polls `/_agent-native/poll` and invalidates React Query caches.
-
-This works across serverless and multi-instance deployments because the database is the coordination point. If you write custom mutations outside actions, use framework helpers or emit the appropriate sync invalidation so open UIs refresh.
-
-<Diagram id="doc-block-qhkdv8" title="SQL-backed sync loop" summary={"No watchers, no sticky state. A write bumps a version in SQL; every client polls the version and refetches."}>
-
-```html
-<div class="diagram-sync">
-  <div class="diagram-box" data-rough>
-    Action / helper<br /><small class="diagram-muted">mutates data</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="diagram-panel" data-rough>
-    <strong>SQL database</strong
-    ><small class="diagram-muted">sync version increments</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&larr;</div>
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useDbSync()<br /><small class="diagram-muted"
-        >polls /_agent-native/poll</small
-      >
-    </div>
-    <div class="diagram-pill ok">invalidate caches &rarr; UI refreshes</div>
-  </div>
-</div>
-```
-
-```css
-.diagram-sync {
-  display: flex;
-  align-items: center;
-  gap: 14px;
-  flex-wrap: wrap;
-}
-.diagram-sync .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  align-items: flex-start;
-}
-.diagram-sync .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-<Endpoint id="doc-block-1s11d2e" title="The poll endpoint" method="GET" path="/_agent-native/poll" summary="Return the current per-source database sync versions so the client can detect changes." auth="Session cookie (request-scoped identity)" responses={[
-  {
-    "status": "200",
-    "description": "Current sync versions keyed by source."
-  }
-]}>
-
-`useDbSync()` calls this on an interval (and falls back to it when SSE is unavailable). When a returned version is higher than the client's last-seen value, the matching React Query caches are invalidated and refetch.
-
-</Endpoint>
-
-## Webhooks {#webhooks}
-
-Inbound webhooks should verify, persist, and return quickly. Long-running agent work should use the integration queue pattern:
-
-1. Verify the platform signature or challenge.
-2. Insert durable work into SQL.
-3. Self-fire a signed processor route.
-4. Return 200 immediately.
-5. Let the fresh processor execution run the agent loop and post the result.
-
-<Diagram id="doc-block-1v3q81q" title="Integration queue pattern" summary={"The webhook handler returns in milliseconds; a separate signed execution runs the slow agent work."}>
-
-```html
-<div class="diagram-webhook">
-  <div class="diagram-box" data-rough>
-    Inbound webhook<br /><small class="diagram-muted"
-      >Slack · Stripe · email</small
-    >
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="diagram-panel" data-rough>
-    <strong>Handler</strong>
-    <div class="diagram-step">
-      <span class="diagram-pill">1</span
-      ><small class="diagram-muted">verify signature</small>
-    </div>
-    <div class="diagram-step">
-      <span class="diagram-pill">2</span
-      ><small class="diagram-muted">insert work into SQL</small>
-    </div>
-    <div class="diagram-step">
-      <span class="diagram-pill">3</span
-      ><small class="diagram-muted">self-fire processor</small>
-    </div>
-    <div class="diagram-step">
-      <span class="diagram-pill ok">4</span
-      ><small class="diagram-muted">return 200 now</small>
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="diagram-box" data-rough>
-    Signed processor<br /><small class="diagram-muted"
-      >runs agent loop, posts result</small
-    >
-  </div>
-</div>
-```
-
-```css
-.diagram-webhook {
-  display: flex;
-  align-items: center;
-  gap: 14px;
-  flex-wrap: wrap;
-}
-.diagram-webhook .diagram-panel {
-  display: flex;
-  flex-direction: column;
-  gap: 6px;
-  padding: 14px 16px;
-}
-.diagram-webhook .diagram-step {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-.diagram-webhook .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-<Callout tone="warning">
-  Do not rely on unawaited promises after returning a response — serverless
-  hosts freeze the execution. See [Messaging](/docs/messaging) for the canonical
-  integration queue.
-</Callout>
-
-## Advanced: Escape Hatches {#advanced-escape-hatches}
-
-Most templates never need these. Nitro file routes and the framework's agent
-chat plugin already wire up the app server and the production agent handler.
-Reach for them only when building a custom server integration outside the
-standard template plugin stack.
-
-### Programmatic H3 servers {#create-server}
-
-For custom packages or tests that need an H3 app directly, `createServer()`
-returns a preconfigured app and router:
-
-```ts
-import { createServer } from "@agent-native/core/server";
-import { defineEventHandler } from "h3";
-
-const { app, router } = createServer();
-
-router.get(
-  "/api/health",
-  defineEventHandler(() => ({ ok: true })),
-);
-```
-
-### Production agent handler {#agent-handler}
-
-The framework's agent chat plugin already mounts the production agent handler
-for templates. Only call `createProductionAgentHandler()` directly when building
-a custom server integration outside the standard template plugin stack —
-otherwise customize the agent through `AGENTS.md`, skills, actions, and the
-agent chat plugin.
-
-```ts
-import { createProductionAgentHandler } from "@agent-native/core/server";
-
-const handler = createProductionAgentHandler({
-  scripts,
-  systemPrompt: "You are the app agent...",
-});
-```
-
-## What's next
-
-- [**Actions**](/docs/actions) — the default operation surface; reach for a custom route only when it doesn't fit
-- [**Database**](/docs/database) — the `getDb()`/`schema` pattern custom routes and actions both import
-- [**Security**](/docs/security#access-guards) — `accessFilter`/`assertAccess` and the full data-scoping model
-- [**Messaging**](/docs/messaging) — the canonical inbound-webhook integration queue pattern
-- [**MCP Protocol**](/docs/mcp-protocol) — the `/mcp` endpoint this server mounts automatically