@agent-native/core 0.141.4 → 0.141.6

package/docs/content/server-overview.mdx

@@ -0,0 +1,234 @@
+---
+title: "Server"
+description: "The Nitro server layer in an agent-native app: what it's for, when to reach for custom routes, and how its pieces connect."
+---
+
+# Server
+
+The `server/` directory is the infrastructure layer of an agent-native app. It handles startup tasks, authentication, and the HTTP surfaces that actions don't cover. Most product behavior belongs in [Actions](/docs/actions). The server is what makes those actions available.
+
+<Diagram id="doc-block-server-overview-1" title="How requests flow through the server" summary="Callers reach the Nitro server, which handles most requests through Actions. Middleware and Routes cover cases Actions can't. Both paths can query the database.">
+
+```html
+<div class="diagram-srv">
+  <div class="diagram-col">
+    <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="srv-path">
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">primary path</small>
+    </div>
+    <div class="srv-or diagram-muted">or</div>
+    <div class="srv-path">
+      <span class="diagram-pill">Middleware</span
+      ><span class="srv-inner-arrow diagram-muted" aria-hidden="true"
+        >&rarr;</span
+      ><span class="diagram-pill">Routes</span>
+    </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</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-srv {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-srv .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-srv .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 14px 16px;
+}
+.diagram-srv .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.srv-path {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.srv-or {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  padding-left: 2px;
+}
+.srv-inner-arrow {
+  font-size: 14px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Where the Server Fits {#role}
+
+In a traditional web app, the server is where most logic lives. Business rules, data access, and presentation all happen inside route handlers. Agent-native apps work differently. Logic lives in actions, which the agent and UI share as equal partners. The server's job is coordination: run database migrations, configure authentication, mount the agent loop, and handle the narrow set of HTTP concerns that actions can't express on their own.
+
+<Diagram id="doc-block-server-overview-2" title="Traditional server vs. Agent Native">
+
+```html
+<div class="diagram-cmp">
+  <div class="cmp-col">
+    <div class="cmp-label diagram-muted">Traditional</div>
+    <div class="diagram-node">Browser</div>
+    <div class="cmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Server</strong>
+      <small class="diagram-muted">logic lives here</small>
+      <div class="cmp-pills">
+        <span class="cmp-tag">Route handlers</span>
+        <span class="cmp-tag">Business logic</span>
+        <span class="cmp-tag">Data access</span>
+      </div>
+    </div>
+    <div class="cmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Database</div>
+  </div>
+  <div class="cmp-vs diagram-muted">vs</div>
+  <div class="cmp-col">
+    <div class="cmp-label diagram-muted">Agent Native</div>
+    <div class="cmp-callers">
+      <div class="diagram-node">Browser / UI</div>
+      <div class="diagram-node">Agent</div>
+    </div>
+    <div class="cmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Server</strong>
+      <small class="diagram-muted">coordination only</small>
+      <div class="cmp-pills">
+        <span class="cmp-tag">Actions</span>
+        <span class="cmp-tag">Auth</span>
+        <span class="cmp-tag">Migrations</span>
+      </div>
+    </div>
+    <div class="cmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Database</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 160px;
+}
+.cmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: flex-start;
+}
+.cmp-pills {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+.cmp-tag {
+  font-size: 12px;
+  opacity: 0.7;
+  margin-right: 10px;
+}
+.cmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+Browser requests, the agent loop, and external API clients all route through the same Nitro server and read from the same SQL database. There is no separate agent backend or UI backend. The server layer is what exposes actions to the outside world.
+
+## What's in the server/ directory {#server-directory}
+
+These are the directories and files inside `server/` that every agent-native app ships. Each corresponds to a specific piece of the server layer: what it does, when to reach for it, and how it connects to the rest of the framework.
+
+| Page                                      | What it covers                                                                      |
+| ----------------------------------------- | ----------------------------------------------------------------------------------- |
+| **[Database](/docs/server-database)**     | Schema definition with `table()` helpers, `getDb`, and ownable table patterns       |
+| **[Middleware](/docs/server-middleware)** | Auth guards in `server/middleware/` and why they run there instead of in a plugin   |
+| **[Plugins](/docs/server-plugins)**       | The three startup plugins every app ships: db migrations, auth, and agent-chat      |
+| **[Routes](/docs/server-routes)**         | File-based routes, the SSR catch-all, and scoping custom routes to the request user |
+
+## Nitro {#nitro}
+
+[Nitro](https://nitro.build) is the server toolkit that powers the agent-native HTTP layer. Most of what you'll configure in `server/` is Nitro: file-based routes, startup plugins, and middleware.
+
+- **File-based routing**: the filename maps directly to an HTTP method and URL path, with no registration needed. `server/routes/api/health.get.ts` becomes `GET /api/health` automatically. Visit [Routes](/docs/server-routes) for more details.
+- **Plugins**: code that runs once at server startup, before any request is served. Database migrations, auth configuration, and the agent-chat mount all happen in `server/plugins/`. Visit [Plugins](/docs/server-plugins) for more details.
+- **Middleware**: code that runs on every incoming request before it reaches a route. The auth guard lives in `server/middleware/`. Visit [Middleware](/docs/server-middleware) for more details.
+
+Nitro is also deployment-agnostic. The same app deploys to Node.js, Cloudflare Workers, Netlify, Vercel, and other runtimes with no code changes. Just set a preset. See [Deployment](/docs/deployment).
+
+The underlying request/response API is [H3](https://h3.unjs.io). When you see `defineEventHandler`, `createError`, or `getQuery` in custom routes, that's H3. The [Nitro docs](https://nitro.build/guide) and [H3 docs](https://h3.unjs.io) are the reference for anything the framework doesn't cover directly.
+
+## Default to Actions first {#actions-first}
+
+Agent Native architecture is different. Whenever you think of a new feature for your application, consider first whether it can be an action. For example, 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. For more details, visit [Actions](/docs/actions).
+
+## What's next {#whats-next}
+
+- [**Actions**](/docs/actions): the default operation surface. Reach for a custom route only when it doesn't fit.
+- [**Database**](/docs/server-database): the `getDb()`/schema pattern custom routes and actions both import
+- [**Middleware**](/docs/server-middleware): auth guards and the `server/middleware/` directory
+- [**Plugins**](/docs/server-plugins): startup plugins for migrations, auth, and the agent
+- [**Routes**](/docs/server-routes): file-based routes, request context, and the SSR catch-all

package/docs/content/server-plugins.mdx

@@ -0,0 +1,147 @@
+---
+title: "Plugins"
+description: "Startup plugins in server/plugins/ — what they are, the two plugins every app ships, the optional database plugin, and how to write your own."
+---
+
+# Plugins
+
+Plugins are startup hooks. Each file in `server/plugins/` exports a function that Nitro calls once when the server initializes, before any route is served. They are the right place for one-time setup: configuring auth, mounting the agent loop, running database migrations, or registering any other initialization code that needs to complete before requests arrive.
+
+Nitro discovers plugins automatically from the filesystem. No registration or imports are required. Files run in alphabetical order, so execution order is controlled by filename prefix.
+
+Every agent-native app ships two plugins by default:
+
+```text
+server/plugins/
+  auth.ts        -> configure auth provider and public paths
+  agent-chat.ts  -> mount the agent loop with your actions and system prompt
+```
+
+Apps that need custom database tables add a third:
+
+```text
+server/plugins/
+  db.ts          -> run migrations on startup
+```
+
+## Auth Plugin {#auth-plugin}
+
+`server/plugins/auth.ts` configures how users sign in. `createAuthPlugin` from `@agent-native/core/server` wires up the auth provider and sets the sign-in page branding:
+
+```ts filename="server/plugins/auth.ts"
+import { createAuthPlugin } from "@agent-native/core/server";
+
+export default createAuthPlugin({
+  marketing: {
+    appName: "My App",
+    tagline: "A short description shown on the sign-in page.",
+    features: ["Feature one", "Feature two", "Feature three"],
+  },
+});
+```
+
+To open specific routes to unauthenticated users, pass `publicPaths`:
+
+```ts
+export default createAuthPlugin({
+  publicPaths: ["/public", "/api/webhook"],
+  marketing: { appName: "My App", tagline: "..." },
+});
+```
+
+The auth plugin configures the guard. The middleware in `server/middleware/auth.ts` enforces it on every request. See [Middleware](/docs/server-middleware).
+
+## Agent-Chat Plugin {#agent-chat-plugin}
+
+`server/plugins/agent-chat.ts` mounts the agent loop with your app's actions, system prompt, and initial tool set. This is the plugin that makes your app an agent-native app.
+
+```ts filename="server/plugins/agent-chat.ts"
+import { getOrgContext } from "@agent-native/core/org";
+import {
+  createAgentChatPlugin,
+  loadActionsFromStaticRegistry,
+} from "@agent-native/core/server";
+
+import actionsRegistry from "../../.generated/actions-registry.js";
+
+export default createAgentChatPlugin({
+  appId: "my-app",
+  actions: loadActionsFromStaticRegistry(actionsRegistry),
+  initialToolNames: ["view-screen", "navigate"],
+  resolveOrgId: async (event) => (await getOrgContext(event)).orgId,
+  systemPrompt: `You are the My App agent.
+
+Use actions as the source of truth. Start by inspecting the current
+screen when context matters.`,
+});
+```
+
+`loadActionsFromStaticRegistry` picks up every action exported from `actions/` through the generated registry. `initialToolNames` controls which actions the agent has access to at the start of a conversation. It can still call others as needed.
+
+## Database Plugin {#database-plugin}
+
+If your app defines custom database tables, add `server/plugins/db.ts` to run schema migrations at startup. It uses `runMigrations` from `@agent-native/core/db`:
+
+```ts filename="server/plugins/db.ts"
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      name: "projects-table",
+      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" },
+);
+```
+
+Each entry needs a `version` number and a `sql` string. Give it a stable `name` too — `runMigrations` tracks named entries independently of `version`, so it still applies exactly once even if another branch reuses the same version number for unrelated DDL. The `table` option names the migration tracking table. Use a name unique to your app so it does not collide with framework migrations. See [Database](/docs/server-database#migrations) for the full schema authoring guide and the name-based tracking rationale.
+
+<Callout tone="warning">
+  Migrations must be additive. Never put destructive SQL (`DROP TABLE`, `ALTER
+  TABLE ... DROP COLUMN`, `DELETE FROM`) in startup plugins.
+</Callout>
+
+## Writing Custom Plugins {#custom-plugins}
+
+The framework helpers (`createAuthPlugin`, `createAgentChatPlugin`, `runMigrations`) each return a Nitro plugin function. For anything outside those helpers, write a plugin using `defineNitroPlugin`:
+
+```ts filename="server/plugins/my-plugin.ts"
+import { defineNitroPlugin } from "nitropack/runtime";
+
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook("request", (event) => {
+    // runs on every request
+  });
+
+  nitro.hooks.hookOnce("close", async () => {
+    // runs when the server shuts down
+  });
+});
+```
+
+Plugins can use any of Nitro's lifecycle hooks: `request`, `beforeResponse`, `close`, and others. The [Nitro plugin docs](https://nitro.build/guide/plugins) cover the full hook API and the plugin contract in detail.
+
+## Startup Order {#startup-order}
+
+Nitro discovers plugins in lexical filename order, so with the default names it invokes `agent-chat.ts`, then `auth.ts`, then `db.ts` — not the dependency order you might expect.
+
+File order controls only when each plugin _starts_, not when it _finishes_. Nitro does not await one plugin's async default export before invoking the next, so a later plugin's synchronous setup — and the first incoming request — can run while an earlier plugin's async work (like migrations) is still in flight. `createAuthPlugin` and `createAgentChatPlugin` coordinate internally so framework routes wait for both to finish initializing before serving requests. `runMigrations` has no equivalent coordination: nothing blocks an action or route from querying the database before `db.ts` finishes running its migrations.
+
+If you add custom plugins, prefix their filenames to control invocation order, but don't rely on filename order alone to sequence async work across plugins.
+
+## What's next {#whats-next}
+
+- [**Database**](/docs/server-database): schema helpers and the `getDb` pattern used inside plugins
+- [**Middleware**](/docs/server-middleware): the auth guard that enforces what the auth plugin configures
+- [**Routes**](/docs/server-routes): custom file routes served after plugins complete
+- [**Writing Agent Instructions**](/docs/writing-agent-instructions): how to craft the `systemPrompt` in the agent-chat plugin
+- [**Nitro plugin docs**](https://nitro.build/guide/plugins): the full plugin API and lifecycle hooks

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.6",
   "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/corpus/templates/analytics/changelog/2026-08-05-historical-analytics-rollups-stay-complete-and-atomic.md

@@ -1,6 +0,0 @@
----
-type: fixed
-date: 2026-08-05
----
-
-Historical analytics events now populate rollups, and new events update raw data and rollups atomically.

package/corpus/templates/analytics/changelog/2026-08-05-historical-rollups-stay-complete-while-live-events-arrive.md

@@ -1,6 +0,0 @@
----
-type: fixed
-date: 2026-08-05
----
-
-Historical analytics rollups stay complete while live events arrive.